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

kfinance/tests/test_fetch.py

@@ -2,9 +2,17 @@ from unittest import TestCase
 from unittest.mock import MagicMock
 
 import pytest
+from requests_mock import Mocker
 
-from kfinance.constants import Periodicity, PeriodType
+from kfinance.constants import BusinessRelationshipType, Periodicity, PeriodType
 from kfinance.fetch import KFinanceApiClient
+from kfinance.kfinance import Client
+from kfinance.pydantic_models import (
+    CompanyIdAndName,
+    RelationshipResponse,
+    RelationshipResponseNoName,
+)
+from kfinance.tests.conftest import SPGI_COMPANY_ID
 
 
 def build_mock_api_client() -> KFinanceApiClient:
@@ -130,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 = (
@@ -279,3 +299,56 @@ class TestMarketCap:
         expected_fetch_url = f"{client.url_base}users/permissions"
         client.fetch_permissions()
         client.fetch.assert_called_with(expected_fetch_url)
+
+
+class TestFetchCompaniesFromBusinessRelationship:
+    def test_old_response_format(self, requests_mock: Mocker, mock_client: Client) -> None:
+        """
+        GIVEN a business relationship request
+        WHEN the api returns a response in the old (no name) format
+        THEN the response can successfully be parsed.
+        """
+        http_resp = {"current": [883103], "previous": [472898, 8182358]}
+        expected_result = RelationshipResponseNoName(current=[883103], previous=[472898, 8182358])
+        requests_mock.get(
+            url=f"{mock_client.kfinance_api_client.url_base}relationship/{SPGI_COMPANY_ID}/{BusinessRelationshipType.supplier}",
+            json=http_resp,
+        )
+
+        resp = mock_client.kfinance_api_client.fetch_companies_from_business_relationship(
+            company_id=SPGI_COMPANY_ID, relationship_type=BusinessRelationshipType.supplier
+        )
+        assert resp == expected_result
+
+    def test_new_response_format(self, requests_mock: Mocker, mock_client: Client) -> None:
+        """
+        GIVEN a business relationship request
+        WHEN the api returns a response in the new (with name) format
+        THEN the response can successfully be parsed.
+        """
+
+        http_resp = {
+            "current": [{"company_name": "foo", "company_id": 883103}],
+            "previous": [
+                {"company_name": "bar", "company_id": 472898},
+                {"company_name": "baz", "company_id": 8182358},
+            ],
+        }
+
+        expected_result = RelationshipResponse(
+            current=[CompanyIdAndName(company_name="foo", company_id=883103)],
+            previous=[
+                CompanyIdAndName(company_name="bar", company_id=472898),
+                CompanyIdAndName(company_name="baz", company_id=8182358),
+            ],
+        )
+
+        requests_mock.get(
+            url=f"{mock_client.kfinance_api_client.url_base}relationship/{SPGI_COMPANY_ID}/{BusinessRelationshipType.supplier}",
+            json=http_resp,
+        )
+
+        resp = mock_client.kfinance_api_client.fetch_companies_from_business_relationship(
+            company_id=SPGI_COMPANY_ID, relationship_type=BusinessRelationshipType.supplier
+        )
+        assert resp == expected_result

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(),
+        }