Add LangChain utility for real-time crypto exchange prices (#4501)

This commit adds the LangChain utility which allows for the real-time
retrieval of cryptocurrency exchange prices. With LangChain, users can
easily access up-to-date pricing information by running the command
".run(from_currency, to_currency)". This new feature provides a
convenient way to stay informed on the latest exchange rates and make
informed decisions when trading crypto.


---------

Co-authored-by: Bagatur <baskaryan@gmail.com>

docs/extras/integrations/tools/alpha_vantage.ipynb

@@ -0,0 +1,134 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "245a954a",
+   "metadata": {
+    "id": "245a954a"
+   },
+   "source": [
+    "# Alpha Vantage\n",
+    "\n",
+    ">[Alpha Vantage](https://www.alphavantage.co) Alpha Vantage provides realtime and historical financial market data through a set of powerful and developer-friendly data APIs and spreadsheets. \n",
+    "\n",
+    "Use the ``AlphaVantageAPIWrapper`` to get currency exchange rates."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "34bb5968",
+   "metadata": {
+    "id": "34bb5968"
+   },
+   "outputs": [
+    {
+     "name": "stdin",
+     "output_type": "stream",
+     "text": [
+      " ········\n"
+     ]
+    }
+   ],
+   "source": [
+    "import getpass\n",
+    "import os\n",
+    "\n",
+    "os.environ[\"ALPHAVANTAGE_API_KEY\"] = getpass.getpass()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "ac4910f8",
+   "metadata": {
+    "id": "ac4910f8"
+   },
+   "outputs": [],
+   "source": [
+    "from langchain.utilities.alpha_vantage import AlphaVantageAPIWrapper"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "84b8f773",
+   "metadata": {
+    "id": "84b8f773"
+   },
+   "outputs": [],
+   "source": [
+    "alpha_vantage = AlphaVantageAPIWrapper()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "068991a6",
+   "metadata": {
+    "id": "068991a6",
+    "outputId": "c5cdc6ec-03cf-4084-cc6f-6ae792d91d39"
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'1. From_Currency Code': 'USD',\n",
+       " '2. From_Currency Name': 'United States Dollar',\n",
+       " '3. To_Currency Code': 'JPY',\n",
+       " '4. To_Currency Name': 'Japanese Yen',\n",
+       " '5. Exchange Rate': '144.93000000',\n",
+       " '6. Last Refreshed': '2023-08-11 21:31:01',\n",
+       " '7. Time Zone': 'UTC',\n",
+       " '8. Bid Price': '144.92600000',\n",
+       " '9. Ask Price': '144.93400000'}"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "alpha_vantage.run(\"USD\", \"JPY\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "84fc2b66-c08f-4cd3-ae13-494c54789c09",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.1"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "53f3bc57609c7a84333bb558594977aa5b4026b1d6070b93987956689e367341"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

libs/langchain/langchain/utilities/__init__.py

@@ -3,6 +3,7 @@
 Other LangChain classes use **Utilities** to interact with third-part systems
 and packages.
 """
+from langchain.utilities.alpha_vantage import AlphaVantageAPIWrapper
 from langchain.utilities.arxiv import ArxivAPIWrapper
 from langchain.utilities.awslambda import LambdaWrapper
 from langchain.utilities.bash import BashProcess
@@ -36,6 +37,7 @@ from langchain.utilities.wolfram_alpha import WolframAlphaAPIWrapper
 from langchain.utilities.zapier import ZapierNLAWrapper
 
 __all__ = [
+    "AlphaVantageAPIWrapper",
     "ArxivAPIWrapper",
     "BashProcess",
     "BibtexparserWrapper",

libs/langchain/langchain/utilities/alpha_vantage.py

@@ -0,0 +1,66 @@
+"""Util that calls AlphaVantage for Currency Exchange Rate."""
+from typing import Any, Dict, List, Optional
+
+import requests
+from pydantic import Extra, root_validator
+
+from langchain.tools.base import BaseModel
+from langchain.utils import get_from_dict_or_env
+
+
+class AlphaVantageAPIWrapper(BaseModel):
+    """Wrapper for AlphaVantage API for Currency Exchange Rate.
+
+    Docs for using:
+
+    1. Go to AlphaVantage and sign up for an API key
+    2. Save your API KEY into ALPHAVANTAGE_API_KEY env variable
+    """
+
+    alphavantage_api_key: Optional[str] = None
+
+    class Config:
+        """Configuration for this pydantic object."""
+
+        extra = Extra.forbid
+
+    @root_validator(pre=True)
+    def validate_environment(cls, values: Dict) -> Dict:
+        """Validate that api key exists in environment."""
+        values["alphavantage_api_key"] = get_from_dict_or_env(
+            values, "alphavantage_api_key", "ALPHAVANTAGE_API_KEY"
+        )
+        return values
+
+    def _get_exchange_rate(
+        self, from_currency: str, to_currency: str
+    ) -> Dict[str, Any]:
+        """Make a request to the AlphaVantage API to get the exchange rate."""
+        response = requests.get(
+            "https://www.alphavantage.co/query/",
+            params={
+                "function": "CURRENCY_EXCHANGE_RATE",
+                "from_currency": from_currency,
+                "to_currency": to_currency,
+                "apikey": self.alphavantage_api_key,
+            },
+        )
+        response.raise_for_status()
+        data = response.json()
+
+        if "Error Message" in data:
+            raise ValueError(f"API Error: {data['Error Message']}")
+
+        return data
+
+    @property
+    def standard_currencies(self) -> List[str]:
+        return ["USD", "EUR", "GBP", "JPY", "CHF", "CAD", "AUD", "NZD"]
+
+    def run(self, from_currency: str, to_currency: str) -> str:
+        """Get the current exchange rate for a specified currency pair."""
+        if to_currency not in self.standard_currencies:
+            from_currency, to_currency = to_currency, from_currency
+
+        data = self._get_exchange_rate(from_currency, to_currency)
+        return data["Realtime Currency Exchange Rate"]