Skip to content

"Vibe-Trading: Your Personal Trading Agent"

18.8 KB
Raw Blame
"""Agent tool for client-cash-flow-aware portfolio performance.

Read-only. It reports the time-weighted, Modified Dietz, and money-weighted
returns of an account whose owner moved money in and out mid-period, which the
backtest metric path cannot express because it is funded by a single scalar.
No order path exists here and none may be added: this is a research surface.
"""

from __future__ import annotations

import json
import math
from datetime import date
from typing import Any

from src.agent.tools import BaseTool
from src.tools._arguments import boolean_argument
from src.entities.cashflow import CashFlow, CashFlowSeries
from src.entities.ingest import load_cashflows
from src.quantlib.performance import (
    DEFAULT_EXTERNAL_KINDS,
    DEFAULT_INTERNAL_KINDS,
    FLOW_TIMING_END,
    FLOW_TIMING_START,
    UnsolvableRateError,
    modified_dietz_return,
    money_weighted_return,
    time_weighted_return,
)

#: Upper bound on inline records, so one tool call cannot blow the context
#: window. Larger histories belong in a file and go through ``flows_path``.
_MAX_VALUATIONS = 4000
_MAX_INLINE_FLOWS = 4000

#: Decimal places used for every number in the envelope. Six is enough to carry
#: a return to a hundredth of a basis point without emitting float noise.
_ROUNDING = 6


class CashFlowPerformanceTool(BaseTool):
    """Report TWR, Modified Dietz, and money-weighted return for a client account."""

    name = "cashflow_performance"
    description = (
        "Measure the return of an account that received client contributions "
        "or paid out withdrawals mid-period. Takes a dated valuation series "
        "plus irregular cash flows (inline records or a CSV path) and returns "
        "the true time-weighted return (manager skill, immune to flow timing), "
        "the Modified Dietz day-weighted approximation, and the money-weighted "
        "XIRR (client experience). External flows are contributions, capital "
        "calls, subscriptions, transfers, distributions, redemptions and "
        "withdrawals; dividends, coupons, interest and fees are internal and "
        "already inside the valuations. Research only; places no orders."
    )
    repeatable = True
    is_readonly = True
    parameters = {
        "type": "object",
        "properties": {
            "valuations": {
                "type": "array",
                "minItems": 2,
                "maxItems": _MAX_VALUATIONS,
                "description": (
                    "Portfolio value on each valuation date, earliest first. "
                    "Two entries give a single-period answer; add interim "
                    "marks to make the time-weighted return exact."
                ),
                "items": {
                    "type": "object",
                    "properties": {
                        "date": {
                            "type": "string",
                            "description": "ISO-8601 date, e.g. 2024-06-30.",
                        },
                        "value": {"type": "number"},
                    },
                    "required": ["date", "value"],
                },
            },
            "flows": {
                "type": "array",
                "maxItems": _MAX_INLINE_FLOWS,
                "description": (
                    "Inline cash flows. Amounts are from the client's point of "
                    "view: a contribution is NEGATIVE (cash leaves the client) "
                    "and a distribution is POSITIVE. A transfer into the "
                    "portfolio is NEGATIVE; a transfer out is POSITIVE. "
                    "Mutually exclusive with flows_path."
                ),
                "items": {
                    "type": "object",
                    "properties": {
                        "date": {"type": "string"},
                        "amount": {"type": "number"},
                        "kind": {
                            "type": "string",
                            "description": (
                                "e.g. contribution, withdrawal, distribution, "
                                "capital_call, dividend."
                            ),
                        },
                        "currency": {
                            "type": "string",
                            "description": "Overrides the top-level currency.",
                        },
                    },
                    "required": ["date", "amount", "kind"],
                },
            },
            "flows_path": {
                "type": "string",
                "description": (
                    "Path to a delimited cash-flow file (.csv/.tsv/.txt). "
                    "Mutually exclusive with flows."
                ),
            },
            "currency": {
                "type": "string",
                "description": (
                    "Reporting currency. Required for inline flows that do not "
                    "carry their own, and for a file with no currency column."
                ),
            },
            "flows_default_kind": {
                "type": "string",
                "description": "Kind for file rows whose kind column is absent or blank.",
            },
            "flows_date_format": {
                "type": "string",
                "description": "strptime format for the file's date column, if not ISO-8601.",
            },
            "flows_columns": {
                "type": "object",
                "description": (
                    "Map canonical field to file column name, e.g. "
                    '{"date": "Payment Date", "amount": "Net"}.'
                ),
                "additionalProperties": {"type": "string"},
            },
            "flows_invert_sign": {
                "type": "boolean",
                "default": False,
                "description": (
                    "Negate every file amount, for exports that report "
                    "contributions as positive."
                ),
            },
            "flow_timing": {
                "type": "string",
                "enum": [FLOW_TIMING_END, FLOW_TIMING_START],
                "default": FLOW_TIMING_END,
                "description": (
                    "Whether a flow dated on a valuation date settles after "
                    "that valuation ('end') or before the next interval "
                    "('start'). Affects the time-weighted return only."
                ),
            },
            "external_kinds": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Override the default set of boundary-crossing kinds.",
            },
            "internal_kinds": {
                "type": "array",
                "items": {"type": "string"},
                "description": "Override the default set of inside-the-portfolio kinds.",
            },
        },
        "required": ["valuations"],
    }

    def execute(self, **kwargs: Any) -> str:
        """Compute the three returns and package them in one envelope.

        Args:
            **kwargs: Inputs described by :attr:`parameters`.

        Returns:
            A JSON envelope with ``status``, ``inputs``, ``summary``,
            ``sub_periods``, per-measure detail, ``notes`` and ``limitations``.
            Invalid input returns a JSON error envelope; it never raises and
            never returns ``None``.
        """
        notes: list[str] = []
        try:
            valuations = _coerce_valuations(kwargs.get("valuations"))
            series = _resolve_flows(kwargs)
            flow_timing = _coerce_flow_timing(kwargs.get("flow_timing"))
            external_kinds = _coerce_kinds(kwargs.get("external_kinds"), "external_kinds")
            internal_kinds = _coerce_kinds(kwargs.get("internal_kinds"), "internal_kinds")

            twr = time_weighted_return(
                valuations,
                series,
                flow_timing=flow_timing,
                external_kinds=external_kinds,
                internal_kinds=internal_kinds,
            )
            dietz = modified_dietz_return(
                valuations,
                series,
                external_kinds=external_kinds,
                internal_kinds=internal_kinds,
            )
        except (KeyError, OSError, TypeError, ValueError) as exc:
            return _error(str(exc))

        try:
            mwr = money_weighted_return(
                valuations,
                series,
                external_kinds=external_kinds,
                internal_kinds=internal_kinds,
            )
        except UnsolvableRateError as exc:
            # A one-directional stream has no IRR. That is a property of the
            # account, not a failure, so the other two measures still ship.
            mwr = None
            notes.append(f"money-weighted return not reported: {exc}")

        payload = {
            "status": "ok",
            "tool": self.name,
            "inputs": {
                "valuation_count": len(valuations),
                "flow_count": len(series) if series is not None else 0,
                "flow_source": (
                    "flows_path"
                    if kwargs.get("flows_path")
                    else "inline" if kwargs.get("flows") else "none"
                ),
                "flow_timing": flow_timing,
                "currency": series.currency if series is not None else kwargs.get("currency"),
                "external_kinds": sorted(external_kinds or DEFAULT_EXTERNAL_KINDS),
                "internal_kinds": sorted(internal_kinds or DEFAULT_INTERNAL_KINDS),
            },
            "summary": {
                "start_date": twr.start_date.isoformat(),
                "end_date": twr.end_date.isoformat(),
                "start_value": _rounded(twr.start_value),
                "end_value": _rounded(twr.end_value),
                "net_external_flow": _rounded(twr.net_external_flow),
                "time_weighted_return": _rounded(twr.total_return),
                "time_weighted_annualized": _rounded_or_none(twr.annualized_return),
                "modified_dietz_return": _rounded(dietz.total_return),
                "modified_dietz_annualized": _rounded_or_none(dietz.annualized_return),
                "money_weighted_return_annualized": (
                    None if mwr is None else _rounded(mwr.annualized_return)
                ),
                "money_weighted_return_period": (
                    None if mwr is None else _rounded(mwr.period_return)
                ),
            },
            "sub_periods": [
                {
                    "start": period.start.isoformat(),
                    "end": period.end.isoformat(),
                    "start_value": _rounded(period.start_value),
                    "end_value": _rounded(period.end_value),
                    "external_flow": _rounded(period.external_flow),
                    "return": _rounded(period.period_return),
                }
                for period in twr.sub_periods
            ],
            "modified_dietz": {
                "net_external_flow": _rounded(dietz.net_external_flow),
                "weighted_external_flow": _rounded(dietz.weighted_external_flow),
                "average_capital": _rounded(dietz.average_capital),
                "flow_weights": [
                    {
                        "date": when.isoformat(),
                        "amount": _rounded(amount),
                        "weight": _rounded(weight),
                    }
                    for when, amount, weight in dietz.flow_weights
                ],
            },
            "money_weighted": (
                None
                if mwr is None
                else {
                    "annualized_return": _rounded(mwr.annualized_return),
                    "period_return": _rounded(mwr.period_return),
                    "years": _rounded(mwr.years),
                    "solver_iterations": mwr.iterations,
                }
            ),
            "notes": notes,
            "limitations": [
                "Flow amounts are holder-perspective: a contribution is negative.",
                "Only contributions, withdrawals and transfers are treated as "
                "external; dividends, coupons and fees are assumed already "
                "inside the valuation series.",
                "Modified Dietz is a money-weighted approximation, not a "
                "cheaper time-weighted return.",
                "Returns are gross of any fee not already reflected in the "
                "valuations, and carry no tax or currency translation.",
            ],
        }
        return json.dumps(payload, ensure_ascii=False, allow_nan=False)


def _coerce_valuations(raw: Any) -> list[tuple[date, float]]:
    """Parse the raw valuation array into ``(date, value)`` pairs.

    Args:
        raw: Value supplied for the ``valuations`` parameter.

    Returns:
        Pairs in the order supplied; the library sorts and validates them.

    Raises:
        ValueError: If the array is missing, wrongly shaped, over the size cap,
            or an entry lacks a usable date or value.
    """
    if not isinstance(raw, list) or len(raw) < 2:
        raise ValueError("valuations must be an array of at least two {date, value} objects")
    if len(raw) > _MAX_VALUATIONS:
        raise ValueError(f"valuations may contain at most {_MAX_VALUATIONS} entries")

    pairs: list[tuple[date, float]] = []
    for index, item in enumerate(raw):
        if not isinstance(item, dict):
            raise ValueError(f"valuations[{index}] must be an object with date and value")
        if "date" not in item or "value" not in item:
            raise ValueError(f"valuations[{index}] needs both 'date' and 'value'")
        try:
            value = float(item["value"])
        except (TypeError, ValueError) as exc:
            raise ValueError(f"valuations[{index}].value must be numeric") from exc
        if not math.isfinite(value):
            raise ValueError(f"valuations[{index}].value must be finite")
        pairs.append((item["date"], value))
    return pairs


def _resolve_flows(kwargs: dict[str, Any]) -> CashFlowSeries | None:
    """Build the cash-flow series from inline records or from a file.

    Args:
        kwargs: The tool's raw inputs.

    Returns:
        A ``CashFlowSeries``, or ``None`` when no flows were supplied.

    Raises:
        ValueError: If both sources were given, an inline record is malformed,
            or a currency is missing. File problems surface as
            ``CashFlowIngestError``, which is a ``ValueError``.
    """
    inline = kwargs.get("flows")
    path = kwargs.get("flows_path")
    if inline and path:
        raise ValueError("pass either flows or flows_path, not both")
    currency = kwargs.get("currency")

    if path:
        columns = kwargs.get("flows_columns")
        if columns is not None and not isinstance(columns, dict):
            raise ValueError("flows_columns must be an object mapping field to column name")
        invert_sign = boolean_argument(kwargs.get("flows_invert_sign", False), field="flows_invert_sign")
        return load_cashflows(
            str(path),
            columns=columns,
            currency=currency,
            default_kind=kwargs.get("flows_default_kind"),
            date_format=kwargs.get("flows_date_format"),
            invert_sign=invert_sign,
        )

    if not inline:
        return None
    if not isinstance(inline, list):
        raise ValueError("flows must be an array of {date, amount, kind} objects")
    if len(inline) > _MAX_INLINE_FLOWS:
        raise ValueError(f"flows may contain at most {_MAX_INLINE_FLOWS} entries")

    records: list[CashFlow] = []
    for index, item in enumerate(inline):
        if not isinstance(item, dict):
            raise ValueError(f"flows[{index}] must be an object")
        row_currency = item.get("currency") or currency
        if not row_currency:
            raise ValueError(
                f"flows[{index}] has no currency and no top-level currency was "
                "given; currency is never defaulted"
            )
        try:
            records.append(
                CashFlow(
                    date=item["date"],
                    amount=item["amount"],
                    kind=item["kind"],
                    currency=row_currency,
                )
            )
        except KeyError as exc:
            raise ValueError(f"flows[{index}] is missing {exc.args[0]!r}") from exc
        except ValueError as exc:
            raise ValueError(f"flows[{index}]: {exc}") from exc
    return CashFlowSeries(tuple(records))


def _coerce_flow_timing(raw: Any) -> str:
    """Validate the flow-timing token.

    Args:
        raw: Value supplied for ``flow_timing``; ``None`` selects the default.

    Returns:
        Either :data:`~src.quantlib.performance.FLOW_TIMING_END` or
        :data:`~src.quantlib.performance.FLOW_TIMING_START`.

    Raises:
        ValueError: If the token is not one of the two recognised values.
    """
    if raw is None or raw == "":
        return FLOW_TIMING_END
    token = str(raw).strip().lower()
    if token not in (FLOW_TIMING_END, FLOW_TIMING_START):
        raise ValueError(
            f"flow_timing must be {FLOW_TIMING_END!r} or {FLOW_TIMING_START!r}, "
            f"got {raw!r}"
        )
    return token


def _coerce_kinds(raw: Any, field_name: str) -> list[str] | None:
    """Validate an optional kind-classification override.

    Args:
        raw: Value supplied for ``external_kinds`` or ``internal_kinds``.
        field_name: Name used in the error message.

    Returns:
        The list of labels, or ``None`` to keep the module default.

    Raises:
        ValueError: If the value is not an array of non-empty strings.
    """
    if raw is None:
        return None
    if not isinstance(raw, list) or not raw:
        raise ValueError(f"{field_name} must be a non-empty array of kind labels")
    labels: list[str] = []
    for item in raw:
        if not isinstance(item, str) or not item.strip():
            raise ValueError(f"{field_name} entries must be non-empty strings")
        labels.append(item)
    return labels


def _rounded(value: float) -> float:
    """Round a finite scalar for stable, compact JSON.

    Args:
        value: Number to round.

    Returns:
        The value rounded to :data:`_ROUNDING` decimal places.
    """
    return round(float(value), _ROUNDING)


def _rounded_or_none(value: float | None) -> float | None:
    """Round a scalar that may be deliberately absent.

    Args:
        value: Number to round, or ``None``.

    Returns:
        The rounded value, or ``None`` when the caller had nothing to report.
    """
    return None if value is None else _rounded(value)


def _error(message: str) -> str:
    """Build the tool's stable error envelope.

    Args:
        message: Operator-facing explanation.

    Returns:
        A JSON string with ``status`` set to ``"error"``.
    """
    return json.dumps(
        {"status": "error", "tool": CashFlowPerformanceTool.name, "error": message},
        ensure_ascii=False,
    )