- README.md rewritten with verified counts (68 routes, 21 crates, 9 apps, 7 skills, 63 dashboard pages); + docs/QUICKSTART.md. - clients/typescript: CLI watch subcommand (interval/once/json, SIGINT-clean, offline-safe). - python-lab: correlation.py (pure-python Pearson matrix + exposure/HHI) + analyze.py correlation subcommand. - dashboard: /analytics overview page (equity/drawdown/regime/exposure). tsc clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1032 lines
33 KiB
Python
1032 lines
33 KiB
Python
#!/usr/bin/env python3
|
|
"""Standalone analytics CLI for Guardrail Alpha.
|
|
|
|
Subcommands:
|
|
|
|
regime Regime-transition matrix, time-in-regime, exposure multipliers.
|
|
drawdown Underwater curve, max drawdown, and worst drawdown episodes.
|
|
montecarlo IID bootstrap risk simulation over the NAV curve (VaR/CVaR).
|
|
dossier One Markdown research dossier synthesizing every analytic.
|
|
ensemble Blended target book + attribution across the 4 Track-2 skills.
|
|
ensemble-compare Blend vs. each single skill: concentration / overlap.
|
|
journal Human-readable per-cycle decision journal from the event log.
|
|
|
|
Both subcommands load real data from the event-log database and the agent's
|
|
run report when those files exist, and print a readable text report. When no
|
|
data files are present they print a clear "no data" message and exit 0 (they
|
|
never crash on missing data).
|
|
|
|
Usage (from the repository root)::
|
|
|
|
python3 python-lab/analyze.py regime
|
|
python3 python-lab/analyze.py drawdown --db data/guardrail_alpha.db
|
|
python3 python-lab/analyze.py dossier --out data/dossier.md
|
|
|
|
Standard-library only.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import sys
|
|
from datetime import timedelta
|
|
from pathlib import Path
|
|
|
|
# Make ``guardrail_lab`` importable whether this file is run as a script from
|
|
# the repo root (python3 python-lab/analyze.py) or from within python-lab.
|
|
_PACKAGE_ROOT = Path(__file__).resolve().parent
|
|
if str(_PACKAGE_ROOT) not in sys.path:
|
|
sys.path.insert(0, str(_PACKAGE_ROOT))
|
|
|
|
from guardrail_lab import correlation as co # noqa: E402
|
|
from guardrail_lab import dossier as ds # noqa: E402
|
|
from guardrail_lab import dossier_html as dsh # noqa: E402
|
|
from guardrail_lab import drawdown as dd # noqa: E402
|
|
from guardrail_lab import ensemble as en # noqa: E402
|
|
from guardrail_lab import ensemble_compare as ec # noqa: E402
|
|
from guardrail_lab import journal as jn # noqa: E402
|
|
from guardrail_lab import journal_html as jnh # noqa: E402
|
|
from guardrail_lab import montecarlo as mc # noqa: E402
|
|
from guardrail_lab import regime_analysis as ra # noqa: E402
|
|
from guardrail_lab import report_bundle as rb # noqa: E402
|
|
from guardrail_lab import seed as sd # noqa: E402
|
|
from guardrail_lab.db import load_events # noqa: E402
|
|
from guardrail_lab.metrics import nav_series # noqa: E402
|
|
|
|
DEFAULT_DB = "data/guardrail_alpha.db"
|
|
DEFAULT_REPORT = "data/run_report.json"
|
|
DEFAULT_ENSEMBLE_CONFIG = "skills/ensemble.json"
|
|
DEFAULT_SKILLS_ROOT = "skills"
|
|
DEFAULT_SNAPSHOT_DIR = co.DEFAULT_SNAPSHOT_DIR
|
|
DEFAULT_REGIME = "risk_on"
|
|
DEFAULT_BUNDLE_OUT = rb.DEFAULT_OUT_DIR
|
|
NO_DATA_MESSAGE = (
|
|
"no data — run the agent first "
|
|
"(expected event log and/or run report under data/)."
|
|
)
|
|
|
|
|
|
def _format_seconds(seconds: float | None) -> str:
|
|
"""Render a duration in seconds as a compact human-readable string."""
|
|
if seconds is None:
|
|
return "n/a"
|
|
if seconds <= 0:
|
|
return "0s"
|
|
return str(timedelta(seconds=round(seconds)))
|
|
|
|
|
|
def _print_header(title: str) -> None:
|
|
"""Print a section header underlined to its width."""
|
|
print(title)
|
|
print("=" * len(title))
|
|
|
|
|
|
def run_regime(db_path: str) -> int:
|
|
"""Load events and print the regime analytics report.
|
|
|
|
Returns the process exit code (always ``0``: missing data is reported, not
|
|
an error).
|
|
"""
|
|
events = load_events(db_path)
|
|
if not events:
|
|
print(NO_DATA_MESSAGE)
|
|
print(f"(looked for event log at: {db_path})")
|
|
return 0
|
|
|
|
analysis = ra.analyze_regimes(events)
|
|
|
|
_print_header("Guardrail Alpha — Regime Analysis")
|
|
print(f"Event log: {db_path}")
|
|
print(f"Events: {len(events)}")
|
|
print()
|
|
|
|
print("Time in Regime")
|
|
print("-" * 14)
|
|
if analysis.time_in_regime:
|
|
for entry in analysis.time_in_regime:
|
|
print(
|
|
f" {entry.regime:<12} "
|
|
f"classifications={entry.classifications:<4} "
|
|
f"share={entry.fraction * 100:6.2f}% "
|
|
f"time={_format_seconds(entry.seconds)}"
|
|
)
|
|
else:
|
|
print(" (no regime classifications recorded)")
|
|
print()
|
|
|
|
print("Transition Matrix (counts -> P)")
|
|
print("-" * 31)
|
|
matrix = analysis.transitions
|
|
if matrix.total_transitions:
|
|
for source in matrix.regimes:
|
|
row = matrix.counts[source]
|
|
successors = [
|
|
f"{target}: {row[target]} "
|
|
f"({matrix.probabilities[source][target] * 100:.0f}%)"
|
|
for target in matrix.regimes
|
|
if row[target] > 0
|
|
]
|
|
if successors:
|
|
print(f" {source:<12} -> " + ", ".join(successors))
|
|
print(f" total transitions: {matrix.total_transitions}")
|
|
else:
|
|
print(" (need at least two classifications for transitions)")
|
|
print()
|
|
|
|
print("Average Exposure Multiplier per Regime")
|
|
print("-" * 38)
|
|
if analysis.exposure:
|
|
for entry in analysis.exposure:
|
|
print(
|
|
f" {entry.regime:<12} "
|
|
f"orders={entry.order_count:<4} "
|
|
f"avg_order=${entry.avg_order_usd:,.2f} "
|
|
f"multiplier={entry.exposure_multiplier:.2f}x"
|
|
)
|
|
else:
|
|
print(" (no orders proposed)")
|
|
print()
|
|
|
|
return 0
|
|
|
|
|
|
def run_drawdown(db_path: str, top_n: int) -> int:
|
|
"""Load the NAV curve and print the drawdown report.
|
|
|
|
Returns the process exit code (always ``0``).
|
|
"""
|
|
events = load_events(db_path)
|
|
curve = nav_series(events) if events else []
|
|
if not curve:
|
|
print(NO_DATA_MESSAGE)
|
|
print(f"(looked for event log at: {db_path})")
|
|
return 0
|
|
|
|
report = dd.analyze_drawdown(curve, top_n=top_n)
|
|
|
|
_print_header("Guardrail Alpha — Drawdown Analysis")
|
|
print(f"Event log: {db_path}")
|
|
print(f"NAV points: {len(curve)}")
|
|
print(f"First NAV: ${curve[0][1]:,.2f} Last NAV: ${curve[-1][1]:,.2f}")
|
|
print()
|
|
|
|
print("Max Drawdown")
|
|
print("-" * 12)
|
|
print(f" depth: {report.max_drawdown_pct:.4f}%")
|
|
print(f" peak: {report.peak_timestamp or 'n/a'}")
|
|
print(f" trough: {report.trough_timestamp or 'n/a'}")
|
|
print(f" duration: {_format_seconds(report.max_drawdown_seconds)}")
|
|
print(f" recovery time: {_format_seconds(report.max_recovery_seconds)}")
|
|
print()
|
|
|
|
print(f"Top {top_n} Worst Drawdown Episodes")
|
|
print("-" * 30)
|
|
if report.episodes:
|
|
for index, episode in enumerate(report.episodes, start=1):
|
|
status = "recovered" if episode.recovered else "UNRECOVERED"
|
|
print(
|
|
f" {index}. {episode.depth_pct:.4f}% "
|
|
f"peak ${episode.peak_nav:,.2f} @ {episode.peak_timestamp} -> "
|
|
f"trough ${episode.trough_nav:,.2f} @ "
|
|
f"{episode.trough_timestamp}"
|
|
)
|
|
print(
|
|
f" duration={_format_seconds(episode.drawdown_seconds)} "
|
|
f"recovery={_format_seconds(episode.recovery_seconds)} "
|
|
f"[{status}]"
|
|
)
|
|
else:
|
|
print(" (no drawdown episodes — NAV never declined from its peak)")
|
|
print()
|
|
|
|
return 0
|
|
|
|
|
|
def run_montecarlo(
|
|
db_path: str,
|
|
n_paths: int,
|
|
seed: int,
|
|
dd_threshold_pct: float,
|
|
) -> int:
|
|
"""Run an IID bootstrap risk simulation over the NAV curve and print it.
|
|
|
|
Returns the process exit code (always ``0``: missing/short data is reported,
|
|
not an error). ``dd_threshold_pct`` is given in percent (e.g. ``24`` for the
|
|
kill-switch level) and converted to a fraction for the simulator.
|
|
"""
|
|
events = load_events(db_path)
|
|
curve = nav_series(events) if events else []
|
|
if not curve:
|
|
print(NO_DATA_MESSAGE)
|
|
print(f"(looked for event log at: {db_path})")
|
|
return 0
|
|
|
|
threshold = max(0.0, dd_threshold_pct) / 100.0
|
|
report = mc.bootstrap(
|
|
curve, n_paths=n_paths, seed=seed, dd_threshold=threshold
|
|
)
|
|
|
|
_print_header("Guardrail Alpha — Monte Carlo Risk (IID bootstrap)")
|
|
print(f"Event log: {db_path}")
|
|
print(f"NAV points: {len(curve)} Start NAV: ${report.start_nav:,.2f}")
|
|
if not report.ok:
|
|
print()
|
|
print(f" (not simulated: {report.reason})")
|
|
print()
|
|
return 0
|
|
|
|
print(
|
|
f"Paths: {report.n_paths} Horizon: {report.horizon} steps "
|
|
f"Seed: {report.seed} Returns sampled: {report.n_returns}"
|
|
)
|
|
print()
|
|
|
|
print("Terminal Return Percentiles")
|
|
print("-" * 27)
|
|
for pct in (5.0, 25.0, 50.0, 75.0, 95.0):
|
|
ret = report.terminal_return_percentiles.get(pct)
|
|
nav = report.terminal_nav_percentiles.get(pct)
|
|
if ret is not None:
|
|
print(
|
|
f" p{int(pct):<3} return={ret * 100:7.2f}% "
|
|
f"NAV=${nav:,.2f}"
|
|
)
|
|
print(f" mean return={report.terminal_return_mean * 100:7.2f}%")
|
|
print()
|
|
|
|
print("Tail Risk — Terminal Loss")
|
|
print("-" * 25)
|
|
for level in sorted(report.var_terminal):
|
|
tail = report.var_terminal[level]
|
|
print(
|
|
f" {int(level * 100)}% VaR={tail.var * 100:6.2f}% "
|
|
f"CVaR={tail.cvar * 100:6.2f}%"
|
|
)
|
|
print()
|
|
|
|
print("Tail Risk — Worst Drawdown")
|
|
print("-" * 26)
|
|
for level in sorted(report.var_drawdown):
|
|
tail = report.var_drawdown[level]
|
|
print(
|
|
f" {int(level * 100)}% VaR={tail.var * 100:6.2f}% "
|
|
f"CVaR={tail.cvar * 100:6.2f}%"
|
|
)
|
|
print(
|
|
f" mean worst drawdown across paths="
|
|
f"{report.worst_drawdowns_mean * 100:.2f}%"
|
|
)
|
|
print()
|
|
|
|
print(
|
|
f"P(drawdown breaches {dd_threshold_pct:g}%) = "
|
|
f"{report.prob_breach * 100:.2f}%"
|
|
)
|
|
print()
|
|
|
|
return 0
|
|
|
|
|
|
def run_dossier(
|
|
db_path: str,
|
|
report_path: str,
|
|
out_path: str | None,
|
|
as_html: bool,
|
|
) -> int:
|
|
"""Build the research dossier (Markdown or HTML) and print it to stdout.
|
|
|
|
Always exits ``0``. When no data files exist the underlying builders
|
|
return a clear "no data — run the agent first" skeleton rather than
|
|
raising, so the command remains safe to run on a fresh checkout. When
|
|
``out_path`` is provided the dossier is also written to that file.
|
|
|
|
HTML output is selected by either the ``as_html`` flag or an ``out_path``
|
|
whose name ends in ``.html``/``.htm``; otherwise Markdown is emitted. In
|
|
HTML mode the result is a single self-contained document (inline dark-theme
|
|
CSS, no external CSS/JS/CDN references) produced by
|
|
:func:`dsh.build_dossier_html`, which reuses :func:`ds.build_dossier`.
|
|
"""
|
|
wants_html = as_html or (
|
|
out_path is not None and out_path.lower().endswith((".html", ".htm"))
|
|
)
|
|
|
|
if wants_html:
|
|
document = dsh.build_dossier_html(db_path, report_path)
|
|
if out_path:
|
|
dsh.write_dossier_html(
|
|
out_path, db_path=db_path, report_path=report_path
|
|
)
|
|
print(document)
|
|
else:
|
|
markdown = ds.build_dossier(db_path, report_path)
|
|
if out_path:
|
|
ds.write_dossier(
|
|
out_path, db_path=db_path, report_path=report_path
|
|
)
|
|
print(markdown)
|
|
|
|
if out_path:
|
|
print(f"\n(wrote dossier to: {out_path})", file=sys.stderr)
|
|
return 0
|
|
|
|
|
|
def _latest_regime_from_db(db_path: str) -> str | None:
|
|
"""Return the most recent classified regime from the event log, if any.
|
|
|
|
Reuses the existing event loader and regime sequence helper rather than
|
|
re-querying the database. Returns ``None`` when no usable classification
|
|
exists (missing DB, no ``regime_classified`` events, or unknown labels).
|
|
"""
|
|
events = load_events(db_path)
|
|
if not events:
|
|
return None
|
|
sequence = ra.regime_sequence(events)
|
|
for _timestamp, regime in reversed(sequence):
|
|
if regime and regime != ra.UNKNOWN_REGIME:
|
|
return regime
|
|
return None
|
|
|
|
|
|
def run_ensemble(
|
|
regime: str | None,
|
|
config_path: str,
|
|
skills_root: str,
|
|
db_path: str,
|
|
) -> int:
|
|
"""Blend the four Track-2 skills for a regime and print the result.
|
|
|
|
When ``regime`` is ``None`` the current regime is taken from the event log
|
|
if present, otherwise it falls back to :data:`DEFAULT_REGIME`. Always exits
|
|
``0``: a missing config or regime is reported via the rendered result, not
|
|
raised.
|
|
"""
|
|
resolved = regime
|
|
source = "explicit --regime"
|
|
if resolved is None:
|
|
resolved = _latest_regime_from_db(db_path)
|
|
if resolved is not None:
|
|
source = f"current regime from {db_path}"
|
|
else:
|
|
resolved = DEFAULT_REGIME
|
|
source = "default (no regime in data)"
|
|
|
|
result = en.blend_regime(
|
|
resolved, config_path=config_path, skills_root=skills_root
|
|
)
|
|
print(en.render_markdown(result))
|
|
print(f"\n(regime source: {source})", file=sys.stderr)
|
|
return 0
|
|
|
|
|
|
def run_ensemble_compare(
|
|
regime: str | None,
|
|
do_all: bool,
|
|
config_path: str,
|
|
skills_root: str,
|
|
db_path: str,
|
|
) -> int:
|
|
"""Compare the blended ensemble book against each single skill, per regime.
|
|
|
|
With ``do_all`` (``--all``) every known regime is compared and the sections
|
|
are joined into one Markdown document. Otherwise a single regime is
|
|
compared: an explicit ``--regime`` if given, else the current regime from
|
|
the event log, else :data:`DEFAULT_REGIME`. Always exits ``0``: a missing
|
|
config or absent skill examples are reported via the rendered output, not
|
|
raised.
|
|
"""
|
|
if do_all:
|
|
comparisons = ec.compare_all(
|
|
config_path=config_path, skills_root=skills_root
|
|
)
|
|
print(ec.render_markdown_all(comparisons))
|
|
print("\n(compared all regimes)", file=sys.stderr)
|
|
return 0
|
|
|
|
resolved = regime
|
|
source = "explicit --regime"
|
|
if resolved is None:
|
|
resolved = _latest_regime_from_db(db_path)
|
|
if resolved is not None:
|
|
source = f"current regime from {db_path}"
|
|
else:
|
|
resolved = DEFAULT_REGIME
|
|
source = "default (no regime in data)"
|
|
|
|
comparison = ec.compare_regime(
|
|
resolved, config_path=config_path, skills_root=skills_root
|
|
)
|
|
print(ec.render_markdown(comparison))
|
|
print(f"\n(regime source: {source})", file=sys.stderr)
|
|
return 0
|
|
|
|
|
|
def run_journal(
|
|
db_path: str,
|
|
limit: int | None,
|
|
out_path: str | None,
|
|
as_html: bool,
|
|
) -> int:
|
|
"""Build the decision journal from the event log and print it.
|
|
|
|
Always exits ``0``. When the event log is empty the rendered journal is a
|
|
clear "no data" note rather than an error. ``limit`` caps the number of
|
|
scored assets shown per cycle.
|
|
|
|
Output format is Markdown by default. HTML output is selected by the
|
|
``as_html`` flag or an ``out_path`` whose name ends in ``.html``/``.htm``;
|
|
in HTML mode the result is a single self-contained document (inline
|
|
dark-theme CSS, no external CSS/JS/CDN references) produced by
|
|
:func:`jnh.build_journal_html`, which reuses :func:`jn.render_markdown` and
|
|
the shared Markdown->HTML converter. When ``out_path`` is given the rendered
|
|
document is also written to that file.
|
|
"""
|
|
top_n = limit if (limit is not None and limit > 0) else 5
|
|
wants_html = as_html or (
|
|
out_path is not None and out_path.lower().endswith((".html", ".htm"))
|
|
)
|
|
|
|
if wants_html:
|
|
document = jnh.build_journal_html(db_path=db_path, top_n=top_n)
|
|
print(document)
|
|
if out_path:
|
|
jnh.write_journal_html(out_path, db_path=db_path, top_n=top_n)
|
|
print(f"\n(wrote journal to: {out_path})", file=sys.stderr)
|
|
return 0
|
|
|
|
journal = jn.build_journal_from_db(db_path)
|
|
markdown = jn.render_markdown(journal, top_n=top_n)
|
|
print(markdown)
|
|
|
|
if out_path:
|
|
try:
|
|
Path(out_path).write_text(markdown, encoding="utf-8")
|
|
print(f"\n(wrote journal to: {out_path})", file=sys.stderr)
|
|
except OSError as error:
|
|
print(f"\n(could not write journal: {error})", file=sys.stderr)
|
|
return 0
|
|
|
|
|
|
def run_bundle(
|
|
out_dir: str,
|
|
db_path: str,
|
|
report_path: str,
|
|
config_path: str,
|
|
skills_root: str,
|
|
) -> int:
|
|
"""Build the folder of self-contained HTML reports and print the index path.
|
|
|
|
Reuses :func:`guardrail_lab.report_bundle.build_bundle`, which composes the
|
|
existing dossier / journal / ensemble-comparison renderers into one
|
|
browsable bundle (``index.html`` linking ``dossier.html``, ``journal.html``,
|
|
and ``ensemble.html``). Always exits ``0``: on missing data each underlying
|
|
builder writes a valid no-data skeleton rather than raising, so a fresh
|
|
checkout still produces a complete, well-formed bundle.
|
|
|
|
Args:
|
|
out_dir: Destination directory for the bundle.
|
|
db_path: Path to the SQLite event-log database.
|
|
report_path: Path to the agent's JSON run report.
|
|
config_path: Path to the ensemble blend-weights config.
|
|
skills_root: Root directory holding the skill directories.
|
|
|
|
Returns:
|
|
The process exit code (always ``0``).
|
|
"""
|
|
written = rb.build_bundle(
|
|
out_dir=out_dir,
|
|
db_path=db_path,
|
|
report_path=report_path,
|
|
config_path=config_path,
|
|
skills_root=skills_root,
|
|
)
|
|
index_path = next(
|
|
(path for path in written if path.endswith(rb.INDEX_FILE)),
|
|
written[0] if written else out_dir,
|
|
)
|
|
print(index_path)
|
|
print(f"\n(wrote {len(written)} report(s) to: {out_dir})", file=sys.stderr)
|
|
return 0
|
|
|
|
|
|
def run_seed(
|
|
db_path: str,
|
|
report_path: str,
|
|
cycles: int,
|
|
seed: int,
|
|
) -> int:
|
|
"""Generate a deterministic synthetic run into the demo files and summarize.
|
|
|
|
Delegates to :func:`guardrail_lab.seed.seed_demo`, which writes a
|
|
multi-regime, multi-cycle event-log database and a matching run report to a
|
|
SEPARATE demo location (defaults under ``data/demo_*``) so the analytics
|
|
demo richly without touching the real ``data/guardrail_alpha.db`` /
|
|
``data/run_report.json``. Prints a summary (events written, regimes
|
|
covered, NAV range) and returns ``0`` on success.
|
|
"""
|
|
result = sd.seed_demo(
|
|
db_path=db_path,
|
|
report_path=report_path,
|
|
cycles=cycles,
|
|
seed=seed,
|
|
)
|
|
|
|
_print_header("Guardrail Alpha — Demo Seeder")
|
|
print(f"Database: {result.db_path}")
|
|
print(f"Run report: {result.report_path}")
|
|
print(f"Run ID: {result.run_id}")
|
|
print(f"Seed: {seed}")
|
|
print()
|
|
print(f"Cycles: {result.cycles}")
|
|
print(f"Events written: {result.events_written}")
|
|
print(f"Confirmed trades: {result.trades}")
|
|
print(f"Regimes covered: {', '.join(result.regimes)}")
|
|
print()
|
|
print(
|
|
f"NAV range: ${result.nav_min:,.2f} -> ${result.nav_max:,.2f} "
|
|
f"(final ${result.final_nav:,.2f})"
|
|
)
|
|
print(f"Max drawdown: {result.max_drawdown_pct:.4f}%")
|
|
print()
|
|
print("Try the analytics against the demo database, e.g.:")
|
|
print(f" python3 python-lab/analyze.py regime --db {result.db_path}")
|
|
print(f" python3 python-lab/analyze.py drawdown --db {result.db_path}")
|
|
print(
|
|
f" python3 python-lab/analyze.py dossier "
|
|
f"--db {result.db_path} --report {result.report_path}"
|
|
)
|
|
print()
|
|
return 0
|
|
|
|
|
|
def run_correlation(
|
|
snapshot_dir: str,
|
|
report_path: str,
|
|
db_path: str,
|
|
top_n: int,
|
|
) -> int:
|
|
"""Print the asset correlation matrix and exposure/concentration summary.
|
|
|
|
Loads the price/return history (snapshots preferred, event log fallback) and
|
|
the latest target book (run report), then prints the most-correlated asset
|
|
pairs, a compact correlation matrix, and the concentration diagnostics.
|
|
Always exits ``0``: missing/insufficient data is reported via a clear
|
|
message rather than raised.
|
|
"""
|
|
report = co.analyze_correlation(
|
|
snapshot_dir=snapshot_dir,
|
|
report_path=report_path,
|
|
db_path=db_path,
|
|
)
|
|
|
|
_print_header("Guardrail Alpha — Correlation & Exposure")
|
|
print(f"Snapshots: {snapshot_dir} Run report: {report_path}")
|
|
print(f"Price source: {report.source}")
|
|
print()
|
|
|
|
if not report.ok:
|
|
print(report.reason)
|
|
print()
|
|
return 0
|
|
|
|
print(f"({report.reason})")
|
|
print()
|
|
|
|
matrix = report.correlation
|
|
show_n = top_n if top_n > 0 else 10
|
|
|
|
print(f"Top {show_n} Correlated Pairs")
|
|
print("-" * 24)
|
|
defined_pairs = [pair for pair in matrix.pairs if pair.defined]
|
|
if defined_pairs:
|
|
for pair in defined_pairs[:show_n]:
|
|
print(
|
|
f" {pair.a:<6} ~ {pair.b:<6} "
|
|
f"corr={pair.correlation:+.4f} "
|
|
f"(n={pair.observations})"
|
|
)
|
|
else:
|
|
print(" (no asset pair had enough overlapping returns)")
|
|
print()
|
|
|
|
print("Correlation Matrix")
|
|
print("-" * 18)
|
|
if matrix.symbols:
|
|
header = " " + "".join(f"{sym:>8}" for sym in matrix.symbols)
|
|
print(header)
|
|
for row_sym in matrix.symbols:
|
|
cells = "".join(
|
|
f"{matrix.matrix[row_sym][col_sym]:>8.2f}"
|
|
for col_sym in matrix.symbols
|
|
)
|
|
print(f" {row_sym:<6}{cells}")
|
|
print(f" assets={len(matrix.symbols)} return steps={matrix.n_observations}")
|
|
else:
|
|
print(" (no correlation matrix — insufficient price history)")
|
|
print()
|
|
|
|
exposure = report.exposure
|
|
print("Exposure & Concentration (latest target book)")
|
|
print("-" * 45)
|
|
if exposure.position_count:
|
|
for position in exposure.positions:
|
|
print(
|
|
f" {position.symbol:<6} "
|
|
f"weight={position.weight_pct:6.2f}%"
|
|
)
|
|
print()
|
|
print(f" positions: {exposure.position_count}")
|
|
print(f" gross weight: {exposure.gross_weight * 100:.2f}%")
|
|
print(f" Herfindahl index: {exposure.herfindahl:.4f}")
|
|
print(
|
|
f" effective positions: {exposure.effective_positions:.2f}"
|
|
)
|
|
else:
|
|
print(" (no target book positions found)")
|
|
print()
|
|
|
|
return 0
|
|
|
|
|
|
def build_parser() -> argparse.ArgumentParser:
|
|
"""Construct the argparse CLI parser."""
|
|
parser = argparse.ArgumentParser(
|
|
prog="analyze.py",
|
|
description="Guardrail Alpha analytics (regime + drawdown).",
|
|
)
|
|
subparsers = parser.add_subparsers(dest="command", required=True)
|
|
|
|
regime = subparsers.add_parser(
|
|
"regime", help="Regime transition / time / exposure analytics."
|
|
)
|
|
regime.add_argument(
|
|
"--db",
|
|
default=DEFAULT_DB,
|
|
help=f"Path to the event-log database (default: {DEFAULT_DB}).",
|
|
)
|
|
regime.add_argument(
|
|
"--report",
|
|
default=DEFAULT_REPORT,
|
|
help=f"Path to the run report JSON (default: {DEFAULT_REPORT}).",
|
|
)
|
|
|
|
draw = subparsers.add_parser(
|
|
"drawdown", help="NAV underwater curve and worst drawdown episodes."
|
|
)
|
|
draw.add_argument(
|
|
"--db",
|
|
default=DEFAULT_DB,
|
|
help=f"Path to the event-log database (default: {DEFAULT_DB}).",
|
|
)
|
|
draw.add_argument(
|
|
"--report",
|
|
default=DEFAULT_REPORT,
|
|
help=f"Path to the run report JSON (default: {DEFAULT_REPORT}).",
|
|
)
|
|
draw.add_argument(
|
|
"--top-n",
|
|
type=int,
|
|
default=5,
|
|
help="Number of worst drawdown episodes to show (default: 5).",
|
|
)
|
|
|
|
montecarlo = subparsers.add_parser(
|
|
"montecarlo",
|
|
help="IID bootstrap risk simulation over the NAV curve (VaR/CVaR).",
|
|
)
|
|
montecarlo.add_argument(
|
|
"--db",
|
|
default=DEFAULT_DB,
|
|
help=f"Path to the event-log database (default: {DEFAULT_DB}).",
|
|
)
|
|
montecarlo.add_argument(
|
|
"--report",
|
|
default=DEFAULT_REPORT,
|
|
help=f"Path to the run report JSON (default: {DEFAULT_REPORT}).",
|
|
)
|
|
montecarlo.add_argument(
|
|
"--paths",
|
|
type=int,
|
|
default=mc.DEFAULT_N_PATHS,
|
|
help=f"Number of bootstrap paths (default: {mc.DEFAULT_N_PATHS}).",
|
|
)
|
|
montecarlo.add_argument(
|
|
"--seed",
|
|
type=int,
|
|
default=mc.DEFAULT_SEED,
|
|
help=f"RNG seed for reproducibility (default: {mc.DEFAULT_SEED}).",
|
|
)
|
|
montecarlo.add_argument(
|
|
"--dd-threshold",
|
|
type=float,
|
|
default=mc.DEFAULT_DD_THRESHOLD * 100.0,
|
|
help=(
|
|
"Drawdown breach threshold in percent "
|
|
f"(default: {mc.DEFAULT_DD_THRESHOLD * 100.0:g})."
|
|
),
|
|
)
|
|
|
|
dossier = subparsers.add_parser(
|
|
"dossier",
|
|
help="Synthesize every analytic into one Markdown research dossier.",
|
|
)
|
|
dossier.add_argument(
|
|
"--db",
|
|
default=DEFAULT_DB,
|
|
help=f"Path to the event-log database (default: {DEFAULT_DB}).",
|
|
)
|
|
dossier.add_argument(
|
|
"--report",
|
|
default=DEFAULT_REPORT,
|
|
help=f"Path to the run report JSON (default: {DEFAULT_REPORT}).",
|
|
)
|
|
dossier.add_argument(
|
|
"--out",
|
|
default=None,
|
|
help=(
|
|
"Optional path to also write the dossier to. A .html/.htm "
|
|
"suffix selects HTML output automatically."
|
|
),
|
|
)
|
|
dossier.add_argument(
|
|
"--html",
|
|
action="store_true",
|
|
help="Emit a self-contained HTML document instead of Markdown.",
|
|
)
|
|
|
|
ensemble = subparsers.add_parser(
|
|
"ensemble",
|
|
help="Blend the 4 Track-2 skills by regime (book + attribution).",
|
|
)
|
|
ensemble.add_argument(
|
|
"--regime",
|
|
default=None,
|
|
help=(
|
|
"Regime to blend (risk_on/risk_off/chop/breakout). Defaults to the "
|
|
f"current regime in the event log, else {DEFAULT_REGIME}."
|
|
),
|
|
)
|
|
ensemble.add_argument(
|
|
"--config",
|
|
default=DEFAULT_ENSEMBLE_CONFIG,
|
|
help=(
|
|
"Path to the ensemble blend-weights config "
|
|
f"(default: {DEFAULT_ENSEMBLE_CONFIG})."
|
|
),
|
|
)
|
|
ensemble.add_argument(
|
|
"--skills-root",
|
|
default=DEFAULT_SKILLS_ROOT,
|
|
help=(
|
|
"Root directory holding the 4 skill directories "
|
|
f"(default: {DEFAULT_SKILLS_ROOT})."
|
|
),
|
|
)
|
|
ensemble.add_argument(
|
|
"--db",
|
|
default=DEFAULT_DB,
|
|
help=f"Path to the event-log database (default: {DEFAULT_DB}).",
|
|
)
|
|
|
|
compare = subparsers.add_parser(
|
|
"ensemble-compare",
|
|
help=(
|
|
"Compare the blended ensemble book vs. each single skill "
|
|
"(concentration / diversification / overlap) by regime."
|
|
),
|
|
)
|
|
compare.add_argument(
|
|
"--regime",
|
|
default=None,
|
|
help=(
|
|
"Regime to compare (risk_on/risk_off/chop/breakout). Defaults to "
|
|
f"the current regime in the event log, else {DEFAULT_REGIME}. "
|
|
"Ignored when --all is given."
|
|
),
|
|
)
|
|
compare.add_argument(
|
|
"--all",
|
|
action="store_true",
|
|
help="Compare all four regimes and emit one combined report.",
|
|
)
|
|
compare.add_argument(
|
|
"--config",
|
|
default=DEFAULT_ENSEMBLE_CONFIG,
|
|
help=(
|
|
"Path to the ensemble blend-weights config "
|
|
f"(default: {DEFAULT_ENSEMBLE_CONFIG})."
|
|
),
|
|
)
|
|
compare.add_argument(
|
|
"--skills-root",
|
|
default=DEFAULT_SKILLS_ROOT,
|
|
help=(
|
|
"Root directory holding the 4 skill directories "
|
|
f"(default: {DEFAULT_SKILLS_ROOT})."
|
|
),
|
|
)
|
|
compare.add_argument(
|
|
"--db",
|
|
default=DEFAULT_DB,
|
|
help=f"Path to the event-log database (default: {DEFAULT_DB}).",
|
|
)
|
|
|
|
journal = subparsers.add_parser(
|
|
"journal",
|
|
help="Human-readable per-cycle decision journal from the event log.",
|
|
)
|
|
journal.add_argument(
|
|
"--db",
|
|
default=DEFAULT_DB,
|
|
help=f"Path to the event-log database (default: {DEFAULT_DB}).",
|
|
)
|
|
journal.add_argument(
|
|
"--limit",
|
|
type=int,
|
|
default=5,
|
|
help="Max scored assets to list per cycle (default: 5).",
|
|
)
|
|
journal.add_argument(
|
|
"--out",
|
|
default=None,
|
|
help=(
|
|
"Optional path to also write the journal to. A .html/.htm suffix "
|
|
"selects HTML output automatically."
|
|
),
|
|
)
|
|
journal.add_argument(
|
|
"--html",
|
|
action="store_true",
|
|
help=(
|
|
"Emit a self-contained HTML document (inline dark-theme CSS, no "
|
|
"external CSS/JS/CDN) instead of Markdown."
|
|
),
|
|
)
|
|
|
|
correlation = subparsers.add_parser(
|
|
"correlation",
|
|
help=(
|
|
"Per-asset return correlation matrix (Pearson) plus "
|
|
"concentration / exposure summary (HHI, effective positions)."
|
|
),
|
|
)
|
|
correlation.add_argument(
|
|
"--snapshots",
|
|
default=DEFAULT_SNAPSHOT_DIR,
|
|
help=(
|
|
"Directory of market snapshot .jsonl files "
|
|
f"(default: {DEFAULT_SNAPSHOT_DIR})."
|
|
),
|
|
)
|
|
correlation.add_argument(
|
|
"--report",
|
|
default=DEFAULT_REPORT,
|
|
help=(
|
|
"Path to the run report JSON (latest target book) "
|
|
f"(default: {DEFAULT_REPORT})."
|
|
),
|
|
)
|
|
correlation.add_argument(
|
|
"--db",
|
|
default=DEFAULT_DB,
|
|
help=(
|
|
"Path to the event-log database (fallback price source) "
|
|
f"(default: {DEFAULT_DB})."
|
|
),
|
|
)
|
|
correlation.add_argument(
|
|
"--top-n",
|
|
type=int,
|
|
default=10,
|
|
help="Number of top correlated pairs to show (default: 10).",
|
|
)
|
|
|
|
bundle = subparsers.add_parser(
|
|
"bundle",
|
|
help=(
|
|
"Write a folder of self-contained HTML reports (index + dossier + "
|
|
"journal + ensemble) and print the index path."
|
|
),
|
|
)
|
|
bundle.add_argument(
|
|
"--out",
|
|
default=DEFAULT_BUNDLE_OUT,
|
|
help=(
|
|
"Output directory for the report bundle "
|
|
f"(default: {DEFAULT_BUNDLE_OUT})."
|
|
),
|
|
)
|
|
bundle.add_argument(
|
|
"--db",
|
|
default=DEFAULT_DB,
|
|
help=f"Path to the event-log database (default: {DEFAULT_DB}).",
|
|
)
|
|
bundle.add_argument(
|
|
"--report",
|
|
default=DEFAULT_REPORT,
|
|
help=f"Path to the run report JSON (default: {DEFAULT_REPORT}).",
|
|
)
|
|
bundle.add_argument(
|
|
"--config",
|
|
default=DEFAULT_ENSEMBLE_CONFIG,
|
|
help=(
|
|
"Path to the ensemble blend-weights config "
|
|
f"(default: {DEFAULT_ENSEMBLE_CONFIG})."
|
|
),
|
|
)
|
|
bundle.add_argument(
|
|
"--skills-root",
|
|
default=DEFAULT_SKILLS_ROOT,
|
|
help=(
|
|
"Root directory holding the 4 skill directories "
|
|
f"(default: {DEFAULT_SKILLS_ROOT})."
|
|
),
|
|
)
|
|
|
|
seed = subparsers.add_parser(
|
|
"seed",
|
|
help=(
|
|
"Generate a deterministic multi-regime, multi-cycle synthetic run "
|
|
"into a SEPARATE demo database + run report (real data untouched)."
|
|
),
|
|
)
|
|
seed.add_argument(
|
|
"--db",
|
|
default=sd.DEFAULT_DB,
|
|
help=(
|
|
"Destination demo event-log database "
|
|
f"(default: {sd.DEFAULT_DB})."
|
|
),
|
|
)
|
|
seed.add_argument(
|
|
"--report",
|
|
default=sd.DEFAULT_REPORT,
|
|
help=(
|
|
"Destination demo run report JSON "
|
|
f"(default: {sd.DEFAULT_REPORT})."
|
|
),
|
|
)
|
|
seed.add_argument(
|
|
"--cycles",
|
|
type=int,
|
|
default=sd.DEFAULT_CYCLES,
|
|
help=(
|
|
"Approximate number of decision cycles to generate "
|
|
f"(default: {sd.DEFAULT_CYCLES})."
|
|
),
|
|
)
|
|
seed.add_argument(
|
|
"--seed",
|
|
type=int,
|
|
default=sd.DEFAULT_SEED,
|
|
help=(
|
|
"Integer RNG seed for deterministic output "
|
|
f"(default: {sd.DEFAULT_SEED})."
|
|
),
|
|
)
|
|
|
|
return parser
|
|
|
|
|
|
def main(argv: list[str] | None = None) -> int:
|
|
"""CLI entry point. Returns the process exit code."""
|
|
parser = build_parser()
|
|
args = parser.parse_args(argv)
|
|
|
|
if args.command == "regime":
|
|
return run_regime(args.db)
|
|
if args.command == "drawdown":
|
|
return run_drawdown(args.db, args.top_n)
|
|
if args.command == "montecarlo":
|
|
return run_montecarlo(
|
|
args.db, args.paths, args.seed, args.dd_threshold
|
|
)
|
|
if args.command == "dossier":
|
|
return run_dossier(args.db, args.report, args.out, args.html)
|
|
if args.command == "ensemble":
|
|
return run_ensemble(
|
|
args.regime, args.config, args.skills_root, args.db
|
|
)
|
|
if args.command == "ensemble-compare":
|
|
return run_ensemble_compare(
|
|
args.regime, args.all, args.config, args.skills_root, args.db
|
|
)
|
|
if args.command == "journal":
|
|
return run_journal(args.db, args.limit, args.out, args.html)
|
|
if args.command == "correlation":
|
|
return run_correlation(
|
|
args.snapshots, args.report, args.db, args.top_n
|
|
)
|
|
if args.command == "bundle":
|
|
return run_bundle(
|
|
args.out, args.db, args.report, args.config, args.skills_root
|
|
)
|
|
if args.command == "seed":
|
|
return run_seed(args.db, args.report, args.cycles, args.seed)
|
|
|
|
parser.print_help()
|
|
return 0
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|