Skip to content

"Vibe-Trading: Your Personal Trading Agent"

7.4 KB
Raw Blame
"""Read-only fundamental panel facade backed by the loader layer."""

from __future__ import annotations

import json
import logging
import math
from typing import Any

import pandas as pd

from src.agent.tools import BaseTool

logger = logging.getLogger(__name__)

_VALID_FREQS = ("annual", "quarterly", "ttm")
# Mirrors what ``load_fundamental_panel`` actually accepts. Advertising
# ``eastmoney``/``tushare`` here made the agent pick a source the loader rejects
# at runtime.
_VALID_SOURCES = ("auto", "sec")


def _error(message: str) -> str:
    """Build the failure envelope as a JSON string.

    Args:
        message: Human-readable error description.

    Returns:
        A strict JSON ``{"ok": false, "error": ...}`` string.
    """
    return json.dumps({"ok": False, "error": message}, ensure_ascii=False)


def _json_safe(value: Any) -> Any:
    """Convert provider/scalar values to strict-JSON-safe values."""
    if hasattr(value, "isoformat"):
        return value.isoformat()
    if hasattr(value, "item"):
        value = value.item()
    if isinstance(value, float) and not math.isfinite(value):
        return None
    return value


def _frame_records(df: pd.DataFrame) -> list[dict[str, Any]]:
    """Serialize a wide fundamental panel DataFrame as JSON-safe records.

    Args:
        df: Wide DataFrame indexed by date with symbols as columns.

    Returns:
        Row records matching the existing market-data JSON style.
    """
    frame = df.copy()
    frame.index.name = frame.index.name or "date"
    records = frame.reset_index().to_dict(orient="records")
    for row in records:
        for key, value in row.items():
            row[key] = _json_safe(value)
    return records


class GetFundamentalsTool(BaseTool):
    """Fetch PIT-aligned fundamental fields as daily wide panels."""

    name = "get_fundamentals"
    description = (
        "Fetch PIT-safe fundamental fields as daily wide panels aligned by filed "
        "date. Returns {field: date x symbol records}. Fields use the unified "
        "fundamental schema, e.g. roe, gross_profitability, net_income, "
        "shares_diluted. Default freq is ttm and PIT mode is on."
    )
    parameters = {
        "type": "object",
        "properties": {
            "symbols": {
                "type": "array",
                "items": {"type": "string"},
                "description": (
                    "US tickers, with or without a .US suffix, e.g. "
                    '["AAPL", "MSFT.US", "BRK-B"]. This tool is US-only: it '
                    "reads SEC XBRL, so A-share and HK symbols are rejected."
                ),
            },
            "fields": {
                "type": "array",
                "items": {"type": "string"},
                "description": 'Unified schema fields, e.g. ["roe", "net_income"].',
            },
            "start": {
                "type": "string",
                "description": "Start date in YYYY-MM-DD format.",
            },
            "end": {
                "type": "string",
                "description": "End date in YYYY-MM-DD format.",
            },
            "freq": {
                "type": "string",
                "enum": list(_VALID_FREQS),
                "description": "Reporting cadence: annual, quarterly, or ttm.",
                "default": "ttm",
            },
            "pit": {
                "type": "boolean",
                "description": "Use point-in-time filed-date alignment.",
                "default": True,
            },
            "source": {
                "type": "string",
                "enum": list(_VALID_SOURCES),
                "description": "Fundamental source router.",
                "default": "auto",
            },
            "index": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Optional trading-date index to align to.",
            },
        },
        "required": ["symbols", "fields", "start", "end"],
    }
    repeatable = True

    def execute(self, **kwargs: Any) -> str:
        """Validate inputs, call the loader, and return a JSON envelope.

        Args:
            **kwargs: ``symbols``, ``fields``, ``start``, ``end``, optional
                ``freq``, ``pit``, ``source``, and ``index``.

        Returns:
            Strict JSON envelope with serialized field panels or an error.
        """
        symbols = kwargs.get("symbols")
        if not isinstance(symbols, list) or not symbols:
            return _error("symbols must be a non-empty list of strings")
        if any(not isinstance(symbol, str) or not symbol.strip() for symbol in symbols):
            return _error("every symbol must be a non-empty string")
        symbols = [symbol.strip() for symbol in symbols]

        fields = kwargs.get("fields")
        if not isinstance(fields, list) or not fields:
            return _error("fields must be a non-empty list of strings")
        if any(not isinstance(field, str) or not field.strip() for field in fields):
            return _error("every field must be a non-empty string")
        fields = [field.strip() for field in fields]

        start = kwargs.get("start")
        end = kwargs.get("end")
        if not isinstance(start, str) or not start.strip():
            return _error("start must be a non-empty YYYY-MM-DD string")
        if not isinstance(end, str) or not end.strip():
            return _error("end must be a non-empty YYYY-MM-DD string")

        freq = kwargs.get("freq", "ttm")
        if freq not in _VALID_FREQS:
            return _error(f"freq must be one of {list(_VALID_FREQS)}")

        pit = kwargs.get("pit", True)
        if not isinstance(pit, bool):
            return _error("pit must be a boolean")

        source = kwargs.get("source", "auto")
        if source not in _VALID_SOURCES:
            return _error(f"source must be one of {list(_VALID_SOURCES)}")

        index_arg = kwargs.get("index")
        if index_arg is None or isinstance(index_arg, pd.DatetimeIndex):
            index = index_arg
        elif isinstance(index_arg, list):
            index = pd.DatetimeIndex(index_arg)
        else:
            return _error("index must be a list of date strings or a DatetimeIndex")

        try:
            from backtest.loaders.fundamentals_loader import load_fundamental_panel

            panel = load_fundamental_panel(
                symbols=symbols,
                fields=fields,
                start=start.strip(),
                end=end.strip(),
                freq=freq,
                pit=pit,
                source=source,
                index=index,
            )
            data: dict[str, list[dict[str, Any]]] = {}
            for field, frame in panel.items():
                if not isinstance(frame, pd.DataFrame):
                    raise TypeError(
                        f"loader returned {type(frame).__name__} for field {field!r}, expected DataFrame"
                    )
                data[str(field)] = _frame_records(frame)
        except Exception as exc:  # noqa: BLE001 - tool facade must envelope failures
            logger.warning("get_fundamentals failed: %s", exc)
            return _error(str(exc))

        envelope = {
            "ok": True,
            "source": source,
            "freq": freq,
            "pit": pit,
            "symbols": symbols,
            "fields": fields,
            "data": data,
        }
        return json.dumps(envelope, ensure_ascii=False, indent=2, allow_nan=False)