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

{kensho_kfinance-3.2.3.dist-info → kensho_kfinance-3.2.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 3.2.3
+Version: 3.2.4
 Summary: Python CLI for kFinance
 Author-email: Luke Brown <luke.brown@kensho.com>, Michelle Keoy <michelle.keoy@kensho.com>, Keith Page <keith.page@kensho.com>, Matthew Rosen <matthew.rosen@kensho.com>, Nick Roshdieh <nick.roshdieh@kensho.com>
 Project-URL: source, https://github.com/kensho-technologies/kfinance

{kensho_kfinance-3.2.3.dist-info → kensho_kfinance-3.2.4.dist-info}/RECORD

@@ -1,11 +1,11 @@
-kensho_kfinance-3.2.3.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-3.2.3.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=DVWdxUssDxF0aqYQZwHmHEuG03gLFCJ4MVQU5JSbaMc,2836
+kensho_kfinance-3.2.4.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-3.2.4.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=X2CjISKbQr2oXL2f3r3X_grVSulqoOKOcaOfISxR_ls,2895
 kfinance/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-kfinance/conftest.py,sha256=O9e1ddyTfqnZ1T-9ehnkXwK8PfxPdCHAI7-fke52Ouk,3281
+kfinance/conftest.py,sha256=FIZNQyfFbldyVmzaLfWbnMGh6RiC4MZwOVax6815_Ms,3754
 kfinance/mcp.py,sha256=LTzCIlqsDKRD-0Xcpa_P99-JmJ8duAneO_-GzM43kjw,424
 kfinance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/version.py,sha256=TNj-kvOWGvYoPhrgqpaiE88yQqMnl_5-Khjy6DXZyxo,704
+kfinance/version.py,sha256=l9_iMqlxiCOGrY70L8JWiTjDNINwByOH0aKGS6QXJ4I,704
 kfinance/client/README.md,sha256=DA5vg4uz1JmJNiqvYywrj46YNhOr584WO8L83Ysx_Mk,372
 kfinance/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/client/batch_request_handling.py,sha256=opwJJAU2JtqH-s4vt8wRqhH34MiU4tQP6Ng7K6b3upA,6561
@@ -66,10 +66,10 @@ kfinance/domains/line_items/line_item_tools.py,sha256=C-E7W1cNSYRtqXp1ULAaXcxMh6
 kfinance/domains/line_items/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/domains/line_items/tests/test_line_item_tools.py,sha256=kZXbi_2oaR5cxxQk9Qj7pY0bvL7G3ch9-z9mprvxMGo,4106
 kfinance/domains/mergers_and_acquisitions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/domains/mergers_and_acquisitions/merger_and_acquisition_models.py,sha256=TLDYiR2TX-gb13px7xEYzOuYpwqRDjKCSnJFJaeAI8o,287
-kfinance/domains/mergers_and_acquisitions/merger_and_acquisition_tools.py,sha256=mSFFOODsWAh2qF5hrwjYU4Yr7pp9NtILdc_jNmgpSSM,8063
+kfinance/domains/mergers_and_acquisitions/merger_and_acquisition_models.py,sha256=hJ87rnRj14FpmeEJDmEXLdUv37pBrcpKSWtb19j_vLQ,418
+kfinance/domains/mergers_and_acquisitions/merger_and_acquisition_tools.py,sha256=8cTI5E6nAUbC45xFshIkNrICjujGo99Ane2xW8Y0IEo,9735
 kfinance/domains/mergers_and_acquisitions/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/domains/mergers_and_acquisitions/tests/test_merger_and_acquisition_tools.py,sha256=h9h8Z2fW3nZ-1f81C9gKn3GcnKvzvmvQJGjQGIqfauU,5924
+kfinance/domains/mergers_and_acquisitions/tests/test_merger_and_acquisition_tools.py,sha256=ad4vv3qevHAaLZI0t5qEUPqEKTQm-e800ybA2ID5S_o,6640
 kfinance/domains/prices/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/domains/prices/price_models.py,sha256=6K2Yi8PQKJ92rf6ulcOSh9rBVOiPcUQD_WIRjpIRuSo,2156
 kfinance/domains/prices/price_tools.py,sha256=KrcJz3GT8iQElfLp0pArVVcV-jckX_Ggj4lgO0s3wkE,7192
@@ -95,7 +95,7 @@ kfinance/integrations/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMp
 kfinance/integrations/tests/test_example_notebook.py,sha256=NrqYFn_XyOn0YlV9QYEnNMBB7LEkg70pP1eqiLGxcBE,6529
 kfinance/integrations/tool_calling/README.md,sha256=TSk-AJddoEctzc0HXQvGNac2CckbnWxHcRDtEifSe1w,2029
 kfinance/integrations/tool_calling/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/integrations/tool_calling/all_tools.py,sha256=pgPSXtFNO9pD9Y2FRk97ofIcdHHtpah4pEdipYktwxQ,2366
+kfinance/integrations/tool_calling/all_tools.py,sha256=UsmCupFumXx2J5AZU9M0fbihbZhlirzVrOQehpcgbfo,2724
 kfinance/integrations/tool_calling/prompts.py,sha256=4qeW_VLLcxutUFuXnMKa0QD-_jq9qufo03BY-Slz-XU,1718
 kfinance/integrations/tool_calling/tool_calling_models.py,sha256=o1LGGwx8ikwEiZaHEALS4rvymF9O1Mp5dO9LcfFheUI,5856
 kfinance/integrations/tool_calling/static_tools/README.md,sha256=lWQWdLY1tkGxqE8o4f61gc-RCX0doaCnZM0GmcNO6Jo,97
@@ -108,7 +108,7 @@ kfinance/integrations/tool_calling/static_tools/tests/test_get_n_quarters_ago.py
 kfinance/integrations/tool_calling/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/integrations/tool_calling/tests/test_tool_calling_models.py,sha256=Ts1pvaYjq9BTR71dMZ73X__bQ7gQynPkQjy-9x2CuyQ,2605
 kfinance/models/permission_models.py,sha256=G0so8ZOsD1YDsCM4he0z5R9M_shUbSRwD3hUDJdqZl0,635
-kensho_kfinance-3.2.3.dist-info/METADATA,sha256=xovbKJI3SJnJUr_Us2zsKJ3bUDo3rgiMHOG8zJUQrhY,6197
-kensho_kfinance-3.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kensho_kfinance-3.2.3.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-3.2.3.dist-info/RECORD,,
+kensho_kfinance-3.2.4.dist-info/METADATA,sha256=rc_-W3DvkZ-X_MtcKpQUD3I5rcf4pPVZa9BIaBvjyUE,6197
+kensho_kfinance-3.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kensho_kfinance-3.2.4.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-3.2.4.dist-info/RECORD,,

kfinance/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v3.2.4
+- Add Mergers & Acquisitions tools to ALL_TOOLS
+
 ## v3.2.3
 - Disable low level MCP SDK input validation
 

kfinance/conftest.py

@@ -52,7 +52,18 @@ def mock_client(requests_mock: Mocker) -> Client:
         additional_matcher=lambda req: req.json().get("identifiers") == ["SPGI"],
         json={"data": {"SPGI": spgi_id_triple}},
     )
-
+    # Fetch a non-existent company (which will include an error)
+    requests_mock.post(
+        url="https://kfinance.kensho.com/api/v1/ids",
+        additional_matcher=lambda req: req.json().get("identifiers") == ["non-existent"],
+        json={
+            "data": {
+                "non-existent": {
+                    "error": "No identification triple found for the provided identifier: NON-EXISTENT of type: ticker"
+                },
+            }
+        },
+    )
     # Fetch SPGI and a non-existent company (which will include an error)
     requests_mock.post(
         url="https://kfinance.kensho.com/api/v1/ids",

kfinance/domains/mergers_and_acquisitions/merger_and_acquisition_models.py

@@ -6,10 +6,16 @@ from pydantic import BaseModel
 class MergerSummary(BaseModel):
     transaction_id: int
     merger_title: str
-    closed_date: date
+    closed_date: date | None
 
 
 class MergersResp(BaseModel):
     target: list[MergerSummary]
     buyer: list[MergerSummary]
     seller: list[MergerSummary]
+
+
+class AdvisorResp(BaseModel):
+    advisor_company_id: str
+    advisor_company_name: str
+    advisor_type_name: str | None

kfinance/domains/mergers_and_acquisitions/merger_and_acquisition_tools.py

@@ -7,7 +7,10 @@ from kfinance.client.batch_request_handling import Task, process_tasks_in_thread
 from kfinance.client.kfinance import Company, MergerOrAcquisition, ParticipantInMerger
 from kfinance.client.permission_models import Permission
 from kfinance.domains.companies.company_models import prefix_company_id
-from kfinance.domains.mergers_and_acquisitions.merger_and_acquisition_models import MergersResp
+from kfinance.domains.mergers_and_acquisitions.merger_and_acquisition_models import (
+    AdvisorResp,
+    MergersResp,
+)
 from kfinance.integrations.tool_calling.tool_calling_models import (
     KfinanceTool,
     ToolArgsWithIdentifier,
@@ -23,9 +26,7 @@ class GetMergersFromIdentifiersResp(ToolRespWithErrors):
 class GetMergersFromIdentifiers(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?"
+        "Retrieves all merger and acquisition transactions involving the specified company identifier for each specified company identifier. The results are categorized by the company's role in each transaction: target, buyer, or seller. Provides the transaction_id, merger_title, and transaction closed_date (finalization) . Use this tool to answer questions like 'Which companies did Microsoft purchase?', 'Which company acquired Ben & Jerry's?', and 'Who did Pfizer acquire?'"
     """).strip()
     args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
     accepted_permissions: set[Permission] | None = {Permission.MergersPermission}
@@ -91,9 +92,7 @@ class GetMergerInfoFromTransactionIdArgs(BaseModel):
 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?"
+        "Provides comprehensive information about a specific merger or acquisition transaction, including its timeline (announced date, closed date), participants' company_name and company_id (target, buyers, sellers), and financial consideration details (including monetary values). Use this tool to answer questions like 'When was the acquisition Ben & Jerry's announced?', 'What was the transaction size of Vodafone's acquisition of Mannesmann?', 'How much did S&P purchase Kensho for?'. Always call this for announcement related questions"
     """).strip()
     args_schema: Type[BaseModel] = GetMergerInfoFromTransactionIdArgs
     accepted_permissions: set[Permission] | None = {Permission.MergersPermission}
@@ -162,32 +161,53 @@ class GetAdvisorsForCompanyInTransactionFromIdentifierArgs(ToolArgsWithIdentifie
     transaction_id: int | None = Field(description="The ID of the merger.", default=None)
 
 
+class GetAdvisorsForCompanyInTransactionFromIdentifierResp(ToolRespWithErrors):
+    results: list[AdvisorResp]
+
+
 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?"'
+    description: str = dedent("""
+        "Returns a list of advisor companies that provided advisory services to the specified company during a particular merger or acquisition transaction. Use this tool to answer questions like 'Who advised S&P Global during their purchase of Kensho?', 'Which firms advised Ben & Jerry's in their acquisition?'."
+    """).strip()
     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)
+    def _run(self, identifier: str, transaction_id: int) -> dict:
+        api_client = self.kfinance_client.kfinance_api_client
+        id_triple_resp = api_client.unified_fetch_id_triples(identifiers=[identifier])
+        # If the identifier cannot be resolved, return the associated error.
+        if id_triple_resp.errors:
+            output_model = GetAdvisorsForCompanyInTransactionFromIdentifierResp(
+                results=[], errors=list(id_triple_resp.errors.values())
+            )
+            return output_model.model_dump(mode="json")
+
+        id_triple = id_triple_resp.identifiers_to_id_triples[identifier]
+
         participant_in_merger = ParticipantInMerger(
-            kfinance_api_client=ticker.kfinance_api_client,
+            kfinance_api_client=api_client,
             transaction_id=transaction_id,
             company=Company(
-                kfinance_api_client=ticker.kfinance_api_client,
-                company_id=ticker.company.company_id,
+                kfinance_api_client=api_client,
+                company_id=id_triple.company_id,
             ),
         )
+
         advisors = participant_in_merger.advisors
 
+        advisors_response: list[AdvisorResp] = []
         if advisors:
-            return [
-                {
-                    "advisor_company_id": prefix_company_id(advisor.company.company_id),
-                    "advisor_company_name": advisor.company.name,
-                    "advisor_type_name": advisor.advisor_type_name,
-                }
-                for advisor in advisors
-            ]
-        else:
-            return []
+            for advisor in advisors:
+                advisors_response.append(
+                    AdvisorResp(
+                        advisor_company_id=prefix_company_id(advisor.company.company_id),
+                        advisor_company_name=advisor.company.name,
+                        advisor_type_name=advisor.advisor_type_name,
+                    )
+                )
+
+        output_model = GetAdvisorsForCompanyInTransactionFromIdentifierResp(
+            results=advisors_response, errors=list(id_triple_resp.errors.values())
+        )
+        return output_model.model_dump(mode="json")

kfinance/domains/mergers_and_acquisitions/tests/test_merger_and_acquisition_tools.py

@@ -46,28 +46,42 @@ 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",
-                }
-            ]
+        advisor_data = {
+            "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
+        api_response = {"advisors": [deepcopy(advisor_data)]}
+        expected_response = {"results": [deepcopy(advisor_data)]}
+        expected_response["results"][0]["advisor_company_id"] = f"{COMPANY_ID_PREFIX}251994106"
+        transaction_id = 554979212
         requests_mock.get(
-            url=f"https://kfinance.kensho.com/api/v1/merger/info/{transaction_id}/advisors/21835",
+            url=f"https://kfinance.kensho.com/api/v1/merger/info/{transaction_id}/advisors/{SPGI_COMPANY_ID}",
             json=api_response,
         )
         tool = GetAdvisorsForCompanyInTransactionFromIdentifier(kfinance_client=mock_client)
         args = GetAdvisorsForCompanyInTransactionFromIdentifierArgs(
-            identifier="MSFT", transaction_id=transaction_id
+            identifier="SPGI", transaction_id=transaction_id
+        )
+        response = tool.run(args.model_dump(mode="json"))
+        assert response == expected_response
+
+    def test_get_companies_advising_company_in_transaction_from_bad_identifier(
+        self, requests_mock: Mocker, mock_client: Client
+    ):
+        expected_response = {
+            "results": [],
+            "errors": [
+                "No identification triple found for the provided identifier: NON-EXISTENT of type: ticker"
+            ],
+        }
+        transaction_id = 554979212
+        tool = GetAdvisorsForCompanyInTransactionFromIdentifier(kfinance_client=mock_client)
+        args = GetAdvisorsForCompanyInTransactionFromIdentifierArgs(
+            identifier="non-existent", transaction_id=transaction_id
         )
         response = tool.run(args.model_dump(mode="json"))
-        assert response == expected_response["advisors"]
+        assert response == expected_response
 
 
 class TestGetMergerInfoFromTransactionId:

kfinance/integrations/tool_calling/all_tools.py

@@ -20,6 +20,11 @@ from kfinance.domains.earnings.earning_tools import (
     GetTranscriptFromKeyDevId,
 )
 from kfinance.domains.line_items.line_item_tools import GetFinancialLineItemFromIdentifiers
+from kfinance.domains.mergers_and_acquisitions.merger_and_acquisition_tools import (
+    GetAdvisorsForCompanyInTransactionFromIdentifier,
+    GetMergerInfoFromTransactionId,
+    GetMergersFromIdentifiers,
+)
 from kfinance.domains.prices.price_tools import GetPricesFromIdentifiers
 from kfinance.domains.segments.segment_tools import GetSegmentsFromIdentifiers
 from kfinance.domains.statements.statement_tools import GetFinancialStatementFromIdentifiers
@@ -60,4 +65,8 @@ ALL_TOOLS: list[type[KfinanceTool]] = [
     GetSegmentsFromIdentifiers,
     # Statements
     GetFinancialStatementFromIdentifiers,
+    # Mergers & Acquisitions
+    GetAdvisorsForCompanyInTransactionFromIdentifier,
+    GetMergerInfoFromTransactionId,
+    GetMergersFromIdentifiers,
 ]

kfinance/version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '3.2.3'
-__version_tuple__ = version_tuple = (3, 2, 3)
+__version__ = version = '3.2.4'
+__version_tuple__ = version_tuple = (3, 2, 4)
 
 __commit_id__ = commit_id = None