kensho-kfinance 3.2.7__py3-none-any.whl → 3.2.9__py3-none-any.whl

{kensho_kfinance-3.2.7.dist-info → kensho_kfinance-3.2.9.dist-info}/METADATA

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

@@ -1,11 +1,11 @@
-kensho_kfinance-3.2.7.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-3.2.7.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=UddmW-btMQ2H8aUNxY3gIHVd_Lmr5toYlD-r0L5A-PQ,3054
+kensho_kfinance-3.2.9.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-3.2.9.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=Bmr-5uaCGmPyE6Io5wRAp9XtbTvirW4WEiezpVxBqeA,3331
 kfinance/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 kfinance/conftest.py,sha256=FIZNQyfFbldyVmzaLfWbnMGh6RiC4MZwOVax6815_Ms,3754
 kfinance/mcp.py,sha256=LTzCIlqsDKRD-0Xcpa_P99-JmJ8duAneO_-GzM43kjw,424
 kfinance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/version.py,sha256=ADz4iV30MoA4-uH6aIZn2XG9xptnnO-_t_Do6H2M4s0,704
+kfinance/version.py,sha256=d825_zg1e75hjTXcJJrUYWF2PzVuogUemVjSrnFB5a8,704
 kfinance/client/README.md,sha256=DA5vg4uz1JmJNiqvYywrj46YNhOr584WO8L83Ysx_Mk,372
 kfinance/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/client/batch_request_handling.py,sha256=opwJJAU2JtqH-s4vt8wRqhH34MiU4tQP6Ng7K6b3upA,6561
@@ -61,10 +61,10 @@ kfinance/domains/earnings/earning_tools.py,sha256=AmHZQKTGExPPxyDdjhrn5CVLvWr6xM
 kfinance/domains/earnings/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/domains/earnings/tests/test_earnings_tools.py,sha256=qGhdWI1s4uEjF6XtFC0f1nlAths1H6xfym-iJyBpwBo,6998
 kfinance/domains/line_items/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/domains/line_items/line_item_models.py,sha256=qDvY2dVGNP9JlujuHYefoi3Q9Yg0ICyEi4HsHx5Cneg,50962
-kfinance/domains/line_items/line_item_tools.py,sha256=fLLEGND7S8MLd-0sGKgWUxb3JZP4Rdq4b4azjzlTrZo,4929
+kfinance/domains/line_items/line_item_models.py,sha256=6J_9cko9nZ3OAGSC7OMGEMQW8dkXjRLWn4_2BjtHemU,50969
+kfinance/domains/line_items/line_item_tools.py,sha256=lxvhYbnZKapIf2nIfdtVqXiDswJoeU5XxMOAGUeb8cI,5192
 kfinance/domains/line_items/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/domains/line_items/tests/test_line_item_tools.py,sha256=Bxsf0cGTxbc3dZ6djbC53pA3l0kzogA942LJFNfkuYQ,4082
+kfinance/domains/line_items/tests/test_line_item_tools.py,sha256=vgxJsPbQG1msXZKTfpyHSzUfhw0GvfxZ041T7J-56hU,5499
 kfinance/domains/mergers_and_acquisitions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/domains/mergers_and_acquisitions/merger_and_acquisition_models.py,sha256=WAWyBCgYMZj8NLz6nq_sW5MRg_UU5_F9jUUoQ_bcmsM,1893
 kfinance/domains/mergers_and_acquisitions/merger_and_acquisition_tools.py,sha256=Yx3_TxTWdPcIiOddyAJEddpWc6L-fgx1-JoMtqdPtWQ,7156
@@ -78,14 +78,14 @@ kfinance/domains/prices/tests/test_price_models.py,sha256=PWGqbR9aCys2ldHZMF5anM
 kfinance/domains/prices/tests/test_price_tools.py,sha256=xNuzAzeu1KuhkB0xF2oIYLVZub9uDg8VLRNmKq-iJ3s,6426
 kfinance/domains/segments/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/domains/segments/segment_models.py,sha256=CEZK_B9WM0eppsOpjUbt-ILIcLkQMYgVq4TAx_SrPlc,262
-kfinance/domains/segments/segment_tools.py,sha256=DhbTnH6JwRbkJsUqR3bMtzlSNggg9wATRXFo8x4XXho,4330
+kfinance/domains/segments/segment_tools.py,sha256=3zOAn0tayBykTNiprwn32hH-Q0sNJrPwMhnoGSs6yYo,4654
 kfinance/domains/segments/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/domains/segments/tests/test_segment_tools.py,sha256=aOesRHFjR9FG0urmiPCzxYXDNjnrw8sqKovuEnDPHC8,3574
+kfinance/domains/segments/tests/test_segment_tools.py,sha256=Qmh1SpGwVGUhe_r1b4ZpBesu_yN2hq2wiM3z1wmmY6M,4975
 kfinance/domains/statements/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/domains/statements/statement_models.py,sha256=f7jEejuvMbsW9paqHIJ19DKUX3XL_qzf74jZBKDamfE,328
-kfinance/domains/statements/statement_tools.py,sha256=8zJZtPktbszVuwKifPhY0_k3nsJALyR2SjZoqgEp5gE,4898
+kfinance/domains/statements/statement_tools.py,sha256=RHNQmv4yExXHHxokwgxzLuYG9iCfZuOKRRThm-K3mOQ,5162
 kfinance/domains/statements/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/domains/statements/tests/test_statement_tools.py,sha256=ruojqNUnnBYynJpjl6Oj62c-K2eXV4Gh0whvcgRw3N0,4355
+kfinance/domains/statements/tests/test_statement_tools.py,sha256=mraxvm6tpd-SFRIcco9dKRR2VC8kg1LlYcggBBocLBA,6052
 kfinance/integrations/README.md,sha256=GalSN11UHzbLfcNzKAlObNbw5XqMKVXSVzzGlryM3zc,320
 kfinance/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/integrations/local_mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -108,7 +108,7 @@ kfinance/integrations/tool_calling/static_tools/tests/test_get_n_quarters_ago.py
 kfinance/integrations/tool_calling/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/integrations/tool_calling/tests/test_tool_calling_models.py,sha256=FIusHU4kFmVPuh31Kn57_356tNNVMGTbHApMUFJOaGM,2724
 kfinance/models/permission_models.py,sha256=G0so8ZOsD1YDsCM4he0z5R9M_shUbSRwD3hUDJdqZl0,635
-kensho_kfinance-3.2.7.dist-info/METADATA,sha256=_44qoF4hacG441wRJuZwFy-snXawFUdtnl4zsY1al7A,6197
-kensho_kfinance-3.2.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kensho_kfinance-3.2.7.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-3.2.7.dist-info/RECORD,,
+kensho_kfinance-3.2.9.dist-info/METADATA,sha256=mKEsNivUKkpEoAL43ulOOgv4tTDLUFOfeYCNak7x3VE,6197
+kensho_kfinance-3.2.9.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kensho_kfinance-3.2.9.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-3.2.9.dist-info/RECORD,,

kfinance/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+# v3.2.9
+- Updated tool descriptions for line items, segments, and statements to mention that all period-based inputs and outputs refer only to the calendar year.
+
+# v3.2.8
+- Added support for None to LineItemResponse & empty behavior for line items, segments, and statements
+
 # v3.2.7
 - Fix validator for UnifiedIdTripleResponse
 

kfinance/domains/line_items/line_item_models.py

@@ -6,7 +6,7 @@ from pydantic import BaseModel
 
 
 class LineItemResponse(BaseModel):
-    line_item: dict[str, Decimal]
+    line_item: dict[str, Decimal | None]
 
 
 class LineItemType(TypedDict):

kfinance/domains/line_items/line_item_tools.py

@@ -43,6 +43,7 @@ class GetFinancialLineItemFromIdentifiers(KfinanceTool):
 
         - When possible, pass multiple identifiers in a single call rather than making multiple calls.
         - To fetch the most recent value for the line item, leave start_year, start_quarter, end_year, and end_quarter as None.
+        - The tool accepts arguments in calendar years, and all outputs will be presented in terms of calendar years. Please note that these calendar years may not align with the company's fiscal year.
 
         Example:
         Query: "What are the revenues of Lowe's and Home Depot?"
@@ -109,9 +110,10 @@ class GetFinancialLineItemFromIdentifiers(KfinanceTool):
             and len(line_item_responses) > 1
         ):
             for line_item_response in line_item_responses.values():
-                most_recent_year = max(line_item_response.line_item.keys())
-                most_recent_year_data = line_item_response.line_item[most_recent_year]
-                line_item_response.line_item = {most_recent_year: most_recent_year_data}
+                if line_item_response.line_item:
+                    most_recent_year = max(line_item_response.line_item.keys())
+                    most_recent_year_data = line_item_response.line_item[most_recent_year]
+                    line_item_response.line_item = {most_recent_year: most_recent_year_data}
 
         return GetFinancialLineItemFromIdentifiersResp(
             results=line_item_responses, errors=list(id_triple_resp.errors.values())

kfinance/domains/line_items/tests/test_line_item_tools.py

@@ -86,6 +86,38 @@ class TestGetFinancialLineItemFromCompanyIds:
         response = tool.run(args.model_dump(mode="json"))
         assert response == expected_response
 
+    def test_empty_most_recent_request(self, requests_mock: Mocker, mock_client: Client) -> None:
+        """
+        GIVEN the GetFinancialLineItemFromIdentifiers tool
+        WHEN we request most recent line items for multiple companies
+        THEN we only get back the most recent line item for each company
+        UNLESS no line items exist
+        """
+
+        company_ids = [1, 2]
+
+        c_1_line_item_resp = LineItemResponse(line_item={})
+        c_2_line_item_resp = LineItemResponse(line_item={"2024": Decimal(14208000000)})
+        expected_response = GetFinancialLineItemFromIdentifiersResp(
+            results={"C_1": c_1_line_item_resp, "C_2": c_2_line_item_resp},
+        )
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/line_item/1/revenue/none/none/none/none/none",
+            json={"line_item": {}},
+        )
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/line_item/2/revenue/none/none/none/none/none",
+            json=self.line_item_resp,
+        )
+        tool = GetFinancialLineItemFromIdentifiers(kfinance_client=mock_client)
+        args = GetFinancialLineItemFromIdentifiersArgs(
+            identifiers=[f"{COMPANY_ID_PREFIX}{company_id}" for company_id in company_ids],
+            line_item="revenue",
+        )
+        response = tool.run(args.model_dump(mode="json"))
+        assert response == expected_response
+
     def test_line_items_and_aliases_included_in_schema(self, mock_client: Client):
         """
         GIVEN a GetFinancialLineItemFromCompanyIds tool

kfinance/domains/segments/segment_tools.py

@@ -1,3 +1,4 @@
+from textwrap import dedent
 from typing import Literal, Type
 
 from pydantic import BaseModel, Field
@@ -30,7 +31,11 @@ class GetSegmentsFromIdentifiersResp(ToolRespWithErrors):
 
 class GetSegmentsFromIdentifiers(KfinanceTool):
     name: str = "get_segments_from_identifiers"
-    description: str = "Get the templated segments associated with a list of identifiers."
+    description: str = dedent("""
+        Get the templated segments associated with a list of identifiers.
+
+        - The tool accepts arguments in calendar years, and all outputs will be presented in terms of calendar years. Please note that these calendar years may not align with the company's fiscal year.
+    """).strip()
     args_schema: Type[BaseModel] = GetSegmentsFromIdentifiersArgs
     accepted_permissions: set[Permission] | None = {Permission.SegmentsPermission}
 
@@ -98,9 +103,10 @@ class GetSegmentsFromIdentifiers(KfinanceTool):
             and len(segments_responses) > 1
         ):
             for segments_response in segments_responses.values():
-                most_recent_year = max(segments_response.segments.keys())
-                most_recent_year_data = segments_response.segments[most_recent_year]
-                segments_response.segments = {most_recent_year: most_recent_year_data}
+                if segments_response.segments:
+                    most_recent_year = max(segments_response.segments.keys())
+                    most_recent_year_data = segments_response.segments[most_recent_year]
+                    segments_response.segments = {most_recent_year: most_recent_year_data}
 
         return GetSegmentsFromIdentifiersResp(
             results=segments_responses, errors=list(id_triple_resp.errors.values())

kfinance/domains/segments/tests/test_segment_tools.py

@@ -63,8 +63,8 @@ class TestGetSegmentsFromIdentifier:
     def test_most_recent_request(self, requests_mock: Mocker, mock_client: Client) -> None:
         """
         GIVEN the GetFinancialLineItemFromIdentifiers tool
-        WHEN we request most recent statement for multiple companies
-        THEN we only get back the most recent statement for each company
+        WHEN we request most recent segment for multiple companies
+        THEN we only get back the most recent segment for each company
         """
 
         company_ids = [1, 2]
@@ -90,3 +90,38 @@ class TestGetSegmentsFromIdentifier:
         )
         response = tool.run(args.model_dump(mode="json"))
         assert response == expected_response
+
+    def test_empty_most_recent_request(self, requests_mock: Mocker, mock_client: Client) -> None:
+        """
+        GIVEN the GetFinancialLineItemFromIdentifiers tool
+        WHEN we request most recent segment for multiple companies
+        THEN we only get back the most recent segment for each company
+        UNLESS no segments exist
+        """
+
+        company_ids = [1, 2]
+        expected_response = GetSegmentsFromIdentifiersResp.model_validate(
+            {
+                "results": {
+                    "C_1": {"segments": {}},
+                    "C_2": {"segments": {"2021": self.segments_response["segments"]["2021"]}},
+                }
+            }
+        )
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/segments/1/business/none/none/none/none/none",
+            json={"segments": {}},
+        )
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/segments/2/business/none/none/none/none/none",
+            json=self.segments_response,
+        )
+
+        tool = GetSegmentsFromIdentifiers(kfinance_client=mock_client)
+        args = GetSegmentsFromIdentifiersArgs(
+            identifiers=[f"{COMPANY_ID_PREFIX}{company_id}" for company_id in company_ids],
+            segment_type=SegmentType.business,
+        )
+        response = tool.run(args.model_dump(mode="json"))
+        assert response == expected_response

kfinance/domains/statements/statement_tools.py

@@ -35,6 +35,7 @@ class GetFinancialStatementFromIdentifiers(KfinanceTool):
         Get a financial statement associated with a group of identifiers.
 
         - To fetch the most recent value for the statement, leave start_year, start_quarter, end_year, and end_quarter as None.
+        - The tool accepts arguments in calendar years, and all outputs will be presented in terms of calendar years. Please note that these calendar years may not align with the company's fiscal year.
 
         Example:
         Query: "Fetch the balance sheets of BAC and GS for 2024"
@@ -105,9 +106,10 @@ class GetFinancialStatementFromIdentifiers(KfinanceTool):
             and len(statement_responses) > 1
         ):
             for statement_response in statement_responses.values():
-                most_recent_year = max(statement_response.statements.keys())
-                most_recent_year_data = statement_response.statements[most_recent_year]
-                statement_response.statements = {most_recent_year: most_recent_year_data}
+                if statement_response.statements:
+                    most_recent_year = max(statement_response.statements.keys())
+                    most_recent_year_data = statement_response.statements[most_recent_year]
+                    statement_response.statements = {most_recent_year: most_recent_year_data}
 
         return GetFinancialStatementFromIdentifiersResp(
             results=statement_responses, errors=list(id_triple_resp.errors.values())

kfinance/domains/statements/tests/test_statement_tools.py

@@ -105,3 +105,45 @@ class TestGetFinancialStatementFromIdentifiers:
         )
         response = tool.run(args.model_dump(mode="json"))
         assert response == expected_response
+
+    def test_empty_most_recent_request(self, requests_mock: Mocker, mock_client: Client) -> None:
+        """
+        GIVEN the GetFinancialStatementFromIdentifiers tool
+        WHEN we request most recent statement for multiple companies
+        THEN we only get back the most recent statement for each company
+        UNLESS no statements exist
+        """
+
+        company_ids = [1, 2]
+        expected_response = GetFinancialStatementFromIdentifiersResp.model_validate(
+            {
+                "results": {
+                    "C_1": {"statements": {}},
+                    "C_2": {
+                        "statements": {
+                            "2021": {
+                                "Revenues": "8243000000.000000",
+                                "Total Revenues": "8243000000.000000",
+                            }
+                        }
+                    },
+                }
+            }
+        )
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/statements/1/income_statement/none/none/none/none/none",
+            json={"statements": {}},
+        )
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/statements/2/income_statement/none/none/none/none/none",
+            json=self.statement_resp,
+        )
+
+        tool = GetFinancialStatementFromIdentifiers(kfinance_client=mock_client)
+        args = GetFinancialStatementFromIdentifiersArgs(
+            identifiers=[f"{COMPANY_ID_PREFIX}{company_id}" for company_id in company_ids],
+            statement=StatementType.income_statement,
+        )
+        response = tool.run(args.model_dump(mode="json"))
+        assert response == expected_response

kfinance/version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '3.2.7'
-__version_tuple__ = version_tuple = (3, 2, 7)
+__version__ = version = '3.2.9'
+__version_tuple__ = version_tuple = (3, 2, 9)
 
 __commit_id__ = commit_id = None