kensho-kfinance 2.4.1__py3-none-any.whl → 2.4.3__py3-none-any.whl

{kensho_kfinance-2.4.1.dist-info → kensho_kfinance-2.4.3.dist-info}/METADATA

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

@@ -1,28 +1,28 @@
-kensho_kfinance-2.4.1.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-2.4.1.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=a6wxwkKHkXVFy50em1v27v8zB6kwU9TWdsZFe5wSYTA,1487
+kensho_kfinance-2.4.3.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-2.4.3.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=2EpxIzLz1uuod_1rJk6xxGLW_Y2-kupUSWJsREi4esI,1578
 kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/batch_request_handling.py,sha256=p6p_G4_BL06GgeKlh7P1k9CUqOMahWCLEw1NoBwbLvU,5698
-kfinance/constants.py,sha256=UuFzqL253-2tRQfma785K9tfaZGv-o821tO2tVLwc5Q,48813
-kfinance/fetch.py,sha256=yaCih8PAkOhVHb3tvmBW0x2w4QmXJiyUATu6Yx-xzP4,23851
+kfinance/constants.py,sha256=vVE_WlLNUKBn85eL8QBnk_zUSNDBRLcWutaQy-5wvGA,48768
+kfinance/fetch.py,sha256=yLqKMYYP5MwHhRZBuY_ihudHeSpNvzA8u1meYrEYX90,23923
 kfinance/kfinance.py,sha256=9lcarUW4fLHJA_U7_1ihCMbNJWs0AztvKf_XEd0qupk,59889
-kfinance/mcp.py,sha256=57OoTrxo5x_v7u1s3WFQNG0LySXyLEGc6CKSVpJLJVw,3717
+kfinance/mcp.py,sha256=MbktclVfBOEwfe-eR7kPaTXopMJmn_8RMlf4Jx5CXKU,3689
 kfinance/meta_classes.py,sha256=3V0nSXDDoake5o7kXnrqXuqNIiwI75KR4IYxFqSPhTE,20736
 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=H3hbvip-BJTNbNG0ITRXctaII3Vc2949yckZEGuAGg8,511
+kfinance/version.py,sha256=xLAVxNld0iPK6tqrofzfozu9ZHg4aby5Rg0HcLuAYIU,511
 kfinance/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/tests/conftest.py,sha256=voB-w8P_6L3Nel3rdgylXKe5WWaS1q7nCFt1O04uqoY,948
+kfinance/tests/scratch.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/tests/test_batch_requests.py,sha256=uXJF2IcRdyBm5SthwIUHMKtkGZ21MY84pg_k1JeSNOY,11430
 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=nfnz_ZxE-W3KMzpDaRClX55fQJrRjwLTha-rHTallmE,16713
 kfinance/tests/test_group_objects.py,sha256=SoMEZmkG4RYdgWOAwxLHHtzIQho92KM01YbQXPUg578,1689
-kfinance/tests/test_mcp.py,sha256=-pmeZ0PDp8GmXWcrWmaNNqMe7OVZONZLrjA0Y4b82os,594
 kfinance/tests/test_objects.py,sha256=0nDmCFrVcfI8VBo1Ph3YqXNo3uPLsSUiQkjEEHsax1M,30416
-kfinance/tests/test_tools.py,sha256=EWWWyPlGGES8Cn43_VaDAT7Vdp1nlIETE5dtOrP163o,24447
+kfinance/tests/test_tools.py,sha256=GMyReX2GBy_fozMZvA_yvZ6_bl1EPvJ2Eza9G5f4CEM,25753
 kfinance/tool_calling/README.md,sha256=omJq7Us6r4U45QB7hRpLjRJ5BMalCkZkh4uXBjTbJXc,2022
 kfinance/tool_calling/__init__.py,sha256=V5BVcJkLT1zC0QKZIQjLb-cZiQYV4T9Egj64uH807WE,2215
 kfinance/tool_calling/get_business_relationship_from_identifier.py,sha256=CipXvyqEjPm6BXYP0CA9Kp1BIyiIEm7abp85x1zXRV4,1472
@@ -30,8 +30,8 @@ kfinance/tool_calling/get_capitalization_from_identifier.py,sha256=TdWdJDeI-jSL-
 kfinance/tool_calling/get_cusip_from_ticker.py,sha256=houhGCYXoSzaaTtCvOBf3pPsYiSbcV1Ej5nAyGuMWcU,644
 kfinance/tool_calling/get_earnings.py,sha256=7xavYvqwq4fO0vpks25eDM87bCYwZxEQSwgT0I8jAok,1165
 kfinance/tool_calling/get_earnings_call_datetimes_from_identifier.py,sha256=Zp7gHP-z2ePu484wWx4xw89hl0z7NLcG3qliJT-6rUo,782
-kfinance/tool_calling/get_financial_line_item_from_identifier.py,sha256=bMK-GUMz_wmJ-7iFS72sM8AvvUvR83JYRWzYtr9Fofw,2153
-kfinance/tool_calling/get_financial_statement_from_identifier.py,sha256=9ouzC43skA78uI3dh3bvtM86db5RGxuWQAAJ24y-kBM,1906
+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
@@ -40,12 +40,12 @@ kfinance/tool_calling/get_latest_earnings.py,sha256=pQdExGdztGY3pHcak0bd6ULNf_RO
 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=5schxaVyPT4-LqtkmqHMXUF4PiouEzS8disolJ8VAXE,1865
+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=K-NPQyE_7Ew6Cs0zxG1xO2O47gp5uDHdHtWD7wUDZX4,2132
-kensho_kfinance-2.4.1.dist-info/METADATA,sha256=auRXUJ2d7DGgvj9qg199sB1dLufCa1zdGg1VfXh445k,5191
-kensho_kfinance-2.4.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kensho_kfinance-2.4.1.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-2.4.1.dist-info/RECORD,,
+kfinance/tool_calling/shared_models.py,sha256=loNoVFVyQnnpHLUIjkR6P9flGNbzp6kkGpL5hT37Sdg,2666
+kensho_kfinance-2.4.3.dist-info/METADATA,sha256=1Q6uTDsyuQqiSoEJ10HF83D5JHvupCBhyK0HobXrzyA,5191
+kensho_kfinance-2.4.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kensho_kfinance-2.4.3.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-2.4.3.dist-info/RECORD,,

kfinance/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v2.4.3
+- Improve MCP tool build process
+
+## v2.4.2
+- Update missing permission warning
+
 ## v2.4.1
 - Fix SegmentsPermission typo
 

kfinance/constants.py

@@ -56,10 +56,8 @@ class StatementType(StrEnum):
     """The type of financial statement"""
 
     balance_sheet = "balance_sheet"
-    bs = "balance_sheet"
     income_statement = "income_statement"
     cashflow = "cashflow"
-    cf = "cashflow"
 
 
 class SegmentType(StrEnum):

kfinance/fetch.py

@@ -200,9 +200,9 @@ class KFinanceApiClient:
                 self._user_permissions.add(Permission[permission_str])
             except KeyError:
                 logger.warning(
-                    "Could not resolve %s to a member of the Permission enum. "
-                    "%s may be a new type of permission that still needs to be "
-                    "added to the enum.",
+                    "You have access to functions using %s. However, functions using "
+                    "%s have not yet been added in this version of the client. To access "
+                    "all functions that you have access to, you may need to update the client.",
                     permission_str,
                     permission_str,
                 )

kfinance/mcp.py

@@ -1,44 +1,36 @@
-from textwrap import dedent
 from typing import Literal, Optional
 
 import click
 from fastmcp import FastMCP
+from fastmcp.tools import FunctionTool
 from fastmcp.utilities.logging import get_logger
+from langchain_core.utils.function_calling import convert_to_openai_tool
 
 from kfinance.kfinance import Client
-from kfinance.tool_calling.shared_models import KfinanceTool
+from kfinance.tool_calling import KfinanceTool
 
 
 logger = get_logger(__name__)
 
 
-def build_doc_string(tool: KfinanceTool) -> str:
-    """Build a formatted documentation string for a Kfinance tool.
+def build_mcp_tool_from_kfinance_tool(kfinance_tool: KfinanceTool) -> FunctionTool:
+    """Build an MCP FunctionTool from a langchain KfinanceTool."""
 
-    This function takes a KfinanceTool object and constructs a comprehensive
-    documentation string that includes the tool's description and detailed
-    information about its arguments, including default values and descriptions.
-
-    :param tool: The Kfinance tool object containing metadata about the tool's functionality, description, and argument schema.
-    :type tool: KfinanceTool
-    :return: A formatted documentation string containing for the tool description with detailed argument information.
-    :rtype: str
-    """
-
-    description = dedent(f"""
-        {tool.description}
-
-        Args:
-    """).strip()
-
-    for arg_name, arg_field in tool.args_schema.model_fields.items():
-        default_value_description = (
-            f"Default: {arg_field.default}. " if not arg_field.is_required() else ""
-        )
-        param_description = f"\n    {arg_name}: {default_value_description}{arg_field.description}"
-        description += param_description
-
-    return description
+    return FunctionTool(
+        name=kfinance_tool.name,
+        description=kfinance_tool.description,
+        # MCP expects a JSON schema for tool params, which we
+        # can generate similar to how langchain generates openai json schemas.
+        parameters=convert_to_openai_tool(kfinance_tool)["function"]["parameters"],
+        # The langchain runner internally validates input arguments via the args_schema.
+        # When running with mcp, we need to reproduce that validation ourselves in
+        # run_without_langchain (which then calls _run).
+        # If we pass in the underlying _run method directly, mcp generates a schema from
+        # the _run type hints but bypasses our internal validation. This causes errors,
+        # for example with integer literals, which our args models allow but the
+        # mcp-internal validation disallows.
+        fn=kfinance_tool.run_without_langchain,
+    )
 
 
 @click.command()
@@ -85,13 +77,9 @@ def run_mcp(
         kfinance_client = Client()
 
     kfinance_mcp: FastMCP = FastMCP("Kfinance")
-    for tool in kfinance_client.langchain_tools:
-        logger.info("Adding %s to server", tool.name)
-        kfinance_mcp.tool(
-            name_or_fn=getattr(tool, "_run"),
-            name=tool.name,
-            description=build_doc_string(tool),
-        )
+    for langchain_tool in kfinance_client.langchain_tools:
+        logger.info("Adding %s to server", langchain_tool.name)
+        kfinance_mcp.add_tool(build_mcp_tool_from_kfinance_tool(langchain_tool))
 
     logger.info("Server starting")
     kfinance_mcp.run(transport=transport)

kfinance/tests/test_tools.py

@@ -1,6 +1,10 @@
+import contextlib
+from contextlib import nullcontext as does_not_raise
 from datetime import date, datetime
 
 from langchain_core.utils.function_calling import convert_to_openai_tool
+from pydantic import BaseModel, ValidationError
+import pytest
 from pytest import raises
 from requests_mock import Mocker
 import time_machine
@@ -48,7 +52,7 @@ from kfinance.tool_calling.get_segments_from_identifier import (
     GetSegmentsFromIdentifierArgs,
 )
 from kfinance.tool_calling.get_transcript import GetTranscriptArgs
-from kfinance.tool_calling.shared_models import ToolArgsWithIdentifier
+from kfinance.tool_calling.shared_models import ToolArgsWithIdentifier, ValidQuarter
 
 
 class TestGetBusinessRelationshipFromIdentifier:
@@ -638,3 +642,33 @@ class TestGetTranscript:
         tool = GetTranscript(kfinance_client=mock_client)
         response = tool.run(GetTranscriptArgs(key_dev_id=12345).model_dump(mode="json"))
         assert response == expected_response
+
+
+class TestValidQuarter:
+    class QuarterModel(BaseModel):
+        quarter: ValidQuarter | None
+
+    @pytest.mark.parametrize(
+        "input_quarter, expectation, expected_quarter",
+        [
+            pytest.param(1, does_not_raise(), 1, id="int input works"),
+            pytest.param("1", does_not_raise(), 1, id="str input works"),
+            pytest.param(None, does_not_raise(), None, id="None input works"),
+            pytest.param(5, pytest.raises(ValidationError), None, id="invalid int raises"),
+            pytest.param("5", pytest.raises(ValidationError), None, id="invalid str raises"),
+        ],
+    )
+    def test_valid_quarter(
+        self,
+        input_quarter: int | str | None,
+        expectation: contextlib.AbstractContextManager,
+        expected_quarter: int | None,
+    ) -> None:
+        """
+        GIVEN a model that uses `ValidQuarter`
+        WHEN we deserialize with int, str, or None
+        THEN valid str get coerced to int. Invalid values raise.
+        """
+        with expectation:
+            res = self.QuarterModel.model_validate(dict(quarter=input_quarter))
+            assert res.quarter == expected_quarter

kfinance/tool_calling/get_financial_line_item_from_identifier.py

@@ -3,7 +3,7 @@ from typing import Literal, Type
 from pydantic import BaseModel, Field
 
 from kfinance.constants import LINE_ITEM_NAMES_AND_ALIASES, PeriodType, Permission
-from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier, ValidQuarter
 
 
 class GetFinancialLineItemFromIdentifierArgs(ToolArgsWithIdentifier):
@@ -16,8 +16,8 @@ class GetFinancialLineItemFromIdentifierArgs(ToolArgsWithIdentifier):
     period_type: PeriodType | None = Field(default=None, description="The period type")
     start_year: int | None = Field(default=None, description="The starting year for the data range")
     end_year: int | None = Field(default=None, description="The ending year for the data range")
-    start_quarter: Literal[1, 2, 3, 4] | None = Field(default=None, description="Starting quarter")
-    end_quarter: Literal[1, 2, 3, 4] | None = Field(default=None, description="Ending quarter")
+    start_quarter: ValidQuarter | None = Field(default=None, description="Starting quarter")
+    end_quarter: ValidQuarter | None = Field(default=None, description="Ending quarter")
 
 
 class GetFinancialLineItemFromIdentifier(KfinanceTool):

kfinance/tool_calling/get_financial_statement_from_identifier.py

@@ -3,7 +3,7 @@ from typing import Literal, Type
 from pydantic import BaseModel, Field
 
 from kfinance.constants import PeriodType, Permission, StatementType
-from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier, ValidQuarter
 
 
 class GetFinancialStatementFromIdentifierArgs(ToolArgsWithIdentifier):
@@ -12,8 +12,8 @@ class GetFinancialStatementFromIdentifierArgs(ToolArgsWithIdentifier):
     period_type: PeriodType | None = Field(default=None, description="The period type")
     start_year: int | None = Field(default=None, description="The starting year for the data range")
     end_year: int | None = Field(default=None, description="The ending year for the data range")
-    start_quarter: Literal[1, 2, 3, 4] | None = Field(default=None, description="Starting quarter")
-    end_quarter: Literal[1, 2, 3, 4] | None = Field(default=None, description="Ending quarter")
+    start_quarter: ValidQuarter | None = Field(default=None, description="Starting quarter")
+    end_quarter: ValidQuarter | None = Field(default=None, description="Ending quarter")
 
 
 class GetFinancialStatementFromIdentifier(KfinanceTool):

kfinance/tool_calling/get_segments_from_identifier.py

@@ -3,7 +3,7 @@ from typing import Literal, Type
 from pydantic import BaseModel, Field
 
 from kfinance.constants import PeriodType, Permission, SegmentType
-from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier, ValidQuarter
 
 
 class GetSegmentsFromIdentifierArgs(ToolArgsWithIdentifier):
@@ -12,8 +12,8 @@ class GetSegmentsFromIdentifierArgs(ToolArgsWithIdentifier):
     period_type: PeriodType | None = Field(default=None, description="The period type")
     start_year: int | None = Field(default=None, description="The starting year for the data range")
     end_year: int | None = Field(default=None, description="The ending year for the data range")
-    start_quarter: Literal[1, 2, 3, 4] | None = Field(default=None, description="Starting quarter")
-    end_quarter: Literal[1, 2, 3, 4] | None = Field(default=None, description="Ending quarter")
+    start_quarter: ValidQuarter | None = Field(default=None, description="Starting quarter")
+    end_quarter: ValidQuarter | None = Field(default=None, description="Ending quarter")
 
 
 class GetSegmentsFromIdentifier(KfinanceTool):

kfinance/tool_calling/shared_models.py

@@ -1,7 +1,7 @@
-from typing import Any, Type
+from typing import Annotated, Any, Literal, Type
 
 from langchain_core.tools import BaseTool
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
 
 from kfinance.constants import Permission
 from kfinance.kfinance import Client
@@ -53,3 +53,18 @@ class ToolArgsWithIdentifier(BaseModel):
     identifier: str = Field(
         description="The identifier, which can be a ticker symbol, ISIN, or CUSIP"
     )
+
+
+def convert_str_to_int(v: Any) -> Any:
+    """Convert strings to integers if possible."""
+    if isinstance(v, str) and v.isdigit():
+        return int(v)
+    return v
+
+
+# Valid Quarter is a literal type, which converts strings to int before
+# validating them.
+# Claude seems to often pass strings to int literals, which raise a
+# ValidationError during deserialization unless they have been converted
+# to int.
+ValidQuarter = Annotated[Literal[1, 2, 3, 4], BeforeValidator(convert_str_to_int)]

kfinance/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.4.1'
-__version_tuple__ = version_tuple = (2, 4, 1)
+__version__ = version = '2.4.3'
+__version_tuple__ = version_tuple = (2, 4, 3)

kfinance/tests/test_mcp.py

@@ -1,16 +0,0 @@
-from typing import Type
-
-import pytest
-
-from kfinance.kfinance import Client
-from kfinance.mcp import build_doc_string
-from kfinance.tool_calling import ALL_TOOLS
-from kfinance.tool_calling.shared_models import KfinanceTool
-
-
-class TestDocStringBuilding:
-    @pytest.mark.parametrize("tool_class", ALL_TOOLS)
-    def test_build_doc_string(self, mock_client: Client, tool_class: Type[KfinanceTool]):
-        """This test build the docstring for each tool. A success is considered if no exception is raised"""
-        tool = tool_class(kfinance_client=mock_client)
-        build_doc_string(tool)