Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(runs): add a lightweight run preview endpoint

alexfb0ebe33e1a5
diff --git a/agent/api_server.py b/agent/api_server.py
index 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: E402
register_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, E402
from src.api.attribution_routes import register_attribution_routes # noqa: E402
register_attribution_routes(app)
diff --git a/agent/src/api/run_artifacts.py b/agent/src/api/run_artifacts.py
new file mode 100644
index 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.py
index 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, status
from fastapi.concurrency import run_in_threadpool
from 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"] = True
cached["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.BacktestMetrics
RAGSelection = host.RAGSelection
Artifact = 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(
pass
if 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 artifacts
status_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.py
index ba2c0143b..4c1dc90de 100644
--- a/agent/src/ui_services.py
+++ b/agent/src/ui_services.py
@@ -14,6 +14,7 @@ from __future__ import annotations
import csv
import json
from datetime import datetime, timedelta
+from itertools import islice
from pathlib import Path
from 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.py
new file mode 100644
index 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