"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(runs): add a lightweight run preview endpoint
alexfb0ebe33e1a5
diff --git a/agent/api_server.py b/agent/api_server.pyindex 2399febd0..fbbf1e820 100644--- a/agent/api_server.py+++ b/agent/api_server.py@@ -181,11 +181,7 @@ app.middleware("http")(_apply_security_headers)from src.api.runs_routes import register_runs_routes # noqa: E402register_runs_routes(app)-from src.api.runs_routes import ( # noqa: F401, E402- _load_json_file,- _load_csv_to_dict,- _build_response_from_run_dir,-)+from src.api.runs_routes import _build_response_from_run_dir # noqa: F401, E402from src.api.attribution_routes import register_attribution_routes # noqa: E402register_attribution_routes(app)diff --git a/agent/src/api/run_artifacts.py b/agent/src/api/run_artifacts.pynew file mode 100644index 000000000..c3923c142--- /dev/null+++ b/agent/src/api/run_artifacts.py@@ -0,0 +1,135 @@+"""Readers for persisted run artifacts shared by the run detail and preview routes."""++from __future__ import annotations++import os+import re+from pathlib import Path+from typing import Any, Dict, List, Optional, Set++from src.api.models import BacktestMetrics+from src.ui_services import load_csv_records, load_json_file++EQUITY_CURVE_MAX_POINTS = 1000++# Artifacts a run card can show: metrics, curves, trades, positions, validation+# or strategy source.+_REPORT_ARTIFACT_RE = re.compile(+ r"(?:metrics|equity|trades|positions|ohlcv|validation|strategy)\.(?:csv|json|pine|py)$",+ re.IGNORECASE,+)+++def load_backtest_metrics(run_dir: Path) -> Optional[BacktestMetrics]:+ """Parse ``artifacts/metrics.csv`` into backtest metrics.++ Args:+ run_dir: Run directory.++ Returns:+ Parsed metrics, or ``None`` when the file is missing or lacks the+ required summary fields.+ """+ rows = load_csv_records(run_dir / "artifacts" / "metrics.csv", limit=1)+ if not rows:+ return None+ parsed: Dict[str, Any] = {}+ for key, value in rows[0].items():+ if not key or not value:+ continue+ try:+ parsed[key] = (+ int(float(value))+ if key in ("trade_count", "max_consecutive_loss")+ else float(value)+ )+ except (ValueError, TypeError):+ continue+ if "final_value" not in parsed:+ return None+ try:+ return BacktestMetrics(**parsed)+ except (ValueError, TypeError):+ return None+++def equity_curve_from_rows(rows: List[Dict[str, Any]]) -> List[Dict[str, Any]]:+ """Project ``equity.csv`` rows onto chart points.++ Args:+ rows: Rows read from ``equity.csv``.++ Returns:+ One ``time``/``equity``/``drawdown`` point per row, keeping only the+ columns the row has.+ """+ curve: List[Dict[str, Any]] = []+ for row in rows:+ point: Dict[str, Any] = {}+ if "timestamp" in row:+ point["time"] = row["timestamp"]+ if "equity" in row:+ point["equity"] = row["equity"]+ if "drawdown" in row:+ point["drawdown"] = row["drawdown"]+ curve.append(point)+ return curve+++def _artifact_names(run_dir: Path) -> Set[str]:+ """Return file names directly under ``artifacts/``; empty if unreadable."""+ try:+ with os.scandir(run_dir / "artifacts") as entries:+ return {entry.name for entry in entries if entry.is_file()}+ except OSError:+ return set()+++def is_report_worthy(run_dir: Path, names: Optional[Set[str]] = None) -> bool:+ """Tell whether a run produced anything a run card can show.++ Every chat turn gets a run directory, so most runs are plain replies;+ deciding from file names keeps those to a directory listing.++ Args:+ run_dir: Run directory.+ names: File names under ``artifacts/`` when already listed.++ Returns:+ ``True`` when the run has report artifacts, price data or a non-empty+ run card.+ """+ if names is None:+ names = _artifact_names(run_dir)+ return (+ any(_REPORT_ARTIFACT_RE.search(name) for name in names)+ or "price_series.csv" in names+ or any(name.startswith("ohlcv_") and name.endswith(".csv") for name in names)+ or bool(load_json_file(run_dir / "run_card.json"))+ )+++def build_run_preview(run_dir: Path) -> Dict[str, Any]:+ """Summarize a run for its chat card without loading chart payloads.++ Args:+ run_dir: Existing run directory.++ Returns:+ ``metrics``, the first ``EQUITY_CURVE_MAX_POINTS`` equity points with+ the same shape as the full run response, and ``report_worthy``.+ """+ names = _artifact_names(run_dir)+ metrics = load_backtest_metrics(run_dir) if "metrics.csv" in names else None+ equity_rows = (+ load_csv_records(+ run_dir / "artifacts" / "equity.csv", limit=EQUITY_CURVE_MAX_POINTS+ )+ if "equity.csv" in names+ else []+ )+ return {+ "metrics": metrics.model_dump(mode="json") if metrics else None,+ "equity_curve": equity_curve_from_rows(equity_rows),+ "report_worthy": is_report_worthy(run_dir, names),+ }diff --git a/agent/src/api/runs_routes.py b/agent/src/api/runs_routes.pyindex 72ec04135..989a7125a 100644--- a/agent/src/api/runs_routes.py+++ b/agent/src/api/runs_routes.py@@ -21,6 +21,14 @@ from fastapi import Depends, FastAPI, HTTPException, Query, statusfrom fastapi.concurrency import run_in_threadpoolfrom fastapi.responses import JSONResponse, Response+from src.api.run_artifacts import (+ EQUITY_CURVE_MAX_POINTS,+ build_run_preview,+ equity_curve_from_rows,+ load_backtest_metrics,+)+from src.ui_services import load_csv_records, load_json_file+# ---------------------------------------------------------------------------# Helper functions (module-level; host Pydantic models resolved via sys.modules)@@ -37,30 +45,6 @@ _FACTOR_MAX_TOTAL_ROWS = 20_000_FACTOR_MAX_GROUP_COLUMNS = 100-def _load_json_file(path: Path) -> Optional[Dict[str, Any]]:- """Load JSON from disk if present."""- try:- if path.exists():- return json.loads(path.read_text(encoding="utf-8"))- except Exception:- pass- return None---def _load_csv_to_dict(path: Path, limit: Optional[int] = None) -> List[Dict[str, Any]]:- """Load CSV rows into a list of dictionaries."""- try:- if not path.exists():- return []- with path.open("r", encoding="utf-8", newline="") as handle:- rows = [dict(row) for row in csv.DictReader(handle)]- if limit is not None:- rows = rows[:limit]- return rows- except Exception:- return []--def _finite_float(value: Any) -> Optional[float]:"""Parse a finite float, returning ``None`` for invalid values.@@ -583,7 +567,7 @@ def _build_positions_sector_map(run_dir: Path, run_id: str, *, refresh: bool) ->return {"ok": True, "run_id": run_id, "symbols": {}, "note": "no positions artifact"}if not refresh:- cached = _load_json_file(cache_path)+ cached = load_json_file(cache_path)if isinstance(cached, dict) and isinstance(cached.get("symbols"), dict):cached["cached"] = Truecached["run_id"] = run_id@@ -688,6 +672,11 @@ def _render_run_result()+def _render_run_preview(run_dir: Path) -> JSONResponse:+ """Build and encode a run preview off the event loop."""+ return JSONResponse(build_run_preview(run_dir))++def _build_response_from_run_dir(run_dir: Path,elapsed: float,@@ -702,7 +691,6 @@ def _build_response_from_run_dir(host = _sys.modules.get("api_server") or _sys.modules.get("agent.api_server")RunResponse = host.RunResponse- BacktestMetrics = host.BacktestMetricsRAGSelection = host.RAGSelectionArtifact = host.Artifact@@ -715,7 +703,7 @@ def _build_response_from_run_dir(run_directory=str(run_dir),)- state_data = _load_json_file(run_dir / "state.json")+ state_data = load_json_file(run_dir / "state.json")if state_data:state_status = str(state_data.get("status") or "").lower()if state_status == "success":@@ -728,17 +716,17 @@ def _build_response_from_run_dir(else:response.status = "unknown"- request_data = _load_json_file(run_dir / "req.json") or {}+ request_data = load_json_file(run_dir / "req.json") or {}response.prompt = request_data.get("prompt") or request_data.get("request")planner_path = run_dir / "planner_output.json"- response.planner_output = _load_json_file(planner_path)+ response.planner_output = load_json_file(planner_path)design_path = run_dir / "design_spec.json"- response.strategy_spec = _load_json_file(design_path)+ response.strategy_spec = load_json_file(design_path)rag_path = run_dir / "rag_metadata.json"- rag_data = _load_json_file(rag_path)+ rag_data = load_json_file(rag_path)if rag_data:response.rag_selection = RAGSelection(selected_api=rag_data.get("selected_api") or rag_data.get("api_code", ""),@@ -746,25 +734,7 @@ def _build_response_from_run_dir(selected_score=float(rag_data.get("selected_score") or rag_data.get("score", 0.0)),)- metrics_path = run_dir / "artifacts" / "metrics.csv"- if metrics_path.exists():- metrics_dict_list = _load_csv_to_dict(metrics_path, limit=1)- if metrics_dict_list:- row = metrics_dict_list[0]- try:- # Pass ALL CSV columns to BacktestMetrics (extra="allow")- parsed: dict = {}- for k, v in row.items():- if not k or not v:- continue- try:- parsed[k] = int(float(v)) if k == "trade_count" or k == "max_consecutive_loss" else float(v)- except (ValueError, TypeError):- continue- if "final_value" in parsed:- response.metrics = BacktestMetrics(**parsed)- except (ValueError, TypeError):- pass+ response.metrics = load_backtest_metrics(run_dir)artifacts_dir = run_dir / "artifacts"if artifacts_dir.exists():@@ -785,11 +755,11 @@ def _build_response_from_run_dir(equity_path = run_dir / "artifacts" / "equity.csv"if equity_path.exists():- response.artifacts_equity_csv = _load_csv_to_dict(equity_path)+ response.artifacts_equity_csv = load_csv_records(equity_path)metrics_csv_path = run_dir / "artifacts" / "metrics.csv"if metrics_csv_path.exists():- response.artifacts_metrics_csv = _load_csv_to_dict(metrics_csv_path)+ response.artifacts_metrics_csv = load_csv_records(metrics_csv_path)run_card_path = run_dir / "run_card.json"if run_card_path.exists():@@ -798,10 +768,10 @@ def _build_response_from_run_dir(except (json.JSONDecodeError, OSError):pass- risk_xray = _load_json_file(run_dir / "artifacts" / "risk_xray.json")+ risk_xray = load_json_file(run_dir / "artifacts" / "risk_xray.json")if risk_xray is not None:response.risk_xray = risk_xray- rebalance_notes = _load_json_file(run_dir / "artifacts" / "rebalance_notes.json")+ rebalance_notes = load_json_file(run_dir / "artifacts" / "rebalance_notes.json")if rebalance_notes is not None:response.rebalance_notes = rebalance_notes@@ -814,15 +784,17 @@ def _build_response_from_run_dir(trades_path = run_dir / "artifacts" / "trades.csv"if trades_path.exists():- response.artifacts_trades_csv = _load_csv_to_dict(trades_path)+ response.artifacts_trades_csv = load_csv_records(trades_path)positions_path = run_dir / "artifacts" / "positions.csv"if positions_path.exists():- response.artifacts_positions_csv = _load_csv_to_dict(positions_path)+ response.artifacts_positions_csv = load_csv_records(positions_path)target_positions_path = run_dir / "artifacts" / "target_positions.csv"if target_positions_path.exists():- response.artifacts_target_positions_csv = _load_csv_to_dict(target_positions_path)+ response.artifacts_target_positions_csv = load_csv_records(+ target_positions_path+ )validation_path = run_dir / "artifacts" / "validation.json"if validation_path.exists():@@ -832,17 +804,9 @@ def _build_response_from_run_dir(passif response.artifacts_equity_csv:- filtered_equity = []- for row in response.artifacts_equity_csv[:1000]:- filtered_row: Dict[str, Any] = {}- if "timestamp" in row:- filtered_row["time"] = row["timestamp"]- if "equity" in row:- filtered_row["equity"] = row["equity"]- if "drawdown" in row:- filtered_row["drawdown"] = row["drawdown"]- filtered_equity.append(filtered_row)- response.equity_curve = filtered_equity+ response.equity_curve = equity_curve_from_rows(+ response.artifacts_equity_csv[:EQUITY_CURVE_MAX_POINTS]+ )if response.artifacts_trades_csv:response.trade_log = response.artifacts_trades_csv[:500]@@ -951,6 +915,25 @@ def register_runs_routes("content": pine_path.read_text(encoding="utf-8"),}+ @app.get("/runs/{run_id}/preview", dependencies=[Depends(require_auth)])+ async def get_run_preview(run_id: str):+ """Return the summary a chat card needs for a run.++ Args:+ run_id: Run identifier.++ Returns:+ ``metrics``, ``equity_curve`` and ``report_worthy``; see+ :func:`src.api.run_artifacts.build_run_preview`.+ """+ _host_validate_path_param(run_id, "run_id")+ run_dir = _host_RUNS_DIR() / run_id+ if not run_dir.exists():+ raise HTTPException(+ status_code=status.HTTP_404_NOT_FOUND, detail=f"Run {run_id} not found"+ )+ return await run_in_threadpool(_render_run_preview, run_dir)+@app.get("/runs/{run_id}/factor", dependencies=[Depends(require_auth)])async def get_run_factor(run_id: str):"""Return factor-analysis artifacts for a run.@@ -978,7 +961,14 @@ def register_runs_routes("ic_correlation": _factor_ic_correlation(factors),}- @app.get("/runs/{run_id}", response_model=RunResponse, dependencies=[Depends(require_auth)])+ # Pre-rendered off the event loop, so FastAPI does not re-validate the body;+ # ``responses`` keeps the schema in the OpenAPI docs.+ @app.get(+ "/runs/{run_id}",+ response_model=None,+ responses={200: {"model": RunResponse}},+ dependencies=[Depends(require_auth)],+ )async def get_run_result(run_id: str,chart_symbol: Optional[str] = Query(None, description="Opt in to chart payloads for a single symbol"),@@ -1067,7 +1057,7 @@ def register_runs_routes(# Status from state.json or artifactsstatus_val = "unknown"- state_file = _load_json_file(d / "state.json")+ state_file = load_json_file(d / "state.json")if state_file:status_val = str(state_file.get("status") or "unknown").lower()elif (d / "artifacts" / "equity.csv").exists():diff --git a/agent/src/ui_services.py b/agent/src/ui_services.pyindex ba2c0143b..4c1dc90de 100644--- a/agent/src/ui_services.py+++ b/agent/src/ui_services.py@@ -14,6 +14,7 @@ from __future__ import annotationsimport csvimport jsonfrom datetime import datetime, timedelta+from itertools import islicefrom pathlib import Pathfrom typing import Any, Dict, List, Optional@@ -62,11 +63,12 @@ def load_json_file(path: Path) -> Optional[Dict[str, Any]]:return None-def load_csv_records(path: Path) -> List[Dict[str, Any]]:+def load_csv_records(path: Path, limit: Optional[int] = None) -> List[Dict[str, Any]]:"""Load CSV rows as dictionaries.Args:path: CSV file path.+ limit: Stop after this many rows; ``None`` reads the whole file.Returns:Parsed CSV rows. Missing or unreadable files return an empty list.@@ -76,7 +78,7 @@ def load_csv_records(path: Path) -> List[Dict[str, Any]]:try:with path.open("r", encoding="utf-8", newline="") as handle:- return [dict(row) for row in csv.DictReader(handle)]+ return [dict(row) for row in islice(csv.DictReader(handle), limit)]except Exception:return []diff --git a/agent/tests/api/test_run_preview.py b/agent/tests/api/test_run_preview.pynew file mode 100644index 000000000..c93eaf73d--- /dev/null+++ b/agent/tests/api/test_run_preview.py@@ -0,0 +1,201 @@+"""Tests for GET /runs/{run_id}/preview.++The chat history asks for a preview of every assistant turn, and every turn+owns a run directory, so the route must stay cheap for plain replies and must+never pull chart payloads for backtests.+"""++from __future__ import annotations++import json+from datetime import date, timedelta+from pathlib import Path++import pytest+from fastapi.testclient import TestClient++import api_server+from src import ui_services+from src.api import run_artifacts, runs_routes++BACKTEST_RUN = "run_backtest"+CHAT_RUN = "run_chat"+METRICS_CSV = (+ "final_value,total_return,annual_return,max_drawdown,sharpe,win_rate,trade_count\n"+ "112000,0.12,0.05,-0.08,1.3,0.55,42\n"+)+++def _write_backtest_run(+ run_dir: Path, symbols: int, bars: int, equity_rows: int+) -> None:+ artifacts = run_dir / "artifacts"+ artifacts.mkdir(parents=True)+ (run_dir / "state.json").write_text('{"status": "success"}\n', encoding="utf-8")+ (artifacts / "metrics.csv").write_text(METRICS_CSV, encoding="utf-8")+ start = date(2020, 1, 1)+ days = [+ (start + timedelta(days=i)).isoformat() for i in range(max(bars, equity_rows))+ ]+ for n in range(symbols):+ rows = ["trade_date,open,high,low,close,volume"]+ rows += [f"{day},10,11,9,10.5,1000" for day in days[:bars]]+ (artifacts / f"ohlcv_S{n:03d}.csv").write_text(+ "\n".join(rows) + "\n", encoding="utf-8"+ )+ equity = ["timestamp,equity,drawdown"]+ equity += [f"{day},{100000 + i},0" for i, day in enumerate(days[:equity_rows])]+ (artifacts / "equity.csv").write_text("\n".join(equity) + "\n", encoding="utf-8")+ (artifacts / "trades.csv").write_text(+ "timestamp,code,side,price,qty\n2020-01-02,S000,BUY,10,100\n", encoding="utf-8"+ )+++def _write_chat_run(run_dir: Path) -> None:+ artifacts = run_dir / "artifacts"+ artifacts.mkdir(parents=True)+ (run_dir / "state.json").write_text('{"status": "success"}\n', encoding="utf-8")+ (run_dir / "llm_usage.json").write_text('{"input_tokens": 10}\n', encoding="utf-8")+ (artifacts / "grounding_evidence.json").write_text(+ '{"items": []}\n', encoding="utf-8"+ )++[email protected](scope="module")+def runs_root(tmp_path_factory) -> Path:+ root = tmp_path_factory.mktemp("preview") / "runs"+ _write_backtest_run(root / BACKTEST_RUN, symbols=40, bars=500, equity_rows=1200)+ _write_chat_run(root / CHAT_RUN)+ return root+++def client(runs_root: Path, monkeypatch) -> TestClient:+ monkeypatch.setattr(api_server, "RUNS_DIR", runs_root)+ return TestClient(api_server.app, client=("127.0.0.1", 50000))+++def test_backtest_preview_matches_full_response(+ client: TestClient, runs_root: Path+) -> None:+ full = api_server._build_response_from_run_dir(+ runs_root / BACKTEST_RUN, elapsed=0.0+ ).model_dump(mode="json")++ response = client.get(f"/runs/{BACKTEST_RUN}/preview")++ assert response.status_code == 200+ payload = response.json()+ assert set(payload) == {"metrics", "equity_curve", "report_worthy"}+ assert payload["report_worthy"] is True+ assert payload["metrics"] == full["metrics"]+ assert payload["equity_curve"] == full["equity_curve"]+ assert len(payload["equity_curve"]) == run_artifacts.EQUITY_CURVE_MAX_POINTS+++def test_backtest_preview_is_a_small_fraction_of_the_full_response(+ client: TestClient,+) -> None:+ full = client.get(f"/runs/{BACKTEST_RUN}")+ preview = client.get(f"/runs/{BACKTEST_RUN}/preview")++ assert full.status_code == preview.status_code == 200+ assert len(preview.content) < 64 * 1024+ assert len(preview.content) * 50 < len(full.content)+++def test_preview_never_builds_chart_payloads(client: TestClient, monkeypatch) -> None:+ def fail(*_args, **_kwargs):+ raise AssertionError("preview loaded chart payloads")++ monkeypatch.setattr(ui_services, "build_run_analysis", fail)+ monkeypatch.setattr(ui_services, "load_price_series", fail)+ monkeypatch.setattr(ui_services, "reconstruct_price_series", fail)++ response = client.get(f"/runs/{BACKTEST_RUN}/preview")++ assert response.status_code == 200+ assert response.json()["report_worthy"] is True+++def test_chat_turn_preview_reads_no_csv(client: TestClient, monkeypatch) -> None:+ def fail(*_args, **_kwargs):+ raise AssertionError("chat-turn preview opened a CSV")++ monkeypatch.setattr(run_artifacts, "load_csv_records", fail)++ response = client.get(f"/runs/{CHAT_RUN}/preview")++ assert response.status_code == 200+ assert response.json() == {+ "metrics": None,+ "equity_curve": [],+ "report_worthy": False,+ }+++def test_preview_is_rendered_in_threadpool(client: TestClient, offloaded: list) -> None:+ response = client.get(f"/runs/{CHAT_RUN}/preview")++ assert response.status_code == 200+ assert runs_routes._render_run_preview in offloaded+++ ("setup", "expected"),+ [+ (+ lambda d: (d / "run_card.json").write_text(+ json.dumps({"metrics": {"sharpe": 1}})+ ),+ True,+ ),+ (lambda d: (d / "run_card.json").write_text("{}"), False),+ (+ lambda d: (d / "artifacts" / "ohlcv_AAPL.csv").write_text(+ "trade_date,close\n"+ ),+ True,+ ),+ (+ lambda d: (d / "artifacts" / "price_series.csv").write_text(+ "timestamp,code\n"+ ),+ True,+ ),+ (lambda d: (d / "artifacts" / "strategy.pine").write_text("//"), True),+ (lambda d: (d / "artifacts" / "VALIDATION.JSON").write_text("{}"), True),+ (lambda d: (d / "artifacts" / "notes.txt").write_text("x"), False),+ ],+)+def test_report_worthy_rules(tmp_path: Path, setup, expected: bool) -> None:+ run_dir = tmp_path / "run"+ (run_dir / "artifacts").mkdir(parents=True)+ setup(run_dir)++ assert run_artifacts.build_run_preview(run_dir)["report_worthy"] is expected+++def test_metrics_without_required_fields_stay_empty(tmp_path: Path) -> None:+ run_dir = tmp_path / "run"+ (run_dir / "artifacts").mkdir(parents=True)+ (run_dir / "artifacts" / "metrics.csv").write_text(+ "final_value\n100\n", encoding="utf-8"+ )++ preview = run_artifacts.build_run_preview(run_dir)++ assert preview["metrics"] is None+ assert preview["report_worthy"] is True+++def test_preview_missing_run_is_404(client: TestClient) -> None:+ response = client.get("/runs/run_missing/preview")++ assert response.status_code == 404+++def test_preview_rejects_invalid_run_id(client: TestClient) -> None:+ response = client.get("/runs/foo.bar/preview")++ assert response.status_code == 400