kensho-kfinance 2.0.1__py3-none-any.whl → 2.2.2__py3-none-any.whl

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_example_notebook.py

@@ -0,0 +1,194 @@
+from pathlib import Path
+import subprocess
+import sys
+from textwrap import dedent
+import uuid
+
+from nbconvert.preprocessors import ExecutePreprocessor
+import nbformat
+import pytest
+
+
+@pytest.fixture(scope="session")
+def jupyter_kernel_name() -> str:
+    """Create a jupyter kernel for a test run and yield its name.
+
+    The kernel gets removed at the end of the test run.
+    """
+
+    kernel_name = f"test-kfinance-kernel-{uuid.uuid4().hex[:8]}"
+
+    # Install a new kernel pointing to the current interpreter.
+    subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "ipykernel",
+            "install",
+            "--user",
+            "--name",
+            kernel_name,
+            "--display-name",
+            f"Python ({kernel_name})",
+        ],
+        check=True,
+    )
+
+    yield kernel_name
+
+    # Remove the kernel after the test.
+    subprocess.run(
+        [sys.executable, "-m", "jupyter", "kernelspec", "uninstall", "-f", kernel_name], check=True
+    )
+
+
+def test_run_notebook(jupyter_kernel_name: str):
+    """
+    GIVEN the usage_examples.ipynb notebook
+    WHEN the notebook gets run with a mock client and mock responses
+    THEN all cells of the notebook complete without errors.
+    """
+
+    # Create a replacement startup cell for the normal notebook client init.
+    # This cell contains:
+    # - setup of a mock client
+    # - mocks for all calls made by the client while executing the notebook
+    startup_cell_code = dedent("""
+        from datetime import datetime
+        from kfinance.kfinance import Client
+        kfinance_client = Client(refresh_token="foo")
+        api_client = kfinance_client.kfinance_api_client
+        # Set access token so that the client doesn't try to fetch it.
+        api_client._access_token = "foo"
+        api_client._access_token_expiry = datetime(2100, 1, 1).timestamp()
+
+        # Mock out all necessary requests with requests_mock
+        import requests_mock
+        mocker = requests_mock.Mocker()
+        mocker.start()
+
+        id_triple_resp = {
+            "trading_item_id": 2629108,
+            "security_id": 2629107,
+            "company_id": 21719
+        }
+
+        # spgi = kfinance_client.ticker("SPGI")
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/id/SPGI",
+            json=id_triple_resp
+        )
+
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/info/21719",
+            json={"name": "S&P Global Inc."}
+        )
+
+        balance_sheet_resp = {
+            "statements": {
+                "2022Q3": {"Cash And Equivalents": "1387000000.000000"},
+                "2022Q4": {"Cash And Equivalents": "1286000000.000000"}
+            }
+        }
+
+        # spgi.balance_sheet()
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/statements/21719/balance_sheet/none/none/none/none/none",
+            json=balance_sheet_resp
+        )
+
+        # spgi.balance_sheet(period_type=PeriodType.annual, start_year=2010, end_year=2019)
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/statements/21719/balance_sheet/annual/2010/2019/none/none",
+            json=balance_sheet_resp
+        )
+
+        # kfinance_client.ticker("JPM").balance_sheet()
+        # (leads to fetching SPGI balance sheet when requesting JPM because they return the same
+        # company id)
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/id/JPM",
+            json=id_triple_resp
+        )
+
+        # spgi.net_income(period_type=PeriodType.annual, start_year=2010, end_year=2019)
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/line_item/21719/net_income/annual/2010/2019/none/none",
+            json={"line_item": {"2010": "828000000.000000"}}
+        )
+
+        prices_resp = {
+            "prices": [
+                {
+                    "date": "2024-05-20",
+                    "open": "439.540000",
+                    "high": "441.570000",
+                    "low": "437.000000",
+                    "close": "437.740000",
+                    "volume": "1080006"
+                }
+            ]
+        }
+
+        # spgi.history()
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/pricing/2629108/none/none/day/adjusted",
+            json=prices_resp
+        )
+
+        # spgi.history(
+        #     periodicity=Periodicity.month,
+        #     adjusted=False,
+        #     start_date="2010-01-01",
+        #     end_date="2019-12-31"
+        # )
+        mocker.get(
+            url="https://kfinance.kensho.com/api/v1/pricing/2629108/2010-01-01/2019-12-31/month/unadjusted",
+            json=prices_resp
+        )
+
+        # spgi.price_chart(
+        #     periodicity=Periodicity.month,
+        #     adjusted=False,
+        #     start_date="2010-01-01",
+        #     end_date="2019-12-31"
+        # )
+        mocker.get(
+            url='https://kfinance.kensho.com/api/v1/price_chart/2629108/2010-01-01/2019-12-31/month/unadjusted',
+            content=b"",
+            headers={'Content-Type': 'image/png'}
+        )
+        # Mock out image_open so that we don't have to return an actual png.
+        from unittest.mock import MagicMock
+        import kfinance.kfinance
+        kfinance.kfinance.image_open = MagicMock()
+    """)
+
+    # Load the notebook
+    notebook_path = Path(Path(__file__).parent.parent.parent, "usage_examples.ipynb")
+    with notebook_path.open() as f:
+        nb = nbformat.read(f, as_version=4)
+
+    # Set up the notebook executor
+    ep = ExecutePreprocessor(timeout=600, kernel_name=jupyter_kernel_name)
+
+    # Identify the start of the example section
+    example_sections_heading = "## Example functions"
+    examples_start_cell_id = None
+    for idx, cell in enumerate(nb.cells):
+        if cell["source"] == example_sections_heading:
+            examples_start_cell_id = idx
+
+    if not examples_start_cell_id:
+        raise ValueError(
+            f"Did not find a cell with content {example_sections_heading} that "
+            f"indicates the start of the examples."
+        )
+
+    # Combine the startup cell with the start of the examples
+    # i.e. toss everything before the examples start
+    nb.cells = [nbformat.v4.new_code_cell(startup_cell_code)] + nb.cells[examples_start_cell_id:]
+
+    # Run the notebook.
+    # The test passes if the notebook runs without errors.
+    ep.preprocess(nb, {"metadata": {"path": notebook_path.parent}})

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
 
 
@@ -229,6 +229,29 @@ class TestFetchItem(TestCase):
         )
         self.kfinance_api_client.fetch.assert_called_once_with(expected_fetch_url)
 
+    def test_fetch_segments(self) -> None:
+        company_id = 21719
+        segment_type = "business"
+        expected_fetch_url = f"{self.kfinance_api_client.url_base}segments/{company_id}/{segment_type}/none/none/none/none/none"
+        self.kfinance_api_client.fetch_segments(company_id=company_id, segment_type=segment_type)
+        self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
+        period_type = PeriodType.quarterly
+        start_year = 2023
+        end_year = 2023
+        start_quarter = 1
+        end_quarter = 4
+        expected_fetch_url = f"{self.kfinance_api_client.url_base}segments/{company_id}/{segment_type}/{period_type.value}/{start_year}/{end_year}/{start_quarter}/{end_quarter}"
+        self.kfinance_api_client.fetch_segments(
+            company_id=company_id,
+            segment_type=segment_type,
+            period_type=period_type,
+            start_year=start_year,
+            end_year=end_year,
+            start_quarter=start_quarter,
+            end_quarter=end_quarter,
+        )
+        self.kfinance_api_client.fetch.assert_called_with(expected_fetch_url)
+
 
 class TestMarketCap:
     @pytest.mark.parametrize(
@@ -250,3 +273,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_objects.py

@@ -75,6 +75,19 @@ MOCK_COMPANY_DB = {
                 }
             }
         },
+        "segments": {
+            "2024": {
+                "Intelligent Cloud": {"Operating Income": 49584000000.0, "Revenue": 105362000000.0},
+                "More Personal Computing": {
+                    "Operating Income": 19309000000.0,
+                    "Revenue": 62032000000.0,
+                },
+                "Productivity and Business Processes": {
+                    "Operating Income": 40540000000.0,
+                    "Revenue": 77728000000.0,
+                },
+            }
+        },
     }
 }
 
@@ -189,6 +202,19 @@ class MockKFinanceApiClient:
             ]
         }
 
+    def fetch_segments(
+        self,
+        company_id,
+        segment_type,
+        period_type,
+        start_year,
+        end_year,
+        start_quarter,
+        end_quarter,
+    ):
+        """Get a segment"""
+        return MOCK_COMPANY_DB[company_id]
+
 
 class TestTradingItem(TestCase):
     def setUp(self):
@@ -309,6 +335,20 @@ class TestCompany(TestCase):
         revenue = self.msft_company.revenue()
         pd.testing.assert_frame_equal(expected_revenue, revenue)
 
+    def test_business_segments(self) -> None:
+        """test business statement"""
+        rows = []
+        for period, segments in MOCK_COMPANY_DB[msft_company_id]["segments"].items():
+            for segment_name, line_items in segments.items():
+                for line_item, value in line_items.items():
+                    rows.append([period, segment_name, line_item, value])
+        expected_segments = pd.DataFrame(
+            rows, columns=["Year", "Segment Name", "Line Item", "Value"]
+        ).replace(np.nan, None)
+
+        business_segment = self.msft_company.business_segments()
+        pd.testing.assert_frame_equal(expected_segments, business_segment)
+
 
 class TestSecurity(TestCase):
     def setUp(self):

kfinance/tests/test_tools.py

@@ -1,14 +1,13 @@
 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,
     GetFinancialLineItemFromIdentifier,
     GetFinancialStatementFromIdentifier,
@@ -18,8 +17,7 @@ from kfinance.tool_calling import (
     GetLatest,
     GetNQuartersAgo,
     GetPricesFromIdentifier,
-    GetSecurityIdFromIdentifier,
-    GetTradingItemIdFromIdentifier,
+    ResolveIdentifier,
 )
 from kfinance.tool_calling.get_business_relationship_from_identifier import (
     GetBusinessRelationshipFromIdentifier,
@@ -43,32 +41,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
@@ -133,18 +105,6 @@ class TestGetCapitalizationFromIdentifier:
         assert response == expected_response
 
 
-class TestGetCompanyIdFromIdentifier:
-    def test_get_company_id_from_identifier(self, mock_client: Client):
-        """
-        GIVEN the GetCompanyIdFromIdentifier tool
-        WHEN request the company id for SPGI
-        THEN we get back the SPGI company id
-        """
-        tool = GetCompanyIdFromIdentifier(kfinance_client=mock_client)
-        resp = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
-        assert resp == SPGI_COMPANY_ID
-
-
 class TestGetCusipFromTicker:
     def test_get_cusip_from_ticker(self, requests_mock: Mocker, mock_client: Client):
         """
@@ -406,25 +366,17 @@ class TestPricesFromIdentifier:
         assert response == expected_response
 
 
-class TestGetSecurityIdFromIdentifier:
-    def test_get_security_id_from_identifier(self, mock_client: Client):
+class TestResolveIdentifier:
+    def test_resolve_identifier(self, mock_client: Client):
         """
-        GIVEN the GetSecurityIdFromIdentifier tool
-        WHEN we request the security id for SPGI
-        THEN we get back the SPGI primary security id
+        GIVEN the ResolveIdentifier tool
+        WHEN request to resolve SPGI
+        THEN we get back a dict with the SPGI company id, security id, and trading item id
         """
-        tool = GetSecurityIdFromIdentifier(kfinance_client=mock_client)
+        tool = ResolveIdentifier(kfinance_client=mock_client)
         resp = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
-        assert resp == SPGI_SECURITY_ID
-
-
-class TestGetTradingItemIdFromIdentifier:
-    def test_get_security_id_from_identifier(self, mock_client: Client):
-        """
-        GIVEN the GetTradingItemIdFromIdentifier tool
-        WHEN we request the trading item id for SPGI
-        THEN we get back the SPGI primary trading item id
-        """
-        tool = GetTradingItemIdFromIdentifier(kfinance_client=mock_client)
-        resp = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
-        assert resp == SPGI_TRADING_ITEM_ID
+        assert resp == {
+            "company_id": SPGI_COMPANY_ID,
+            "security_id": SPGI_SECURITY_ID,
+            "trading_item_id": SPGI_TRADING_ITEM_ID,
+        }

kfinance/tool_calling/__init__.py

@@ -4,7 +4,6 @@ from kfinance.tool_calling.get_business_relationship_from_identifier import (
     GetBusinessRelationshipFromIdentifier,
 )
 from kfinance.tool_calling.get_capitalization_from_identifier import GetCapitalizationFromIdentifier
-from kfinance.tool_calling.get_company_id_from_identifier import GetCompanyIdFromIdentifier
 from kfinance.tool_calling.get_cusip_from_ticker import GetCusipFromTicker
 from kfinance.tool_calling.get_earnings_call_datetimes_from_identifier import (
     GetEarningsCallDatetimesFromIdentifier,
@@ -23,17 +22,13 @@ from kfinance.tool_calling.get_isin_from_ticker import GetIsinFromTicker
 from kfinance.tool_calling.get_latest import GetLatest
 from kfinance.tool_calling.get_n_quarters_ago import GetNQuartersAgo
 from kfinance.tool_calling.get_prices_from_identifier import GetPricesFromIdentifier
-from kfinance.tool_calling.get_security_id_from_identifier import GetSecurityIdFromIdentifier
-from kfinance.tool_calling.get_trading_item_id_from_identifier import GetTradingItemIdFromIdentifier
+from kfinance.tool_calling.resolve_identifier import ResolveIdentifier
 from kfinance.tool_calling.shared_models import KfinanceTool
 
 
 ALL_TOOLS: list[Type[KfinanceTool]] = [
     GetLatest,
     GetNQuartersAgo,
-    GetCompanyIdFromIdentifier,
-    GetSecurityIdFromIdentifier,
-    GetTradingItemIdFromIdentifier,
     GetIsinFromTicker,
     GetCusipFromTicker,
     GetInfoFromIdentifier,
@@ -44,4 +39,5 @@ ALL_TOOLS: list[Type[KfinanceTool]] = [
     GetFinancialStatementFromIdentifier,
     GetFinancialLineItemFromIdentifier,
     GetBusinessRelationshipFromIdentifier,
+    ResolveIdentifier,
 ]

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_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