kensho-kfinance 1.2.2__py3-none-any.whl → 2.0.1__py3-none-any.whl

kfinance/tool_calling/get_financial_statement_from_identifier.py

@@ -0,0 +1,41 @@
+from typing import Literal, Type
+
+from pydantic import BaseModel, Field
+
+from kfinance.constants import PeriodType, StatementType
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetFinancialStatementFromIdentifierArgs(ToolArgsWithIdentifier):
+    # no description because the description for enum fields comes from the enum docstring.
+    statement: StatementType
+    period_type: PeriodType | None = Field(default=None, description="The period type")
+    start_year: int | None = Field(default=None, description="The starting year for the data range")
+    end_year: int | None = Field(default=None, description="The ending year for the data range")
+    start_quarter: Literal[1, 2, 3, 4] | None = Field(default=None, description="Starting quarter")
+    end_quarter: Literal[1, 2, 3, 4] | None = Field(default=None, description="Ending quarter")
+
+
+class GetFinancialStatementFromIdentifier(KfinanceTool):
+    name: str = "get_financial_statement_from_identifier"
+    description: str = "Get the financial statement associated with an identifier."
+    args_schema: Type[BaseModel] = GetFinancialStatementFromIdentifierArgs
+
+    def _run(
+        self,
+        identifier: str,
+        statement: StatementType,
+        period_type: PeriodType | None = None,
+        start_year: int | None = None,
+        end_year: int | None = None,
+        start_quarter: Literal[1, 2, 3, 4] | None = None,
+        end_quarter: Literal[1, 2, 3, 4] | None = None,
+    ) -> str:
+        ticker = self.kfinance_client.ticker(identifier)
+        return getattr(ticker, statement.value)(
+            period_type=period_type,
+            start_year=start_year,
+            end_year=end_year,
+            start_quarter=start_quarter,
+            end_quarter=end_quarter,
+        ).to_markdown()

kfinance/tool_calling/get_history_metadata_from_identifier.py

@@ -0,0 +1,15 @@
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.constants import HistoryMetadata
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetHistoryMetadataFromIdentifier(KfinanceTool):
+    name: str = "get_history_metadata_from_identifier"
+    description: str = "Get the history metadata associated with an identifier. History metadata includes currency, symbol, exchange name, instrument type, and first trade date."
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+
+    def _run(self, identifier: str) -> HistoryMetadata:
+        return self.kfinance_client.ticker(identifier).history_metadata

kfinance/tool_calling/get_info_from_identifier.py

@@ -0,0 +1,14 @@
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetInfoFromIdentifier(KfinanceTool):
+    name: str = "get_info_from_identifier"
+    description: str = "Get the information associated with an identifier. Info includes company name, status, type, simple industry, number of employees, founding date, webpage, HQ address, HQ city, HQ zip code, HQ state, HQ country, and HQ country iso code."
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+
+    def _run(self, identifier: str) -> str:
+        return str(self.kfinance_client.ticker(identifier).info)

kfinance/tool_calling/get_isin_from_ticker.py

@@ -0,0 +1,18 @@
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+from kfinance.tool_calling.shared_models import KfinanceTool
+
+
+class GetIsinFromTickerArgs(BaseModel):
+    ticker_str: str = Field(description="The ticker")
+
+
+class GetIsinFromTicker(KfinanceTool):
+    name: str = "get_isin_from_ticker"
+    description: str = "Get the ISIN associated with a ticker."
+    args_schema: Type[BaseModel] = GetIsinFromTickerArgs
+
+    def _run(self, ticker_str: str) -> str:
+        return self.kfinance_client.ticker(ticker_str).isin

kfinance/tool_calling/get_latest.py

@@ -0,0 +1,21 @@
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+from kfinance.constants import LatestPeriods
+from kfinance.tool_calling.shared_models import KfinanceTool
+
+
+class GetLatestArgs(BaseModel):
+    use_local_timezone: bool = Field(
+        description="Whether to use the local timezone of the user", default=True
+    )
+
+
+class GetLatest(KfinanceTool):
+    name: str = "get_latest"
+    description: str = "Get the latest annual reporting year, latest quarterly reporting quarter and year, and current date."
+    args_schema: Type[BaseModel] = GetLatestArgs
+
+    def _run(self, use_local_timezone: bool = True) -> LatestPeriods:
+        return self.kfinance_client.get_latest(use_local_timezone=use_local_timezone)

kfinance/tool_calling/get_n_quarters_ago.py

@@ -0,0 +1,21 @@
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+from kfinance.constants import YearAndQuarter
+from kfinance.tool_calling.shared_models import KfinanceTool
+
+
+class GetNQuartersAgoArgs(BaseModel):
+    n: int = Field(description="Number of quarters before the current quarter")
+
+
+class GetNQuartersAgo(KfinanceTool):
+    name: str = "get_n_quarters_ago"
+    description: str = (
+        "Get the year and quarter corresponding to [n] quarters before the current quarter."
+    )
+    args_schema: Type[BaseModel] = GetNQuartersAgoArgs
+
+    def _run(self, n: int) -> YearAndQuarter:
+        return self.kfinance_client.get_n_quarters_ago(n)

kfinance/tool_calling/get_prices_from_identifier.py

@@ -0,0 +1,44 @@
+from datetime import date
+from typing import Type
+
+from pydantic import BaseModel, Field
+
+from kfinance.constants import Periodicity
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetPricesFromIdentifierArgs(ToolArgsWithIdentifier):
+    start_date: date | None = Field(
+        description="The start date for historical price retrieval", default=None
+    )
+    end_date: date | None = Field(
+        description="The end date for historical price retrieval", default=None
+    )
+    # no description because the description for enum fields comes from the enum docstring.
+    periodicity: Periodicity = Field(default=Periodicity.day)
+    adjusted: bool = Field(
+        description="Whether to retrieve adjusted prices that account for corporate actions such as dividends and splits.",
+        default=True,
+    )
+
+
+class GetPricesFromIdentifier(KfinanceTool):
+    name: str = "get_prices_from_identifier"
+    description: str = "Get the historical open, high, low, and close prices, and volume of an identifier between inclusive start_date and inclusive end date. When requesting the most recent values, leave start_date and end_date empty."
+    args_schema: Type[BaseModel] = GetPricesFromIdentifierArgs
+
+    def _run(
+        self,
+        identifier: str,
+        start_date: date | None = None,
+        end_date: date | None = None,
+        periodicity: Periodicity = Periodicity.day,
+        adjusted: bool = True,
+    ) -> str:
+        ticker = self.kfinance_client.ticker(identifier)
+        return ticker.history(
+            start_date=start_date.isoformat() if start_date else None,
+            end_date=end_date.isoformat() if end_date else None,
+            periodicity=periodicity,
+            adjusted=adjusted,
+        ).to_markdown()

kfinance/tool_calling/get_security_id_from_identifier.py

@@ -0,0 +1,14 @@
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetSecurityIdFromIdentifier(KfinanceTool):
+    name: str = "get_security_id_from_identifier"
+    description: str = "Get the security id associated with an identifier."
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+
+    def _run(self, identifier: str) -> int:
+        return self.kfinance_client.ticker(identifier).security_id

kfinance/tool_calling/get_trading_item_id_from_identifier.py

@@ -0,0 +1,14 @@
+from typing import Type
+
+from pydantic import BaseModel
+
+from kfinance.tool_calling.shared_models import KfinanceTool, ToolArgsWithIdentifier
+
+
+class GetTradingItemIdFromIdentifier(KfinanceTool):
+    name: str = "get_trading_item_id_from_identifier"
+    description: str = "Get the trading item id associated with an identifier."
+    args_schema: Type[BaseModel] = ToolArgsWithIdentifier
+
+    def _run(self, identifier: str) -> int:
+        return self.kfinance_client.ticker(identifier).trading_item_id

kfinance/tool_calling/shared_models.py

@@ -0,0 +1,53 @@
+from typing import Any, Type
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, ConfigDict, Field
+
+from kfinance.kfinance import Client
+
+
+class KfinanceTool(BaseTool):
+    """KfinanceTool is a langchain base tool with a kfinance Client.
+
+    The kfinance_client attribute allows us to make kfinance calls without needing
+    the client to get passed in as a param during invocations.
+    """
+
+    kfinance_client: Client
+    args_schema: Type[BaseModel]
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    def run_without_langchain(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute a Kfinance tool without langchain.
+
+        Langchain converts json input params into the pydantic args_schema, which means that
+        strings get turned into enums, dates, or datetimes where necessary.
+        When executing a tool without langchain, we have to handle this
+        conversion ourselves.
+        """
+        args_model = self.args_schema.model_validate(kwargs)
+        args_dict = args_model.model_dump()
+        # Only pass params included in the LLM generated kwargs.
+        # This means that we don't use defaults defined by the pydantic models and instead use
+        # the defaults defined in the `_run` function.
+        # This behavior matches the langchain handling. See
+        # https://github.com/langchain-ai/langchain/blob/ca39680d2ab0d786bc035930778a5787e7bb5e01/libs/core/langchain_core/tools/base.py#L595-L597
+        args_dict = {k: v for k, v in args_dict.items() if k in kwargs}
+        return self._run(**args_dict)
+
+    def _run(self, *args: Any, **kwargs: Any) -> Any:
+        """The code to execute the tool"""
+        ...
+
+
+class ToolArgsWithIdentifier(BaseModel):
+    """Tool argument with an identifier.
+
+    All tools using an identifier should subclass this model to ensure that the description
+    of identifier is always the same.
+    """
+
+    identifier: str = Field(
+        description="The identifier, which can be a ticker symbol, ISIN, or CUSIP"
+    )

kfinance/version.py

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

kensho_kfinance-1.2.2.dist-info/RECORD

@@ -1,23 +0,0 @@
-kensho_kfinance-1.2.2.dist-info/licenses/AUTHORS.md,sha256=0h9ClbI0pu1oKj1M28ROUsaxrbZg-6ukQGl6X4y9noI,68
-kensho_kfinance-1.2.2.dist-info/licenses/LICENSE,sha256=bsY4blvSgq6o0FMQ3RXa2NCgco--nHCCchLXzxr6kms,83
-kfinance/CHANGELOG.md,sha256=2s4rnko1N6MDMK38Bn0OUvhHSygSGb2XGQgM1kKEUtc,580
-kfinance/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/batch_request_handling.py,sha256=s0uXRY4CC-GnShI0i8PLPgLddRdqLyQ8jnqDKdmaZzs,5531
-kfinance/constants.py,sha256=uopijPmpAU97l9OA_mllG2UvGHP9-zeq0UqkA7Yrk-w,47553
-kfinance/fetch.py,sha256=XrkOC_5RsiI_ycRiaBbhrs1ND-gqBOknWmfIOpDSLRI,20114
-kfinance/kfinance.py,sha256=PGJzfq_AdX7IZsY4BpNuni90R6SGa6nrNLicJi_QEec,45643
-kfinance/llm_tools.py,sha256=t3i-5y34AzeFujjwOJVWY7OFI5aOAWG8rt-9KgR_0-E,30683
-kfinance/meta_classes.py,sha256=ryncusGDe48gG31a-Ldx1ApJ-ZPRFJvjC18jry7TOVE,15980
-kfinance/prompt.py,sha256=PtVB8c_FcSlVdyGgByAnIFGzuUuBaEjciCqnBJl1hSQ,25133
-kfinance/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/server_thread.py,sha256=jUnt1YGoYDkqqz1MbCwd44zJs1T_Z2BCgvj75bdtLgA,2574
-kfinance/tool_schemas.py,sha256=JrFSbb6i2lOQaI24QqnhGhZ3e-pWLhjNqZloY9WGlnM,5643
-kfinance/version.py,sha256=o0zEAUXpMoJZCULVYplCdjcZuIQ-3sIIZKyfNu_loQE,511
-kfinance/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-kfinance/tests/test_batch_requests.py,sha256=NsldoZqjjQpv0QKM2th80F1nru2tIF4LJeXU-RamQvA,9836
-kfinance/tests/test_fetch.py,sha256=6au-TrsLbLoyvgd1vZSMlxOtXrau8ptM4tcS7vPXIzA,12088
-kfinance/tests/test_objects.py,sha256=egXkhfoK2MepZdXtrBxzWxWni7f-zVCefUbnyDnWDOE,22554
-kensho_kfinance-1.2.2.dist-info/METADATA,sha256=1OzzFZCWvGJEYcKJGURgJjgZ_awy66sdEKqxSpfpuGE,2935
-kensho_kfinance-1.2.2.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-kensho_kfinance-1.2.2.dist-info/top_level.txt,sha256=kT_kNwVhfQoOAecY8W7uYah5xaHMoHoAdBIvXh6DaKM,9
-kensho_kfinance-1.2.2.dist-info/RECORD,,