aether-quant 0.2.0__py3-none-any.whl

aether_quant-0.2.0.dist-info/METADATA

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: aether-quant
+Version: 0.2.0
+Summary: Aether Quant convenience CLI
+Requires-Python: >=3.10

aether_quant-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+aq_cli.py,sha256=0v_TC-nHdm7pPBMNOBOGGCkxQB2In6H6U9mDhow8isA,13467
+risk/README.md,sha256=l9EBeIVirsIW4zw9rMZY9dLRfci_MZbVM2PYRWyGf-k,608
+risk/__init__.py,sha256=DpEPHZV9GRLE3Wi731QMZ6J0e0moJsfCe6KH0OfRKK0,492
+risk/manual_override.py,sha256=XwQYAfGlKtyXiJfAF_P9FNsOfLjfYG4HRHVySLFEhAk,2595
+risk/position_sizing.py,sha256=UvAvehp5hPQX3-qm-F2dDKzQ5hpgUiRnH-asrKt3UAI,3981
+aether_quant-0.2.0.dist-info/METADATA,sha256=F4r2u5uBzS9GlSh5Yf1uTwPEAF95FDlzYQutz7AHikc,118
+aether_quant-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+aether_quant-0.2.0.dist-info/entry_points.txt,sha256=QFFJIvHqEKjBKlVrniDI73HObpCTR3rECR22vsJtvxQ,35
+aether_quant-0.2.0.dist-info/scm_file_list.json,sha256=gI7-wezKOZOTbrJzS4RFGIa87mmdX1FaahVN2WHkQQQ,7642
+aether_quant-0.2.0.dist-info/scm_version.json,sha256=WaH5Lrm-sEC3pB9zIMQHDkWtTYjcdL5L3HxqppJdaKg,160
+aether_quant-0.2.0.dist-info/top_level.txt,sha256=SAJI6n0gUv2UeUVOJ3PEEJEHiOoFrbQNLIrnBpcdMA0,12
+aether_quant-0.2.0.dist-info/RECORD,,

aether_quant-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aether_quant-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aq = aq_cli:main

aether_quant-0.2.0.dist-info/scm_file_list.json

@@ -0,0 +1,211 @@
+{
+  "files": [
+    "README.md",
+    "aq_cli.py",
+    "Dockerfile",
+    "pyproject.toml",
+    ".env.compose.example",
+    "Dockerfile.retraining_worker",
+    "train_topology.py",
+    "train.py",
+    ".dockerignore",
+    "Dockerfile.telegram_worker",
+    "Dockerfile.worker",
+    ".gitattributes",
+    "main.py",
+    ".gitignore",
+    "docker-compose.yml",
+    "risk_controls.py",
+    "Dockerfile.trigger_worker",
+    "experience/redis_queue.py",
+    "experience/README.md",
+    "experience/__init__.py",
+    "experience/simulated_portfolio.py",
+    "experience/observation_metrics.py",
+    "experience/postgres_worker.py",
+    "risk/README.md",
+    "risk/__init__.py",
+    "risk/manual_override.py",
+    "risk/position_sizing.py",
+    "notifications/telegram_client.py",
+    "notifications/README.md",
+    "notifications/__init__.py",
+    "notifications/telegram_worker.py",
+    "notifications/postgres_telegram.py",
+    "notifications/telegram_alerts.py",
+    "topology/README.md",
+    "topology/__init__.py",
+    "topology/market_topology.py",
+    "topology/learned_topology.py",
+    "analyzer/README.md",
+    "analyzer/market_analyzer.py",
+    "analyzer/__init__.py",
+    "data_pipeline/README.md",
+    "data_pipeline/__init__.py",
+    "data_pipeline/v2_manifest.py",
+    "data_pipeline/yfinance_backfill.py",
+    "visualization/README.md",
+    "regime/README.md",
+    "regime/__init__.py",
+    "regime/market_regime.py",
+    "moe/README.md",
+    "moe/__init__.py",
+    "moe/gating.py",
+    "backtests/.gitkeep",
+    "retraining/README.md",
+    "retraining/lean_backtest.py",
+    "retraining/__init__.py",
+    "retraining/artifacts.py",
+    "retraining/planning.py",
+    "retraining/vault_commands.py",
+    "retraining/backtest_gate.py",
+    "retraining/validation_gate.py",
+    "retraining/vault_client.py",
+    "retraining/worker.py",
+    "retraining/status_export.py",
+    "retraining/postgres_registry.py",
+    "retraining/orchestrator.py",
+    "execution/README.md",
+    "execution/__init__.py",
+    "execution/order_gate.py",
+    "monitoring/neural_network_state.py",
+    "monitoring/README.md",
+    "monitoring/__init__.py",
+    "monitoring/api_server.py",
+    "performance/README.md",
+    "performance/__init__.py",
+    "performance/triggers.py",
+    "performance/postgres_triggers.py",
+    "performance/trigger_worker.py",
+    "liquidity/README.md",
+    "liquidity/__init__.py",
+    "liquidity/market_liquidity.py",
+    "experts/expert_datasets.py",
+    "experts/README.md",
+    "experts/__init__.py",
+    "webui/package-lock.json",
+    "webui/README.md",
+    "webui/risk_v2_12.png",
+    "webui/tsconfig.json",
+    "webui/.oxlintrc.json",
+    "webui/tsconfig.node.json",
+    "webui/tsconfig.app.json",
+    "webui/index.html",
+    "webui/.gitignore",
+    "webui/vite.config.ts",
+    "webui/overview_v2_12.png",
+    "webui/package.json",
+    "webui/src/App.tsx",
+    "webui/src/index.css",
+    "webui/src/main.tsx",
+    "webui/src/api/hooks.ts",
+    "webui/src/api/client.ts",
+    "webui/src/lib/downsample.ts",
+    "webui/src/lib/format.ts",
+    "webui/src/components/scene3d/Scene3D.tsx",
+    "webui/src/components/risk/RiskCore.tsx",
+    "webui/src/components/risk/AssetSizingTable.tsx",
+    "webui/src/components/risk/LiquidityTable.tsx",
+    "webui/src/components/risk/RiskBar.tsx",
+    "webui/src/components/risk/StrategyRiskCards.tsx",
+    "webui/src/components/heatmap/AssetHeatmap.tsx",
+    "webui/src/components/topology/TopologyScene3D.tsx",
+    "webui/src/components/topology/ClusterList.tsx",
+    "webui/src/components/topology/TopologyLearningPanel.tsx",
+    "webui/src/components/layout/Panel.tsx",
+    "webui/src/components/layout/AppShell.tsx",
+    "webui/src/components/scorecards/Scorecards.tsx",
+    "webui/src/components/signals/PositionsList.tsx",
+    "webui/src/components/signals/Badge.tsx",
+    "webui/src/components/signals/SignalBoard.tsx",
+    "webui/src/components/neuralnet/NeuralNetworkScene3D.tsx",
+    "webui/src/components/neuralnet/NeuralNetworkStatsPanel.tsx",
+    "webui/src/components/monitoring/RetrainingStatusPanel.tsx",
+    "webui/src/components/monitoring/ObservationPanel.tsx",
+    "webui/src/components/monitoring/PerformanceTriggersPanel.tsx",
+    "webui/src/components/monitoring/CountTable.tsx",
+    "webui/src/components/monitoring/RawStateViewer.tsx",
+    "webui/src/components/monitoring/MonitoringFeeds.tsx",
+    "webui/src/components/tracing/BacktestEquityPanel.tsx",
+    "webui/src/components/tracing/ObservationEquityPanel.tsx",
+    "webui/src/components/tracing/MetricsSnapshotPanel.tsx",
+    "webui/src/components/tracing/DivergingBarChart.tsx",
+    "webui/src/components/tracing/LineChart.tsx",
+    "webui/src/components/tracing/AssetPerformancePanel.tsx",
+    "webui/src/pages/TopologyPage.tsx",
+    "webui/src/pages/Overview.tsx",
+    "webui/src/pages/RiskPage.tsx",
+    "webui/src/pages/TracingPage.tsx",
+    "webui/src/pages/NeuralNetworkPage.tsx",
+    "webui/src/types/tracing.ts",
+    "webui/src/types/state.ts",
+    "webui/public/favicon.svg",
+    "webui/public/icons.svg",
+    "development/README.md",
+    "development/Problems.md",
+    "development/Changelog.md",
+    "development/v2_architecture.md",
+    "development/infrastructure.md",
+    "tests/test_order_gate.py",
+    "tests/test_telegram_alerts.py",
+    "tests/test_trigger_worker.py",
+    "tests/test_v2_pipeline_manifest.py",
+    "tests/test_aq_cli.py",
+    "tests/test_risk_controls.py",
+    "tests/test_backtest_gate.py",
+    "tests/README.md",
+    "tests/test_status_export.py",
+    "tests/test_postgres_worker.py",
+    "tests/test_retraining_artifacts.py",
+    "tests/test_expert_datasets.py",
+    "tests/test_expert_models.py",
+    "tests/test_retraining_orchestrator.py",
+    "tests/test_telegram_client.py",
+    "tests/test_yfinance_backfill.py",
+    "tests/test_neural_network_state.py",
+    "tests/test_market_regime.py",
+    "tests/test_vault_client.py",
+    "tests/test_validation_gate.py",
+    "tests/test_observation_metrics.py",
+    "tests/test_train_topology.py",
+    "tests/test_telegram_worker.py",
+    "tests/test_triggers.py",
+    "tests/test_simulated_portfolio.py",
+    "tests/test_position_sizing.py",
+    "tests/test_market_liquidity.py",
+    "tests/test_lean_backtest_ml_coverage.py",
+    "tests/test_market_analyzer.py",
+    "tests/test_lean_backtest.py",
+    "tests/test_retraining_planning.py",
+    "tests/test_market_topology.py",
+    "tests/test_postgres_triggers.py",
+    "tests/test_manual_override.py",
+    "tests/test_postgres_telegram.py",
+    "tests/test_retraining_worker.py",
+    "tests/test_retraining_postgres_registry.py",
+    "tests/test_learned_topology.py",
+    "tests/test_gating_network.py",
+    "tests/test_train_pipeline.py",
+    "tests/test_experience_queue.py",
+    "tests/test_vault_commands.py",
+    "data/alternative/sec/aapl/.keep",
+    "data/alternative/trading-economics/.keep",
+    "data/alternative/trading-economics/calendar/.keep",
+    "data/alternative/trading-economics/indicator/.keep",
+    "data/alternative/trading-economics/earnings/.keep",
+    "data/alternative/estimize/estimate/.keep",
+    "data/alternative/estimize/release/.keep",
+    "data/alternative/estimize/consensus/aapl/.keep",
+    "requirements/requirements-runtime.txt",
+    "requirements/README.md",
+    "requirements/requirements-telegram-worker.txt",
+    "requirements/requirements.txt",
+    "requirements/requirements-worker.txt",
+    "requirements/requirements-trigger-worker.txt",
+    "requirements/requirements-dev.txt",
+    "requirements/requirements-retraining-worker.txt",
+    "ml/README.md",
+    ".github/workflows/release.yml",
+    ".github/workflows/ci.yml"
+  ]
+}

aether_quant-0.2.0.dist-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.2.0",
+  "distance": 0,
+  "node": "gaf8d80bac1f1b574de4f070bda52817a11973f49",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-04"
+}

aether_quant-0.2.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+aq_cli
+risk

aq_cli.py

@@ -0,0 +1,329 @@
+"""`aq` — a thin convenience CLI wrapping Aether Quant's day-to-day commands.
+
+Matches this codebase's existing CLI convention exactly (see
+`retraining/orchestrator.py`'s `argparse` + `subparsers.add_parser(...)`
+shape) - a single-file dispatcher, not a framework. Every subcommand other
+than `trade-lock` is a thin `subprocess.run(...)` wrapper around a command
+that already exists and is already documented elsewhere (README.md,
+development/infrastructure.md) - no logic is reimplemented here, this file
+only saves typing. `trade-lock` is the one exception: it calls
+`risk/manual_override.py` directly, no subprocess.
+
+Deliberately scoped for v1 - wraps the commands already in daily use, not
+every command mentioned anywhere in the project. Designed to be extended
+incrementally: add a new `subparsers.add_parser(...)` block plus one `elif`
+branch in `main()` for each new command, following the existing pattern.
+
+Install once (registers the `aq` command on PATH inside the active venv):
+    pip install -e .
+Then:
+    aq --help
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+import urllib.request
+from importlib.metadata import version as installed_version
+from pathlib import Path
+
+from risk.manual_override import read_manual_trade_lock_override, write_manual_trade_lock_override
+
+ROOT_DIR = Path(__file__).resolve().parent
+CONFIG_PATH = ROOT_DIR / "config.json"
+WEBUI_DIR = ROOT_DIR / "webui"
+
+PACKAGE_NAME = "aether-quant"
+UPDATE_CACHE_PATH = Path.home() / ".aq" / "update_check.json"
+UPDATE_CHECK_INTERVAL_SECONDS = 24 * 60 * 60
+UPDATE_CHECK_TIMEOUT_SECONDS = 2
+
+
+def _run(cmd: list[str], cwd: Path = ROOT_DIR) -> int:
+    """Runs a command with inherited stdout/stderr (live output), returns its exit code."""
+    result = subprocess.run(cmd, cwd=str(cwd))
+    return result.returncode
+
+
+def _find_quantconnect_lean_binary() -> str | None:
+    """Plain `lean` on PATH is ambiguous on machines with `elan` (Lean 4, the
+    theorem prover) installed - it ships its own `lean` binary under the same
+    name as QuantConnect's Lean CLI (`pip install lean`). Disambiguate by
+    checking `--version` output (Lean 4 prints "Lean (version 4...."; the
+    QuantConnect CLI does not), preferring this repo's own venv first."""
+    bin_dir_name = "Scripts" if sys.platform == "win32" else "bin"
+    binary_name = "lean.exe" if sys.platform == "win32" else "lean"
+    candidates = [str(ROOT_DIR / ".venv" / bin_dir_name / binary_name)]
+    on_path = shutil.which("lean")
+    if on_path:
+        candidates.append(on_path)
+
+    for candidate in candidates:
+        if candidate != on_path and not Path(candidate).exists():
+            continue
+        try:
+            result = subprocess.run([candidate, "--version"], capture_output=True, text=True, timeout=30)
+        except (FileNotFoundError, OSError, subprocess.TimeoutExpired):
+            continue
+        if "Lean (version" not in (result.stdout or "") + (result.stderr or ""):
+            return candidate
+    return None
+
+
+def _parse_simple_version(value: str) -> tuple[int, ...] | None:
+    """Best-effort "X.Y.Z" -> (X, Y, Z) parse. Returns None for anything that
+    isn't a clean dotted-integer release version - dev/local builds (e.g.
+    setuptools-scm's "0.1.dev35+gc744f9ca4.d20260704" fallback for untagged
+    installs) simply never get flagged as outdated, which is the correct
+    behavior here."""
+    try:
+        return tuple(int(part) for part in value.split("."))
+    except ValueError:
+        return None
+
+
+def _read_update_cache() -> dict:
+    if not UPDATE_CACHE_PATH.exists():
+        return {}
+    try:
+        return json.loads(UPDATE_CACHE_PATH.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _write_update_cache(latest_version: str) -> None:
+    UPDATE_CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    payload = {"last_checked": time.time(), "latest_version": latest_version}
+    UPDATE_CACHE_PATH.write_text(json.dumps(payload), encoding="utf-8")
+
+
+def _fetch_latest_version_from_pypi() -> str | None:
+    try:
+        url = f"https://pypi.org/pypi/{PACKAGE_NAME}/json"
+        with urllib.request.urlopen(url, timeout=UPDATE_CHECK_TIMEOUT_SECONDS) as response:  # noqa: S310
+            payload = json.loads(response.read().decode("utf-8"))
+        return payload["info"]["version"]
+    except Exception:
+        return None
+
+
+def _latest_known_version() -> str | None:
+    cache = _read_update_cache()
+    last_checked = cache.get("last_checked", 0)
+    if time.time() - last_checked < UPDATE_CHECK_INTERVAL_SECONDS:
+        return cache.get("latest_version")
+
+    # Update the cache timestamp even on a failed fetch, so an offline user
+    # doesn't pay the network timeout again on every single command - only
+    # once per interval.
+    latest = _fetch_latest_version_from_pypi()
+    _write_update_cache(latest or cache.get("latest_version", ""))
+    return latest or cache.get("latest_version")
+
+
+def check_for_update() -> None:
+    """Prints a one-line notice to stderr if a newer aether-quant release is
+    available on PyPI. Never raises, never blocks a real command by more
+    than the short network timeout, and only actually checks PyPI once per
+    24h (cached in ~/.aq/update_check.json). Opt out with
+    AQ_SKIP_UPDATE_CHECK=1 (e.g. for CI/scripted usage)."""
+    if os.environ.get("AQ_SKIP_UPDATE_CHECK"):
+        return
+    try:
+        installed = installed_version(PACKAGE_NAME)
+        latest = _latest_known_version()
+        if not latest:
+            return
+        installed_tuple = _parse_simple_version(installed)
+        latest_tuple = _parse_simple_version(latest)
+        if installed_tuple is None or latest_tuple is None:
+            return
+        if installed_tuple < latest_tuple:
+            print(
+                f"aq: a newer version is available ({latest}, you have {installed}) - "
+                f"upgrade with: pip install --upgrade {PACKAGE_NAME}",
+                file=sys.stderr,
+            )
+    except Exception:
+        pass
+
+
+def cmd_train(args: argparse.Namespace) -> int:
+    cmd = [sys.executable, "train.py"]
+    if args.dataset_only:
+        cmd.append("--dataset-only")
+    elif args.init_only:
+        cmd.append("--init-only")
+    elif args.experts_only:
+        cmd.append("--experts-only")
+    return _run(cmd)
+
+
+def cmd_test(_args: argparse.Namespace) -> int:
+    return _run([sys.executable, "-m", "pytest", "tests/"])
+
+
+def cmd_backtest(_args: argparse.Namespace) -> int:
+    lean_binary = _find_quantconnect_lean_binary()
+    if lean_binary is None:
+        print("error: QuantConnect Lean CLI not found (checked .venv and PATH).", file=sys.stderr)
+        return 1
+    return _run([lean_binary, "backtest", "."])
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    lean_binary = _find_quantconnect_lean_binary()
+    if lean_binary is None:
+        print("error: QuantConnect Lean CLI not found (checked .venv and PATH).", file=sys.stderr)
+        return 1
+    backtest_dir = ROOT_DIR / "backtests" / args.backtest_dir
+    return _run(
+        [
+            lean_binary,
+            "report",
+            "--backtest-results",
+            str(backtest_dir / f"{args.result_id}.json"),
+            "--report-destination",
+            str(backtest_dir / "report.html"),
+            "--overwrite",
+        ]
+    )
+
+
+def cmd_api(_args: argparse.Namespace) -> int:
+    return _run([sys.executable, "-m", "uvicorn", "monitoring.api_server:app", "--port", "8001", "--reload"])
+
+
+def cmd_webui(_args: argparse.Namespace) -> int:
+    npm = "npm.cmd" if sys.platform == "win32" else "npm"
+    return _run([npm, "run", "dev"], cwd=WEBUI_DIR)
+
+
+def cmd_docker_up(args: argparse.Namespace) -> int:
+    if args.all:
+        services = [
+            "redis",
+            "postgres",
+            "aether-quant",
+            "experience-worker",
+            "performance-trigger-worker",
+            "retraining-worker",
+            "telegram-worker",
+        ]
+        return _run(["docker", "compose", "up", "-d", *services])
+    if args.lean:
+        return _run(["docker", "compose", "--profile", "lean", "up", "-d"])
+    return _run(["docker", "compose", "up", "-d", "redis", "postgres"])
+
+
+def cmd_docker_build(_args: argparse.Namespace) -> int:
+    return _run(["docker", "compose", "build", "aether-quant"])
+
+
+def cmd_retrain(args: argparse.Namespace) -> int:
+    return _run([sys.executable, "-m", "retraining.orchestrator", args.stage, *args.retrain_args])
+
+
+def cmd_trade_lock(args: argparse.Namespace) -> int:
+    if args.on:
+        write_manual_trade_lock_override(True, CONFIG_PATH)
+        print("Trade lock override: ON (trading forced paused).")
+    elif args.off:
+        write_manual_trade_lock_override(False, CONFIG_PATH)
+        print("Trade lock override: OFF (trading forced resumed, even past a sticky total-drawdown lock).")
+    elif args.auto:
+        write_manual_trade_lock_override(None, CONFIG_PATH)
+        print("Trade lock override: AUTO (back to today's default automatic behavior).")
+    else:  # status
+        override = read_manual_trade_lock_override(CONFIG_PATH)
+        label = {True: "ON (forced paused)", False: "OFF (forced resumed)", None: "AUTO (automatic behavior)"}[override]
+        print(f"Trade lock override: {label}")
+    return 0
+
+
+def cmd_status(_args: argparse.Namespace) -> int:
+    return _run(["git", "status"])
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="aq", description="Aether Quant convenience CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    train_parser = subparsers.add_parser("train", help="Run the training pipeline (wraps python train.py)")
+    train_group = train_parser.add_mutually_exclusive_group()
+    train_group.add_argument("--dataset-only", action="store_true", help="Build dataset/scaler/manifest only")
+    train_group.add_argument("--init-only", action="store_true", help="Refresh the data inventory only")
+    train_group.add_argument("--experts-only", action="store_true", help="Train the 4 expert models only")
+    train_parser.set_defaults(func=cmd_train)
+
+    test_parser = subparsers.add_parser("test", help="Run the test suite (wraps pytest tests/)")
+    test_parser.set_defaults(func=cmd_test)
+
+    backtest_parser = subparsers.add_parser("backtest", help="Run a Lean backtest (wraps lean backtest .)")
+    backtest_parser.set_defaults(func=cmd_backtest)
+
+    report_parser = subparsers.add_parser("report", help="Generate a Lean HTML report for a finished backtest")
+    report_parser.add_argument("backtest_dir", help="Folder name under backtests/, e.g. 2026-07-04_13-06-51")
+    report_parser.add_argument("result_id", help="Result JSON id, e.g. 1366365999")
+    report_parser.set_defaults(func=cmd_report)
+
+    api_parser = subparsers.add_parser("api", help="Start the FastAPI monitoring server on :8001")
+    api_parser.set_defaults(func=cmd_api)
+
+    webui_parser = subparsers.add_parser("webui", help="Start the webui dev server (npm run dev)")
+    webui_parser.set_defaults(func=cmd_webui)
+
+    docker_parser = subparsers.add_parser("docker", help="Docker Compose shortcuts")
+    docker_subparsers = docker_parser.add_subparsers(dest="docker_command", required=True)
+
+    docker_up_parser = docker_subparsers.add_parser("up", help="Start infra services")
+    docker_up_group = docker_up_parser.add_mutually_exclusive_group()
+    docker_up_group.add_argument("--lean", action="store_true", help="Start via the lean Compose profile")
+    docker_up_group.add_argument("--all", action="store_true", help="Start the full stack, including all workers")
+    docker_up_parser.set_defaults(func=cmd_docker_up)
+
+    docker_build_parser = docker_subparsers.add_parser("build", help="Rebuild the aether-quant app image")
+    docker_build_parser.set_defaults(func=cmd_docker_build)
+
+    retrain_parser = subparsers.add_parser(
+        "retrain", help="Thin dispatcher to python -m retraining.orchestrator <stage> ..."
+    )
+    retrain_parser.add_argument(
+        "stage",
+        choices=["plan", "train", "train_topology", "validate", "backtest", "commit", "promote", "rollback", "status"],
+    )
+    retrain_parser.add_argument("retrain_args", nargs=argparse.REMAINDER, help="Passed through verbatim, e.g. --version-id <uuid>")
+    retrain_parser.set_defaults(func=cmd_retrain)
+
+    trade_lock_parser = subparsers.add_parser(
+        "trade-lock", help="Manually override the sticky total-drawdown trade lock"
+    )
+    trade_lock_group = trade_lock_parser.add_mutually_exclusive_group(required=True)
+    trade_lock_group.add_argument("--on", action="store_true", help="Force trading paused")
+    trade_lock_group.add_argument("--off", action="store_true", help="Force trading resumed")
+    trade_lock_group.add_argument("--auto", action="store_true", help="Return to fully automatic behavior")
+    trade_lock_group.add_argument("--status", dest="status", action="store_true", help="Print the current override state")
+    trade_lock_parser.set_defaults(func=cmd_trade_lock)
+
+    status_parser = subparsers.add_parser("status", help="Show git status")
+    status_parser.set_defaults(func=cmd_status)
+
+    return parser
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    exit_code = args.func(args)
+    check_for_update()
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

risk/README.md

@@ -0,0 +1,19 @@
+# risk
+
+Owns V2 dynamic risk controls:
+
+- volatility-adjusted position sizing
+- leverage caps
+- drawdown-aware sizing
+- liquidity checks
+- market-impact and slippage controls
+
+This package should reuse the existing conservative risk-control behavior and extend it gradually.
+
+Current V2-7 behavior:
+
+- classifies rolling volatility into low, normal and high regimes
+- scales target position weight toward a target daily volatility
+- reduces exposure in high-volatility regimes
+- allows controlled expansion in low-volatility regimes
+- emits leverage/sizing telemetry for the future HTML volatility dashboard

risk/__init__.py

@@ -0,0 +1,16 @@
+"""Dynamic risk, leverage and liquidity controls for Aether Quant V2."""
+
+from .manual_override import read_manual_trade_lock_override, write_manual_trade_lock_override
+from .position_sizing import (
+    PositionSizingDecision,
+    build_dynamic_position_sizing,
+    classify_volatility_regime,
+)
+
+__all__ = [
+    "PositionSizingDecision",
+    "build_dynamic_position_sizing",
+    "classify_volatility_regime",
+    "read_manual_trade_lock_override",
+    "write_manual_trade_lock_override",
+]

risk/manual_override.py

@@ -0,0 +1,61 @@
+"""Manual trade-lock override for Aether Quant V2.
+
+`main.py`'s sticky total-drawdown lock (see `_refresh_risk_state()`) never
+auto-clears on its own once tripped - by design, a capital-preservation
+circuit breaker requiring a deliberate decision to resume trading. This
+module is that deliberate decision, expressed as a single config value:
+`phase_v2.risk.manual_trade_lock_override` (`true` = force-lock, `false` =
+force-clear, absent/`null` = leave today's automatic behavior untouched).
+
+Two callers, both read-modify-write the same key:
+- `aq_cli.py`'s `trade-lock` command - a human flips the switch directly.
+- `retraining/orchestrator.py::promote()` - a successful promotion clears it
+  automatically, tying "trading resumes" to "a genuinely new model shipped".
+
+This is the first place in the codebase where a Python process writes to
+`config.json` (every other reader treats it as human-edited, read-only
+input) - a deliberate, narrow exception, not a new general pattern. It is a
+*standing* switch, not one-shot: it stays in effect until explicitly changed
+again, so `main.py` itself never writes back to `config.json` - it only
+reads this one key once per session rollover (see `_refresh_risk_state()`).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+_PHASE_V2_KEY = "phase_v2"
+_RISK_KEY = "risk"
+_OVERRIDE_KEY = "manual_trade_lock_override"
+
+
+def read_manual_trade_lock_override(config_path: Path) -> bool | None:
+    """Returns True/False if a manual override is set, None if absent/unset
+    or the config file doesn't exist yet - never raises."""
+    if not config_path.exists():
+        return None
+    with config_path.open("r", encoding="utf-8") as f:
+        config = json.load(f)
+    value = config.get(_PHASE_V2_KEY, {}).get(_RISK_KEY, {}).get(_OVERRIDE_KEY)
+    return value if isinstance(value, bool) else None
+
+
+def write_manual_trade_lock_override(value: bool | None, config_path: Path) -> None:
+    """Read-modify-write config.json, setting only
+    phase_v2.risk.manual_trade_lock_override - every other key is preserved
+    untouched. value=None removes the override key entirely (returns to
+    fully automatic behavior)."""
+    with config_path.open("r", encoding="utf-8") as f:
+        config = json.load(f)
+
+    phase_v2 = config.setdefault(_PHASE_V2_KEY, {})
+    risk = phase_v2.setdefault(_RISK_KEY, {})
+    if value is None:
+        risk.pop(_OVERRIDE_KEY, None)
+    else:
+        risk[_OVERRIDE_KEY] = value
+
+    with config_path.open("w", encoding="utf-8") as f:
+        json.dump(config, f, indent=4)
+        f.write("\n")

risk/position_sizing.py

@@ -0,0 +1,113 @@
+"""Dynamic position sizing for Aether Quant V2."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass
+
+
+TRADING_DAYS_PER_YEAR = 252
+
+
+@dataclass(frozen=True)
+class PositionSizingDecision:
+    base_target_weight: float
+    target_weight: float
+    rolling_volatility: float
+    annualized_volatility: float
+    volatility_regime: str
+    volatility_multiplier: float
+    confidence_multiplier: float
+    leverage_factor: float
+    max_leverage: float
+    sizing_reason: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def classify_volatility_regime(
+    rolling_volatility: float,
+    low_volatility_threshold: float,
+    high_volatility_threshold: float,
+) -> str:
+    volatility = abs(float(rolling_volatility))
+    if volatility >= high_volatility_threshold:
+        return "high_volatility"
+    if volatility <= low_volatility_threshold:
+        return "low_volatility"
+    return "normal_volatility"
+
+
+def build_dynamic_position_sizing(
+    base_target_weight: float,
+    confidence: float,
+    rolling_volatility: float,
+    max_position_weight: float,
+    target_daily_volatility: float = 0.015,
+    min_position_weight: float = 0.0,
+    low_volatility_threshold: float = 0.01,
+    high_volatility_threshold: float = 0.03,
+    min_volatility_multiplier: float = 0.35,
+    max_volatility_multiplier: float = 1.25,
+    max_leverage: float = 1.0,
+) -> PositionSizingDecision:
+    base_target_weight = float(base_target_weight)
+    confidence = max(0.0, min(float(confidence), 1.0))
+    max_position_weight = max(float(max_position_weight), 0.0)
+    abs_base_target = abs(base_target_weight)
+    volatility = abs(float(rolling_volatility))
+    annualized_volatility = volatility * math.sqrt(TRADING_DAYS_PER_YEAR)
+    volatility_regime = classify_volatility_regime(
+        volatility,
+        low_volatility_threshold,
+        high_volatility_threshold,
+    )
+
+    if abs_base_target == 0.0 or confidence == 0.0 or max_position_weight == 0.0:
+        return PositionSizingDecision(
+            base_target_weight=base_target_weight,
+            target_weight=0.0,
+            rolling_volatility=volatility,
+            annualized_volatility=annualized_volatility,
+            volatility_regime=volatility_regime,
+            volatility_multiplier=0.0,
+            confidence_multiplier=0.0,
+            leverage_factor=0.0,
+            max_leverage=float(max_leverage),
+            sizing_reason="no_active_signal",
+        )
+
+    safe_volatility = max(volatility, 1e-6)
+    volatility_multiplier = target_daily_volatility / safe_volatility
+    volatility_multiplier = max(min_volatility_multiplier, min(volatility_multiplier, max_volatility_multiplier))
+    confidence_multiplier = 0.5 + 0.5 * confidence
+
+    sized_weight = abs_base_target * volatility_multiplier * confidence_multiplier
+    sized_weight = min(sized_weight, max_position_weight)
+    if sized_weight > 0.0 and min_position_weight > 0.0:
+        sized_weight = max(sized_weight, min_position_weight)
+
+    direction = 1.0 if base_target_weight >= 0.0 else -1.0
+    target_weight = direction * sized_weight
+    leverage_factor = min(float(max_leverage), sized_weight / max(abs_base_target, 1e-9))
+
+    if volatility_regime == "high_volatility":
+        reason = "reduced_for_high_volatility"
+    elif volatility_regime == "low_volatility" and volatility_multiplier > 1.0:
+        reason = "expanded_for_low_volatility"
+    else:
+        reason = "normal_volatility_sizing"
+
+    return PositionSizingDecision(
+        base_target_weight=base_target_weight,
+        target_weight=target_weight,
+        rolling_volatility=volatility,
+        annualized_volatility=annualized_volatility,
+        volatility_regime=volatility_regime,
+        volatility_multiplier=volatility_multiplier,
+        confidence_multiplier=confidence_multiplier,
+        leverage_factor=leverage_factor,
+        max_leverage=float(max_leverage),
+        sizing_reason=reason,
+    )