kensho-kfinance 2.9.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

kfinance/domains/earnings/earning_models.py

@@ -0,0 +1,41 @@
+from datetime import datetime, timezone
+
+from pydantic import AliasPath, BaseModel, Field
+
+
+class EarningsCall(BaseModel):
+    name: str
+    key_dev_id: int
+    datetime: datetime
+
+
+class EarningsCallResp(BaseModel):
+    earnings_calls: list[EarningsCall] = Field(validation_alias=AliasPath("earnings"))
+
+    @property
+    def most_recent_earnings(self) -> EarningsCall | None:
+        """Returns the most recent earnings call if available."""
+
+        past_earnings = [e for e in self.earnings_calls if e.datetime < datetime.now(timezone.utc)]
+        if past_earnings:
+            return max(past_earnings, key=lambda x: x.datetime)
+        return None
+
+    @property
+    def next_earnings(self) -> EarningsCall | None:
+        """Returns the next earnings call if available."""
+
+        future_earnings = [
+            e for e in self.earnings_calls if e.datetime > datetime.now(timezone.utc)
+        ]
+        if future_earnings:
+            return min(future_earnings, key=lambda x: x.datetime)
+        return None
+
+
+class TranscriptComponent(BaseModel):
+    """A transcript component with person name, text, and component type."""
+
+    person_name: str
+    text: str
+    component_type: str

kfinance/domains/earnings/earning_tools.py

@@ -0,0 +1,174 @@
+from textwrap import dedent
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+from kfinance.client.batch_request_handling import Task, process_tasks_in_thread_pool_executor
+from kfinance.client.fetch import KFinanceApiClient
+from kfinance.client.permission_models import Permission
+from kfinance.domains.companies.company_identifiers import (
+    CompanyIdentifier,
+    fetch_company_ids_from_identifiers,
+    parse_identifiers,
+)
+from kfinance.domains.earnings.earning_models import EarningsCallResp
+from kfinance.integrations.tool_calling.tool_calling_models import (
+    KfinanceTool,
+    ToolArgsWithIdentifiers,
+)
+
+
+class GetEarningsFromIdentifiers(KfinanceTool):
+    name: str = "get_earnings_from_identifiers"
+    description: str = dedent("""
+        Get all earnings for a list of identifiers.
+
+        Returns a list of dictionaries, with 'name' (str), 'key_dev_id' (int), and 'datetime' (str in ISO 8601 format with UTC timezone) attributes for each identifier.
+    """).strip()
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
+    accepted_permissions: set[Permission] | None = {
+        Permission.EarningsPermission,
+        Permission.TranscriptsPermission,
+    }
+
+    def _run(self, identifiers: list[str]) -> dict:
+        """Sample response:
+
+        {
+            'SPGI': [
+                {
+                    'datetime': '2025-04-29T12:30:00Z',
+                    'key_dev_id': 12346,
+                    'name': 'SPGI Q1 2025 Earnings Call'
+                }
+            ]
+        }
+
+        """
+        earnings_responses = get_earnings_from_identifiers(
+            identifiers=identifiers, kfinance_api_client=self.kfinance_client.kfinance_api_client
+        )
+        return {
+            str(identifier): earnings.model_dump(mode="json")["earnings_calls"]
+            for identifier, earnings in earnings_responses.items()
+        }
+
+
+class GetLatestEarningsFromIdentifiers(KfinanceTool):
+    name: str = "get_latest_earnings_from_identifiers"
+    description: str = dedent("""
+        Get the latest earnings for a list of identifiers.
+
+        Returns a dictionary with 'name' (str), 'key_dev_id' (int), and 'datetime' (str in ISO 8601 format with UTC timezone) attributes for each identifier.
+    """).strip()
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
+    accepted_permissions: set[Permission] | None = {
+        Permission.EarningsPermission,
+        Permission.TranscriptsPermission,
+    }
+
+    def _run(self, identifiers: list[str]) -> dict:
+        """Sample response:
+
+        {
+            'JPM': {
+                'datetime': '2025-04-29T12:30:00Z',
+                'key_dev_id': 12346,
+                'name': 'SPGI Q1 2025 Earnings Call'
+            },
+            'SPGI': 'No latest earnings available.'
+        }
+        """
+        earnings_responses = get_earnings_from_identifiers(
+            identifiers=identifiers, kfinance_api_client=self.kfinance_client.kfinance_api_client
+        )
+        output = {}
+        for identifier, earnings in earnings_responses.items():
+            most_recent_earnings = earnings.most_recent_earnings
+            if most_recent_earnings:
+                identifier_output: str | dict = most_recent_earnings.model_dump(mode="json")
+            else:
+                identifier_output = f"No latest earnings available."
+            output[str(identifier)] = identifier_output
+        return output
+
+
+class GetNextEarningsFromIdentifiers(KfinanceTool):
+    name: str = "get_next_earnings_from_identifiers"
+    description: str = dedent("""
+        Get the next earnings for a given identifier.
+
+        Returns a dictionary with 'name' (str), 'key_dev_id' (int), and 'datetime' (str in ISO 8601 format with UTC timezone) attributes for each identifier."
+    """).strip()
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
+    accepted_permissions: set[Permission] | None = {
+        Permission.EarningsPermission,
+        Permission.TranscriptsPermission,
+    }
+
+    def _run(self, identifiers: list[str]) -> dict:
+        """Sample response:
+
+        {
+            'JPM': {
+                'datetime': '2025-04-29T12:30:00Z',
+                'key_dev_id': 12346,
+                'name': 'SPGI Q1 2025 Earnings Call'
+            },
+            'SPGI': 'No next earnings available.'
+        }
+        """
+        earnings_responses = get_earnings_from_identifiers(
+            identifiers=identifiers, kfinance_api_client=self.kfinance_client.kfinance_api_client
+        )
+        output = {}
+        for identifier, earnings in earnings_responses.items():
+            next_earnings = earnings.next_earnings
+            if next_earnings:
+                identifier_output: str | dict = next_earnings.model_dump(mode="json")
+            else:
+                identifier_output = f"No next earnings available."
+            output[str(identifier)] = identifier_output
+        return output
+
+
+def get_earnings_from_identifiers(
+    identifiers: list[str], kfinance_api_client: KFinanceApiClient
+) -> dict[CompanyIdentifier, EarningsCallResp]:
+    """Return the earnings call response for all passed identifiers."""
+
+    parsed_identifiers = parse_identifiers(identifiers=identifiers, api_client=kfinance_api_client)
+    identifiers_to_company_ids = fetch_company_ids_from_identifiers(
+        identifiers=parsed_identifiers, api_client=kfinance_api_client
+    )
+
+    tasks = [
+        Task(
+            func=kfinance_api_client.fetch_earnings,
+            kwargs=dict(company_id=company_id),
+            result_key=identifier,
+        )
+        for identifier, company_id in identifiers_to_company_ids.items()
+    ]
+
+    earnings_responses = process_tasks_in_thread_pool_executor(
+        api_client=kfinance_api_client, tasks=tasks
+    )
+    return earnings_responses
+
+
+class GetTranscriptFromKeyDevIdArgs(BaseModel):
+    """Tool argument with a key_dev_id."""
+
+    key_dev_id: int = Field(description="The key dev ID for the earnings call")
+
+
+class GetTranscriptFromKeyDevId(KfinanceTool):
+    name: str = "get_transcript_from_key_dev_id"
+    description: str = "Get the raw transcript text for an earnings call by key dev ID."
+    args_schema: Type[BaseModel] = GetTranscriptFromKeyDevIdArgs
+    accepted_permissions: set[Permission] | None = {Permission.TranscriptsPermission}
+
+    def _run(self, key_dev_id: int) -> str:
+        transcript = self.kfinance_client.transcript(key_dev_id)
+        return transcript.raw

kfinance/domains/earnings/tests/test_earnings_tools.py

@@ -0,0 +1,195 @@
+from datetime import datetime
+
+from requests_mock import Mocker
+import time_machine
+
+from kfinance.client.kfinance import Client
+from kfinance.conftest import SPGI_COMPANY_ID
+from kfinance.domains.earnings.earning_tools import (
+    GetEarningsFromIdentifiers,
+    GetLatestEarningsFromIdentifiers,
+    GetNextEarningsFromIdentifiers,
+    GetTranscriptFromKeyDevId,
+    GetTranscriptFromKeyDevIdArgs,
+)
+from kfinance.integrations.tool_calling.tool_calling_models import ToolArgsWithIdentifiers
+
+
+class TestGetEarnings:
+    earnings_response = {
+        "earnings": [
+            {
+                "name": "SPGI Q1 2025 Earnings Call",
+                "datetime": "2025-04-29T12:30:00Z",
+                "key_dev_id": 12346,
+            },
+            {
+                "name": "SPGI Q4 2024 Earnings Call",
+                "datetime": "2025-02-11T13:30:00Z",
+                "key_dev_id": 12345,
+            },
+        ]
+    }
+
+    def test_get_earnings_from_identifiers(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetEarnings tool
+        WHEN we request all earnings for SPGI
+        THEN we get back all SPGI earnings
+        """
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
+            json=self.earnings_response,
+        )
+
+        expected_response = {
+            "SPGI": [
+                {
+                    "datetime": "2025-04-29T12:30:00Z",
+                    "key_dev_id": 12346,
+                    "name": "SPGI Q1 2025 Earnings Call",
+                },
+                {
+                    "datetime": "2025-02-11T13:30:00Z",
+                    "key_dev_id": 12345,
+                    "name": "SPGI Q4 2024 Earnings Call",
+                },
+            ]
+        }
+
+        tool = GetEarningsFromIdentifiers(kfinance_client=mock_client)
+        response = tool.run(ToolArgsWithIdentifiers(identifiers=["SPGI"]).model_dump(mode="json"))
+        assert response == expected_response
+
+    @time_machine.travel(
+        datetime(
+            2025,
+            5,
+            1,
+        )
+    )
+    def test_get_latest_earnings_from_identifiers(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetLatestEarnings tool
+        WHEN we request the latest earnings for SPGI
+        THEN we get back the latest SPGI earnings
+        """
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
+            json=self.earnings_response,
+        )
+
+        expected_response = {
+            "SPGI": {
+                "datetime": "2025-04-29T12:30:00Z",
+                "key_dev_id": 12346,
+                "name": "SPGI Q1 2025 Earnings Call",
+            }
+        }
+
+        tool = GetLatestEarningsFromIdentifiers(kfinance_client=mock_client)
+        response = tool.run(ToolArgsWithIdentifiers(identifiers=["SPGI"]).model_dump(mode="json"))
+        assert response == expected_response
+
+    def test_get_latest_earnings_no_data(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetLatestEarnings tool
+        WHEN we request the latest earnings for a company with no data
+        THEN we get a `No latest earnings available` message.
+        """
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
+            json={"earnings": []},
+        )
+        expected_response = {"SPGI": "No latest earnings available."}
+
+        tool = GetLatestEarningsFromIdentifiers(kfinance_client=mock_client)
+        response = tool.run(ToolArgsWithIdentifiers(identifiers=["SPGI"]).model_dump(mode="json"))
+        assert response == expected_response
+
+    @time_machine.travel(
+        datetime(
+            2025,
+            4,
+            1,
+        )
+    )
+    def test_get_next_earnings(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetNextEarningsFromIdentifiers tool
+        WHEN we request the next earnings for SPGI
+        THEN we get back the next SPGI earnings
+        """
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
+            json=self.earnings_response,
+        )
+
+        expected_response = {
+            "SPGI": {
+                "datetime": "2025-04-29T12:30:00Z",
+                "key_dev_id": 12346,
+                "name": "SPGI Q1 2025 Earnings Call",
+            }
+        }
+
+        tool = GetNextEarningsFromIdentifiers(kfinance_client=mock_client)
+        response = tool.run(ToolArgsWithIdentifiers(identifiers=["SPGI"]).model_dump(mode="json"))
+        assert response == expected_response
+
+    def test_get_next_earnings_no_data(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetNextEarnings tool
+        WHEN we request the next earnings for a company with no data
+        THEN we get a `No next earnings available` message.
+        """
+        earnings_data = {"earnings": []}
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
+            json=earnings_data,
+        )
+        expected_response = {"SPGI": "No next earnings available."}
+
+        tool = GetNextEarningsFromIdentifiers(kfinance_client=mock_client)
+        response = tool.run(ToolArgsWithIdentifiers(identifiers=["SPGI"]).model_dump(mode="json"))
+        assert response == expected_response
+
+
+class TestGetTranscript:
+    def test_get_transcript(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetTranscript tool
+        WHEN we request a transcript by key_dev_id
+        THEN we get back the transcript text
+        """
+        transcript_data = {
+            "transcript": [
+                {
+                    "person_name": "Operator",
+                    "text": "Good morning, everyone.",
+                    "component_type": "speech",
+                },
+                {
+                    "person_name": "CEO",
+                    "text": "Thank you for joining us today.",
+                    "component_type": "speech",
+                },
+            ]
+        }
+
+        requests_mock.get(
+            url="https://kfinance.kensho.com/api/v1/transcript/12345",
+            json=transcript_data,
+        )
+
+        expected_response = (
+            "Operator: Good morning, everyone.\n\nCEO: Thank you for joining us today."
+        )
+
+        tool = GetTranscriptFromKeyDevId(kfinance_client=mock_client)
+        response = tool.run(GetTranscriptFromKeyDevIdArgs(key_dev_id=12345).model_dump(mode="json"))
+        assert response == expected_response

kfinance/domains/line_items/line_item_tools.py

@@ -0,0 +1,114 @@
+from textwrap import dedent
+from typing import Literal, Type
+
+import numpy as np
+import pandas as pd
+from pydantic import BaseModel, Field
+
+from kfinance.client.batch_request_handling import Task, process_tasks_in_thread_pool_executor
+from kfinance.client.models.date_and_period_models import PeriodType
+from kfinance.client.permission_models import Permission
+from kfinance.domains.companies.company_identifiers import (
+    fetch_company_ids_from_identifiers,
+    parse_identifiers,
+)
+from kfinance.domains.line_items.line_item_models import LINE_ITEM_NAMES_AND_ALIASES
+from kfinance.integrations.tool_calling.tool_calling_models import (
+    KfinanceTool,
+    ToolArgsWithIdentifiers,
+)
+
+
+class GetFinancialLineItemFromIdentifiersArgs(ToolArgsWithIdentifiers):
+    # 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 GetFinancialLineItemFromIdentifiers(KfinanceTool):
+    name: str = "get_financial_line_item_from_identifiers"
+    description: str = dedent("""
+        Get the financial line item associated with a list of identifiers.
+
+        - When possible, pass multiple identifiers in a single call rather than making multiple calls.
+        - To fetch the most recent value for the line item, leave start_year, start_quarter, end_year, and end_quarter as None.
+
+        Example:
+        Query: "What are the revenues of Lowe's and Home Depot?"
+        Function: get_financial_line_item_from_identifiers(line_item="revenue", company_ids=["LW", "HD"])
+    """).strip()
+    args_schema: Type[BaseModel] = GetFinancialLineItemFromIdentifiersArgs
+    accepted_permissions: set[Permission] | None = {Permission.StatementsPermission}
+
+    def _run(
+        self,
+        identifiers: list[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,
+    ) -> dict:
+        """Sample response:
+
+        {
+            'SPGI': {
+                '2022': {'revenue': 11181000000.0},
+                '2023': {'revenue': 12497000000.0},
+                '2024': {'revenue': 14208000000.0}
+            }
+        }
+        """
+        api_client = self.kfinance_client.kfinance_api_client
+        parsed_identifiers = parse_identifiers(identifiers=identifiers, api_client=api_client)
+        identifiers_to_company_ids = fetch_company_ids_from_identifiers(
+            identifiers=parsed_identifiers, api_client=api_client
+        )
+
+        tasks = [
+            Task(
+                func=api_client.fetch_line_item,
+                kwargs=dict(
+                    company_id=company_id,
+                    line_item=line_item,
+                    period_type=period_type,
+                    start_year=start_year,
+                    end_year=end_year,
+                    start_quarter=start_quarter,
+                    end_quarter=end_quarter,
+                ),
+                result_key=identifier,
+            )
+            for identifier, company_id in identifiers_to_company_ids.items()
+        ]
+
+        line_item_responses = process_tasks_in_thread_pool_executor(
+            api_client=api_client, tasks=tasks
+        )
+
+        output = dict()
+        for identifier, result in line_item_responses.items():
+            df = pd.DataFrame(result).apply(pd.to_numeric).replace(np.nan, None)
+            # If no date and multiple companies, only return the most recent value.
+            # By default, we return 5 years of data, which can be too much when
+            # returning data for many companies.
+            if (
+                start_year is None
+                and end_year is None
+                and start_quarter is None
+                and end_quarter is None
+                and len(identifiers) > 1
+            ):
+                df = df.tail(1)
+            output[str(identifier)] = df.transpose().set_index(pd.Index([line_item])).to_dict()
+
+        return output

kfinance/domains/line_items/tests/test_line_item_tools.py

@@ -0,0 +1,86 @@
+from langchain_core.utils.function_calling import convert_to_openai_tool
+from requests_mock import Mocker
+
+from kfinance.client.kfinance import Client
+from kfinance.conftest import SPGI_COMPANY_ID
+from kfinance.domains.companies.company_models import COMPANY_ID_PREFIX
+from kfinance.domains.line_items.line_item_tools import (
+    GetFinancialLineItemFromIdentifiers,
+    GetFinancialLineItemFromIdentifiersArgs,
+)
+
+
+class TestGetFinancialLineItemFromCompanyIds:
+    line_item_resp = {
+        "line_item": {
+            "2022": "11181000000.000000",
+            "2023": "12497000000.000000",
+            "2024": "14208000000.000000",
+        }
+    }
+
+    def test_get_financial_line_item_from_identifiers(
+        self, mock_client: Client, requests_mock: Mocker
+    ):
+        """
+        GIVEN the GetFinancialLineItemFromCompanyId tool
+        WHEN we request SPGI revenue
+        THEN we get back the SPGI revenue
+        """
+
+        expected_response = {
+            "SPGI": {
+                "2022": {"revenue": 11181000000.0},
+                "2023": {"revenue": 12497000000.0},
+                "2024": {"revenue": 14208000000.0},
+            }
+        }
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/line_item/{SPGI_COMPANY_ID}/revenue/none/none/none/none/none",
+            json=self.line_item_resp,
+        )
+
+        tool = GetFinancialLineItemFromIdentifiers(kfinance_client=mock_client)
+        args = GetFinancialLineItemFromIdentifiersArgs(identifiers=["SPGI"], line_item="revenue")
+        response = tool.run(args.model_dump(mode="json"))
+        assert response == expected_response
+
+    def test_most_recent_request(self, requests_mock: Mocker, mock_client: Client) -> None:
+        """
+        GIVEN the GetFinancialLineItemFromIdentifiers tool
+        WHEN we request most recent line items for multiple companies
+        THEN we only get back the most recent line item for each company
+        """
+
+        company_ids = [1, 2]
+        expected_response = {
+            "C_1": {"2024": {"revenue": 14208000000.0}},
+            "C_2": {"2024": {"revenue": 14208000000.0}},
+        }
+        for company_id in company_ids:
+            requests_mock.get(
+                url=f"https://kfinance.kensho.com/api/v1/line_item/{company_id}/revenue/none/none/none/none/none",
+                json=self.line_item_resp,
+            )
+        tool = GetFinancialLineItemFromIdentifiers(kfinance_client=mock_client)
+        args = GetFinancialLineItemFromIdentifiersArgs(
+            identifiers=[f"{COMPANY_ID_PREFIX}{company_id}" for company_id in company_ids],
+            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 GetFinancialLineItemFromCompanyIds tool
+        WHEN we generate an openai schema from the tool
+        THEN all line items and aliases are included in the line item enum
+        """
+        tool = GetFinancialLineItemFromIdentifiers(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