kensho-kfinance 3.2.4__py3-none-any.whl → 4.0.0__py3-none-any.whl

kfinance/domains/cusip_and_isin/cusip_and_isin_tools.py

@@ -1,3 +1,4 @@
+from textwrap import dedent
 from typing import Type
 
 from pydantic import BaseModel
@@ -19,11 +20,22 @@ class GetCusipOrIsinFromIdentifiersResp(ToolRespWithErrors):
 
 class GetCusipFromIdentifiers(KfinanceTool):
     name: str = "get_cusip_from_identifiers"
-    description: str = "Get the CUSIPs for a group of identifiers."
+    description: str = dedent("""
+        Get the CUSIPs for a group of identifiers.
+
+        - When possible, pass multiple identifiers in a single call rather than making multiple calls.
+
+        Examples:
+        Query: "What is the CUSIP for Humana?"
+        Function: get_cusip_from_identifiers(identifiers=["Humana"])
+
+        Query: "Get CUSIPs for ATO and DTE"
+        Function: get_cusip_from_identifiers(identifiers=["ATO", "DTE"])
+    """).strip()
     args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
     accepted_permissions: set[Permission] | None = {Permission.IDPermission}
 
-    def _run(self, identifiers: list[str]) -> dict[str, str]:
+    def _run(self, identifiers: list[str]) -> GetCusipOrIsinFromIdentifiersResp:
         """Sample response:
 
         {
@@ -45,23 +57,33 @@ class GetCusipFromIdentifiers(KfinanceTool):
         ]
 
         cusip_responses = process_tasks_in_thread_pool_executor(api_client=api_client, tasks=tasks)
-        resp_model = GetCusipOrIsinFromIdentifiersResp(
+        return GetCusipOrIsinFromIdentifiersResp(
             results={
                 identifier: cusip_resp["cusip"]
                 for identifier, cusip_resp in cusip_responses.items()
             },
             errors=list(id_triple_resp.errors.values()),
         )
-        return resp_model.model_dump(mode="json")
 
 
 class GetIsinFromIdentifiers(KfinanceTool):
     name: str = "get_isin_from_identifiers"
-    description: str = "Get the ISINs for a group of identifiers."
+    description: str = dedent("""
+        Get the ISINs for a group of identifiers.
+
+        - When possible, pass multiple identifiers in a single call rather than making multiple calls.
+
+        Examples:
+        Query: "What is the ISIN for Autodesk?"
+        Function: get_isin_from_identifiers(identifiers=["Autodesk"])
+
+        Query: "Get ISINs for RCL and CCL"
+        Function: get_isin_from_identifiers(identifiers=["RCL", "CCL"])
+    """).strip()
     args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
     accepted_permissions: set[Permission] | None = {Permission.IDPermission}
 
-    def _run(self, identifiers: list[str]) -> dict:
+    def _run(self, identifiers: list[str]) -> GetCusipOrIsinFromIdentifiersResp:
         """Sample response:
 
         {
@@ -83,10 +105,9 @@ class GetIsinFromIdentifiers(KfinanceTool):
         ]
 
         isin_responses = process_tasks_in_thread_pool_executor(api_client=api_client, tasks=tasks)
-        resp_model = GetCusipOrIsinFromIdentifiersResp(
+        return GetCusipOrIsinFromIdentifiersResp(
             results={
                 identifier: isin_resp["isin"] for identifier, isin_resp in isin_responses.items()
             },
             errors=list(id_triple_resp.errors.values()),
         )
-        return resp_model.model_dump(mode="json")

kfinance/domains/cusip_and_isin/tests/test_cusip_and_isin_tools.py

@@ -4,6 +4,7 @@ from kfinance.client.kfinance import Client
 from kfinance.conftest import SPGI_SECURITY_ID
 from kfinance.domains.cusip_and_isin.cusip_and_isin_tools import (
     GetCusipFromIdentifiers,
+    GetCusipOrIsinFromIdentifiersResp,
     GetIsinFromIdentifiers,
 )
 from kfinance.integrations.tool_calling.tool_calling_models import ToolArgsWithIdentifiers
@@ -18,10 +19,12 @@ class TestGetCusipFromIdentifiers:
         """
 
         spgi_cusip = "78409V104"
-        expected_response = {
-            "results": {"SPGI": "78409V104"},
-            "errors": ["private_company is a private company without a security_id."],
-        }
+        expected_response = GetCusipOrIsinFromIdentifiersResp.model_validate(
+            {
+                "results": {"SPGI": "78409V104"},
+                "errors": ["private_company is a private company without a security_id."],
+            }
+        )
         requests_mock.get(
             url=f"https://kfinance.kensho.com/api/v1/cusip/{SPGI_SECURITY_ID}",
             json={"cusip": spgi_cusip},
@@ -43,10 +46,12 @@ class TestGetIsinFromIdentifiers:
 
         spgi_isin = "US78409V1044"
 
-        expected_response = {
-            "results": {"SPGI": "US78409V1044"},
-            "errors": ["private_company is a private company without a security_id."],
-        }
+        expected_response = GetCusipOrIsinFromIdentifiersResp.model_validate(
+            {
+                "results": {"SPGI": "US78409V1044"},
+                "errors": ["private_company is a private company without a security_id."],
+            }
+        )
         requests_mock.get(
             url=f"https://kfinance.kensho.com/api/v1/isin/{SPGI_SECURITY_ID}",
             json={"isin": spgi_isin},

kfinance/domains/earnings/earning_tools.py

@@ -14,6 +14,35 @@ from kfinance.integrations.tool_calling.tool_calling_models import (
 )
 
 
+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 GetTranscriptFromKeyDevIdResp(BaseModel):
+    transcript: str
+
+
+class GetTranscriptFromKeyDevId(KfinanceTool):
+    name: str = "get_transcript_from_key_dev_id"
+    description: str = dedent("""
+        Get the raw transcript text for an earnings call by key_dev_id.
+
+        The key_dev_id is obtained from earnings tools (get_earnings_from_identifiers, get_latest_earnings_from_identifiers, or get_next_earnings_from_identifiers).
+
+        Example:
+        Query: "Get the transcript for earnings call 12346"
+        Function: get_transcript_from_key_dev_id(key_dev_id=12346)
+    """).strip()
+    args_schema: Type[BaseModel] = GetTranscriptFromKeyDevIdArgs
+    accepted_permissions: set[Permission] | None = {Permission.TranscriptsPermission}
+
+    def _run(self, key_dev_id: int) -> GetTranscriptFromKeyDevIdResp:
+        transcript = self.kfinance_client.transcript(key_dev_id)
+        return GetTranscriptFromKeyDevIdResp(transcript=transcript.raw)
+
+
 class GetEarningsFromIdentifiersResp(ToolRespWithErrors):
     results: dict[str, EarningsCallResp]
 
@@ -25,9 +54,20 @@ class GetNextOrLatestEarningsFromIdentifiersResp(ToolRespWithErrors):
 class GetEarningsFromIdentifiers(KfinanceTool):
     name: str = "get_earnings_from_identifiers"
     description: str = dedent("""
-        Get all earnings for a list of identifiers.
+        Get all earnings calls 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.
+
+        - Use get_latest_earnings_from_identifiers to get only the most recent earnings
+        - Use get_next_earnings_from_identifiers to get only the next upcoming earnings
+        - To fetch the full transcript, call get_transcript_from_key_dev_id with the key_dev_id
+
+        Examples:
+        Query: "Get all earnings calls for Microsoft"
+        Function: get_earnings_from_identifiers(identifiers=["Microsoft"])
 
-        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.
+        Query: "Get earnings for CRM and ORCL"
+        Function: get_earnings_from_identifiers(identifiers=["CRM", "ORCL"])
     """).strip()
     args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
     accepted_permissions: set[Permission] | None = {
@@ -35,7 +75,7 @@ class GetEarningsFromIdentifiers(KfinanceTool):
         Permission.TranscriptsPermission,
     }
 
-    def _run(self, identifiers: list[str]) -> dict:
+    def _run(self, identifiers: list[str]) -> GetEarningsFromIdentifiersResp:
         """Sample response:
 
         {
@@ -52,18 +92,28 @@ class GetEarningsFromIdentifiers(KfinanceTool):
         }
 
         """
-        earnings_responses = get_earnings_from_identifiers(
+        return get_earnings_from_identifiers(
             identifiers=identifiers, kfinance_api_client=self.kfinance_client.kfinance_api_client
         )
-        return earnings_responses.model_dump(mode="json")
 
 
 class GetLatestEarningsFromIdentifiers(KfinanceTool):
     name: str = "get_latest_earnings_from_identifiers"
     description: str = dedent("""
-        Get the latest earnings for a list of identifiers.
+        Get the latest (most recent) earnings call 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.
+
+        - Use get_earnings_from_identifiers for all historical earnings
+        - Use get_next_earnings_from_identifiers for upcoming earnings
+        - To fetch the full transcript, call get_transcript_from_key_dev_id with the key_dev_id
+
+        Examples:
+        Query: "What was Microsoft's latest earnings call?"
+        Function: get_latest_earnings_from_identifiers(identifiers=["Microsoft"])
+
+        Query: "Get latest earnings for JPM and GS"
+        Function: get_latest_earnings_from_identifiers(identifiers=["JPM", "GS"])
     """).strip()
     args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
     accepted_permissions: set[Permission] | None = {
@@ -71,7 +121,7 @@ class GetLatestEarningsFromIdentifiers(KfinanceTool):
         Permission.TranscriptsPermission,
     }
 
-    def _run(self, identifiers: list[str]) -> dict:
+    def _run(self, identifiers: list[str]) -> GetNextOrLatestEarningsFromIdentifiersResp:
         """Sample response:
 
         {
@@ -95,15 +145,26 @@ class GetLatestEarningsFromIdentifiers(KfinanceTool):
                 output_model.results[identifier] = most_recent_earnings
             else:
                 output_model.errors.append(f"No latest earnings available for {identifier}.")
-        return output_model.model_dump(mode="json")
+        return output_model
 
 
 class GetNextEarningsFromIdentifiers(KfinanceTool):
     name: str = "get_next_earnings_from_identifiers"
     description: str = dedent("""
-        Get the next earnings for a given identifier.
+        Get the next scheduled earnings call 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.
 
-        Returns a dictionary with 'name' (str), 'key_dev_id' (int), and 'datetime' (str in ISO 8601 format with UTC timezone) attributes for each identifier."
+        - Use get_latest_earnings_from_identifiers for the most recent completed earnings
+        - Use get_earnings_from_identifiers for all historical earnings
+        - To fetch the full transcript (once available), call get_transcript_from_key_dev_id with the key_dev_id
+
+        Examples:
+        Query: "When is Waste Management's next earnings call?"
+        Function: get_next_earnings_from_identifiers(identifiers=["Waste Management"])
+
+        Query: "Get next earnings for FDX and UPS"
+        Function: get_next_earnings_from_identifiers(identifiers=["FDX", "UPS"])
     """).strip()
     args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
     accepted_permissions: set[Permission] | None = {
@@ -111,7 +172,7 @@ class GetNextEarningsFromIdentifiers(KfinanceTool):
         Permission.TranscriptsPermission,
     }
 
-    def _run(self, identifiers: list[str]) -> dict:
+    def _run(self, identifiers: list[str]) -> GetNextOrLatestEarningsFromIdentifiersResp:
         """Sample response:
 
         {
@@ -135,7 +196,7 @@ class GetNextEarningsFromIdentifiers(KfinanceTool):
                 output_model.results[identifier] = next_earnings
             else:
                 output_model.errors.append(f"No next earnings available for {identifier}.")
-        return output_model.model_dump(mode="json")
+        return output_model
 
 
 def get_earnings_from_identifiers(
@@ -162,20 +223,3 @@ def get_earnings_from_identifiers(
         results=earnings_responses, errors=list(id_triple_resp.errors.values())
     )
     return resp_model
-
-
-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

@@ -7,10 +7,13 @@ from kfinance.client.kfinance import Client
 from kfinance.conftest import SPGI_COMPANY_ID
 from kfinance.domains.earnings.earning_tools import (
     GetEarningsFromIdentifiers,
+    GetEarningsFromIdentifiersResp,
     GetLatestEarningsFromIdentifiers,
     GetNextEarningsFromIdentifiers,
+    GetNextOrLatestEarningsFromIdentifiersResp,
     GetTranscriptFromKeyDevId,
     GetTranscriptFromKeyDevIdArgs,
+    GetTranscriptFromKeyDevIdResp,
 )
 from kfinance.integrations.tool_calling.tool_calling_models import ToolArgsWithIdentifiers
 
@@ -43,27 +46,29 @@ class TestGetEarnings:
             json=self.earnings_response,
         )
 
-        expected_response = {
-            "results": {
-                "SPGI": {
-                    "earnings_calls": [
-                        {
-                            "name": "SPGI Q1 2025 Earnings Call",
-                            "key_dev_id": 12346,
-                            "datetime": "2025-04-29T12:30:00Z",
-                        },
-                        {
-                            "name": "SPGI Q4 2024 Earnings Call",
-                            "key_dev_id": 12345,
-                            "datetime": "2025-02-11T13:30:00Z",
-                        },
-                    ]
-                }
-            },
-            "errors": [
-                "No identification triple found for the provided identifier: NON-EXISTENT of type: ticker"
-            ],
-        }
+        expected_response = GetEarningsFromIdentifiersResp.model_validate(
+            {
+                "results": {
+                    "SPGI": {
+                        "earnings": [
+                            {
+                                "name": "SPGI Q1 2025 Earnings Call",
+                                "key_dev_id": 12346,
+                                "datetime": "2025-04-29T12:30:00Z",
+                            },
+                            {
+                                "name": "SPGI Q4 2024 Earnings Call",
+                                "key_dev_id": 12345,
+                                "datetime": "2025-02-11T13:30:00Z",
+                            },
+                        ]
+                    }
+                },
+                "errors": [
+                    "No identification triple found for the provided identifier: NON-EXISTENT of type: ticker"
+                ],
+            }
+        )
 
         tool = GetEarningsFromIdentifiers(kfinance_client=mock_client)
         response = tool.run(
@@ -95,16 +100,18 @@ class TestGetEarnings:
             json={"earnings": []},
         )
 
-        expected_response = {
-            "results": {
-                "SPGI": {
-                    "name": "SPGI Q1 2025 Earnings Call",
-                    "key_dev_id": 12346,
-                    "datetime": "2025-04-29T12:30:00Z",
-                }
-            },
-            "errors": ["No latest earnings available for private_company."],
-        }
+        expected_response = GetNextOrLatestEarningsFromIdentifiersResp.model_validate(
+            {
+                "results": {
+                    "SPGI": {
+                        "name": "SPGI Q1 2025 Earnings Call",
+                        "key_dev_id": 12346,
+                        "datetime": "2025-04-29T12:30:00Z",
+                    }
+                },
+                "errors": ["No latest earnings available for private_company."],
+            }
+        )
 
         tool = GetLatestEarningsFromIdentifiers(kfinance_client=mock_client)
         response = tool.run(
@@ -136,16 +143,18 @@ class TestGetEarnings:
             json={"earnings": []},
         )
 
-        expected_response = {
-            "results": {
-                "SPGI": {
-                    "datetime": "2025-04-29T12:30:00Z",
-                    "key_dev_id": 12346,
-                    "name": "SPGI Q1 2025 Earnings Call",
-                }
-            },
-            "errors": ["No next earnings available for private_company."],
-        }
+        expected_response = GetNextOrLatestEarningsFromIdentifiersResp.model_validate(
+            {
+                "results": {
+                    "SPGI": {
+                        "datetime": "2025-04-29T12:30:00Z",
+                        "key_dev_id": 12346,
+                        "name": "SPGI Q1 2025 Earnings Call",
+                    }
+                },
+                "errors": ["No next earnings available for private_company."],
+            }
+        )
 
         tool = GetNextEarningsFromIdentifiers(kfinance_client=mock_client)
         response = tool.run(
@@ -181,8 +190,8 @@ class TestGetTranscript:
             json=transcript_data,
         )
 
-        expected_response = (
-            "Operator: Good morning, everyone.\n\nCEO: Thank you for joining us today."
+        expected_response = GetTranscriptFromKeyDevIdResp(
+            transcript="Operator: Good morning, everyone.\n\nCEO: Thank you for joining us today."
         )
 
         tool = GetTranscriptFromKeyDevId(kfinance_client=mock_client)