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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.6.3
+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.7.0.dist-info/RECORD

@@ -0,0 +1,54 @@
+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=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=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
+kfinance/tests/test_batch_requests.py,sha256=2A0XnDDDSPkq0-BuiRryZx8b9_jBDtjYd2kWxFVyRew,10140
+kfinance/tests/test_client.py,sha256=_OJ8fZ14aa7Oj2znheuRIRKz7FyQLqwkhWexEZetxmg,3855
+kfinance/tests/test_example_notebook.py,sha256=XHwDKw2avyMonTmi3snCcFWNfZhEJOkpBGOZNrMLrhk,6470
+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=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
+kfinance/tool_calling/get_business_relationship_from_identifier.py,sha256=vILN4k2NGCIrpgWiT_p7CLwDv_uQf9qXwojmQwDRsJo,1480
+kfinance/tool_calling/get_capitalization_from_identifier.py,sha256=7n52UH0oug6KspPxCQsRinb6WPC4M5UNK1CFhQxKAaE,1529
+kfinance/tool_calling/get_competitors_from_identifier.py,sha256=RZ1ngeeZee12GOKUvw1rpzij9A55Zfs3MTt6O-DC98M,1096
+kfinance/tool_calling/get_cusip_from_ticker.py,sha256=P4J2JS0_jwmfBWD9k-URlJ0gPFsgTkglivN-d3fA9Ek,652
+kfinance/tool_calling/get_earnings.py,sha256=53mpdno7uaVMQVQXC_IXYEGvBh2kM7e41SFxI9LG--A,1230
+kfinance/tool_calling/get_financial_line_item_from_identifier.py,sha256=iQywFZzXQdvL3oSWPHZJ6v1kifR27tsHLcXa6089Wls,2161
+kfinance/tool_calling/get_financial_statement_from_identifier.py,sha256=4nJvQBaZZpD9-cKBONEimicUsQxIftFfdVj7rRqdUck,1914
+kfinance/tool_calling/get_history_metadata_from_identifier.py,sha256=N-ZXYMT0YGIcTmCEAKgs5IK134WKFeuVzrGyPYIliXM,734
+kfinance/tool_calling/get_info_from_identifier.py,sha256=XRan7nKa0FQuBF0i8UmoN2E0FOMEx34N8H-El4J51E0,772
+kfinance/tool_calling/get_isin_from_ticker.py,sha256=iy4p8dhOpkooPZP8BPQRijsZbDbuAf9WyV5t8zBGMi8,646
+kfinance/tool_calling/get_latest.py,sha256=CHtR8MvUdOxI63kWVWFONUaqlHPhSrE9qv96RRCJsiw,792
+kfinance/tool_calling/get_latest_earnings.py,sha256=lUahH0G-QbxxeN4ClF-ETrMACFesw5UXOl9pnssDgzM,1182
+kfinance/tool_calling/get_merger_info_from_transaction_id.py,sha256=uTtUFMtKrN53BxZ53s_HlTyyc4ToO1qIPFUts6IQFu8,3150
+kfinance/tool_calling/get_mergers_from_identifier.py,sha256=Av86oG4Rf4eUYG3aHIzIMwJEkrxKR1CqRYLPnCQN5po,1710
+kfinance/tool_calling/get_n_quarters_ago.py,sha256=R-_Wn-VUYABb7CPD2OQ_xauMAOZoYXW0FPw6ccvw6Ho,719
+kfinance/tool_calling/get_next_earnings.py,sha256=O7bIXqJmvxgBZZ9jjcvN2WGy2KIsBe6YegnymiYJy-E,1162
+kfinance/tool_calling/get_prices_from_identifier.py,sha256=4yTEPWTMqfUfU6JdsD_TQJLEFTNji0wic-8oXtdSqVY,1890
+kfinance/tool_calling/get_segments_from_identifier.py,sha256=-6I5pK_VSNxszUuQX6ne9zr7HFwaeWCFMddmJ3PYA_g,1873
+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=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,6 +1,15 @@
 # Changelog
 
-# v2.6.3
+## 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
+
+## v2.6.4
+- Add transcript permission and update accepted_permissions type to set[Permission]
+
+## v2.6.3
 - Bump urllib3 to 2.5 to  address CVEs
 
 ## v2.6.2

kfinance/constants.py

@@ -94,6 +94,7 @@ class BusinessRelationshipType(StrEnum):
 
 class Permission(StrEnum):
     EarningsPermission = "EarningsPermission"
+    TranscriptsPermission = "TranscriptsPermission"
     GICSPermission = "GICSPermission"
     IDPermission = "IDPermission"
     ISCRSPermission = "ISCRSPermission"

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

@@ -1644,8 +1644,11 @@ class Client:
             for tool_cls in ALL_TOOLS:
                 tool = tool_cls(kfinance_client=self)  # type: ignore[call-arg]
                 if (
-                    tool.required_permission is None
-                    or tool.required_permission in self.kfinance_api_client.user_permissions
+                    tool.accepted_permissions is None
+                    # if one or more of the required permission for a tool is a permission the user has
+                    or tool.accepted_permissions.intersection(
+                        self.kfinance_api_client.user_permissions
+                    )
                 ):
                     self._tools.append(tool)
 
@@ -1660,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/meta_classes.py

@@ -427,19 +427,26 @@ class CompanyFunctionsMetaClass:
     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.
+        """Get the list of company_id and company_name 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
+        :return: The list of company_id and company_name that are competitors of company_id, optionally filtered by the competitor_source type
         :rtype: Companies
         """
-        from .kfinance import Companies
+        from .kfinance import Companies, Company
 
         competitors_data = self.kfinance_api_client.fetch_competitors(
             company_id=self.company_id, competitor_source=competitor_source
-        )["companies"]
+        )["competitors"]
         return Companies(
             kfinance_api_client=self.kfinance_api_client,
-            company_ids=[company["company_id"] for company in competitors_data],
+            companies=[
+                Company(
+                    kfinance_api_client=self.kfinance_api_client,
+                    company_id=company["company_id"],
+                    company_name=company["company_name"],
+                )
+                for company in competitors_data
+            ],
         )
 
 

kfinance/tests/test_client.py

@@ -6,9 +6,14 @@ from kfinance.constants import Permission
 from kfinance.kfinance import Client
 from kfinance.tool_calling import (
     GetBusinessRelationshipFromIdentifier,
+    GetEarnings,
     GetFinancialStatementFromIdentifier,
     GetLatest,
+    GetLatestEarnings,
+    GetNextEarnings,
+    GetTranscript,
 )
+from kfinance.tool_calling.shared_models import KfinanceTool
 
 
 class TestLangchainTools:
@@ -52,3 +57,33 @@ class TestLangchainTools:
         assert GetLatest in tool_classes
         # User should not have access to functions that require statement permissions
         assert GetFinancialStatementFromIdentifier not in tool_classes
+
+    @pytest.mark.parametrize(
+        "user_permission, expected_tool",
+        [
+            pytest.param(
+                Permission.TranscriptsPermission, GetTranscript, id="Transcript Permissions"
+            ),
+            pytest.param(Permission.EarningsPermission, GetEarnings, id="Earnings Permissions"),
+        ],
+    )
+    def test_permission_set_handling(
+        self, user_permission: Permission, expected_tool: KfinanceTool, mock_client: Client
+    ):
+        """
+        GIVEN a user with a permission that is in a set of required permission for a tool
+        WHEN we filter tools by permissions
+        THEN we successfully return the correct tools that either don't require permissions or tools that the user
+            specifically has access to.
+        """
+        mock_client.kfinance_api_client._user_permissions = {user_permission}  # noqa: SLF001
+        tool_classes = [type(t) for t in mock_client.langchain_tools]
+        # User should have access to GetEarnings, GetNextEarnings, GetLatestEarnings, GetTranscript
+        assert GetEarnings in tool_classes
+        assert GetNextEarnings in tool_classes
+        assert GetLatestEarnings in tool_classes
+        assert expected_tool in tool_classes
+        # User should have access to functions that don't require permissions
+        assert GetLatest in tool_classes
+        # User should not have access to functions that require statement permissions
+        assert GetFinancialStatementFromIdentifier not in tool_classes

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/get_advisors_for_company_in_transaction_from_identifier.py

@@ -15,7 +15,7 @@ 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
-    required_permission: Permission | None = Permission.MergersPermission
+    accepted_permissions: set[Permission] | None = {Permission.MergersPermission}
 
     def _run(self, identifier: str, transaction_id: int) -> list:
         ticker = self.kfinance_client.ticker(identifier)

kfinance/tool_calling/get_business_relationship_from_identifier.py

@@ -16,7 +16,7 @@ class GetBusinessRelationshipFromIdentifier(KfinanceTool):
     name: str = "get_business_relationship_from_identifier"
     description: str = 'Get the current and previous company IDs that are relationship_type of a given identifier. For example, "What are the current distributors of SPGI?" or "What are the previous borrowers of JPM?"'
     args_schema: Type[BaseModel] = GetBusinessRelationshipFromIdentifierArgs
-    required_permission: Permission | None = Permission.RelationshipPermission
+    accepted_permissions: set[Permission] | None = {Permission.RelationshipPermission}
 
     def _run(self, identifier: str, business_relationship: BusinessRelationshipType) -> dict:
         ticker = self.kfinance_client.ticker(identifier)

kfinance/tool_calling/get_capitalization_from_identifier.py

@@ -21,7 +21,7 @@ class GetCapitalizationFromIdentifier(KfinanceTool):
     name: str = "get_capitalization_from_identifier"
     description: str = "Get the historical market cap, tev (Total Enterprise Value), or shares outstanding of an identifier between inclusive start_date and inclusive end date. When requesting the most recent values, leave start_date and end_date empty."
     args_schema = GetCapitalizationFromIdentifierArgs
-    required_permission: Permission | None = Permission.PricingPermission
+    accepted_permissions: set[Permission] | None = {Permission.PricingPermission}
 
     def _run(
         self,

kfinance/tool_calling/get_competitors_from_identifier.py

@@ -9,9 +9,9 @@ class GetCompetitorsFromIdentifierArgs(ToolArgsWithIdentifier):
 
 class GetCompetitorsFromIdentifier(KfinanceTool):
     name: str = "get_competitors_from_identifier"
-    description: str = "Retrieves a list of competitors for a given company, optionally filtered by the source of the competitor information."
+    description: str = "Retrieves a list of company_id and company_name that are competitors for a given company, optionally filtered by the source of the competitor information."
     args_schema = GetCompetitorsFromIdentifierArgs
-    required_permission: Permission | None = Permission.CompetitorsPermission
+    accepted_permissions: set[Permission] | None = {Permission.CompetitorsPermission}
 
     def _run(
         self,

kfinance/tool_calling/get_cusip_from_ticker.py

@@ -14,7 +14,7 @@ class GetCusipFromTicker(KfinanceTool):
     name: str = "get_cusip_from_ticker"
     description: str = "Get the CUSIP associated with a ticker."
     args_schema: Type[BaseModel] = GetCusipFromTickerArgs
-    required_permission: Permission | None = Permission.IDPermission
+    accepted_permissions: set[Permission] | None = {Permission.IDPermission}
 
     def _run(self, ticker_str: str) -> str:
         return self.kfinance_client.ticker(ticker_str).cusip

kfinance/tool_calling/get_earnings.py

@@ -11,7 +11,10 @@ class GetEarnings(KfinanceTool):
     name: str = "get_earnings"
     description: str = "Get all earnings for a given identifier. Returns a list of dictionaries, each with 'name' (str), 'key_dev_id' (int), and 'datetime' (str in ISO 8601 format with UTC timezone) attributes."
     args_schema: Type[BaseModel] = ToolArgsWithIdentifier
-    required_permission: Permission | None = Permission.EarningsPermission
+    accepted_permissions: set[Permission] | None = {
+        Permission.EarningsPermission,
+        Permission.TranscriptsPermission,
+    }
 
     def _run(self, identifier: str) -> list[dict]:
         ticker = self.kfinance_client.ticker(identifier)

kfinance/tool_calling/get_financial_line_item_from_identifier.py

@@ -24,7 +24,7 @@ class GetFinancialLineItemFromIdentifier(KfinanceTool):
     name: str = "get_financial_line_item_from_identifier"
     description: str = "Get the financial line item associated with an identifier."
     args_schema: Type[BaseModel] = GetFinancialLineItemFromIdentifierArgs
-    required_permission: Permission | None = Permission.StatementsPermission
+    accepted_permissions: set[Permission] | None = {Permission.StatementsPermission}
 
     def _run(
         self,

kfinance/tool_calling/get_financial_statement_from_identifier.py

@@ -20,7 +20,7 @@ class GetFinancialStatementFromIdentifier(KfinanceTool):
     name: str = "get_financial_statement_from_identifier"
     description: str = "Get the financial statement associated with an identifier."
     args_schema: Type[BaseModel] = GetFinancialStatementFromIdentifierArgs
-    required_permission: Permission | None = Permission.StatementsPermission
+    accepted_permissions: set[Permission] | None = {Permission.StatementsPermission}
 
     def _run(
         self,

kfinance/tool_calling/get_history_metadata_from_identifier.py

@@ -10,7 +10,7 @@ class GetHistoryMetadataFromIdentifier(KfinanceTool):
     name: str = "get_history_metadata_from_identifier"
     description: str = "Get the history metadata associated with an identifier. History metadata includes currency, symbol, exchange name, instrument type, and first trade date."
     args_schema: Type[BaseModel] = ToolArgsWithIdentifier
-    required_permission: Permission | None = None
+    accepted_permissions: set[Permission] | None = None
 
     def _run(self, identifier: str) -> HistoryMetadata:
         return self.kfinance_client.ticker(identifier).history_metadata

kfinance/tool_calling/get_info_from_identifier.py

@@ -10,7 +10,7 @@ class GetInfoFromIdentifier(KfinanceTool):
     name: str = "get_info_from_identifier"
     description: str = "Get the information associated with an identifier. Info includes company name, status, type, simple industry, number of employees (if available), founding date, webpage, HQ address, HQ city, HQ zip code, HQ state, HQ country, and HQ country iso code."
     args_schema: Type[BaseModel] = ToolArgsWithIdentifier
-    required_permission: Permission | None = None
+    accepted_permissions: set[Permission] | None = None
 
     def _run(self, identifier: str) -> str:
         return str(self.kfinance_client.ticker(identifier).info)

kfinance/tool_calling/get_isin_from_ticker.py

@@ -14,7 +14,7 @@ class GetIsinFromTicker(KfinanceTool):
     name: str = "get_isin_from_ticker"
     description: str = "Get the ISIN associated with a ticker."
     args_schema: Type[BaseModel] = GetIsinFromTickerArgs
-    required_permission: Permission | None = Permission.IDPermission
+    accepted_permissions: set[Permission] | None = {Permission.IDPermission}
 
     def _run(self, ticker_str: str) -> str:
         return self.kfinance_client.ticker(ticker_str).isin

kfinance/tool_calling/get_latest.py

@@ -16,7 +16,7 @@ class GetLatest(KfinanceTool):
     name: str = "get_latest"
     description: str = "Get the latest annual reporting year, latest quarterly reporting quarter and year, and current date."
     args_schema: Type[BaseModel] = GetLatestArgs
-    required_permission: Permission | None = None
+    accepted_permissions: set[Permission] | None = None
 
     def _run(self, use_local_timezone: bool = True) -> LatestPeriods:
         return self.kfinance_client.get_latest(use_local_timezone=use_local_timezone)

kfinance/tool_calling/get_latest_earnings.py

@@ -11,7 +11,10 @@ class GetLatestEarnings(KfinanceTool):
     name: str = "get_latest_earnings"
     description: str = "Get the latest earnings for a given identifier. Returns a dictionary with 'name' (str), 'key_dev_id' (int), and 'datetime' (str in ISO 8601 format with UTC timezone) attributes."
     args_schema: Type[BaseModel] = ToolArgsWithIdentifier
-    required_permission: Permission | None = Permission.EarningsPermission
+    accepted_permissions: set[Permission] | None = {
+        Permission.EarningsPermission,
+        Permission.TranscriptsPermission,
+    }
 
     def _run(self, identifier: str) -> dict:
         ticker = self.kfinance_client.ticker(identifier)

kfinance/tool_calling/get_merger_info_from_transaction_id.py

@@ -15,7 +15,7 @@ class GetMergerInfoFromTransactionId(KfinanceTool):
     name: str = "get_merger_info_from_transaction_id"
     description: str = '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?"'
     args_schema: Type[BaseModel] = GetMergerInfoFromTransactionIdArgs
-    required_permission: Permission | None = Permission.MergersPermission
+    accepted_permissions: set[Permission] | None = {Permission.MergersPermission}
 
     def _run(self, transaction_id: int) -> dict:
         merger_or_acquisition = MergerOrAcquisition(

kfinance/tool_calling/get_mergers_from_identifier.py

@@ -10,7 +10,7 @@ class GetMergersFromIdentifier(KfinanceTool):
     name: str = "get_mergers_from_identifier"
     description: str = 'Get the transaction IDs that involve the given identifier. For example, "Which companies did Microsoft purchase?" or "Which company bought Ben & Jerrys?"'
     args_schema: Type[BaseModel] = ToolArgsWithIdentifier
-    required_permission: Permission | None = Permission.MergersPermission
+    accepted_permissions: set[Permission] | None = {Permission.MergersPermission}
 
     def _run(self, identifier: str) -> dict:
         ticker = self.kfinance_client.ticker(identifier)

kfinance/tool_calling/get_n_quarters_ago.py

@@ -16,7 +16,7 @@ class GetNQuartersAgo(KfinanceTool):
         "Get the year and quarter corresponding to [n] quarters before the current quarter."
     )
     args_schema: Type[BaseModel] = GetNQuartersAgoArgs
-    required_permission: Permission | None = None
+    accepted_permissions: set[Permission] | None = None
 
     def _run(self, n: int) -> YearAndQuarter:
         return self.kfinance_client.get_n_quarters_ago(n)

kfinance/tool_calling/get_next_earnings.py

@@ -11,7 +11,10 @@ class GetNextEarnings(KfinanceTool):
     name: str = "get_next_earnings"
     description: str = "Get the next earnings for a given identifier. Returns a dictionary with 'name' (str), 'key_dev_id' (int), and 'datetime' (str in ISO 8601 format with UTC timezone) attributes."
     args_schema: Type[BaseModel] = ToolArgsWithIdentifier
-    required_permission: Permission | None = Permission.EarningsPermission
+    accepted_permissions: set[Permission] | None = {
+        Permission.EarningsPermission,
+        Permission.TranscriptsPermission,
+    }
 
     def _run(self, identifier: str) -> dict:
         ticker = self.kfinance_client.ticker(identifier)

kfinance/tool_calling/get_prices_from_identifier.py

@@ -26,7 +26,7 @@ class GetPricesFromIdentifier(KfinanceTool):
     name: str = "get_prices_from_identifier"
     description: str = "Get the historical open, high, low, and close prices, and volume of an identifier between inclusive start_date and inclusive end date. When requesting the most recent values, leave start_date and end_date empty."
     args_schema: Type[BaseModel] = GetPricesFromIdentifierArgs
-    required_permission: Permission | None = Permission.PricingPermission
+    accepted_permissions: set[Permission] | None = {Permission.PricingPermission}
 
     def _run(
         self,

kfinance/tool_calling/get_segments_from_identifier.py

@@ -20,7 +20,7 @@ class GetSegmentsFromIdentifier(KfinanceTool):
     name: str = "get_segments_from_identifier"
     description: str = "Get the templated segments associated with an identifier."
     args_schema: Type[BaseModel] = GetSegmentsFromIdentifierArgs
-    required_permission: Permission | None = Permission.SegmentsPermission
+    accepted_permissions: set[Permission] | None = {Permission.SegmentsPermission}
 
     def _run(
         self,

kfinance/tool_calling/get_transcript.py

@@ -16,7 +16,7 @@ class GetTranscript(KfinanceTool):
     name: str = "get_transcript"
     description: str = "Get the raw transcript text for an earnings call by key dev ID."
     args_schema: Type[BaseModel] = GetTranscriptArgs
-    required_permission: Permission | None = Permission.EarningsPermission
+    accepted_permissions: set[Permission] | None = {Permission.TranscriptsPermission}
 
     def _run(self, key_dev_id: int) -> str:
         transcript = self.kfinance_client.transcript(key_dev_id)

kfinance/tool_calling/resolve_identifier.py

@@ -12,7 +12,7 @@ class ResolveIdentifier(KfinanceTool):
         "Get the company_id, security_id, and trading_item_id associated with an identifier."
     )
     args_schema: Type[BaseModel] = ToolArgsWithIdentifier
-    required_permission: Permission | None = None
+    accepted_permissions: set[Permission] | None = None
 
     def _run(self, identifier: str) -> dict[str, int]:
         return self.kfinance_client.ticker(identifier).id_triple._asdict()

kfinance/tool_calling/shared_models.py

@@ -16,7 +16,9 @@ class KfinanceTool(BaseTool):
 
     kfinance_client: Client
     args_schema: Type[BaseModel]
-    required_permission: Permission | None
+    accepted_permissions: set[Permission] | None = Field(
+        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")
 
@@ -38,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.3'
-__version_tuple__ = version_tuple = (2, 6, 3)
+__version__ = version = '2.7.0'
+__version_tuple__ = version_tuple = (2, 7, 0)

kensho_kfinance-2.6.3.dist-info/RECORD

@@ -1,54 +0,0 @@
-kensho_kfinance-2.6.3.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-2.6.3.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=ndCVbkomHlJ7kB7FoNB3N17A97hrPPtu02dxh-JBdJA,1927
-kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/batch_request_handling.py,sha256=G9rhpgQaCdb5C1dsfuJip8383iszibcOJ5k8gxld-tQ,5001
-kfinance/constants.py,sha256=jaHsTXEmGKLp55x1_ob_MA-GVn_hua5B6RZCbujKWz0,49401
-kfinance/fetch.py,sha256=QyQjL2t9Z_tT1DD_Xzal59URH7QtnrpLQywcHSFtoWA,26691
-kfinance/kfinance.py,sha256=WNw6hR7eIKVFM5iBtGrArJcOowange_ed5_PAc0aLzE,72768
-kfinance/mcp.py,sha256=MbktclVfBOEwfe-eR7kPaTXopMJmn_8RMlf4Jx5CXKU,3689
-kfinance/meta_classes.py,sha256=bUkksl5a9NkQQWmSM2XIWP3jsmmP4ZAfvSxPW5tRZg4,21492
-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=4cULVvUTy4PTYSp0nJA5kcg2kfWGvGZeFR9hHzx74PU,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
-kfinance/tests/test_batch_requests.py,sha256=2A0XnDDDSPkq0-BuiRryZx8b9_jBDtjYd2kWxFVyRew,10140
-kfinance/tests/test_client.py,sha256=O7icZCSDhlQ9WGhzoXlpiSvbuA-mQNJHBYVsilyP_dE,2209
-kfinance/tests/test_example_notebook.py,sha256=XHwDKw2avyMonTmi3snCcFWNfZhEJOkpBGOZNrMLrhk,6470
-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/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=u9FNRiNYiwsFXuWJNOsaW8msMrAYqGcMp-blPG-cIfg,1607
-kfinance/tool_calling/get_business_relationship_from_identifier.py,sha256=CipXvyqEjPm6BXYP0CA9Kp1BIyiIEm7abp85x1zXRV4,1472
-kfinance/tool_calling/get_capitalization_from_identifier.py,sha256=TdWdJDeI-jSL-1YfhnnwIA9D1SXobidvoHrjK42QmqQ,1521
-kfinance/tool_calling/get_competitors_from_identifier.py,sha256=sCmimHZexWzvKE-13TOAErKKUoyBChxp9h_oa3W0Duo,1051
-kfinance/tool_calling/get_cusip_from_ticker.py,sha256=houhGCYXoSzaaTtCvOBf3pPsYiSbcV1Ej5nAyGuMWcU,644
-kfinance/tool_calling/get_earnings.py,sha256=7xavYvqwq4fO0vpks25eDM87bCYwZxEQSwgT0I8jAok,1165
-kfinance/tool_calling/get_financial_line_item_from_identifier.py,sha256=TgZCHOKwMVUc0c7k5RGN5FWfXEM9cmJXTrDWiGudad8,2153
-kfinance/tool_calling/get_financial_statement_from_identifier.py,sha256=QM3DfctPq8gMJzRZl508Qc184MWq_o6gwGNZEwbYopg,1906
-kfinance/tool_calling/get_history_metadata_from_identifier.py,sha256=kKIInfRC1Plf-Wnx9cmaJ46RRABm6zn3F5_8qAdqrBg,728
-kfinance/tool_calling/get_info_from_identifier.py,sha256=PRhSYpYs_iUcIVFGYCMN_7QJyhewua7c7pqngPIp-qg,766
-kfinance/tool_calling/get_isin_from_ticker.py,sha256=2fJBcA-rNGbVOQmQ7qJEYxqejQwJ6nyWOBSFlzxG7dY,638
-kfinance/tool_calling/get_latest.py,sha256=btGeVBmvX5QJutzrKfE6spatGGejDuHxtq53NoAaGNk,786
-kfinance/tool_calling/get_latest_earnings.py,sha256=pQdExGdztGY3pHcak0bd6ULNf_ROPc91bJ7zAVSKQkk,1117
-kfinance/tool_calling/get_merger_info_from_transaction_id.py,sha256=8aMktxIs89czDRCn4o7LcUmoTO8ueUDI40nXHo6rNZY,3142
-kfinance/tool_calling/get_mergers_from_identifier.py,sha256=9tCaSrJsK3-i0ZDNKAJRhE-nRdJvQxTbrZbvVY0YmQw,1702
-kfinance/tool_calling/get_n_quarters_ago.py,sha256=A0ilwPKUqU0YYQSz3gNsVF0Jy4YttXrSaDhYj7y8GHA,713
-kfinance/tool_calling/get_next_earnings.py,sha256=knzQw-m-hscCvTuDUXG9v_dObKJBGn5BbDZWGKHKQcw,1097
-kfinance/tool_calling/get_prices_from_identifier.py,sha256=ViJkwLDvStB7grc8RuoKSDXQM399Wru4-OY3E8k1l_U,1882
-kfinance/tool_calling/get_segments_from_identifier.py,sha256=xDi6GF0GgZwATaxw9me64BDXVrmopKQed6j3HfXSASA,1865
-kfinance/tool_calling/get_transcript.py,sha256=eB-IsRwD-mllsMOYRZbH35caQ1Y3teKft0tmI9nVL-A,756
-kfinance/tool_calling/prompts.py,sha256=Yw1DJIMh90cjL-8q6_RMRiSjCtFDXvJAy7QiV5_uAU8,911
-kfinance/tool_calling/resolve_identifier.py,sha256=npslr6bBCu0qEDV1-8d24F5OC3nQ1KBMphuMbHVC1AU,626
-kfinance/tool_calling/shared_models.py,sha256=loNoVFVyQnnpHLUIjkR6P9flGNbzp6kkGpL5hT37Sdg,2666
-kensho_kfinance-2.6.3.dist-info/METADATA,sha256=RLO0Q9-6duwKJmS65JFtry8_DFpGXKZb2Ovvk33wlcI,6197
-kensho_kfinance-2.6.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kensho_kfinance-2.6.3.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-2.6.3.dist-info/RECORD,,