kensho-kfinance 1.2.2__tar.gz → 2.0.0__tar.gz

{kensho_kfinance-1.2.2 → kensho_kfinance-2.0.0}/.gitignore

@@ -100,3 +100,7 @@ dmypy.json
 
 
 kfinance/version.py
+kfinance/wrappers/
+
+docs/output/
+docs/generated/

{kensho_kfinance-1.2.2 → kensho_kfinance-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 1.2.2
+Version: 2.0.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,6 +13,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: AUTHORS.md
 Requires-Dist: langchain-core>=0.3.15
+Requires-Dist: langchain-google-genai<3,>=2.1.0
 Requires-Dist: numpy>=1.22.4
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: pillow>=10
@@ -29,15 +30,16 @@ Requires-Dist: coverage<8,>=7.6.10; extra == "dev"
 Requires-Dist: mypy<2,>=1.15.0; extra == "dev"
 Requires-Dist: pytest<7,>=6.1.2; extra == "dev"
 Requires-Dist: pytest-cov<7,>=6.0.0; extra == "dev"
-Requires-Dist: requests_mock<1.2,>=1.1; extra == "dev"
+Requires-Dist: requests_mock<2,>=1.12; extra == "dev"
 Requires-Dist: ruff<1,>=0.9.4; extra == "dev"
+Requires-Dist: time_machine<3,>=2.1; extra == "dev"
 Dynamic: license-file
 
 # 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://kfinance.kensho.com/docs).
+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).
 

{kensho_kfinance-1.2.2 → kensho_kfinance-2.0.0}/README.md

@@ -2,7 +2,7 @@
 
 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://kfinance.kensho.com/docs).
+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).
 

kensho_kfinance-2.0.0/docs/build_tool_calling_documentation.py

@@ -0,0 +1,123 @@
+import inspect
+from enum import Enum
+from pathlib import Path
+
+from langchain_core.utils.function_calling import convert_to_openai_tool
+from pydantic._internal._repr import display_as_type
+
+from kfinance.kfinance import Client
+from kfinance.tool_calling import ALL_TOOLS, KfinanceTool
+
+
+def add_tool_calling_docs_for_all_tools() -> None:
+    """Add tool calling documentation for all tools.
+
+    Adding tool calling documentation involves two steps:
+    - Add a function definition to the tool file
+    - Add the module to tool_calling.rst to instruct sphinx what tool functions to document.
+
+    Do not commit changes that result from executing this function.
+    """
+
+    for tool_cls in ALL_TOOLS:
+        tool = tool_cls(kfinance_client=Client(refresh_token="fake"))
+        add_function_to_tools_file(tool)
+        add_module_to_tool_calling_rst(tool)
+
+
+def add_function_to_tools_file(tool: KfinanceTool) -> None:
+    """Add a function definition to each tool file, which mimics the tool definition passed to LLMs
+
+    The KfinanceTools are primarily intended to be transpiled for use with langchain, openai,
+    anthropic etc. However, the automatically generated documentation is not very helpful.
+    Instead, we use the tool definition to create a function definition that's close to what we
+    pass to the LLM. We then use sphinx to generate docs only for these generated functions.
+
+    We append the function definition to the same file as the tool. This ensures that the
+    [source] field in the documentation links to the file where the tool is defined.
+
+    Here's an example from the `GetNQuartersAgo` tool:
+
+    def get_n_quarters_ago(n: int) -> kfinance.constants.YearAndQuarter:
+        '''Get the year and quarter corresponding to [n] quarters before the current quarter.
+
+        :param n: Number of quarters before the current quarter
+        :type n: int
+        :rtype: YearAndQuarter'''
+
+    """
+
+    # The signature built with the inspect module does not include necessary imports.
+    imports = [
+        "import kfinance",
+        "import datetime",
+        "from typing import Optional"
+    ]
+    signature_str = build_signature_str(tool)
+
+    # Use inspect to retrieve the return type and add it to the imports if it's not a builtin.
+    return_annotation = inspect.signature(tool._run).return_annotation
+    if return_annotation.__module__ != "builtins":
+        imports.append(f"from {return_annotation.__module__} import {return_annotation.__name__}")
+
+    # Generate sphinx style annotations for each param.
+    openai_params = convert_to_openai_tool(tool)["function"]["parameters"]["properties"]
+    args = ""
+    for field_name, field_metadata in tool.args_schema.model_fields.items():
+        # We use the openai definition to extract the field description. This means that, just like
+        # pydantic/langchain, we use the docstring of an enum as the description for an enum field.
+        try:
+            openai_params[field_name]['description']
+        except:
+            assert False, tool.name
+        args += f"\n    :param {field_name}: {openai_params[field_name]['description']}"
+        args += f"\n    :type {field_name}: {display_as_type(field_metadata.annotation)}"
+
+    func_str = "\n" + "\n".join(imports) + "\n"
+    func_str += f"{signature_str}"
+    func_str += f'\n    """{tool.description}\n'
+    func_str += args
+    # Add sphinx style return annotation
+    func_str += f'\n    :rtype: {return_annotation.__name__}"""'
+
+    # Write definition to tool file
+    with open(inspect.getfile(tool.__class__), mode="a") as f:
+        f.write(func_str)
+
+def build_signature_str(tool) -> str:
+    """Return the signature string of the tool
+
+    Return value example:
+        def get_latest(use_local_timezone: bool = True) -> kfinance.constants.LatestPeriods:
+
+    This function is mostly necessary for proper enum handling.
+    inspect.Parameter uses __repr__ to stringify enum default values, not __str__.
+    As a result, it formats default values as "<Periodicity.day: 'day'>" rather than
+    "Periodicity.day".
+    """
+    signature = inspect.signature(tool._run)
+
+    for param in signature.parameters.values():
+        if isinstance(param.default, Enum):
+            # For enums, redirect __repr__ to __str__
+            param.default.__class__.__repr__ = param.default.__class__.__str__
+    return f"def {tool.name}{signature}:"
+
+
+
+def add_module_to_tool_calling_rst(tool: KfinanceTool) -> None:
+    """Add a module for each tool to tool_calling.rst.
+
+    We only want to include the generated function in the docs.
+
+    Example:
+        .. automodule:: kfinance.tool_calling.get_latest
+        :members: get_latest
+    """
+
+    module_str = "\n"
+    module_str += f"\n.. automodule:: {tool.__module__}"
+    module_str += f"\n    :members: {tool.name}"
+
+    with open(Path(Path(__file__).resolve().parent, "tool_calling.rst"), mode="a") as f:
+        f.write(module_str)

{kensho_kfinance-1.2.2 → kensho_kfinance-2.0.0}/docs/conf.py

@@ -7,15 +7,21 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 from importlib.metadata import version as get_version
 
-project = 'kensho-kfinance'
-copyright = '2025, Kensho Technologies'
-author = 'Kensho Technologies'
+from docs.build_tool_calling_documentation import add_tool_calling_docs_for_all_tools
+
+
+project = "kensho-kfinance"
+copyright = "2025, Kensho Technologies"
+author = "Kensho Technologies"
+
+# Add documentation for tool calling.
+add_tool_calling_docs_for_all_tools()
 
 # borrowed from here:
 # https://setuptools-scm.readthedocs.io/en/latest/usage/#usage-from-sphinx
 release: str = get_version(project)
 # for example take major/minor
-version: str = ".".join(release.split('.')[:2])
+version: str = ".".join(release.split(".")[:2])
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -57,7 +63,7 @@ source_suffix = [".rst", ".md"]
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html
 html_theme_options = {"body_min_width": 0, "body_max_width": "none"}

{kensho_kfinance-1.2.2 → kensho_kfinance-2.0.0}/docs/index.rst

@@ -9,7 +9,8 @@ Documentation page for kensho-kfinance library.
    :maxdepth: 1
 
    kfinance <kfinance>
-   llm_tools <llm_tools>
+   tool_calling <tool_calling>
+
 
 Indices and tables
 ==================

kensho_kfinance-2.0.0/docs/tool_calling.rst

@@ -0,0 +1,17 @@
+Tool Calling
+============
+
+Below, you can find all the tools that are available for tool calling.
+
+For examples on how to call these tools via OpenAI, Anthropic, or Gemini, see the
+`LLM-ready API examples. <https://github.com/kensho-technologies/llm-ready-api-examples>`_
+
+Note: The tool definitions below cannot be called directly and are intended for documentation only.
+They are auto-generated from langchain
+`BaseTools. <https://api.python.langchain.com/en/latest/tools/langchain_core.tools.BaseTool.html>`_
+To see the BaseTool behind a function definition, click on the source of the definition.
+
+.. The contents of tool_calling.rst get auto-generated by
+.. build_tool_calling_documentation.py. Don't commit any content below
+.. this comment.
+

{kensho_kfinance-1.2.2 → kensho_kfinance-2.0.0}/justfile

@@ -34,4 +34,4 @@ unit-test *args:
 # First, copy the dependencies in docs/requirements.txt into pyproject.toml and install in a venv.
 # Don't merge changes to pyproject and docs/output into the remote repo!
 sphinx *args:
-    sphinx-build docs docs/output
+    PYTHONPATH="${PYTHONPATH:-}:." sphinx-build docs docs/output

{kensho_kfinance-1.2.2 → kensho_kfinance-2.0.0}/kensho_kfinance.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 1.2.2
+Version: 2.0.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,6 +13,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: AUTHORS.md
 Requires-Dist: langchain-core>=0.3.15
+Requires-Dist: langchain-google-genai<3,>=2.1.0
 Requires-Dist: numpy>=1.22.4
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: pillow>=10
@@ -29,15 +30,16 @@ Requires-Dist: coverage<8,>=7.6.10; extra == "dev"
 Requires-Dist: mypy<2,>=1.15.0; extra == "dev"
 Requires-Dist: pytest<7,>=6.1.2; extra == "dev"
 Requires-Dist: pytest-cov<7,>=6.0.0; extra == "dev"
-Requires-Dist: requests_mock<1.2,>=1.1; extra == "dev"
+Requires-Dist: requests_mock<2,>=1.12; extra == "dev"
 Requires-Dist: ruff<1,>=0.9.4; extra == "dev"
+Requires-Dist: time_machine<3,>=2.1; extra == "dev"
 Dynamic: license-file
 
 # 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://kfinance.kensho.com/docs).
+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).
 

kensho_kfinance-2.0.0/kensho_kfinance.egg-info/SOURCES.txt

@@ -0,0 +1,64 @@
+.coveragerc
+.gitignore
+.readthedocs.yaml
+AUTHORS.md
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+LICENSE
+README.md
+justfile
+pyproject.toml
+setup.py
+.github/workflows/ci-lint.yml
+.github/workflows/ci-test.yml
+.github/workflows/python-publish.yml
+docs/build_tool_calling_documentation.py
+docs/conf.py
+docs/index.rst
+docs/kfinance.rst
+docs/requirements.txt
+docs/tool_calling.rst
+docs/templates/apidoc/package.rst_t
+docs/templates/apidoc/toc.rst_t
+kensho_kfinance.egg-info/PKG-INFO
+kensho_kfinance.egg-info/SOURCES.txt
+kensho_kfinance.egg-info/dependency_links.txt
+kensho_kfinance.egg-info/requires.txt
+kensho_kfinance.egg-info/top_level.txt
+kfinance/CHANGELOG.md
+kfinance/__init__.py
+kfinance/batch_request_handling.py
+kfinance/constants.py
+kfinance/fetch.py
+kfinance/kfinance.py
+kfinance/meta_classes.py
+kfinance/prompt.py
+kfinance/py.typed
+kfinance/server_thread.py
+kfinance/version.py
+kfinance/tests/__init__.py
+kfinance/tests/test_batch_requests.py
+kfinance/tests/test_fetch.py
+kfinance/tests/test_objects.py
+kfinance/tests/test_tools.py
+kfinance/tool_calling/README.md
+kfinance/tool_calling/__init__.py
+kfinance/tool_calling/get_business_relationship_from_identifier.py
+kfinance/tool_calling/get_capitalization_from_identifier.py
+kfinance/tool_calling/get_company_id_from_identifier.py
+kfinance/tool_calling/get_cusip_from_ticker.py
+kfinance/tool_calling/get_earnings_call_datetimes_from_identifier.py
+kfinance/tool_calling/get_financial_line_item_from_identifier.py
+kfinance/tool_calling/get_financial_statement_from_identifier.py
+kfinance/tool_calling/get_history_metadata_from_identifier.py
+kfinance/tool_calling/get_info_from_identifier.py
+kfinance/tool_calling/get_isin_from_ticker.py
+kfinance/tool_calling/get_latest.py
+kfinance/tool_calling/get_n_quarters_ago.py
+kfinance/tool_calling/get_prices_from_identifier.py
+kfinance/tool_calling/get_security_id_from_identifier.py
+kfinance/tool_calling/get_trading_item_id_from_identifier.py
+kfinance/tool_calling/shared_models.py
+scripts/copyright_line_check.sh
+scripts/lint.sh
+scripts/test.sh

{kensho_kfinance-1.2.2 → kensho_kfinance-2.0.0}/kensho_kfinance.egg-info/requires.txt

@@ -1,4 +1,5 @@
 langchain-core>=0.3.15
+langchain-google-genai<3,>=2.1.0
 numpy>=1.22.4
 pandas>=2.0.0
 pillow>=10
@@ -16,5 +17,6 @@ coverage<8,>=7.6.10
 mypy<2,>=1.15.0
 pytest<7,>=6.1.2
 pytest-cov<7,>=6.0.0
-requests_mock<1.2,>=1.1
+requests_mock<2,>=1.12
 ruff<1,>=0.9.4
+time_machine<3,>=2.1

{kensho_kfinance-1.2.2 → kensho_kfinance-2.0.0}/kfinance/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v2.0.0
+- Refactor llm tools to use langchain `BaseTool`.
+
 ## v1.2.2
 - Add tabulate and pydantic as dependencies
 

{kensho_kfinance-1.2.2 → kensho_kfinance-2.0.0}/kfinance/constants.py

@@ -1,4 +1,5 @@
 from datetime import date
+from enum import Enum
 from itertools import chain
 from typing import TypedDict
 
@@ -26,7 +27,45 @@ class IdentificationTriple(TypedDict):
     company_id: int
 
 
+class Capitalization(Enum):
+    """The capitalization type"""
+
+    market_cap = "market_cap"
+    tev = "tev"
+    shares_outstanding = "shares_outstanding"
+
+
+class PeriodType(Enum):
+    """The period type"""
+
+    annual = "annual"
+    quarterly = "quarterly"
+    ltm = "ltm"
+    ytd = "ytd"
+
+
+class Periodicity(Enum):
+    """The frequency or interval at which the historical data points are sampled or aggregated. Periodicity is not the same as the date range. The date range specifies the time span over which the data is retrieved, while periodicity determines how the data within that date range is aggregated."""
+
+    day = "day"
+    week = "week"
+    month = "month"
+    year = "year"
+
+
+class StatementType(Enum):
+    """The type of financial statement"""
+
+    balance_sheet = "balance_sheet"
+    bs = "balance_sheet"
+    income_statement = "income_statement"
+    cashflow = "cashflow"
+    cf = "cashflow"
+
+
 class BusinessRelationshipType(StrEnum):
+    """The type of business relationship"""
+
     supplier = "supplier"
     customer = "customer"
     distributor = "distributor"
@@ -1672,18 +1711,11 @@ LINE_ITEMS: list[LineItemType] = [
     },
 ]
 
-LINE_ITEMS_TO_DATA_ITEM_ID = {
-    line_item["name"]: line_item["dataitemid"] for line_item in LINE_ITEMS
-}
 
-LINE_ITEM_NAMES_AND_ALIASES = list(
+LINE_ITEM_NAMES_AND_ALIASES: list[str] = list(
     chain(*[[line_item["name"]] + list(line_item["aliases"]) for line_item in LINE_ITEMS])
 )
 
-LINE_ITEM_SYNONYMS = {
-    alias: line_item["dataitemid"] for line_item in LINE_ITEMS for alias in line_item["aliases"]
-}
-
 
 FINANCIAL_STATEMENTS: dict[str, int] = {
     "income_statement": 1,

{kensho_kfinance-1.2.2 → kensho_kfinance-2.0.0}/kfinance/fetch.py

@@ -7,7 +7,13 @@ from uuid import uuid4
 import jwt
 import requests
 
-from .constants import BusinessRelationshipType, IdentificationTriple, IndustryClassification
+from .constants import (
+    BusinessRelationshipType,
+    IdentificationTriple,
+    IndustryClassification,
+    Periodicity,
+    PeriodType,
+)
 
 
 # version.py gets autogenerated by setuptools-scm and is not available
@@ -228,14 +234,14 @@ class KFinanceApiClient:
         is_adjusted: bool = True,
         start_date: Optional[str] = None,
         end_date: Optional[str] = None,
-        periodicity: Optional[str] = None,
+        periodicity: Optional[Periodicity] = None,
     ) -> dict:
         """Get the pricing history."""
         url = (
             f"{self.url_base}pricing/{trading_item_id}/"
             f"{start_date if start_date is not None else 'none'}/"
             f"{end_date if end_date is not None else 'none'}/"
-            f"{periodicity if periodicity is not None else 'none'}/"
+            f"{periodicity.value if periodicity else 'none'}/"
             f"{'adjusted' if is_adjusted else 'unadjusted'}"
         )
         return self.fetch(url)
@@ -265,14 +271,14 @@ class KFinanceApiClient:
         is_adjusted: bool = True,
         start_date: Optional[str] = None,
         end_date: Optional[str] = None,
-        periodicity: Optional[str] = "",
+        periodicity: Optional[Periodicity] = None,
     ) -> bytes:
         """Get the price chart."""
         url = (
             f"{self.url_base}price_chart/{trading_item_id}/"
             f"{start_date if start_date is not None else 'none'}/"
             f"{end_date if end_date is not None else 'none'}/"
-            f"{periodicity if periodicity is not None else 'none'}/"
+            f"{periodicity.value if periodicity else 'none'}/"
             f"{'adjusted' if is_adjusted else 'unadjusted'}"
         )
 
@@ -291,7 +297,7 @@ class KFinanceApiClient:
         self,
         company_id: int,
         statement_type: str,
-        period_type: Optional[str] = None,
+        period_type: Optional[PeriodType] = None,
         start_year: Optional[int] = None,
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
@@ -300,7 +306,7 @@ class KFinanceApiClient:
         """Get a specified financial statement for a specified duration."""
         url = (
             f"{self.url_base}statements/{company_id}/{statement_type}/"
-            f"{period_type if period_type is not None else 'none'}/"
+            f"{period_type.value if period_type else 'none'}/"
             f"{start_year if start_year is not None else 'none'}/"
             f"{end_year if end_year is not None else 'none'}/"
             f"{start_quarter if start_quarter is not None else 'none'}/"
@@ -312,7 +318,7 @@ class KFinanceApiClient:
         self,
         company_id: int,
         line_item: str,
-        period_type: Optional[str] = None,
+        period_type: Optional[PeriodType] = None,
         start_year: Optional[int] = None,
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
@@ -321,7 +327,7 @@ class KFinanceApiClient:
         """Get a specified financial line item for a specified duration."""
         url = (
             f"{self.url_base}line_item/{company_id}/{line_item}/"
-            f"{period_type if period_type is not None else 'none'}/"
+            f"{period_type.value if period_type else 'none'}/"
             f"{start_year if start_year is not None else 'none'}/"
             f"{end_year if end_year is not None else 'none'}/"
             f"{start_quarter if start_quarter is not None else 'none'}/"