kensho-kfinance 2.2.5__tar.gz → 2.4.0__tar.gz

{kensho_kfinance-2.2.5 → kensho_kfinance-2.4.0}/.gitignore

@@ -104,4 +104,5 @@ kfinance/version.py
 kfinance/wrappers/
 
 docs/output/
-docs/generated/
+docs/generated/
+wrappers/

{kensho_kfinance-2.2.5 → kensho_kfinance-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.2.5
+Version: 2.4.0
 Summary: Python CLI for kFinance
 Author-email: Luke Brown <luke.brown@kensho.com>, Michelle Keoy <michelle.keoy@kensho.com>, Keith Page <keith.page@kensho.com>, Matthew Rosen <matthew.rosen@kensho.com>, Nick Roshdieh <nick.roshdieh@kensho.com>
 Project-URL: source, https://github.com/kensho-technologies/kfinance
@@ -13,8 +13,10 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: AUTHORS.md
 Requires-Dist: cachetools<6,>=5.5
+Requires-Dist: click<=9,>=8.2.1
+Requires-Dist: fastmcp<3,>=2
 Requires-Dist: langchain-core>=0.3.15
-Requires-Dist: langchain-google-genai<3,>=2.1.0
+Requires-Dist: langchain-google-genai<3,>=2.1.5
 Requires-Dist: numpy>=1.22.4
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: pillow>=10
@@ -29,7 +31,8 @@ Requires-Dist: urllib3>=1.21.1
 Provides-Extra: dev
 Requires-Dist: coverage<8,>=7.6.10; extra == "dev"
 Requires-Dist: ipykernel<7,>=6.29; extra == "dev"
-Requires-Dist: mypy<2,>=1.15.0; extra == "dev"
+Requires-Dist: langchain-anthropic<1,>=0.3.10; extra == "dev"
+Requires-Dist: mypy<2,>=1.16.0; extra == "dev"
 Requires-Dist: nbconvert<8,>=7.16; extra == "dev"
 Requires-Dist: nbformat<6,>5.10; extra == "dev"
 Requires-Dist: nbqa<2,>1.9; extra == "dev"
@@ -51,7 +54,7 @@ Any questions or suggestions can be sent to the [kFinance Maintainers](kfinance-
 
 # Setup
 
-You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via 
+You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via
 
 `pip install kensho-kfinance`
 
@@ -61,11 +64,41 @@ To receive access, please email [S&P Global Market Intelligence](market.intellig
 
 Once access is obtained, get started using the [Authentication Guide](https://docs.kensho.com/llmreadyapi/kf-authentication) and [Usage Guide](https://docs.kensho.com/llmreadyapi/usage).
 
-We also provide an [interactive notebook](usage_examples.ipynb) that demonstrates some usage examples.
+To get started, we provide some notebooks:
+
+- The [LLM-ready API Basic Usage](example_notebooks%2Fbasic_usage.ipynb) notebook demonstrates how
+fetch data with the kFinance client.
+- The [tool_calling notebooks](example_notebooks%2Ftool_calling) show how the kFinance library can
+be used for tool calling. We provide notebooks for OpenAI (GPT), Anthropic (Claude), and Google
+  (Gemini). Each of these integrations comes in a langchain version, which uses langchain as a
+wrapper to simplify the integration, and as a lower level non-langchain version.
+
+We also provide an [interactive notebook](example_notebooks/basic_usage.ipynb) that demonstrates some usage examples.
+
+# MCP (Model Context Protocol)
+
+To run the kFinance MCP server use:
+
+`python -m kfinance.mcp`
+
+This function initializes and starts an MCP server that exposes the kFinance tools. The server supports multiple authentication methods and transport protocols to accommodate different deployment scenarios.
+
+The server's full signature is as follows:
+
+`kfinance.mcp [--stdio,-s]/[--sse, ] --refresh-token <refresh-token> --client-id <client-id> --private-key <private-key>`
+
+Authentication Methods (in order of precedence):
+1. Refresh Token: Uses an existing refresh token for authentication. The `--refresh-token <refresh-token>` argument must be provided.
+2. Key Pair: Uses client ID and private key for authentication. Both the `--client-id <client-id>` and `--private-key <private-key>` arguments must be provided.
+3. Browser: Falls back to browser-based authentication flow. This occurs if no auth arguments are provided.
+
+Transport Layers:
+- stdio can be set by passing either `--stdio` or `-s`
+- sse can be set by passing `--sse` or no other transport related flag
 
 # Versioning
-The kFinance uses semantic versioning (major, minor, patch). 
-To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md). 
+The kFinance uses semantic versioning (major, minor, patch).
+To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md).
 This will generate a new version of the library as part of the release process.
 
 # License

kensho_kfinance-2.4.0/README.md

@@ -0,0 +1,62 @@
+# kFinance
+
+The kFinance Python library provides a simple interface for the LLM-ready API, streamlining API requests and response handling. It can be used on its own, with LLMs, or integrated into applications.
+
+For a complete overview of the functions, usage, and features of the kFinance Python library, please refer to documentation [here](https://kensho-kfinance.readthedocs.io/en/stable/).
+
+Any questions or suggestions can be sent to the [kFinance Maintainers](kfinance-maintainers@kensho.com).
+
+# Setup
+
+You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via
+
+`pip install kensho-kfinance`
+
+# Getting started
+
+To receive access, please email [S&P Global Market Intelligence](market.intelligence@spglobal.com) for information on free trials and pricing.
+
+Once access is obtained, get started using the [Authentication Guide](https://docs.kensho.com/llmreadyapi/kf-authentication) and [Usage Guide](https://docs.kensho.com/llmreadyapi/usage).
+
+To get started, we provide some notebooks:
+
+- The [LLM-ready API Basic Usage](example_notebooks%2Fbasic_usage.ipynb) notebook demonstrates how
+fetch data with the kFinance client.
+- The [tool_calling notebooks](example_notebooks%2Ftool_calling) show how the kFinance library can
+be used for tool calling. We provide notebooks for OpenAI (GPT), Anthropic (Claude), and Google
+  (Gemini). Each of these integrations comes in a langchain version, which uses langchain as a
+wrapper to simplify the integration, and as a lower level non-langchain version.
+
+We also provide an [interactive notebook](example_notebooks/basic_usage.ipynb) that demonstrates some usage examples.
+
+# MCP (Model Context Protocol)
+
+To run the kFinance MCP server use:
+
+`python -m kfinance.mcp`
+
+This function initializes and starts an MCP server that exposes the kFinance tools. The server supports multiple authentication methods and transport protocols to accommodate different deployment scenarios.
+
+The server's full signature is as follows:
+
+`kfinance.mcp [--stdio,-s]/[--sse, ] --refresh-token <refresh-token> --client-id <client-id> --private-key <private-key>`
+
+Authentication Methods (in order of precedence):
+1. Refresh Token: Uses an existing refresh token for authentication. The `--refresh-token <refresh-token>` argument must be provided.
+2. Key Pair: Uses client ID and private key for authentication. Both the `--client-id <client-id>` and `--private-key <private-key>` arguments must be provided.
+3. Browser: Falls back to browser-based authentication flow. This occurs if no auth arguments are provided.
+
+Transport Layers:
+- stdio can be set by passing either `--stdio` or `-s`
+- sse can be set by passing `--sse` or no other transport related flag
+
+# Versioning
+The kFinance uses semantic versioning (major, minor, patch).
+To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md).
+This will generate a new version of the library as part of the release process.
+
+# License
+
+Use is solely in accordance with the signed agreement between your entity and S&P.
+
+Copyright 2025-present Kensho Technologies, LLC. The present date is determined by the timestamp of the most recent commit in the repository.

kensho_kfinance-2.2.5/usage_examples.ipynb → kensho_kfinance-2.4.0/example_notebooks/basic_usage.ipynb

@@ -20,7 +20,7 @@
     "\n",
     "<table class=\"tfo-notebook-buttons\" align=\"left\">\n",
     "  <td>\n",
-    "    <a target=\"_blank\" href=\"https://colab.research.google.com/github/kensho-technologies/llm-ready-api-examples/blob/main/basic_usage.ipynb\"><img src=\"./images/colab_logo_32px.png\" />Run in Google Colab</a>\n",
+    "    <a target=\"_blank\" href=\"https://colab.research.google.com/github/kensho-technologies/kfinance/blob/main/example_notebooks/basic_usage.ipynb\"><img src=\"../images/colab_logo_32px.png\" />Run in Google Colab</a>\n",
     "  </td>\n",
     "</table>"
    ]

kensho_kfinance-2.4.0/example_notebooks/tool_calling/langchain/anthropic_langchain_tool_calling.ipynb

@@ -0,0 +1,200 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "##### Copyright 2025 Kensho Technologies, LLC"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "# LangChain Tool Calling with Anthropic Claude\n",
+    "**_Claude to retrieve data from the LLM-ready API using the kFinance python library!_**\n",
+    "\n",
+    "What you'll need to run this notebook:\n",
+    "\n",
+    "1.   kFinance credentials\n",
+    "2.   An Anthropic API key\n",
+    "\n",
+    "<table class=\"tfo-notebook-buttons\" align=\"left\">\n",
+    "  <td>\n",
+    "    <a target=\"_blank\" href=\"https://colab.research.google.com/github/kensho-technologies/kfinance/blob/main/example_notebooks/tool_calling/langchain/anthropic_langchain_tool_calling.ipynb\"><img src=\"../../../images/colab_logo_32px.png\" />Run in Google Colab</a>\n",
+    "  </td>\n",
+    "</table>"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "ruP6MHfzR2Y4"
+   },
+   "source": [
+    "## Install dependencies"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "collapsed": true,
+    "id": "YAwU0_7TRhV7",
+    "jupyter": {
+     "outputs_hidden": true
+    },
+    "outputId": "e6ebf89c-7680-4852-e52b-c99610107cdf"
+   },
+   "outputs": [],
+   "source": [
+    "# install the latest version of kFinance package\n",
+    "%pip install kensho-kfinance\n",
+    "# install langchain and anthropic\n",
+    "%pip install anthropic\n",
+    "%pip install langchain\n",
+    "%pip install langchain-anthropic"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "e_G2p3tTSHeo"
+   },
+   "source": [
+    "# Instantiate kFinance Client"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "7QPnfPuX87rg"
+   },
+   "outputs": [],
+   "source": [
+    "# import the kfinance client\n",
+    "import sys\n",
+    "from kfinance.kfinance import Client\n",
+    "\n",
+    "# check if the current environment is a Google Colab\n",
+    "try:\n",
+    "    import google.colab\n",
+    "\n",
+    "    IN_GOOGLE_COLAB = True\n",
+    "except:\n",
+    "    IN_GOOGLE_COLAB = False\n",
+    "\n",
+    "# initialize the kfinance client with one of the following:\n",
+    "# 1. your kensho refresh token\n",
+    "# 2. your kensho client id and kensho private key\n",
+    "# 3. automated login (not accessible on Google Collab)\n",
+    "if IN_GOOGLE_COLAB:\n",
+    "    kensho_refresh_token = \"\"\n",
+    "    assert kensho_refresh_token != \"\", \"kensho refresh token is empty! Make sure to enter your kensho refresh token above\"\n",
+    "    kfinance_client = Client(refresh_token=kensho_refresh_token)\n",
+    "\n",
+    "    # kensho_client_id = \"\"\n",
+    "    # kensho_private_key = \"\"\n",
+    "    # assert kensho_client_id != \"\", \"kensho client id is empty! Make sure to enter your kensho client id above\"\n",
+    "    # assert kensho_private_key != \"\", \"kensho private key is empty! Make sure to enter your kensho private key above\"\n",
+    "    # kfinance_client = Client(client_id=kensho_client_id, private_key=kensho_private_key)\n",
+    "else:\n",
+    "    kfinance_client = Client()"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "LvQy_66Jioys"
+   },
+   "source": [
+    "# LangChain Tool Calling with Anthropic"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "WkoRuipOEQz6"
+   },
+   "outputs": [],
+   "source": [
+    "from pydantic import SecretStr\n",
+    "from kfinance.tool_calling.prompts import BASE_PROMPT\n",
+    "from langchain.agents import AgentExecutor, create_tool_calling_agent\n",
+    "from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder\n",
+    "from langchain_anthropic import ChatAnthropic\n",
+    "\n",
+    "\n",
+    "class LangChainAnthropicChat:\n",
+    "    def __init__(self, kfinance_client: Client) -> None:\n",
+    "        \"\"\"Initialize a LangChainAnthropicChat\"\"\"\n",
+    "\n",
+    "        # Initialize Anthropic with your Anthropic key\n",
+    "        anthropic_api_key = SecretStr(\"\")  # replace with your own key\n",
+    "        assert anthropic_api_key, \"Anthropic API key is empty! Make sure to enter your Anthropic API key above\"\n",
+    "        llm = ChatAnthropic(model=\"claude-3-7-sonnet-20250219\",\n",
+    "                            api_key=anthropic_api_key)  # type: ignore[call-arg]\n",
+    "\n",
+    "        # Get the prompt to use - can be replaced with any prompt that includes variables \"agent_scratchpad\" and \"input\"!\n",
+    "        # Prompt\n",
+    "        prompt = ChatPromptTemplate.from_messages(\n",
+    "            [\n",
+    "                (\"system\", BASE_PROMPT),\n",
+    "                MessagesPlaceholder(\"chat_history\", optional=True),\n",
+    "                (\"human\", \"{input}\"),\n",
+    "                MessagesPlaceholder(\"agent_scratchpad\"),\n",
+    "            ]\n",
+    "        )\n",
+    "        # Construct the tool calling agent\n",
+    "        agent = create_tool_calling_agent(llm=llm, tools=kfinance_client.langchain_tools,\n",
+    "                                          prompt=prompt)\n",
+    "        # Create an agent executor by passing in the agent and tools\n",
+    "        self.agent_executor = AgentExecutor(agent=agent, tools=kfinance_client.langchain_tools,\n",
+    "                                            verbose=True)\n",
+    "\n",
+    "    def start_chatting(self) -> None:\n",
+    "        \"\"\"Open chat shell\"\"\"\n",
+    "        while True:\n",
+    "            user_input = input(\"Enter your message and press the [return] key\\n\")\n",
+    "            self.agent_executor.invoke({\"input\": user_input})\n",
+    "            sys.stdout.write(\"\\n\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# instantiate LangChainAnthropicChat with the kfinance client\n",
+    "anthropic_chat = LangChainAnthropicChat(kfinance_client)\n",
+    "# start chatting with LangChainAnthropicChat\n",
+    "anthropic_chat.start_chatting()"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  },
+  "orig_nbformat": 4,
+  "kernelspec": {
+   "name": "python3",
+   "language": "python",
+   "display_name": "Python 3 (ipykernel)"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

kensho_kfinance-2.4.0/example_notebooks/tool_calling/langchain/google_gemini_langchain_tool_calling.ipynb

@@ -0,0 +1,193 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "##### Copyright 2025 Kensho Technologies, LLC"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "-zOQ3ZfKSrT2"
+   },
+   "source": [
+    "# LangChain Tool Calling with Google Gemini\n",
+    "**_Gemini to retrieve data from the LLM-ready API using the kFinance python library!_**\n",
+    "\n",
+    "What you'll need to run this notebook:\n",
+    "\n",
+    "1.   kFinance credentials\n",
+    "2.   An Gemini API key\n",
+    "\n",
+    "<table class=\"tfo-notebook-buttons\" align=\"left\">\n",
+    "  <td>\n",
+    "    <a target=\"_blank\" href=\"https://colab.research.google.com/github/kensho-technologies/kfinance/blob/main/example_notebooks/tool_calling/langchain/google_gemini_langchain_tool_calling.ipynb\"><img src=\"../../../images/colab_logo_32px.png\" />Run in Google Colab</a>\n",
+    "  </td>\n",
+    "</table>"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "ruP6MHfzR2Y4"
+   },
+   "source": [
+    "## Install dependencies"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "collapsed": true,
+    "id": "YAwU0_7TRhV7",
+    "jupyter": {
+     "outputs_hidden": true
+    },
+    "outputId": "e6ebf89c-7680-4852-e52b-c99610107cdf"
+   },
+   "outputs": [],
+   "source": [
+    "# install the latest version of kFinance package\n",
+    "%pip install kensho-kfinance\n",
+    "# install langchain and gemini\n",
+    "%pip install langchain\n",
+    "%pip install google-generativeai\n",
+    "%pip install langchain-google-genai"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "e_G2p3tTSHeo"
+   },
+   "source": [
+    "# Instantiate kFinance Client"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "7QPnfPuX87rg"
+   },
+   "outputs": [],
+   "source": [
+    "# import the kfinance client\n",
+    "import sys\n",
+    "from kfinance.kfinance import Client\n",
+    "# check if the current environment is a Google Colab\n",
+    "try:\n",
+    "    import google.colab\n",
+    "    IN_GOOGLE_COLAB = True\n",
+    "except:\n",
+    "    IN_GOOGLE_COLAB = False\n",
+    "\n",
+    "# initialize the kfinance client with one of the following:\n",
+    "# 1. your kensho refresh token\n",
+    "# 2. your kensho client id and kensho private key\n",
+    "# 3. automated login (not accessible on Google Collab)\n",
+    "if IN_GOOGLE_COLAB:\n",
+    "    kensho_refresh_token = \"\"\n",
+    "    assert kensho_refresh_token != \"\", \"kensho refresh token is empty! Make sure to enter your kensho refresh token above\"\n",
+    "    kfinance_client = Client(refresh_token=kensho_refresh_token)\n",
+    "\n",
+    "    # kensho_client_id = \"\"\n",
+    "    # kensho_private_key = \"\"\n",
+    "    # assert kensho_client_id != \"\", \"kensho client id is empty! Make sure to enter your kensho client id above\"\n",
+    "    # assert kensho_private_key != \"\", \"kensho private key is empty! Make sure to enter your kensho private key above\"\n",
+    "    # kfinance_client = Client(client_id=kensho_client_id, private_key=kensho_private_key)\n",
+    "else:\n",
+    "    kfinance_client = Client()\n"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "LvQy_66Jioys"
+   },
+   "source": [
+    "# LangChain Function Calling with Gemini"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "WkoRuipOEQz6"
+   },
+   "outputs": [],
+   "source": [
+    "from kfinance.tool_calling.prompts import BASE_PROMPT\n",
+    "# import langchain\n",
+    "from langchain.agents import AgentExecutor, create_tool_calling_agent\n",
+    "from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder\n",
+    "from langchain_google_genai import ChatGoogleGenerativeAI\n",
+    "\n",
+    "class LangChainGeminiChat:\n",
+    "    def __init__(self, kfinance_client: Client) -> None:\n",
+    "        # Initialize Gemini with your Gemini API key\n",
+    "        gemini_api_key = \"\" # replace with your own key\n",
+    "        assert gemini_api_key != \"\", \"Gemini API key is empty! Make sure to enter your Gemini API key above\"\n",
+    "        llm = ChatGoogleGenerativeAI(model=\"gemini-2.0-flash\", google_api_key=gemini_api_key)\n",
+    "        \n",
+    "        # Prompt\n",
+    "        prompt = ChatPromptTemplate.from_messages(\n",
+    "            [\n",
+    "                (\"system\", BASE_PROMPT),\n",
+    "                MessagesPlaceholder(\"chat_history\", optional=True),\n",
+    "                (\"human\", \"{input}\"),\n",
+    "                MessagesPlaceholder(\"agent_scratchpad\"),\n",
+    "            ]\n",
+    "        )\n",
+    "        # Construct the tool calling agent\n",
+    "        agent = create_tool_calling_agent(llm=llm, tools=kfinance_client.langchain_tools, prompt=prompt)\n",
+    "        # Create an agent executor by passing in the agent and tools\n",
+    "        self.agent_executor = AgentExecutor(agent=agent, tools=kfinance_client.langchain_tools, verbose=True)\n",
+    "\n",
+    "\n",
+    "    def start_chatting(self) -> None:\n",
+    "        \"\"\"Open chat shell\"\"\"\n",
+    "        while True:\n",
+    "            user_input = input(\"Enter your message and press the [return] key\\n\")\n",
+    "            self.agent_executor.invoke({\"input\": user_input})\n",
+    "            sys.stdout.write(\"\\n\")\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# instantiate LangChainGeminiChat with the kfinance client\n",
+    "gemini_chat = LangChainGeminiChat(kfinance_client)\n",
+    "# start chatting with LangChainGeminiChat\n",
+    "gemini_chat.start_chatting()"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  },
+  "orig_nbformat": 4,
+  "kernelspec": {
+   "name": "python3",
+   "language": "python",
+   "display_name": "Python 3 (ipykernel)"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}