kensho-kfinance 2.2.5__py3-none-any.whl → 2.4.0__py3-none-any.whl

{kensho_kfinance-2.2.5.dist-info → kensho_kfinance-2.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 2.2.5
+Version: 2.4.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
@@ -13,8 +13,10 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: AUTHORS.md
 Requires-Dist: cachetools<6,>=5.5
+Requires-Dist: click<=9,>=8.2.1
+Requires-Dist: fastmcp<3,>=2
 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 +31,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"
@@ -51,7 +54,7 @@ Any questions or suggestions can be sent to the [kFinance Maintainers](kfinance-
 
 # Setup
 
-You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via 
+You can install kFinance on [PyPI](https://pypi.org/project/kensho-kfinance/) via
 
 `pip install kensho-kfinance`
 
@@ -61,11 +64,41 @@ 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.
+
+# MCP (Model Context Protocol)
+
+To run the kFinance MCP server use:
+
+`python -m kfinance.mcp`
+
+This function initializes and starts an MCP server that exposes the kFinance tools. The server supports multiple authentication methods and transport protocols to accommodate different deployment scenarios.
+
+The server's full signature is as follows:
+
+`kfinance.mcp [--stdio,-s]/[--sse, ] --refresh-token <refresh-token> --client-id <client-id> --private-key <private-key>`
+
+Authentication Methods (in order of precedence):
+1. Refresh Token: Uses an existing refresh token for authentication. The `--refresh-token <refresh-token>` argument must be provided.
+2. Key Pair: Uses client ID and private key for authentication. Both the `--client-id <client-id>` and `--private-key <private-key>` arguments must be provided.
+3. Browser: Falls back to browser-based authentication flow. This occurs if no auth arguments are provided.
+
+Transport Layers:
+- stdio can be set by passing either `--stdio` or `-s`
+- sse can be set by passing `--sse` or no other transport related flag
 
 # Versioning
-The kFinance uses semantic versioning (major, minor, patch). 
-To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md). 
+The kFinance uses semantic versioning (major, minor, patch).
+To bump the version, add a new entry in [CHANGELOG.md](kfinance%2FCHANGELOG.md).
 This will generate a new version of the library as part of the release process.
 
 # License

{kensho_kfinance-2.2.5.dist-info → kensho_kfinance-2.4.0.dist-info}/RECORD

@@ -1,31 +1,34 @@
-kensho_kfinance-2.2.5.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-2.2.5.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=Nlkx-7DFWd9kyeKUdm7pqHW7bFi8ZdruQxCmOo88TpY,1302
+kensho_kfinance-2.4.0.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-2.4.0.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=snsLVUBbhNjIau_BsoWKdxxCAPbPHM_rUQ3pNsseF_k,1446
 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=y4B-xPKrGNDVkicSf904q-M1hXHtNN8AuJ0Y55x_r2s,23464
-kfinance/kfinance.py,sha256=_U69k0Dcwkw1B_lzaUZy8N2-c-v93ZKoUAVVZb6wBUM,52758
+kfinance/fetch.py,sha256=yaCih8PAkOhVHb3tvmBW0x2w4QmXJiyUATu6Yx-xzP4,23851
+kfinance/kfinance.py,sha256=9lcarUW4fLHJA_U7_1ihCMbNJWs0AztvKf_XEd0qupk,59889
+kfinance/mcp.py,sha256=57OoTrxo5x_v7u1s3WFQNG0LySXyLEGc6CKSVpJLJVw,3717
 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=WWLjcxBvVOpW2Wzpq1zKKju4uMlIeH4nKvM2GqLsjEE,597
+kfinance/pydantic_models.py,sha256=avpbPqwrAyLqsCbrmFpK_B8_fj1nPlBHrnPxRcBaSkE,774
 kfinance/server_thread.py,sha256=jUnt1YGoYDkqqz1MbCwd44zJs1T_Z2BCgvj75bdtLgA,2574
-kfinance/version.py,sha256=VXEVDzLsFHRu1B1J9TV6pbjt3sWduv6BDj43YpV5xIM,511
+kfinance/version.py,sha256=KyHVhKcn4Ob8_JP09Buz8x5uB4b7RJZLl3FBlZ8sWSY,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=LbE8JLS4OsByfQ_GsGxYwSX5Z4Dgfr-T6bFaZo1k7Oo,16079
+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_mcp.py,sha256=-pmeZ0PDp8GmXWcrWmaNNqMe7OVZONZLrjA0Y4b82os,594
+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
@@ -33,12 +36,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.5.dist-info/METADATA,sha256=ilytuQ2DVw1h-i2Qo3EV-VKP6_p0OgiuF-Fzdvo5R9M,3436
-kensho_kfinance-2.2.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kensho_kfinance-2.2.5.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-2.2.5.dist-info/RECORD,,
+kensho_kfinance-2.4.0.dist-info/METADATA,sha256=yWX6RmluCSz_qoG7EVTJnKJcsOByeZYXmu3M88-ch2A,5191
+kensho_kfinance-2.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kensho_kfinance-2.4.0.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-2.4.0.dist-info/RECORD,,

kfinance/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v2.4.0
+- Add MCP server
+
+## 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
 

kfinance/fetch.py

@@ -567,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/mcp.py

@@ -0,0 +1,101 @@
+from textwrap import dedent
+from typing import Literal, Optional
+
+import click
+from fastmcp import FastMCP
+from fastmcp.utilities.logging import get_logger
+
+from kfinance.kfinance import Client
+from kfinance.tool_calling.shared_models import KfinanceTool
+
+
+logger = get_logger(__name__)
+
+
+def build_doc_string(tool: KfinanceTool) -> str:
+    """Build a formatted documentation string for a Kfinance tool.
+
+    This function takes a KfinanceTool object and constructs a comprehensive
+    documentation string that includes the tool's description and detailed
+    information about its arguments, including default values and descriptions.
+
+    :param tool: The Kfinance tool object containing metadata about the tool's functionality, description, and argument schema.
+    :type tool: KfinanceTool
+    :return: A formatted documentation string containing for the tool description with detailed argument information.
+    :rtype: str
+    """
+
+    description = dedent(f"""
+        {tool.description}
+
+        Args:
+    """).strip()
+
+    for arg_name, arg_field in tool.args_schema.model_fields.items():
+        default_value_description = (
+            f"Default: {arg_field.default}. " if not arg_field.is_required() else ""
+        )
+        param_description = f"\n    {arg_name}: {default_value_description}{arg_field.description}"
+        description += param_description
+
+    return description
+
+
+@click.command()
+@click.option("--stdio/--sse", "-s/ ", default=False)
+@click.option("--refresh-token", required=False)
+@click.option("--client-id", required=False)
+@click.option("--private-key", required=False)
+def run_mcp(
+    stdio: bool,
+    refresh_token: Optional[str] = None,
+    client_id: Optional[str] = None,
+    private_key: Optional[str] = None,
+) -> None:
+    """Run the Kfinance MCP server with specified configuration.
+
+    This function initializes and starts an MCP server that exposes Kfinance
+    tools. The server supports multiple authentication methods and
+    transport protocols to accommodate different deployment scenarios.
+
+    Authentication Methods (in order of precedence):
+    1. Refresh Token: Uses an existing refresh token for authentication
+    2. Key Pair: Uses client ID and private key for authentication
+    3. Browser: Falls back to browser-based authentication flow
+
+    :param stdio: If True, use STDIO transport; if False, use SSE transport.
+    :type stdio: bool
+    :param refresh_token: OAuth refresh token for authentication
+    :type refresh_token: str
+    :param client_id: Client id for key-pair authentication
+    :type client_id: str
+    :param private_key: Private key for key-pair authentication.
+    :type private_key: str
+    """
+    transport: Literal["stdio", "sse"] = "stdio" if stdio else "sse"
+    logger.info("Sever will run with %s transport", transport)
+    if refresh_token:
+        logger.info("The client will be authenticated using a refresh token")
+        kfinance_client = Client(refresh_token=refresh_token)
+    elif client_id and private_key:
+        logger.info("The client will be authenticated using a key pair")
+        kfinance_client = Client(client_id=client_id, private_key=private_key)
+    else:
+        logger.info("The client will be authenticated using a browser")
+        kfinance_client = Client()
+
+    kfinance_mcp: FastMCP = FastMCP("Kfinance")
+    for tool in kfinance_client.langchain_tools:
+        logger.info("Adding %s to server", tool.name)
+        kfinance_mcp.tool(
+            name_or_fn=getattr(tool, "_run"),
+            name=tool.name,
+            description=build_doc_string(tool),
+        )
+
+    logger.info("Server starting")
+    kfinance_mcp.run(transport=transport)
+
+
+if __name__ == "__main__":
+    run_mcp()

kfinance/pydantic_models.py

@@ -1,6 +1,14 @@
 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.
 

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)
 

kfinance/tests/test_fetch.py

@@ -138,6 +138,18 @@ class TestFetchItem(TestCase):
         self.kfinance_api_client.fetch_earnings_dates(company_id=company_id)
         self.kfinance_api_client.fetch.assert_called_once_with(expected_fetch_url)
 
+    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)
+        self.kfinance_api_client.fetch.assert_called_once_with(expected_fetch_url)
+
+    def test_fetch_transcript(self) -> None:
+        key_dev_id = 12345
+        expected_fetch_url = f"{self.kfinance_api_client.url_base}transcript/{key_dev_id}"
+        self.kfinance_api_client.fetch_transcript(key_dev_id=key_dev_id)
+        self.kfinance_api_client.fetch.assert_called_once_with(expected_fetch_url)
+
     def test_fetch_ticker_geography_groups(self) -> None:
         country_iso_code = "USA"
         expected_fetch_url = (

kfinance/tests/test_mcp.py

@@ -0,0 +1,16 @@
+from typing import Type
+
+import pytest
+
+from kfinance.kfinance import Client
+from kfinance.mcp import build_doc_string
+from kfinance.tool_calling import ALL_TOOLS
+from kfinance.tool_calling.shared_models import KfinanceTool
+
+
+class TestDocStringBuilding:
+    @pytest.mark.parametrize("tool_class", ALL_TOOLS)
+    def test_build_doc_string(self, mock_client: Client, tool_class: Type[KfinanceTool]):
+        """This test build the docstring for each tool. A success is considered if no exception is raised"""
+        tool = tool_class(kfinance_client=mock_client)
+        build_doc_string(tool)

kfinance/tests/test_objects.py

@@ -1,4 +1,4 @@
-from datetime import datetime, timezone
+from datetime import date, datetime, timezone
 from io import BytesIO
 import re
 from typing import Optional
@@ -7,8 +7,9 @@ from unittest import TestCase
 import numpy as np
 import pandas as pd
 from PIL.Image import open as image_open
+import time_machine
 
-from kfinance.kfinance import Company, Security, Ticker, TradingItem
+from kfinance.kfinance import Company, Earnings, Security, Ticker, TradingItem, Transcript
 
 
 msft_company_id = "21835"
@@ -54,6 +55,25 @@ 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",
+                },
+            ]
+        },
         "statements": {
             "income_statement": {
                 "statements": {
@@ -91,6 +111,32 @@ MOCK_COMPANY_DB = {
     }
 }
 
+MOCK_TRANSCRIPT_DB = {
+    1916266380: {
+        "transcript": [
+            {
+                "component_type": "Presentation Operator Message",
+                "person_name": "Operator",
+                "text": "Good morning, and welcome to Microsoft's Fourth Quarter 2024 Earnings Conference Call.",
+            },
+            {
+                "component_type": "Presenter Speech",
+                "person_name": "Satya Nadella",
+                "text": "Thank you for joining us today. We had an exceptional quarter with strong growth across all segments.",
+            },
+        ]
+    },
+    1916266381: {
+        "transcript": [
+            {
+                "component_type": "Presentation Operator Message",
+                "person_name": "Operator",
+                "text": "Good morning, and welcome to Microsoft's First Quarter 2025 Earnings Conference Call.",
+            }
+        ]
+    },
+}
+
 
 MOCK_SECURITY_DB = {msft_security_id: {"isin": msft_isin, "cusip": msft_cusip}}
 
@@ -215,6 +261,14 @@ class MockKFinanceApiClient:
         """Get a segment"""
         return MOCK_COMPANY_DB[company_id]
 
+    def fetch_earnings(self, company_id: int) -> dict:
+        """Get the earnings for a company."""
+        return MOCK_COMPANY_DB[company_id]["earnings"]
+
+    def fetch_transcript(self, key_dev_id: int) -> dict:
+        """Get the transcript for an earnings item."""
+        return MOCK_TRANSCRIPT_DB[key_dev_id]
+
 
 class TestTradingItem(TestCase):
     def setUp(self):
@@ -619,3 +673,112 @@ class TestTicker(TestCase):
         expected_dataframe.index.name = "date"
         market_caps = self.msft_ticker_from_ticker.market_cap()
         pd.testing.assert_frame_equal(expected_dataframe, market_caps)
+
+
+class TestTranscript(TestCase):
+    def setUp(self):
+        """setup tests"""
+        self.transcript_components = [
+            {
+                "component_type": "Presentation Operator Message",
+                "person_name": "Operator",
+                "text": "Good morning, and welcome to Microsoft's Fourth Quarter 2024 Earnings Conference Call.",
+            },
+            {
+                "component_type": "Presenter Speech",
+                "person_name": "Satya Nadella",
+                "text": "Thank you for joining us today. We had an exceptional quarter with strong growth across all segments.",
+            },
+        ]
+        self.transcript = Transcript(self.transcript_components)
+
+    def test_transcript_length(self):
+        """test transcript length"""
+        self.assertEqual(len(self.transcript), 2)
+
+    def test_transcript_indexing(self):
+        """test transcript indexing"""
+        self.assertEqual(
+            self.transcript[0].person_name, self.transcript_components[0]["person_name"]
+        )
+        self.assertEqual(self.transcript[0].text, self.transcript_components[0]["text"])
+        self.assertEqual(
+            self.transcript[0].component_type, self.transcript_components[0]["component_type"]
+        )
+        self.assertEqual(
+            self.transcript[1].person_name, self.transcript_components[1]["person_name"]
+        )
+        self.assertEqual(self.transcript[1].text, self.transcript_components[1]["text"])
+        self.assertEqual(
+            self.transcript[1].component_type, self.transcript_components[1]["component_type"]
+        )
+
+    def test_transcript_raw(self):
+        """test transcript raw property"""
+        expected_raw = "Operator: Good morning, and welcome to Microsoft's Fourth Quarter 2024 Earnings Conference Call.\n\nSatya Nadella: Thank you for joining us today. We had an exceptional quarter with strong growth across all segments."
+        self.assertEqual(self.transcript.raw, expected_raw)
+
+
+class TestEarnings(TestCase):
+    def setUp(self):
+        """setup tests"""
+        self.kfinance_api_client = MockKFinanceApiClient()
+        self.earnings = Earnings(
+            kfinance_api_client=self.kfinance_api_client,
+            name="Microsoft Corporation, Q4 2024 Earnings Call, Jul 25, 2024",
+            datetime=datetime.fromisoformat("2024-07-25T21:30:00").replace(tzinfo=timezone.utc),
+            key_dev_id=1916266380,
+        )
+
+    def test_earnings_attributes(self):
+        """test earnings attributes"""
+        self.assertEqual(
+            self.earnings.name, "Microsoft Corporation, Q4 2024 Earnings Call, Jul 25, 2024"
+        )
+        self.assertEqual(self.earnings.key_dev_id, 1916266380)
+        expected_datetime = datetime.fromisoformat("2024-07-25T21:30:00").replace(
+            tzinfo=timezone.utc
+        )
+        self.assertEqual(self.earnings.datetime, expected_datetime)
+
+    def test_earnings_transcript(self):
+        """test earnings transcript property"""
+        transcript = self.earnings.transcript
+        self.assertIsInstance(transcript, Transcript)
+        self.assertEqual(len(transcript), 2)
+        self.assertEqual(transcript[0].person_name, "Operator")
+        self.assertEqual(transcript[1].person_name, "Satya Nadella")
+
+
+class TestCompanyEarnings(TestCase):
+    def setUp(self):
+        """setup tests"""
+        self.kfinance_api_client = MockKFinanceApiClient()
+        self.msft_company = Company(self.kfinance_api_client, msft_company_id)
+
+    def test_company_earnings(self):
+        """test company earnings method"""
+        earnings_list = self.msft_company.earnings()
+        self.assertEqual(len(earnings_list), 3)
+        self.assertIsInstance(earnings_list[0], Earnings)
+        self.assertEqual(earnings_list[0].key_dev_id, 1916266380)
+
+    def test_company_earnings_with_date_filter(self):
+        """test company earnings method with date filtering"""
+        start_date = date(2024, 8, 1)
+        end_date = date(2024, 12, 31)
+        earnings_list = self.msft_company.earnings(start_date=start_date, end_date=end_date)
+        self.assertEqual(len(earnings_list), 1)
+        self.assertEqual(earnings_list[0].key_dev_id, 1916266381)
+
+    @time_machine.travel(datetime(2025, 2, 1, 12, tzinfo=timezone.utc))
+    def test_company_latest_earnings(self):
+        """test company latest_earnings property"""
+        latest_earnings = self.msft_company.latest_earnings
+        self.assertEqual(latest_earnings.key_dev_id, 1916266382)
+
+    @time_machine.travel(datetime(2024, 6, 1, 12, tzinfo=timezone.utc))
+    def test_company_next_earnings(self):
+        """test company next_earnings property"""
+        next_earnings = self.msft_company.next_earnings
+        self.assertEqual(next_earnings.key_dev_id, 1916266380)

kfinance/tests/test_tools.py

@@ -1,13 +1,15 @@
 from datetime import date, datetime
 
 from langchain_core.utils.function_calling import convert_to_openai_tool
+from pytest import raises
 from requests_mock import Mocker
 import time_machine
 
 from kfinance.constants import BusinessRelationshipType, Capitalization, SegmentType, StatementType
-from kfinance.kfinance import Client
+from kfinance.kfinance import Client, NoEarningsDataError
 from kfinance.tests.conftest import SPGI_COMPANY_ID, SPGI_SECURITY_ID, SPGI_TRADING_ITEM_ID
 from kfinance.tool_calling import (
+    GetEarnings,
     GetEarningsCallDatetimesFromIdentifier,
     GetFinancialLineItemFromIdentifier,
     GetFinancialStatementFromIdentifier,
@@ -15,8 +17,11 @@ from kfinance.tool_calling import (
     GetInfoFromIdentifier,
     GetIsinFromTicker,
     GetLatest,
+    GetLatestEarnings,
+    GetNextEarnings,
     GetNQuartersAgo,
     GetPricesFromIdentifier,
+    GetTranscript,
     ResolveIdentifier,
 )
 from kfinance.tool_calling.get_business_relationship_from_identifier import (
@@ -42,6 +47,7 @@ from kfinance.tool_calling.get_segments_from_identifier import (
     GetSegmentsFromIdentifier,
     GetSegmentsFromIdentifierArgs,
 )
+from kfinance.tool_calling.get_transcript import GetTranscriptArgs
 from kfinance.tool_calling.shared_models import ToolArgsWithIdentifier
 
 
@@ -422,3 +428,213 @@ class TestResolveIdentifier:
             "security_id": SPGI_SECURITY_ID,
             "trading_item_id": SPGI_TRADING_ITEM_ID,
         }
+
+
+class TestGetLatestEarnings:
+    def test_get_latest_earnings(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetLatestEarnings tool
+        WHEN we request the latest earnings for SPGI
+        THEN we get back the latest SPGI earnings
+        """
+        earnings_data = {
+            "earnings": [
+                {
+                    "name": "SPGI Q4 2024 Earnings Call",
+                    "datetime": "2025-02-11T13:30:00Z",
+                    "keydevid": 12345,
+                },
+                {
+                    "name": "SPGI Q3 2024 Earnings Call",
+                    "datetime": "2024-10-30T12:30:00Z",
+                    "keydevid": 12344,
+                },
+            ]
+        }
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
+            json=earnings_data,
+        )
+
+        expected_response = {
+            "name": "SPGI Q4 2024 Earnings Call",
+            "key_dev_id": 12345,
+            "datetime": "2025-02-11T13:30:00+00:00",
+        }
+
+        tool = GetLatestEarnings(kfinance_client=mock_client)
+        response = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+        assert response == expected_response
+
+    def test_get_latest_earnings_no_data(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetLatestEarnings tool
+        WHEN we request the latest earnings for a company with no data
+        THEN we get a NoEarningsDataError exception
+        """
+        earnings_data = {"earnings": []}
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
+            json=earnings_data,
+        )
+
+        tool = GetLatestEarnings(kfinance_client=mock_client)
+        with raises(NoEarningsDataError, match="Latest earnings for SPGI not found"):
+            tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+
+
+class TestGetNextEarnings:
+    def test_get_next_earnings_(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetNextEarnings tool
+        WHEN we request the next earnings for SPGI
+        THEN we get back the next SPGI earnings
+        """
+        earnings_data = {
+            "earnings": [
+                {
+                    "name": "SPGI Q1 2025 Earnings Call",
+                    "datetime": "2025-04-29T12:30:00Z",
+                    "keydevid": 12346,
+                },
+                {
+                    "name": "SPGI Q4 2024 Earnings Call",
+                    "datetime": "2025-02-11T13:30:00Z",
+                    "keydevid": 12345,
+                },
+            ]
+        }
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
+            json=earnings_data,
+        )
+
+        expected_response = {
+            "name": "SPGI Q1 2025 Earnings Call",
+            "key_dev_id": 12346,
+            "datetime": "2025-04-29T12:30:00+00:00",
+        }
+
+        with time_machine.travel("2025-03-01T00:00:00+00:00"):
+            tool = GetNextEarnings(kfinance_client=mock_client)
+            response = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+            assert response == expected_response
+
+    def test_get_next_earnings_no_data(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetNextEarnings tool
+        WHEN we request the next earnings for a company with no data
+        THEN we get a NoEarningsDataError exception
+        """
+        earnings_data = {"earnings": []}
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
+            json=earnings_data,
+        )
+
+        with time_machine.travel("2025-03-01T00:00:00+00:00"):
+            tool = GetNextEarnings(kfinance_client=mock_client)
+            with raises(NoEarningsDataError, match="Next earnings for SPGI not found"):
+                tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+
+
+class TestGetEarnings:
+    def test_get_earnings(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetEarnings tool
+        WHEN we request all earnings for SPGI
+        THEN we get back all SPGI earnings
+        """
+        earnings_data = {
+            "earnings": [
+                {
+                    "name": "SPGI Q1 2025 Earnings Call",
+                    "datetime": "2025-04-29T12:30:00Z",
+                    "keydevid": 12346,
+                },
+                {
+                    "name": "SPGI Q4 2024 Earnings Call",
+                    "datetime": "2025-02-11T13:30:00Z",
+                    "keydevid": 12345,
+                },
+            ]
+        }
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
+            json=earnings_data,
+        )
+
+        expected_response = [
+            {
+                "name": "SPGI Q1 2025 Earnings Call",
+                "key_dev_id": 12346,
+                "datetime": "2025-04-29T12:30:00+00:00",
+            },
+            {
+                "name": "SPGI Q4 2024 Earnings Call",
+                "key_dev_id": 12345,
+                "datetime": "2025-02-11T13:30:00+00:00",
+            },
+        ]
+
+        tool = GetEarnings(kfinance_client=mock_client)
+        response = tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+        assert response == expected_response
+
+    def test_get_earnings_no_data(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetEarnings tool
+        WHEN we request all earnings for a company with no data
+        THEN we get a NoEarningslDataError exception
+        """
+        earnings_data = {"earnings": []}
+
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/earnings/{SPGI_COMPANY_ID}",
+            json=earnings_data,
+        )
+
+        tool = GetEarnings(kfinance_client=mock_client)
+        with raises(NoEarningsDataError, match="Earnings for SPGI not found"):
+            tool.run(ToolArgsWithIdentifier(identifier="SPGI").model_dump(mode="json"))
+
+
+class TestGetTranscript:
+    def test_get_transcript(self, requests_mock: Mocker, mock_client: Client):
+        """
+        GIVEN the GetTranscript tool
+        WHEN we request a transcript by key_dev_id
+        THEN we get back the transcript text
+        """
+        transcript_data = {
+            "transcript": [
+                {
+                    "person_name": "Operator",
+                    "text": "Good morning, everyone.",
+                    "component_type": "speech",
+                },
+                {
+                    "person_name": "CEO",
+                    "text": "Thank you for joining us today.",
+                    "component_type": "speech",
+                },
+            ]
+        }
+
+        requests_mock.get(
+            url="https://kfinance.kensho.com/api/v1/transcript/12345",
+            json=transcript_data,
+        )
+
+        expected_response = (
+            "Operator: Good morning, everyone.\n\nCEO: Thank you for joining us today."
+        )
+
+        tool = GetTranscript(kfinance_client=mock_client)
+        response = tool.run(GetTranscriptArgs(key_dev_id=12345).model_dump(mode="json"))
+        assert response == expected_response

kfinance/tool_calling/__init__.py

@@ -5,6 +5,7 @@ from kfinance.tool_calling.get_business_relationship_from_identifier import (
 )
 from kfinance.tool_calling.get_capitalization_from_identifier import GetCapitalizationFromIdentifier
 from kfinance.tool_calling.get_cusip_from_ticker import GetCusipFromTicker
+from kfinance.tool_calling.get_earnings import GetEarnings
 from kfinance.tool_calling.get_earnings_call_datetimes_from_identifier import (
     GetEarningsCallDatetimesFromIdentifier,
 )
@@ -20,11 +21,14 @@ from kfinance.tool_calling.get_history_metadata_from_identifier import (
 from kfinance.tool_calling.get_info_from_identifier import GetInfoFromIdentifier
 from kfinance.tool_calling.get_isin_from_ticker import GetIsinFromTicker
 from kfinance.tool_calling.get_latest import GetLatest
+from kfinance.tool_calling.get_latest_earnings import GetLatestEarnings
 from kfinance.tool_calling.get_n_quarters_ago import GetNQuartersAgo
+from kfinance.tool_calling.get_next_earnings import GetNextEarnings
 from kfinance.tool_calling.get_prices_from_identifier import GetPricesFromIdentifier
 from kfinance.tool_calling.get_segments_from_identifier import (
     GetSegmentsFromIdentifier,
 )
+from kfinance.tool_calling.get_transcript import GetTranscript
 from kfinance.tool_calling.resolve_identifier import ResolveIdentifier
 from kfinance.tool_calling.shared_models import KfinanceTool
 
@@ -36,6 +40,10 @@ ALL_TOOLS: list[Type[KfinanceTool]] = [
     GetCusipFromTicker,
     GetInfoFromIdentifier,
     GetEarningsCallDatetimesFromIdentifier,
+    GetEarnings,
+    GetLatestEarnings,
+    GetNextEarnings,
+    GetTranscript,
     GetHistoryMetadataFromIdentifier,
     GetPricesFromIdentifier,
     GetCapitalizationFromIdentifier,

kfinance/tool_calling/get_earnings.py

@@ -0,0 +1,30 @@
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.constants import Permission
+from kfinance.kfinance import NoEarningsDataError
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetEarnings(KfinanceTool):
+    name: str = "get_earnings"
+    description: str = "Get all earnings for a given identifier. Returns a list of dictionaries, each with 'name' (str), 'key_dev_id' (int), and 'datetime' (str in ISO 8601 format with UTC timezone) attributes."
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+    required_permission: Permission | None = Permission.EarningsPermission
+
+    def _run(self, identifier: str) -> list[dict]:
+        ticker = self.kfinance_client.ticker(identifier)
+        earnings = ticker.company.earnings()
+
+        if not earnings:
+            raise NoEarningsDataError(f"Earnings for {identifier} not found")
+
+        return [
+            {
+                "name": earnings_item.name,
+                "key_dev_id": earnings_item.key_dev_id,
+                "datetime": earnings_item.datetime.isoformat(),
+            }
+            for earnings_item in earnings
+        ]

kfinance/tool_calling/get_latest_earnings.py

@@ -0,0 +1,27 @@
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.constants import Permission
+from kfinance.kfinance import NoEarningsDataError
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetLatestEarnings(KfinanceTool):
+    name: str = "get_latest_earnings"
+    description: str = "Get the latest earnings for a given identifier. Returns a dictionary with 'name' (str), 'key_dev_id' (int), and 'datetime' (str in ISO 8601 format with UTC timezone) attributes."
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+    required_permission: Permission | None = Permission.EarningsPermission
+
+    def _run(self, identifier: str) -> dict:
+        ticker = self.kfinance_client.ticker(identifier)
+        latest_earnings = ticker.company.latest_earnings
+
+        if latest_earnings is None:
+            raise NoEarningsDataError(f"Latest earnings for {identifier} not found")
+
+        return {
+            "name": latest_earnings.name,
+            "key_dev_id": latest_earnings.key_dev_id,
+            "datetime": latest_earnings.datetime.isoformat(),
+        }

kfinance/tool_calling/get_next_earnings.py

@@ -0,0 +1,27 @@
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.constants import Permission
+from kfinance.kfinance import NoEarningsDataError
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetNextEarnings(KfinanceTool):
+    name: str = "get_next_earnings"
+    description: str = "Get the next earnings for a given identifier. Returns a dictionary with 'name' (str), 'key_dev_id' (int), and 'datetime' (str in ISO 8601 format with UTC timezone) attributes."
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+    required_permission: Permission | None = Permission.EarningsPermission
+
+    def _run(self, identifier: str) -> dict:
+        ticker = self.kfinance_client.ticker(identifier)
+        next_earnings = ticker.company.next_earnings
+
+        if next_earnings is None:
+            raise NoEarningsDataError(f"Next earnings for {identifier} not found")
+
+        return {
+            "name": next_earnings.name,
+            "key_dev_id": next_earnings.key_dev_id,
+            "datetime": next_earnings.datetime.isoformat(),
+        }

kfinance/tool_calling/get_transcript.py

@@ -0,0 +1,23 @@
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+from kfinance.constants import Permission
+from kfinance.tool_calling.shared_models import KfinanceTool
+
+
+class GetTranscriptArgs(BaseModel):
+    """Tool argument with a key_dev_id."""
+
+    key_dev_id: int = Field(description="The key dev ID for the earnings call")
+
+
+class GetTranscript(KfinanceTool):
+    name: str = "get_transcript"
+    description: str = "Get the raw transcript text for an earnings call by key dev ID."
+    args_schema: Type[BaseModel] = GetTranscriptArgs
+    required_permission: Permission | None = Permission.EarningsPermission
+
+    def _run(self, key_dev_id: int) -> str:
+        transcript = self.kfinance_client.transcript(key_dev_id)
+        return transcript.raw

kfinance/tool_calling/prompts.py

@@ -0,0 +1,16 @@
+from kfinance.tool_calling import GetFinancialLineItemFromIdentifier, GetLatest
+
+
+BASE_PROMPT = f"""
+    You are an agent that calls one or more tools to retrieve data to answer questions from
+    financial analysts. Use the supplied tools to answer the user's questions.
+
+    - Always use the `{GetLatest.model_fields["name"].default}` function when asked about the last or most recent quarter or
+    when the time is unspecified in the question.
+    - Try to use `{GetFinancialLineItemFromIdentifier.model_fields["name"].default}` for questions about a company's
+    finances.
+    - If the tools do not respond with data that answers the question, then respond by saying that
+    you don't have the data available.
+    - Keep calling tools until you have the answer or the tool says the data is not available.
+    - Label large numbers with "million" or "billion" and currency symbols if appropriate.
+    """

kfinance/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '2.2.5'
-__version_tuple__ = version_tuple = (2, 2, 5)
+__version__ = version = '2.4.0'
+__version_tuple__ = version_tuple = (2, 4, 0)