kensho-kfinance 1.2.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

kfinance/meta_classes.py

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Any, Callable, Literal, Optional
 import numpy as np
 import pandas as pd
 
-from .constants import LINE_ITEMS, BusinessRelationshipType
+from .constants import LINE_ITEMS, BusinessRelationshipType, PeriodType
 from .fetch import KFinanceApiClient
 
 
@@ -27,7 +27,6 @@ class CompanyFunctionsMetaClass:
 
     def validate_inputs(
         self,
-        period_type: Optional[str] = None,
         start_year: Optional[int] = None,
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
@@ -35,9 +34,6 @@ class CompanyFunctionsMetaClass:
     ) -> None:
         """Test the time inputs for validity."""
 
-        if period_type not in {"annual", "quarterly", "ytd", "ltm", None}:
-            raise RuntimeError(f"Period type {period_type} is not valid.")
-
         if start_year and (start_year > datetime.now().year):
             raise ValueError("start_year is in the future")
 
@@ -54,7 +50,7 @@ class CompanyFunctionsMetaClass:
     def statement(
         self,
         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,
@@ -63,7 +59,6 @@ class CompanyFunctionsMetaClass:
         """Get the company's financial statement"""
         try:
             self.validate_inputs(
-                period_type=period_type,
                 start_year=start_year,
                 end_year=end_year,
                 start_quarter=start_quarter,
@@ -182,7 +177,7 @@ class CompanyFunctionsMetaClass:
     def line_item(
         self,
         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,
@@ -191,7 +186,6 @@ class CompanyFunctionsMetaClass:
         """Get a DataFrame of a financial line item according to the date ranges."""
         try:
             self.validate_inputs(
-                period_type=period_type,
                 start_year=start_year,
                 end_year=end_year,
                 start_quarter=start_quarter,

kfinance/tests/test_fetch.py

@@ -3,6 +3,7 @@ from unittest.mock import Mock
 
 import pytest
 
+from kfinance.constants import Periodicity, PeriodType
 from kfinance.fetch import KFinanceApiClient
 
 
@@ -50,8 +51,8 @@ class TestFetchItem(TestCase):
         start_date = "2025-01-01"
         end_date = "2025-01-31"
         is_adjusted = False
-        periodicity = "day"
-        expected_fetch_url = f"{self.kfinance_api_client.url_base}pricing/{trading_item_id}/{start_date}/{end_date}/{periodicity}/unadjusted"
+        periodicity = Periodicity.day
+        expected_fetch_url = f"{self.kfinance_api_client.url_base}pricing/{trading_item_id}/{start_date}/{end_date}/{periodicity.value}/unadjusted"
         self.kfinance_api_client.fetch_history(
             trading_item_id=trading_item_id,
             is_adjusted=is_adjusted,
@@ -77,12 +78,12 @@ class TestFetchItem(TestCase):
             company_id=company_id, statement_type=statement_type
         )
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
-        period_type = "quarterly"
+        period_type = PeriodType.quarterly
         start_year = 2024
         end_year = 2024
         start_quarter = 1
         end_quarter = 4
-        expected_fetch_url = f"{self.kfinance_api_client.url_base}statements/{company_id}/{statement_type}/{period_type}/{start_year}/{end_year}/{start_quarter}/{end_quarter}"
+        expected_fetch_url = f"{self.kfinance_api_client.url_base}statements/{company_id}/{statement_type}/{period_type.value}/{start_year}/{end_year}/{start_quarter}/{end_quarter}"
         self.kfinance_api_client.fetch_statement(
             company_id=company_id,
             statement_type=statement_type,
@@ -100,12 +101,12 @@ class TestFetchItem(TestCase):
         expected_fetch_url = f"{self.kfinance_api_client.url_base}line_item/{company_id}/{line_item}/none/none/none/none/none"
         self.kfinance_api_client.fetch_line_item(company_id=company_id, line_item=line_item)
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
-        period_type = "quarterly"
+        period_type = PeriodType.quarterly
         start_year = 2024
         end_year = 2024
         start_quarter = 1
         end_quarter = 4
-        expected_fetch_url = f"{self.kfinance_api_client.url_base}line_item/{company_id}/{line_item}/{period_type}/{start_year}/{end_year}/{start_quarter}/{end_quarter}"
+        expected_fetch_url = f"{self.kfinance_api_client.url_base}line_item/{company_id}/{line_item}/{period_type.value}/{start_year}/{end_year}/{start_quarter}/{end_quarter}"
         self.kfinance_api_client.fetch_line_item(
             company_id=company_id,
             line_item=line_item,
@@ -157,26 +158,6 @@ class TestFetchItem(TestCase):
         )
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
 
-    def test_fetch_ticker_industry_simple_groups(self) -> None:
-        simple_industry = "media"
-        expected_fetch_url = (
-            f"{self.kfinance_api_client.url_base}ticker_groups/industry/simple/{simple_industry}"
-        )
-        self.kfinance_api_client.fetch_ticker_simple_industry_groups(
-            simple_industry=simple_industry
-        )
-        self.kfinance_api_client.fetch.assert_called_once_with(expected_fetch_url)
-
-    def test_fetch_company_industry_simple_groups(self) -> None:
-        simple_industry = "media"
-        expected_fetch_url = (
-            f"{self.kfinance_api_client.url_base}company_groups/industry/simple/{simple_industry}"
-        )
-        self.kfinance_api_client.fetch_company_simple_industry_groups(
-            simple_industry=simple_industry
-        )
-        self.kfinance_api_client.fetch.assert_called_once_with(expected_fetch_url)
-
     def test_fetch_ticker_exchange_groups(self) -> None:
         exchange_code = "NYSE"
         expected_fetch_url = (

kfinance/tests/test_tools.py

@@ -0,0 +1,430 @@
+from datetime import date, datetime
+
+from langchain_core.utils.function_calling import convert_to_openai_tool
+import pytest
+from requests_mock import Mocker
+import time_machine
+
+from kfinance.constants import BusinessRelationshipType, Capitalization, StatementType
+from kfinance.kfinance import Client
+from kfinance.tool_calling import (
+    GetCompanyIdFromIdentifier,
+    GetEarningsCallDatetimesFromIdentifier,
+    GetFinancialLineItemFromIdentifier,
+    GetFinancialStatementFromIdentifier,
+    GetHistoryMetadataFromIdentifier,
+    GetInfoFromIdentifier,
+    GetIsinFromTicker,
+    GetLatest,
+    GetNQuartersAgo,
+    GetPricesFromIdentifier,
+    GetSecurityIdFromIdentifier,
+    GetTradingItemIdFromIdentifier,
+)
+from kfinance.tool_calling.get_business_relationship_from_identifier import (
+    GetBusinessRelationshipFromIdentifier,
+    GetBusinessRelationshipFromIdentifierArgs,
+)
+from kfinance.tool_calling.get_capitalization_from_identifier import (
+    GetCapitalizationFromIdentifier,
+    GetCapitalizationFromIdentifierArgs,
+)
+from kfinance.tool_calling.get_cusip_from_ticker import GetCusipFromTicker, GetCusipFromTickerArgs
+from kfinance.tool_calling.get_financial_line_item_from_identifier import (
+    GetFinancialLineItemFromIdentifierArgs,
+)
+from kfinance.tool_calling.get_financial_statement_from_identifier import (
+    GetFinancialStatementFromIdentifierArgs,
+)
+from kfinance.tool_calling.get_isin_from_ticker import GetIsinFromTickerArgs
+from kfinance.tool_calling.get_latest import GetLatestArgs
+from kfinance.tool_calling.get_n_quarters_ago import GetNQuartersAgoArgs
+from kfinance.tool_calling.get_prices_from_identifier import GetPricesFromIdentifierArgs
+from kfinance.tool_calling.shared_models import ToolArgsWithIdentifier
+
+
+SPGI_COMPANY_ID = 21719
+SPGI_SECURITY_ID = 2629107
+SPGI_TRADING_ITEM_ID = 2629108
+
+
+@pytest.fixture
+def mock_client(requests_mock: Mocker) -> Client:
+    """Create a KFinanceApiClient with a mock response for the SPGI id triple."""
+
+    client = Client(refresh_token="foo")
+    # Set access token so that the client doesn't try to fetch it.
+    client.kfinance_api_client._access_token = "foo"  # noqa: SLF001
+    client.kfinance_api_client._access_token_expiry = datetime(2100, 1, 1).timestamp()  # noqa: SLF001
+
+    # Create a mock for the SPGI id triple.
+    requests_mock.get(
+        url="https://kfinance.kensho.com/api/v1/id/SPGI",
+        json={
+            "trading_item_id": SPGI_TRADING_ITEM_ID,
+            "security_id": SPGI_SECURITY_ID,
+            "company_id": SPGI_COMPANY_ID,
+        },
+    )
+    return client
+
+
+class TestGetBusinessRelationshipFromIdentifier:
+    def test_get_business_relationship_from_identifier(
+        self, requests_mock: Mocker, mock_client: Client
+    ):
+        """
+        GIVEN the GetBusinessRelationshipFromIdentifier tool
+        WHEN we request SPGI suppliers
+        THEN we get back the SPGI suppliers
+        """
+        supplier_resp = {"current": [883103], "previous": [472898, 8182358]}
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/relationship/{SPGI_COMPANY_ID}/supplier",
+            json=supplier_resp,
+        )
+
+        tool = GetBusinessRelationshipFromIdentifier(kfinance_client=mock_client)
+        args = GetBusinessRelationshipFromIdentifierArgs(
+            identifier="SPGI", business_relationship=BusinessRelationshipType.supplier
+        )
+        resp = tool.run(args.model_dump(mode="json"))
+        # Companies is a set, so we have to sort the result
+        resp["previous"].sort()
+        assert resp == supplier_resp
+
+
+class TestGetCapitalizationFromIdentifier:
+    def test_get_capitalization_from_identifier(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetCapitalizationFromIdentifier tool
+        WHEN we request the SPGI market cap
+        THEN we get back the SPGI market cap
+        """
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/market_cap/{SPGI_COMPANY_ID}/none/none",
+            json={
+                "market_caps": [
+                    {
+                        "date": "2024-04-10",
+                        "market_cap": "132766738270.000000",
+                        "tev": "147455738270.000000",
+                        "shares_outstanding": 313099562,
+                    },
+                    {
+                        "date": "2024-04-11",
+                        "market_cap": "132416066761.000000",
+                        "tev": "147105066761.000000",
+                        "shares_outstanding": 313099562,
+                    },
+                ]
+            },
+        )
+
+        expected_response = "| date       |   market_cap |\n|:-----------|-------------:|\n| 2024-04-10 |  1.32767e+11 |\n| 2024-04-11 |  1.32416e+11 |"
+
+        tool = GetCapitalizationFromIdentifier(kfinance_client=mock_client)
+        args = GetCapitalizationFromIdentifierArgs(
+            identifier="SPGI", capitalization=Capitalization.market_cap
+        )
+        response = tool.run(args.model_dump(mode="json"))
+        assert response == expected_response
+
+
+class TestGetCompanyIdFromIdentifier:
+    def test_get_company_id_from_identifier(self, mock_client: Client):
+        """
+        GIVEN the GetCompanyIdFromIdentifier tool
+        WHEN request the company id for SPGI
+        THEN we get back the SPGI company id
+        """
+        tool = GetCompanyIdFromIdentifier(kfinance_client=mock_client)
+        resp = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+        assert resp == SPGI_COMPANY_ID
+
+
+class TestGetCusipFromTicker:
+    def test_get_cusip_from_ticker(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetCusipFromTicker tool
+        WHEN we pass args with the SPGI ticker
+        THEN we get back the SPGI cusip
+        """
+
+        spgi_cusip = "78409V104"
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/cusip/{SPGI_SECURITY_ID}",
+            json={"cusip": spgi_cusip},
+        )
+        tool = GetCusipFromTicker(kfinance_client=mock_client)
+        resp = tool.run(GetCusipFromTickerArgs(ticker_str="SPGI").model_dump(mode="json"))
+        assert resp == spgi_cusip
+
+
+class TestGetEarningsCallDatetimesFromTicker:
+    def test_get_earnings_call_datetimes_from_ticker(
+        self, requests_mock: Mocker, mock_client: Client
+    ):
+        """
+        GIVEN the GetEarningsCallDatetimesFromIdentifier tool
+        WHEN we request earnings call datetimes for SPGI
+        THEN we get back the expected SPGI earnings call datetimes
+        """
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}/dates",
+            json={"earnings": ["2025-04-29T12:30:00", "2025-02-11T13:30:00"]},
+        )
+        expected_response = '["2025-04-29T12:30:00+00:00", "2025-02-11T13:30:00+00:00"]'
+
+        tool = GetEarningsCallDatetimesFromIdentifier(kfinance_client=mock_client)
+        response = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+        assert response == expected_response
+
+
+class TestGetFinancialLineItemFromIdentifier:
+    def test_get_financial_line_item_from_identifier(
+        self, mock_client: Client, requests_mock: Mocker
+    ):
+        """
+        GIVEN the GetFinancialLineItemFromIdentifier tool
+        WHEN we request SPGI revenue
+        THEN we get back the SPGI revenue
+        """
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/line_item/{SPGI_COMPANY_ID}/revenue/none/none/none/none/none",
+            json={
+                "line_item": {
+                    "2020": "7442000000.000000",
+                    "2021": "8297000000.000000",
+                    "2022": "11181000000.000000",
+                    "2023": "12497000000.000000",
+                    "2024": "14208000000.000000",
+                }
+            },
+        )
+        expected_response = "|         |      2020 |      2021 |       2022 |       2023 |       2024 |\n|:--------|----------:|----------:|-----------:|-----------:|-----------:|\n| revenue | 7.442e+09 | 8.297e+09 | 1.1181e+10 | 1.2497e+10 | 1.4208e+10 |"
+
+        tool = GetFinancialLineItemFromIdentifier(kfinance_client=mock_client)
+        args = GetFinancialLineItemFromIdentifierArgs(identifier="SPGI", line_item="revenue")
+        response = tool.run(args.model_dump(mode="json"))
+        assert response == expected_response
+
+    def test_line_items_and_aliases_included_in_schema(self, mock_client: Client):
+        """
+        GIVEN a GetFinancialLineItemFromIdentifier tool
+        WHEN we generate an openai schema from the tool
+        THEN all line items and aliases are included in the line item enum
+        """
+        tool = GetFinancialLineItemFromIdentifier(kfinance_client=mock_client)
+        oai_schema = convert_to_openai_tool(tool)
+        line_items = oai_schema["function"]["parameters"]["properties"]["line_item"]["enum"]
+        # revenue is a line item
+        assert "revenue" in line_items
+        # normal_revenue is an alias for revenue
+        assert "normal_revenue" in line_items
+
+
+class TestGetFinancialStatementFromIdentifier:
+    def test_get_financial_statement_from_identifier(
+        self, mock_client: Client, requests_mock: Mocker
+    ):
+        """
+        GIVEN the GetFinancialLineItemFromIdentifier tool
+        WHEN we request the SPGI income statement
+        THEN we get back the SPGI income statement
+        """
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/statements/{SPGI_COMPANY_ID}/income_statement/none/none/none/none/none",
+            # truncated from the original API response
+            json={
+                "statements": {
+                    "2020": {"Revenues": "7442000000.000000", "Total Revenues": "7442000000.000000"}
+                }
+            },
+        )
+        expected_response = "|                |      2020 |\n|:---------------|----------:|\n| Revenues       | 7.442e+09 |\n| Total Revenues | 7.442e+09 |"
+
+        tool = GetFinancialStatementFromIdentifier(kfinance_client=mock_client)
+        args = GetFinancialStatementFromIdentifierArgs(
+            identifier="SPGI", statement=StatementType.income_statement
+        )
+        response = tool.run(args.model_dump(mode="json"))
+        assert response == expected_response
+
+
+class TestGetHistoryMetadataFromIdentifier:
+    def test_get_history_metadata_from_identifier(self, mock_client: Client, requests_mock: Mocker):
+        """
+        GIVEN the GetHistoryMetadataFromIdentifier tool
+        WHEN request history metadata for SPGI
+        THEN we get back the SPGI history metadata
+        """
+
+        metadata_resp = {
+            "currency": "USD",
+            "exchange_name": "NYSE",
+            "first_trade_date": "1968-01-02",
+            "instrument_type": "Equity",
+            "symbol": "SPGI",
+        }
+        expected_resp = {
+            "currency": "USD",
+            "exchange_name": "NYSE",
+            "first_trade_date": date(1968, 1, 2),
+            "instrument_type": "Equity",
+            "symbol": "SPGI",
+        }
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/pricing/{SPGI_TRADING_ITEM_ID}/metadata",
+            json=metadata_resp,
+        )
+
+        tool = GetHistoryMetadataFromIdentifier(kfinance_client=mock_client)
+        resp = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+        assert resp == expected_resp
+
+
+class TestGetInfoFromIdentifier:
+    def test_get_info_from_identifier(self, mock_client: Client, requests_mock: Mocker):
+        """
+        GIVEN the GetInfoFromIdentifier tool
+        WHEN request info for SPGI
+        THEN we get back info for SPGI
+        """
+
+        # truncated from the original
+        info_resp = {"name": "S&P Global Inc.", "status": "Operating"}
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/info/{SPGI_COMPANY_ID}",
+            json=info_resp,
+        )
+
+        tool = GetInfoFromIdentifier(kfinance_client=mock_client)
+        resp = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+        assert resp == str(info_resp)
+
+
+class TestGetIsinFromTicker:
+    def test_get_isin_from_ticker(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetIsinFromTicker tool
+        WHEN we pass args with the SPGI ticker
+        THEN we get back the SPGI isin
+        """
+
+        spgi_isin = "US78409V1044"
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/isin/{SPGI_SECURITY_ID}",
+            json={"isin": spgi_isin},
+        )
+
+        tool = GetIsinFromTicker(kfinance_client=mock_client)
+        resp = tool.run(GetIsinFromTickerArgs(ticker_str="SPGI").model_dump(mode="json"))
+        assert resp == spgi_isin
+
+
+class TestGetLatest:
+    @time_machine.travel(datetime(2025, 1, 1, 12, tzinfo=datetime.now().astimezone().tzinfo))
+    def test_get_latest(self, mock_client: Client):
+        """
+        GIVEN the GetLatest tool
+        WHEN request latest info
+        THEN we get back latest info
+        """
+
+        expected_resp = {
+            "annual": {"latest_year": 2024},
+            "now": {
+                "current_date": "2025-01-01",
+                "current_month": 1,
+                "current_quarter": 1,
+                "current_year": 2025,
+            },
+            "quarterly": {"latest_quarter": 4, "latest_year": 2024},
+        }
+        tool = GetLatest(kfinance_client=mock_client)
+        resp = tool.run(GetLatestArgs().model_dump(mode="json"))
+        assert resp == expected_resp
+
+
+class TestGetNQuartersAgo:
+    @time_machine.travel(datetime(2025, 1, 1, 12, tzinfo=datetime.now().astimezone().tzinfo))
+    def test_get_n_quarters_ago(self, mock_client: Client):
+        """
+        GIVEN the GetNQuartersAgo tool
+        WHEN we request 3 quarters ago
+        THEN we get back 3 quarters ago
+        """
+
+        expected_resp = {"quarter": 2, "year": 2024}
+        tool = GetNQuartersAgo(kfinance_client=mock_client)
+        resp = tool.run(GetNQuartersAgoArgs(n=3).model_dump(mode="json"))
+        assert resp == expected_resp
+
+
+class TestPricesFromIdentifier:
+    def test_get_prices_from_identifier(self, mock_client: Client, requests_mock: Mocker):
+        """
+        GIVEN the GetPricesFromIdentifier tool
+        WHEN we request prices for SPGI
+        THEN we get back prices for SPGI
+        """
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/pricing/{SPGI_TRADING_ITEM_ID}/none/none/day/adjusted",
+            # truncated response
+            json={
+                "prices": [
+                    {
+                        "date": "2024-04-11",
+                        "open": "424.260000",
+                        "high": "425.990000",
+                        "low": "422.040000",
+                        "close": "422.920000",
+                        "volume": "1129158",
+                    },
+                    {
+                        "date": "2024-04-12",
+                        "open": "419.230000",
+                        "high": "421.940000",
+                        "low": "416.450000",
+                        "close": "417.810000",
+                        "volume": "1182229",
+                    },
+                ]
+            },
+        )
+        expected_response = "| date       |   open |   high |    low |   close |      volume |\n|:-----------|-------:|-------:|-------:|--------:|------------:|\n| 2024-04-11 | 424.26 | 425.99 | 422.04 |  422.92 | 1.12916e+06 |\n| 2024-04-12 | 419.23 | 421.94 | 416.45 |  417.81 | 1.18223e+06 |"
+
+        tool = GetPricesFromIdentifier(kfinance_client=mock_client)
+        response = tool.run(GetPricesFromIdentifierArgs(identifier="SPGI").model_dump(mode="json"))
+        assert response == expected_response
+
+
+class TestGetSecurityIdFromIdentifier:
+    def test_get_security_id_from_identifier(self, mock_client: Client):
+        """
+        GIVEN the GetSecurityIdFromIdentifier tool
+        WHEN we request the security id for SPGI
+        THEN we get back the SPGI primary security id
+        """
+        tool = GetSecurityIdFromIdentifier(kfinance_client=mock_client)
+        resp = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+        assert resp == SPGI_SECURITY_ID
+
+
+class TestGetTradingItemIdFromIdentifier:
+    def test_get_security_id_from_identifier(self, mock_client: Client):
+        """
+        GIVEN the GetTradingItemIdFromIdentifier tool
+        WHEN we request the trading item id for SPGI
+        THEN we get back the SPGI primary trading item id
+        """
+        tool = GetTradingItemIdFromIdentifier(kfinance_client=mock_client)
+        resp = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+        assert resp == SPGI_TRADING_ITEM_ID

kfinance/tool_calling/README.md

@@ -0,0 +1,38 @@
+# Tool Calling
+
+The tools defined in this directory are intended for tool calling. 
+
+Each tool is a subclass of [KfinanceTool](shared_models.py), which is
+turn a subclass of `BaseTool` from langchain. We use langchain to convert these tools 
+into LLM-specific tool descriptions.
+
+### KfinanceTool
+Each `KfinanceTool` requires the following attributes to be defined:
+- name: the function name
+- description: the description of the function passed to an LLM. This should not include a description 
+of the arguments.
+- args_schema: A pydantic model defining the input schema for the function (more on that below)
+- _run: the source code for the tool.
+
+All new tools have to be added to the `ALL_TOOLS` [list](__init__.py).
+
+
+When initializing a `KfinanceTool`, it's always required to pass in an initialized Kfinance 
+`Client`, which can be accessed from within the tool as `self.kfinance_client`. This allows us to 
+make kfinance api calls without needing to get a kfinance client passed in with every call.
+
+If tools are called from langchain, then langchain handles the deserialization of arguments before 
+calling the tools. If tools are called without langchain, then we have to handle that
+deserialization ourselves. The deserialization step is handled by 
+`KfinanceTool.run_without_langchain`.
+
+### args_schema Pydantic Model
+Each `KfinanceTool` has a corresponding pydantic model that defines the call arguments for the tool.
+We use langchain to convert these pydantic models into llm-specific argument schemas. 
+- Each field should contain a `description` and, where feasible, a `default`.
+- Use of python objects is preferred over string types. For example enums, dates, and datetimes all 
+work.
+- The order, type, and default of arguments in the `tool_args` has to match the order, type, and 
+default of arguments in the `_run` function.
+- If your tool takes an `identifier` as its first argument, subclass `ToolArgsWithIdentifier` to 
+ensure that the description of the identifier remains consistent across tools.

kfinance/tool_calling/__init__.py

@@ -0,0 +1,47 @@
+from typing import Type
+
+from kfinance.tool_calling.get_business_relationship_from_identifier import (
+    GetBusinessRelationshipFromIdentifier,
+)
+from kfinance.tool_calling.get_capitalization_from_identifier import GetCapitalizationFromIdentifier
+from kfinance.tool_calling.get_company_id_from_identifier import GetCompanyIdFromIdentifier
+from kfinance.tool_calling.get_cusip_from_ticker import GetCusipFromTicker
+from kfinance.tool_calling.get_earnings_call_datetimes_from_identifier import (
+    GetEarningsCallDatetimesFromIdentifier,
+)
+from kfinance.tool_calling.get_financial_line_item_from_identifier import (
+    GetFinancialLineItemFromIdentifier,
+)
+from kfinance.tool_calling.get_financial_statement_from_identifier import (
+    GetFinancialStatementFromIdentifier,
+)
+from kfinance.tool_calling.get_history_metadata_from_identifier import (
+    GetHistoryMetadataFromIdentifier,
+)
+from kfinance.tool_calling.get_info_from_identifier import GetInfoFromIdentifier
+from kfinance.tool_calling.get_isin_from_ticker import GetIsinFromTicker
+from kfinance.tool_calling.get_latest import GetLatest
+from kfinance.tool_calling.get_n_quarters_ago import GetNQuartersAgo
+from kfinance.tool_calling.get_prices_from_identifier import GetPricesFromIdentifier
+from kfinance.tool_calling.get_security_id_from_identifier import GetSecurityIdFromIdentifier
+from kfinance.tool_calling.get_trading_item_id_from_identifier import GetTradingItemIdFromIdentifier
+from kfinance.tool_calling.shared_models import KfinanceTool
+
+
+ALL_TOOLS: list[Type[KfinanceTool]] = [
+    GetLatest,
+    GetNQuartersAgo,
+    GetCompanyIdFromIdentifier,
+    GetSecurityIdFromIdentifier,
+    GetTradingItemIdFromIdentifier,
+    GetIsinFromTicker,
+    GetCusipFromTicker,
+    GetInfoFromIdentifier,
+    GetEarningsCallDatetimesFromIdentifier,
+    GetHistoryMetadataFromIdentifier,
+    GetPricesFromIdentifier,
+    GetCapitalizationFromIdentifier,
+    GetFinancialStatementFromIdentifier,
+    GetFinancialLineItemFromIdentifier,
+    GetBusinessRelationshipFromIdentifier,
+]

kfinance/tool_calling/get_business_relationship_from_identifier.py

@@ -0,0 +1,28 @@
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.constants import BusinessRelationshipType
+from kfinance.kfinance import BusinessRelationships
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetBusinessRelationshipFromIdentifierArgs(ToolArgsWithIdentifier):
+    # no description because the description for enum fields comes from the enum docstring.
+    business_relationship: BusinessRelationshipType
+
+
+class GetBusinessRelationshipFromIdentifier(KfinanceTool):
+    name: str = "get_business_relationship_from_identifier"
+    description: str = 'Get the current and previous company IDs that are relationship_type of a given identifier. For example, "What are the current distributors of SPGI?" or "What are the previous borrowers of JPM?"'
+    args_schema: Type[BaseModel] = GetBusinessRelationshipFromIdentifierArgs
+
+    def _run(self, identifier: str, business_relationship: BusinessRelationshipType) -> dict:
+        ticker = self.kfinance_client.ticker(identifier)
+        business_relationship_obj: BusinessRelationships = getattr(
+            ticker, business_relationship.value
+        )
+        return {
+            "current": [company.company_id for company in business_relationship_obj.current],
+            "previous": [company.company_id for company in business_relationship_obj.previous],
+        }