kensho-kfinance 2.9.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

kfinance/{tests → client/tests}/test_client.py

@@ -2,18 +2,20 @@ from unittest.mock import Mock
 
 import pytest
 
-from kfinance.kfinance import Client
-from kfinance.models.permission_models import Permission
-from kfinance.tool_calling import (
-    GetBusinessRelationshipFromIdentifier,
-    GetEarnings,
-    GetFinancialStatementFromIdentifier,
-    GetLatest,
-    GetLatestEarnings,
-    GetNextEarnings,
-    GetTranscript,
+from kfinance.client.kfinance import Client
+from kfinance.client.permission_models import Permission
+from kfinance.domains.business_relationships.business_relationship_tools import (
+    GetBusinessRelationshipFromIdentifiers,
 )
-from kfinance.tool_calling.shared_models import KfinanceTool
+from kfinance.domains.earnings.earning_tools import (
+    GetEarningsFromIdentifiers,
+    GetLatestEarningsFromIdentifiers,
+    GetNextEarningsFromIdentifiers,
+    GetTranscriptFromKeyDevId,
+)
+from kfinance.domains.statements.statement_tools import GetFinancialStatementFromIdentifiers
+from kfinance.integrations.tool_calling.static_tools.get_latest import GetLatest
+from kfinance.integrations.tool_calling.tool_calling_models import KfinanceTool
 
 
 class TestLangchainTools:
@@ -52,19 +54,23 @@ class TestLangchainTools:
         mock_client.kfinance_api_client._user_permissions = {Permission.RelationshipPermission}  # noqa: SLF001
         tool_classes = [type(t) for t in mock_client.langchain_tools]
         # User should have access to GetBusinessRelationshipFromIdentifier
-        assert GetBusinessRelationshipFromIdentifier in tool_classes
+        assert GetBusinessRelationshipFromIdentifiers in tool_classes
         # User should have access to functions that don't require permissions
         assert GetLatest in tool_classes
         # User should not have access to functions that require statement permissions
-        assert GetFinancialStatementFromIdentifier not in tool_classes
+        assert GetFinancialStatementFromIdentifiers not in tool_classes
 
     @pytest.mark.parametrize(
         "user_permission, expected_tool",
         [
             pytest.param(
-                Permission.TranscriptsPermission, GetTranscript, id="Transcript Permissions"
+                Permission.TranscriptsPermission,
+                GetTranscriptFromKeyDevId,
+                id="Transcript Permissions",
+            ),
+            pytest.param(
+                Permission.EarningsPermission, GetEarningsFromIdentifiers, id="Earnings Permissions"
             ),
-            pytest.param(Permission.EarningsPermission, GetEarnings, id="Earnings Permissions"),
         ],
     )
     def test_permission_set_handling(
@@ -79,11 +85,11 @@ class TestLangchainTools:
         mock_client.kfinance_api_client._user_permissions = {user_permission}  # noqa: SLF001
         tool_classes = [type(t) for t in mock_client.langchain_tools]
         # User should have access to GetEarnings, GetNextEarnings, GetLatestEarnings, GetTranscript
-        assert GetEarnings in tool_classes
-        assert GetNextEarnings in tool_classes
-        assert GetLatestEarnings in tool_classes
+        assert GetEarningsFromIdentifiers in tool_classes
+        assert GetNextEarningsFromIdentifiers in tool_classes
+        assert GetLatestEarningsFromIdentifiers in tool_classes
         assert expected_tool in tool_classes
         # User should have access to functions that don't require permissions
         assert GetLatest in tool_classes
         # User should not have access to functions that require statement permissions
-        assert GetFinancialStatementFromIdentifier not in tool_classes
+        assert GetFinancialStatementFromIdentifiers not in tool_classes

kfinance/{tests → client/tests}/test_fetch.py

@@ -5,16 +5,15 @@ from pydantic import ValidationError
 import pytest
 from requests_mock import Mocker
 
-from kfinance.fetch import KFinanceApiClient
-from kfinance.kfinance import Client
-from kfinance.models.business_relationship_models import BusinessRelationshipType
-from kfinance.models.date_and_period_models import Periodicity, PeriodType
-from kfinance.pydantic_models import (
-    CompanyIdAndName,
+from kfinance.client.fetch import KFinanceApiClient
+from kfinance.client.kfinance import Client
+from kfinance.client.models.date_and_period_models import Periodicity, PeriodType
+from kfinance.conftest import SPGI_COMPANY_ID
+from kfinance.domains.business_relationships.business_relationship_models import (
+    BusinessRelationshipType,
     RelationshipResponse,
-    RelationshipResponseNoName,
 )
-from kfinance.tests.conftest import SPGI_COMPANY_ID
+from kfinance.domains.companies.company_models import CompanyIdAndName
 
 
 def build_mock_api_client() -> KFinanceApiClient:
@@ -150,7 +149,8 @@ class TestFetchItem(TestCase):
     def test_fetch_earnings(self) -> None:
         company_id = 21719
         expected_fetch_url = f"{self.kfinance_api_client.url_base}earnings/{company_id}"
-        self.kfinance_api_client.fetch_earnings(company_id=company_id)
+        with pytest.raises(ValidationError):
+            self.kfinance_api_client.fetch_earnings(company_id=company_id)
         self.kfinance_api_client.fetch.assert_called_once_with(expected_fetch_url)
 
     def test_fetch_transcript(self) -> None:
@@ -334,28 +334,10 @@ class TestMarketCap:
 
 
 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:
+    def test_fetch_business_relationships(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
+        WHEN the api returns a response
         THEN the response can successfully be parsed.
         """
 

kfinance/{tests → client/tests}/test_group_objects.py

@@ -1,6 +1,6 @@
 from unittest.mock import Mock
 
-from kfinance.kfinance import Client, IdentificationTriple, Tickers
+from kfinance.client.kfinance import Client, IdentificationTriple, Tickers
 
 
 class TestTickers:

kfinance/{tests → client/tests}/test_objects.py

@@ -10,7 +10,7 @@ import pandas as pd
 from PIL.Image import open as image_open
 import time_machine
 
-from kfinance.kfinance import (
+from kfinance.client.kfinance import (
     BusinessRelationships,
     Company,
     Earnings,
@@ -21,9 +21,13 @@ from kfinance.kfinance import (
     TradingItem,
     Transcript,
 )
-from kfinance.models.business_relationship_models import BusinessRelationshipType
-from kfinance.models.capitalization_models import Capitalizations
-from kfinance.pydantic_models import CompanyIdAndName, RelationshipResponse
+from kfinance.domains.business_relationships.business_relationship_models import (
+    BusinessRelationshipType,
+    RelationshipResponse,
+)
+from kfinance.domains.capitalizations.capitalization_models import Capitalizations
+from kfinance.domains.companies.company_models import CompanyIdAndName
+from kfinance.domains.earnings.earning_models import EarningsCallResp
 
 
 msft_company_id = "21835"
@@ -70,25 +74,27 @@ MOCK_COMPANY_DB = {
             "iso_country": "USA",
         },
         "earnings_call_dates": {"earnings": ["2004-07-22T21:30:00"]},
-        "earnings": {
-            "earnings": [
-                {
-                    "name": "Microsoft Corporation, Q4 2024 Earnings Call, Jul 25, 2024",
-                    "key_dev_id": 1916266380,
-                    "datetime": "2024-07-25T21:30:00",
-                },
-                {
-                    "name": "Microsoft Corporation, Q1 2025 Earnings Call, Oct 24, 2024",
-                    "keydevid": 1916266381,
-                    "datetime": "2024-10-24T21:30:00",
-                },
-                {
-                    "name": "Microsoft Corporation, Q2 2025 Earnings Call, Jan 25, 2025",
-                    "keydevid": 1916266382,
-                    "datetime": "2025-01-25T21:30:00",
-                },
-            ]
-        },
+        "earnings": EarningsCallResp.model_validate(
+            {
+                "earnings": [
+                    {
+                        "name": "Microsoft Corporation, Q4 2024 Earnings Call, Jul 25, 2024",
+                        "key_dev_id": 1916266380,
+                        "datetime": "2024-07-25T21:30:00Z",
+                    },
+                    {
+                        "name": "Microsoft Corporation, Q1 2025 Earnings Call, Oct 24, 2024",
+                        "key_dev_id": 1916266381,
+                        "datetime": "2024-10-24T21:30:00Z",
+                    },
+                    {
+                        "name": "Microsoft Corporation, Q2 2025 Earnings Call, Jan 25, 2025",
+                        "key_dev_id": 1916266382,
+                        "datetime": "2025-01-25T21:30:00Z",
+                    },
+                ]
+            }
+        ),
         "statements": {
             "income_statement": {
                 "statements": {
@@ -890,12 +896,10 @@ class TestTicker(TestCase):
         THEN the Ticker object can correctly extract market caps from the dict.
         """
 
-        expected_response = {
-            "market_cap": [
-                {"2025-01-01": {"unit": "USD", "value": "3133802247084.00"}},
-                {"2025-01-02": {"unit": "USD", "value": "3112092395218.00"}},
-            ]
-        }
+        expected_response = [
+            {"date": "2025-01-01", "market_cap": {"unit": "USD", "value": "3133802247084.00"}},
+            {"date": "2025-01-02", "market_cap": {"unit": "USD", "value": "3112092395218.00"}},
+        ]
         market_caps = self.msft_ticker_from_ticker.market_cap()
         assert market_caps == expected_response
 

kfinance/{tests/conftest.py → conftest.py}

@@ -3,7 +3,7 @@ from datetime import datetime
 import pytest
 from requests_mock import Mocker
 
-from kfinance.kfinance import Client
+from kfinance.client.kfinance import Client
 
 
 SPGI_COMPANY_ID = 21719
@@ -18,7 +18,7 @@ def mock_client(requests_mock: Mocker) -> Client:
     client = Client(refresh_token="foo")
     # Set access token so that the client doesn't try to fetch it.
     client.kfinance_api_client._access_token = "foo"  # noqa: SLF001
-    client.kfinance_api_client._access_token_expiry = datetime(2100, 1, 1).timestamp()  # noqa: SLF001
+    client.kfinance_api_client._access_token_expiry = int(datetime(2100, 1, 1).timestamp())  # noqa: SLF001
 
     # Create a mock for the SPGI id triple.
     requests_mock.get(
@@ -33,4 +33,16 @@ def mock_client(requests_mock: Mocker) -> Client:
         url="https://kfinance.kensho.com/api/v1/id/MSFT",
         json={"trading_item_id": 2630413, "security_id": 2630412, "company_id": 21835},
     )
+
+    # Create mock security id and trading item id for company ids 1 and 2:
+    for company_id in [1, 2]:
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/securities/{company_id}/primary",
+            json={"primary_security": company_id},
+        )
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/trading_items/{company_id}/primary",
+            json={"primary_trading_item": company_id},
+        )
+
     return client

kfinance/domains/README.md

@@ -0,0 +1,14 @@
+# Domains
+
+Domains loosely correspond to datasets and permission boundaries. 
+They are used to group together related tools and models, 
+for example all earnings related tools and models.
+
+There are no hard boundaries around what constitutes a domain. If you
+think it makes sense to group certain tools or models together, it probably does.
+
+Each domain will usually have a tools file with `KfinanceTools` and a
+models file with enums, pydantic models, data classes, or typed dicts 
+related to the domain. We may at some point also move ORM models related
+to the domain into these sub folders. Each domain should have a `tests` 
+directory for tool and model tests.

kfinance/{models → domains/business_relationships}/business_relationship_models.py

@@ -1,5 +1,8 @@
+from pydantic import BaseModel
 from strenum import StrEnum
 
+from kfinance.domains.companies.company_models import CompanyIdAndName
+
 
 class BusinessRelationshipType(StrEnum):
     """The type of business relationship"""
@@ -24,3 +27,10 @@ class BusinessRelationshipType(StrEnum):
     transfer_agent_client = "transfer_agent_client"
     vendor = "vendor"
     client_services = "client_services"
+
+
+class RelationshipResponse(BaseModel):
+    """A response from the relationship endpoint that includes both company_id and name."""
+
+    current: list[CompanyIdAndName]
+    previous: list[CompanyIdAndName]

kfinance/domains/business_relationships/business_relationship_tools.py

@@ -0,0 +1,74 @@
+from textwrap import dedent
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.client.batch_request_handling import Task, process_tasks_in_thread_pool_executor
+from kfinance.client.permission_models import Permission
+from kfinance.domains.business_relationships.business_relationship_models import (
+    BusinessRelationshipType,
+)
+from kfinance.domains.companies.company_identifiers import (
+    fetch_company_ids_from_identifiers,
+    parse_identifiers,
+)
+from kfinance.integrations.tool_calling.tool_calling_models import (
+    KfinanceTool,
+    ToolArgsWithIdentifiers,
+)
+
+
+class GetBusinessRelationshipFromIdentifiersArgs(ToolArgsWithIdentifiers):
+    # no description because the description for enum fields comes from the enum docstring.
+    business_relationship: BusinessRelationshipType
+
+
+class GetBusinessRelationshipFromIdentifiers(KfinanceTool):
+    name: str = "get_business_relationship_from_identifiers"
+    description: str = dedent("""
+        Get the current and previous company IDs that are relationship_type for a list of identifiers.
+
+        Example:
+        Query: "What are the previous borrowers of SPGI and JPM?"
+        Function: get_business_relationship_from_identifiers(identifiers=["SPGI", "JPM"], business_relationship=BusinessRelationshipType.borrower)
+    """).strip()
+    args_schema: Type[BaseModel] = GetBusinessRelationshipFromIdentifiersArgs
+    accepted_permissions: set[Permission] | None = {Permission.RelationshipPermission}
+
+    def _run(self, identifiers: list[str], business_relationship: BusinessRelationshipType) -> dict:
+        """Sample response:
+
+        {
+            "SPGI": {
+                "current": [{"company_id": "C_883103", "company_name": "CRISIL Limited"}],
+                "previous": [
+                    {"company_id": "C_472898", "company_name": "Morgan Stanley"},
+                    {"company_id": "C_8182358", "company_name": "Eloqua, Inc."},
+                ],
+            }
+        }
+        """
+
+        api_client = self.kfinance_client.kfinance_api_client
+        parsed_identifiers = parse_identifiers(identifiers=identifiers, api_client=api_client)
+        identifiers_to_company_ids = fetch_company_ids_from_identifiers(
+            identifiers=parsed_identifiers, api_client=api_client
+        )
+
+        tasks = [
+            Task(
+                func=api_client.fetch_companies_from_business_relationship,
+                kwargs=dict(
+                    company_id=company_id,
+                    relationship_type=business_relationship,
+                ),
+                result_key=identifier,
+            )
+            for identifier, company_id in identifiers_to_company_ids.items()
+        ]
+
+        relationship_responses = process_tasks_in_thread_pool_executor(
+            api_client=api_client, tasks=tasks
+        )
+
+        return {str(k): v.model_dump(mode="json") for k, v in relationship_responses.items()}

kfinance/domains/business_relationships/tests/test_business_relationship_tools.py

@@ -0,0 +1,55 @@
+from requests_mock import Mocker
+
+from kfinance.client.kfinance import Client
+from kfinance.conftest import SPGI_COMPANY_ID
+from kfinance.domains.business_relationships.business_relationship_models import (
+    BusinessRelationshipType,
+)
+from kfinance.domains.business_relationships.business_relationship_tools import (
+    GetBusinessRelationshipFromIdentifiers,
+    GetBusinessRelationshipFromIdentifiersArgs,
+)
+
+
+class TestGetBusinessRelationshipFromIdentifiers:
+    def test_get_business_relationship_from_identifiers(
+        self, requests_mock: Mocker, mock_client: Client
+    ):
+        """
+        GIVEN the GetBusinessRelationshipFromIdentifiers tool
+        WHEN we request SPGI suppliers
+        THEN we get back the SPGI suppliers
+        """
+        supplier_resp = {
+            "current": [{"company_id": 883103, "company_name": "CRISIL Limited"}],
+            "previous": [
+                {"company_id": 472898, "company_name": "Morgan Stanley"},
+                {"company_id": 8182358, "company_name": "Eloqua, Inc."},
+            ],
+        }
+        expected_result = {
+            "SPGI": {
+                "current": [{"company_id": "C_883103", "company_name": "CRISIL Limited"}],
+                "previous": [
+                    {"company_id": "C_472898", "company_name": "Morgan Stanley"},
+                    {"company_id": "C_8182358", "company_name": "Eloqua, Inc."},
+                ],
+            }
+        }
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/relationship/{SPGI_COMPANY_ID}/supplier",
+            json=supplier_resp,
+        )
+
+        tool = GetBusinessRelationshipFromIdentifiers(kfinance_client=mock_client)
+        args = GetBusinessRelationshipFromIdentifiersArgs(
+            identifiers=["SPGI"], business_relationship=BusinessRelationshipType.supplier
+        )
+        resp = tool.run(args.model_dump(mode="json"))
+
+        assert list(resp.keys()) == ["SPGI"]
+        # Sort companies by ID to make the result deterministic
+        resp["SPGI"]["current"].sort(key=lambda x: x["company_id"])
+        resp["SPGI"]["previous"].sort(key=lambda x: x["company_id"])
+        assert resp == expected_result

kfinance/{models → domains/capitalizations}/capitalization_models.py

@@ -5,7 +5,7 @@ from typing import Any
 from pydantic import BaseModel, Field, model_validator
 from strenum import StrEnum
 
-from kfinance.decimal_with_unit import Money, Shares
+from kfinance.client.models.decimal_with_unit import Money, Shares
 
 
 class Capitalization(StrEnum):
@@ -68,23 +68,30 @@ class Capitalizations(BaseModel):
                     capitalization[key] = dict(unit=currency, value=capitalization[key])
         return data
 
-    def jsonify_single_attribute(self, capitalization_to_extract: Capitalization) -> dict:
-        """Return a json representation of a single attribute like "market_cap".
+    def model_dump_json_single_metric(
+        self, capitalization_metric: Capitalization, only_include_most_recent_value: bool = False
+    ) -> dict:
+        """Dump only a single metric (market cap, tev, or shares outstanding) to json
 
-        Example response:
-        {
-            "market_cap": [
-                {'2024-06-24': {'unit': 'USD', 'value': '139231113000.00'}},
-                {'2024-06-25': {'unit': 'USD', 'value': '140423262000.00'}}
-            ]
-        }
+        If only_include_most_recent_value is set to True, only the most recent value gets included.
 
+        Sample response:
+        [
+            {
+                'date': datetime.date(2024, 4, 10),
+                'market_cap': {'value': Decimal('132766738270.00'), 'unit': 'USD'}
+            }
+        ]
         """
 
-        capitalizations = []
-        for capitalization in self.capitalizations:
-            attribute_val = getattr(capitalization, capitalization_to_extract.value)
-            capitalizations.append(
-                {capitalization.date.isoformat(): attribute_val.model_dump(mode="json")}
-            )
-        return {capitalization_to_extract: capitalizations}
+        return self.model_dump(
+            mode="json",
+            include={  # type: ignore[arg-type]
+                "capitalizations": {
+                    0 if only_include_most_recent_value else "__all__": {
+                        "date",
+                        capitalization_metric.value,
+                    }
+                }
+            },
+        )["capitalizations"]

kfinance/domains/capitalizations/capitalization_tools.py

@@ -0,0 +1,89 @@
+from datetime import date
+from textwrap import dedent
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+from kfinance.client.batch_request_handling import Task, process_tasks_in_thread_pool_executor
+from kfinance.client.permission_models import Permission
+from kfinance.domains.capitalizations.capitalization_models import Capitalization
+from kfinance.domains.companies.company_identifiers import (
+    fetch_company_ids_from_identifiers,
+    parse_identifiers,
+)
+from kfinance.integrations.tool_calling.tool_calling_models import (
+    KfinanceTool,
+    ToolArgsWithIdentifiers,
+)
+
+
+class GetCapitalizationFromIdentifiersArgs(ToolArgsWithIdentifiers):
+    # no description because the description for enum fields comes from the enum docstring.
+    capitalization: Capitalization
+    start_date: date | None = Field(
+        description="The start date for historical capitalization retrieval", default=None
+    )
+    end_date: date | None = Field(
+        description="The end date for historical capitalization retrieval", default=None
+    )
+
+
+class GetCapitalizationFromIdentifiers(KfinanceTool):
+    name: str = "get_capitalization_from_identifiers"
+    description: str = dedent("""
+        Get the historical market cap, tev (Total Enterprise Value), or shares outstanding for a group of identifiers between inclusive start_date and inclusive end date.
+
+        - When possible, pass multiple identifiers in a single call rather than making multiple calls.
+        - When requesting the most recent values, leave start_date and end_date empty.
+
+        Example:
+        Query: "What are the market caps of AAPL and WMT?"
+        Function: get_capitalization_from_identifiers(capitalization=Capitalization.market_cap, identifiers=["AAPL", "WMT"])
+    """).strip()
+    args_schema: Type[BaseModel] = GetCapitalizationFromIdentifiersArgs
+    accepted_permissions: set[Permission] | None = {Permission.PricingPermission}
+
+    def _run(
+        self,
+        identifiers: list[str],
+        capitalization: Capitalization,
+        start_date: str | None = None,
+        end_date: str | None = None,
+    ) -> dict:
+        """Sample response:
+
+        {
+            'SPGI': [
+                {'date': '2024-04-10', 'market_cap': {'unit': 'USD', 'value': '132766738270.00'}},
+                {'date': '2024-04-11', 'market_cap': {'unit': 'USD', 'value': '132416066761.00'}}
+            ]
+        }
+        """
+        api_client = self.kfinance_client.kfinance_api_client
+        parsed_identifiers = parse_identifiers(identifiers=identifiers, api_client=api_client)
+        identifiers_to_company_ids = fetch_company_ids_from_identifiers(
+            identifiers=parsed_identifiers, api_client=api_client
+        )
+
+        tasks = [
+            Task(
+                func=api_client.fetch_market_caps_tevs_and_shares_outstanding,
+                kwargs=dict(company_id=company_id, start_date=start_date, end_date=end_date),
+                result_key=identifier,
+            )
+            for identifier, company_id in identifiers_to_company_ids.items()
+        ]
+
+        capitalization_responses = process_tasks_in_thread_pool_executor(
+            api_client=api_client, tasks=tasks
+        )
+
+        return {
+            str(identifier): capitalization_response.model_dump_json_single_metric(
+                capitalization_metric=capitalization,
+                only_include_most_recent_value=True
+                if (len(identifiers) > 1 and start_date == end_date is None)
+                else False,
+            )
+            for identifier, capitalization_response in capitalization_responses.items()
+        }

kfinance/{tests/test_models → domains/capitalizations/tests}/test_capitalization_models.py

@@ -1,8 +1,8 @@
 from datetime import date
 from decimal import Decimal
 
-from kfinance.decimal_with_unit import Money, Shares
-from kfinance.models.capitalization_models import (
+from kfinance.client.models.decimal_with_unit import Money, Shares
+from kfinance.domains.capitalizations.capitalization_models import (
     Capitalization,
     Capitalizations,
     DailyCapitalization,
@@ -69,15 +69,13 @@ class TestCapitalizations:
     def test_single_attribute_serialization(self):
         """
         GIVEN a Capitalizations object
-        WHEN we only want to jsonify a single attribute like market_cap
+        WHEN we only want to dump a single attribute like market_cap
         THEN that attribute gets returned in an LLM-readable, jsonifyable dict format
         """
-        expected_serialization = {
-            "market_cap": [
-                {"2024-06-24": {"unit": "USD", "value": "139231113000.00"}},
-                {"2024-06-25": {"unit": "USD", "value": "140423262000.00"}},
-            ]
-        }
+        expected_serialization = [
+            {"date": "2024-06-24", "market_cap": {"unit": "USD", "value": "139231113000.00"}},
+            {"date": "2024-06-25", "market_cap": {"unit": "USD", "value": "140423262000.00"}},
+        ]
         capitalizations = Capitalizations.model_validate(self.api_resp)
-        serialized = capitalizations.jsonify_single_attribute(Capitalization.market_cap)
+        serialized = capitalizations.model_dump_json_single_metric(Capitalization.market_cap)
         assert serialized == expected_serialization