kensho-kfinance 2.0.0__py3-none-any.whl → 2.1.2__py3-none-any.whl

kfinance/kfinance.py

@@ -22,6 +22,7 @@ from .batch_request_handling import add_methods_of_singular_class_to_iterable_cl
 from .constants import (
     HistoryMetadata,
     IdentificationTriple,
+    IndustryClassification,
     LatestPeriods,
     Periodicity,
     YearAndQuarter,
@@ -233,10 +234,9 @@ class Company(CompanyFunctionsMetaClass):
         primary_security_id = self.kfinance_api_client.fetch_primary_security(self.company_id)[
             "primary_security"
         ]
-        self.primary_security = Security(
+        return Security(
             kfinance_api_client=self.kfinance_api_client, security_id=primary_security_id
         )
-        return self.primary_security
 
     @cached_property
     def securities(self) -> Securities:
@@ -246,10 +246,7 @@ class Company(CompanyFunctionsMetaClass):
         :rtype: Securities
         """
         security_ids = self.kfinance_api_client.fetch_securities(self.company_id)["securities"]
-        self.securities = Securities(
-            kfinance_api_client=self.kfinance_api_client, security_ids=security_ids
-        )
-        return self.securities
+        return Securities(kfinance_api_client=self.kfinance_api_client, security_ids=security_ids)
 
     @cached_property
     def latest_earnings_call(self) -> None:
@@ -268,8 +265,7 @@ class Company(CompanyFunctionsMetaClass):
         :return: a dict with containing: name, status, type, simple industry, number of employees, founding date, webpage, address, city, zip code, state, country, & iso_country
         :rtype: dict
         """
-        self.info = self.kfinance_api_client.fetch_info(self.company_id)
-        return self.info
+        return self.kfinance_api_client.fetch_info(self.company_id)
 
     @property
     def name(self) -> str:
@@ -539,6 +535,23 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
                 "Neither an identifier nor an identification triple (company id, security id, & trading item id) were passed in"
             )
 
+    @property
+    def id_triple(self) -> IdentificationTriple:
+        """Returns a unique identifier triple for the Ticker object."""
+        return IdentificationTriple(
+            company_id=self.company_id,
+            security_id=self.security_id,
+            trading_item_id=self.trading_item_id,
+        )
+
+    def __hash__(self) -> int:
+        return hash(self.id_triple)
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, Ticker):
+            return False
+        return self.id_triple == other.id_triple
+
     def __str__(self) -> str:
         """String representation for the ticker object"""
         str_attributes = []
@@ -991,13 +1004,33 @@ class Tickers(set):
         super().__init__(
             Ticker(
                 kfinance_api_client=kfinance_api_client,
-                company_id=id_triple["company_id"],
-                security_id=id_triple["security_id"],
-                trading_item_id=id_triple["trading_item_id"],
+                company_id=id_triple.company_id,
+                security_id=id_triple.security_id,
+                trading_item_id=id_triple.trading_item_id,
             )
             for id_triple in id_triples
         )
 
+    def intersection(self, *s: Iterable[Any]) -> Tickers:
+        """Returns the intersection of Tickers objects"""
+        for obj in s:
+            if not isinstance(obj, Tickers):
+                raise ValueError("Can only intersect Tickers object with other Tickers object.")
+
+        self_triples = {t.id_triple for t in self}
+        set_triples = []
+
+        for ticker_set in s:
+            set_triples.append({t.id_triple for t in ticker_set})
+        common_triples = self_triples.intersection(*set_triples)
+
+        return Tickers(kfinance_api_client=self.kfinance_api_client, id_triples=common_triples)
+
+    def __and__(self, other: Any) -> "Tickers":
+        if not isinstance(other, Tickers):
+            raise ValueError("Can only combine Tickers objects with other Tickers objects.")
+        return self.intersection(other)
+
     def companies(self) -> Companies:
         """Build a group of company objects from the group of tickers
 
@@ -1126,7 +1159,16 @@ class Client:
         if self._tools is None:
             from kfinance.tool_calling import ALL_TOOLS
 
-            self._tools = [t(kfinance_client=self) for t in ALL_TOOLS]  # type: ignore[call-arg]
+            self._tools = []
+            # Add tool to _tools if the user has permissions to use it.
+            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
+                ):
+                    self._tools.append(tool)
+
         return self._tools
 
     @property
@@ -1212,31 +1254,90 @@ class Client:
         state_iso_code: Optional[str] = None,
         simple_industry: Optional[str] = None,
         exchange_code: Optional[str] = None,
+        sic: Optional[str] = None,
+        naics: Optional[str] = None,
+        nace: Optional[str] = None,
+        anzsic: Optional[str] = None,
+        spcapiqetf: Optional[str] = None,
+        spratings: Optional[str] = None,
+        gics: Optional[str] = None,
     ) -> Tickers:
-        """Generate tickers object representing the collection of Tickers that meet all the supplied parameters
+        """Generate a Tickers object representing the collection of Tickers that meet all the supplied parameters.
 
-        One of country_iso_code, simple_industry, or exchange_code must be supplied. A parameter set to None is not used to filter on
+        One of country_iso_code, simple_industry, or exchange_code must be supplied, or one of sic, naics, nace, anzsic, spcapiqetf, spratings, or gics.
 
-        :param country_iso_code: The ISO 3166-1 Alpha-2 or Alpha-3 code that represent the primary country the firm is based in. It default None
+        :param country_iso_code: The ISO 3166-1 Alpha-2 or Alpha-3 code that represent the primary country the firm is based in. It defaults to None
         :type country_iso_code: str, optional
-        :param state_iso_code: The ISO 3166-2 Alpha-2 code that represents the primary subdivision of the country the firm the based in. Not all ISO 3166-2 codes are supported as S&P doesn't maintain the full list but a feature request for the full list is submitted to S&P product. Requires country_iso_code also to have a value other then None. It default None
+        :param state_iso_code: The ISO 3166-2 Alpha-2 code that represents the primary subdivision of the country the firm the based in. Not all ISO 3166-2 codes are supported as S&P doesn't maintain the full list but a feature request for the full list is submitted to S&P product. Requires country_iso_code also to have a value other then None. It defaults to None
         :type state_iso_code: str, optional
-        :param simple_industry: The S&P CIQ Simple Industry defined in ciqSimpleIndustry in XPF. It default None
+        :param simple_industry: The S&P CIQ Simple Industry defined in ciqSimpleIndustry in XPF. It defaults to None
         :type simple_industry: str, optional
-        :param exchange_code: The exchange code for the primary equity listing exchange of the firm. It default None
+        :param exchange_code: The exchange code for the primary equity listing exchange of the firm. It defaults to None
         :type exchange_code: str, optional
-        :return: A tickers object that is the group of Ticker objects meeting all the supplied parameters
+        :param sic: The SIC industry code. It defaults to None
+        :type sic: str, optional
+        :param naics: The NAICS industry code. It defaults to None
+        :type naics: str, optional
+        :param nace: The NACE industry code. It defaults to None
+        :type nace: str, optional
+        :param anzsic: The ANZSIC industry code. It defaults to None
+        :type anzsic: str, optional
+        :param spcapiqetf: The S&P CapitalIQ ETF industry code. It defaults to None
+        :type spcapiqetf: str, optional
+        :param spratings: The S&P Ratings industry code. It defaults to None
+        :type spratings: str, optional
+        :param gics: The GICS code. It defaults to None
+        :type gics: str, optional
+        :return: A Tickers object that is the intersection of Ticker objects meeting all the supplied parameters.
         :rtype: Tickers
         """
-        return Tickers(
-            kfinance_api_client=self.kfinance_api_client,
-            id_triples=self.kfinance_api_client.fetch_ticker_combined(
-                country_iso_code=country_iso_code,
-                state_iso_code=state_iso_code,
-                simple_industry=simple_industry,
-                exchange_code=exchange_code,
-            )["tickers"],
-        )
+        # Create a list to accumulate the fetched ticker sets
+        ticker_sets: list[Tickers] = []
+
+        # Map the parameters to the industry_dict, pass the values in as the key.
+        industry_dict = {
+            "sic": sic,
+            "naics": naics,
+            "nace": nace,
+            "anzsic": anzsic,
+            "spcapiqetf": spcapiqetf,
+            "spratings": spratings,
+            "gics": gics,
+        }
+
+        if any(
+            parameter is not None
+            for parameter in [country_iso_code, state_iso_code, simple_industry, exchange_code]
+        ):
+            ticker_sets.append(
+                Tickers(
+                    kfinance_api_client=self.kfinance_api_client,
+                    id_triples=self.kfinance_api_client.fetch_ticker_combined(
+                        country_iso_code=country_iso_code,
+                        state_iso_code=state_iso_code,
+                        simple_industry=simple_industry,
+                        exchange_code=exchange_code,
+                    ),
+                )
+            )
+
+        for key, value in industry_dict.items():
+            if value is not None:
+                ticker_sets.append(
+                    Tickers(
+                        kfinance_api_client=self.kfinance_api_client,
+                        id_triples=self.kfinance_api_client.fetch_ticker_from_industry_code(
+                            industry_code=value,
+                            industry_classification=IndustryClassification(key),
+                        ),
+                    )
+                )
+
+        if not ticker_sets:
+            return Tickers(kfinance_api_client=self.kfinance_api_client, id_triples=set())
+
+        common_ticker_elements = Tickers.intersection(*ticker_sets)
+        return common_ticker_elements
 
     def company(self, company_id: int) -> Company:
         """Generate the Company object from company_id

kfinance/meta_classes.py

@@ -1,8 +1,9 @@
 from datetime import datetime
-from functools import cache, cached_property
+from functools import cached_property
 import logging
 from typing import TYPE_CHECKING, Any, Callable, Literal, Optional
 
+from cachetools import LRUCache, cached
 import numpy as np
 import pandas as pd
 
@@ -46,7 +47,7 @@ class CompanyFunctionsMetaClass:
         if end_quarter and not (1 <= end_quarter <= 4):
             raise ValueError("end_qtr is out of range 1 to 4")
 
-    @cache
+    @cached(cache=LRUCache(maxsize=100))
     def statement(
         self,
         statement_type: str,
@@ -85,7 +86,7 @@ class CompanyFunctionsMetaClass:
 
     def income_statement(
         self,
-        period_type: Optional[str] = None,
+        period_type: Optional[PeriodType] = None,
         start_year: Optional[int] = None,
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
@@ -103,7 +104,7 @@ class CompanyFunctionsMetaClass:
 
     def income_stmt(
         self,
-        period_type: Optional[str] = None,
+        period_type: Optional[PeriodType] = None,
         start_year: Optional[int] = None,
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
@@ -121,7 +122,7 @@ class CompanyFunctionsMetaClass:
 
     def balance_sheet(
         self,
-        period_type: Optional[str] = None,
+        period_type: Optional[PeriodType] = None,
         start_year: Optional[int] = None,
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
@@ -139,7 +140,7 @@ class CompanyFunctionsMetaClass:
 
     def cash_flow(
         self,
-        period_type: Optional[str] = None,
+        period_type: Optional[PeriodType] = None,
         start_year: Optional[int] = None,
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
@@ -157,7 +158,7 @@ class CompanyFunctionsMetaClass:
 
     def cashflow(
         self,
-        period_type: Optional[str] = None,
+        period_type: Optional[PeriodType] = None,
         start_year: Optional[int] = None,
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
@@ -173,7 +174,7 @@ class CompanyFunctionsMetaClass:
             end_quarter=end_quarter,
         )
 
-    @cache
+    @cached(cache=LRUCache(maxsize=100))
     def line_item(
         self,
         line_item: str,

kfinance/tests/conftest.py

@@ -0,0 +1,32 @@
+from datetime import datetime
+
+import pytest
+from requests_mock import Mocker
+
+from kfinance.kfinance import Client
+
+
+SPGI_COMPANY_ID = 21719
+SPGI_SECURITY_ID = 2629107
+SPGI_TRADING_ITEM_ID = 2629108
+
+
+@pytest.fixture
+def mock_client(requests_mock: Mocker) -> Client:
+    """Create a KFinanceApiClient with a mock response for the SPGI id triple."""
+
+    client = Client(refresh_token="foo")
+    # Set access token so that the client doesn't try to fetch it.
+    client.kfinance_api_client._access_token = "foo"  # noqa: SLF001
+    client.kfinance_api_client._access_token_expiry = datetime(2100, 1, 1).timestamp()  # noqa: SLF001
+
+    # Create a mock for the SPGI id triple.
+    requests_mock.get(
+        url="https://kfinance.kensho.com/api/v1/id/SPGI",
+        json={
+            "trading_item_id": SPGI_TRADING_ITEM_ID,
+            "security_id": SPGI_SECURITY_ID,
+            "company_id": SPGI_COMPANY_ID,
+        },
+    )
+    return client

kfinance/tests/test_batch_requests.py

@@ -34,8 +34,13 @@ class TestTradingItem(TestCase):
     def test_batch_request_property(self, m):
         """GIVEN a kfinance group object like Companies
         WHEN we batch request a 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."""
+        THEN the batch request completes successfully, and we get back a mapping of
+        company objects to the corresponding values.
+
+        Note: This test also checks that multiple tasks can be submitted. In the
+        first implementation, we used the threadpool context manager, which shuts down
+        the threadpool on __exit__ and prevented further tasks from getting submitted.
+        """
 
         m.get(
             "https://kfinance.kensho.com/api/v1/info/1001",
@@ -52,12 +57,13 @@ class TestTradingItem(TestCase):
             },
         )
 
-        companies = Companies(self.kfinance_api_client, [1001, 1002])
-        result = companies.city
-        id_based_result = self.company_object_keys_as_company_id(result)
+        for _ in range(3):
+            companies = Companies(self.kfinance_api_client, [1001, 1002])
+            result = companies.city
+            id_based_result = self.company_object_keys_as_company_id(result)
 
-        expected_id_based_result = {1001: "Mock City A", 1002: "Mock City B"}
-        self.assertDictEqual(id_based_result, expected_id_based_result)
+            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):

kfinance/tests/test_client.py

@@ -0,0 +1,54 @@
+from unittest.mock import Mock
+
+import pytest
+
+from kfinance.constants import Permission
+from kfinance.kfinance import Client
+from kfinance.tool_calling import (
+    GetBusinessRelationshipFromIdentifier,
+    GetFinancialStatementFromIdentifier,
+    GetLatest,
+)
+
+
+class TestLangchainTools:
+    @pytest.mark.parametrize(
+        "fetch_value, parsed_permissions",
+        [
+            pytest.param(["RelationshipPermission"], {Permission.RelationshipPermission}),
+            pytest.param([], set(), id="empty permissions don't raise."),
+            pytest.param(
+                ["InvalidPermission"], set(), id="invalid permissions get logged but don't raise."
+            ),
+        ],
+    )
+    def test_user_permissions(
+        self, fetch_value: list[str], parsed_permissions: set[Permission], mock_client: Client
+    ) -> None:
+        """
+        WHEN we fetch user permissions from the fetch_permissions endpoint
+        THEN we correctly parse those permission strings into Permission enums.
+        """
+        mock_client.kfinance_api_client.fetch_permissions = Mock()
+        mock_client.kfinance_api_client.fetch_permissions.return_value = {
+            "permissions": fetch_value
+        }
+
+        assert mock_client.kfinance_api_client.user_permissions == parsed_permissions
+
+    def test_permission_filtering(self, mock_client: Client):
+        """
+        GIVEN a user with limited permissions
+        WHEN we filter tools by permissions
+        THEN we only return tools that either don't require permissions or tools that the user
+            specifically has access to.
+        """
+
+        mock_client.kfinance_api_client._user_permissions = {Permission.RelationshipPermission}  # noqa: SLF001
+        tool_classes = [type(t) for t in mock_client.langchain_tools]
+        # User should have access to GetBusinessRelationshipFromIdentifier
+        assert GetBusinessRelationshipFromIdentifier 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_fetch.py

@@ -1,5 +1,5 @@
 from unittest import TestCase
-from unittest.mock import Mock
+from unittest.mock import MagicMock
 
 import pytest
 
@@ -10,7 +10,7 @@ from kfinance.fetch import KFinanceApiClient
 def build_mock_api_client() -> KFinanceApiClient:
     """Create a KFinanceApiClient with mocked-out fetch function."""
     kfinance_api_client = KFinanceApiClient(refresh_token="fake_refresh_token")
-    kfinance_api_client.fetch = Mock()
+    kfinance_api_client.fetch = MagicMock()
     return kfinance_api_client
 
 
@@ -250,3 +250,9 @@ class TestMarketCap:
             company_id=company_id, start_date=start_date, end_date=end_date
         )
         client.fetch.assert_called_with(expected_fetch_url)
+
+    def test_fetch_permissions(self):
+        client = build_mock_api_client()
+        expected_fetch_url = f"{client.url_base}users/permissions"
+        client.fetch_permissions()
+        client.fetch.assert_called_with(expected_fetch_url)

kfinance/tests/test_group_objects.py

@@ -0,0 +1,32 @@
+from unittest.mock import Mock
+
+from kfinance.kfinance import Client, IdentificationTriple, Tickers
+
+
+class TestTickers:
+    def test_tickers(self, mock_client: Client):
+        """
+        WHEN the client requests tickers using multiple filters
+        THEN only tickers matching all filter criteria are returned
+        """
+        ticker_1 = IdentificationTriple(company_id=1, security_id=1, trading_item_id=1)
+        ticker_2 = IdentificationTriple(company_id=2, security_id=2, trading_item_id=2)
+        ticker_3 = IdentificationTriple(company_id=3, security_id=3, trading_item_id=3)
+        expected_intersection = Tickers(
+            kfinance_api_client=mock_client.kfinance_api_client, id_triples=[ticker_2]
+        )
+        # tickers() calls both fetch_ticker_combined and fetch_ticker_from_industry_code so we set two different return values to test intersection()
+        mock_client.kfinance_api_client.fetch_ticker_combined = Mock()
+        mock_client.kfinance_api_client.fetch_ticker_combined.return_value = [ticker_1, ticker_2]
+        mock_client.kfinance_api_client.fetch_ticker_from_industry_code = Mock()
+        mock_client.kfinance_api_client.fetch_ticker_from_industry_code.return_value = [
+            ticker_3,
+            ticker_2,
+        ]
+        tickers_object = mock_client.tickers(
+            country_iso_code="USA", state_iso_code="FL", sic="6141", gics="2419512"
+        )
+        # fetch_ticker_from_industry_code should be called once for SIC and GICS
+        assert mock_client.kfinance_api_client.fetch_ticker_from_industry_code.call_count == 2
+        # Only the common tickers are returned
+        assert tickers_object == expected_intersection

kfinance/tests/test_tools.py

@@ -1,12 +1,12 @@
 from datetime import date, datetime
 
 from langchain_core.utils.function_calling import convert_to_openai_tool
-import pytest
 from requests_mock import Mocker
 import time_machine
 
 from kfinance.constants import BusinessRelationshipType, Capitalization, StatementType
 from kfinance.kfinance import Client
+from kfinance.tests.conftest import SPGI_COMPANY_ID, SPGI_SECURITY_ID, SPGI_TRADING_ITEM_ID
 from kfinance.tool_calling import (
     GetCompanyIdFromIdentifier,
     GetEarningsCallDatetimesFromIdentifier,
@@ -43,32 +43,6 @@ from kfinance.tool_calling.get_prices_from_identifier import GetPricesFromIdenti
 from kfinance.tool_calling.shared_models import ToolArgsWithIdentifier
 
 
-SPGI_COMPANY_ID = 21719
-SPGI_SECURITY_ID = 2629107
-SPGI_TRADING_ITEM_ID = 2629108
-
-
-@pytest.fixture
-def mock_client(requests_mock: Mocker) -> Client:
-    """Create a KFinanceApiClient with a mock response for the SPGI id triple."""
-
-    client = Client(refresh_token="foo")
-    # Set access token so that the client doesn't try to fetch it.
-    client.kfinance_api_client._access_token = "foo"  # noqa: SLF001
-    client.kfinance_api_client._access_token_expiry = datetime(2100, 1, 1).timestamp()  # noqa: SLF001
-
-    # Create a mock for the SPGI id triple.
-    requests_mock.get(
-        url="https://kfinance.kensho.com/api/v1/id/SPGI",
-        json={
-            "trading_item_id": SPGI_TRADING_ITEM_ID,
-            "security_id": SPGI_SECURITY_ID,
-            "company_id": SPGI_COMPANY_ID,
-        },
-    )
-    return client
-
-
 class TestGetBusinessRelationshipFromIdentifier:
     def test_get_business_relationship_from_identifier(
         self, requests_mock: Mocker, mock_client: Client

kfinance/tool_calling/get_business_relationship_from_identifier.py

@@ -2,7 +2,7 @@ from typing import Type
 
 from pydantic import BaseModel
 
-from kfinance.constants import BusinessRelationshipType
+from kfinance.constants import BusinessRelationshipType, Permission
 from kfinance.kfinance import BusinessRelationships
 from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
 
@@ -16,6 +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
 
     def _run(self, identifier: str, business_relationship: BusinessRelationshipType) -> dict:
         ticker = self.kfinance_client.ticker(identifier)

kfinance/tool_calling/get_capitalization_from_identifier.py

@@ -2,7 +2,7 @@ from datetime import date
 
 from pydantic import Field
 
-from kfinance.constants import Capitalization
+from kfinance.constants import Capitalization, Permission
 from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
 
 
@@ -21,6 +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
 
     def _run(
         self,

kfinance/tool_calling/get_company_id_from_identifier.py

@@ -2,6 +2,7 @@ from typing import Type
 
 from pydantic import BaseModel
 
+from kfinance.constants import Permission
 from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
 
 
@@ -9,6 +10,7 @@ class GetCompanyIdFromIdentifier(KfinanceTool):
     name: str = "get_company_id_from_identifier"
     description: str = "Get the company id associated with an identifier."
     args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+    required_permission: Permission | None = None
 
     def _run(self, identifier: str) -> int:
         return self.kfinance_client.ticker(identifier).company_id

kfinance/tool_calling/get_cusip_from_ticker.py

@@ -2,6 +2,7 @@ from typing import Type
 
 from pydantic import BaseModel, Field
 
+from kfinance.constants import Permission
 from kfinance.tool_calling.shared_models import KfinanceTool
 
 
@@ -13,6 +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
 
     def _run(self, ticker_str: str) -> str:
         return self.kfinance_client.ticker(ticker_str).cusip

kfinance/tool_calling/get_earnings_call_datetimes_from_identifier.py

@@ -3,6 +3,7 @@ from typing import Type
 
 from pydantic import BaseModel
 
+from kfinance.constants import Permission
 from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
 
 
@@ -10,6 +11,7 @@ class GetEarningsCallDatetimesFromIdentifier(KfinanceTool):
     name: str = "get_earnings_call_datetimes_from_identifier"
     description: str = "Get earnings call datetimes associated with an identifier."
     args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+    required_permission: Permission | None = Permission.EarningsPermission
 
     def _run(self, identifier: str) -> str:
         ticker = self.kfinance_client.ticker(identifier)

kfinance/tool_calling/get_financial_line_item_from_identifier.py

@@ -2,7 +2,7 @@ from typing import Literal, Type
 
 from pydantic import BaseModel, Field
 
-from kfinance.constants import LINE_ITEM_NAMES_AND_ALIASES, PeriodType
+from kfinance.constants import LINE_ITEM_NAMES_AND_ALIASES, PeriodType, Permission
 from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
 
 
@@ -24,6 +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
 
     def _run(
         self,

kfinance/tool_calling/get_financial_statement_from_identifier.py

@@ -2,7 +2,7 @@ from typing import Literal, Type
 
 from pydantic import BaseModel, Field
 
-from kfinance.constants import PeriodType, StatementType
+from kfinance.constants import PeriodType, Permission, StatementType
 from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
 
 
@@ -20,6 +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
 
     def _run(
         self,

kfinance/tool_calling/get_history_metadata_from_identifier.py

@@ -2,7 +2,7 @@ from typing import Type
 
 from pydantic import BaseModel
 
-from kfinance.constants import HistoryMetadata
+from kfinance.constants import HistoryMetadata, Permission
 from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
 
 
@@ -10,6 +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
 
     def _run(self, identifier: str) -> HistoryMetadata:
         return self.kfinance_client.ticker(identifier).history_metadata