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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.2.4
+Version: 2.3.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
@@ -14,7 +14,7 @@ License-File: LICENSE
 License-File: AUTHORS.md
 Requires-Dist: cachetools<6,>=5.5
 Requires-Dist: langchain-core>=0.3.15
-Requires-Dist: langchain-google-genai<3,>=2.1.0
+Requires-Dist: langchain-google-genai<3,>=2.1.5
 Requires-Dist: numpy>=1.22.4
 Requires-Dist: pandas>=2.0.0
 Requires-Dist: pillow>=10
@@ -29,7 +29,8 @@ Requires-Dist: urllib3>=1.21.1
 Provides-Extra: dev
 Requires-Dist: coverage<8,>=7.6.10; extra == "dev"
 Requires-Dist: ipykernel<7,>=6.29; extra == "dev"
-Requires-Dist: mypy<2,>=1.15.0; extra == "dev"
+Requires-Dist: langchain-anthropic<1,>=0.3.10; extra == "dev"
+Requires-Dist: mypy<2,>=1.16.0; extra == "dev"
 Requires-Dist: nbconvert<8,>=7.16; extra == "dev"
 Requires-Dist: nbformat<6,>5.10; extra == "dev"
 Requires-Dist: nbqa<2,>1.9; extra == "dev"
@@ -61,7 +62,16 @@ To receive access, please email [S&P Global Market Intelligence](market.intellig
 
 Once access is obtained, get started using the [Authentication Guide](https://docs.kensho.com/llmreadyapi/kf-authentication) and [Usage Guide](https://docs.kensho.com/llmreadyapi/usage).
 
-We also provide an [interactive notebook](usage_examples.ipynb) that demonstrates some usage examples.
+To get started, we provide some notebooks:
+
+- The [LLM-ready API Basic Usage](example_notebooks%2Fbasic_usage.ipynb) notebook demonstrates how 
+fetch data with the kFinance client.
+- The [tool_calling notebooks](example_notebooks%2Ftool_calling) show how the kFinance library can
+be used for tool calling. We provide notebooks for OpenAI (GPT), Anthropic (Claude), and Google
+  (Gemini). Each of these integrations comes in a langchain version, which uses langchain as a
+wrapper to simplify the integration, and as a lower level non-langchain version.
+
+We also provide an [interactive notebook](example_notebooks/basic_usage.ipynb) that demonstrates some usage examples.
 
 # Versioning
 The kFinance uses semantic versioning (major, minor, patch). 

{kensho_kfinance-2.2.4.dist-info → kensho_kfinance-2.3.0.dist-info}/RECORD

@@ -1,30 +1,32 @@
-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
+kensho_kfinance-2.3.0.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-2.3.0.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=vIFnA_ArXUrV64T76m3KVMX0wGeVMsEi_u4BmQ3os7Y,1418
 kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/batch_request_handling.py,sha256=p6p_G4_BL06GgeKlh7P1k9CUqOMahWCLEw1NoBwbLvU,5698
 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=1qYkj2L7jcBfdkye6TG2nuRhwzhAbmtxay6rSVY3DsA,19883
+kfinance/fetch.py,sha256=yaCih8PAkOhVHb3tvmBW0x2w4QmXJiyUATu6Yx-xzP4,23851
+kfinance/kfinance.py,sha256=9lcarUW4fLHJA_U7_1ihCMbNJWs0AztvKf_XEd0qupk,59889
+kfinance/meta_classes.py,sha256=3V0nSXDDoake5o7kXnrqXuqNIiwI75KR4IYxFqSPhTE,20736
 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=Ath1yNFbHtPzluPba0J7EfQTfLH_byRzLfGjqAUl6cY,511
+kfinance/version.py,sha256=U--yqU7RFo8hQQm8oopUGYLkafj4phNIVfkf5HFEal8,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
 kfinance/tests/test_client.py,sha256=O7icZCSDhlQ9WGhzoXlpiSvbuA-mQNJHBYVsilyP_dE,2209
-kfinance/tests/test_example_notebook.py,sha256=XhDAJp3H5Y6usLAt3k4Ug4W3H6gLyh68nzmoWgOOLn4,6441
-kfinance/tests/test_fetch.py,sha256=O9qOsffQYJPSAR1X_P6CNoA0Buyq2kx4vfS0FOc2Goc,13564
+kfinance/tests/test_example_notebook.py,sha256=XHwDKw2avyMonTmi3snCcFWNfZhEJOkpBGOZNrMLrhk,6470
+kfinance/tests/test_fetch.py,sha256=nfnz_ZxE-W3KMzpDaRClX55fQJrRjwLTha-rHTallmE,16713
 kfinance/tests/test_group_objects.py,sha256=SoMEZmkG4RYdgWOAwxLHHtzIQho92KM01YbQXPUg578,1689
-kfinance/tests/test_objects.py,sha256=CSk3iN-uDt-E6gaOX4jExuYPT8Up-YNC3hafpenadcA,23614
-kfinance/tests/test_tools.py,sha256=ne4XhebhoxDHFl4kRLl10j4K-SXLrxS6jv6Ypt0Gv_E,16846
+kfinance/tests/test_objects.py,sha256=0nDmCFrVcfI8VBo1Ph3YqXNo3uPLsSUiQkjEEHsax1M,30416
+kfinance/tests/test_tools.py,sha256=EWWWyPlGGES8Cn43_VaDAT7Vdp1nlIETE5dtOrP163o,24447
 kfinance/tool_calling/README.md,sha256=omJq7Us6r4U45QB7hRpLjRJ5BMalCkZkh4uXBjTbJXc,2022
-kfinance/tool_calling/__init__.py,sha256=Fb30Snu09B63NscSUJGGnFAdlXSDrTAOJlzjYvMyZXk,1873
+kfinance/tool_calling/__init__.py,sha256=V5BVcJkLT1zC0QKZIQjLb-cZiQYV4T9Egj64uH807WE,2215
 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
+kfinance/tool_calling/get_earnings.py,sha256=7xavYvqwq4fO0vpks25eDM87bCYwZxEQSwgT0I8jAok,1165
 kfinance/tool_calling/get_earnings_call_datetimes_from_identifier.py,sha256=Zp7gHP-z2ePu484wWx4xw89hl0z7NLcG3qliJT-6rUo,782
 kfinance/tool_calling/get_financial_line_item_from_identifier.py,sha256=bMK-GUMz_wmJ-7iFS72sM8AvvUvR83JYRWzYtr9Fofw,2153
 kfinance/tool_calling/get_financial_statement_from_identifier.py,sha256=9ouzC43skA78uI3dh3bvtM86db5RGxuWQAAJ24y-kBM,1906
@@ -32,12 +34,16 @@ kfinance/tool_calling/get_history_metadata_from_identifier.py,sha256=kKIInfRC1Pl
 kfinance/tool_calling/get_info_from_identifier.py,sha256=PRhSYpYs_iUcIVFGYCMN_7QJyhewua7c7pqngPIp-qg,766
 kfinance/tool_calling/get_isin_from_ticker.py,sha256=2fJBcA-rNGbVOQmQ7qJEYxqejQwJ6nyWOBSFlzxG7dY,638
 kfinance/tool_calling/get_latest.py,sha256=btGeVBmvX5QJutzrKfE6spatGGejDuHxtq53NoAaGNk,786
+kfinance/tool_calling/get_latest_earnings.py,sha256=pQdExGdztGY3pHcak0bd6ULNf_ROPc91bJ7zAVSKQkk,1117
 kfinance/tool_calling/get_n_quarters_ago.py,sha256=A0ilwPKUqU0YYQSz3gNsVF0Jy4YttXrSaDhYj7y8GHA,713
+kfinance/tool_calling/get_next_earnings.py,sha256=knzQw-m-hscCvTuDUXG9v_dObKJBGn5BbDZWGKHKQcw,1097
 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/get_transcript.py,sha256=eB-IsRwD-mllsMOYRZbH35caQ1Y3teKft0tmI9nVL-A,756
+kfinance/tool_calling/prompts.py,sha256=Yw1DJIMh90cjL-8q6_RMRiSjCtFDXvJAy7QiV5_uAU8,911
 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.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.3.0.dist-info/METADATA,sha256=3rNOXczOABUGLavlhJUmseCJ0pOL6x00uckfLkJcSkI,4066
+kensho_kfinance-2.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kensho_kfinance-2.3.0.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-2.3.0.dist-info/RECORD,,

kfinance/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v2.3.1
+- Add llm tools for retrieving earnings and transcripts
+
+## v2.3.0
+- Add earnings and transcript objects
+
+## v2.2.5
+- Add parsing for relationship response with name
+
 ## v2.2.4
 - Add segments as llm tools
 

kfinance/fetch.py

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

kfinance/kfinance.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
+from collections.abc import Sequence
 from concurrent.futures import ThreadPoolExecutor
+from copy import deepcopy
 from datetime import date, datetime, timezone
 from functools import cached_property
 from io import BytesIO
 import logging
 import re
 from sys import stdout
-from typing import TYPE_CHECKING, Any, Callable, Iterable, NamedTuple, Optional
+from typing import TYPE_CHECKING, Any, Callable, Iterable, NamedTuple, Optional, overload
 from urllib.parse import urljoin
 import webbrowser
 
@@ -39,6 +41,7 @@ from .meta_classes import (
     DelegatedCompanyFunctionsMetaClass,
 )
 from .prompt import PROMPT
+from .pydantic_models import TranscriptComponent
 from .server_thread import ServerThread
 
 
@@ -48,6 +51,12 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+class NoEarningsDataError(Exception):
+    """Exception raised when no earnings data is found for a company."""
+
+    pass
+
+
 class TradingItem:
     """Trading Class
 
@@ -199,6 +208,96 @@ class TradingItem:
         return image
 
 
+class Transcript(Sequence[TranscriptComponent]):
+    """Transcript class that represents earnings item transcript components"""
+
+    def __init__(self, transcript_components: list[dict[str, str]]):
+        """Initialize the Transcript object
+
+        :param transcript_components: List of transcript component dictionaries
+        :type transcript_components: list[dict[str, str]]
+        """
+        self._components = [TranscriptComponent(**component) for component in transcript_components]
+        self._raw_transcript: str | None = None
+
+    @overload
+    def __getitem__(self, index: int) -> TranscriptComponent: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[TranscriptComponent]: ...
+
+    def __getitem__(self, index: int | slice) -> TranscriptComponent | list[TranscriptComponent]:
+        return self._components[index]
+
+    def __len__(self) -> int:
+        return len(self._components)
+
+    @property
+    def raw(self) -> str:
+        """Get the raw transcript as a single string
+
+        :return: Raw transcript text with speaker names and double newlines between components
+        :rtype: str
+        """
+        if self._raw_transcript is not None:
+            return self._raw_transcript
+
+        raw_components = []
+        for component in self._components:
+            speaker = component.person_name
+            text = component.text
+            raw_components.append(f"{speaker}: {text}")
+
+        self._raw_transcript = "\n\n".join(raw_components)
+        return self._raw_transcript
+
+
+class Earnings:
+    """Earnings class that represents an earnings item"""
+
+    def __init__(
+        self,
+        kfinance_api_client: "KFinanceApiClient",
+        name: str,
+        datetime: datetime,
+        key_dev_id: int,
+    ):
+        """Initialize the Earnings object
+
+        :param kfinance_api_client: The KFinanceApiClient used to fetch data
+        :type kfinance_api_client: KFinanceApiClient
+        :param name: The earnings name
+        :type name: str
+        :param datetime: The earnings datetime
+        :type datetime: datetime
+        :param key_dev_id: The key dev ID for the earnings
+        :type key_dev_id: int
+        """
+        self.kfinance_api_client = kfinance_api_client
+        self.name = name
+        self.datetime = datetime
+        self.key_dev_id = key_dev_id
+        self._transcript: Transcript | None = None
+
+    def __str__(self) -> str:
+        """String representation for the earnings object"""
+        return f"{type(self).__module__}.{type(self).__qualname__} of {self.key_dev_id}"
+
+    @property
+    def transcript(self) -> Transcript:
+        """Get the transcript for this earnings
+
+        :return: The transcript object containing all components
+        :rtype: Transcript
+        """
+        if self._transcript is not None:
+            return self._transcript
+
+        transcript_data = self.kfinance_api_client.fetch_transcript(self.key_dev_id)
+        self._transcript = Transcript(transcript_data["transcript"])
+        return self._transcript
+
+
 class Company(CompanyFunctionsMetaClass):
     """Company class
 
@@ -219,6 +318,7 @@ class Company(CompanyFunctionsMetaClass):
         super().__init__()
         self.kfinance_api_client = kfinance_api_client
         self.company_id = company_id
+        self._all_earnings: list[Earnings] | None = None
 
     def __str__(self) -> str:
         """String representation for the company object"""
@@ -248,16 +348,6 @@ class Company(CompanyFunctionsMetaClass):
         security_ids = self.kfinance_api_client.fetch_securities(self.company_id)["securities"]
         return Securities(kfinance_api_client=self.kfinance_api_client, security_ids=security_ids)
 
-    @cached_property
-    def latest_earnings_call(self) -> None:
-        """Set and return the latest earnings call item for the object
-
-        :raises NotImplementedError: This function is not yet implemented
-        """
-        raise NotImplementedError(
-            "The latest earnings call property of company class not implemented yet"
-        )
-
     @cached_property
     def info(self) -> dict:
         """Get the company info
@@ -398,6 +488,121 @@ class Company(CompanyFunctionsMetaClass):
             ]
         ]
 
+    @property
+    def all_earnings(self) -> list[Earnings]:
+        """Retrieve and cache all earnings items for this company"""
+        if self._all_earnings is not None:
+            return self._all_earnings
+
+        earnings_data = self.kfinance_api_client.fetch_earnings(self.company_id)
+        self._all_earnings = []
+
+        for earnings in earnings_data["earnings"]:
+            if "keydevid" in earnings:
+                earnings["key_dev_id"] = deepcopy(earnings["keydevid"])
+                del earnings["keydevid"]
+            earnings_datetime = datetime.fromisoformat(
+                earnings["datetime"].replace("Z", "+00:00")
+            ).replace(tzinfo=timezone.utc)
+
+            self._all_earnings.append(
+                Earnings(
+                    kfinance_api_client=self.kfinance_api_client,
+                    name=earnings["name"],
+                    datetime=earnings_datetime,
+                    key_dev_id=earnings["key_dev_id"],
+                )
+            )
+
+        return self._all_earnings
+
+    def earnings(
+        self, start_date: date | None = None, end_date: date | None = None
+    ) -> list[Earnings]:
+        """Get earnings for the company within date range sorted in descending order by date
+
+        :param start_date: Start date filter, defaults to None
+        :type start_date: date, optional
+        :param end_date: End date filter, defaults to None
+        :type end_date: date, optional
+        :return: List of earnings objects
+        :rtype: list[Earnings]
+        """
+        if not self.all_earnings:
+            return []
+
+        if start_date is not None:
+            start_date_utc = datetime.combine(start_date, datetime.min.time()).replace(
+                tzinfo=timezone.utc
+            )
+
+        else:
+            start_date_utc = None
+
+        if end_date is not None:
+            end_date_utc = datetime.combine(end_date, datetime.max.time()).replace(
+                tzinfo=timezone.utc
+            )
+
+        else:
+            end_date_utc = None
+
+        filtered_earnings = []
+
+        for earnings in self.all_earnings:
+            # Apply date filtering if provided
+            if start_date_utc is not None and earnings.datetime < start_date_utc:
+                continue
+
+            if end_date_utc is not None and earnings.datetime > end_date_utc:
+                continue
+
+            filtered_earnings.append(earnings)
+
+        return filtered_earnings
+
+    @property
+    def latest_earnings(self) -> Earnings | None:
+        """Get the most recent past earnings
+
+        :return: The most recent earnings or None if no data available
+        :rtype: Earnings | None
+        """
+        if not self.all_earnings:
+            return None
+
+        now = datetime.now(timezone.utc)
+        past_earnings = [
+            earnings_item for earnings_item in self.all_earnings if earnings_item.datetime <= now
+        ]
+
+        if not past_earnings:
+            return None
+
+        # Sort by datetime descending and get the most recent
+        return max(past_earnings, key=lambda x: x.datetime)
+
+    @property
+    def next_earnings(self) -> Earnings | None:
+        """Get the next upcoming earnings
+
+        :return: The next earnings or None if no data available
+        :rtype: Earnings | None
+        """
+        if not self.all_earnings:
+            return None
+
+        now = datetime.now(timezone.utc)
+        future_earnings = [
+            earnings_item for earnings_item in self.all_earnings if earnings_item.datetime > now
+        ]
+
+        if not future_earnings:
+            return None
+
+        # Sort by datetime ascending and get the earliest
+        return min(future_earnings, key=lambda x: x.datetime)
+
 
 class Security:
     """Security class
@@ -1345,6 +1550,17 @@ class Client:
             kfinance_api_client=self.kfinance_api_client, trading_item_id=trading_item_id
         )
 
+    def transcript(self, key_dev_id: int) -> Transcript:
+        """Generate Transcript object from key_dev_id
+
+        :param key_dev_id: The key dev ID for the earnings
+        :type key_dev_id: int
+        :return: The transcript specified by the key dev id
+        :rtype: Transcript
+        """
+        transcript_data = self.kfinance_api_client.fetch_transcript(key_dev_id)
+        return Transcript(transcript_data["transcript"])
+
     @staticmethod
     def get_latest(use_local_timezone: bool = True) -> LatestPeriods:
         """Get the latest annual reporting year, latest quarterly reporting quarter and year, and current date.

kfinance/meta_classes.py

@@ -9,12 +9,12 @@ import pandas as pd
 
 from .constants import LINE_ITEMS, BusinessRelationshipType, PeriodType, SegmentType
 from .fetch import KFinanceApiClient
+from .pydantic_models import RelationshipResponse
 
 
 if TYPE_CHECKING:
     from .kfinance import BusinessRelationships
 
-
 logger = logging.getLogger(__name__)
 
 
@@ -223,14 +223,32 @@ class CompanyFunctionsMetaClass:
         """
         from .kfinance import BusinessRelationships, Companies
 
-        companies = self.kfinance_api_client.fetch_companies_from_business_relationship(
-            self.company_id,
-            relationship_type,
-        )
-        return BusinessRelationships(
-            Companies(self.kfinance_api_client, companies["current"]),
-            Companies(self.kfinance_api_client, companies["previous"]),
+        relationship_resp = self.kfinance_api_client.fetch_companies_from_business_relationship(
+            company_id=self.company_id,
+            relationship_type=relationship_type,
         )
+        if isinstance(relationship_resp, RelationshipResponse):
+            return BusinessRelationships(
+                current=Companies(
+                    kfinance_api_client=self.kfinance_api_client,
+                    company_ids=[c.company_id for c in relationship_resp.current],
+                ),
+                previous=Companies(
+                    kfinance_api_client=self.kfinance_api_client,
+                    company_ids=[c.company_id for c in relationship_resp.previous],
+                ),
+            )
+        else:
+            return BusinessRelationships(
+                current=Companies(
+                    kfinance_api_client=self.kfinance_api_client,
+                    company_ids=relationship_resp.current,
+                ),
+                previous=Companies(
+                    kfinance_api_client=self.kfinance_api_client,
+                    company_ids=relationship_resp.previous,
+                ),
+            )
 
     def market_cap(
         self,

kfinance/pydantic_models.py

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

kfinance/tests/test_example_notebook.py

@@ -44,7 +44,7 @@ def jupyter_kernel_name() -> str:
 
 def test_run_notebook(jupyter_kernel_name: str):
     """
-    GIVEN the usage_examples.ipynb notebook
+    GIVEN the basic_usage.ipynb notebook
     WHEN the notebook gets run with a mock client and mock responses
     THEN all cells of the notebook complete without errors.
     """
@@ -165,7 +165,9 @@ def test_run_notebook(jupyter_kernel_name: str):
     """)
 
     # Load the notebook
-    notebook_path = Path(Path(__file__).parent.parent.parent, "usage_examples.ipynb")
+    notebook_path = Path(
+        Path(__file__).parent.parent.parent, "example_notebooks", "basic_usage.ipynb"
+    )
     with notebook_path.open() as f:
         nb = nbformat.read(f, as_version=4)