kensho-kfinance 2.4.2__py3-none-any.whl → 2.6.1__py3-none-any.whl

kfinance/mcp.py

@@ -1,44 +1,36 @@
-from textwrap import dedent
 from typing import Literal, Optional
 
 import click
 from fastmcp import FastMCP
+from fastmcp.tools import FunctionTool
 from fastmcp.utilities.logging import get_logger
+from langchain_core.utils.function_calling import convert_to_openai_tool
 
 from kfinance.kfinance import Client
-from kfinance.tool_calling.shared_models import KfinanceTool
+from kfinance.tool_calling import KfinanceTool
 
 
 logger = get_logger(__name__)
 
 
-def build_doc_string(tool: KfinanceTool) -> str:
-    """Build a formatted documentation string for a Kfinance tool.
+def build_mcp_tool_from_kfinance_tool(kfinance_tool: KfinanceTool) -> FunctionTool:
+    """Build an MCP FunctionTool from a langchain KfinanceTool."""
 
-    This function takes a KfinanceTool object and constructs a comprehensive
-    documentation string that includes the tool's description and detailed
-    information about its arguments, including default values and descriptions.
-
-    :param tool: The Kfinance tool object containing metadata about the tool's functionality, description, and argument schema.
-    :type tool: KfinanceTool
-    :return: A formatted documentation string containing for the tool description with detailed argument information.
-    :rtype: str
-    """
-
-    description = dedent(f"""
-        {tool.description}
-
-        Args:
-    """).strip()
-
-    for arg_name, arg_field in tool.args_schema.model_fields.items():
-        default_value_description = (
-            f"Default: {arg_field.default}. " if not arg_field.is_required() else ""
-        )
-        param_description = f"\n    {arg_name}: {default_value_description}{arg_field.description}"
-        description += param_description
-
-    return description
+    return FunctionTool(
+        name=kfinance_tool.name,
+        description=kfinance_tool.description,
+        # MCP expects a JSON schema for tool params, which we
+        # can generate similar to how langchain generates openai json schemas.
+        parameters=convert_to_openai_tool(kfinance_tool)["function"]["parameters"],
+        # The langchain runner internally validates input arguments via the args_schema.
+        # When running with mcp, we need to reproduce that validation ourselves in
+        # run_without_langchain (which then calls _run).
+        # If we pass in the underlying _run method directly, mcp generates a schema from
+        # the _run type hints but bypasses our internal validation. This causes errors,
+        # for example with integer literals, which our args models allow but the
+        # mcp-internal validation disallows.
+        fn=kfinance_tool.run_without_langchain,
+    )
 
 
 @click.command()
@@ -85,13 +77,9 @@ def run_mcp(
         kfinance_client = Client()
 
     kfinance_mcp: FastMCP = FastMCP("Kfinance")
-    for tool in kfinance_client.langchain_tools:
-        logger.info("Adding %s to server", tool.name)
-        kfinance_mcp.tool(
-            name_or_fn=getattr(tool, "_run"),
-            name=tool.name,
-            description=build_doc_string(tool),
-        )
+    for langchain_tool in kfinance_client.langchain_tools:
+        logger.info("Adding %s to server", langchain_tool.name)
+        kfinance_mcp.add_tool(build_mcp_tool_from_kfinance_tool(langchain_tool))
 
     logger.info("Server starting")
     kfinance_mcp.run(transport=transport)

kfinance/meta_classes.py

@@ -1,5 +1,5 @@
+from abc import abstractmethod
 from datetime import datetime
-from functools import cached_property
 import logging
 from typing import TYPE_CHECKING, Any, Callable, Literal, Optional
 
@@ -7,13 +7,19 @@ from cachetools import LRUCache, cached
 import numpy as np
 import pandas as pd
 
-from .constants import LINE_ITEMS, BusinessRelationshipType, PeriodType, SegmentType
+from .constants import (
+    LINE_ITEMS,
+    BusinessRelationshipType,
+    CompetitorSource,
+    PeriodType,
+    SegmentType,
+)
 from .fetch import KFinanceApiClient
 from .pydantic_models import RelationshipResponse
 
 
 if TYPE_CHECKING:
-    from .kfinance import BusinessRelationships
+    from .kfinance import BusinessRelationships, Companies
 
 logger = logging.getLogger(__name__)
 
@@ -21,7 +27,8 @@ logger = logging.getLogger(__name__)
 class CompanyFunctionsMetaClass:
     kfinance_api_client: KFinanceApiClient
 
-    @cached_property
+    @property
+    @abstractmethod
     def company_id(self) -> Any:
         """Set and return the company id for the object"""
         raise NotImplementedError("child classes must implement company id property")
@@ -213,6 +220,7 @@ class CompanyFunctionsMetaClass:
             .set_index(pd.Index([line_item]))
         )
 
+    @cached(cache=LRUCache(maxsize=100))
     def relationships(self, relationship_type: BusinessRelationshipType) -> "BusinessRelationships":
         """Returns a BusinessRelationships object that includes the current and previous Companies associated with company_id and filtered by relationship_type. The function calls fetch_companies_from_business_relationship.
 
@@ -416,6 +424,24 @@ class CompanyFunctionsMetaClass:
             end_quarter=end_quarter,
         )
 
+    def competitors(
+        self, competitor_source: CompetitorSource = CompetitorSource.all
+    ) -> "Companies":
+        """Get the list of companies that are competitors of company_id, optionally filtered by the competitor_source type.
+
+        :return: The list of companies that are competitors of company_id, optionally filtered by the competitor_source type
+        :rtype: Companies
+        """
+        from .kfinance import Companies
+
+        competitors_data = self.kfinance_api_client.fetch_competitors(
+            company_id=self.company_id, competitor_source=competitor_source
+        )["companies"]
+        return Companies(
+            kfinance_api_client=self.kfinance_api_client,
+            company_ids=[company["company_id"] for company in competitors_data],
+        )
+
 
 for line_item in LINE_ITEMS:
     line_item_name = line_item["name"]
@@ -494,7 +520,7 @@ class DelegatedCompanyFunctionsMetaClass(CompanyFunctionsMetaClass):
                 delegated_function(company_function_name),
             )
 
-    @cached_property
+    @property
     def company(self) -> Any:
         """Set and return the company for the object"""
         raise NotImplementedError("child classes must implement company property")
@@ -502,8 +528,8 @@ class DelegatedCompanyFunctionsMetaClass(CompanyFunctionsMetaClass):
 
 for relationship in BusinessRelationshipType:
 
-    def _relationship_outer_wrapper(relationship_type: BusinessRelationshipType) -> cached_property:
-        """Creates a cached property for a relationship type.
+    def _relationship_outer_wrapper(relationship_type: BusinessRelationshipType) -> property:
+        """Creates a property for a relationship type.
 
         This function returns a property that retrieves the associated company's current and previous
         relationships of the specified type.
@@ -512,7 +538,7 @@ for relationship in BusinessRelationshipType:
             relationship_type (BusinessRelationshipType): The type of relationship to be wrapped.
 
         Returns:
-            property: A cached property that calls the inner wrapper to retrieve the relationship data.
+            property: A property that calls the inner wrapper to retrieve the relationship data.
         """
 
         def relationship_inner_wrapper(
@@ -533,12 +559,11 @@ for relationship in BusinessRelationshipType:
         relationship_inner_wrapper.__doc__ = doc
         relationship_inner_wrapper.__name__ = relationship
 
-        return cached_property(relationship_inner_wrapper)
+        return property(relationship_inner_wrapper)
 
-    relationship_cached_property = _relationship_outer_wrapper(relationship)
-    relationship_cached_property.__set_name__(CompanyFunctionsMetaClass, relationship)
+    relationship_property = _relationship_outer_wrapper(relationship)
     setattr(
         CompanyFunctionsMetaClass,
         relationship,
-        relationship_cached_property,
+        relationship_property,
     )

kfinance/tests/conftest.py

@@ -29,4 +29,8 @@ def mock_client(requests_mock: Mocker) -> Client:
             "company_id": SPGI_COMPANY_ID,
         },
     )
+    requests_mock.get(
+        url="https://kfinance.kensho.com/api/v1/id/MSFT",
+        json={"trading_item_id": 2630413, "security_id": 2630412, "company_id": 21835},
+    )
     return client

kfinance/tests/test_batch_requests.py

@@ -67,38 +67,6 @@ class TestTradingItem(TestCase):
             expected_id_based_result = {1001: "Mock City A", 1002: "Mock City B"}
             self.assertDictEqual(id_based_result, expected_id_based_result)
 
-    @requests_mock.Mocker()
-    def test_batch_request_cached_properties(self, m):
-        """GIVEN a kfinance group object like Companies
-        WHEN we batch request a cached property for each object in the group
-        THEN the batch request completes successfully and we get back a mapping of
-        company objects to the corresponding values."""
-
-        m.get(
-            "https://kfinance.kensho.com/api/v1/securities/1001",
-            json={"securities": [101, 102, 103]},
-        )
-        m.get(
-            "https://kfinance.kensho.com/api/v1/securities/1002",
-            json={"securities": [104, 105, 106, 107]},
-        )
-        m.get("https://kfinance.kensho.com/api/v1/securities/1005", json={"securities": [108, 109]})
-
-        companies = Companies(self.kfinance_api_client, [1001, 1002, 1005])
-        result = companies.securities
-
-        id_based_result = self.company_object_keys_as_company_id(result)
-        for k, v in id_based_result.items():
-            id_based_result[k] = set(map(lambda s: s.security_id, v))
-
-        expected_id_based_result = {
-            1001: set([101, 102, 103]),
-            1002: set([104, 105, 106, 107]),
-            1005: set([108, 109]),
-        }
-
-        self.assertDictEqual(id_based_result, expected_id_based_result)
-
     @requests_mock.Mocker()
     def test_batch_request_function(self, m):
         """GIVEN a kfinance group object like TradingItems

kfinance/tests/test_fetch.py

@@ -272,6 +272,27 @@ class TestFetchItem(TestCase):
         )
         self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
 
+    def test_fetch_mergers_for_company(self) -> None:
+        company_id = 21719
+        expected_fetch_url = f"{self.kfinance_api_client.url_base}mergers/{company_id}"
+        self.kfinance_api_client.fetch_mergers_for_company(company_id=company_id)
+        self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
+
+    def test_fetch_merger_info(self) -> None:
+        transaction_id = 554979212
+        expected_fetch_url = f"{self.kfinance_api_client.url_base}merger/info/{transaction_id}"
+        self.kfinance_api_client.fetch_merger_info(transaction_id=transaction_id)
+        self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
+
+    def test_fetch_advisors_for_company_in_merger(self) -> None:
+        transaction_id = 554979212
+        advised_company_id = 251994106
+        expected_fetch_url = f"{self.kfinance_api_client.url_base}merger/info/{transaction_id}/advisors/{advised_company_id}"
+        self.kfinance_api_client.fetch_advisors_for_company_in_merger(
+            transaction_id=transaction_id, advised_company_id=advised_company_id
+        )
+        self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
+
 
 class TestMarketCap:
     @pytest.mark.parametrize(

kfinance/tests/test_objects.py

@@ -1,3 +1,4 @@
+import copy
 from datetime import date, datetime, timezone
 from io import BytesIO
 import re
@@ -9,7 +10,19 @@ import pandas as pd
 from PIL.Image import open as image_open
 import time_machine
 
-from kfinance.kfinance import Company, Earnings, Security, Ticker, TradingItem, Transcript
+from kfinance.constants import BusinessRelationshipType
+from kfinance.kfinance import (
+    AdvisedCompany,
+    BusinessRelationships,
+    Company,
+    Earnings,
+    MergerOrAcquisition,
+    Security,
+    Ticker,
+    TradingItem,
+    Transcript,
+)
+from kfinance.pydantic_models import CompanyIdAndName, RelationshipResponse
 
 
 msft_company_id = "21835"
@@ -17,6 +30,7 @@ msft_security_id = "2630412"
 msft_isin = "US5949181045"
 msft_cusip = "594918104"
 msft_trading_item_id = "2630413"
+msft_buys_mongo = "517414"
 
 
 MOCK_TRADING_ITEM_DB = {
@@ -108,7 +122,47 @@ 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"},
+            ],
+            "buyer": [
+                {"transaction_id": 517414, "merger_title": "Closed M/A of MongoMusic, Inc."},
+                {"transaction_id": 596722, "merger_title": "Closed M/A of Digital Anvil, Inc."},
+            ],
+            "seller": [
+                {"transaction_id": 455551, "merger_title": "Closed M/A of VacationSpot.com, Inc."},
+                {"transaction_id": 456045, "merger_title": "Closed M/A of TransPoint, LLC"},
+            ],
+        },
+        "advisors": {
+            msft_buys_mongo: {
+                "advisors": [
+                    {
+                        "advisor_company_id": 251994106,
+                        "advisor_company_name": "Kensho Technologies, Inc.",
+                        "advisor_type_name": "Professional Mongo Enjoyer",
+                    }
+                ]
+            }
+        },
+        BusinessRelationshipType.supplier: RelationshipResponse(
+            current=[CompanyIdAndName(company_name="foo", company_id=883103)],
+            previous=[
+                CompanyIdAndName(company_name="bar", company_id=472898),
+                CompanyIdAndName(company_name="baz", company_id=8182358),
+            ],
+        ),
+    },
+    31696: {"info": {"name": "MongoMusic, Inc."}},
+    21835: {"info": {"name": "Microsoft Corporation"}},
+    18805: {"info": {"name": "Angel Investors L.P."}},
+    20087: {"info": {"name": "Draper Richards, L.P."}},
+    22103: {"info": {"name": "BRV Partners, LLC"}},
+    23745: {"info": {"name": "Venture Frogs, LLC"}},
+    105902: {"info": {"name": "ARGUS Capital International Limited"}},
+    880300: {"info": {"name": "Sony Music Entertainment, Inc."}},
 }
 
 MOCK_TRANSCRIPT_DB = {
@@ -165,6 +219,51 @@ MOCK_CUSIP_DB = {
     }
 }
 
+MOCK_MERGERS_DB = {
+    msft_buys_mongo: {
+        "timeline": [
+            {"status": "Announced", "date": "2000-09-12"},
+            {"status": "Closed", "date": "2000-09-12"},
+        ],
+        "participants": {
+            "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."},
+                {"company_id": 22103, "company_name": "BRV Partners, LLC"},
+                {"company_id": 23745, "company_name": "Venture Frogs, LLC"},
+                {"company_id": 105902, "company_name": "ARGUS Capital International Limited"},
+                {"company_id": 880300, "company_name": "Sony Music Entertainment, Inc."},
+            ],
+        },
+        "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",
+                }
+            ],
+        },
+    }
+}
+
+
+def ordered(obj):
+    if isinstance(obj, dict):
+        return sorted((k, ordered(v)) for k, v in obj.items())
+    if isinstance(obj, list):
+        return sorted(ordered(x) for x in obj)
+    else:
+        return obj
+
 
 class MockKFinanceApiClient:
     def __init__(self):
@@ -261,6 +360,11 @@ class MockKFinanceApiClient:
         """Get a segment"""
         return MOCK_COMPANY_DB[company_id]
 
+    def fetch_companies_from_business_relationship(
+        self, company_id: int, relationship_type: BusinessRelationshipType
+    ) -> RelationshipResponse:
+        return MOCK_COMPANY_DB[company_id][relationship_type]
+
     def fetch_earnings(self, company_id: int) -> dict:
         """Get the earnings for a company."""
         return MOCK_COMPANY_DB[company_id]["earnings"]
@@ -269,6 +373,15 @@ class MockKFinanceApiClient:
         """Get the transcript for an earnings item."""
         return MOCK_TRANSCRIPT_DB[key_dev_id]
 
+    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_advisors_for_company_in_merger(self, transaction_id, advised_company_id):
+        return copy.deepcopy(MOCK_COMPANY_DB[advised_company_id]["advisors"][transaction_id])
+
 
 class TestTradingItem(TestCase):
     def setUp(self):
@@ -327,7 +440,9 @@ class TestCompany(TestCase):
     def setUp(self):
         """setup tests"""
         self.kfinance_api_client = MockKFinanceApiClient()
-        self.msft_company = Company(self.kfinance_api_client, msft_company_id)
+        self.msft_company = AdvisedCompany(
+            self.kfinance_api_client, company_id=msft_company_id, transaction_id=msft_buys_mongo
+        )
 
     def test_company_id(self) -> None:
         """test company id"""
@@ -396,6 +511,67 @@ class TestCompany(TestCase):
         business_segment = self.msft_company.business_segments()
         self.assertEqual(expected_segments, business_segment)
 
+    def test_relationships(self) -> None:
+        """
+        WHEN we fetch the relationships of a company
+        THEN we get back a BusinessRelationships object.
+        """
+
+        expected_suppliers = MOCK_COMPANY_DB[msft_company_id][BusinessRelationshipType.supplier]
+
+        suppliers_via_method = self.msft_company.relationships(BusinessRelationshipType.supplier)
+        self.assertIsInstance(suppliers_via_method, BusinessRelationships)
+        # Company ids should match
+        self.assertEqual(
+            sorted([c.company_id for c in suppliers_via_method.current]),
+            sorted([c.company_id for c in expected_suppliers.current]),
+        )
+        self.assertEqual(
+            sorted([c.company_id for c in suppliers_via_method.previous]),
+            sorted([c.company_id for c in expected_suppliers.previous]),
+        )
+
+        # Fetching via property should return the same result
+        suppliers_via_property = self.msft_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_json = {
+            "target": [
+                {"transaction_id": merger.transaction_id, "merger_title": merger.merger_title}
+                for merger in mergers["target"]
+            ],
+            "buyer": [
+                {"transaction_id": merger.transaction_id, "merger_title": merger.merger_title}
+                for merger in mergers["buyer"]
+            ],
+            "seller": [
+                {"transaction_id": merger.transaction_id, "merger_title": merger.merger_title}
+                for merger in mergers["seller"]
+            ],
+        }
+        self.assertEqual(ordered(expected_mergers), ordered(mergers_json))
+
+    def test_advisors(self) -> None:
+        expected_advisors_json = MOCK_COMPANY_DB[msft_company_id]["advisors"][msft_buys_mongo][
+            "advisors"
+        ]
+        expected_company_ids: list[int] = []
+        expected_advisor_type_names: list[str] = []
+        for advisor in expected_advisors_json:
+            expected_company_ids.append(int(advisor["advisor_company_id"]))
+            expected_advisor_type_names.append(str(advisor["advisor_type_name"]))
+        advisors = self.msft_company.advisors
+        company_ids: list[int] = []
+        advisor_type_names: list[str] = []
+        for advisor in advisors:
+            company_ids.append(advisor.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)
+
 
 class TestSecurity(TestCase):
     def setUp(self):
@@ -782,3 +958,63 @@ class TestCompanyEarnings(TestCase):
         """test company next_earnings property"""
         next_earnings = self.msft_company.next_earnings
         self.assertEqual(next_earnings.key_dev_id, 1916266380)
+
+
+class TestMerger(TestCase):
+    def setUp(self):
+        self.kfinance_api_client = MockKFinanceApiClient()
+        self.merger = MergerOrAcquisition(
+            self.kfinance_api_client,
+            transaction_id=msft_buys_mongo,
+            merger_title="Closed M/A of MongoMusic, Inc.",
+        )
+
+    def test_merger_info(self) -> None:
+        expected_merger_info = MOCK_MERGERS_DB[msft_buys_mongo]
+        merger_info = {
+            "timeline": [
+                {"status": timeline["status"], "date": timeline["date"].strftime("%Y-%m-%d")}
+                for timeline in self.merger.get_timeline.to_dict(orient="records")
+            ],
+            "participants": {
+                "target": {
+                    "company_id": self.merger.get_participants["target"].company_id,
+                    "company_name": self.merger.get_participants["target"].name,
+                },
+                "buyers": [
+                    {"company_id": company.company_id, "company_name": company.name}
+                    for company in self.merger.get_participants["buyers"]
+                ],
+                "sellers": [
+                    {"company_id": company.company_id, "company_name": company.name}
+                    for company in self.merger.get_participants["sellers"]
+                ],
+            },
+            "consideration": {
+                "currency_name": self.merger.get_consideration["currency_name"],
+                "current_calculated_gross_total_transaction_value": self.merger.get_consideration[
+                    "current_calculated_gross_total_transaction_value"
+                ],
+                "current_calculated_implied_equity_value": self.merger.get_consideration[
+                    "current_calculated_implied_equity_value"
+                ],
+                "current_calculated_implied_enterprise_value": self.merger.get_consideration[
+                    "current_calculated_implied_enterprise_value"
+                ],
+                "details": [
+                    {
+                        "scenario": detail["scenario"],
+                        "subtype": detail["subtype"],
+                        "cash_or_cash_equivalent_per_target_share_unit": detail[
+                            "cash_or_cash_equivalent_per_target_share_unit"
+                        ],
+                        "number_of_target_shares_sought": detail["number_of_target_shares_sought"],
+                        "current_calculated_gross_value_of_consideration": detail[
+                            "current_calculated_gross_value_of_consideration"
+                        ],
+                    }
+                    for detail in self.merger.get_consideration["details"].to_dict(orient="records")
+                ],
+            },
+        }
+        self.assertEqual(ordered(expected_merger_info), ordered(merger_info))