kensho-kfinance 3.0.3__py3-none-any.whl → 3.1.1__py3-none-any.whl

kfinance/domains/competitors/tests/test_competitor_tools.py

@@ -14,7 +14,9 @@ class TestGetCompetitorsFromIdentifiers:
         """
         GIVEN the GetCompetitorsFromIdentifiers tool
         WHEN we request the SPGI competitors that are named by competitors
+            and competitors for a non-existent company
         THEN we get back the SPGI competitors that are named by competitors
+            and an error for the non-existent company
         """
         competitors_response = {
             "competitors": [
@@ -23,12 +25,23 @@ class TestGetCompetitorsFromIdentifiers:
             ]
         }
         expected_response = {
-            "SPGI": {
-                "competitors": [
-                    {"company_id": "C_35352", "company_name": "The Descartes Systems Group Inc."},
-                    {"company_id": "C_4003514", "company_name": "London Stock Exchange Group plc"},
-                ]
-            }
+            "results": {
+                "SPGI": {
+                    "competitors": [
+                        {
+                            "company_id": "C_35352",
+                            "company_name": "The Descartes Systems Group Inc.",
+                        },
+                        {
+                            "company_id": "C_4003514",
+                            "company_name": "London Stock Exchange Group plc",
+                        },
+                    ]
+                }
+            },
+            "errors": [
+                "No identification triple found for the provided identifier: NON-EXISTENT of type: ticker"
+            ],
         }
 
         requests_mock.get(
@@ -39,7 +52,8 @@ class TestGetCompetitorsFromIdentifiers:
 
         tool = GetCompetitorsFromIdentifiers(kfinance_client=mock_client)
         args = GetCompetitorsFromIdentifiersArgs(
-            identifiers=["SPGI"], competitor_source=CompetitorSource.named_by_competitor
+            identifiers=["SPGI", "non-existent"],
+            competitor_source=CompetitorSource.named_by_competitor,
         )
         response = tool.run(args.model_dump(mode="json"))
         assert response == expected_response

kfinance/domains/cusip_and_isin/cusip_and_isin_tools.py

@@ -4,16 +4,19 @@ from pydantic import BaseModel
 
 from kfinance.client.batch_request_handling import Task, process_tasks_in_thread_pool_executor
 from kfinance.client.permission_models import Permission
-from kfinance.domains.companies.company_identifiers import (
-    fetch_security_ids_from_identifiers,
-    parse_identifiers,
-)
 from kfinance.integrations.tool_calling.tool_calling_models import (
     KfinanceTool,
     ToolArgsWithIdentifiers,
+    ToolRespWithErrors,
 )
 
 
+class GetCusipOrIsinFromIdentifiersResp(ToolRespWithErrors):
+    """Both cusip and isin return a mapping from identifier to str (isin or cusip)."""
+
+    results: dict[str, str]
+
+
 class GetCusipFromIdentifiers(KfinanceTool):
     name: str = "get_cusip_from_identifiers"
     description: str = "Get the CUSIPs for a group of identifiers."
@@ -23,30 +26,33 @@ class GetCusipFromIdentifiers(KfinanceTool):
     def _run(self, identifiers: list[str]) -> dict[str, str]:
         """Sample response:
 
-        {"SPGI": "78409V104"}
+        {
+            'results': {'SPGI': '78409V104'},
+            'errors': ['Kensho is a private company without a security_id.']
+        }
         """
         api_client = self.kfinance_client.kfinance_api_client
-        parsed_identifiers = parse_identifiers(identifiers=identifiers, api_client=api_client)
-        identifiers_to_security_ids = fetch_security_ids_from_identifiers(
-            identifiers=parsed_identifiers, api_client=api_client
-        )
+        id_triple_resp = api_client.unified_fetch_id_triples(identifiers=identifiers)
+        id_triple_resp.filter_out_companies_without_security_ids()
 
         tasks = [
             Task(
                 func=api_client.fetch_cusip,
-                kwargs=dict(security_id=security_id),
+                kwargs=dict(security_id=id_triple.security_id),
                 result_key=identifier,
             )
-            for identifier, security_id in identifiers_to_security_ids.items()
+            for identifier, id_triple in id_triple_resp.identifiers_to_id_triples.items()
         ]
 
         cusip_responses = process_tasks_in_thread_pool_executor(api_client=api_client, tasks=tasks)
-
-        return {str(identifier): resp["cusip"] for identifier, resp in cusip_responses.items()}
-
-
-class GetIsinFromIdentifiersArgs(BaseModel):
-    security_ids: list[int]
+        resp_model = 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):
@@ -58,23 +64,29 @@ class GetIsinFromIdentifiers(KfinanceTool):
     def _run(self, identifiers: list[str]) -> dict:
         """Sample response:
 
-        {"SPGI": "US78409V1044"}
+        {
+            'results': {'SPGI': 'US78409V104'},
+            'errors': ['Kensho is a private company without a security_id.']
+        }
         """
         api_client = self.kfinance_client.kfinance_api_client
-        parsed_identifiers = parse_identifiers(identifiers=identifiers, api_client=api_client)
-        identifiers_to_security_ids = fetch_security_ids_from_identifiers(
-            identifiers=parsed_identifiers, api_client=api_client
-        )
+        id_triple_resp = api_client.unified_fetch_id_triples(identifiers=identifiers)
+        id_triple_resp.filter_out_companies_without_security_ids()
 
         tasks = [
             Task(
                 func=api_client.fetch_isin,
-                kwargs=dict(security_id=security_id),
+                kwargs=dict(security_id=id_triple.security_id),
                 result_key=identifier,
             )
-            for identifier, security_id in identifiers_to_security_ids.items()
+            for identifier, id_triple in id_triple_resp.identifiers_to_id_triples.items()
         ]
 
         isin_responses = process_tasks_in_thread_pool_executor(api_client=api_client, tasks=tasks)
-
-        return {str(identifier): resp["isin"] for identifier, resp in isin_responses.items()}
+        resp_model = 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

@@ -1,7 +1,7 @@
 from requests_mock import Mocker
 
 from kfinance.client.kfinance import Client
-from kfinance.domains.companies.company_models import COMPANY_ID_PREFIX
+from kfinance.conftest import SPGI_SECURITY_ID
 from kfinance.domains.cusip_and_isin.cusip_and_isin_tools import (
     GetCusipFromIdentifiers,
     GetIsinFromIdentifiers,
@@ -13,45 +13,46 @@ class TestGetCusipFromIdentifiers:
     def test_get_cusip_from_identifiers(self, requests_mock: Mocker, mock_client: Client):
         """
         GIVEN the GetCusipFromIdentifiers tool
-        WHEN we request the CUSIPs for multiple companies
-        THEN we get back the corresponding CUSIPs
+        WHEN we request the CUSIPs for SPGI including a private one
+        THEN we get back the CUSIP of SPGI and an error for the private company
         """
 
-        company_ids = [1, 2]
-        expected_response = {"C_1": "CU1", "C_2": "CU2"}
-        for security_id in company_ids:
-            requests_mock.get(
-                url=f"https://kfinance.kensho.com/api/v1/cusip/{security_id}",
-                json={"cusip": f"CU{security_id}"},
-            )
+        spgi_cusip = "78409V104"
+        expected_response = {
+            "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},
+        )
         tool = GetCusipFromIdentifiers(kfinance_client=mock_client)
         resp = tool.run(
-            ToolArgsWithIdentifiers(
-                identifiers=[f"{COMPANY_ID_PREFIX}{company_id}" for company_id in company_ids]
-            ).model_dump(mode="json")
+            ToolArgsWithIdentifiers(identifiers=["SPGI", "private_company"]).model_dump(mode="json")
         )
         assert resp == expected_response
 
 
-class TestGetIsinFromSecurityIds:
+class TestGetIsinFromIdentifiers:
     def test_get_isin_from_security_ids(self, requests_mock: Mocker, mock_client: Client):
         """
         GIVEN the GetIsinFromSecurityIds tool
-        WHEN we request the ISINs for multiple security ids
-        THEN we get back the corresponding ISINs
+        WHEN we request the ISINs for SPGI including a private one
+        THEN we get back the ISIN of SPGI and an error for the private company
         """
 
-        company_ids = [1, 2]
-        expected_response = {"C_1": "IS1", "C_2": "IS2"}
-        for security_id in company_ids:
-            requests_mock.get(
-                url=f"https://kfinance.kensho.com/api/v1/isin/{security_id}",
-                json={"isin": f"IS{security_id}"},
-            )
+        spgi_isin = "US78409V1044"
+
+        expected_response = {
+            "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},
+        )
         tool = GetIsinFromIdentifiers(kfinance_client=mock_client)
         resp = tool.run(
-            ToolArgsWithIdentifiers(
-                identifiers=[f"{COMPANY_ID_PREFIX}{company_id}" for company_id in company_ids]
-            ).model_dump(mode="json")
+            ToolArgsWithIdentifiers(identifiers=["SPGI", "private_company"]).model_dump(mode="json")
         )
         assert resp == expected_response

kfinance/domains/earnings/earning_tools.py

@@ -6,18 +6,22 @@ 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.domains.earnings.earning_models import EarningsCall, EarningsCallResp
 from kfinance.integrations.tool_calling.tool_calling_models import (
     KfinanceTool,
     ToolArgsWithIdentifiers,
+    ToolRespWithErrors,
 )
 
 
+class GetEarningsFromIdentifiersResp(ToolRespWithErrors):
+    results: dict[str, EarningsCallResp]
+
+
+class GetNextOrLatestEarningsFromIdentifiersResp(ToolRespWithErrors):
+    results: dict[str, EarningsCall]
+
+
 class GetEarningsFromIdentifiers(KfinanceTool):
     name: str = "get_earnings_from_identifiers"
     description: str = dedent("""
@@ -35,23 +39,23 @@ class GetEarningsFromIdentifiers(KfinanceTool):
         """Sample response:
 
         {
-            'SPGI': [
-                {
-                    'datetime': '2025-04-29T12:30:00Z',
-                    'key_dev_id': 12346,
-                    'name': 'SPGI Q1 2025 Earnings Call'
-                }
-            ]
+            "results": {
+                'SPGI': [
+                    {
+                        'datetime': '2025-04-29T12:30:00Z',
+                        'key_dev_id': 12346,
+                        'name': 'SPGI Q1 2025 Earnings Call'
+                    }
+                ]
+            },
+            "errors": ['No identification triple found for the provided identifier: NON-EXISTENT of type: ticker']
         }
 
         """
         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()
-        }
+        return earnings_responses.model_dump(mode="json")
 
 
 class GetLatestEarningsFromIdentifiers(KfinanceTool):
@@ -71,26 +75,27 @@ class GetLatestEarningsFromIdentifiers(KfinanceTool):
         """Sample response:
 
         {
-            'JPM': {
-                'datetime': '2025-04-29T12:30:00Z',
-                'key_dev_id': 12346,
-                'name': 'SPGI Q1 2025 Earnings Call'
+            "results": {
+                'JPM': {
+                    'datetime': '2025-04-29T12:30:00Z',
+                    'key_dev_id': 12346,
+                    'name': 'SPGI Q1 2025 Earnings Call'
+                },
             },
-            'SPGI': 'No latest earnings available.'
+            "errors": ["No latest earnings available for Kensho."]
         }
         """
         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():
+        output_model = GetNextOrLatestEarningsFromIdentifiersResp(results=dict(), errors=list())
+        for identifier, earnings in earnings_responses.results.items():
             most_recent_earnings = earnings.most_recent_earnings
             if most_recent_earnings:
-                identifier_output: str | dict = most_recent_earnings.model_dump(mode="json")
+                output_model.results[identifier] = most_recent_earnings
             else:
-                identifier_output = f"No latest earnings available."
-            output[str(identifier)] = identifier_output
-        return output
+                output_model.errors.append(f"No latest earnings available for {identifier}.")
+        return output_model.model_dump(mode="json")
 
 
 class GetNextEarningsFromIdentifiers(KfinanceTool):
@@ -110,51 +115,53 @@ class GetNextEarningsFromIdentifiers(KfinanceTool):
         """Sample response:
 
         {
-            'JPM': {
-                'datetime': '2025-04-29T12:30:00Z',
-                'key_dev_id': 12346,
-                'name': 'SPGI Q1 2025 Earnings Call'
+            "results": {
+                'JPM': {
+                    'datetime': '2025-04-29T12:30:00Z',
+                    'key_dev_id': 12346,
+                    'name': 'SPGI Q1 2025 Earnings Call'
+                },
             },
-            'SPGI': 'No next earnings available.'
+            "errors": ["No next earnings available for Kensho."]
         }
         """
         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():
+        output_model = GetNextOrLatestEarningsFromIdentifiersResp(results=dict(), errors=list())
+        for identifier, earnings in earnings_responses.results.items():
             next_earnings = earnings.next_earnings
             if next_earnings:
-                identifier_output: str | dict = next_earnings.model_dump(mode="json")
+                output_model.results[identifier] = next_earnings
             else:
-                identifier_output = f"No next earnings available."
-            output[str(identifier)] = identifier_output
-        return output
+                output_model.errors.append(f"No next earnings available for {identifier}.")
+        return output_model.model_dump(mode="json")
 
 
 def get_earnings_from_identifiers(
     identifiers: list[str], kfinance_api_client: KFinanceApiClient
-) -> dict[CompanyIdentifier, EarningsCallResp]:
+) -> GetEarningsFromIdentifiersResp:
     """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
-    )
+    api_client = kfinance_api_client
+    id_triple_resp = api_client.unified_fetch_id_triples(identifiers=identifiers)
 
     tasks = [
         Task(
             func=kfinance_api_client.fetch_earnings,
-            kwargs=dict(company_id=company_id),
+            kwargs=dict(company_id=id_triple.company_id),
             result_key=identifier,
         )
-        for identifier, company_id in identifiers_to_company_ids.items()
+        for identifier, id_triple in id_triple_resp.identifiers_to_id_triples.items()
     ]
 
     earnings_responses = process_tasks_in_thread_pool_executor(
         api_client=kfinance_api_client, tasks=tasks
     )
-    return earnings_responses
+    resp_model = GetEarningsFromIdentifiersResp(
+        results=earnings_responses, errors=list(id_triple_resp.errors.values())
+    )
+    return resp_model
 
 
 class GetTranscriptFromKeyDevIdArgs(BaseModel):

kfinance/domains/earnings/tests/test_earnings_tools.py

@@ -34,8 +34,8 @@ class TestGetEarnings:
     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
+        WHEN we request all earnings for SPGI and a non-existent company
+        THEN we get back all SPGI earnings and an error for the non-existent company
         """
 
         requests_mock.get(
@@ -44,22 +44,31 @@ class TestGetEarnings:
         )
 
         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",
-                },
-            ]
+            "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"
+            ],
         }
 
         tool = GetEarningsFromIdentifiers(kfinance_client=mock_client)
-        response = tool.run(ToolArgsWithIdentifiers(identifiers=["SPGI"]).model_dump(mode="json"))
+        response = tool.run(
+            ToolArgsWithIdentifiers(identifiers=["SPGI", "non-existent"]).model_dump(mode="json")
+        )
         assert response == expected_response
 
     @time_machine.travel(
@@ -72,41 +81,35 @@ class TestGetEarnings:
     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
+        WHEN we request the latest earnings for SPGI and a private company without earnings
+        THEN we get back the latest SPGI earnings and an error for the private company.
         """
 
         requests_mock.get(
             url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
             json=self.earnings_response,
         )
+        # private company without earnings
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/1",
+            json={"earnings": []},
+        )
 
         expected_response = {
-            "SPGI": {
-                "datetime": "2025-04-29T12:30:00Z",
-                "key_dev_id": 12346,
-                "name": "SPGI Q1 2025 Earnings Call",
-            }
+            "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(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": []},
+        response = tool.run(
+            ToolArgsWithIdentifiers(identifiers=["SPGI", "private_company"]).model_dump(mode="json")
         )
-        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(
@@ -119,43 +122,35 @@ class TestGetEarnings:
     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
+        WHEN we request the next earnings for SPGI and a private company
+        THEN we get back the next SPGI earnings and an error for the private company
         """
 
         requests_mock.get(
             url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
             json=self.earnings_response,
         )
+        # private company without earnings
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/1",
+            json={"earnings": []},
+        )
 
         expected_response = {
-            "SPGI": {
-                "datetime": "2025-04-29T12:30:00Z",
-                "key_dev_id": 12346,
-                "name": "SPGI Q1 2025 Earnings Call",
-            }
+            "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(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,
+        response = tool.run(
+            ToolArgsWithIdentifiers(identifiers=["SPGI", "private_company"]).model_dump(mode="json")
         )
-        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