kensho-kfinance 2.4.2__tar.gz → 2.4.3__tar.gz

{kensho_kfinance-2.4.2/kensho_kfinance.egg-info → kensho_kfinance-2.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.4.2
+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.2 → kensho_kfinance-2.4.3/kensho_kfinance.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.4.2
+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.2 → kensho_kfinance-2.4.3}/kensho_kfinance.egg-info/SOURCES.txt

@@ -48,12 +48,12 @@ kfinance/server_thread.py
 kfinance/version.py
 kfinance/tests/__init__.py
 kfinance/tests/conftest.py
+kfinance/tests/scratch.py
 kfinance/tests/test_batch_requests.py
 kfinance/tests/test_client.py
 kfinance/tests/test_example_notebook.py
 kfinance/tests/test_fetch.py
 kfinance/tests/test_group_objects.py
-kfinance/tests/test_mcp.py
 kfinance/tests/test_objects.py
 kfinance/tests/test_tools.py
 kfinance/tool_calling/README.md

{kensho_kfinance-2.4.2 → kensho_kfinance-2.4.3}/kfinance/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v2.4.3
+- Improve MCP tool build process
+
 ## v2.4.2
 - Update missing permission warning
 

{kensho_kfinance-2.4.2 → kensho_kfinance-2.4.3}/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):

{kensho_kfinance-2.4.2 → kensho_kfinance-2.4.3}/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)

{kensho_kfinance-2.4.2 → kensho_kfinance-2.4.3}/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

{kensho_kfinance-2.4.2 → kensho_kfinance-2.4.3}/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):

{kensho_kfinance-2.4.2 → kensho_kfinance-2.4.3}/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):

{kensho_kfinance-2.4.2 → kensho_kfinance-2.4.3}/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):

{kensho_kfinance-2.4.2 → kensho_kfinance-2.4.3}/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)]

{kensho_kfinance-2.4.2 → kensho_kfinance-2.4.3}/kfinance/version.py

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

kensho_kfinance-2.4.2/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)