kensho-kfinance 3.2.14__py3-none-any.whl → 3.2.15__py3-none-any.whl

kfinance/domains/line_items/line_item_tools.py

@@ -1,14 +1,17 @@
+from difflib import SequenceMatcher
 from textwrap import dedent
 from typing import Literal, Type
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 
 from kfinance.client.batch_request_handling import Task, process_tasks_in_thread_pool_executor
 from kfinance.client.models.date_and_period_models import PeriodType
 from kfinance.client.permission_models import Permission
 from kfinance.domains.line_items.line_item_models import (
     LINE_ITEM_NAMES_AND_ALIASES,
+    LINE_ITEM_TO_DESCRIPTIONS_MAP,
     LineItemResponse,
+    LineItemScore,
 )
 from kfinance.integrations.tool_calling.tool_calling_models import (
     KfinanceTool,
@@ -18,6 +21,75 @@ from kfinance.integrations.tool_calling.tool_calling_models import (
 )
 
 
+def _find_similar_line_items(
+    invalid_item: str, descriptors: dict[str, str], max_suggestions: int = 8
+) -> list[LineItemScore]:
+    """Find similar line items using keyword matching and string similarity.
+
+    Args:
+        invalid_item: The invalid line item provided by the user
+        descriptors: Dictionary mapping line item names to descriptions
+        max_suggestions: Maximum number of suggestions to return
+
+    Returns:
+        List of LineItemScore objects for the best matches
+    """
+    if not descriptors:
+        return []
+
+    invalid_lower = invalid_item.lower()
+    scores: list[LineItemScore] = []
+
+    for line_item, description in descriptors.items():
+        # Calculate similarity scores
+        name_similarity = SequenceMatcher(None, invalid_lower, line_item.lower()).ratio()
+
+        # Check for keyword matches in the line item name
+        invalid_words = set(invalid_lower.replace("_", " ").split())
+        item_words = set(line_item.lower().replace("_", " ").split())
+        keyword_match_score = len(invalid_words.intersection(item_words)) / max(
+            len(invalid_words), 1
+        )
+
+        # Check for keyword matches in description
+        description_words = set(description.lower().split())
+        description_match_score = len(invalid_words.intersection(description_words)) / max(
+            len(invalid_words), 1
+        )
+
+        # Combined score (weighted)
+        total_score = (
+            name_similarity * 0.5  # Direct name similarity
+            + keyword_match_score * 0.3  # Keyword matches in name
+            + description_match_score * 0.2  # Keyword matches in description
+        )
+
+        scores.append(LineItemScore(name=line_item, description=description, score=total_score))
+
+    # Sort by score (descending) and return top matches
+    scores.sort(reverse=True, key=lambda x: x.score)
+    return [item for item in scores[:max_suggestions] if item.score > 0.1]
+
+
+def _smart_line_item_validator(v: str) -> str:
+    """Custom validator that provides intelligent suggestions for invalid line items."""
+    if v not in LINE_ITEM_NAMES_AND_ALIASES:
+        # Find similar items using pre-computed descriptors
+        suggestions = _find_similar_line_items(v, LINE_ITEM_TO_DESCRIPTIONS_MAP)
+
+        if suggestions:
+            suggestion_text = "\n\nDid you mean one of these?\n"
+            for item in suggestions:
+                suggestion_text += f"  • '{item.name}': {item.description}\n"
+
+            error_msg = f"Invalid line_item '{v}'.{suggestion_text}"
+        else:
+            error_msg = f"Invalid line_item '{v}'. Please refer to the tool documentation for valid options."
+
+        raise ValueError(error_msg)
+    return v
+
+
 class GetFinancialLineItemFromIdentifiersArgs(ToolArgsWithIdentifiers):
     # Note: mypy will not enforce this literal because of the type: ignore.
     # But pydantic still uses the literal to check for allowed values and only includes
@@ -31,6 +103,16 @@ class GetFinancialLineItemFromIdentifiersArgs(ToolArgsWithIdentifiers):
     start_quarter: ValidQuarter | None = Field(default=None, description="Starting quarter")
     end_quarter: ValidQuarter | None = Field(default=None, description="Ending quarter")
 
+    @model_validator(mode="before")
+    @classmethod
+    def validate_line_item_with_suggestions(cls, values: dict) -> dict:
+        """Custom validator that provides intelligent suggestions for invalid line items."""
+        if isinstance(values, dict) and "line_item" in values:
+            line_item = values["line_item"]
+            # Use the helper function to validate and provide suggestions
+            _smart_line_item_validator(line_item)
+        return values
+
 
 class GetFinancialLineItemFromIdentifiersResp(ToolRespWithErrors):
     results: dict[str, LineItemResponse]

kfinance/domains/line_items/tests/test_line_item_tools.py

@@ -6,11 +6,12 @@ from requests_mock import Mocker
 from kfinance.client.kfinance import Client
 from kfinance.conftest import SPGI_COMPANY_ID
 from kfinance.domains.companies.company_models import COMPANY_ID_PREFIX
-from kfinance.domains.line_items.line_item_models import LineItemResponse
+from kfinance.domains.line_items.line_item_models import LineItemResponse, LineItemScore
 from kfinance.domains.line_items.line_item_tools import (
     GetFinancialLineItemFromIdentifiers,
     GetFinancialLineItemFromIdentifiersArgs,
     GetFinancialLineItemFromIdentifiersResp,
+    _find_similar_line_items,
 )
 
 
@@ -131,3 +132,140 @@ class TestGetFinancialLineItemFromCompanyIds:
         assert "revenue" in line_items
         # normal_revenue is an alias for revenue
         assert "normal_revenue" in line_items
+
+
+class TestFindSimilarLineItems:
+    """Tests for the _find_similar_line_items function."""
+
+    # Preset test descriptors to ensure consistent results
+    TEST_DESCRIPTORS = {
+        "revenue": "Revenue recognized from primary business activities (excludes non-operating income).",
+        "total_revenue": "Sum of operating and non-operating revenue streams for the period.",
+        "cost_of_goods_sold": "Direct costs attributable to producing goods sold during the period.",
+        "cogs": "Direct costs attributable to producing goods sold during the period.",
+        "gross_profit": "Revenue minus cost_of_goods_sold or cost_of_revenue for the reported period.",
+        "operating_income": "Operating profit after subtracting operating expenses from operating revenue.",
+        "net_income": "Bottom-line profit attributable to common shareholders.",
+        "research_and_development_expense": "Expenses incurred for research and development activities.",
+        "r_and_d_expense": "Expenses incurred for research and development activities.",
+        "depreciation_and_amortization": "Combined depreciation and amortization expense for the period.",
+        "ebitda": "Earnings before interest, taxes, depreciation, and amortization.",
+    }
+
+    def test_exact_keyword_match(self):
+        """
+        GIVEN a preset descriptors dictionary
+        WHEN searching for 'revenues' (similar to 'revenue')
+        THEN 'revenue' should be in the top suggestions
+        """
+        results = _find_similar_line_items("revenues", self.TEST_DESCRIPTORS, max_suggestions=5)
+
+        assert len(results) > 0
+        assert isinstance(results[0], LineItemScore)
+        # Check that revenue or total_revenue is in top results
+        result_names = [item.name for item in results]
+        assert "revenue" in result_names or "total_revenue" in result_names
+
+    def test_acronym_matching(self):
+        """
+        GIVEN a preset descriptors dictionary
+        WHEN searching for 'R&D' (abbreviation)
+        THEN research and development related items should appear
+        """
+        results = _find_similar_line_items("R&D", self.TEST_DESCRIPTORS, max_suggestions=5)
+
+        result_names = [item.name for item in results]
+        # Should find r_and_d_expense or research_and_development_expense
+        assert any("research" in name or "r_and_d" in name for name in result_names)
+
+    def test_multiple_word_matching(self):
+        """
+        GIVEN a preset descriptors dictionary
+        WHEN searching for 'cost goods'
+        THEN 'cost_of_goods_sold' should be suggested
+        """
+        results = _find_similar_line_items("cost goods", self.TEST_DESCRIPTORS, max_suggestions=5)
+
+        result_names = [item.name for item in results]
+        assert "cost_of_goods_sold" in result_names or "cogs" in result_names
+
+    def test_description_matching(self):
+        """
+        GIVEN a preset descriptors dictionary
+        WHEN searching for 'profit'
+        THEN items with 'profit' in description should appear
+        """
+        results = _find_similar_line_items("profit", self.TEST_DESCRIPTORS, max_suggestions=5)
+
+        assert len(results) > 0
+        # Should find items like gross_profit, operating_income (operating profit), or net_income
+        result_names = [item.name for item in results]
+        assert any("profit" in name or "income" in name for name in result_names)
+
+    def test_empty_descriptors(self):
+        """
+        GIVEN an empty descriptors dictionary
+        WHEN searching for any term
+        THEN should return empty list
+        """
+        results = _find_similar_line_items("revenue", {}, max_suggestions=5)
+        assert results == []
+
+    def test_no_matches(self):
+        """
+        GIVEN a preset descriptors dictionary
+        WHEN searching for completely unrelated term
+        THEN should return empty list or very low scores filtered out
+        """
+        results = _find_similar_line_items("xyz123abc", self.TEST_DESCRIPTORS, max_suggestions=5)
+        # Should return empty or very few results since threshold is > 0.1
+        assert len(results) <= 2  # May have some weak matches but should be minimal
+
+    def test_max_suggestions_respected(self):
+        """
+        GIVEN a preset descriptors dictionary
+        WHEN searching with max_suggestions=3
+        THEN should return at most 3 results
+        """
+        results = _find_similar_line_items("income", self.TEST_DESCRIPTORS, max_suggestions=3)
+        assert len(results) <= 3
+
+    def test_score_ordering(self):
+        """
+        GIVEN a preset descriptors dictionary
+        WHEN searching for a term
+        THEN results should be ordered by descending score
+        """
+        results = _find_similar_line_items("revenue", self.TEST_DESCRIPTORS, max_suggestions=5)
+
+        if len(results) > 1:
+            for i in range(len(results) - 1):
+                assert results[i].score >= results[i + 1].score
+
+    def test_score_threshold(self):
+        """
+        GIVEN a preset descriptors dictionary
+        WHEN searching for a term
+        THEN all returned results should have score > 0.1
+        """
+        results = _find_similar_line_items("revenue", self.TEST_DESCRIPTORS, max_suggestions=10)
+
+        for item in results:
+            assert item.score > 0.1
+
+    def test_lineitemscore_structure(self):
+        """
+        GIVEN a preset descriptors dictionary
+        WHEN searching for a term
+        THEN each result should be a LineItemScore with name, description, and score
+        """
+        results = _find_similar_line_items("revenue", self.TEST_DESCRIPTORS, max_suggestions=5)
+
+        assert len(results) > 0
+        for item in results:
+            assert isinstance(item, LineItemScore)
+            assert isinstance(item.name, str)
+            assert isinstance(item.description, str)
+            assert isinstance(item.score, float)
+            assert item.name in self.TEST_DESCRIPTORS
+            assert item.description == self.TEST_DESCRIPTORS[item.name]

kfinance/version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '3.2.14'
-__version_tuple__ = version_tuple = (3, 2, 14)
+__version__ = version = '3.2.15'
+__version_tuple__ = version_tuple = (3, 2, 15)
 
 __commit_id__ = commit_id = None