kensho-kfinance 3.1.0__py3-none-any.whl → 3.2.0__py3-none-any.whl

{kensho_kfinance-3.1.0.dist-info → kensho_kfinance-3.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kensho-kfinance
-Version: 3.1.0
+Version: 3.2.0
 Summary: Python CLI for kFinance
 Author-email: Luke Brown <luke.brown@kensho.com>, Michelle Keoy <michelle.keoy@kensho.com>, Keith Page <keith.page@kensho.com>, Matthew Rosen <matthew.rosen@kensho.com>, Nick Roshdieh <nick.roshdieh@kensho.com>
 Project-URL: source, https://github.com/kensho-technologies/kfinance

{kensho_kfinance-3.1.0.dist-info → kensho_kfinance-3.2.0.dist-info}/RECORD

@@ -1,19 +1,19 @@
-kensho_kfinance-3.1.0.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-3.1.0.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=HFCQeAbfhuhQ-Yhj9gPjNezoYJMs_dvfjjs6hhzv9RE,2576
+kensho_kfinance-3.2.0.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
+kensho_kfinance-3.2.0.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
+kfinance/CHANGELOG.md,sha256=q1nGxRpIJgjeQ-p2WEEBvPfC93NQ0GSaof7wprmBvqY,2659
 kfinance/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 kfinance/conftest.py,sha256=O9e1ddyTfqnZ1T-9ehnkXwK8PfxPdCHAI7-fke52Ouk,3281
 kfinance/mcp.py,sha256=LTzCIlqsDKRD-0Xcpa_P99-JmJ8duAneO_-GzM43kjw,424
 kfinance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/version.py,sha256=KrVRMDzlLQ07c4N1d6-nDOLo4hWpD8cSSFcYXWlm64k,511
+kfinance/version.py,sha256=y06zal8IRedOSeT6uowixE-C3eIqYMoBwLenNv0a-Zc,511
 kfinance/client/README.md,sha256=DA5vg4uz1JmJNiqvYywrj46YNhOr584WO8L83Ysx_Mk,372
 kfinance/client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/client/batch_request_handling.py,sha256=opwJJAU2JtqH-s4vt8wRqhH34MiU4tQP6Ng7K6b3upA,6561
-kfinance/client/fetch.py,sha256=Sd-Qcz9k37FHsUB-5OLxn2XimnneoW9Km3wKsiWBUO0,28652
+kfinance/client/fetch.py,sha256=JKw09G8P9jMw6qwVY4E-SAOW1YhZqVzOkirh0Nu8g9o,29336
 kfinance/client/industry_models.py,sha256=ydB_cTIsNsfCUeaO7K2qqLUuHdG6WfUCoAzBigKVV8M,243
 kfinance/client/kfinance.py,sha256=9BMhXfmw5WzNl-xFdLvkvgJIr585F5rlM7YePwtlW7s,72684
-kfinance/client/meta_classes.py,sha256=TQh43b8r3IEc7Br-XVaZP7IDx75F3MnCcLcu7Fd91PI,21442
-kfinance/client/permission_models.py,sha256=G0so8ZOsD1YDsCM4he0z5R9M_shUbSRwD3hUDJdqZl0,635
+kfinance/client/meta_classes.py,sha256=O0qoz1ALveS25GgOVOfMjjsw0gl9gojpiLCfF-a8xsY,23622
+kfinance/client/permission_models.py,sha256=6pvoxRz5QGYvkSih_rrlBh4Yf5ltxTD1aeP5a6wCuRw,703
 kfinance/client/server_thread.py,sha256=jUnt1YGoYDkqqz1MbCwd44zJs1T_Z2BCgvj75bdtLgA,2574
 kfinance/client/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/client/models/currency_models.py,sha256=JfDZf-nATCyjThBw-Ky2BNvM-n2oHepBLIHMCIyCRUE,19201
@@ -24,7 +24,7 @@ kfinance/client/models/tests/test_decimal_with_unit.py,sha256=7WlmVXFOFNHFqwsvXQ
 kfinance/client/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/client/tests/test_batch_requests.py,sha256=KcE5rNJHBP27xaZOmwg8cVyUMZAAPt6jDiCeq94wUUk,11661
 kfinance/client/tests/test_client.py,sha256=GlK89ZOGL9bwrAUFUk8nua2ooKt0JYm7o_rpAfajFXA,4312
-kfinance/client/tests/test_fetch.py,sha256=rr1fAKjcIVW5QHvIAGlOhh54RzkUpF-SVsTRIIeGzPw,18835
+kfinance/client/tests/test_fetch.py,sha256=nFVQ3hHn7gqe7ecTYRviRxLuf06QyFZegfDLLOSUpR8,21569
 kfinance/client/tests/test_group_objects.py,sha256=wb7MEyGm-Qya3CXWM5Xz3kUhKFWdHT8FF3cQcjt1WxQ,1696
 kfinance/client/tests/test_objects.py,sha256=eAEy1kAHS6JQDoXVU5uSyTQpV099F3xFZsbvgspWMn8,42623
 kfinance/domains/README.md,sha256=ehD15VwLupdXbz5M7hHUI7Y-2SCGxaP5W7Q4NuMcN64,664
@@ -42,10 +42,10 @@ kfinance/domains/capitalizations/tests/test_capitalization_models.py,sha256=SSFx
 kfinance/domains/capitalizations/tests/test_capitalization_tools.py,sha256=LDjFiEEax2O65HQ65CY73J3y4RvuKjw5pqBO5imoUyY,4187
 kfinance/domains/companies/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/domains/companies/company_identifiers.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/domains/companies/company_models.py,sha256=bQdBEKCKZDI-Xqiz_K-RsqVUC7xamTvvyPjmKLPwXNI,4379
-kfinance/domains/companies/company_tools.py,sha256=iv4YlVFC485OPncwACj8lZybbUS9dDZ4Ezs3CB9QY4w,2786
+kfinance/domains/companies/company_models.py,sha256=ez87FsQlpYvAmd668sAgSbdgFum4PjMisN59J4vkqNo,4819
+kfinance/domains/companies/company_tools.py,sha256=wwhB98fg8mKOJp1kvN-KKFhKurLx6F6KX3BfLPJkWP0,8984
 kfinance/domains/companies/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/domains/companies/tests/test_company_tools.py,sha256=Gg0_Cep4hw_EcY50a_qKikWOwIX9nAi3eo_3rR1t398,1317
+kfinance/domains/companies/tests/test_company_tools.py,sha256=i9_P5mf92wZv_mcnWhK5L8BjbBLfsuBtxPLcgPOyHzE,4895
 kfinance/domains/competitors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/domains/competitors/competitor_models.py,sha256=HAEn2AzKZNusclsFzyAufpS-627RfRGL4Vw1AiT_Ek0,747
 kfinance/domains/competitors/competitor_tools.py,sha256=W_vRMng5UG1csJWDZKDxibrvXzUcwwnN9hw5cSg4EHI,2551
@@ -95,7 +95,7 @@ kfinance/integrations/tests/test_example_notebook.py,sha256=NrqYFn_XyOn0YlV9QYEn
 kfinance/integrations/tool_calling/README.md,sha256=TSk-AJddoEctzc0HXQvGNac2CckbnWxHcRDtEifSe1w,2029
 kfinance/integrations/tool_calling/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/integrations/tool_calling/all_tools.py,sha256=MbvAZX2yEyovGtBNcr5f6n2G_lV5Zc9nnSn7xgH3zjQ,2115
-kfinance/integrations/tool_calling/prompts.py,sha256=cLslVoubJyuh4W2-Eeok2dLOV4R7wUQGCu1HeQ1kNQo,1005
+kfinance/integrations/tool_calling/prompts.py,sha256=4qeW_VLLcxutUFuXnMKa0QD-_jq9qufo03BY-Slz-XU,1718
 kfinance/integrations/tool_calling/tool_calling_models.py,sha256=o1LGGwx8ikwEiZaHEALS4rvymF9O1Mp5dO9LcfFheUI,5856
 kfinance/integrations/tool_calling/static_tools/README.md,sha256=lWQWdLY1tkGxqE8o4f61gc-RCX0doaCnZM0GmcNO6Jo,97
 kfinance/integrations/tool_calling/static_tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -107,7 +107,7 @@ kfinance/integrations/tool_calling/static_tools/tests/test_get_n_quarters_ago.py
 kfinance/integrations/tool_calling/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 kfinance/integrations/tool_calling/tests/test_tool_calling_models.py,sha256=Ts1pvaYjq9BTR71dMZ73X__bQ7gQynPkQjy-9x2CuyQ,2605
 kfinance/models/permission_models.py,sha256=G0so8ZOsD1YDsCM4he0z5R9M_shUbSRwD3hUDJdqZl0,635
-kensho_kfinance-3.1.0.dist-info/METADATA,sha256=7xNJrtPsw2Z745G3XYikUwicoR7Iq8fmHEof3Wq0t_0,6202
-kensho_kfinance-3.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kensho_kfinance-3.1.0.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-3.1.0.dist-info/RECORD,,
+kensho_kfinance-3.2.0.dist-info/METADATA,sha256=2qQ3tv6IrgkR2Hv3n3VdzlN6J6iccWG-j9Sim4_wthc,6202
+kensho_kfinance-3.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kensho_kfinance-3.2.0.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
+kensho_kfinance-3.2.0.dist-info/RECORD,,

kfinance/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v3.2.0
+- Add Company Intelligence tools
+
+## v3.1.1
+- Update client base prompt
+
 ## v3.1.0
 - Use unified endpoint for company resolution
 

kfinance/client/fetch.py

@@ -17,7 +17,12 @@ from kfinance.domains.business_relationships.business_relationship_models import
     RelationshipResponse,
 )
 from kfinance.domains.capitalizations.capitalization_models import Capitalizations
-from kfinance.domains.companies.company_models import IdentificationTriple, UnifiedIdTripleResponse
+from kfinance.domains.companies.company_models import (
+    CompanyDescriptions,
+    CompanyOtherNames,
+    IdentificationTriple,
+    UnifiedIdTripleResponse,
+)
 from kfinance.domains.competitors.competitor_models import CompetitorResponse, CompetitorSource
 from kfinance.domains.earnings.earning_models import EarningsCallResp
 from kfinance.domains.line_items.line_item_models import LineItemResponse
@@ -602,6 +607,18 @@ class KFinanceApiClient:
         url = f"{self.url_base}transcript/{key_dev_id}"
         return self.fetch(url)
 
+    def fetch_company_descriptions(self, company_id: int) -> CompanyDescriptions:
+        """Get the short description (summary) and long description for a company"""
+        url = f"{self.url_base}info/{company_id}/descriptions"
+        result = self.fetch(url)
+        return CompanyDescriptions.model_validate(result)
+
+    def fetch_company_other_names(self, company_id: int) -> CompanyOtherNames:
+        """Get the alternate, historical, and native names for a company"""
+        url = f"{self.url_base}info/{company_id}/names"
+        result = self.fetch(url)
+        return CompanyOtherNames.model_validate(result)
+
     def fetch_competitors(
         self, company_id: int, competitor_source: CompetitorSource
     ) -> CompetitorResponse:

kfinance/client/meta_classes.py

@@ -13,6 +13,11 @@ from kfinance.domains.business_relationships.business_relationship_models import
     BusinessRelationshipType,
 )
 from kfinance.domains.capitalizations.capitalization_models import Capitalization
+from kfinance.domains.companies.company_models import (
+    CompanyDescriptions,
+    CompanyOtherNames,
+    NativeName,
+)
 from kfinance.domains.competitors.competitor_models import CompetitorSource
 from kfinance.domains.line_items.line_item_models import LINE_ITEMS
 from kfinance.domains.segments.segment_models import SegmentType
@@ -27,6 +32,11 @@ logger = logging.getLogger(__name__)
 class CompanyFunctionsMetaClass:
     kfinance_api_client: KFinanceApiClient
 
+    def __init__(self) -> None:
+        """Initialize the CompanyFunctionsMetaClass object"""
+        self._company_descriptions: CompanyDescriptions | None = None
+        self._company_other_names: CompanyOtherNames | None = None
+
     @property
     @abstractmethod
     def company_id(self) -> Any:
@@ -415,6 +425,51 @@ class CompanyFunctionsMetaClass:
             end_quarter=end_quarter,
         )
 
+    @property
+    def summary(self) -> str:
+        """Lazily fetch and return a company's summary"""
+        if not self._company_descriptions:
+            self._company_descriptions = self.kfinance_api_client.fetch_company_descriptions(
+                company_id=self.company_id
+            )
+        return self._company_descriptions.summary
+
+    @property
+    def description(self) -> str:
+        """Lazily fetch and return a company's description"""
+        if not self._company_descriptions:
+            self._company_descriptions = self.kfinance_api_client.fetch_company_descriptions(
+                company_id=self.company_id
+            )
+        return self._company_descriptions.description
+
+    @property
+    def alternate_names(self) -> list[str]:
+        """Lazily fetch and return a company's alternate names"""
+        if not self._company_other_names:
+            self._company_other_names = self.kfinance_api_client.fetch_company_other_names(
+                company_id=self.company_id
+            )
+        return self._company_other_names.alternate_names
+
+    @property
+    def historical_names(self) -> list[str]:
+        """Lazily fetch and return a company's historical names"""
+        if not self._company_other_names:
+            self._company_other_names = self.kfinance_api_client.fetch_company_other_names(
+                company_id=self.company_id
+            )
+        return self._company_other_names.historical_names
+
+    @property
+    def native_names(self) -> list[NativeName]:
+        """Lazily fetch and return a company's native names"""
+        if not self._company_other_names:
+            self._company_other_names = self.kfinance_api_client.fetch_company_other_names(
+                company_id=self.company_id
+            )
+        return self._company_other_names.native_names
+
     def competitors(
         self, competitor_source: CompetitorSource = CompetitorSource.all
     ) -> "Companies":

kfinance/client/permission_models.py

@@ -14,3 +14,4 @@ class Permission(StrEnum):
     StatementsPermission = "StatementsPermission"
     TranscriptsPermission = "TranscriptsPermission"
     PrivateCompanyFinancialsPermission = "PrivateCompanyFinancialsPermission"
+    CompanyIntelligencePermission = "CompanyIntelligencePermission"

kfinance/client/tests/test_fetch.py

@@ -13,7 +13,11 @@ from kfinance.domains.business_relationships.business_relationship_models import
     BusinessRelationshipType,
     RelationshipResponse,
 )
-from kfinance.domains.companies.company_models import CompanyIdAndName
+from kfinance.domains.companies.company_models import (
+    CompanyDescriptions,
+    CompanyIdAndName,
+    CompanyOtherNames,
+)
 
 
 def build_mock_api_client() -> KFinanceApiClient:
@@ -383,3 +387,75 @@ class TestFetchCompaniesFromBusinessRelationship:
             company_id=SPGI_COMPANY_ID, relationship_type=BusinessRelationshipType.supplier
         )
         assert resp == expected_result
+
+
+class TestFetchCompanyDescriptions:
+    def test_fetch_company_descriptions(self, requests_mock: Mocker, mock_client: Client) -> None:
+        """
+        GIVEN a request to fetch company descriptions
+        WHEN the api returns a response
+        THEN the response can successfully be parsed into a CompanyDescriptions object.
+        """
+
+        # Truncated from actual http response
+        http_resp = {
+            "summary": "S&P Global Inc., together... [summary]",
+            "description": "S&P Global Inc. (S&P Global), together... [description]",
+        }
+
+        expected_result = CompanyDescriptions(
+            summary="S&P Global Inc., together... [summary]",
+            description="S&P Global Inc. (S&P Global), together... [description]",
+        )
+
+        requests_mock.get(
+            url=f"{mock_client.kfinance_api_client.url_base}info/{SPGI_COMPANY_ID}/descriptions",
+            json=http_resp,
+        )
+
+        resp = mock_client.kfinance_api_client.fetch_company_descriptions(
+            company_id=SPGI_COMPANY_ID
+        )
+        assert resp == expected_result
+
+
+class TestFetchCompanyOtherNames:
+    def test_fetch_company_other_names(self, requests_mock: Mocker, mock_client: Client) -> None:
+        """
+        GIVEN a request to fetch a company's other names (alternate, historical, and native)
+        WHEN the api returns a response
+        THEN the response can be successfully parsed into a CompanyOtherNames object
+        """
+        alternate_names = ["S&P Global", "S&P Global, Inc.", "S&P"]
+        historical_names = [
+            "McGraw-Hill Publishing Company, Inc.",
+            "McGraw-Hill Book Company",
+            "McGraw Hill Financial, Inc.",
+            "The McGraw-Hill Companies, Inc.",
+        ]
+        native_names = [
+            {"name": "KLab Venture Partners 株式会社", "language": "Japanese"},
+            {"name": "株式会社ANOBAKA", "language": "Japanese"},
+            {"name": "株式会社KVP", "language": "Japanese"},
+        ]
+
+        http_resp = {
+            "alternate_names": alternate_names,
+            "historical_names": historical_names,
+            "native_names": native_names,
+        }
+
+        expected_resp = CompanyOtherNames(
+            alternate_names=alternate_names,
+            historical_names=historical_names,
+            native_names=native_names,
+        )
+
+        requests_mock.get(
+            url=f"{mock_client.kfinance_api_client.url_base}info/{SPGI_COMPANY_ID}/names",
+            json=http_resp,
+        )
+
+        resp = mock_client.kfinance_api_client.fetch_company_other_names(company_id=SPGI_COMPANY_ID)
+
+        assert resp == expected_resp

kfinance/domains/companies/company_models.py

@@ -118,3 +118,25 @@ class UnifiedIdTripleResponse(BaseModel):
                 f"{identifier} is a private company without a trading_item_id."
             )
             self.identifiers_to_id_triples.pop(identifier)
+
+
+class CompanyDescriptions(BaseModel):
+    """A company summary and description"""
+
+    summary: str
+    description: str
+
+
+class NativeName(BaseModel):
+    """A company's native name's name and language"""
+
+    name: str
+    language: str
+
+
+class CompanyOtherNames(BaseModel):
+    """A company's alternate, historical, and native names"""
+
+    alternate_names: list[str]
+    historical_names: list[str]
+    native_names: list[NativeName]

kfinance/domains/companies/company_tools.py

@@ -5,6 +5,7 @@ from pydantic import BaseModel
 
 from kfinance.client.batch_request_handling import Task, process_tasks_in_thread_pool_executor
 from kfinance.client.permission_models import Permission
+from kfinance.domains.companies.company_models import CompanyDescriptions, CompanyOtherNames
 from kfinance.integrations.tool_calling.tool_calling_models import (
     KfinanceTool,
     ToolArgsWithIdentifiers,
@@ -68,3 +69,130 @@ class GetInfoFromIdentifiers(KfinanceTool):
             results=info_responses, errors=list(id_triple_resp.errors.values())
         )
         return resp_model.model_dump(mode="json")
+
+
+class GetCompanyOtherNamesFromIdentifiersResp(ToolRespWithErrors):
+    results: dict[str, CompanyOtherNames]
+
+
+class GetCompanyOtherNamesFromIdentifiers(KfinanceTool):
+    name: str = "get_company_other_names_from_identifiers"
+    description: str = dedent("""
+        Given a list of identifiers, fetch the alternate, historical, and native names associated with each identifier. Alternate names are additional names a company might go by (for example, Hewlett-Packard Company also goes by the name HP). Historical names are previous names for the company if it has changed over time. Native names are primary non-Latin character native names for global companies, including languages such as Arabic, Russian, Greek, Japanese, etc. This also includes limited history on native name changes.
+
+        - When possible, pass multiple identifiers in a single call rather than making multiple calls.
+    """).strip()
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
+    accepted_permissions: set[Permission] | None = {Permission.CompanyIntelligencePermission}
+
+    def _run(
+        self,
+        identifiers: list[str],
+    ) -> dict:
+        api_client = self.kfinance_client.kfinance_api_client
+        id_triple_resp = api_client.unified_fetch_id_triples(identifiers=identifiers)
+        tasks = [
+            Task(
+                func=api_client.fetch_company_other_names,
+                kwargs=dict(company_id=id_triple.company_id),
+                result_key=identifier,
+            )
+            for identifier, id_triple in id_triple_resp.identifiers_to_id_triples.items()
+        ]
+        info_responses: dict[str, CompanyOtherNames] = process_tasks_in_thread_pool_executor(
+            api_client=api_client, tasks=tasks
+        )
+        resp_model = GetCompanyOtherNamesFromIdentifiersResp(
+            results=info_responses, errors=list(id_triple_resp.errors.values())
+        )
+        return resp_model.model_dump(mode="json")
+
+
+class GetCompanySummaryFromIdentifiersResp(ToolRespWithErrors):
+    results: dict[str, str]
+
+
+class GetCompanySummaryFromIdentifiers(KfinanceTool):
+    name: str = "get_company_summary_from_identifiers"
+    description: str = dedent("""
+        Get one paragraph summary/short descriptions of companies, including information about the company's primary business, products and services offered and their applications, business segment details, client/customer groups served, geographic markets served, distribution channels, strategic alliances/partnerships, founded/incorporated year, latest former name, and headquarters and additional offices."
+
+        - When possible, pass multiple identifiers in a single call rather than making multiple calls.
+    """).strip()
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
+    accepted_permissions: set[Permission] | None = {Permission.CompanyIntelligencePermission}
+
+    def _run(
+        self,
+        identifiers: list[str],
+    ) -> dict:
+        api_client = self.kfinance_client.kfinance_api_client
+        id_triple_resp = api_client.unified_fetch_id_triples(identifiers=identifiers)
+
+        tasks = [
+            Task(
+                func=api_client.fetch_company_descriptions,
+                kwargs=dict(company_id=id_triple.company_id),
+                result_key=identifier,
+            )
+            for identifier, id_triple in id_triple_resp.identifiers_to_id_triples.items()
+        ]
+        company_description_responses: dict[str, CompanyDescriptions] = (
+            process_tasks_in_thread_pool_executor(api_client=api_client, tasks=tasks)
+        )
+
+        # Extract only the summary field
+        summary_results = {
+            identifier: descriptions.summary
+            for identifier, descriptions in company_description_responses.items()
+        }
+
+        resp_model = GetCompanySummaryFromIdentifiersResp(
+            results=summary_results, errors=list(id_triple_resp.errors.values())
+        )
+        return resp_model.model_dump(mode="json")
+
+
+class GetCompanyDescriptionFromIdentifiersResp(ToolRespWithErrors):
+    results: dict[str, str]
+
+
+class GetCompanyDescriptionFromIdentifiers(KfinanceTool):
+    name: str = "get_company_description_from_identifiers"
+    description: str = dedent("""
+        Get detailed descriptions of companies, broken down into sections, which may include information about the company's Primary business, Segments (including Products and Services for each), Competition, Significant events, and History. Within the text, four spaces represent a new paragraph. Note that the description is divided into sections with headers, where each section has a new paragraph (four spaces) before and after the section header.
+
+        - When possible, pass multiple identifiers in a single call rather than making multiple calls.
+    """).strip()
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifiers
+    accepted_permissions: set[Permission] | None = {Permission.CompanyIntelligencePermission}
+
+    def _run(
+        self,
+        identifiers: list[str],
+    ) -> dict:
+        api_client = self.kfinance_client.kfinance_api_client
+        id_triple_resp = api_client.unified_fetch_id_triples(identifiers=identifiers)
+
+        tasks = [
+            Task(
+                func=api_client.fetch_company_descriptions,
+                kwargs=dict(company_id=id_triple.company_id),
+                result_key=identifier,
+            )
+            for identifier, id_triple in id_triple_resp.identifiers_to_id_triples.items()
+        ]
+        company_description_responses: dict[str, CompanyDescriptions] = (
+            process_tasks_in_thread_pool_executor(api_client=api_client, tasks=tasks)
+        )
+
+        # Extract only the description field
+        description_results = {
+            identifier: descriptions.description
+            for identifier, descriptions in company_description_responses.items()
+        }
+
+        resp_model = GetCompanyDescriptionFromIdentifiersResp(
+            results=description_results, errors=list(id_triple_resp.errors.values())
+        )
+        return resp_model.model_dump(mode="json")

kfinance/domains/companies/tests/test_company_tools.py

@@ -2,7 +2,12 @@ from requests_mock import Mocker
 
 from kfinance.client.kfinance import Client
 from kfinance.conftest import SPGI_COMPANY_ID
-from kfinance.domains.companies.company_tools import GetInfoFromIdentifiers
+from kfinance.domains.companies.company_tools import (
+    GetCompanyDescriptionFromIdentifiers,
+    GetCompanyOtherNamesFromIdentifiers,
+    GetCompanySummaryFromIdentifiers,
+    GetInfoFromIdentifiers,
+)
 from kfinance.integrations.tool_calling.tool_calling_models import ToolArgsWithIdentifiers
 
 
@@ -31,3 +36,90 @@ class TestGetInfoFromIdentifiers:
             ToolArgsWithIdentifiers(identifiers=["SPGI", "non-existent"]).model_dump(mode="json")
         )
         assert resp == expected_response
+
+
+class TestGetCompanyDescriptions:
+    description = "S&P Global Inc. (S&P Global), together... [description]"
+    summary = "S&P Global Inc., together... [summary]"
+    descriptions_data = {
+        "summary": summary,
+        "description": description,
+    }
+
+    def test_get_company_summary_from_identifier(self, mock_client: Client, requests_mock: Mocker):
+        """
+        GIVEN the GetCompanySummaryFromIdentifier tool
+        WHEN we request the company summary (short description) for SPGI
+        THEN we get back SPGI company's summary (short description)
+        """
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/info/{SPGI_COMPANY_ID}/descriptions",
+            # truncated from the original API response
+            json=self.descriptions_data,
+        )
+
+        tool = GetCompanySummaryFromIdentifiers(kfinance_client=mock_client)
+        args = ToolArgsWithIdentifiers(identifiers=["SPGI"])
+        response = tool.run(args.model_dump(mode="json"))
+        expected_response = {"results": {"SPGI": self.summary}}
+        assert response == expected_response
+
+    def test_get_company_description_from_identifier(
+        self, mock_client: Client, requests_mock: Mocker
+    ):
+        """
+        GIVEN the GetCompanyDescriptionFromIdentifier tool
+        WHEN we request the company description for SPGI
+        THEN we get back SPGI company's description
+        """
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/info/{SPGI_COMPANY_ID}/descriptions",
+            # truncated from the original API response
+            json=self.descriptions_data,
+        )
+
+        tool = GetCompanyDescriptionFromIdentifiers(kfinance_client=mock_client)
+        args = ToolArgsWithIdentifiers(identifiers=["SPGI"])
+        response = tool.run(args.model_dump(mode="json"))
+        expected_response = {"results": {"SPGI": self.description}}
+        assert response == expected_response
+
+
+class TestGetCompanyOtherNames:
+    alternate_names = ["S&P Global", "S&P Global, Inc.", "S&P"]
+    historical_names = [
+        "McGraw-Hill Publishing Company, Inc.",
+        "McGraw-Hill Book Company",
+        "McGraw Hill Financial, Inc.",
+        "The McGraw-Hill Companies, Inc.",
+    ]
+    native_names = [
+        {"name": "KLab Venture Partners 株式会社", "language": "Japanese"},
+        {"name": "株式会社ANOBAKA", "language": "Japanese"},
+        {"name": "株式会社KVP", "language": "Japanese"},
+    ]
+
+    company_other_names_info = {
+        "alternate_names": alternate_names,
+        "historical_names": historical_names,
+        "native_names": native_names,
+    }
+
+    def test_get_company_other_names_from_identifier(
+        self, mock_client: Client, requests_mock: Mocker
+    ):
+        """
+        GIVEN the GetCompanyOtherNamesFromIdentifier tool
+        WHEN we request the other names for SPGI
+        THEN we get back SPGI's other names
+        """
+        requests_mock.get(
+            url=f"https://kfinance.kensho.com/api/v1/info/{SPGI_COMPANY_ID}/names",
+            json=self.company_other_names_info,
+        )
+
+        tool = GetCompanyOtherNamesFromIdentifiers(kfinance_client=mock_client)
+        args = ToolArgsWithIdentifiers(identifiers=["SPGI"])
+        response = tool.run(args.model_dump(mode="json"))
+        expected_response = {"results": {"SPGI": self.company_other_names_info}}
+        assert response == expected_response

kfinance/integrations/tool_calling/prompts.py

@@ -1,17 +1,24 @@
-from kfinance.domains.line_items.line_item_tools import GetFinancialLineItemFromIdentifiers
-from kfinance.integrations.tool_calling.static_tools.get_latest import GetLatest
+BASE_PROMPT = f"""
+You are an LLM designed to help financial analysts. Use the supplied tools to assist the user.
+CRITICAL RULES FOR TOOL USAGE
 
+Time Handling:
+- Always select the most recent complete period when the user does not specify a time.
+- Use the get_latest function to determine the latest annual year, latest completed quarter, and current date.
+- For annual data, use the latest completed year. For quarterly data, use the latest completed quarter and year.
+- If the user specifies a time period (year, quarter, or date range), use it exactly as provided.
+- For relative time references (such as "3 quarters ago"), always use get_n_quarters_ago to resolve the correct year and quarter.
+- For price or history tools, if the user does not specify a date range, use the most recent period as determined by get_latest.
+- "Last year" or "last quarter" refers to the previous completed period from the current date.
+- For quarterly data requests without specific quarters, assume the most recent completed quarter.
 
-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.
+Tool Selection:
+- Use get_latest before any other tool when dates are ambiguous, unspecified, or when you need to determine the most recent period.
+- Use get_n_quarters_ago for relative quarter references such as "3 quarters ago".
+- Always make tool calls when financial data is requested—never skip them.
+- For identifier resolution, use the exact identifiers provided by the user. Do not add or modify suffixes unless explicitly required.
 
-    - 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 `{GetFinancialLineItemFromIdentifiers.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.
-    """
+Identifier Handling:
+- Use the exact identifiers provided by the user. Do not add or modify suffixes such as ".PA" or ".DE" unless the user specifies the exchange or market.
+- Never invent or guess identifiers. Only use those explicitly provided.
+"""

kfinance/version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '3.1.0'
-__version_tuple__ = version_tuple = (3, 1, 0)
+__version__ = version = '3.2.0'
+__version_tuple__ = version_tuple = (3, 2, 0)