kensho-kfinance 2.6.5__py3-none-any.whl → 2.7.0__py3-none-any.whl

{kensho_kfinance-2.6.5.dist-info → kensho_kfinance-2.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.6.5
+Version: 2.7.0
 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-2.6.5.dist-info → kensho_kfinance-2.7.0.dist-info}/RECORD

@@ -1,18 +1,18 @@
-kensho_kfinance-2.6.5.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-2.6.5.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=YiHif7EkkMz4H_xOuDpLlFZ1-8nJE3LOR6yHs1mO_6w,2065
+kensho_kfinance-2.7.0.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-2.7.0.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=wNB99rvUBZsLmuCxq9ZtzvNpzeze8YmFz2HMdue3Di4,2175
 kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/batch_request_handling.py,sha256=G9rhpgQaCdb5C1dsfuJip8383iszibcOJ5k8gxld-tQ,5001
 kfinance/constants.py,sha256=Zh7ruf-gFR6twCy5CUjOCgT_cGX-rgFdmR84AkcztYw,49453
-kfinance/fetch.py,sha256=QyQjL2t9Z_tT1DD_Xzal59URH7QtnrpLQywcHSFtoWA,26691
-kfinance/kfinance.py,sha256=-KilPs5VK5DDddfcFtt5NB_S8ITPfixlRUyovgE3LZA,72931
+kfinance/fetch.py,sha256=sDxO3loGNcn2aT8azXR6MlHHLyjYoWIKK1HpN2-fYu0,27682
+kfinance/kfinance.py,sha256=MvEgcSDSiws3beJefQbOh3n8DdC6Wf33wiwf3Jfu6Mg,73194
 kfinance/mcp.py,sha256=MbktclVfBOEwfe-eR7kPaTXopMJmn_8RMlf4Jx5CXKU,3689
 kfinance/meta_classes.py,sha256=ulRNnWZ4P0HURs8XPzCTsJ3SYbvnT4SXyG4dIuITxAo,21766
 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=-IQDAMhAOM7pwUeC1G5pNoAyrR4v-SlcNn3yoDx_kZw,511
+kfinance/version.py,sha256=t0tYtjmuqfTGJQNs3pmrehzkGSiJlTwAuPRgzmcsAVU,511
 kfinance/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/tests/conftest.py,sha256=dhL_RSc-af3j-2_UrAGRE9mxgcbjuIRtj08DTx79pQc,1123
 kfinance/tests/scratch.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -22,7 +22,7 @@ kfinance/tests/test_example_notebook.py,sha256=XHwDKw2avyMonTmi3snCcFWNfZhEJOkpB
 kfinance/tests/test_fetch.py,sha256=mIj61dd843p3D1qtTAO60rZi6Rax0NgefOTTiBFrQcQ,17887
 kfinance/tests/test_group_objects.py,sha256=SoMEZmkG4RYdgWOAwxLHHtzIQho92KM01YbQXPUg578,1689
 kfinance/tests/test_objects.py,sha256=YlpxjlT1kJsDf4SgTZkhhthODwCnwNukJF_wvi11p3A,40805
-kfinance/tests/test_tools.py,sha256=OfyoS4LInkh8c6hlGj-qtTwaL0WqV-8H7od3uNYXnec,29086
+kfinance/tests/test_tools.py,sha256=nq6xfnUYBm4uF_iGe2iLv6SXFesbEy4QyBk4ldXyhPk,30097
 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=rrUVesFG3EpdVnvML42o6apJyBfWOBk0iYydJgIZaig,1615
@@ -47,8 +47,8 @@ kfinance/tool_calling/get_segments_from_identifier.py,sha256=-6I5pK_VSNxszUuQX6n
 kfinance/tool_calling/get_transcript.py,sha256=2Vzab47kMw1288AubFXwhNGHtodmy_n2itITgk5szOg,767
 kfinance/tool_calling/prompts.py,sha256=Yw1DJIMh90cjL-8q6_RMRiSjCtFDXvJAy7QiV5_uAU8,911
 kfinance/tool_calling/resolve_identifier.py,sha256=_XEfGtDEB5tnAnseyQaugn4AuNsy6wZe5f-QOh8myko,632
-kfinance/tool_calling/shared_models.py,sha256=COwOWhzgBMJMv1uXEhlsZJ0iwgA6yX2knFG8t9wY0uU,2819
-kensho_kfinance-2.6.5.dist-info/METADATA,sha256=Ajs4li5Ux4TEl-zmEd2QoQB-W07xiCTgdsghc6mHORQ,6197
-kensho_kfinance-2.6.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kensho_kfinance-2.6.5.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-2.6.5.dist-info/RECORD,,
+kfinance/tool_calling/shared_models.py,sha256=2KUY7PLFO-89Y6pYyDNbF8ub8KgWkay16683u8Wvf8Y,3731
+kensho_kfinance-2.7.0.dist-info/METADATA,sha256=MGykZUh-nhnOLxDtjsY_rgKZX73bGLOJ5vg54yO_pY0,6197
+kensho_kfinance-2.7.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kensho_kfinance-2.7.0.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-2.7.0.dist-info/RECORD,,

kfinance/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v2.7.0
+ - Expose a new list of LLM tools `grounding_tools` that return a list of all endpoint urls called
+
 ## v2.6.5
  - Add competitor company_name
 

kfinance/fetch.py

@@ -1,6 +1,7 @@
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import contextmanager
 import logging
+from queue import Queue
 from time import time
 from typing import Callable, Generator, Optional
 from uuid import uuid4
@@ -95,6 +96,7 @@ class KFinanceApiClient:
         self._batch_id: str | None = None
         self._batch_size: str | None = None
         self._user_permissions: set[Permission] | None = None
+        self._endpoint_tracker_queue: Queue[str] | None = None
 
     @contextmanager
     def batch_request_header(self, batch_size: int) -> Generator:
@@ -208,9 +210,28 @@ class KFinanceApiClient:
                     permission_str,
                 )
 
+    @contextmanager
+    def endpoint_tracker(self) -> Generator:
+        """Context manager to track and return endpoint URLs in our thread-safe queue during execution.
+
+        endpoint_tracker yields a queue into which all endpoint URLs are written until the context manager gets exited.
+        It is up to the callers to dequeue the queue before the context manager gets exited and the queue gets wiped.
+        This functionality is currently used by `run_with_grounding` to collect and forward endpoint URLs.
+        """
+        self._endpoint_tracker_queue = Queue[str]()
+
+        try:
+            yield self._endpoint_tracker_queue
+        finally:
+            self._endpoint_tracker_queue = None
+
     def fetch(self, url: str) -> dict:
         """Does the request and auth"""
 
+        # _endpoint_tracker_queue will only be initialized if inside the endpoint_tracker context manager
+        if self._endpoint_tracker_queue:
+            self._endpoint_tracker_queue.put(url)
+
         headers = {
             "Content-Type": "application/json",
             "Authorization": f"Bearer {self.access_token}",

kfinance/kfinance.py

@@ -1663,6 +1663,11 @@ class Client:
         """
         return {t.name: t.run_without_langchain for t in self.langchain_tools}
 
+    @property
+    def grounding_tools(self) -> dict[str, Callable]:
+        """Return a mapping of tool calling function names to the corresponding functions for the grounding agent."""
+        return {t.name: t.run_with_grounding for t in self.langchain_tools}
+
     @property
     def anthropic_tool_descriptions(self) -> list[dict[str, Any]]:
         """Return tool descriptions for anthropic"""

kfinance/tests/test_tools.py

@@ -722,6 +722,34 @@ class TestGetCompetitorsFromIdentifier:
         assert response == expected_competitors_response
 
 
+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": 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 = GetInfoFromIdentifier(kfinance_client=mock_client)
+        resp = tool.run_with_grounding(identifier="SPGI")
+        assert resp == expected_resp
+
+
 class TestValidQuarter:
     class QuarterModel(BaseModel):
         quarter: ValidQuarter | None

kfinance/tool_calling/shared_models.py

@@ -40,6 +40,25 @@ class KfinanceTool(BaseTool):
         args_dict = {k: v for k, v in args_dict.items() if k in kwargs}
         return self._run(**args_dict)
 
+    def run_with_grounding(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute a Kfinance tool with grounding support.
+
+        This is a wrapper around the `run_without_langchain` method that adds grounding
+        support, for returning the endpoint urls along with the data as citation info for the LRA Data Agent.
+        """
+        with self.kfinance_client.kfinance_api_client.endpoint_tracker() as endpoint_tracker_queue:
+            data = self.run_without_langchain(*args, **kwargs)
+
+            # After completion of tool data fetching and within the endpoint_tracker context manager scope, dequeue the endpoint_tracker_queue
+            endpoint_urls = []
+            while not endpoint_tracker_queue.empty():
+                endpoint_urls.append(endpoint_tracker_queue.get())
+
+            return {
+                "data": data,
+                "endpoint_urls": endpoint_urls,
+            }
+
     def _run(self, *args: Any, **kwargs: Any) -> Any:
         """The code to execute the tool"""
         ...

kfinance/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.6.5'
-__version_tuple__ = version_tuple = (2, 6, 5)
+__version__ = version = '2.7.0'
+__version_tuple__ = version_tuple = (2, 7, 0)