kensho-kfinance 2.7.0__py3-none-any.whl → 2.8.0__py3-none-any.whl

{kensho_kfinance-2.7.0.dist-info → kensho_kfinance-2.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.7.0
+Version: 2.8.0
 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.8.0.dist-info/RECORD

@@ -0,0 +1,70 @@
+kensho_kfinance-2.8.0.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-2.8.0.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=JaR2dyTzhmue8dt6LVbt8ckSFTuqnJuqP5mYaePs85A,2245
+kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kfinance/batch_request_handling.py,sha256=G9rhpgQaCdb5C1dsfuJip8383iszibcOJ5k8gxld-tQ,5001
+kfinance/decimal_with_unit.py,sha256=U1eJSJ-4zPHkdtHcrfaW9CmmaLPE13MiWJy6odRyeXo,2904
+kfinance/fetch.py,sha256=MSdDddZ_1YdmzCuXqCXwY_vfFLdbdQeCJ6YRQrwCUCI,28157
+kfinance/kfinance.py,sha256=qa8oOFBayT2zIdvDh4Gizg1aF_PNWJrsvoAd1q5Oflg,73225
+kfinance/mcp.py,sha256=MbktclVfBOEwfe-eR7kPaTXopMJmn_8RMlf4Jx5CXKU,3689
+kfinance/meta_classes.py,sha256=0wI70PXfQzNbRUW2nYVfxJjqCqqI5EukUIKjaMcrzVA,21804
+kfinance/prompt.py,sha256=PtVB8c_FcSlVdyGgByAnIFGzuUuBaEjciCqnBJl1hSQ,25133
+kfinance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kfinance/pydantic_models.py,sha256=avpbPqwrAyLqsCbrmFpK_B8_fj1nPlBHrnPxRcBaSkE,774
+kfinance/server_thread.py,sha256=jUnt1YGoYDkqqz1MbCwd44zJs1T_Z2BCgvj75bdtLgA,2574
+kfinance/version.py,sha256=xvvCLYZzL60ATcl_e94czeUS6YcsWE3LumbDKAyCfWM,511
+kfinance/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kfinance/models/business_relationship_models.py,sha256=XlkYI_XUegORH4U4oLXjdFIX9Pr9FvQUnFAc67D2M4s,770
+kfinance/models/capitalization_models.py,sha256=jB0MIZ94UOPfVckuS2asED9ARjisrStC_O4KgfHmoJw,3193
+kfinance/models/competitor_models.py,sha256=0yDu49Pe28ErpCMLX-BBeUnjjxqerb49ToVKSTOivNk,565
+kfinance/models/currency_models.py,sha256=JfDZf-nATCyjThBw-Ky2BNvM-n2oHepBLIHMCIyCRUE,19201
+kfinance/models/date_and_period_models.py,sha256=B508v1SLy_mbSSuSbPz41xeFNRAeBFv41gJSlaXyHnU,1062
+kfinance/models/id_models.py,sha256=xhFKmDddBfqkQZsbOP8za8VnxIFHiwvGThKjeGKC2Hg,138
+kfinance/models/industry_models.py,sha256=ydB_cTIsNsfCUeaO7K2qqLUuHdG6WfUCoAzBigKVV8M,243
+kfinance/models/line_item_models.py,sha256=JIdoSYxoJDQVkmqUK6_ABpb6lULXRvrCDJGiKL6kRhE,45399
+kfinance/models/permission_models.py,sha256=z6MKY7Zf7StPKwsucsoVqltUesicU6MC6rxRGmlRwZI,557
+kfinance/models/price_models.py,sha256=saiJk1ZIs02cHtY54-5YvS7NgH3EABR2RGT6wpzRauY,2149
+kfinance/models/segment_models.py,sha256=GSJhK1HmbMmwRDFmrDTZzx8aYrAaHN13IJ0J9GTBn9Y,145
+kfinance/models/statement_models.py,sha256=RmclTeyahCODUP0-KgZZZequFgQ2pUQ8cdfHI96c9vA,207
+kfinance/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kfinance/tests/conftest.py,sha256=dhL_RSc-af3j-2_UrAGRE9mxgcbjuIRtj08DTx79pQc,1123
+kfinance/tests/test_batch_requests.py,sha256=JjP5OOKyxzYqmVmTR2hzM4Q6wyYDCEDHINH4vNFd6ag,11597
+kfinance/tests/test_client.py,sha256=YZT-AXpFsVHpdoZj01d2TkmUkNP-8f3cIOgeXtP_05U,3870
+kfinance/tests/test_decimal_with_unit.py,sha256=98zZmSLojWq3FS0e5AuNxv9eluqGVEoqM3r_agkmt_Y,2188
+kfinance/tests/test_example_notebook.py,sha256=VFS2W_T0yEtd74YiRxj3KA7eEL_fJuCpWwUAkiFqzkc,6501
+kfinance/tests/test_fetch.py,sha256=s8fSkXDtNjDcK_jWQYUO1stx9ElX1I54qG_48WxfBAc,18558
+kfinance/tests/test_group_objects.py,sha256=SoMEZmkG4RYdgWOAwxLHHtzIQho92KM01YbQXPUg578,1689
+kfinance/tests/test_objects.py,sha256=Fd5iYy-Ofzil3xJr5hLflsvvNVwoWfEDDiRZb_-LVKc,41082
+kfinance/tests/test_tools.py,sha256=jLrugYTSdK6Cw4SmJxsxdYdJ1S3X7wDcBC7kQAWe75A,31024
+kfinance/tests/test_models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kfinance/tests/test_models/test_capitalization_models.py,sha256=E-5eZX0ufdFsmcWATt5agyH4Ks-q8TNO-W6cnYIMOcE,3116
+kfinance/tests/test_models/test_price_models.py,sha256=DHBMAFJ8axat1s_C0tElqcCjw6YhmzF9WWKpKmySwv0,2378
+kfinance/tool_calling/README.md,sha256=omJq7Us6r4U45QB7hRpLjRJ5BMalCkZkh4uXBjTbJXc,2022
+kfinance/tool_calling/__init__.py,sha256=UmtbtG6PvQHB1fInEL-K5q0kPHL__zTY9wzaPRSp1wg,2174
+kfinance/tool_calling/get_advisors_for_company_in_transaction_from_identifier.py,sha256=kL8cnTIsnPBAZcTriKJKL2uFfFFNUuV0PMKVitD2MXQ,1630
+kfinance/tool_calling/get_business_relationship_from_identifier.py,sha256=oPlVpDy4AY8nQFZnHRp9DhpL8SecIlyEY6aiklHtVDg,1551
+kfinance/tool_calling/get_capitalization_from_identifier.py,sha256=qciQI9gSJh4gGatnjOkid-GJSlzXkvt7-2VcK2yBfrg,1558
+kfinance/tool_calling/get_competitors_from_identifier.py,sha256=J9TVWNU_6d6ltJLIJTdCtkhbc0MqoCbqdWUxrwBkOUs,1156
+kfinance/tool_calling/get_cusip_from_ticker.py,sha256=ebzFmjZFkcuydntQXmuxfh8mhPiXmmzUTb2ncHy00ao,667
+kfinance/tool_calling/get_earnings.py,sha256=d7UvVsSAcrVlveWyUpua35vdloA_QgJnQ4Nmg7wT7m0,1245
+kfinance/tool_calling/get_financial_line_item_from_identifier.py,sha256=hsKmObT2TJ4HMusVtQXU6FMDmyY7bKg2V-x-IXuU71c,2270
+kfinance/tool_calling/get_financial_statement_from_identifier.py,sha256=ba8Z378YrQ_J0-A6KVLOtxe-hYMP68780g0xXZfAyT8,2023
+kfinance/tool_calling/get_history_metadata_from_identifier.py,sha256=hPC-RwwcnJ9kkhxTUJLE-xvCqfIq5kJcKM4deiL8zlI,789
+kfinance/tool_calling/get_info_from_identifier.py,sha256=2-NmGvFpYXASGV_lJaYhhdXMxQpyvi30bXY9mGWwbBw,787
+kfinance/tool_calling/get_isin_from_ticker.py,sha256=tp79lowBUdkv7fm-8QX4vJqeDZiq5M_jkkp8XKC1KY4,661
+kfinance/tool_calling/get_latest.py,sha256=m6nBA8Bo51Q85kGbGnP59IUz4-lm_CRo1kSuNM26iXg,857
+kfinance/tool_calling/get_latest_earnings.py,sha256=R98ImaONP3AjVshygkRLwcAHKscvVRkVoPw117O9nuw,1197
+kfinance/tool_calling/get_merger_info_from_transaction_id.py,sha256=zzAg79hbUmwcdg-hJ2wGjcTQ_YHWXw85eOt48lmlZLs,3165
+kfinance/tool_calling/get_mergers_from_identifier.py,sha256=2w8bA-FQMdbmleuoWTbMPHK1K4IRxwHciZQPeQGGIVw,1725
+kfinance/tool_calling/get_n_quarters_ago.py,sha256=VYUBbQIowHXmNuln1oKoDKeWDbnXLg4p6X0d1HoY_NY,784
+kfinance/tool_calling/get_next_earnings.py,sha256=vL3sCoocPhHDRawVRu9IyQPLXVAgODrZgKSqkP3Scs8,1177
+kfinance/tool_calling/get_prices_from_identifier.py,sha256=uXD9fiLFI0vUM_YY8DI_9ifC0oeeC3KCyaTQQ0IjuSA,1966
+kfinance/tool_calling/get_segments_from_identifier.py,sha256=1Ux9ZWEU3xmOSuAPGedo2r8wdRa_glv8roghp08MJ-c,1980
+kfinance/tool_calling/get_transcript.py,sha256=urZgpQXigmahy-vj6OjkGI9O6HJcPIpd-5CRU7NI3YQ,782
+kfinance/tool_calling/prompts.py,sha256=Yw1DJIMh90cjL-8q6_RMRiSjCtFDXvJAy7QiV5_uAU8,911
+kfinance/tool_calling/resolve_identifier.py,sha256=Rkhwi6m3hffE19qaxRkrsu6slRKyiAXjfLr8L41N2zc,647
+kfinance/tool_calling/shared_models.py,sha256=Sx_zlwk5YLu533406Pmh499NH5oTBWrZf8Ua8zoUSRk,3746
+kensho_kfinance-2.8.0.dist-info/METADATA,sha256=XiOVL58W7LuXqyo76ASS9XESdvFUCHVYHXigOl11YTY,6197
+kensho_kfinance-2.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kensho_kfinance-2.8.0.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-2.8.0.dist-info/RECORD,,

kfinance/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v2.8.0
+- Add currency to get_capitalization and get_prices tools.
+
 ## v2.7.0
  - Expose a new list of LLM tools `grounding_tools` that return a list of all endpoint urls called
 

kfinance/decimal_with_unit.py

@@ -0,0 +1,78 @@
+from copy import deepcopy
+from decimal import Decimal
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+from typing_extensions import Self
+
+from kfinance.models.currency_models import ISO_CODE_TO_CURRENCY
+
+
+class DecimalWithUnit(BaseModel):
+    """DecimalWithUnit (DWU) represents a decimal with a corresponding unit like $100 or 20 shares.
+
+    In addition to a value and unit, each DWU has a `conventional_decimals` attribute,
+    which indicates the number of decimals that should be represented.
+    For example, for USD, conventional_decimals is 2, which will display as "1.00".
+    For shares, conventional_decimals is 0, which will display as "1"
+
+    Usually, rather than initializing a DWU directly, you'll likely want to use an
+    existing subclass like `Money` or `Shares` or create a new one.
+    """
+
+    value: Decimal
+    unit: str
+    # exclude conventional_decimals from serialization
+    conventional_decimals: int = Field(exclude=True)
+
+    @model_validator(mode="after")
+    def quantize_value(self) -> Self:
+        """Quantize the value at the end of the deserialization.
+
+        The value gets adjusted so that it always has the expected number of decimals defined in
+        conventional_decimals.
+        For USD with conventional_decimals=2, it will show values like "1.00"
+        For Shares with conventional_decimals=0, it will show values like "1"
+        """
+        exponent = Decimal("10") ** Decimal(-self.conventional_decimals)
+        self.value = self.value.quantize(exp=exponent)
+        return self
+
+
+class Money(DecimalWithUnit):
+    @model_validator(mode="before")
+    @classmethod
+    def inject_conventional_decimals_into_data(cls, data: Any) -> Any:
+        """Inject conventional_decimals into data dict.
+
+        Each currency has an associated conventional_decimals defined in the
+        CURRENCIES list. This validator fetches that number and injects it into the
+        data dict.
+        """
+
+        if isinstance(data, dict) and "conventional_decimals" not in data:
+            data = deepcopy(data)
+            currency = ISO_CODE_TO_CURRENCY[data["unit"]]
+            data["conventional_decimals"] = currency.conventional_decimals
+
+        return data
+
+
+class Shares(DecimalWithUnit):
+    unit: str = "Shares"
+    conventional_decimals: int = Field(exclude=True, default=0)
+
+    @model_validator(mode="before")
+    @classmethod
+    def convert_numbers_to_dicts(cls, data: Any) -> Any:
+        """Convert numbers into dicts.
+
+        The shares class can be built from a single number because unit and
+        conventional_decimals are always the same. However, the parser expects a
+        dict instead of a number, so we have to convert any number ("10") into a
+        dict {"value": "10"}.
+        """
+
+        if isinstance(data, (str, int, float, Decimal)):
+            data = {"value": data}
+        return data

kfinance/fetch.py

@@ -10,23 +10,22 @@ import jwt
 from pydantic import ValidationError
 import requests
 
-from .constants import (
-    BusinessRelationshipType,
-    CompetitorSource,
-    IdentificationTriple,
-    IndustryClassification,
-    Periodicity,
-    PeriodType,
-    Permission,
-    SegmentType,
-)
-from .pydantic_models import RelationshipResponse, RelationshipResponseNoName
+from kfinance.models.business_relationship_models import BusinessRelationshipType
+from kfinance.models.capitalization_models import Capitalizations
+from kfinance.models.competitor_models import CompetitorSource
+from kfinance.models.date_and_period_models import Periodicity, PeriodType
+from kfinance.models.id_models import IdentificationTriple
+from kfinance.models.industry_models import IndustryClassification
+from kfinance.models.permission_models import Permission
+from kfinance.models.price_models import PriceHistory
+from kfinance.models.segment_models import SegmentType
+from kfinance.pydantic_models import RelationshipResponse, RelationshipResponseNoName
 
 
 # version.py gets autogenerated by setuptools-scm and is not available
 # during local development.
 try:
-    from .version import __version__ as kfinance_version
+    from kfinance.version import __version__ as kfinance_version
 except ImportError:
     kfinance_version = "dev"
 
@@ -300,7 +299,7 @@ class KFinanceApiClient:
         start_date: Optional[str] = None,
         end_date: Optional[str] = None,
         periodicity: Optional[Periodicity] = None,
-    ) -> dict:
+    ) -> PriceHistory:
         """Get the pricing history."""
         url = (
             f"{self.url_base}pricing/{trading_item_id}/"
@@ -309,7 +308,7 @@ class KFinanceApiClient:
             f"{periodicity if periodicity else 'none'}/"
             f"{'adjusted' if is_adjusted else 'unadjusted'}"
         )
-        return self.fetch(url)
+        return PriceHistory.model_validate(self.fetch(url))
 
     def fetch_history_metadata(self, trading_item_id: int) -> dict[str, str]:
         """Get the pricing history metadata."""
@@ -321,14 +320,14 @@ class KFinanceApiClient:
         company_id: int,
         start_date: Optional[str] = None,
         end_date: Optional[str] = None,
-    ) -> dict:
+    ) -> Capitalizations:
         """Get the market cap, TEV, and shares outstanding for a company."""
         url = (
             f"{self.url_base}market_cap/{company_id}/"
             f"{start_date if start_date is not None else 'none'}/"
             f"{end_date if end_date is not None else 'none'}"
         )
-        return self.fetch(url)
+        return Capitalizations.model_validate(self.fetch(url))
 
     def fetch_segments(
         self,

kfinance/kfinance.py

@@ -15,33 +15,28 @@ import webbrowser
 import google.ai.generativelanguage_v1beta.types as gapic
 from langchain_core.utils.function_calling import convert_to_openai_tool
 from langchain_google_genai._function_utils import convert_to_genai_function_declarations
-import numpy as np
 import pandas as pd
 from PIL.Image import Image, open as image_open
 
-from .batch_request_handling import add_methods_of_singular_class_to_iterable_class
-from .constants import (
-    HistoryMetadata,
-    IdentificationTriple,
-    IndustryClassification,
-    LatestPeriods,
-    Periodicity,
-    YearAndQuarter,
-)
-from .fetch import (
+from kfinance.batch_request_handling import add_methods_of_singular_class_to_iterable_class
+from kfinance.fetch import (
     DEFAULT_API_HOST,
     DEFAULT_API_VERSION,
     DEFAULT_OKTA_AUTH_SERVER,
     DEFAULT_OKTA_HOST,
     KFinanceApiClient,
 )
-from .meta_classes import (
+from kfinance.meta_classes import (
     CompanyFunctionsMetaClass,
     DelegatedCompanyFunctionsMetaClass,
 )
-from .prompt import PROMPT
-from .pydantic_models import TranscriptComponent
-from .server_thread import ServerThread
+from kfinance.models.date_and_period_models import LatestPeriods, Periodicity, YearAndQuarter
+from kfinance.models.id_models import IdentificationTriple
+from kfinance.models.industry_models import IndustryClassification
+from kfinance.models.price_models import HistoryMetadata, PriceHistory
+from kfinance.prompt import PROMPT
+from kfinance.pydantic_models import TranscriptComponent
+from kfinance.server_thread import ServerThread
 
 
 if TYPE_CHECKING:
@@ -140,36 +135,29 @@ class TradingItem:
         adjusted: bool = True,
         start_date: Optional[str] = None,
         end_date: Optional[str] = None,
-    ) -> pd.DataFrame:
+    ) -> PriceHistory:
         """Retrieves the historical price data for a given asset over a specified date range.
 
         :param periodicity: Determines the frequency of the historical data returned. Defaults to Periodicity.day.
         :param Optional[bool] adjusted: Whether to retrieve adjusted prices that account for corporate actions such as dividends and splits, it defaults True
         :param Optional[str] start_date: The start date for historical price retrieval in format "YYYY-MM-DD", default to None
         :param Optional[str] end_date: The end date for historical price retrieval in format "YYYY-MM-DD", default to None
-        :return: A pd.DataFrame containing historical price data with columns corresponding to the specified periodicity, with Date as the index, and columns "open", "high", "low", "close", "volume" in type decimal. The Date index is a string that depends on the periodicity. If Periodicity.day, the Date index is the day in format "YYYY-MM-DD", eg "2024-05-13" If Periodicity.week, the Date index is the week number of the year in format "YYYY Week ##", eg "2024 Week 2" If Periodicity.month, the Date index is the month name of the year in format "<Month> YYYY", eg "January 2024". If Periodicity.year, the Date index is the year in format "YYYY", eg "2024".
-        :rtype: pd.DataFrame
+        :return: A PriceHistory containing historical price data including "open", "high", "low", "close", "volume" in type Money. The date value is a string that depends on the periodicity. If Periodicity.day, the Date index is the day in format "YYYY-MM-DD", eg "2024-05-13" If Periodicity.week, the Date index is the week number of the year in format "YYYY Week ##", eg "2024 Week 2" If Periodicity.month, the Date index is the month name of the year in format "<Month> YYYY", eg "January 2024". If Periodicity.year, the Date index is the year in format "YYYY", eg "2024".
+        :rtype: PriceHistory
         """
         if start_date and end_date:
             if (
                 datetime.strptime(start_date, "%Y-%m-%d").date()
                 > datetime.strptime(end_date, "%Y-%m-%d").date()
             ):
-                return pd.DataFrame()
+                return PriceHistory(prices=[])
 
-        return (
-            pd.DataFrame(
-                self.kfinance_api_client.fetch_history(
-                    trading_item_id=self.trading_item_id,
-                    is_adjusted=adjusted,
-                    start_date=start_date,
-                    end_date=end_date,
-                    periodicity=periodicity,
-                )["prices"]
-            )
-            .set_index("date")
-            .apply(pd.to_numeric)
-            .replace(np.nan, None)
+        return self.kfinance_api_client.fetch_history(
+            trading_item_id=self.trading_item_id,
+            is_adjusted=adjusted,
+            start_date=start_date,
+            end_date=end_date,
+            periodicity=periodicity,
         )
 
     def price_chart(
@@ -815,7 +803,11 @@ class Security:
                 "trading_items"
             ]
             self._trading_items = TradingItems(
-                kfinance_api_client=self.kfinance_api_client, trading_item_ids=trading_item_ids
+                kfinance_api_client=self.kfinance_api_client,
+                trading_items=[
+                    TradingItem(kfinance_api_client=self.kfinance_api_client, trading_item_id=tii)
+                    for tii in trading_item_ids
+                ],
             )
         return self._trading_items
 
@@ -1194,7 +1186,7 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         adjusted: bool = True,
         start_date: Optional[str] = None,
         end_date: Optional[str] = None,
-    ) -> pd.DataFrame:
+    ) -> PriceHistory:
         """Retrieves the historical price data for a given asset over a specified date range.
 
         :param periodicity: Determines the frequency of the historical data returned. Defaults to Periodicity.day.
@@ -1205,8 +1197,8 @@ class Ticker(DelegatedCompanyFunctionsMetaClass):
         :type start_date: str, optional
         :param end_date: The end date for historical price retrieval in format "YYYY-MM-DD", default to None
         :type end_date: str, optional
-        :return: A pd.DataFrame containing historical price data with columns corresponding to the specified periodicity, with Date as the index, and columns "open", "high", "low", "close", "volume" in type decimal. The Date index is a string that depends on the periodicity. If Periodicity.day, the Date index is the day in format "YYYY-MM-DD", eg "2024-05-13" If Periodicity.week, the Date index is the week number of the year in format "YYYY Week ##", eg "2024 Week 2" If Periodicity.month, the Date index is the month name of the year in format "<Month> YYYY", eg "January 2024". If Periodicity.year, the Date index is the year in format "YYYY", eg "2024".
-        :rtype: pd.DataFrame
+        :return: A PriceHistory containing historical price data including "open", "high", "low", "close", "volume" in type Money. The date value is a string that depends on the periodicity. If Periodicity.day, the Date index is the day in format "YYYY-MM-DD", eg "2024-05-13" If Periodicity.week, the Date index is the week number of the year in format "YYYY Week ##", eg "2024 Week 2" If Periodicity.month, the Date index is the month name of the year in format "<Month> YYYY", eg "January 2024". If Periodicity.year, the Date index is the year in format "YYYY", eg "2024".
+        :rtype: PriceHistory
         """
         return self.primary_trading_item.history(
             periodicity,
@@ -1425,20 +1417,17 @@ class TradingItems(set):
     """Base class for representing a set of Trading Items"""
 
     def __init__(
-        self, kfinance_api_client: KFinanceApiClient, trading_item_ids: Iterable[int]
+        self, kfinance_api_client: KFinanceApiClient, trading_items: Iterable[TradingItem]
     ) -> None:
         """Initialize the Trading Items
 
         :param kfinance_api_client: The KFinanceApiClient used to fetch data
         :type kfinance_api_client: KFinanceApiClient
-        :param company_ids: An iterable of S&P CIQ Company ids
-        :type company_ids: Iterable[int]
+        :param trading_items: An iterable of TradingItem
+        :type trading_items: Iterable[TradingItem]
         """
         self.kfinance_api_client = kfinance_api_client
-        super().__init__(
-            TradingItem(kfinance_api_client, trading_item_id)
-            for trading_item_id in trading_item_ids
-        )
+        super().__init__(trading_items)
 
 
 @add_methods_of_singular_class_to_iterable_class(Ticker)
@@ -1515,7 +1504,14 @@ class Tickers(set):
         :rtype: TradingItems
         """
         return TradingItems(
-            self.kfinance_api_client, (ticker.trading_item_id for ticker in self.__iter__())
+            self.kfinance_api_client,
+            [
+                TradingItem(
+                    kfinance_api_client=self.kfinance_api_client,
+                    trading_item_id=ticker.trading_item_id,
+                )
+                for ticker in self.__iter__()
+            ],
         )
 
 

kfinance/meta_classes.py

@@ -1,20 +1,19 @@
 from abc import abstractmethod
 from datetime import datetime
 import logging
-from typing import TYPE_CHECKING, Any, Callable, Literal, Optional
+from typing import TYPE_CHECKING, Any, Callable, Optional
 
 from cachetools import LRUCache, cached
 import numpy as np
 import pandas as pd
 
-from .constants import (
-    LINE_ITEMS,
-    BusinessRelationshipType,
-    CompetitorSource,
-    PeriodType,
-    SegmentType,
-)
 from .fetch import KFinanceApiClient
+from .models.business_relationship_models import BusinessRelationshipType
+from .models.capitalization_models import Capitalization
+from .models.competitor_models import CompetitorSource
+from .models.date_and_period_models import PeriodType
+from .models.line_item_models import LINE_ITEMS
+from .models.segment_models import SegmentType
 from .pydantic_models import RelationshipResponse
 
 
@@ -262,73 +261,75 @@ class CompanyFunctionsMetaClass:
         self,
         start_date: Optional[str] = None,
         end_date: Optional[str] = None,
-    ) -> pd.DataFrame:
+    ) -> dict:
         """Retrieves market caps for a company between start and end date.
 
         :param start_date: The start date in format "YYYY-MM-DD", default to None
         :type start_date: str, optional
         :param end_date: The end date in format "YYYY-MM-DD", default to None
         :type end_date: str, optional
-        :return: A DataFrame with a `market_cap` column. The dates are the index.
-        :rtype: pd.DataFrame
+        :return: A dict with market_cap
+        :rtype: dict
         """
 
         return self._fetch_market_cap_tev_or_shares_outstanding(
-            column_to_extract="market_cap", start_date=start_date, end_date=end_date
+            capitalization_to_extract=Capitalization.market_cap,
+            start_date=start_date,
+            end_date=end_date,
         )
 
     def tev(
         self,
         start_date: Optional[str] = None,
         end_date: Optional[str] = None,
-    ) -> pd.DataFrame:
+    ) -> dict:
         """Retrieves TEV (total enterprise value) for a company between start and end date.
 
         :param start_date: The start date in format "YYYY-MM-DD", default to None
         :type start_date: str, optional
         :param end_date: The end date in format "YYYY-MM-DD", default to None
         :type end_date: str, optional
-        :return: A DataFrame with a `tev` column. The dates are the index.
-        :rtype: pd.DataFrame
+        :return: A dict with TEV
+        :rtype: dict
         """
 
         return self._fetch_market_cap_tev_or_shares_outstanding(
-            column_to_extract="tev", start_date=start_date, end_date=end_date
+            capitalization_to_extract=Capitalization.tev, start_date=start_date, end_date=end_date
         )
 
     def shares_outstanding(
         self,
         start_date: Optional[str] = None,
         end_date: Optional[str] = None,
-    ) -> pd.DataFrame:
+    ) -> dict:
         """Retrieves shares outstanding for a company between start and end date.
 
         :param start_date: The start date in format "YYYY-MM-DD", default to None
         :type start_date: str, optional
         :param end_date: The end date in format "YYYY-MM-DD", default to None
         :type end_date: str, optional
-        :return: A DataFrame with a `shares_outstanding` column. The dates are the index.
-        :rtype: pd.DataFrame
+        :return: A dict with outstanding shares
+        :rtype: dict
         """
 
         return self._fetch_market_cap_tev_or_shares_outstanding(
-            column_to_extract="shares_outstanding", start_date=start_date, end_date=end_date
+            capitalization_to_extract=Capitalization.shares_outstanding,
+            start_date=start_date,
+            end_date=end_date,
         )
 
     def _fetch_market_cap_tev_or_shares_outstanding(
         self,
-        column_to_extract: Literal["market_cap", "tev", "shares_outstanding"],
+        capitalization_to_extract: Capitalization,
         start_date: str | None,
         end_date: str | None,
-    ) -> pd.DataFrame:
+    ) -> dict:
         """Helper function to fetch market cap, TEV, and shares outstanding."""
 
-        df = pd.DataFrame(
-            self.kfinance_api_client.fetch_market_caps_tevs_and_shares_outstanding(
-                company_id=self.company_id, start_date=start_date, end_date=end_date
-            )["market_caps"]
+        capitalizations = self.kfinance_api_client.fetch_market_caps_tevs_and_shares_outstanding(
+            company_id=self.company_id, start_date=start_date, end_date=end_date
         )
-        return df.set_index("date")[[column_to_extract]].apply(pd.to_numeric).replace(np.nan, None)
+        return capitalizations.jsonify_single_attribute(capitalization_to_extract)
 
     def _segments(
         self,

kfinance/models/business_relationship_models.py

@@ -0,0 +1,26 @@
+from strenum import StrEnum
+
+
+class BusinessRelationshipType(StrEnum):
+    """The type of business relationship"""
+
+    supplier = "supplier"
+    customer = "customer"
+    distributor = "distributor"
+    franchisor = "franchisor"
+    franchisee = "franchisee"
+    landlord = "landlord"
+    tenant = "tenant"
+    licensor = "licensor"
+    licensee = "licensee"
+    creditor = "creditor"
+    borrower = "borrower"
+    lessor = "lessor"
+    lessee = "lessee"
+    strategic_alliance = "strategic_alliance"
+    investor_relations_firm = "investor_relations_firm"
+    investor_relations_client = "investor_relations_client"
+    transfer_agent = "transfer_agent"
+    transfer_agent_client = "transfer_agent_client"
+    vendor = "vendor"
+    client_services = "client_services"

kfinance/models/capitalization_models.py

@@ -0,0 +1,90 @@
+from copy import deepcopy
+from datetime import date
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+from strenum import StrEnum
+
+from kfinance.decimal_with_unit import Money, Shares
+
+
+class Capitalization(StrEnum):
+    """The capitalization type"""
+
+    market_cap = "market_cap"
+    tev = "tev"
+    shares_outstanding = "shares_outstanding"
+
+
+class DailyCapitalization(BaseModel):
+    """DailyCapitalization represents market cap, TEV, and shares outstanding for a day"""
+
+    date: date
+    market_cap: Money
+    tev: Money
+    shares_outstanding: Shares
+
+
+class Capitalizations(BaseModel):
+    """Capitalizations represents market cap, TEV, and shares outstanding for a date range"""
+
+    capitalizations: list[DailyCapitalization] = Field(validation_alias="market_caps")
+
+    @model_validator(mode="before")
+    @classmethod
+    def inject_currency_into_data(cls, data: Any) -> Any:
+        """Inject the currency into each market_cap and TEV.
+
+        The capitalization response only includes the currency as a top level element.
+        However, the capitalizations model expects the unit to be included with each market cap
+        and tev.
+        Before:
+            "market_caps": [
+                {
+                    "date": "2024-06-24",
+                    "market_cap": "139231113000.000000",
+                    "tev": "153942113000.000000",
+                    "shares_outstanding": 312900000
+                },
+            ]
+        After:
+            "market_caps": [
+                {
+                    "date": "2024-06-24",
+                    "market_cap": {"value": "139231113000.000000", "unit": "USD"},
+                    "tev": {"value": "153942113000.000000", "unit": "USD"},
+                    "shares_outstanding": 312900000
+                },
+
+        Note: shares_outstanding does not need the unit injected because the Shares class
+            already has "Shares" encoded. However, currencies differ between companies,
+            so we need to inject that information.
+        """
+        if isinstance(data, dict) and "currency" in data:
+            data = deepcopy(data)
+            currency = data["currency"]
+            for capitalization in data["market_caps"]:
+                for key in ["market_cap", "tev"]:
+                    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".
+
+        Example response:
+        {
+            "market_cap": [
+                {'2024-06-24': {'unit': 'USD', 'value': '139231113000.00'}},
+                {'2024-06-25': {'unit': 'USD', 'value': '140423262000.00'}}
+            ]
+        }
+
+        """
+
+        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}

kfinance/models/competitor_models.py

@@ -0,0 +1,13 @@
+from strenum import StrEnum
+
+
+class CompetitorSource(StrEnum):
+    """The source type of the competitor information: 'filing' (from SEC filings), 'key_dev' (from key developments), 'contact' (from contact relationships), 'third_party' (from third-party sources), 'self_identified' (self-identified), 'named_by_competitor' (from competitor's perspective)."""
+
+    all = "all"
+    filing = "filing"
+    key_dev = "key_dev"
+    contact = "contact"
+    third_party = "third_party"
+    self_identified = "self_identified"
+    named_by_competitor = "named_by_competitor"