"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Run listing and detail HTTP routes.
Mounted by ``agent/api_server.py`` via ``register_runs_routes(app, ...)``.
"""
from __future__ import annotations
import csv
import json
import math
import os
import statistics
import threading
from collections import deque
from concurrent.futures import ThreadPoolExecutor, as_completed
from datetime import datetime, timezone
from pathlib import Path
from typing import Any, Awaitable, Callable, Deque, Dict, Generator, List, Optional, Tuple
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)
# ---------------------------------------------------------------------------
_FACTOR_MAX_RESULTS = 20
_FACTOR_MAX_SCAN_ENTRIES = 4096
_FACTOR_MAX_SCAN_DEPTH = 8
_FACTOR_MAX_FILE_BYTES = 2 * 1024 * 1024
_FACTOR_MAX_SUMMARY_BYTES = 128 * 1024
_FACTOR_MAX_TOTAL_ARTIFACT_BYTES = 8 * 1024 * 1024
_FACTOR_MAX_ROWS_PER_CSV = 5000
_FACTOR_MAX_TOTAL_ROWS = 20_000
_FACTOR_MAX_GROUP_COLUMNS = 100
def _finite_float(value: Any) -> Optional[float]:
"""Parse a finite float, returning ``None`` for invalid values.
Args:
value: Candidate numeric value.
Returns:
Parsed finite float, or ``None``.
"""
try:
parsed = float(value)
except (TypeError, ValueError, OverflowError):
return None
return parsed if math.isfinite(parsed) else None
def _sanitize_finite_json(value: Any) -> Any:
"""Replace non-finite JSON numeric leaves with ``None`` recursively.
Args:
value: Parsed JSON value.
Returns:
JSON-compatible value without NaN or infinities.
"""
if isinstance(value, float):
return value if math.isfinite(value) else None
if isinstance(value, dict):
return {key: _sanitize_finite_json(item) for key, item in value.items()}
if isinstance(value, list):
return [_sanitize_finite_json(item) for item in value]
return value
def _claim_factor_artifact(
path: Path,
*,
max_file_bytes: int,
remaining_bytes: int,
) -> Tuple[bool, int, bool]:
"""Check whether an artifact can be read inside the response byte budget.
Symlinks are rejected so companion files cannot escape the discovered
bundle. The returned tuple is ``(readable, charged_bytes, degraded)``;
missing optional files are not considered degraded.
Args:
path: Candidate artifact path.
max_file_bytes: Per-file byte ceiling.
remaining_bytes: Remaining aggregate byte budget.
Returns:
Tuple of readability, charged bytes, and degraded status.
"""
try:
if path.is_symlink():
return False, 0, True
if not path.is_file():
return False, 0, False
size = path.stat().st_size
except OSError:
return False, 0, True
if size < 0 or size > max_file_bytes or size > remaining_bytes:
return False, 0, True
return True, size, False
def _load_ic_series_csv(path: Path, row_limit: int) -> Tuple[List[Dict[str, Any]], bool]:
"""Load an ``ic_series.csv`` file into ``{"date", "ic"}`` rows.
The first CSV column is treated as the date column regardless of its
header name (the factor tool writes it with an empty or varying index
label). Rows whose IC value does not parse as a float are skipped.
Args:
path: Path to the ic_series.csv file.
row_limit: Maximum source rows to parse.
Returns:
Tuple of rows with raw string dates and finite IC values plus a flag
indicating that the source was truncated or could not be parsed.
"""
if row_limit <= 0:
return [], True
try:
with path.open("r", encoding="utf-8", newline="") as handle:
reader = csv.DictReader(handle)
fieldnames = reader.fieldnames
if not fieldnames or fieldnames[0] is None:
return [], True
date_col = fieldnames[0]
rows: List[Dict[str, Any]] = []
truncated = False
for source_index, row in enumerate(reader):
if source_index >= row_limit:
truncated = True
break
date_value = row.get(date_col)
if date_value is None:
continue
ic_value = _finite_float(row.get("IC"))
if ic_value is None:
continue
rows.append({"date": date_value, "ic": ic_value})
return rows, truncated
except Exception:
return [], True
def _load_group_equity_csv(
path: Path,
row_limit: int,
) -> Tuple[List[Dict[str, Any]], List[str], bool]:
"""Load a ``group_equity.csv`` file into dated rows of float group values.
The first column is the date; every remaining column is kept in file
order and parsed as float. Cells that fail to parse are dropped.
Args:
path: Path to the group_equity.csv file.
row_limit: Maximum source rows to parse.
Returns:
Tuple of (rows, value column names in file order, truncated/degraded).
"""
if row_limit <= 0:
return [], [], True
try:
with path.open("r", encoding="utf-8", newline="") as handle:
reader = csv.DictReader(handle)
fieldnames = reader.fieldnames
if not fieldnames or fieldnames[0] is None or len(fieldnames) < 2:
return [], [], True
date_col = fieldnames[0]
all_value_cols = [col for col in fieldnames[1:] if col]
value_cols = all_value_cols[:_FACTOR_MAX_GROUP_COLUMNS]
truncated = len(value_cols) < len(all_value_cols)
rows: List[Dict[str, Any]] = []
for source_index, row in enumerate(reader):
if source_index >= row_limit:
truncated = True
break
date_value = row.get(date_col)
if date_value is None:
continue
parsed: Dict[str, Any] = {"date": date_value}
for col in value_cols:
numeric_value = _finite_float(row.get(col))
if numeric_value is not None:
parsed[col] = numeric_value
rows.append(parsed)
return rows, value_cols, truncated
except Exception:
return [], [], True
def _load_factor_summary(path: Path) -> Tuple[Optional[Dict[str, Any]], bool]:
"""Load a factor summary while removing non-finite numeric leaves.
Args:
path: Path to ``ic_summary.json``.
Returns:
Sanitized summary and whether parsing degraded.
"""
try:
payload = json.loads(path.read_text(encoding="utf-8"))
if not isinstance(payload, dict):
return None, True
return _sanitize_finite_json(payload), False
except (OSError, UnicodeError, ValueError, RecursionError):
return None, True
def _iter_factor_series_files(
run_dir: Path,
*,
max_results: int,
) -> Generator[Path, None, None]:
"""Yield bounded, non-symlinked ``ic_series.csv`` paths.
Directory entries, nesting depth, and result count are all capped. Unlike
``Path.rglob()``, this iterator never constructs the complete match list
and never follows a symlinked directory.
Args:
run_dir: Root directory of the run.
max_results: Maximum factor marker paths to yield.
Yields:
Safe paths to factor IC-series artifacts.
"""
artifacts_dir = run_dir / "artifacts"
if not artifacts_dir.is_dir() or artifacts_dir.is_symlink() or max_results <= 0:
return
pending: Deque[Tuple[Path, int]] = deque([(artifacts_dir, 0)])
entries_seen = 0
yielded = 0
while pending and entries_seen < _FACTOR_MAX_SCAN_ENTRIES and yielded < max_results:
directory, depth = pending.popleft()
child_directories: List[Path] = []
try:
with os.scandir(directory) as scan:
iterator = iter(scan)
while entries_seen < _FACTOR_MAX_SCAN_ENTRIES:
try:
entry = next(iterator)
except StopIteration:
break
entries_seen += 1
if entry.name.startswith("."):
continue
try:
if entry.is_symlink():
continue
if entry.name == "ic_series.csv" and entry.is_file(follow_symlinks=False):
yield Path(entry.path)
yielded += 1
if yielded >= max_results:
return
elif depth < _FACTOR_MAX_SCAN_DEPTH and entry.is_dir(follow_symlinks=False):
child_directories.append(Path(entry.path))
except OSError:
continue
except OSError:
continue
child_directories.sort(key=lambda path: path.name)
pending.extend((path, depth + 1) for path in child_directories)
def _has_factor_artifacts(run_dir: Path) -> bool:
"""Return whether a bounded directory-entry scan finds a factor bundle."""
candidates = _iter_factor_series_files(run_dir, max_results=1)
try:
return next(candidates, None) is not None
finally:
candidates.close()
def _scan_factor_results(run_dir: Path) -> List[Dict[str, Any]]:
"""Scan a run directory for factor-analysis artifact bundles.
A factor result is any directory under ``run_dir/artifacts`` (recursive)
that contains an ``ic_series.csv`` file. Traversal, nesting, factor count,
file sizes, source rows, columns, and aggregate response inputs are all
bounded. Symlinked directories and files are ignored.
Args:
run_dir: Root directory of the run.
Returns:
Factor result dicts sorted by name ascending.
"""
artifacts_dir = run_dir / "artifacts"
results: List[Dict[str, Any]] = []
remaining_bytes = _FACTOR_MAX_TOTAL_ARTIFACT_BYTES
remaining_rows = _FACTOR_MAX_TOTAL_ROWS
for csv_path in _iter_factor_series_files(run_dir, max_results=_FACTOR_MAX_RESULTS):
try:
relative_dir = csv_path.parent.relative_to(run_dir)
except ValueError:
continue
directory = csv_path.parent
name = "factor_analysis" if directory == artifacts_dir else directory.name
truncated: Dict[str, bool] = {}
ic_rows: List[Dict[str, Any]] = []
ic_readable, ic_size, ic_degraded = _claim_factor_artifact(
csv_path,
max_file_bytes=_FACTOR_MAX_FILE_BYTES,
remaining_bytes=remaining_bytes,
)
if ic_readable:
remaining_bytes -= ic_size
ic_rows, ic_rows_truncated = _load_ic_series_csv(
csv_path,
min(_FACTOR_MAX_ROWS_PER_CSV, remaining_rows),
)
remaining_rows -= len(ic_rows)
if ic_rows_truncated:
truncated["ic_series"] = True
elif ic_degraded:
truncated["ic_series"] = True
summary: Optional[Dict[str, Any]] = None
summary_path = directory / "ic_summary.json"
summary_readable, summary_size, summary_degraded = _claim_factor_artifact(
summary_path,
max_file_bytes=_FACTOR_MAX_SUMMARY_BYTES,
remaining_bytes=remaining_bytes,
)
if summary_readable:
remaining_bytes -= summary_size
summary, summary_parse_degraded = _load_factor_summary(summary_path)
if summary_parse_degraded:
truncated["ic_stats"] = True
elif summary_degraded:
truncated["ic_stats"] = True
equity_rows: List[Dict[str, Any]] = []
equity_cols: List[str] = []
equity_path = directory / "group_equity.csv"
equity_readable, equity_size, equity_degraded = _claim_factor_artifact(
equity_path,
max_file_bytes=_FACTOR_MAX_FILE_BYTES,
remaining_bytes=remaining_bytes,
)
if equity_readable:
remaining_bytes -= equity_size
equity_rows, equity_cols, equity_rows_truncated = _load_group_equity_csv(
equity_path,
min(_FACTOR_MAX_ROWS_PER_CSV, remaining_rows),
)
remaining_rows -= len(equity_rows)
if equity_rows_truncated:
truncated["group_equity"] = True
elif equity_degraded:
truncated["group_equity"] = True
group_cols = [col for col in equity_cols if col.startswith("Group_")]
spread_cols = group_cols or equity_cols
long_short_spread: Optional[float] = None
group_final_equity: Dict[str, Any] = {}
if equity_rows and spread_cols:
last_row = equity_rows[-1]
first_value = last_row.get(spread_cols[0])
last_value = last_row.get(spread_cols[-1])
if first_value is not None and last_value is not None:
spread = last_value - first_value
if math.isfinite(spread):
long_short_spread = round(spread, 6)
group_final_equity = {col: last_row[col] for col in equity_cols if col in last_row}
entry: Dict[str, Any] = {
"name": name,
"path": relative_dir.as_posix(),
"ic_series": ic_rows,
}
if isinstance(summary, dict):
entry["ic_stats"] = summary
entry["group_equity"] = equity_rows
entry["n_groups"] = len(group_cols)
entry["long_short_spread"] = long_short_spread
entry["group_final_equity"] = group_final_equity
if truncated:
entry["truncated"] = truncated
results.append(entry)
results.sort(key=lambda item: (str(item["name"]), str(item["path"])))
return results
def _pearson_correlation(x_values: List[float], y_values: List[float]) -> float:
"""Compute Pearson correlation, degrading to 0.0 for degenerate input.
Args:
x_values: First series of values.
y_values: Second series of values (same length).
Returns:
Pearson correlation in [-1, 1], or 0.0 when a variance is zero.
"""
try:
correlation = statistics.correlation(x_values, y_values)
except (statistics.StatisticsError, ValueError, OverflowError, ZeroDivisionError):
return 0.0
if not math.isfinite(correlation):
return 0.0
return max(-1.0, min(1.0, correlation))
def _factor_ic_correlation(factors: List[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
"""Build the pairwise IC correlation matrix across factor results.
Args:
factors: Factor result dicts from ``_scan_factor_results``.
Returns:
Labels plus a symmetric Pearson correlation matrix rounded to four
decimals, or ``None`` when fewer than two factors exist or any pair
shares fewer than 10 dates.
"""
if len(factors) < 2:
return None
series: List[Dict[str, float]] = []
for factor in factors:
series.append({str(row["date"]): float(row["ic"]) for row in factor.get("ic_series") or []})
for i in range(len(series)):
for j in range(i + 1, len(series)):
if len(series[i].keys() & series[j].keys()) < 10:
return None
size = len(series)
matrix: List[List[float]] = [[1.0 if i == j else 0.0 for j in range(size)] for i in range(size)]
for i in range(size):
for j in range(i + 1, size):
common_dates = sorted(series[i].keys() & series[j].keys())
x_values = [series[i][date] for date in common_dates]
y_values = [series[j][date] for date in common_dates]
correlation = round(_pearson_correlation(x_values, y_values), 4)
matrix[i][j] = correlation
matrix[j][i] = correlation
return {"labels": [str(factor["name"]) for factor in factors], "matrix": matrix}
# Bounded contract for /runs/{run_id}/positions/sectors: at most
# _POSITIONS_SECTOR_MAX_SYMBOLS symbols get a network industry lookup (excess
# symbols degrade to asset-class-only grouping), lookups run on ONE shared
# module-level executor with _POSITIONS_SECTOR_WORKERS threads (created lazily
# on first use and never shut down — process-lifetime — so concurrent requests
# share a single bounded pool instead of spawning one per request), and each
# HTTP call carries the shared Eastmoney client's 15-second socket timeout.
_POSITIONS_SECTOR_MAX_SYMBOLS = 200
_POSITIONS_SECTOR_WORKERS = 4
_POSITIONS_SECTOR_EXECUTOR: Optional[ThreadPoolExecutor] = None
_POSITIONS_SECTOR_EXECUTOR_LOCK = threading.Lock()
def _get_positions_sector_executor() -> ThreadPoolExecutor:
"""Return the shared, process-lifetime industry-lookup executor.
Created lazily on first use with ``_POSITIONS_SECTOR_WORKERS`` workers and
never shut down, so every request fans out onto the same bounded pool.
Returns:
The shared executor instance.
"""
global _POSITIONS_SECTOR_EXECUTOR
if _POSITIONS_SECTOR_EXECUTOR is None:
with _POSITIONS_SECTOR_EXECUTOR_LOCK:
if _POSITIONS_SECTOR_EXECUTOR is None:
_POSITIONS_SECTOR_EXECUTOR = ThreadPoolExecutor(
max_workers=_POSITIONS_SECTOR_WORKERS,
thread_name_prefix="positions-sector",
)
return _POSITIONS_SECTOR_EXECUTOR
def _read_positions_symbols(path: Path) -> List[str]:
"""Read the symbol column names from a wide-format ``positions.csv``.
Args:
path: Path to ``artifacts/positions.csv`` (header
``timestamp,<sym1>,<sym2>,...``).
Returns:
Symbol column names in file order; empty when the file is missing,
a symlink, empty, or unreadable.
"""
try:
if not path.exists() or path.is_symlink():
return []
with path.open("r", encoding="utf-8", newline="") as handle:
fieldnames = csv.DictReader(handle).fieldnames
except Exception:
return []
if not fieldnames:
return []
return [name.strip() for name in fieldnames[1:] if name and name.strip()]
def _resolve_industries_concurrent(symbols: List[str]) -> Dict[str, Optional[str]]:
"""Resolve A-share industry boards with bounded concurrency.
Args:
symbols: A-share symbols to resolve (already capped by the caller).
Returns:
Mapping of symbol -> industry board name, or ``None`` when the lookup
failed or found no board row. Never raises.
"""
from src.tools.sector_tool import resolve_industry_board
results: Dict[str, Optional[str]] = {}
pool = _get_positions_sector_executor()
futures = {pool.submit(resolve_industry_board, symbol): symbol for symbol in symbols}
for future in as_completed(futures):
symbol = futures[future]
try:
results[symbol] = future.result()
except Exception: # noqa: BLE001 - one failure must not abort the batch
results[symbol] = None
return results
def _build_positions_sector_map(run_dir: Path, run_id: str, *, refresh: bool) -> Dict[str, Any]:
"""Resolve asset class + A-share industry for a run's position symbols.
Serves from the ``artifacts/sector_map.json`` cache when a valid cache
exists and ``refresh`` is false; otherwise recomputes and rewrites the
cache. A corrupt cache file is treated as a cache miss.
Blocking work here (file reads plus throttled Eastmoney HTTP) is bounded
by the module-level contract: at most ``_POSITIONS_SECTOR_MAX_SYMBOLS``
network lookups, ``_POSITIONS_SECTOR_WORKERS`` concurrent workers, and the
shared Eastmoney client's 15-second per-request socket timeout. Symbols
beyond the cap keep their asset class but skip industry resolution. The
caller must run this off the event loop (see ``run_in_threadpool``).
Args:
run_dir: Persisted run directory containing ``artifacts/``.
run_id: Run identifier echoed back in the response envelope.
refresh: True bypasses the disk cache.
Returns:
The envelope ``{"ok", "run_id", "resolved_at", "cached", "symbols",
"unresolved", "total_symbols", "symbol_limit"}``, or the ``{"ok",
"run_id", "symbols", "note"}`` form when no positions artifact exists.
"""
from backtest.engines._market_hooks import _detect_market
artifacts_dir = run_dir / "artifacts"
cache_path = artifacts_dir / "sector_map.json"
try:
symlinked = artifacts_dir.is_symlink() or cache_path.is_symlink()
except OSError:
symlinked = False
if symlinked:
# Mirror the factor scan's symlink rejection: a symlinked artifacts dir
# — or a symlinked sector_map.json cache file inside a real one — is
# treated as having no positions artifact rather than followed, so
# neither the cache read nor the cache rewrite can escape the run dir.
return {"ok": True, "run_id": run_id, "symbols": {}, "note": "no positions artifact"}
if not refresh:
cached = load_json_file(cache_path)
if isinstance(cached, dict) and isinstance(cached.get("symbols"), dict):
cached["cached"] = True
cached["run_id"] = run_id
return cached
symbols = _read_positions_symbols(run_dir / "artifacts" / "positions.csv")
if not symbols:
return {"ok": True, "run_id": run_id, "symbols": {}, "note": "no positions artifact"}
resolved: Dict[str, Any] = {}
a_share_to_resolve: List[str] = []
for symbol in symbols:
asset_class = _detect_market(symbol)
resolved[symbol] = {
"asset_class": asset_class,
"industry": None,
"industry_source": None,
}
# The budget counts A-share network lookups only — non-A-share symbols
# never consume it, so a mixed book with a long non-A-share prefix
# still resolves its first _POSITIONS_SECTOR_MAX_SYMBOLS A-shares.
if asset_class == "a_share" and len(a_share_to_resolve) < _POSITIONS_SECTOR_MAX_SYMBOLS:
a_share_to_resolve.append(symbol)
if a_share_to_resolve:
for symbol, industry in _resolve_industries_concurrent(a_share_to_resolve).items():
if industry is not None:
resolved[symbol]["industry"] = industry
resolved[symbol]["industry_source"] = "eastmoney"
unresolved = [
symbol
for symbol in symbols
if resolved[symbol]["asset_class"] == "a_share" and resolved[symbol]["industry"] is None
]
payload: Dict[str, Any] = {
"ok": True,
"run_id": run_id,
"resolved_at": datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z"),
"cached": False,
"symbols": resolved,
"unresolved": unresolved,
"total_symbols": len(symbols),
"symbol_limit": _POSITIONS_SECTOR_MAX_SYMBOLS,
}
tmp_path = cache_path.with_name(f".sector_map.{os.getpid()}.{threading.get_ident()}.tmp")
try:
cache_path.parent.mkdir(parents=True, exist_ok=True)
tmp_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
os.replace(tmp_path, cache_path)
except OSError:
try:
tmp_path.unlink(missing_ok=True)
except OSError:
pass
return payload
def _run_response_payload(response: Any) -> Dict[str, Any]:
"""Return a JSON-ready payload for opt-in run response variants."""
return response.model_dump(mode="json")
def _render_run_result(
run_dir: Path,
chart_symbol: Optional[str],
chart_payload: Optional[str],
) -> Response:
"""Build and serialize a run detail response.
Full responses reach tens of megabytes, so both the build and the JSON
encoding run here, off the event loop; returning the model instead would
leave FastAPI to encode it on the loop and stall every other request.
Args:
run_dir: Existing run directory.
chart_symbol: Optional single chart symbol.
chart_payload: Optional chart payload mode.
Returns:
A rendered JSON response.
"""
wants_chart_meta = bool(chart_payload or chart_symbol)
chart_symbols: List[str] = []
response = _build_response_from_run_dir(
run_dir,
elapsed=0.0,
include_analysis=True,
chart_symbol=chart_symbol,
chart_payload=chart_payload or "full",
chart_symbols_out=chart_symbols if wants_chart_meta else None,
)
if wants_chart_meta:
payload = _run_response_payload(response)
payload["chart_symbols"] = chart_symbols
return JSONResponse(payload)
return Response(
content=response.model_dump_json(by_alias=True), media_type="application/json"
)
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,
*,
include_analysis: bool = False,
chart_symbol: Optional[str] = None,
chart_payload: str = "full",
chart_symbols_out: Optional[List[str]] = None,
):
"""Build a run response from a persisted run directory."""
import sys as _sys
host = _sys.modules.get("api_server") or _sys.modules.get("agent.api_server")
RunResponse = host.RunResponse
RAGSelection = host.RAGSelection
Artifact = host.Artifact
run_id = run_dir.name
response = RunResponse(
status="unknown",
run_id=run_id,
elapsed_seconds=elapsed,
run_directory=str(run_dir),
)
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":
response.status = "success"
elif state_status in {"failed", "cancelled"}:
response.status = state_status
response.reason = state_data.get("reason", "")
else:
response.status = state_status or "unknown"
else:
response.status = "unknown"
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)
design_path = run_dir / "design_spec.json"
response.strategy_spec = load_json_file(design_path)
rag_path = run_dir / "rag_metadata.json"
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", ""),
selected_name=rag_data.get("selected_name") or rag_data.get("api_name", ""),
selected_score=float(rag_data.get("selected_score") or rag_data.get("score", 0.0)),
)
response.metrics = load_backtest_metrics(run_dir)
artifacts_dir = run_dir / "artifacts"
if artifacts_dir.exists():
for file_path in artifacts_dir.iterdir():
if file_path.is_file():
file_type = file_path.suffix.lstrip(".")
response.artifacts.append(
Artifact(
name=file_path.name,
path=str(file_path),
type=file_type if file_type else "unknown",
size=file_path.stat().st_size,
exists=True,
)
)
response.has_factor_artifacts = _has_factor_artifacts(run_dir)
equity_path = run_dir / "artifacts" / "equity.csv"
if equity_path.exists():
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_records(metrics_csv_path)
run_card_path = run_dir / "run_card.json"
if run_card_path.exists():
try:
response.run_card = json.loads(run_card_path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError):
pass
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")
if rebalance_notes is not None:
response.rebalance_notes = rebalance_notes
llm_usage_path = run_dir / "llm_usage.json"
if llm_usage_path.exists():
try:
response.llm_usage = json.loads(llm_usage_path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError):
pass
trades_path = run_dir / "artifacts" / "trades.csv"
if trades_path.exists():
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_records(positions_path)
target_positions_path = run_dir / "artifacts" / "target_positions.csv"
if target_positions_path.exists():
response.artifacts_target_positions_csv = load_csv_records(
target_positions_path
)
validation_path = run_dir / "artifacts" / "validation.json"
if validation_path.exists():
try:
response.validation = json.loads(validation_path.read_text(encoding="utf-8"))
except (json.JSONDecodeError, OSError):
pass
if response.artifacts_equity_csv:
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]
if include_analysis:
from src.ui_services import build_run_analysis
analysis = build_run_analysis(
run_dir,
symbols=[chart_symbol] if chart_symbol else None,
include_payload=chart_payload != "summary" or bool(chart_symbol),
include_symbol_list=chart_symbols_out is not None,
)
if chart_symbols_out is not None:
chart_symbols_out.extend(analysis.get("chart_symbols") or [])
response.run_stage = analysis.get("run_stage")
response.run_context = analysis.get("run_context")
response.price_series = analysis.get("price_series")
response.indicator_series = analysis.get("indicator_series")
response.trade_markers = analysis.get("trade_markers")
response.run_logs = analysis.get("run_logs")
return response
# ---------------------------------------------------------------------------
# Registration
# ---------------------------------------------------------------------------
AuthDep = Callable[..., Awaitable[Any] | Any]
def register_runs_routes(
app: FastAPI,
require_auth: AuthDep | None = None,
) -> None:
"""Mount the runs routes onto ``app``.
Resolves ``require_auth`` from the host ``api_server`` module via
``sys.modules`` when not passed explicitly.
"""
import sys as _sys
host = _sys.modules.get("api_server") or _sys.modules.get("agent.api_server")
if host is None:
raise RuntimeError(
"register_runs_routes: api_server module not in sys.modules; "
"ensure api_server is imported before calling this function"
)
if require_auth is None:
require_auth = host.require_auth
# Late-access closures for shared host symbols (monkeypatch-safe)
def _host_validate_path_param(value: str, kind: str) -> None:
h = _sys.modules.get("api_server") or _sys.modules.get("agent.api_server")
return h._validate_path_param(value, kind)
def _host_RUNS_DIR() -> Path:
h = _sys.modules.get("api_server") or _sys.modules.get("agent.api_server")
return h.RUNS_DIR
# Pydantic models for response_model (resolved at registration time)
RunResponse = host.RunResponse
RunInfo = host.RunInfo
# --- Routes ---
@app.get("/runs/{run_id}/code", dependencies=[Depends(require_auth)])
async def get_run_code(run_id: str):
"""Return strategy source files for a run.
Args:
run_id: Run identifier.
Returns:
Map filename -> source text.
"""
_host_validate_path_param(run_id, "run_id")
run_dir = _host_RUNS_DIR() / run_id / "code"
if not run_dir.exists():
raise HTTPException(status_code=404, detail=f"Code directory for run {run_id} not found")
result = {}
for f in ["signal_engine.py"]:
p = run_dir / f
if p.exists():
result[f] = p.read_text(encoding="utf-8")
return result
@app.get("/runs/{run_id}/pine", dependencies=[Depends(require_auth)])
async def get_run_pine(run_id: str):
"""Return Pine Script file for a run.
Args:
run_id: Run identifier.
Returns:
Object with pine script content and exists flag.
"""
_host_validate_path_param(run_id, "run_id")
pine_path = _host_RUNS_DIR() / run_id / "artifacts" / "strategy.pine"
if not pine_path.exists():
return {"exists": False, "content": None}
return {
"exists": True,
"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.
Args:
run_id: Run identifier.
Returns:
Object with exists flag, factor results sorted by name, and the
pairwise IC correlation matrix (null when not computable).
"""
_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"
)
factors = await run_in_threadpool(_scan_factor_results, run_dir)
if not factors:
return {"exists": False, "factors": [], "ic_correlation": None}
return {
"exists": True,
"factors": factors,
"ic_correlation": _factor_ic_correlation(factors),
}
# 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"),
chart_payload: Optional[str] = Query(
None,
description="Optional chart payload mode. Use 'summary' to omit chart rows and trade markers.",
),
):
"""Fetch details for a historical run by ``run_id``.
The default response stays unchanged for existing consumers. Chart-heavy
optimizations are opt-in via query parameters.
"""
_host_validate_path_param(run_id, "run_id")
if chart_payload not in (None, "summary"):
raise HTTPException(status_code=400, detail="invalid chart_payload")
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_result, run_dir, chart_symbol, chart_payload
)
@app.get("/runs/{run_id}/positions/sectors", dependencies=[Depends(require_auth)])
async def get_run_positions_sectors(
run_id: str,
refresh: int = Query(0, description="Set to 1 to bypass the disk cache and recompute."),
):
"""Resolve asset class + A-share industry for a run's position symbols.
Read-only classification over ``artifacts/positions.csv``, cached in
``artifacts/sector_map.json``. The blocking classification (file reads
plus throttled Eastmoney lookups) runs in the FastAPI threadpool so it
never stalls the event loop, and is bounded by
``_POSITIONS_SECTOR_MAX_SYMBOLS`` / ``_POSITIONS_SECTOR_WORKERS`` /
the shared client's 15-second per-request timeout.
Args:
run_id: Run identifier.
refresh: ``1`` bypasses the disk cache, ``0`` (default) serves it.
Returns:
The sector-map envelope built by ``_build_positions_sector_map``.
Raises:
HTTPException: 404 when the run directory does not exist.
"""
_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(
_build_positions_sector_map, run_dir, run_id, refresh=bool(refresh)
)
@app.get("/runs", response_model=List[RunInfo], dependencies=[Depends(require_auth)])
async def list_runs(limit: int = 20):
"""List recent runs with summary fields."""
from src.ui_services import load_run_context
limit = min(max(1, limit), 100)
runs_dir = _host_RUNS_DIR()
if not runs_dir.exists():
return []
run_dirs = sorted(
[d for d in runs_dir.iterdir() if d.is_dir()],
key=lambda x: x.name,
reverse=True
)
results = []
for d in run_dirs[:limit]:
run_id = d.name
# Status from state.json or artifacts
status_val = "unknown"
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():
status_val = "success"
elif (d / "review_report.json").exists():
status_val = "success"
# Parse created_at from run_id (YYYYMMDD_HHMMSS or run_YYYYMMDD_HHMMSS)
created_at = "Unknown"
if run_id.startswith("run_"):
parts = run_id.split('_')
if len(parts) >= 3:
d_str, t_str = parts[1], parts[2]
if len(d_str) == 8 and len(t_str) == 6:
created_at = f"{d_str[:4]}-{d_str[4:6]}-{d_str[6:8]} {t_str[:2]}:{t_str[2:4]}:{t_str[4:6]}"
elif "_" in run_id:
parts = run_id.split('_')
if len(parts) >= 2:
d_str, t_str = parts[0], parts[1]
if len(d_str) == 8 and len(t_str) == 6:
created_at = f"{d_str[:4]}-{d_str[4:6]}-{d_str[6:8]} {t_str[:2]}:{t_str[2:4]}:{t_str[4:6]}"
if created_at == "Unknown":
mtime = datetime.fromtimestamp(d.stat().st_mtime)
created_at = mtime.strftime("%Y-%m-%d %H:%M:%S")
prompt = None
req_file = d / "req.json"
planner_file = d / "planner_output.json"
if req_file.exists():
try:
req_data = json.loads(req_file.read_text(encoding="utf-8"))
prompt = req_data.get("prompt")
except (json.JSONDecodeError, OSError):
pass
if not prompt and planner_file.exists():
try:
planner_data = json.loads(planner_file.read_text(encoding="utf-8"))
prompt = planner_data.get("user_goal") or planner_data.get("goal")
except (json.JSONDecodeError, OSError):
pass
if not prompt:
prompt_file = d / "user_prompt.txt"
if prompt_file.exists():
prompt = prompt_file.read_text(encoding="utf-8").strip()
total_return = None
sharpe = None
metrics_file = d / "artifacts" / "metrics.csv"
if metrics_file.exists():
try:
with open(metrics_file, 'r', encoding='utf-8') as f:
reader = csv.DictReader(f)
for row in reader:
total_return = float(row.get('total_return', 0) or 0)
sharpe = float(row.get('sharpe', 0) or 0)
break
except (OSError, ValueError):
pass
run_context = load_run_context(d)
results.append(RunInfo(
run_id=run_id,
status=status_val,
created_at=created_at,
prompt=prompt or "Manual Analysis",
total_return=total_return,
sharpe=sharpe,
codes=run_context.get("codes") or [],
start_date=run_context.get("start_date"),
end_date=run_context.get("end_date"),
))
return results