aether-quant 0.3.0__tar.gz → 0.5.0__tar.gz

{aether_quant-0.3.0 → aether_quant-0.5.0}/.gitignore

@@ -94,3 +94,8 @@ Aether-quant-Obsidian-Vault/
 # Webui (React/Vite) build artifacts and dependencies
 webui/node_modules/
 webui/dist/
+
+# Matplotlib font cache, redirected here by main.py so it persists across
+# Lean CLI's ephemeral per-backtest Docker containers instead of rebuilding
+# every run (see Problems.md)
+.matplotlib_cache/

{aether_quant-0.3.0 → aether_quant-0.5.0}/Dockerfile.retraining_worker

@@ -8,7 +8,10 @@ COPY performance/ ./performance/
 COPY regime/ ./regime/
 COPY experts/ ./experts/
 COPY topology/ ./topology/
+COPY moe/ ./moe/
+COPY inference/ ./inference/
 COPY retraining/ ./retraining/
 COPY train.py .
 COPY train_topology.py .
+COPY train_gating.py .
 CMD ["python", "-m", "retraining.worker"]

{aether_quant-0.3.0 → aether_quant-0.5.0}/PKG-INFO

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

{aether_quant-0.3.0 → aether_quant-0.5.0}/README.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.10%2B-FF8C00?style=flat-square&labelColor=1A1A1A&logo=python&logoColor=white" alt="Python 3.10+">
-  <!-- AQ:TEST_BADGE_START --><img src="https://img.shields.io/badge/tests-528%2F528%20passing-brightgreen?style=flat-square&labelColor=1A1A1A" alt="528 of 528 tests passing"><!-- AQ:TEST_BADGE_END -->
+  <!-- AQ:TEST_BADGE_START --><img src="https://img.shields.io/badge/tests-583%2F583%20passing-brightgreen?style=flat-square&labelColor=1A1A1A" alt="583 of 583 tests passing"><!-- AQ:TEST_BADGE_END -->
   <img src="https://img.shields.io/pypi/v/aether-quant?style=flat-square&labelColor=1A1A1A&color=FF8C00" alt="PyPI version">
   <img src="https://img.shields.io/badge/docker-ghcr.io%2Faether--quant-2496ED?style=flat-square&labelColor=1A1A1A&logo=docker&logoColor=white" alt="Docker image on GHCR">
 </p>
@@ -35,6 +35,7 @@ window and hope it generalizes.
 - [Getting Started](#getting-started)
 - [Requirements](#requirements)
 - [Architecture](#architecture)
+- [Universe Size](#universe-size)
 - [Project Structure](#project-structure)
 - [Module Documentation](#module-documentation)
 - [Development Documentation](#development-documentation)
@@ -202,6 +203,105 @@ and more), the module map, and an honest analysis of what would need to
 change for this to become a genuinely low-latency/HFT system — see
 **[`development/v2_architecture.md`](development/v2_architecture.md)**.
 
+## Universe Size
+
+The trading universe currently spans **20 assets** — 15 equities and 5
+crypto pairs — defined in `config.json`'s `phase1.universe.assets` and
+shared across training, validation, and backtesting
+(`phase1.universe.common_window`: `2014-12-01` to `2021-03-31`).
+
+| Ticker | Type | Role |
+|---|---|---|
+| AAPL | Equity | Trading |
+| SPY | Equity | Trading |
+| QQQ | Equity | Trading |
+| IWM | Equity | Trading |
+| EEM | Equity | Trading |
+| BAC | Equity | Trading |
+| IBM | Equity | Trading |
+| AIG | Equity | Trading |
+| BNO | Equity | Trading |
+| FB | Equity | Trading |
+| GOOG | Equity | Trading |
+| GOOGL | Equity | Trading |
+| USO | Equity | Trading |
+| WM | Equity | Trading |
+| AAA | Equity | Observation-only (thin history) |
+| BTCUSD | Crypto | Trading |
+| ETHUSD | Crypto | Observation-only (thin history) |
+| LTCUSD | Crypto | Trading |
+| XRPUSD | Crypto | Observation-only (thin history) |
+| ADAUSD | Crypto | Observation-only (thin history) |
+
+"Observation-only" assets (Phase 9's `asset_quality` gate) are still fed
+through the full model/expert/topology pipeline every bar and visible on
+the dashboard, but are never sized into real positions — their real
+history is too short relative to the training window to be trusted for
+trading decisions (see [`development/Changelog.md`](development/Changelog.md)
+for the exact row-count thresholds). This is re-evaluated automatically
+every time `train.py` rebuilds the dataset, so an asset can move between
+these two roles as more history accumulates.
+
+```mermaid
+flowchart TD
+    DNN(("Baseline DNN<br/>+ MoE Experts<br/>bullish / bearish /<br/>sideways / volatility"))
+
+    subgraph Equities["Equities (15)"]
+        AAPL["AAPL"]
+        SPY["SPY"]
+        QQQ["QQQ"]
+        IWM["IWM"]
+        EEM["EEM"]
+        BAC["BAC"]
+        IBM["IBM"]
+        AIG["AIG"]
+        BNO["BNO"]
+        FB["FB"]
+        GOOG["GOOG"]
+        GOOGL["GOOGL"]
+        USO["USO"]
+        WM["WM"]
+        AAA["AAA"]
+    end
+
+    subgraph Crypto["Crypto (5)"]
+        BTCUSD["BTCUSD"]
+        ETHUSD["ETHUSD"]
+        LTCUSD["LTCUSD"]
+        XRPUSD["XRPUSD"]
+        ADAUSD["ADAUSD"]
+    end
+
+    AAPL --- DNN
+    SPY --- DNN
+    QQQ --- DNN
+    IWM --- DNN
+    EEM --- DNN
+    BAC --- DNN
+    IBM --- DNN
+    AIG --- DNN
+    BNO --- DNN
+    FB --- DNN
+    GOOG --- DNN
+    GOOGL --- DNN
+    USO --- DNN
+    WM --- DNN
+    AAA --- DNN
+    BTCUSD --- DNN
+    ETHUSD --- DNN
+    LTCUSD --- DNN
+    XRPUSD --- DNN
+    ADAUSD --- DNN
+
+    classDef hub fill:#1A1A1A,stroke:#FF8C00,color:#FF8C00,stroke-width:2px;
+    classDef trading fill:#FF8C00,stroke:#1A1A1A,color:#1A1A1A,stroke-width:1px;
+    classDef observation fill:#3A3A3A,stroke:#FF8C00,color:#FF8C00,stroke-width:1px,stroke-dasharray: 4 2;
+
+    class DNN hub;
+    class AAPL,SPY,QQQ,IWM,EEM,BAC,IBM,AIG,BNO,FB,GOOG,GOOGL,USO,WM,BTCUSD,LTCUSD trading;
+    class AAA,ETHUSD,XRPUSD,ADAUSD observation;
+```
+
 ## Project Structure
 
 ```text
@@ -291,16 +391,88 @@ and how it's wired in — this table is the index.
 
 | Metric | Value |
 |---|---|
-| Backtest window | 2014-12-01 to 2016-07-06 |
-| Last updated | 2026-07-05 15:37 UTC (auto-generated by `aq backtest`) |
+| Backtest window | 2018-04-01 to 2021-04-02 |
+| Sharpe Ratio | -0.71 |
+| Net Profit | -8.069% |
+| Compounding Annual Return | -2.761% |
+| Drawdown | 12.500% |
+| Total Orders | 27 |
+| Win Rate | 17% |
+| Last updated | 2026-07-06 17:20 UTC (auto-generated by `aq backtest`) |
 <!-- AQ:BACKTEST_END -->
 
+<details>
+<summary><strong>Full Lean statistics</strong> (Sharpe, Sortino, Alpha/Beta, fees, capacity, and everything else Lean reports)</summary>
+
+<!-- AQ:BACKTEST_FULL_STATS_START -->
+| Metric | Value |
+|---|---|
+| Total Orders | 27 |
+| Average Win | 0.18% |
+| Average Loss | -1.70% |
+| Compounding Annual Return | -2.761% |
+| Drawdown | 12.500% |
+| Expectancy | -0.816 |
+| Start Equity | 100000.00 |
+| End Equity | 91930.60 |
+| Net Profit | -8.069% |
+| Sharpe Ratio | -0.71 |
+| Sortino Ratio | -0.471 |
+| Probabilistic Sharpe Ratio | 0.171% |
+| Loss Rate | 83% |
+| Win Rate | 17% |
+| Profit-Loss Ratio | 0.11 |
+| Alpha | -0.058 |
+| Beta | 0.195 |
+| Annual Standard Deviation | 0.051 |
+| Annual Variance | 0.003 |
+| Information Ratio | -0.972 |
+| Tracking Error | 0.155 |
+| Treynor Ratio | -0.184 |
+| Total Fees | $12.00 |
+| Estimated Strategy Capacity | $210000000.00 |
+| Lowest Capacity Asset | IBM R735QTJ8XC9X |
+| Portfolio Turnover | 0.07% |
+| Drawdown Recovery | 503 |
+<!-- AQ:BACKTEST_FULL_STATS_END -->
+
+</details>
+
 This section is regenerated automatically every time you run `aq backtest`
 (see [`generate_backtest_report.py`](generate_backtest_report.py)) — it
 always reflects your most recent successful Lean backtest, reading directly
 from Lean's own result JSON (strategy equity curve, its native SPY benchmark
 series, and the full statistics block), so it never goes stale as long as
-you keep backtesting.
+you keep backtesting. Both the chart image and every statistic above are
+overwritten on each run — there is no manual step and nothing here can go
+stale relative to your last `aq backtest`.
+
+**What this backtest does *not* prove:** a bare `lean backtest .` run
+exercises the full inference stack (baseline model, all 4 experts, MoE
+gating, regime, topology, liquidity) every bar, but it does **not**
+exercise the controlled retraining loop — the "learning while trading"
+half of this system's thesis. That loop is a decoupled, asynchronous
+pipeline (`main.py` → Redis → experience-worker → Postgres →
+performance-trigger-worker → retraining-worker), and a bare backtest run
+outside the Docker Compose network can't even reach Redis — events are
+dropped with a warning, so nothing reaches Postgres, no performance
+trigger can fire, and no retraining ever runs (see
+`development/infrastructure.md`). Exercising retraining for real requires
+the full Compose stack up (`docker compose up -d redis postgres
+experience-worker performance-trigger-worker retraining-worker`) with the
+backtest run inside that network, plus an actual trigger condition being
+met during the run.
+
+**If `phase_v2.backtest.bypass_safety_gates` is `true`:** this backtest
+also does not represent live/paper-deployable behavior. That flag (default
+`false`) disables the sticky total-drawdown lock and the regime detector's
+drawdown-driven `risk_off` override — both real, designed safety behavior
+in live/paper mode — purely to generate enough trade volume for
+statistically meaningful backtest metrics (see `development/Problems.md`
+#18). A backtest run with this flag set shows the underlying model's
+signal quality across more market conditions, not what this system would
+have actually done if deployed — in live/paper mode, both gates would have
+genuinely halted trading exactly as designed.
 
 ## Test Suite
 
@@ -334,7 +506,7 @@ pip install -e .
 Either way, `aq --help` gives the full command list:
 
 ```text
-aq train [--dataset-only|--init-only|--experts-only]
+aq train [--dataset-only|--init-only|--experts-only|--gating-only]
 aq test
 aq backtest
 aq report <backtest-folder> <result-id>
@@ -344,13 +516,14 @@ aq docker up [--lean|--all]
 aq docker build
 aq retrain <plan|train|validate|backtest|commit|promote|rollback|status> [...]
 aq trade-lock --on|--off|--auto|--status
+aq fetch <crypto|stock> --ticker <TICKER> --start <YYYY-MM-DD> --end <YYYY-MM-DD> [--apply]
 aq status
 ```
 
-Every command except `aq trade-lock` is a thin `subprocess` wrapper around a
-command already documented elsewhere in this README:
+Every command except `aq trade-lock` and `aq fetch` is a thin `subprocess`
+wrapper around a command already documented elsewhere in this README:
 
-- **`aq train`** — runs `train.py`: builds the dataset and trains the baseline + expert models.
+- **`aq train`** — runs `train.py`: builds the dataset and trains the baseline + expert models. `--gating-only` trains just the learned gating blend (`train_gating.py`) and installs it straight into active `ml/`, mirroring what `--experts-only` already does for the expert models — see `moe/README.md`.
 - **`aq test`** — runs the pytest suite and refreshes this README's test badge.
 - **`aq backtest`** — runs `lean backtest .` and refreshes this README's [Backtest Results](#backtest-results) section.
 - **`aq report <backtest-folder> <result-id>`** — generates Lean's own HTML backtest report (trade blotter, standard Lean charts) at `backtests/<backtest-folder>/report.html`.
@@ -360,6 +533,7 @@ command already documented elsewhere in this README:
 - **`aq docker build`** — rebuilds the `aether-quant` app image.
 - **`aq retrain <stage>`** — dispatches to `python -m retraining.orchestrator <stage> ...` for a single manual pipeline stage.
 - **`aq trade-lock --on|--off|--auto|--status`** — manually overrides `main.py`'s sticky total-drawdown trade lock (see `development/v2_architecture.md`'s Manual Trade-Lock Override Contract). `--off` deliberately clears an otherwise-permanent lock; `--auto` returns to fully automatic behavior.
+- **`aq fetch <crypto|stock> --ticker <TICKER> --start <YYYY-MM-DD> --end <YYYY-MM-DD> [--apply]`** — fetches historical OHLCV from Yahoo Finance for a ticker that isn't in `config.json` yet, formats it into Lean's zip/CSV convention, and writes it to the right spot under `data/` (`data/crypto/coinbase/daily/<ticker>_trade.zip` or `data/equity/usa/daily/<ticker>.zip`). On `--apply`, it also appends a new asset block to `config.json`'s `phase1.universe.assets[]` — no manual editing needed. Dry run by default (no `--apply`): reports what would happen, writes nothing. Never runs `train.py` itself — once applied, run `python train.py --dataset-only` (then `python train.py` when ready) yourself to actually train on the new ticker. `crypto`/`stock` today; a `derivative` asset class is planned for V3.
 - **`aq status`** — shows `git status`.
 
 ## Release Process

{aether_quant-0.3.0 → aether_quant-0.5.0}/aether_quant.egg-info/PKG-INFO

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

{aether_quant-0.3.0 → aether_quant-0.5.0}/aether_quant.egg-info/SOURCES.txt

@@ -14,6 +14,7 @@ main.py
 pyproject.toml
 risk_controls.py
 train.py
+train_gating.py
 train_topology.py
 .github/workflows/ci.yml
 .github/workflows/release.yml
@@ -38,6 +39,7 @@ data/alternative/trading-economics/earnings/.keep
 data/alternative/trading-economics/indicator/.keep
 data_pipeline/README.md
 data_pipeline/__init__.py
+data_pipeline/fetch.py
 data_pipeline/v2_manifest.py
 data_pipeline/yfinance_backfill.py
 development/Changelog.md
@@ -45,6 +47,7 @@ development/Problems.md
 development/README.md
 development/backtest_equity_chart.png
 development/infrastructure.md
+development/logo.png
 development/v2_architecture.md
 execution/README.md
 execution/__init__.py
@@ -72,6 +75,12 @@ liquidity/README.md
 liquidity/__init__.py
 liquidity/market_liquidity.py
 ml/README.md
+ml/gating_feature_schema.json
+ml/gating_model.json
+ml/gating_training_metrics.json
+ml/versions/gating-only-26218402-34d9-4a0a-add8-ee5d50dd0459/gating_feature_schema.json
+ml/versions/gating-only-26218402-34d9-4a0a-add8-ee5d50dd0459/gating_model.json
+ml/versions/gating-only-26218402-34d9-4a0a-add8-ee5d50dd0459/gating_training_metrics.json
 moe/README.md
 moe/__init__.py
 moe/gating.py
@@ -124,6 +133,7 @@ tests/test_experience_queue.py
 tests/test_expert_datasets.py
 tests/test_expert_models.py
 tests/test_exported_model.py
+tests/test_fetch.py
 tests/test_gating_network.py
 tests/test_generate_backtest_report.py
 tests/test_lean_backtest.py
@@ -158,6 +168,7 @@ tests/test_status_export.py
 tests/test_telegram_alerts.py
 tests/test_telegram_client.py
 tests/test_telegram_worker.py
+tests/test_train_gating.py
 tests/test_train_pipeline.py
 tests/test_train_topology.py
 tests/test_trigger_worker.py

{aether_quant-0.3.0 → aether_quant-0.5.0}/aether_quant.egg-info/scm_file_list.json

@@ -1,6 +1,7 @@
 {
   "files": [
     "README.md",
+    "train_gating.py",
     "Dockerfile.workers",
     "aq_cli.py",
     "Dockerfile",
@@ -43,6 +44,7 @@
     "data_pipeline/README.md",
     "data_pipeline/__init__.py",
     "data_pipeline/v2_manifest.py",
+    "data_pipeline/fetch.py",
     "data_pipeline/yfinance_backfill.py",
     "visualization/README.md",
     "inference/README.md",
@@ -152,6 +154,7 @@
     "webui/src/types/state.ts",
     "webui/public/favicon.svg",
     "webui/public/icons.svg",
+    "development/logo.png",
     "development/backtest_equity_chart.png",
     "development/README.md",
     "development/Problems.md",
@@ -209,6 +212,8 @@
     "tests/test_train_pipeline.py",
     "tests/test_experience_queue.py",
     "tests/test_vault_commands.py",
+    "tests/test_train_gating.py",
+    "tests/test_fetch.py",
     "data/alternative/sec/aapl/.keep",
     "data/alternative/trading-economics/.keep",
     "data/alternative/trading-economics/calendar/.keep",
@@ -224,6 +229,12 @@
     "requirements/requirements-workers.txt",
     "requirements/requirements-retraining-worker.txt",
     "ml/README.md",
+    "ml/gating_model.json",
+    "ml/gating_feature_schema.json",
+    "ml/gating_training_metrics.json",
+    "ml/versions/gating-only-26218402-34d9-4a0a-add8-ee5d50dd0459/gating_model.json",
+    "ml/versions/gating-only-26218402-34d9-4a0a-add8-ee5d50dd0459/gating_feature_schema.json",
+    "ml/versions/gating-only-26218402-34d9-4a0a-add8-ee5d50dd0459/gating_training_metrics.json",
     ".github/workflows/release.yml",
     ".github/workflows/ci.yml"
   ]

aether_quant-0.5.0/aether_quant.egg-info/scm_version.json

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

{aether_quant-0.3.0 → aether_quant-0.5.0}/aether_quant.egg-info/top_level.txt

@@ -1,4 +1,5 @@
 aq_cli
+data_pipeline
 execution
 generate_backtest_report
 risk

{aether_quant-0.3.0 → aether_quant-0.5.0}/analyzer/README.md

@@ -38,6 +38,17 @@ risk engine, and before action categorization / Lean order placement.
   explicitly ruled out of scope for that phase as a materially riskier
   change than what its safety rule ("confidence/uncertainty only, never a
   randomized decision") allows.
+  - **Follow-up:** the learned topology overlay's confidence/disagreement
+    scores now *do* reach a real trade — but through position sizing
+    (`risk/position_sizing.py::topology_sizing_multiplier()`), not this
+    module. That integration point was chosen specifically because sizing
+    is already a continuous, shrink-only multiplier applied after this
+    analyzer has categorized the action, so it changes only *how large* an
+    already-approved trade is, never *whether* one happens — preserving
+    exactly the "confidence/uncertainty only, never a randomized decision"
+    rule above. This module's own `trade`/`simulate`/`observe`/
+    `reduce_risk` categorization remains fully deterministic and
+    unaffected. See `risk/README.md` for details.
 - `main.py` only calls `_apply_signal` when `action == "trade"`. All five
   actions are written into the per-asset `signal_payload` for
   dashboard/Grafana visibility regardless of whether a real order is

{aether_quant-0.3.0 → aether_quant-0.5.0}/aq_cli.py

@@ -3,11 +3,12 @@
 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.
+than `trade-lock` and `fetch` 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` and `fetch` are the two
+exceptions: they call `risk/manual_override.py` and
+`data_pipeline/fetch.py` directly, in-process, 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
@@ -31,9 +32,12 @@ import subprocess
 import sys
 import time
 import urllib.request
+import uuid
+from datetime import date
 from importlib.metadata import version as installed_version
 from pathlib import Path
 
+from data_pipeline.fetch import ASSET_CLASSES, fetch_adhoc_asset
 from risk.manual_override import read_manual_trade_lock_override, write_manual_trade_lock_override
 
 ROOT_DIR = Path(__file__).resolve().parent
@@ -94,6 +98,18 @@ def _parse_simple_version(value: str) -> tuple[int, ...] | None:
         return None
 
 
+def _iso_date(value: str) -> str:
+    """Validates --start/--end as strict ISO 8601 YYYY-MM-DD, matching the
+    convention used everywhere else in this repo (config.json,
+    yfinance_backfill.py) - rejects other formats (e.g. DD.MM.YYYY) with a
+    clear error instead of a confusing downstream yfinance failure."""
+    try:
+        date.fromisoformat(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"invalid date {value!r} - expected ISO 8601 YYYY-MM-DD") from exc
+    return value
+
+
 def _read_update_cache() -> dict:
     if not UPDATE_CACHE_PATH.exists():
         return {}
@@ -161,6 +177,8 @@ def check_for_update() -> None:
 
 
 def cmd_train(args: argparse.Namespace) -> int:
+    if args.gating_only:
+        return _train_gating_only()
     cmd = [sys.executable, "train.py"]
     if args.dataset_only:
         cmd.append("--dataset-only")
@@ -171,6 +189,41 @@ def cmd_train(args: argparse.Namespace) -> int:
     return _run(cmd)
 
 
+def _train_gating_only() -> int:
+    """`aq train --gating-only`: trains the learned gating blend
+    (train_gating.py) and installs it straight into active ml/, mirroring
+    what `train.py --experts-only` already does for the expert models.
+
+    train_gating.py always writes to ml/versions/<version_id>/ (same
+    versioned-candidate convention every other trainer in this project
+    uses), so this generates a throwaway version-id, runs the trainer,
+    then copies the 3 resulting artifacts into active ml/ - the same
+    manual promotion-simulation step already documented for verifying this
+    trainer, skipping the full retraining/validate/backtest/commit/promote
+    pipeline since this is an ad-hoc, user-triggered run, not a scheduled
+    candidate."""
+    version_id = f"gating-only-{uuid.uuid4()}"
+    returncode = _run([sys.executable, "train_gating.py", "--version-id", version_id])
+    if returncode != 0:
+        return returncode
+
+    version_dir = ROOT_DIR / "ml" / "versions" / version_id
+    artifact_names = ("gating_model.json", "gating_feature_schema.json", "gating_training_metrics.json")
+    if any(not (version_dir / name).exists() for name in artifact_names):
+        print(
+            "aq train --gating-only: train_gating.py exited 0 but skipped writing artifacts "
+            "(likely insufficient validation/backtest rows) - active ml/ left unchanged.",
+            file=sys.stderr,
+        )
+        return 0
+
+    ml_dir = ROOT_DIR / "ml"
+    for name in artifact_names:
+        shutil.copy2(version_dir / name, ml_dir / name)
+    print(f"aq train --gating-only: copied {', '.join(artifact_names)} into active ml/.")
+    return 0
+
+
 def _update_readme_test_badge(passed: int, failed: int) -> None:
     """Atomically rewrites the shields.io test-count badge between the
     AQ:TEST_BADGE markers in README.md, so it never drifts from the real
@@ -340,6 +393,30 @@ def cmd_trade_lock(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_fetch(args: argparse.Namespace) -> int:
+    report = fetch_adhoc_asset(args.asset_class, args.ticker, args.start, args.end, apply=args.apply)
+    label = "APPLY" if args.apply else "DRY RUN"
+    print(f"{label} — {report['ticker']} ({report['yahoo_symbol']}): {report['action']}, rows_fetched={report['rows_fetched']}")
+    if report["suggested_available_from"]:
+        print(f"    date range fetched: {report['suggested_available_from']} .. {report['suggested_available_to']}")
+    print(f"    data_path: {report['data_path']}")
+
+    if report["config_status"] == "added":
+        print(f"    config.json: added a new {report['ticker']} asset block to phase1.universe.assets[]")
+    elif report["config_status"] == "already_exists":
+        print(
+            f"    config.json: {report['ticker']} is already configured - left untouched. "
+            "Use data_pipeline/yfinance_backfill.py to extend an existing asset's date range instead."
+        )
+
+    if not args.apply:
+        print("\nDry run only — nothing was written. Re-run with --apply to write the zip file and update config.json.")
+    elif report["action"] == "written":
+        print("\nReady to prepare training: run `python train.py --dataset-only` to confirm this ticker's asset quality, then `python train.py` when ready.")
+
+    return 1 if report["action"] == "no_data_returned" else 0
+
+
 def cmd_status(_args: argparse.Namespace) -> int:
     return _run(["git", "status"])
 
@@ -353,6 +430,9 @@ def build_parser() -> argparse.ArgumentParser:
     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_group.add_argument(
+        "--gating-only", action="store_true", help="Train the learned gating blend only (wraps python train_gating.py)"
+    )
     train_parser.set_defaults(func=cmd_train)
 
     test_parser = subparsers.add_parser("test", help="Run the test suite (wraps pytest tests/)")
@@ -409,6 +489,20 @@ def build_parser() -> argparse.ArgumentParser:
     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)
 
+    fetch_parser = subparsers.add_parser(
+        "fetch", help="Ad-hoc fetch of historical OHLCV from Yahoo Finance for a ticker not yet in config.json"
+    )
+    fetch_parser.add_argument(
+        "asset_class", choices=list(ASSET_CLASSES), help="Asset class (picks the Lean data_path/market convention)"
+    )
+    fetch_parser.add_argument("--ticker", required=True, help="Internal ticker, e.g. AAPL or BTCUSD")
+    fetch_parser.add_argument("--start", required=True, type=_iso_date, help="Start date, ISO 8601 YYYY-MM-DD")
+    fetch_parser.add_argument("--end", required=True, type=_iso_date, help="End date, ISO 8601 YYYY-MM-DD")
+    fetch_parser.add_argument(
+        "--apply", action="store_true", help="Actually write the zip file and update config.json (default: dry run, report only)"
+    )
+    fetch_parser.set_defaults(func=cmd_fetch)
+
     status_parser = subparsers.add_parser("status", help="Show git status")
     status_parser.set_defaults(func=cmd_status)
 

{aether_quant-0.3.0 → aether_quant-0.5.0}/data_pipeline/README.md

@@ -35,3 +35,30 @@ Usage: `python -m data_pipeline.yfinance_backfill [--tickers ETHUSD LTCUSD] [--a
 `yfinance` is a dev-only dependency (`requirements/requirements-dev.txt`),
 never in `requirements.txt`/`requirements-runtime.txt`.
 
+## Ad-hoc ticker fetch (`aq fetch`)
+
+`fetch.py` is a narrower sibling to `yfinance_backfill.py` above, with a
+different scope and a deliberately different `config.json` policy:
+
+|  | `yfinance_backfill.py` | `fetch.py` (backs `aq fetch`) |
+|---|---|---|
+| Scope | Fills gaps in **already-configured** assets | Fetches **any** ticker, including ones with no `config.json` entry at all |
+| Date range | Auto-detected gap vs. the asset's `"backfill"` block | Explicit `--start`/`--end` |
+| `config.json` | **Never** edited — only prints suggested values | **Writes** a new asset block on `--apply`, for a ticker that isn't already configured |
+
+The differing `config.json` policy is deliberate, not an inconsistency:
+`yfinance_backfill.py`'s rule exists to stop it from silently widening an
+*existing*, already-trained asset's date range without a human decision.
+`fetch.py` exists specifically to *add a brand-new ticker* to the universe
+on purpose — auto-writing `config.json` there is the intended effect, not
+an accidental side effect. If a ticker fetched via `aq fetch` already has a
+`config.json` entry, `fetch.py` leaves it untouched and points at
+`yfinance_backfill.py` instead, since extending an existing asset's range
+is that script's job, not this one's.
+
+Reuses `yfinance_backfill.py`'s pure functions (`fetch_yahoo_ohlcv`,
+`scale_for_lean`, `write_lean_zip`) unchanged — no duplicated logic. Same
+dry-run-by-default/`--apply` safety convention. Never runs `train.py`
+itself; see the root [`README.md`](../README.md#cli-reference) for the
+full `aq fetch` usage.
+