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

kfinance/domains/mergers_and_acquisitions/merger_and_acquisition_tools.py

@@ -0,0 +1,176 @@
+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.kfinance import Company, MergerOrAcquisition, ParticipantInMerger
+from kfinance.client.permission_models import Permission
+from kfinance.domains.companies.company_identifiers import (
+    CompanyId,
+    fetch_company_ids_from_identifiers,
+    parse_identifiers,
+)
+from kfinance.integrations.tool_calling.tool_calling_models import (
+    KfinanceTool,
+    ToolArgsWithIdentifier,
+    ToolArgsWithIdentifiers,
+)
+
+
+class GetMergersFromIdentifier(KfinanceTool):
+    name: str = "get_mergers_from_identifiers"
+    description: str = dedent("""
+        Get the transaction IDs that involve the given identifiers.
+
+        For example, "Which companies did Microsoft purchase?" or "Which company bought Ben & Jerrys?"
+    """).strip()
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
+    accepted_permissions: set[Permission] | None = {Permission.MergersPermission}
+
+    def _run(self, identifiers: list[str]) -> dict:
+        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_mergers_for_company,
+                kwargs=dict(company_id=company_id),
+                result_key=identifier,
+            )
+            for identifier, company_id in identifiers_to_company_ids.items()
+        ]
+
+        merger_responses = process_tasks_in_thread_pool_executor(api_client=api_client, tasks=tasks)
+
+        return {str(identifier): mergers for identifier, mergers in merger_responses.items()}
+
+
+class GetMergerInfoFromTransactionIdArgs(BaseModel):
+    transaction_id: int | None = Field(description="The ID of the transaction.", default=None)
+
+
+class GetMergerInfoFromTransactionId(KfinanceTool):
+    name: str = "get_merger_info_from_transaction_id"
+    description: str = dedent("""
+        Get the timeline, the participants, and the consideration of the merger or acquisition from the given transaction ID.
+
+        For example, "How much was Ben & Jerrys purchased for?" or "What was the price per share for LinkedIn?" or "When did S&P purchase Kensho?"
+    """).strip()
+    args_schema: Type[BaseModel] = GetMergerInfoFromTransactionIdArgs
+    accepted_permissions: set[Permission] | None = {Permission.MergersPermission}
+
+    def _run(self, transaction_id: int) -> dict:
+        merger_or_acquisition = MergerOrAcquisition(
+            kfinance_api_client=self.kfinance_client.kfinance_api_client,
+            transaction_id=transaction_id,
+            merger_title=None,
+            closed_date=None,
+        )
+        merger_timeline = merger_or_acquisition.get_timeline
+        merger_participants = merger_or_acquisition.get_participants
+        merger_consideration = merger_or_acquisition.get_consideration
+
+        return {
+            "timeline": [
+                {"status": timeline["status"], "date": timeline["date"].strftime("%Y-%m-%d")}
+                for timeline in merger_timeline.to_dict(orient="records")
+            ]
+            if merger_timeline is not None
+            else None,
+            "participants": {
+                "target": {
+                    "company_id": str(
+                        CompanyId(
+                            company_id=merger_participants["target"].company.company_id,
+                            api_client=self.kfinance_client.kfinance_api_client,
+                        )
+                    ),
+                    "company_name": merger_participants["target"].company.name,
+                },
+                "buyers": [
+                    {
+                        "company_id": str(
+                            CompanyId(
+                                buyer.company.company_id,
+                                api_client=self.kfinance_client.kfinance_api_client,
+                            )
+                        ),
+                        "company_name": buyer.company.name,
+                    }
+                    for buyer in merger_participants["buyers"]
+                ],
+                "sellers": [
+                    {
+                        "company_id": str(
+                            CompanyId(
+                                seller.company.company_id,
+                                api_client=self.kfinance_client.kfinance_api_client,
+                            )
+                        ),
+                        "company_name": seller.company.name,
+                    }
+                    for seller in merger_participants["sellers"]
+                ],
+            }
+            if merger_participants is not None
+            else None,
+            "consideration": {
+                "currency_name": merger_consideration["currency_name"],
+                "current_calculated_gross_total_transaction_value": merger_consideration[
+                    "current_calculated_gross_total_transaction_value"
+                ],
+                "current_calculated_implied_equity_value": merger_consideration[
+                    "current_calculated_implied_equity_value"
+                ],
+                "current_calculated_implied_enterprise_value": merger_consideration[
+                    "current_calculated_implied_enterprise_value"
+                ],
+                "details": merger_consideration["details"].to_dict(orient="records"),
+            }
+            if merger_consideration is not None
+            else None,
+        }
+
+
+class GetAdvisorsForCompanyInTransactionFromIdentifierArgs(ToolArgsWithIdentifier):
+    transaction_id: int | None = Field(description="The ID of the merger.", default=None)
+
+
+class GetAdvisorsForCompanyInTransactionFromIdentifier(KfinanceTool):
+    name: str = "get_advisors_for_company_in_transaction_from_identifier"
+    description: str = 'Get the companies advising a company in a given transaction. For example, "Who advised S&P Global during their purchase of Kensho?"'
+    args_schema: Type[BaseModel] = GetAdvisorsForCompanyInTransactionFromIdentifierArgs
+    accepted_permissions: set[Permission] | None = {Permission.MergersPermission}
+
+    def _run(self, identifier: str, transaction_id: int) -> list:
+        ticker = self.kfinance_client.ticker(identifier)
+        participant_in_merger = ParticipantInMerger(
+            kfinance_api_client=ticker.kfinance_api_client,
+            transaction_id=transaction_id,
+            company=Company(
+                kfinance_api_client=ticker.kfinance_api_client,
+                company_id=ticker.company.company_id,
+            ),
+        )
+        advisors = participant_in_merger.advisors
+
+        if advisors:
+            return [
+                {
+                    "advisor_company_id": str(
+                        CompanyId(
+                            company_id=advisor.company.company_id,
+                            api_client=self.kfinance_client.kfinance_api_client,
+                        )
+                    ),
+                    "advisor_company_name": advisor.company.name,
+                    "advisor_type_name": advisor.advisor_type_name,
+                }
+                for advisor in advisors
+            ]
+        else:
+            return []

kfinance/domains/mergers_and_acquisitions/tests/test_merger_and_acquisition_tools.py

@@ -0,0 +1,124 @@
+from copy import deepcopy
+
+from requests_mock import Mocker
+
+from kfinance.client.kfinance import Client
+from kfinance.client.tests.test_objects import MOCK_COMPANY_DB, ordered
+from kfinance.domains.companies.company_models import COMPANY_ID_PREFIX
+from kfinance.domains.mergers_and_acquisitions.merger_and_acquisition_tools import (
+    GetAdvisorsForCompanyInTransactionFromIdentifier,
+    GetAdvisorsForCompanyInTransactionFromIdentifierArgs,
+    GetMergerInfoFromTransactionId,
+    GetMergerInfoFromTransactionIdArgs,
+    GetMergersFromIdentifier,
+)
+from kfinance.integrations.tool_calling.tool_calling_models import ToolArgsWithIdentifiers
+
+
+class TestGetMergersFromIdentifiers:
+    def test_get_mergers_from_identifiers(self, requests_mock: Mocker, mock_client: Client):
+        msft_mergers = MOCK_COMPANY_DB["21835"]["mergers"]
+        expected_response = {"MSFT": msft_mergers}
+        company_id = 21835
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/mergers/{company_id}", json=msft_mergers
+        )
+        tool = GetMergersFromIdentifier(kfinance_client=mock_client)
+        args = ToolArgsWithIdentifiers(identifiers=["MSFT"])
+        response = tool.run(args.model_dump(mode="json"))
+        assert ordered(response) == ordered(expected_response)
+
+
+class TestGetCompaniesAdvisingCompanyInTransactionFromIdentifier:
+    def test_get_companies_advising_company_in_transaction_from_identifier(
+        self, requests_mock: Mocker, mock_client: Client
+    ):
+        api_response = {
+            "advisors": [
+                {
+                    "advisor_company_id": 251994106,
+                    "advisor_company_name": "Kensho Technologies, Inc.",
+                    "advisor_type_name": "Professional Mongo Enjoyer",
+                }
+            ]
+        }
+        expected_response = deepcopy(api_response)
+        expected_response["advisors"][0]["advisor_company_id"] = f"{COMPANY_ID_PREFIX}251994106"
+        transaction_id = 517414
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/merger/info/{transaction_id}/advisors/21835",
+            json=api_response,
+        )
+        tool = GetAdvisorsForCompanyInTransactionFromIdentifier(kfinance_client=mock_client)
+        args = GetAdvisorsForCompanyInTransactionFromIdentifierArgs(
+            identifier="MSFT", transaction_id=transaction_id
+        )
+        response = tool.run(args.model_dump(mode="json"))
+        assert response == expected_response["advisors"]
+
+
+class TestGetMergerInfoFromTransactionId:
+    def test_get_merger_info_from_transaction_id(self, requests_mock: Mocker, mock_client: Client):
+        response_base = {
+            "timeline": [
+                {"status": "Announced", "date": "2000-09-12"},
+                {"status": "Closed", "date": "2000-09-12"},
+            ],
+            "participants": {},
+            "consideration": {
+                "currency_name": "US Dollar",
+                "current_calculated_gross_total_transaction_value": "51609375.000000",
+                "current_calculated_implied_equity_value": "51609375.000000",
+                "current_calculated_implied_enterprise_value": "51609375.000000",
+                "details": [
+                    {
+                        "scenario": "Stock Lump Sum",
+                        "subtype": "Common Equity",
+                        "cash_or_cash_equivalent_per_target_share_unit": None,
+                        "number_of_target_shares_sought": "1000000.000000",
+                        "current_calculated_gross_value_of_consideration": "51609375.000000",
+                    }
+                ],
+            },
+        }
+
+        participants_api_response = {
+            "target": {"company_id": 31696, "company_name": "MongoMusic, Inc."},
+            "buyers": [{"company_id": 21835, "company_name": "Microsoft Corporation"}],
+            "sellers": [
+                {"company_id": 18805, "company_name": "Angel Investors L.P."},
+                {"company_id": 20087, "company_name": "Draper Richards, L.P."},
+            ],
+        }
+        api_response = deepcopy(response_base)
+        api_response["participants"] = participants_api_response
+
+        # Returned company IDs should be prefixed
+        expected_participants_tool_response = {
+            "target": {
+                "company_id": f"{COMPANY_ID_PREFIX}31696",
+                "company_name": "MongoMusic, Inc.",
+            },
+            "buyers": [
+                {"company_id": f"{COMPANY_ID_PREFIX}21835", "company_name": "Microsoft Corporation"}
+            ],
+            "sellers": [
+                {"company_id": f"{COMPANY_ID_PREFIX}18805", "company_name": "Angel Investors L.P."},
+                {
+                    "company_id": f"{COMPANY_ID_PREFIX}20087",
+                    "company_name": "Draper Richards, L.P.",
+                },
+            ],
+        }
+        expected_response = deepcopy(response_base)
+        expected_response["participants"] = expected_participants_tool_response
+
+        transaction_id = 517414
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/merger/info/{transaction_id}",
+            json=api_response,
+        )
+        tool = GetMergerInfoFromTransactionId(kfinance_client=mock_client)
+        args = GetMergerInfoFromTransactionIdArgs(transaction_id=transaction_id)
+        response = tool.run(args.model_dump(mode="json"))
+        assert ordered(response) == ordered(expected_response)

kfinance/{models → domains/prices}/price_models.py

@@ -4,7 +4,7 @@ from typing import Any, TypedDict
 
 from pydantic import BaseModel, model_validator
 
-from kfinance.decimal_with_unit import Money, Shares
+from kfinance.client.models.decimal_with_unit import Money, Shares
 
 
 class HistoryMetadata(TypedDict):

kfinance/domains/prices/price_tools.py

@@ -0,0 +1,165 @@
+from datetime import date
+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.models.date_and_period_models import Periodicity
+from kfinance.client.permission_models import Permission
+from kfinance.domains.companies.company_identifiers import (
+    fetch_trading_item_ids_from_identifiers,
+    parse_identifiers,
+)
+from kfinance.integrations.tool_calling.tool_calling_models import (
+    KfinanceTool,
+    ToolArgsWithIdentifiers,
+)
+
+
+class GetPricesFromIdentifiersArgs(ToolArgsWithIdentifiers):
+    start_date: date | None = Field(
+        description="The start date for historical price retrieval", default=None
+    )
+    end_date: date | None = Field(
+        description="The end date for historical price retrieval", default=None
+    )
+    # no description because the description for enum fields comes from the enum docstring.
+    periodicity: Periodicity = Field(default=Periodicity.day)
+    adjusted: bool = Field(
+        description="Whether to retrieve adjusted prices that account for corporate actions such as dividends and splits.",
+        default=True,
+    )
+
+
+class GetPricesFromIdentifiers(KfinanceTool):
+    name: str = "get_prices_from_identifiers"
+    description: str = dedent("""
+        Get the historical open, high, low, and close prices, and volume of a group of identifiers between inclusive start_date and inclusive end date.
+
+        - When possible, pass multiple identifiers in a single call rather than making multiple calls.
+        - When requesting the most recent values, leave start_date and end_date empty.
+
+        Example:
+        Query: "What are the prices of Facebook and Google?"
+        Do:
+            get_prices_from_identifiers(identifiers=["META", "GOOGL"])
+        Don't:
+            get_prices_from_identifiers(trading_item_ids=["META"])
+            get_prices_from_identifiers(trading_item_ids=["GOOGL"])
+    """).strip()
+    args_schema: Type[BaseModel] = GetPricesFromIdentifiersArgs
+    accepted_permissions: set[Permission] | None = {Permission.PricingPermission}
+
+    def _run(
+        self,
+        identifiers: list[str],
+        start_date: date | None = None,
+        end_date: date | None = None,
+        periodicity: Periodicity = Periodicity.day,
+        adjusted: bool = True,
+    ) -> dict:
+        """Sample Response:
+
+        {
+            "SPGI": {
+                'prices': [
+                    {
+                        'date': '2024-04-11',
+                        'open': {'value': '424.26', 'unit': 'USD'},
+                        'high': {'value': '425.99', 'unit': 'USD'},
+                        'low': {'value': '422.04', 'unit': 'USD'},
+                        'close': {'value': '422.92', 'unit': 'USD'},
+                        'volume': {'value': '1129158', 'unit': 'Shares'}
+                    },
+                    {
+                        'date': '2024-04-12',
+                        'open': {'value': '419.23', 'unit': 'USD'},
+                        'high': {'value': '421.94', 'unit': 'USD'},
+                        'low': {'value': '416.45', 'unit': 'USD'},
+                        'close': {'value': '417.81', 'unit': 'USD'},
+                        'volume': {'value': '1182229', 'unit': 'Shares'}
+                    }
+                ]
+            }
+        }
+        """
+        api_client = self.kfinance_client.kfinance_api_client
+        parsed_identifiers = parse_identifiers(identifiers=identifiers, api_client=api_client)
+        identifiers_to_trading_item_ids = fetch_trading_item_ids_from_identifiers(
+            identifiers=parsed_identifiers, api_client=api_client
+        )
+
+        tasks = [
+            Task(
+                func=api_client.fetch_history,
+                kwargs=dict(
+                    trading_item_id=trading_item_id,
+                    start_date=start_date,
+                    end_date=end_date,
+                    periodicity=periodicity,
+                    is_adjusted=adjusted,
+                ),
+                result_key=identifier,
+            )
+            for identifier, trading_item_id in identifiers_to_trading_item_ids.items()
+        ]
+
+        price_responses = process_tasks_in_thread_pool_executor(api_client=api_client, tasks=tasks)
+
+        # Only include most recent price if more than one identifier passed and start_date == end_date == None
+        dump_include_filter = None
+        if len(identifiers) > 1 and start_date == end_date is None:
+            dump_include_filter = {"prices": {0: True}}
+
+        return {
+            str(identifier): prices.model_dump(mode="json", include=dump_include_filter)
+            for identifier, prices in price_responses.items()
+        }
+
+
+class GetHistoryMetadataFromIdentifiers(KfinanceTool):
+    name: str = "get_history_metadata_from_identifiers"
+    description: str = dedent("""
+        Get the history metadata associated with a list of identifiers. History metadata includes currency, symbol, exchange name, instrument type, and first trade date.
+
+        - When possible, pass multiple identifiers in a single call rather than making multiple calls.
+    """).strip()
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
+    accepted_permissions: set[Permission] | None = None
+
+    def _run(self, identifiers: list[str]) -> dict:
+        """Sample response:
+
+        {
+            'SPGI': {
+                'currency': 'USD',
+                'exchange_name': 'NYSE',
+                'first_trade_date': '1968-01-02',
+                'instrument_type': 'Equity',
+                'symbol': 'SPGI'
+            }
+        }
+        """
+        api_client = self.kfinance_client.kfinance_api_client
+        parsed_identifiers = parse_identifiers(identifiers=identifiers, api_client=api_client)
+        identifiers_to_trading_item_ids = fetch_trading_item_ids_from_identifiers(
+            identifiers=parsed_identifiers, api_client=api_client
+        )
+
+        tasks = [
+            Task(
+                func=api_client.fetch_history_metadata,
+                kwargs=dict(trading_item_id=trading_item_id),
+                result_key=identifier,
+            )
+            for identifier, trading_item_id in identifiers_to_trading_item_ids.items()
+        ]
+
+        history_metadata_responses = process_tasks_in_thread_pool_executor(
+            api_client=api_client, tasks=tasks
+        )
+
+        return {
+            str(identifier): result for identifier, result in history_metadata_responses.items()
+        }

kfinance/{tests/test_models → domains/prices/tests}/test_price_models.py

@@ -1,7 +1,7 @@
 from decimal import Decimal
 
-from kfinance.decimal_with_unit import Money, Shares
-from kfinance.models.price_models import PriceHistory, Prices
+from kfinance.client.models.decimal_with_unit import Money, Shares
+from kfinance.domains.prices.price_models import PriceHistory, Prices
 
 
 class TestPriceHistory:

kfinance/domains/prices/tests/test_price_tools.py

@@ -0,0 +1,141 @@
+from requests_mock import Mocker
+
+from kfinance.client.kfinance import Client
+from kfinance.conftest import SPGI_TRADING_ITEM_ID
+from kfinance.domains.companies.company_models import COMPANY_ID_PREFIX
+from kfinance.domains.prices.price_tools import (
+    GetHistoryMetadataFromIdentifiers,
+    GetPricesFromIdentifiers,
+    GetPricesFromIdentifiersArgs,
+)
+from kfinance.integrations.tool_calling.tool_calling_models import ToolArgsWithIdentifiers
+
+
+class TestGetHistoryMetadataFromIdentifiers:
+    def test_get_history_metadata_from_identifiers(
+        self, mock_client: Client, requests_mock: Mocker
+    ):
+        """
+        GIVEN the GetHistoryMetadataFromIdentifiers tool
+        WHEN we request the history metadata for SPGI
+        THEN we get back SPGI's history metadata
+        """
+        metadata_resp = {
+            "currency": "USD",
+            "exchange_name": "NYSE",
+            "first_trade_date": "1968-01-02",
+            "instrument_type": "Equity",
+            "symbol": "SPGI",
+        }
+        expected_resp = {"SPGI": metadata_resp}
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/pricing/{SPGI_TRADING_ITEM_ID}/metadata",
+            json=metadata_resp,
+        )
+
+        tool = GetHistoryMetadataFromIdentifiers(kfinance_client=mock_client)
+        resp = tool.run(ToolArgsWithIdentifiers(identifiers=["SPGI"]).model_dump(mode="json"))
+        assert resp == expected_resp
+
+
+class TestPricesFromIdentifiers:
+    prices_resp = {
+        "currency": "USD",
+        "prices": [
+            {
+                "date": "2024-04-11",
+                "open": "424.260000",
+                "high": "425.990000",
+                "low": "422.040000",
+                "close": "422.920000",
+                "volume": "1129158",
+            },
+            {
+                "date": "2024-04-12",
+                "open": "419.230000",
+                "high": "421.940000",
+                "low": "416.450000",
+                "close": "417.810000",
+                "volume": "1182229",
+            },
+        ],
+    }
+
+    def test_get_prices_from_identifiers(self, mock_client: Client, requests_mock: Mocker):
+        """
+        GIVEN the GetPricesFromIdentifiers tool
+        WHEN we request prices for SPGI
+        THEN we get back prices for SPGI
+        """
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/pricing/{SPGI_TRADING_ITEM_ID}/none/none/day/adjusted",
+            json=self.prices_resp,
+        )
+        expected_response = {
+            "SPGI": {
+                "prices": [
+                    {
+                        "date": "2024-04-11",
+                        "open": {"value": "424.26", "unit": "USD"},
+                        "high": {"value": "425.99", "unit": "USD"},
+                        "low": {"value": "422.04", "unit": "USD"},
+                        "close": {"value": "422.92", "unit": "USD"},
+                        "volume": {"value": "1129158", "unit": "Shares"},
+                    },
+                    {
+                        "date": "2024-04-12",
+                        "open": {"value": "419.23", "unit": "USD"},
+                        "high": {"value": "421.94", "unit": "USD"},
+                        "low": {"value": "416.45", "unit": "USD"},
+                        "close": {"value": "417.81", "unit": "USD"},
+                        "volume": {"value": "1182229", "unit": "Shares"},
+                    },
+                ]
+            }
+        }
+
+        tool = GetPricesFromIdentifiers(kfinance_client=mock_client)
+        response = tool.run(
+            GetPricesFromIdentifiersArgs(identifiers=["SPGI"]).model_dump(mode="json")
+        )
+        assert response == expected_response
+
+    def test_most_recent_request(self, requests_mock: Mocker, mock_client: Client) -> None:
+        """
+        GIVEN the GetPricesFromIdentifiers tool
+        WHEN we request most recent prices for multiple companies
+        THEN we only get back the most recent prices for each company
+        """
+
+        company_ids = [1, 2]
+        for trading_item_id in company_ids:
+            requests_mock.get(
+                url=f"https://kfinance.kensho.com/api/v1/pricing/{trading_item_id}/none/none/day/adjusted",
+                json=self.prices_resp,
+            )
+
+        expected_single_company_response = {
+            "prices": [
+                {
+                    "date": "2024-04-11",
+                    "open": {"value": "424.26", "unit": "USD"},
+                    "high": {"value": "425.99", "unit": "USD"},
+                    "low": {"value": "422.04", "unit": "USD"},
+                    "close": {"value": "422.92", "unit": "USD"},
+                    "volume": {"value": "1129158", "unit": "Shares"},
+                }
+            ]
+        }
+        expected_response = {
+            "C_1": expected_single_company_response,
+            "C_2": expected_single_company_response,
+        }
+        tool = GetPricesFromIdentifiers(kfinance_client=mock_client)
+        response = tool.run(
+            GetPricesFromIdentifiersArgs(
+                identifiers=[f"{COMPANY_ID_PREFIX}{company_id}" for company_id in company_ids]
+            ).model_dump(mode="json")
+        )
+        assert response == expected_response