1032 lines
33 KiB
Python
Raw Permalink Normal View History

#!/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())