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

kfinance/{tests → client/tests}/test_group_objects.py

@@ -1,6 +1,6 @@
 from unittest.mock import Mock
 
-from kfinance.kfinance import Client, IdentificationTriple, Tickers
+from kfinance.client.kfinance import Client, IdentificationTriple, Tickers
 
 
 class TestTickers:

kfinance/{tests → client/tests}/test_objects.py

@@ -10,20 +10,24 @@ import pandas as pd
 from PIL.Image import open as image_open
 import time_machine
 
-from kfinance.kfinance import (
-    AdvisedCompany,
+from kfinance.client.kfinance import (
     BusinessRelationships,
     Company,
     Earnings,
     MergerOrAcquisition,
+    ParticipantInMerger,
     Security,
     Ticker,
     TradingItem,
     Transcript,
 )
-from kfinance.models.business_relationship_models import BusinessRelationshipType
-from kfinance.models.capitalization_models import Capitalizations
-from kfinance.pydantic_models import CompanyIdAndName, RelationshipResponse
+from kfinance.domains.business_relationships.business_relationship_models import (
+    BusinessRelationshipType,
+    RelationshipResponse,
+)
+from kfinance.domains.capitalizations.capitalization_models import Capitalizations
+from kfinance.domains.companies.company_models import CompanyIdAndName
+from kfinance.domains.earnings.earning_models import EarningsCallResp
 
 
 msft_company_id = "21835"
@@ -70,25 +74,27 @@ MOCK_COMPANY_DB = {
             "iso_country": "USA",
         },
         "earnings_call_dates": {"earnings": ["2004-07-22T21:30:00"]},
-        "earnings": {
-            "earnings": [
-                {
-                    "name": "Microsoft Corporation, Q4 2024 Earnings Call, Jul 25, 2024",
-                    "key_dev_id": 1916266380,
-                    "datetime": "2024-07-25T21:30:00",
-                },
-                {
-                    "name": "Microsoft Corporation, Q1 2025 Earnings Call, Oct 24, 2024",
-                    "keydevid": 1916266381,
-                    "datetime": "2024-10-24T21:30:00",
-                },
-                {
-                    "name": "Microsoft Corporation, Q2 2025 Earnings Call, Jan 25, 2025",
-                    "keydevid": 1916266382,
-                    "datetime": "2025-01-25T21:30:00",
-                },
-            ]
-        },
+        "earnings": EarningsCallResp.model_validate(
+            {
+                "earnings": [
+                    {
+                        "name": "Microsoft Corporation, Q4 2024 Earnings Call, Jul 25, 2024",
+                        "key_dev_id": 1916266380,
+                        "datetime": "2024-07-25T21:30:00Z",
+                    },
+                    {
+                        "name": "Microsoft Corporation, Q1 2025 Earnings Call, Oct 24, 2024",
+                        "key_dev_id": 1916266381,
+                        "datetime": "2024-10-24T21:30:00Z",
+                    },
+                    {
+                        "name": "Microsoft Corporation, Q2 2025 Earnings Call, Jan 25, 2025",
+                        "key_dev_id": 1916266382,
+                        "datetime": "2025-01-25T21:30:00Z",
+                    },
+                ]
+            }
+        ),
         "statements": {
             "income_statement": {
                 "statements": {
@@ -125,16 +131,40 @@ MOCK_COMPANY_DB = {
         },
         "mergers": {
             "target": [
-                {"transaction_id": 10998717, "merger_title": "Closed M/A of Microsoft Corporation"},
-                {"transaction_id": 28237969, "merger_title": "Closed M/A of Microsoft Corporation"},
+                {
+                    "transaction_id": 10998717,
+                    "merger_title": "Closed M/A of Microsoft Corporation",
+                    "closed_date": "2021-01-01",
+                },
+                {
+                    "transaction_id": 28237969,
+                    "merger_title": "Closed M/A of Microsoft Corporation",
+                    "closed_date": "2022-01-01",
+                },
             ],
             "buyer": [
-                {"transaction_id": 517414, "merger_title": "Closed M/A of MongoMusic, Inc."},
-                {"transaction_id": 596722, "merger_title": "Closed M/A of Digital Anvil, Inc."},
+                {
+                    "transaction_id": 517414,
+                    "merger_title": "Closed M/A of MongoMusic, Inc.",
+                    "closed_date": "2023-01-01",
+                },
+                {
+                    "transaction_id": 596722,
+                    "merger_title": "Closed M/A of Digital Anvil, Inc.",
+                    "closed_date": "2023-01-01",
+                },
             ],
             "seller": [
-                {"transaction_id": 455551, "merger_title": "Closed M/A of VacationSpot.com, Inc."},
-                {"transaction_id": 456045, "merger_title": "Closed M/A of TransPoint, LLC"},
+                {
+                    "transaction_id": 455551,
+                    "merger_title": "Closed M/A of VacationSpot.com, Inc.",
+                    "closed_date": "2024-01-01",
+                },
+                {
+                    "transaction_id": 456045,
+                    "merger_title": "Closed M/A of TransPoint, LLC",
+                    "closed_date": "2025-01-01",
+                },
             ],
         },
         "advisors": {
@@ -380,8 +410,8 @@ class MockKFinanceApiClient:
     def fetch_mergers_for_company(self, company_id):
         return copy.deepcopy(MOCK_COMPANY_DB[company_id]["mergers"])
 
-    def fetch_merger_info(self, transaction_id):
-        return copy.deepcopy(MOCK_MERGERS_DB[transaction_id])
+    def fetch_merger_info(self, transaction_id: int):
+        return copy.deepcopy(MOCK_MERGERS_DB[str(transaction_id)])
 
     def fetch_advisors_for_company_in_merger(self, transaction_id, advised_company_id):
         return copy.deepcopy(MOCK_COMPANY_DB[advised_company_id]["advisors"][transaction_id])
@@ -444,26 +474,31 @@ class TestCompany(TestCase):
     def setUp(self):
         """setup tests"""
         self.kfinance_api_client = MockKFinanceApiClient()
-        self.msft_company = AdvisedCompany(
-            self.kfinance_api_client, company_id=msft_company_id, transaction_id=msft_buys_mongo
+        self.msft_company = ParticipantInMerger(
+            kfinance_api_client=self.kfinance_api_client,
+            transaction_id=msft_buys_mongo,
+            company=Company(
+                kfinance_api_client=self.kfinance_api_client,
+                company_id=msft_company_id,
+            ),
         )
 
     def test_company_id(self) -> None:
         """test company id"""
         expected_company_id = msft_company_id
-        company_id = self.msft_company.company_id
+        company_id = self.msft_company.company.company_id
         self.assertEqual(expected_company_id, company_id)
 
     def test_info(self) -> None:
         """test info"""
         expected_info = MOCK_COMPANY_DB[msft_company_id]["info"]
-        info = self.msft_company.info
+        info = self.msft_company.company.info
         self.assertEqual(expected_info, info)
 
     def test_name(self) -> None:
         """test name"""
         expected_name = MOCK_COMPANY_DB[msft_company_id]["info"]["name"]
-        name = self.msft_company.name
+        name = self.msft_company.company.name
         self.assertEqual(expected_name, name)
 
     def test_founding_date(self) -> None:
@@ -471,7 +506,7 @@ class TestCompany(TestCase):
         expected_founding_date = datetime.strptime(
             MOCK_COMPANY_DB[msft_company_id]["info"]["founding_date"], "%Y-%m-%d"
         ).date()
-        founding_date = self.msft_company.founding_date
+        founding_date = self.msft_company.company.founding_date
         self.assertEqual(expected_founding_date, founding_date)
 
     def test_earnings_call_datetimes(self) -> None:
@@ -481,7 +516,7 @@ class TestCompany(TestCase):
                 MOCK_COMPANY_DB[msft_company_id]["earnings_call_dates"]["earnings"][0]
             ).replace(tzinfo=timezone.utc)
         ]
-        earnings_call_datetimes = self.msft_company.earnings_call_datetimes
+        earnings_call_datetimes = self.msft_company.company.earnings_call_datetimes
         self.assertEqual(expected_earnings_call_datetimes, earnings_call_datetimes)
 
     def test_income_statement(self) -> None:
@@ -493,7 +528,7 @@ class TestCompany(TestCase):
             .apply(pd.to_numeric)
             .replace(np.nan, None)
         )
-        income_statement = self.msft_company.income_statement()
+        income_statement = self.msft_company.company.income_statement()
         pd.testing.assert_frame_equal(expected_income_statement, income_statement)
 
     def test_revenue(self) -> None:
@@ -505,14 +540,14 @@ class TestCompany(TestCase):
             .replace(np.nan, None)
             .set_index(pd.Index(["revenue"]))
         )
-        revenue = self.msft_company.revenue()
+        revenue = self.msft_company.company.revenue()
         pd.testing.assert_frame_equal(expected_revenue, revenue)
 
     def test_business_segments(self) -> None:
         """test business statement"""
         expected_segments = MOCK_COMPANY_DB[msft_company_id]["segments"]
 
-        business_segment = self.msft_company.business_segments()
+        business_segment = self.msft_company.company.business_segments()
         self.assertEqual(expected_segments, business_segment)
 
     def test_relationships(self) -> None:
@@ -523,7 +558,9 @@ class TestCompany(TestCase):
 
         expected_suppliers = MOCK_COMPANY_DB[msft_company_id][BusinessRelationshipType.supplier]
 
-        suppliers_via_method = self.msft_company.relationships(BusinessRelationshipType.supplier)
+        suppliers_via_method = self.msft_company.company.relationships(
+            BusinessRelationshipType.supplier
+        )
         self.assertIsInstance(suppliers_via_method, BusinessRelationships)
         # Company ids should match
         self.assertEqual(
@@ -536,23 +573,35 @@ class TestCompany(TestCase):
         )
 
         # Fetching via property should return the same result
-        suppliers_via_property = self.msft_company.supplier
+        suppliers_via_property = self.msft_company.company.supplier
         self.assertEqual(suppliers_via_property, suppliers_via_method)
 
     def test_mergers(self) -> None:
         expected_mergers = MOCK_COMPANY_DB[msft_company_id]["mergers"]
-        mergers = self.msft_company.mergers_and_acquisitions
+        mergers = self.msft_company.company.mergers_and_acquisitions
         mergers_json = {
             "target": [
-                {"transaction_id": merger.transaction_id, "merger_title": merger.merger_title}
+                {
+                    "transaction_id": merger.transaction_id,
+                    "merger_title": merger.merger_title,
+                    "closed_date": merger.closed_date,
+                }
                 for merger in mergers["target"]
             ],
             "buyer": [
-                {"transaction_id": merger.transaction_id, "merger_title": merger.merger_title}
+                {
+                    "transaction_id": merger.transaction_id,
+                    "merger_title": merger.merger_title,
+                    "closed_date": merger.closed_date,
+                }
                 for merger in mergers["buyer"]
             ],
             "seller": [
-                {"transaction_id": merger.transaction_id, "merger_title": merger.merger_title}
+                {
+                    "transaction_id": merger.transaction_id,
+                    "merger_title": merger.merger_title,
+                    "closed_date": merger.closed_date,
+                }
                 for merger in mergers["seller"]
             ],
         }
@@ -571,7 +620,7 @@ class TestCompany(TestCase):
         company_ids: list[int] = []
         advisor_type_names: list[str] = []
         for advisor in advisors:
-            company_ids.append(advisor.company_id)
+            company_ids.append(advisor.company.company_id)
             advisor_type_names.append(advisor.advisor_type_name)
         self.assertListEqual(expected_company_ids, company_ids)
         self.assertListEqual(expected_advisor_type_names, advisor_type_names)
@@ -847,12 +896,10 @@ class TestTicker(TestCase):
         THEN the Ticker object can correctly extract market caps from the dict.
         """
 
-        expected_response = {
-            "market_cap": [
-                {"2025-01-01": {"unit": "USD", "value": "3133802247084.00"}},
-                {"2025-01-02": {"unit": "USD", "value": "3112092395218.00"}},
-            ]
-        }
+        expected_response = [
+            {"date": "2025-01-01", "market_cap": {"unit": "USD", "value": "3133802247084.00"}},
+            {"date": "2025-01-02", "market_cap": {"unit": "USD", "value": "3112092395218.00"}},
+        ]
         market_caps = self.msft_ticker_from_ticker.market_cap()
         assert market_caps == expected_response
 
@@ -970,9 +1017,10 @@ class TestMerger(TestCase):
     def setUp(self):
         self.kfinance_api_client = MockKFinanceApiClient()
         self.merger = MergerOrAcquisition(
-            self.kfinance_api_client,
-            transaction_id=msft_buys_mongo,
+            kfinance_api_client=self.kfinance_api_client,
+            transaction_id=int(msft_buys_mongo),
             merger_title="Closed M/A of MongoMusic, Inc.",
+            closed_date=date(2021, 1, 1),
         )
 
     def test_merger_info(self) -> None:
@@ -984,16 +1032,16 @@ class TestMerger(TestCase):
             ],
             "participants": {
                 "target": {
-                    "company_id": self.merger.get_participants["target"].company_id,
-                    "company_name": self.merger.get_participants["target"].name,
+                    "company_id": self.merger.get_participants["target"].company.company_id,
+                    "company_name": self.merger.get_participants["target"].company.name,
                 },
                 "buyers": [
-                    {"company_id": company.company_id, "company_name": company.name}
-                    for company in self.merger.get_participants["buyers"]
+                    {"company_id": buyer.company.company_id, "company_name": buyer.company.name}
+                    for buyer in self.merger.get_participants["buyers"]
                 ],
                 "sellers": [
-                    {"company_id": company.company_id, "company_name": company.name}
-                    for company in self.merger.get_participants["sellers"]
+                    {"company_id": seller.company.company_id, "company_name": seller.company.name}
+                    for seller in self.merger.get_participants["sellers"]
                 ],
             },
             "consideration": {

kfinance/{tests/conftest.py → conftest.py}

@@ -3,7 +3,7 @@ from datetime import datetime
 import pytest
 from requests_mock import Mocker
 
-from kfinance.kfinance import Client
+from kfinance.client.kfinance import Client
 
 
 SPGI_COMPANY_ID = 21719
@@ -18,7 +18,7 @@ def mock_client(requests_mock: Mocker) -> Client:
     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
+    client.kfinance_api_client._access_token_expiry = int(datetime(2100, 1, 1).timestamp())  # noqa: SLF001
 
     # Create a mock for the SPGI id triple.
     requests_mock.get(
@@ -33,4 +33,16 @@ def mock_client(requests_mock: Mocker) -> Client:
         url="https://kfinance.kensho.com/api/v1/id/MSFT",
         json={"trading_item_id": 2630413, "security_id": 2630412, "company_id": 21835},
     )
+
+    # Create mock security id and trading item id for company ids 1 and 2:
+    for company_id in [1, 2]:
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/securities/{company_id}/primary",
+            json={"primary_security": company_id},
+        )
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/trading_items/{company_id}/primary",
+            json={"primary_trading_item": company_id},
+        )
+
     return client

kfinance/domains/README.md

@@ -0,0 +1,14 @@
+# Domains
+
+Domains loosely correspond to datasets and permission boundaries. 
+They are used to group together related tools and models, 
+for example all earnings related tools and models.
+
+There are no hard boundaries around what constitutes a domain. If you
+think it makes sense to group certain tools or models together, it probably does.
+
+Each domain will usually have a tools file with `KfinanceTools` and a
+models file with enums, pydantic models, data classes, or typed dicts 
+related to the domain. We may at some point also move ORM models related
+to the domain into these sub folders. Each domain should have a `tests` 
+directory for tool and model tests.

kfinance/{models → domains/business_relationships}/business_relationship_models.py

@@ -1,5 +1,8 @@
+from pydantic import BaseModel
 from strenum import StrEnum
 
+from kfinance.domains.companies.company_models import CompanyIdAndName
+
 
 class BusinessRelationshipType(StrEnum):
     """The type of business relationship"""
@@ -24,3 +27,10 @@ class BusinessRelationshipType(StrEnum):
     transfer_agent_client = "transfer_agent_client"
     vendor = "vendor"
     client_services = "client_services"
+
+
+class RelationshipResponse(BaseModel):
+    """A response from the relationship endpoint that includes both company_id and name."""
+
+    current: list[CompanyIdAndName]
+    previous: list[CompanyIdAndName]

kfinance/domains/business_relationships/business_relationship_tools.py

@@ -0,0 +1,74 @@
+from textwrap import dedent
+from typing import Type
+
+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.business_relationships.business_relationship_models import (
+    BusinessRelationshipType,
+)
+from kfinance.domains.companies.company_identifiers import (
+    fetch_company_ids_from_identifiers,
+    parse_identifiers,
+)
+from kfinance.integrations.tool_calling.tool_calling_models import (
+    KfinanceTool,
+    ToolArgsWithIdentifiers,
+)
+
+
+class GetBusinessRelationshipFromIdentifiersArgs(ToolArgsWithIdentifiers):
+    # no description because the description for enum fields comes from the enum docstring.
+    business_relationship: BusinessRelationshipType
+
+
+class GetBusinessRelationshipFromIdentifiers(KfinanceTool):
+    name: str = "get_business_relationship_from_identifiers"
+    description: str = dedent("""
+        Get the current and previous company IDs that are relationship_type for a list of identifiers.
+
+        Example:
+        Query: "What are the previous borrowers of SPGI and JPM?"
+        Function: get_business_relationship_from_identifiers(identifiers=["SPGI", "JPM"], business_relationship=BusinessRelationshipType.borrower)
+    """).strip()
+    args_schema: Type[BaseModel] = GetBusinessRelationshipFromIdentifiersArgs
+    accepted_permissions: set[Permission] | None = {Permission.RelationshipPermission}
+
+    def _run(self, identifiers: list[str], business_relationship: BusinessRelationshipType) -> dict:
+        """Sample response:
+
+        {
+            "SPGI": {
+                "current": [{"company_id": "C_883103", "company_name": "CRISIL Limited"}],
+                "previous": [
+                    {"company_id": "C_472898", "company_name": "Morgan Stanley"},
+                    {"company_id": "C_8182358", "company_name": "Eloqua, Inc."},
+                ],
+            }
+        }
+        """
+
+        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_companies_from_business_relationship,
+                kwargs=dict(
+                    company_id=company_id,
+                    relationship_type=business_relationship,
+                ),
+                result_key=identifier,
+            )
+            for identifier, company_id in identifiers_to_company_ids.items()
+        ]
+
+        relationship_responses = process_tasks_in_thread_pool_executor(
+            api_client=api_client, tasks=tasks
+        )
+
+        return {str(k): v.model_dump(mode="json") for k, v in relationship_responses.items()}

kfinance/domains/business_relationships/tests/test_business_relationship_tools.py

@@ -0,0 +1,55 @@
+from requests_mock import Mocker
+
+from kfinance.client.kfinance import Client
+from kfinance.conftest import SPGI_COMPANY_ID
+from kfinance.domains.business_relationships.business_relationship_models import (
+    BusinessRelationshipType,
+)
+from kfinance.domains.business_relationships.business_relationship_tools import (
+    GetBusinessRelationshipFromIdentifiers,
+    GetBusinessRelationshipFromIdentifiersArgs,
+)
+
+
+class TestGetBusinessRelationshipFromIdentifiers:
+    def test_get_business_relationship_from_identifiers(
+        self, requests_mock: Mocker, mock_client: Client
+    ):
+        """
+        GIVEN the GetBusinessRelationshipFromIdentifiers tool
+        WHEN we request SPGI suppliers
+        THEN we get back the SPGI suppliers
+        """
+        supplier_resp = {
+            "current": [{"company_id": 883103, "company_name": "CRISIL Limited"}],
+            "previous": [
+                {"company_id": 472898, "company_name": "Morgan Stanley"},
+                {"company_id": 8182358, "company_name": "Eloqua, Inc."},
+            ],
+        }
+        expected_result = {
+            "SPGI": {
+                "current": [{"company_id": "C_883103", "company_name": "CRISIL Limited"}],
+                "previous": [
+                    {"company_id": "C_472898", "company_name": "Morgan Stanley"},
+                    {"company_id": "C_8182358", "company_name": "Eloqua, Inc."},
+                ],
+            }
+        }
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/relationship/{SPGI_COMPANY_ID}/supplier",
+            json=supplier_resp,
+        )
+
+        tool = GetBusinessRelationshipFromIdentifiers(kfinance_client=mock_client)
+        args = GetBusinessRelationshipFromIdentifiersArgs(
+            identifiers=["SPGI"], business_relationship=BusinessRelationshipType.supplier
+        )
+        resp = tool.run(args.model_dump(mode="json"))
+
+        assert list(resp.keys()) == ["SPGI"]
+        # Sort companies by ID to make the result deterministic
+        resp["SPGI"]["current"].sort(key=lambda x: x["company_id"])
+        resp["SPGI"]["previous"].sort(key=lambda x: x["company_id"])
+        assert resp == expected_result

kfinance/{models → domains/capitalizations}/capitalization_models.py

@@ -5,7 +5,7 @@ from typing import Any
 from pydantic import BaseModel, Field, model_validator
 from strenum import StrEnum
 
-from kfinance.decimal_with_unit import Money, Shares
+from kfinance.client.models.decimal_with_unit import Money, Shares
 
 
 class Capitalization(StrEnum):
@@ -68,23 +68,30 @@ class Capitalizations(BaseModel):
                     capitalization[key] = dict(unit=currency, value=capitalization[key])
         return data
 
-    def jsonify_single_attribute(self, capitalization_to_extract: Capitalization) -> dict:
-        """Return a json representation of a single attribute like "market_cap".
+    def model_dump_json_single_metric(
+        self, capitalization_metric: Capitalization, only_include_most_recent_value: bool = False
+    ) -> dict:
+        """Dump only a single metric (market cap, tev, or shares outstanding) to json
 
-        Example response:
-        {
-            "market_cap": [
-                {'2024-06-24': {'unit': 'USD', 'value': '139231113000.00'}},
-                {'2024-06-25': {'unit': 'USD', 'value': '140423262000.00'}}
-            ]
-        }
+        If only_include_most_recent_value is set to True, only the most recent value gets included.
 
+        Sample response:
+        [
+            {
+                'date': datetime.date(2024, 4, 10),
+                'market_cap': {'value': Decimal('132766738270.00'), 'unit': 'USD'}
+            }
+        ]
         """
 
-        capitalizations = []
-        for capitalization in self.capitalizations:
-            attribute_val = getattr(capitalization, capitalization_to_extract.value)
-            capitalizations.append(
-                {capitalization.date.isoformat(): attribute_val.model_dump(mode="json")}
-            )
-        return {capitalization_to_extract: capitalizations}
+        return self.model_dump(
+            mode="json",
+            include={  # type: ignore[arg-type]
+                "capitalizations": {
+                    0 if only_include_most_recent_value else "__all__": {
+                        "date",
+                        capitalization_metric.value,
+                    }
+                }
+            },
+        )["capitalizations"]