"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Reach the finance-math layer from every transport, without a shell.
``src/quantlib`` holds ~250 tested functions, and until now the only way an
agent could run them was ``bash`` plus an ``import``. That gate is off by
default on the API and MCP transports, and correctly so: process-control tools
are an RCE surface regardless of transport, and force-enabling them on stdio was
the subject of two published advisories (see
``mcp_server._resolve_include_shell_tools``). So on Web, API and MCP the maths
layer was simply unreachable.
Widening the shell gate to fix that would trade a real security property for a
convenience. This tool takes the other route: one stable contract that can call
any *public* function of an allowlisted quantlib module, and nothing else.
WHY THIS IS NOT ARBITRARY CODE EXECUTION
----------------------------------------
Three structural limits, in order of what they rule out:
1. **Module allowlist.** Only the modules in :data:`ALLOWED_MODULES` are
reachable. There is no path from a caller-supplied string to an arbitrary
import -- the string is looked up in a dict, never passed to ``importlib``.
2. **``__all__`` only.** Within a module, only names the module itself exports
are callable. A private helper, a re-exported third-party symbol, or a
dunder is not reachable.
3. **No file-writing entry points.** Names matching :data:`_WRITER_PREFIXES` are
refused even when exported, because they take a destination path. Everything
left is pure computation: no filesystem, no network, no process. Use
``write_file`` if a file is what you want.
WHAT THIS DOES NOT DO
---------------------
It does not fetch data. Every argument comes from the caller, which usually
means a data tool ran first. A function that needs a price history needs you to
have retrieved that history.
PASSING PANDAS OBJECTS OVER JSON
--------------------------------
Several functions need a real indexed ``Series`` or ``DataFrame``, and a bare
JSON list loses the index -- which for an event study or a cash-flow series is
the part that carries the meaning. Two envelopes are therefore understood
anywhere in ``kwargs``::
{"__series__": {"index": [...], "values": [...]}}
{"__dataframe__": {"index": [...], "columns": [...], "data": [[...], ...]}}
A plain list stays a plain list, because most functions accept a sequence and
coercing every list into a Series would break the ones that do not.
"""
from __future__ import annotations
import dataclasses
import inspect
import json
import math
from enum import Enum
from typing import Any
from src.agent.tools import BaseTool
__all__ = ["ALLOWED_MODULES", "QuantlibCallTool"]
#: Short name -> dotted module path. A caller names the short form; nothing a
#: caller sends is ever handed to ``importlib``.
ALLOWED_MODULES: dict[str, str] = {
"options": "src.quantlib.options",
"fixedincome": "src.quantlib.fixedincome",
"credit": "src.quantlib.credit",
"timeseries": "src.quantlib.timeseries",
"risk": "src.quantlib.risk",
"var_backtest": "src.quantlib.var_backtest",
"attribution": "src.quantlib.attribution",
"impact": "src.quantlib.impact",
"fundmath": "src.quantlib.fundmath",
"performance": "src.quantlib.performance",
"eventstudy": "src.quantlib.eventstudy",
"factormodel": "src.quantlib.factormodel",
"neutralization": "src.quantlib.neutralization",
"combination": "src.quantlib.combination",
"multipletesting": "src.quantlib.multipletesting",
"crossvalidation": "src.quantlib.crossvalidation",
"valuation.dcf": "src.quantlib.valuation.dcf",
"valuation.comps": "src.quantlib.valuation.comps",
"valuation.threestatement": "src.quantlib.valuation.threestatement",
"valuation.artifact": "src.quantlib.valuation.artifact",
"valuation.contracts": "src.quantlib.valuation.contracts",
"volatility": "src.quantlib.volatility",
"portfolio": "src.quantlib.portfolio",
"copula": "src.quantlib.copula",
"microstructure": "src.quantlib.microstructure",
}
#: Exported names refused because they write to a caller-supplied path. This
#: tool stays pure-compute; file creation belongs to ``write_file``.
_WRITER_PREFIXES: tuple[str, ...] = ("export_",)
#: Largest number of leaf values serialized back to the caller. A factor panel
#: or a full CSCV logit vector can be enormous, and silently returning 200k
#: numbers into a context window helps nobody.
_MAX_RESULT_LEAVES = 5000
def _import_module(short_name: str) -> Any:
"""Import an allowlisted module by its short name.
Args:
short_name: Key of :data:`ALLOWED_MODULES`.
Returns:
The imported module.
Raises:
KeyError: If the name is not allowlisted.
"""
import importlib
return importlib.import_module(ALLOWED_MODULES[short_name])
def _public_names(module: Any) -> list[str]:
"""Callable public names of a module, writers excluded.
Args:
module: An imported quantlib module.
Returns:
Sorted names from ``__all__`` that are callable and not file writers.
"""
exported = getattr(module, "__all__", [])
out = []
for name in exported:
if name.startswith(_WRITER_PREFIXES):
continue
obj = getattr(module, name, None)
if callable(obj):
out.append(name)
return sorted(out)
def _decode(value: Any) -> Any:
"""Turn JSON envelopes into the pandas objects some functions require.
Args:
value: A decoded-JSON value, possibly a ``__series__`` or
``__dataframe__`` envelope, possibly nested inside a container.
Returns:
The value with any envelope replaced by the pandas object it describes.
Raises:
ValueError: If an envelope is malformed.
"""
import pandas as pd
if isinstance(value, dict):
if "__series__" in value:
spec = value["__series__"]
if not isinstance(spec, dict) or "values" not in spec:
raise ValueError("__series__ needs a 'values' list")
return pd.Series(spec["values"], index=spec.get("index"))
if "__dataframe__" in value:
spec = value["__dataframe__"]
if not isinstance(spec, dict) or "data" not in spec:
raise ValueError("__dataframe__ needs a 'data' list of rows")
return pd.DataFrame(
spec["data"], index=spec.get("index"), columns=spec.get("columns")
)
return {k: _decode(v) for k, v in value.items()}
if isinstance(value, list):
return [_decode(v) for v in value]
return value
class _Budget:
"""Mutable leaf counter shared across one serialization pass."""
def __init__(self) -> None:
self.leaves = 0
self.truncated = False
def _encode(value: Any, budget: _Budget) -> Any:
"""Serialize a quantlib result into JSON-safe data.
Dataclasses become dicts, enums become their value, numpy and pandas objects
become plain containers, and non-finite floats become explicit strings so a
NaN cannot arrive at the caller as ``null`` and read as "absent".
Args:
value: Anything a quantlib function returns.
budget: Shared leaf counter; once exhausted, containers are truncated
and the fact is reported rather than hidden.
Returns:
A JSON-serializable structure.
"""
import numpy as np
import pandas as pd
if budget.leaves >= _MAX_RESULT_LEAVES:
budget.truncated = True
return "<truncated>"
if value is None or isinstance(value, (bool, int, str)):
budget.leaves += 1
return value
if isinstance(value, float):
budget.leaves += 1
if math.isnan(value):
return "NaN"
if math.isinf(value):
return "Infinity" if value > 0 else "-Infinity"
return value
if isinstance(value, Enum):
budget.leaves += 1
return value.value
if isinstance(value, (np.integer, np.floating, np.bool_)):
return _encode(value.item(), budget)
def sequence(values):
encoded = []
for item in values:
if budget.leaves >= _MAX_RESULT_LEAVES:
budget.truncated = True
break
encoded.append(_encode(item, budget))
return encoded
def mapping(items):
encoded = {}
for key, item in items:
if budget.leaves >= _MAX_RESULT_LEAVES:
budget.truncated = True
break
encoded[str(key)] = _encode(item, budget)
return encoded
if isinstance(value, np.ndarray):
return sequence(value)
if isinstance(value, pd.Series):
return {
"__series__": {
"index": sequence(value.index),
"values": sequence(value),
}
}
if isinstance(value, pd.DataFrame):
return {
"__dataframe__": {
"index": sequence(value.index),
"columns": sequence(str(c) for c in value.columns),
"data": sequence(value.itertuples(index=False, name=None)),
}
}
if dataclasses.is_dataclass(value) and not isinstance(value, type):
return mapping(
(f.name, getattr(value, f.name)) for f in dataclasses.fields(value)
)
if isinstance(value, dict):
return mapping(value.items())
if isinstance(value, (list, tuple, set, frozenset)):
return sequence(value)
budget.leaves += 1
return str(value)
class QuantlibCallTool(BaseTool):
"""Call any public function of the tested finance-math layer."""
name = "quantlib_call"
description = (
"Run a function from the tested finance-math library (src/quantlib): "
"Black-Scholes and implied vol, bond math and curve fitting, Altman Z "
"and Merton/KMV, stationarity/cointegration/GARCH/regime switching, "
"VaR/CVaR/EVT and VaR backtesting (Kupiec/Christoffersen/Basel), "
"Brinson-Fachler attribution, market impact, fund maths "
"(XIRR/MOIC/DPI/TVPI/PME/waterfalls), TWR/Dietz/MWR, event studies "
"(CAR/CAAR/Patell/BMP), style factor models, cross-sectional OLS/WLS "
"factor neutralization and PCA at any observation frequency, "
"multi-factor combination with walk-forward IC weights, "
"deflated Sharpe and PBO, "
"purged cross-validation, and the valuation engine (DCF / comps / "
"three-statement). Read-only and pure-compute: it fetches no data and "
"writes no files. Start with action='list' to see modules, then "
"action='list' with a module to see its functions, then "
"action='describe' for a signature. "
'Example: quantlib_call(action="call", module="risk", '
'function="historical_var", kwargs={"returns": [0.01, -0.02], "confidence": 0.95}).'
)
is_readonly = True
repeatable = True
parameters = {
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["list", "describe", "call"],
"description": (
"'list' enumerates modules (or a module's functions when "
"'module' is given); 'describe' returns one function's "
"signature and docstring; 'call' runs it."
),
"default": "list",
},
"module": {
"type": "string",
"description": (
"Short module name, e.g. 'risk', 'options', 'valuation.dcf'. "
"Required for 'describe' and 'call'."
),
},
"function": {
"type": "string",
"description": "Public function name. Required for 'describe' and 'call'.",
},
"kwargs": {
"type": "object",
"description": (
"Keyword arguments. Pass an indexed pandas Series as "
'{"__series__": {"index": [...], "values": [...]}} and a '
'DataFrame as {"__dataframe__": {"index": [...], '
'"columns": [...], "data": [[...]]}}; a plain list stays a list.'
),
"default": {},
},
},
"required": ["action"],
}
def execute(self, **kwargs: Any) -> str:
"""Dispatch a list / describe / call request.
Args:
**kwargs: See :attr:`parameters`.
Returns:
A JSON envelope. Every failure path returns ``ok=false`` with an
actionable ``error`` rather than raising, matching the other
read-only tools.
"""
action = str(kwargs.get("action") or "list").strip().lower()
module_name = kwargs.get("module")
function_name = kwargs.get("function")
try:
if action == "list":
return self._list(module_name)
if action not in ("describe", "call"):
return self._error(f"unknown action {action!r}; use list, describe or call")
if not module_name or not function_name:
return self._error(f"action='{action}' needs both 'module' and 'function'")
resolved = self._resolve(str(module_name), str(function_name))
if isinstance(resolved, str):
return resolved
func = resolved
if action == "describe":
return self._describe(str(module_name), str(function_name), func)
return self._call(str(module_name), str(function_name), func, kwargs.get("kwargs") or {})
except Exception as exc: # noqa: BLE001 - envelope, never raise to the loop
return self._error(f"{type(exc).__name__}: {exc}")
def _resolve(self, module_name: str, function_name: str) -> Any:
"""Look up a callable, or return an error envelope string.
Args:
module_name: Short module name.
function_name: Public function name.
Returns:
The callable, or a JSON error envelope string.
"""
if module_name not in ALLOWED_MODULES:
return self._error(
f"unknown module {module_name!r}; available: {sorted(ALLOWED_MODULES)}"
)
module = _import_module(module_name)
allowed = _public_names(module)
if function_name not in allowed:
if function_name.startswith(_WRITER_PREFIXES):
return self._error(
f"{function_name!r} writes to a path and is not callable here; "
"this tool is pure-compute"
)
return self._error(
f"{function_name!r} is not a public function of {module_name!r}; "
f"available: {allowed}"
)
return getattr(module, function_name)
def _list(self, module_name: Any) -> str:
"""List modules, or one module's public functions."""
if not module_name:
return json.dumps(
{
"ok": True,
"modules": sorted(ALLOWED_MODULES),
"hint": "call again with module=<name> to list its functions",
},
ensure_ascii=False,
)
name = str(module_name)
if name not in ALLOWED_MODULES:
return self._error(f"unknown module {name!r}; available: {sorted(ALLOWED_MODULES)}")
module = _import_module(name)
functions = []
for fn_name in _public_names(module):
fn = getattr(module, fn_name)
doc = (inspect.getdoc(fn) or "").strip().splitlines()
functions.append({"name": fn_name, "summary": doc[0] if doc else ""})
return json.dumps(
{"ok": True, "module": name, "functions": functions}, ensure_ascii=False
)
def _describe(self, module_name: str, function_name: str, func: Any) -> str:
"""Return one function's signature and docstring."""
try:
signature = str(inspect.signature(func))
except (TypeError, ValueError):
signature = "(signature unavailable)"
return json.dumps(
{
"ok": True,
"module": module_name,
"function": function_name,
"signature": signature,
"doc": inspect.getdoc(func) or "",
},
ensure_ascii=False,
)
def _call(self, module_name: str, function_name: str, func: Any, raw_kwargs: Any) -> str:
"""Run the function and serialize its result."""
if not isinstance(raw_kwargs, dict):
return self._error("'kwargs' must be an object")
try:
decoded = {str(k): _decode(v) for k, v in raw_kwargs.items()}
except ValueError as exc:
return self._error(f"bad argument envelope: {exc}")
try:
result = func(**decoded)
except TypeError as exc:
# Almost always a wrong/missing argument; hand back the signature so
# the next attempt is informed rather than another guess.
try:
signature = str(inspect.signature(func))
except (TypeError, ValueError):
signature = "(signature unavailable)"
return self._error(f"{exc}", signature=signature)
except Exception as exc: # noqa: BLE001
# A domain refusal (bad confidence level, missing input, no sign
# change) is information, not a crash: surface it verbatim.
return self._error(f"{type(exc).__name__}: {exc}")
budget = _Budget()
payload = {
"ok": True,
"module": module_name,
"function": function_name,
"result": _encode(result, budget),
}
if budget.truncated:
payload["truncated"] = True
payload["truncation_note"] = (
f"result exceeded {_MAX_RESULT_LEAVES} values and was truncated; "
"narrow the inputs or request a summary statistic instead"
)
return json.dumps(payload, ensure_ascii=False)
@staticmethod
def _error(message: str, **extra: Any) -> str:
"""Build a uniform failure envelope."""
return json.dumps({"ok": False, "error": message, **extra}, ensure_ascii=False)