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

kfinance/integrations/tool_calling/tests/test_tool_calling_models.py

@@ -0,0 +1,69 @@
+import contextlib
+from contextlib import nullcontext as does_not_raise
+
+from pydantic import BaseModel, ValidationError
+import pytest
+from requests_mock import Mocker
+
+from kfinance.client.kfinance import Client
+from kfinance.conftest import SPGI_COMPANY_ID
+from kfinance.domains.companies.company_tools import GetInfoFromIdentifiers
+from kfinance.integrations.tool_calling.tool_calling_models import ValidQuarter
+
+
+class TestGetEndpointsFromToolCallsWithGrounding:
+    def test_get_info_from_identifier_with_grounding(
+        self, mock_client: Client, requests_mock: Mocker
+    ):
+        """
+        GIVEN a KfinanceTool tool
+        WHEN we run the tool with `run_with_grounding`
+        THEN we get back endpoint urls in addition to the usual tool response.
+        """
+
+        # truncated from the original
+        resp_data = {"name": "S&P Global Inc.", "status": "Operating"}
+        resp_endpoint = [
+            "https://kfinance.kensho.com/api/v1/id/SPGI",
+            "https://kfinance.kensho.com/api/v1/info/21719",
+        ]
+        expected_resp = {"data": {"SPGI": resp_data}, "endpoint_urls": resp_endpoint}
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/info/{SPGI_COMPANY_ID}",
+            json=resp_data,
+        )
+
+        tool = GetInfoFromIdentifiers(kfinance_client=mock_client)
+        resp = tool.run_with_grounding(identifiers=["SPGI"])
+        assert resp == expected_resp
+
+
+class TestValidQuarter:
+    class QuarterModel(BaseModel):
+        quarter: ValidQuarter | None
+
+    @pytest.mark.parametrize(
+        "input_quarter, expectation, expected_quarter",
+        [
+            pytest.param(1, does_not_raise(), 1, id="int input works"),
+            pytest.param("1", does_not_raise(), 1, id="str input works"),
+            pytest.param(None, does_not_raise(), None, id="None input works"),
+            pytest.param(5, pytest.raises(ValidationError), None, id="invalid int raises"),
+            pytest.param("5", pytest.raises(ValidationError), None, id="invalid str raises"),
+        ],
+    )
+    def test_valid_quarter(
+        self,
+        input_quarter: int | str | None,
+        expectation: contextlib.AbstractContextManager,
+        expected_quarter: int | None,
+    ) -> None:
+        """
+        GIVEN a model that uses `ValidQuarter`
+        WHEN we deserialize with int, str, or None
+        THEN valid str get coerced to int. Invalid values raise.
+        """
+        with expectation:
+            res = self.QuarterModel.model_validate(dict(quarter=input_quarter))
+            assert res.quarter == expected_quarter

kfinance/{tool_calling/shared_models.py → integrations/tool_calling/tool_calling_models.py}

@@ -3,8 +3,8 @@ from typing import Annotated, Any, Literal, Type
 from langchain_core.tools import BaseTool
 from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
 
-from kfinance.kfinance import Client
-from kfinance.models.permission_models import Permission
+from kfinance.client.kfinance import Client
+from kfinance.client.permission_models import Permission
 
 
 class KfinanceTool(BaseTool):
@@ -20,7 +20,7 @@ class KfinanceTool(BaseTool):
         description="The set of accepted permissions needed to access the tool. Only one of the permissions is required (or None)."
     )
 
-    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+    model_config = ConfigDict(extra="forbid")
 
     def run_without_langchain(self, *args: Any, **kwargs: Any) -> Any:
         """Execute a Kfinance tool without langchain.
@@ -60,19 +60,49 @@ class KfinanceTool(BaseTool):
             }
 
     def _run(self, *args: Any, **kwargs: Any) -> Any:
-        """The code to execute the tool"""
+        """The code to execute the tool.
+
+        Where feasible and useful, tools should use batch processing to parallelize
+        requests, usually by allowing callers to pass in multiple identifiers.
+        The usual processing order for functions with multiple identifiers is:
+        - Parse string identifiers into `CompanyIdentifier`
+        - batch fetch the required id for the api call (company/security/trading item id) via
+            fetch_<relevant>_ids_from_identifiers
+        - batch fetch the required info based on the ids via process_tasks_in_thread_pool_executor
+        - format results for output
+
+        Any company_ids in the response should be prefixed with the COMPANY_ID_PREFIX ("C_").
+        This allows us to circumvent overlaps between tickers (which can be purely numerical)
+        and company_ids. Company_ids with prefixes can be used like normal identifiers.
+        For example:
+        Request: get_business_relationship_from_identifiers(identifiers=["SPGI"], business_relationship="supplier")
+        Response: {"SPGI": {"current": [{"company_id": "C_883103", "company_name": "A Corp"}]...
+        Request: get_prices_from_identifiers(identifiers=["C_883103"])
+        """
         ...
 
 
 class ToolArgsWithIdentifier(BaseModel):
     """Tool argument with an identifier.
 
-    All tools using an identifier should subclass this model to ensure that the description
-    of identifier is always the same.
+    All tools using identifiers should subclass this model to ensure that the description
+    of identifiers is always the same.
     """
 
     identifier: str = Field(
-        description="The identifier, which can be a ticker symbol, ISIN, or CUSIP"
+        description="The identifier, which can be a ticker symbol, ISIN, CUSIP, or company_id"
+    )
+
+
+class ToolArgsWithIdentifiers(BaseModel):
+    """Tool argument with a list of identifiers.
+
+    All tools using identifiers should subclass this model to ensure that the description
+    of identifiers is always the same.
+    """
+
+    identifiers: list[str] = Field(
+        description="The identifiers, which can be a list of ticker symbols, ISINs, or CUSIPs, or company_ids"
     )
 
 

kfinance/models/permission_models.py

@@ -13,3 +13,4 @@ class Permission(StrEnum):
     SegmentsPermission = "SegmentsPermission"
     StatementsPermission = "StatementsPermission"
     TranscriptsPermission = "TranscriptsPermission"
+    PrivateCompanyFinancialsPermission = "PrivateCompanyFinancialsPermission"

kfinance/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.9.0'
-__version_tuple__ = version_tuple = (2, 9, 0)
+__version__ = version = '3.0.1'
+__version_tuple__ = version_tuple = (3, 0, 1)

kensho_kfinance-2.9.0.dist-info/RECORD

@@ -1,70 +0,0 @@
-kensho_kfinance-2.9.0.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-2.9.0.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=vwLoxhyrR2AGSJbkfkvWYjjZQ6UBrfjOPSZq4eM9nok,2280
-kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/batch_request_handling.py,sha256=G9rhpgQaCdb5C1dsfuJip8383iszibcOJ5k8gxld-tQ,5001
-kfinance/decimal_with_unit.py,sha256=U1eJSJ-4zPHkdtHcrfaW9CmmaLPE13MiWJy6odRyeXo,2904
-kfinance/fetch.py,sha256=MSdDddZ_1YdmzCuXqCXwY_vfFLdbdQeCJ6YRQrwCUCI,28157
-kfinance/kfinance.py,sha256=ob5jNO5-aTSfBwknsSVCMLQJD5mWZkPTAZlvsBJ_Z2Y,72584
-kfinance/mcp.py,sha256=MbktclVfBOEwfe-eR7kPaTXopMJmn_8RMlf4Jx5CXKU,3689
-kfinance/meta_classes.py,sha256=0wI70PXfQzNbRUW2nYVfxJjqCqqI5EukUIKjaMcrzVA,21804
-kfinance/prompt.py,sha256=PtVB8c_FcSlVdyGgByAnIFGzuUuBaEjciCqnBJl1hSQ,25133
-kfinance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/pydantic_models.py,sha256=avpbPqwrAyLqsCbrmFpK_B8_fj1nPlBHrnPxRcBaSkE,774
-kfinance/server_thread.py,sha256=jUnt1YGoYDkqqz1MbCwd44zJs1T_Z2BCgvj75bdtLgA,2574
-kfinance/version.py,sha256=pqhLPO2SP7VnEU-lJpoO0qS9x0Kgz8BD6Rgr6J_aK-o,511
-kfinance/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/models/business_relationship_models.py,sha256=XlkYI_XUegORH4U4oLXjdFIX9Pr9FvQUnFAc67D2M4s,770
-kfinance/models/capitalization_models.py,sha256=jB0MIZ94UOPfVckuS2asED9ARjisrStC_O4KgfHmoJw,3193
-kfinance/models/competitor_models.py,sha256=0yDu49Pe28ErpCMLX-BBeUnjjxqerb49ToVKSTOivNk,565
-kfinance/models/currency_models.py,sha256=JfDZf-nATCyjThBw-Ky2BNvM-n2oHepBLIHMCIyCRUE,19201
-kfinance/models/date_and_period_models.py,sha256=B508v1SLy_mbSSuSbPz41xeFNRAeBFv41gJSlaXyHnU,1062
-kfinance/models/id_models.py,sha256=xhFKmDddBfqkQZsbOP8za8VnxIFHiwvGThKjeGKC2Hg,138
-kfinance/models/industry_models.py,sha256=ydB_cTIsNsfCUeaO7K2qqLUuHdG6WfUCoAzBigKVV8M,243
-kfinance/models/line_item_models.py,sha256=JIdoSYxoJDQVkmqUK6_ABpb6lULXRvrCDJGiKL6kRhE,45399
-kfinance/models/permission_models.py,sha256=z6MKY7Zf7StPKwsucsoVqltUesicU6MC6rxRGmlRwZI,557
-kfinance/models/price_models.py,sha256=saiJk1ZIs02cHtY54-5YvS7NgH3EABR2RGT6wpzRauY,2149
-kfinance/models/segment_models.py,sha256=GSJhK1HmbMmwRDFmrDTZzx8aYrAaHN13IJ0J9GTBn9Y,145
-kfinance/models/statement_models.py,sha256=RmclTeyahCODUP0-KgZZZequFgQ2pUQ8cdfHI96c9vA,207
-kfinance/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/tests/conftest.py,sha256=dhL_RSc-af3j-2_UrAGRE9mxgcbjuIRtj08DTx79pQc,1123
-kfinance/tests/test_batch_requests.py,sha256=JjP5OOKyxzYqmVmTR2hzM4Q6wyYDCEDHINH4vNFd6ag,11597
-kfinance/tests/test_client.py,sha256=YZT-AXpFsVHpdoZj01d2TkmUkNP-8f3cIOgeXtP_05U,3870
-kfinance/tests/test_decimal_with_unit.py,sha256=98zZmSLojWq3FS0e5AuNxv9eluqGVEoqM3r_agkmt_Y,2188
-kfinance/tests/test_example_notebook.py,sha256=VFS2W_T0yEtd74YiRxj3KA7eEL_fJuCpWwUAkiFqzkc,6501
-kfinance/tests/test_fetch.py,sha256=s8fSkXDtNjDcK_jWQYUO1stx9ElX1I54qG_48WxfBAc,18558
-kfinance/tests/test_group_objects.py,sha256=SoMEZmkG4RYdgWOAwxLHHtzIQho92KM01YbQXPUg578,1689
-kfinance/tests/test_objects.py,sha256=cpTE22omZATe-2j9jnuchgEiZtNM-wler95ainYoh_o,42471
-kfinance/tests/test_tools.py,sha256=jLrugYTSdK6Cw4SmJxsxdYdJ1S3X7wDcBC7kQAWe75A,31024
-kfinance/tests/test_models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/tests/test_models/test_capitalization_models.py,sha256=E-5eZX0ufdFsmcWATt5agyH4Ks-q8TNO-W6cnYIMOcE,3116
-kfinance/tests/test_models/test_price_models.py,sha256=DHBMAFJ8axat1s_C0tElqcCjw6YhmzF9WWKpKmySwv0,2378
-kfinance/tool_calling/README.md,sha256=omJq7Us6r4U45QB7hRpLjRJ5BMalCkZkh4uXBjTbJXc,2022
-kfinance/tool_calling/__init__.py,sha256=UmtbtG6PvQHB1fInEL-K5q0kPHL__zTY9wzaPRSp1wg,2174
-kfinance/tool_calling/get_advisors_for_company_in_transaction_from_identifier.py,sha256=IYpImoYfeq7Ep_IrUZgsSHC0oLSmI1mwuTR_1ftTPMY,1789
-kfinance/tool_calling/get_business_relationship_from_identifier.py,sha256=oPlVpDy4AY8nQFZnHRp9DhpL8SecIlyEY6aiklHtVDg,1551
-kfinance/tool_calling/get_capitalization_from_identifier.py,sha256=qciQI9gSJh4gGatnjOkid-GJSlzXkvt7-2VcK2yBfrg,1558
-kfinance/tool_calling/get_competitors_from_identifier.py,sha256=J9TVWNU_6d6ltJLIJTdCtkhbc0MqoCbqdWUxrwBkOUs,1156
-kfinance/tool_calling/get_cusip_from_ticker.py,sha256=ebzFmjZFkcuydntQXmuxfh8mhPiXmmzUTb2ncHy00ao,667
-kfinance/tool_calling/get_earnings.py,sha256=d7UvVsSAcrVlveWyUpua35vdloA_QgJnQ4Nmg7wT7m0,1245
-kfinance/tool_calling/get_financial_line_item_from_identifier.py,sha256=hsKmObT2TJ4HMusVtQXU6FMDmyY7bKg2V-x-IXuU71c,2270
-kfinance/tool_calling/get_financial_statement_from_identifier.py,sha256=ba8Z378YrQ_J0-A6KVLOtxe-hYMP68780g0xXZfAyT8,2023
-kfinance/tool_calling/get_history_metadata_from_identifier.py,sha256=hPC-RwwcnJ9kkhxTUJLE-xvCqfIq5kJcKM4deiL8zlI,789
-kfinance/tool_calling/get_info_from_identifier.py,sha256=2-NmGvFpYXASGV_lJaYhhdXMxQpyvi30bXY9mGWwbBw,787
-kfinance/tool_calling/get_isin_from_ticker.py,sha256=tp79lowBUdkv7fm-8QX4vJqeDZiq5M_jkkp8XKC1KY4,661
-kfinance/tool_calling/get_latest.py,sha256=m6nBA8Bo51Q85kGbGnP59IUz4-lm_CRo1kSuNM26iXg,857
-kfinance/tool_calling/get_latest_earnings.py,sha256=R98ImaONP3AjVshygkRLwcAHKscvVRkVoPw117O9nuw,1197
-kfinance/tool_calling/get_merger_info_from_transaction_id.py,sha256=gB6VUmCAKS0OBclpcdp2gQq7cdxKbWTXt5Z8aMH_-ys,3243
-kfinance/tool_calling/get_mergers_from_identifier.py,sha256=tgpcLQM1CPvyk4_xyUhcZh01kAzwdkQCV6gq-bEsFhA,1935
-kfinance/tool_calling/get_n_quarters_ago.py,sha256=VYUBbQIowHXmNuln1oKoDKeWDbnXLg4p6X0d1HoY_NY,784
-kfinance/tool_calling/get_next_earnings.py,sha256=vL3sCoocPhHDRawVRu9IyQPLXVAgODrZgKSqkP3Scs8,1177
-kfinance/tool_calling/get_prices_from_identifier.py,sha256=uXD9fiLFI0vUM_YY8DI_9ifC0oeeC3KCyaTQQ0IjuSA,1966
-kfinance/tool_calling/get_segments_from_identifier.py,sha256=1Ux9ZWEU3xmOSuAPGedo2r8wdRa_glv8roghp08MJ-c,1980
-kfinance/tool_calling/get_transcript.py,sha256=urZgpQXigmahy-vj6OjkGI9O6HJcPIpd-5CRU7NI3YQ,782
-kfinance/tool_calling/prompts.py,sha256=Yw1DJIMh90cjL-8q6_RMRiSjCtFDXvJAy7QiV5_uAU8,911
-kfinance/tool_calling/resolve_identifier.py,sha256=Rkhwi6m3hffE19qaxRkrsu6slRKyiAXjfLr8L41N2zc,647
-kfinance/tool_calling/shared_models.py,sha256=Sx_zlwk5YLu533406Pmh499NH5oTBWrZf8Ua8zoUSRk,3746
-kensho_kfinance-2.9.0.dist-info/METADATA,sha256=NhJXLeMBY0A1QP2PaA2BWB7-m-cUxY1wqp7TlDRqPAY,6202
-kensho_kfinance-2.9.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kensho_kfinance-2.9.0.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-2.9.0.dist-info/RECORD,,

kfinance/models/id_models.py

@@ -1,7 +0,0 @@
-from typing import NamedTuple
-
-
-class IdentificationTriple(NamedTuple):
-    trading_item_id: int
-    security_id: int
-    company_id: int