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

{kensho_kfinance-2.2.2.dist-info → kensho_kfinance-2.2.4.dist-info}/METADATA

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

@@ -1,16 +1,16 @@
-kensho_kfinance-2.2.2.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-2.2.2.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=eX36Pj6mDG2B6AtnHpP5FAJ14X-8XqF0fNRTYOGClXw,1140
+kensho_kfinance-2.2.4.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-2.2.4.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=rBjrg8H9eODymBNuLyOWIRrA5FAVR92WgxswFMkGI9E,1241
 kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/batch_request_handling.py,sha256=p6p_G4_BL06GgeKlh7P1k9CUqOMahWCLEw1NoBwbLvU,5698
-kfinance/constants.py,sha256=4vj0WA0xupEJexvnI-ap6LFHXEf6dn8jQwJlxz8cGTs,48767
+kfinance/constants.py,sha256=UuFzqL253-2tRQfma785K9tfaZGv-o821tO2tVLwc5Q,48813
 kfinance/fetch.py,sha256=fguxYy5rjLQKNkmP7gsvZUJtmt9uDNxg6LN9FRJTAVQ,22936
 kfinance/kfinance.py,sha256=_U69k0Dcwkw1B_lzaUZy8N2-c-v93ZKoUAVVZb6wBUM,52758
-kfinance/meta_classes.py,sha256=nwqHRi8IFa4WLFAZpX4a6htR47doK3_qVLnYBOylQV0,20482
+kfinance/meta_classes.py,sha256=1qYkj2L7jcBfdkye6TG2nuRhwzhAbmtxay6rSVY3DsA,19883
 kfinance/prompt.py,sha256=PtVB8c_FcSlVdyGgByAnIFGzuUuBaEjciCqnBJl1hSQ,25133
 kfinance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/server_thread.py,sha256=jUnt1YGoYDkqqz1MbCwd44zJs1T_Z2BCgvj75bdtLgA,2574
-kfinance/version.py,sha256=YDBduKhVnvbZfZTbXbsjQMbxTwgIIXIZ646Mj9YV074,511
+kfinance/version.py,sha256=Ath1yNFbHtPzluPba0J7EfQTfLH_byRzLfGjqAUl6cY,511
 kfinance/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/tests/conftest.py,sha256=voB-w8P_6L3Nel3rdgylXKe5WWaS1q7nCFt1O04uqoY,948
 kfinance/tests/test_batch_requests.py,sha256=uXJF2IcRdyBm5SthwIUHMKtkGZ21MY84pg_k1JeSNOY,11430
@@ -18,10 +18,10 @@ kfinance/tests/test_client.py,sha256=O7icZCSDhlQ9WGhzoXlpiSvbuA-mQNJHBYVsilyP_dE
 kfinance/tests/test_example_notebook.py,sha256=XhDAJp3H5Y6usLAt3k4Ug4W3H6gLyh68nzmoWgOOLn4,6441
 kfinance/tests/test_fetch.py,sha256=O9qOsffQYJPSAR1X_P6CNoA0Buyq2kx4vfS0FOc2Goc,13564
 kfinance/tests/test_group_objects.py,sha256=SoMEZmkG4RYdgWOAwxLHHtzIQho92KM01YbQXPUg578,1689
-kfinance/tests/test_objects.py,sha256=PpB3q4UPi9ctRznq48Fy6sJUsOEqdAWzMzee1BYORX4,24001
-kfinance/tests/test_tools.py,sha256=fTN43Y8fX8l8Yyw65XJmn_xUIbrTLaPvrsuBEdKPqK0,15234
+kfinance/tests/test_objects.py,sha256=CSk3iN-uDt-E6gaOX4jExuYPT8Up-YNC3hafpenadcA,23614
+kfinance/tests/test_tools.py,sha256=ne4XhebhoxDHFl4kRLl10j4K-SXLrxS6jv6Ypt0Gv_E,16846
 kfinance/tool_calling/README.md,sha256=omJq7Us6r4U45QB7hRpLjRJ5BMalCkZkh4uXBjTbJXc,2022
-kfinance/tool_calling/__init__.py,sha256=ewTzpR4S9mzCtSRpfK7WldDX78VSRKFta-s_zBsmamA,1744
+kfinance/tool_calling/__init__.py,sha256=Fb30Snu09B63NscSUJGGnFAdlXSDrTAOJlzjYvMyZXk,1873
 kfinance/tool_calling/get_business_relationship_from_identifier.py,sha256=CipXvyqEjPm6BXYP0CA9Kp1BIyiIEm7abp85x1zXRV4,1472
 kfinance/tool_calling/get_capitalization_from_identifier.py,sha256=TdWdJDeI-jSL-1YfhnnwIA9D1SXobidvoHrjK42QmqQ,1521
 kfinance/tool_calling/get_cusip_from_ticker.py,sha256=houhGCYXoSzaaTtCvOBf3pPsYiSbcV1Ej5nAyGuMWcU,644
@@ -34,9 +34,10 @@ kfinance/tool_calling/get_isin_from_ticker.py,sha256=2fJBcA-rNGbVOQmQ7qJEYxqejQw
 kfinance/tool_calling/get_latest.py,sha256=btGeVBmvX5QJutzrKfE6spatGGejDuHxtq53NoAaGNk,786
 kfinance/tool_calling/get_n_quarters_ago.py,sha256=A0ilwPKUqU0YYQSz3gNsVF0Jy4YttXrSaDhYj7y8GHA,713
 kfinance/tool_calling/get_prices_from_identifier.py,sha256=ViJkwLDvStB7grc8RuoKSDXQM399Wru4-OY3E8k1l_U,1882
+kfinance/tool_calling/get_segments_from_identifier.py,sha256=WIqJ1wWE6Z87VBREGu42nRc6_eJqUbGKcE9elzqBQJE,1867
 kfinance/tool_calling/resolve_identifier.py,sha256=npslr6bBCu0qEDV1-8d24F5OC3nQ1KBMphuMbHVC1AU,626
 kfinance/tool_calling/shared_models.py,sha256=K-NPQyE_7Ew6Cs0zxG1xO2O47gp5uDHdHtWD7wUDZX4,2132
-kensho_kfinance-2.2.2.dist-info/METADATA,sha256=VOmB9CZIcpr2DI5tJBZuWnR039oK_iRTN4cvDFco4RQ,3436
-kensho_kfinance-2.2.2.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
-kensho_kfinance-2.2.2.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-2.2.2.dist-info/RECORD,,
+kensho_kfinance-2.2.4.dist-info/METADATA,sha256=sx_SF7gbkLwRfyTRUw2WHaqkoSyqQfUoBUS5majgF7w,3436
+kensho_kfinance-2.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kensho_kfinance-2.2.4.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-2.2.4.dist-info/RECORD,,

{kensho_kfinance-2.2.2.dist-info → kensho_kfinance-2.2.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.8.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

kfinance/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v2.2.4
+- Add segments as llm tools
+
+## v2.2.3
+- Change segments return type to nested dictionary
+
 ## v2.2.2
 - Add segments
 

kfinance/constants.py

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

kfinance/meta_classes.py

@@ -312,7 +312,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 +322,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 +334,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 +341,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 +354,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 +373,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 +386,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,

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):

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):
         """

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,
 ]

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,
+        )

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.4'
+__version_tuple__ = version_tuple = (2, 2, 4)