kensho-kfinance 2.2.2__tar.gz → 2.2.5__tar.gz

{kensho_kfinance-2.2.2/kensho_kfinance.egg-info → kensho_kfinance-2.2.5}/PKG-INFO

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

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

@@ -36,6 +36,7 @@ kfinance/kfinance.py
 kfinance/meta_classes.py
 kfinance/prompt.py
 kfinance/py.typed
+kfinance/pydantic_models.py
 kfinance/server_thread.py
 kfinance/version.py
 kfinance/tests/__init__.py
@@ -61,6 +62,7 @@ kfinance/tool_calling/get_isin_from_ticker.py
 kfinance/tool_calling/get_latest.py
 kfinance/tool_calling/get_n_quarters_ago.py
 kfinance/tool_calling/get_prices_from_identifier.py
+kfinance/tool_calling/get_segments_from_identifier.py
 kfinance/tool_calling/resolve_identifier.py
 kfinance/tool_calling/shared_models.py
 scripts/copyright_line_check.sh

{kensho_kfinance-2.2.2 → kensho_kfinance-2.2.5}/kfinance/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v2.2.5
+- Add parsing for relationship response with name
+
+## v2.2.4
+- Add segments as llm tools
+
+## v2.2.3
+- Change segments return type to nested dictionary
+
 ## v2.2.2
 - Add segments
 

{kensho_kfinance-2.2.2 → kensho_kfinance-2.2.5}/kfinance/constants.py

@@ -102,6 +102,7 @@ class Permission(StrEnum):
     PricingPermission = "PricingPermission"
     RelationshipPermission = "RelationshipPermission"
     StatementsPermission = "StatementsPermission"
+    SegmentsPermission = "SegmentsPermission"
 
 
 class YearAndQuarter(TypedDict):

{kensho_kfinance-2.2.2 → kensho_kfinance-2.2.5}/kfinance/fetch.py

@@ -6,6 +6,7 @@ from typing import Callable, Generator, Optional
 from uuid import uuid4
 
 import jwt
+from pydantic import ValidationError
 import requests
 
 from .constants import (
@@ -17,6 +18,7 @@ from .constants import (
     Permission,
     SegmentType,
 )
+from .pydantic_models import RelationshipResponse, RelationshipResponseNoName
 
 
 # version.py gets autogenerated by setuptools-scm and is not available
@@ -505,26 +507,30 @@ class KFinanceApiClient:
 
     def fetch_companies_from_business_relationship(
         self, company_id: int, relationship_type: BusinessRelationshipType
-    ) -> dict[str, list[int]]:
-        """Fetches a dictionary of current and previous company IDs associated with a given company ID based on the specified relationship type.
-
-        The returned dictionary has the following structure:
-        {
-            "current": List[int],
-            "previous": List[int]
-        }
+    ) -> RelationshipResponse | RelationshipResponseNoName:
+        """Fetches a dictionary of current and previous company IDs and names associated with a given company ID based on the specified relationship type.
 
         Example: fetch_companies_from_business_relationship(company_id=1234, relationship_type="distributor") returns a dictionary of company 1234's current and previous distributors.
 
+        As of 2024-05-28, we are changing the response on the backend from
+        RelationshipResponseNoName to RelationshipResponse. This function can handle both response
+        types.
+
         :param company_id: The ID of the company for which associated companies are being fetched.
         :type company_id: int
         :param relationship_type: The type of relationship to filter by. Valid relationship types are defined in the BusinessRelationshipType class.
         :type relationship_type: BusinessRelationshipType
         :return: A dictionary containing lists of current and previous company IDs that have the specified relationship with the given company_id.
-        :rtype: dict[str, list[int]]
+        :rtype: RelationshipResponse | RelationshipResponseNoName
         """
         url = f"{self.url_base}relationship/{company_id}/{relationship_type}"
-        return self.fetch(url)
+        result = self.fetch(url)
+        # Try to parse as the newer RelationshipResponse and fall back to
+        # RelationshipResponseNoName if that fails.
+        try:
+            return RelationshipResponse.model_validate(result)
+        except ValidationError:
+            return RelationshipResponseNoName.model_validate(result)
 
     def fetch_ticker_from_industry_code(
         self,

{kensho_kfinance-2.2.2 → kensho_kfinance-2.2.5}/kfinance/meta_classes.py

@@ -9,12 +9,12 @@ import pandas as pd
 
 from .constants import LINE_ITEMS, BusinessRelationshipType, PeriodType, SegmentType
 from .fetch import KFinanceApiClient
+from .pydantic_models import RelationshipResponse
 
 
 if TYPE_CHECKING:
     from .kfinance import BusinessRelationships
 
-
 logger = logging.getLogger(__name__)
 
 
@@ -223,14 +223,32 @@ class CompanyFunctionsMetaClass:
         """
         from .kfinance import BusinessRelationships, Companies
 
-        companies = self.kfinance_api_client.fetch_companies_from_business_relationship(
-            self.company_id,
-            relationship_type,
-        )
-        return BusinessRelationships(
-            Companies(self.kfinance_api_client, companies["current"]),
-            Companies(self.kfinance_api_client, companies["previous"]),
+        relationship_resp = self.kfinance_api_client.fetch_companies_from_business_relationship(
+            company_id=self.company_id,
+            relationship_type=relationship_type,
         )
+        if isinstance(relationship_resp, RelationshipResponse):
+            return BusinessRelationships(
+                current=Companies(
+                    kfinance_api_client=self.kfinance_api_client,
+                    company_ids=[c.company_id for c in relationship_resp.current],
+                ),
+                previous=Companies(
+                    kfinance_api_client=self.kfinance_api_client,
+                    company_ids=[c.company_id for c in relationship_resp.previous],
+                ),
+            )
+        else:
+            return BusinessRelationships(
+                current=Companies(
+                    kfinance_api_client=self.kfinance_api_client,
+                    company_ids=relationship_resp.current,
+                ),
+                previous=Companies(
+                    kfinance_api_client=self.kfinance_api_client,
+                    company_ids=relationship_resp.previous,
+                ),
+            )
 
     def market_cap(
         self,
@@ -312,7 +330,7 @@ class CompanyFunctionsMetaClass:
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
         end_quarter: Optional[int] = None,
-    ) -> pd.DataFrame:
+    ) -> dict:
         """Get the company's segments"""
         try:
             self.validate_inputs(
@@ -322,9 +340,9 @@ class CompanyFunctionsMetaClass:
                 end_quarter=end_quarter,
             )
         except ValueError:
-            return pd.DataFrame()
+            return {}
 
-        results = self.kfinance_api_client.fetch_segments(
+        return self.kfinance_api_client.fetch_segments(
             company_id=self.company_id,
             segment_type=segment_type,
             period_type=period_type,
@@ -334,20 +352,6 @@ class CompanyFunctionsMetaClass:
             end_quarter=end_quarter,
         )["segments"]
 
-        period_name = (
-            "Year" if (period_type == PeriodType.annual or period_type is None) else "Period"
-        )
-
-        # flatten the nested dictionary and return as a DataFrame
-        rows = []
-        for period, segments in results.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])
-        return pd.DataFrame(
-            rows, columns=[period_name, "Segment Name", "Line Item", "Value"]
-        ).replace(np.nan, None)
-
     def business_segments(
         self,
         period_type: Optional[PeriodType] = None,
@@ -355,7 +359,7 @@ class CompanyFunctionsMetaClass:
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
         end_quarter: Optional[int] = None,
-    ) -> pd.DataFrame:
+    ) -> dict:
         """Retrieves the templated line of business segments for a given period_type, start_year, start_quarter, end_year and end_quarter.
 
         :param period_type: The period_type requested for. Can be “annual”, “quarterly”, "ytd". Defaults to “annual” when start_quarter and end_quarter are None.
@@ -368,8 +372,8 @@ class CompanyFunctionsMetaClass:
         :type start_quarter: int, optional
         :param end_quarter: The ending calendar quarter, defaults to None
         :type end_quarter: int, optional
-        :return: A DataFrame with `Year`/`Period`, `Segment Name`, `Line Item` and `Value` column.
-        :rtype: pd.DataFrame
+        :return: A dictionary containing the templated line of business segments for each time period, segment name, line item, and value.
+        :rtype: dict
         """
         return self._segments(
             segment_type=SegmentType.business,
@@ -387,8 +391,8 @@ class CompanyFunctionsMetaClass:
         end_year: Optional[int] = None,
         start_quarter: Optional[int] = None,
         end_quarter: Optional[int] = None,
-    ) -> pd.DataFrame:
-        """Retrieves the templated geographic segments for a given company for a given period_type, start_year, start_quarter, end_year and end_quarter.
+    ) -> dict:
+        """Retrieves the templated geographic segments for a given period_type, start_year, start_quarter, end_year and end_quarter.
 
         :param period_type: The period_type requested for. Can be “annual”, “quarterly”, "ytd". Defaults to “annual” when start_quarter and end_quarter are None.
         :type start_year: PeriodType, optional
@@ -400,8 +404,8 @@ class CompanyFunctionsMetaClass:
         :type start_quarter: int, optional
         :param end_quarter: The ending calendar quarter, defaults to None
         :type end_quarter: int, optional
-        :return: A DataFrame with `Year`/`Period`, `Segment Name`, `Line Item` and `Value` column.
-        :rtype: pd.DataFrame
+        :return: A dictionary containing the templated geographic segments for each time period, segment name, line item, and value.
+        :rtype: dict
         """
         return self._segments(
             segment_type=SegmentType.geographic,

kensho_kfinance-2.2.5/kfinance/pydantic_models.py

@@ -0,0 +1,25 @@
+from pydantic import BaseModel
+
+
+class RelationshipResponseNoName(BaseModel):
+    """A response from the relationship endpoint before adding the company name.
+
+    Each element in `current` and `previous` is a company_id.
+    """
+
+    current: list[int]
+    previous: list[int]
+
+
+class CompanyIdAndName(BaseModel):
+    """A company_id and name"""
+
+    company_id: int
+    company_name: str
+
+
+class RelationshipResponse(BaseModel):
+    """A response from the relationship endpoint that includes both company_id and name."""
+
+    current: list[CompanyIdAndName]
+    previous: list[CompanyIdAndName]

{kensho_kfinance-2.2.2 → kensho_kfinance-2.2.5}/kfinance/tests/test_fetch.py

@@ -2,9 +2,17 @@ from unittest import TestCase
 from unittest.mock import MagicMock
 
 import pytest
+from requests_mock import Mocker
 
-from kfinance.constants import Periodicity, PeriodType
+from kfinance.constants import BusinessRelationshipType, Periodicity, PeriodType
 from kfinance.fetch import KFinanceApiClient
+from kfinance.kfinance import Client
+from kfinance.pydantic_models import (
+    CompanyIdAndName,
+    RelationshipResponse,
+    RelationshipResponseNoName,
+)
+from kfinance.tests.conftest import SPGI_COMPANY_ID
 
 
 def build_mock_api_client() -> KFinanceApiClient:
@@ -279,3 +287,56 @@ class TestMarketCap:
         expected_fetch_url = f"{client.url_base}users/permissions"
         client.fetch_permissions()
         client.fetch.assert_called_with(expected_fetch_url)
+
+
+class TestFetchCompaniesFromBusinessRelationship:
+    def test_old_response_format(self, requests_mock: Mocker, mock_client: Client) -> None:
+        """
+        GIVEN a business relationship request
+        WHEN the api returns a response in the old (no name) format
+        THEN the response can successfully be parsed.
+        """
+        http_resp = {"current": [883103], "previous": [472898, 8182358]}
+        expected_result = RelationshipResponseNoName(current=[883103], previous=[472898, 8182358])
+        requests_mock.get(
+            url=f"{mock_client.kfinance_api_client.url_base}relationship/{SPGI_COMPANY_ID}/{BusinessRelationshipType.supplier}",
+            json=http_resp,
+        )
+
+        resp = mock_client.kfinance_api_client.fetch_companies_from_business_relationship(
+            company_id=SPGI_COMPANY_ID, relationship_type=BusinessRelationshipType.supplier
+        )
+        assert resp == expected_result
+
+    def test_new_response_format(self, requests_mock: Mocker, mock_client: Client) -> None:
+        """
+        GIVEN a business relationship request
+        WHEN the api returns a response in the new (with name) format
+        THEN the response can successfully be parsed.
+        """
+
+        http_resp = {
+            "current": [{"company_name": "foo", "company_id": 883103}],
+            "previous": [
+                {"company_name": "bar", "company_id": 472898},
+                {"company_name": "baz", "company_id": 8182358},
+            ],
+        }
+
+        expected_result = RelationshipResponse(
+            current=[CompanyIdAndName(company_name="foo", company_id=883103)],
+            previous=[
+                CompanyIdAndName(company_name="bar", company_id=472898),
+                CompanyIdAndName(company_name="baz", company_id=8182358),
+            ],
+        )
+
+        requests_mock.get(
+            url=f"{mock_client.kfinance_api_client.url_base}relationship/{SPGI_COMPANY_ID}/{BusinessRelationshipType.supplier}",
+            json=http_resp,
+        )
+
+        resp = mock_client.kfinance_api_client.fetch_companies_from_business_relationship(
+            company_id=SPGI_COMPANY_ID, relationship_type=BusinessRelationshipType.supplier
+        )
+        assert resp == expected_result

{kensho_kfinance-2.2.2 → kensho_kfinance-2.2.5}/kfinance/tests/test_objects.py

@@ -337,17 +337,10 @@ class TestCompany(TestCase):
 
     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)
+        expected_segments = MOCK_COMPANY_DB[msft_company_id]["segments"]
 
         business_segment = self.msft_company.business_segments()
-        pd.testing.assert_frame_equal(expected_segments, business_segment)
+        self.assertEqual(expected_segments, business_segment)
 
 
 class TestSecurity(TestCase):

{kensho_kfinance-2.2.2 → kensho_kfinance-2.2.5}/kfinance/tests/test_tools.py

@@ -4,7 +4,7 @@ from langchain_core.utils.function_calling import convert_to_openai_tool
 from requests_mock import Mocker
 import time_machine
 
-from kfinance.constants import BusinessRelationshipType, Capitalization, StatementType
+from kfinance.constants import BusinessRelationshipType, Capitalization, SegmentType, 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 (
@@ -38,6 +38,10 @@ from kfinance.tool_calling.get_isin_from_ticker import GetIsinFromTickerArgs
 from kfinance.tool_calling.get_latest import GetLatestArgs
 from kfinance.tool_calling.get_n_quarters_ago import GetNQuartersAgoArgs
 from kfinance.tool_calling.get_prices_from_identifier import GetPricesFromIdentifierArgs
+from kfinance.tool_calling.get_segments_from_identifier import (
+    GetSegmentsFromIdentifier,
+    GetSegmentsFromIdentifierArgs,
+)
 from kfinance.tool_calling.shared_models import ToolArgsWithIdentifier
 
 
@@ -217,6 +221,44 @@ class TestGetFinancialStatementFromIdentifier:
         assert response == expected_response
 
 
+class TestGetSegmentsFromIdentifier:
+    def test_get_segments_from_identifier(self, mock_client: Client, requests_mock: Mocker):
+        """
+        GIVEN the GetSegmentsFromIdentifier tool
+        WHEN we request the SPGI business segment
+        THEN we get back the SPGI business segment
+        """
+
+        segments_response = {
+            "segments": {
+                "2020": {
+                    "Commodity Insights": {
+                        "CAPEX": -7000000.0,
+                        "D&A": 17000000.0,
+                    },
+                    "Unallocated Assets Held for Sale": None,
+                },
+                "2021": {
+                    "Commodity Insights": {
+                        "CAPEX": -2000000.0,
+                        "D&A": 12000000.0,
+                    },
+                    "Unallocated Assets Held for Sale": {"Total Assets": 321000000.0},
+                },
+            },
+        }
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/segments/{SPGI_COMPANY_ID}/business/none/none/none/none/none",
+            # truncated from the original API response
+            json=segments_response,
+        )
+
+        tool = GetSegmentsFromIdentifier(kfinance_client=mock_client)
+        args = GetSegmentsFromIdentifierArgs(identifier="SPGI", segment_type=SegmentType.business)
+        response = tool.run(args.model_dump(mode="json"))
+        assert response == segments_response["segments"]
+
+
 class TestGetHistoryMetadataFromIdentifier:
     def test_get_history_metadata_from_identifier(self, mock_client: Client, requests_mock: Mocker):
         """

{kensho_kfinance-2.2.2 → kensho_kfinance-2.2.5}/kfinance/tool_calling/__init__.py

@@ -22,6 +22,9 @@ 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_segments_from_identifier import (
+    GetSegmentsFromIdentifier,
+)
 from kfinance.tool_calling.resolve_identifier import ResolveIdentifier
 from kfinance.tool_calling.shared_models import KfinanceTool
 
@@ -40,4 +43,5 @@ ALL_TOOLS: list[Type[KfinanceTool]] = [
     GetFinancialLineItemFromIdentifier,
     GetBusinessRelationshipFromIdentifier,
     ResolveIdentifier,
+    GetSegmentsFromIdentifier,
 ]

kensho_kfinance-2.2.5/kfinance/tool_calling/get_segments_from_identifier.py

@@ -0,0 +1,42 @@
+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
+
+
+class GetSegmentsFromIdentifierArgs(ToolArgsWithIdentifier):
+    # no description because the description for enum fields comes from the enum docstring.
+    segment_type: SegmentType
+    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")
+
+
+class GetSegmentsFromIdentifier(KfinanceTool):
+    name: str = "get_segments_from_identifier"
+    description: str = "Get the templated segments associated with an identifier."
+    args_schema: Type[BaseModel] = GetSegmentsFromIdentifierArgs
+    required_permission: Permission | None = Permission.StatementsPermission
+
+    def _run(
+        self,
+        identifier: str,
+        segment_type: SegmentType,
+        period_type: PeriodType | None = None,
+        start_year: int | None = None,
+        end_year: int | None = None,
+        start_quarter: Literal[1, 2, 3, 4] | None = None,
+        end_quarter: Literal[1, 2, 3, 4] | None = None,
+    ) -> str:
+        ticker = self.kfinance_client.ticker(identifier)
+        return getattr(ticker, segment_type.value + "_segments")(
+            period_type=period_type,
+            start_year=start_year,
+            end_year=end_year,
+            start_quarter=start_quarter,
+            end_quarter=end_quarter,
+        )

{kensho_kfinance-2.2.2 → kensho_kfinance-2.2.5}/kfinance/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.2.2'
-__version_tuple__ = version_tuple = (2, 2, 2)
+__version__ = version = '2.2.5'
+__version_tuple__ = version_tuple = (2, 2, 5)