kensho-kfinance 1.2.2__py3-none-any.whl → 2.0.1__py3-none-any.whl

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],
+        }

kfinance/tool_calling/get_capitalization_from_identifier.py

@@ -0,0 +1,35 @@
+from datetime import date
+
+from pydantic import Field
+
+from kfinance.constants import Capitalization
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetCapitalizationFromIdentifierArgs(ToolArgsWithIdentifier):
+    # no description because the description for enum fields comes from the enum docstring.
+    capitalization: Capitalization
+    start_date: date | None = Field(
+        description="The start date for historical capitalization retrieval", default=None
+    )
+    end_date: date | None = Field(
+        description="The end date for historical capitalization retrieval", default=None
+    )
+
+
+class GetCapitalizationFromIdentifier(KfinanceTool):
+    name: str = "get_capitalization_from_identifier"
+    description: str = "Get the historical market cap, tev (Total Enterprise Value), or shares outstanding of an identifier between inclusive start_date and inclusive end date. When requesting the most recent values, leave start_date and end_date empty."
+    args_schema = GetCapitalizationFromIdentifierArgs
+
+    def _run(
+        self,
+        identifier: str,
+        capitalization: Capitalization,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> str:
+        ticker = self.kfinance_client.ticker(identifier)
+        return getattr(ticker, capitalization.value)(
+            start_date=start_date, end_date=end_date
+        ).to_markdown()

kfinance/tool_calling/get_company_id_from_identifier.py

@@ -0,0 +1,14 @@
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetCompanyIdFromIdentifier(KfinanceTool):
+    name: str = "get_company_id_from_identifier"
+    description: str = "Get the company id associated with an identifier."
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+
+    def _run(self, identifier: str) -> int:
+        return self.kfinance_client.ticker(identifier).company_id

kfinance/tool_calling/get_cusip_from_ticker.py

@@ -0,0 +1,18 @@
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+from kfinance.tool_calling.shared_models import KfinanceTool
+
+
+class GetCusipFromTickerArgs(BaseModel):
+    ticker_str: str = Field(description="The ticker")
+
+
+class GetCusipFromTicker(KfinanceTool):
+    name: str = "get_cusip_from_ticker"
+    description: str = "Get the CUSIP associated with a ticker."
+    args_schema: Type[BaseModel] = GetCusipFromTickerArgs
+
+    def _run(self, ticker_str: str) -> str:
+        return self.kfinance_client.ticker(ticker_str).cusip

kfinance/tool_calling/get_earnings_call_datetimes_from_identifier.py

@@ -0,0 +1,17 @@
+import json
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetEarningsCallDatetimesFromIdentifier(KfinanceTool):
+    name: str = "get_earnings_call_datetimes_from_identifier"
+    description: str = "Get earnings call datetimes associated with an identifier."
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+
+    def _run(self, identifier: str) -> str:
+        ticker = self.kfinance_client.ticker(identifier)
+        earnings_call_datetimes = ticker.earnings_call_datetimes
+        return json.dumps([dt.isoformat() for dt in earnings_call_datetimes])

kfinance/tool_calling/get_financial_line_item_from_identifier.py

@@ -0,0 +1,45 @@
+from typing import Literal, Type
+
+from pydantic import BaseModel, Field
+
+from kfinance.constants import LINE_ITEM_NAMES_AND_ALIASES, PeriodType
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetFinancialLineItemFromIdentifierArgs(ToolArgsWithIdentifier):
+    # Note: mypy will not enforce this literal because of the type: ignore.
+    # But pydantic still uses the literal to check for allowed values and only includes
+    # allowed values in generated schemas.
+    line_item: Literal[tuple(LINE_ITEM_NAMES_AND_ALIASES)] = Field(  # type: ignore[valid-type]
+        description="The type of financial line_item requested"
+    )
+    period_type: PeriodType | None = Field(default=None, description="The period type")
+    start_year: int | None = Field(default=None, description="The starting year for the data range")
+    end_year: int | None = Field(default=None, description="The ending year for the data range")
+    start_quarter: Literal[1, 2, 3, 4] | None = Field(default=None, description="Starting quarter")
+    end_quarter: Literal[1, 2, 3, 4] | None = Field(default=None, description="Ending quarter")
+
+
+class GetFinancialLineItemFromIdentifier(KfinanceTool):
+    name: str = "get_financial_line_item_from_identifier"
+    description: str = "Get the financial line item associated with an identifier."
+    args_schema: Type[BaseModel] = GetFinancialLineItemFromIdentifierArgs
+
+    def _run(
+        self,
+        identifier: str,
+        line_item: str,
+        period_type: PeriodType | None = None,
+        start_year: int | None = None,
+        end_year: int | None = None,
+        start_quarter: Literal[1, 2, 3, 4] | None = None,
+        end_quarter: Literal[1, 2, 3, 4] | None = None,
+    ) -> str:
+        ticker = self.kfinance_client.ticker(identifier)
+        return getattr(ticker, line_item)(
+            period_type=period_type,
+            start_year=start_year,
+            end_year=end_year,
+            start_quarter=start_quarter,
+            end_quarter=end_quarter,
+        ).to_markdown()