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

{aether_quant-0.3.0 → aether_quant-0.4.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.4.0}/PKG-INFO

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

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

@@ -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,77 @@ 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 | 2014-12-01 to 2018-08-15 |
+| Sharpe Ratio | -0.765 |
+| Net Profit | -7.955% |
+| Compounding Annual Return | -2.212% |
+| Drawdown | 12.100% |
+| Total Orders | 15 |
+| Win Rate | 0% |
+| Last updated | 2026-07-05 16:59 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 | 15 |
+| Average Win | 0% |
+| Average Loss | -1.64% |
+| Compounding Annual Return | -2.212% |
+| Drawdown | 12.100% |
+| Expectancy | -1 |
+| Start Equity | 100000 |
+| End Equity | 92045.02 |
+| Net Profit | -7.955% |
+| Sharpe Ratio | -0.765 |
+| Sortino Ratio | -0.531 |
+| Probabilistic Sharpe Ratio | 0.052% |
+| Loss Rate | 100% |
+| Win Rate | 0% |
+| Profit-Loss Ratio | 0 |
+| Alpha | -0.043 |
+| Beta | 0.224 |
+| Annual Standard Deviation | 0.036 |
+| Annual Variance | 0.001 |
+| Information Ratio | -1.103 |
+| Tracking Error | 0.087 |
+| Treynor Ratio | -0.123 |
+| Total Fees | $14.51 |
+| Estimated Strategy Capacity | $310000000.00 |
+| Lowest Capacity Asset | IBM R735QTJ8XC9X |
+| Portfolio Turnover | 0.06% |
+| Drawdown Recovery | 57 |
+<!-- 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.
 
 ## Test Suite
 
@@ -344,11 +505,12 @@ 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 test`** — runs the pytest suite and refreshes this README's test badge.
@@ -360,6 +522,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.4.0}/aether_quant.egg-info/PKG-INFO

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

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

@@ -38,6 +38,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 +46,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
@@ -124,6 +126,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

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

@@ -43,6 +43,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 +153,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 +211,7 @@
     "tests/test_train_pipeline.py",
     "tests/test_experience_queue.py",
     "tests/test_vault_commands.py",
+    "tests/test_fetch.py",
     "data/alternative/sec/aapl/.keep",
     "data/alternative/trading-economics/.keep",
     "data/alternative/trading-economics/calendar/.keep",

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

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

{aether_quant-0.3.0 → aether_quant-0.4.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.4.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,11 @@ import subprocess
 import sys
 import time
 import urllib.request
+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 +97,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 {}
@@ -340,6 +355,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"])
 
@@ -409,6 +448,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.4.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.
+

aether_quant-0.4.0/data_pipeline/fetch.py

@@ -0,0 +1,134 @@
+"""Ad-hoc historical OHLCV fetch for tickers not (yet) in config.json.
+
+Distinct responsibility from yfinance_backfill.py: that module fills gaps in
+already-configured assets via a config.json "backfill" block, and
+deliberately never touches config.json (widening an *existing*, already
+-trained asset's date range is a decision a human should make explicitly).
+This module fetches an explicit date range for *any* ticker, including ones
+with no config.json entry at all, and — on --apply — *does* add a new asset
+block to config.json, because adding a brand-new ticker to the universe is
+this module's entire purpose, not an accidental side effect.
+
+Reuses yfinance_backfill.py's config.json-independent pure functions
+(fetch_yahoo_ohlcv, scale_for_lean, write_lean_zip) - no duplicated logic.
+
+Never runs `train.py` itself - preparing a ticker for training (fetching
+its data, formatting it for Lean, wiring it into config.json's universe) is
+this module's job; actually training on it stays a deliberate, separate
+step (`python train.py`).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Callable
+
+from data_pipeline.yfinance_backfill import fetch_yahoo_ohlcv, scale_for_lean, write_lean_zip
+
+ROOT = Path(__file__).resolve().parents[1]
+CONFIG_PATH = ROOT / "config.json"
+
+
+def _crypto_yahoo_symbol(ticker: str) -> str:
+    """BTCUSD -> BTC-USD, DOGEUSD -> DOGE-USD: strip a trailing USD and join
+    with a hyphen, matching Yahoo Finance's crypto pair naming convention."""
+    base = ticker[:-3] if ticker.upper().endswith("USD") else ticker
+    return f"{base}-USD"
+
+
+# One entry per asset class - adding "derivative" in V3 is one new entry
+# here (plus adding "derivative" to the CLI's `choices=`), not a redesign.
+ASSET_CLASS_CONFIG = {
+    "crypto": {
+        "security_type": "crypto",
+        "market": "coinbase",
+        "data_path_fn": lambda ticker: ROOT / "data" / "crypto" / "coinbase" / "daily" / f"{ticker.lower()}_trade.zip",
+        "yahoo_symbol_fn": _crypto_yahoo_symbol,
+    },
+    "stock": {
+        "security_type": "equity",
+        "market": "usa",
+        "data_path_fn": lambda ticker: ROOT / "data" / "equity" / "usa" / "daily" / f"{ticker.lower()}.zip",
+        "yahoo_symbol_fn": lambda ticker: ticker,
+    },
+}
+ASSET_CLASSES = tuple(ASSET_CLASS_CONFIG.keys())
+
+
+def add_asset_to_config(config_path: Path, asset_block: dict) -> str:
+    """Appends asset_block to config.json's phase1.universe.assets[] unless
+    a block with the same ticker already exists there. Returns "added" or
+    "already_exists". Preserves the file's existing exact formatting
+    (4-space indent, trailing newline)."""
+    config = json.loads(config_path.read_text(encoding="utf-8"))
+    assets = config["phase1"]["universe"]["assets"]
+
+    if any(existing["ticker"] == asset_block["ticker"] for existing in assets):
+        return "already_exists"
+
+    assets.append(asset_block)
+    config_path.write_text(json.dumps(config, indent=4) + "\n", encoding="utf-8")
+    return "added"
+
+
+def fetch_adhoc_asset(
+    asset_class: str,
+    ticker: str,
+    start: str,
+    end: str,
+    *,
+    apply: bool,
+    fetch_fn: Callable = fetch_yahoo_ohlcv,
+    config_path: Path = CONFIG_PATH,
+) -> dict:
+    """apply=False (default): dry run - fetches but writes nothing (no zip,
+    no config.json edit). apply=True: writes the Lean zip via
+    write_lean_zip(), then adds a new config.json asset block if this
+    ticker isn't already configured. fetch_fn is the injection point for
+    tests (never real yfinance in tests), matching
+    yfinance_backfill.run_backfill()'s exact convention."""
+    ticker = ticker.upper()
+    class_config = ASSET_CLASS_CONFIG[asset_class]
+    yahoo_symbol = class_config["yahoo_symbol_fn"](ticker)
+    output_zip = class_config["data_path_fn"](ticker)
+    security_type = class_config["security_type"]
+
+    rows = fetch_fn(yahoo_symbol, start, end)
+    scaled_rows = scale_for_lean(rows, security_type)
+
+    dates = [row["date"] for row in rows]
+    suggested_from = min(dates) if dates else None
+    suggested_to = max(dates) if dates else None
+
+    config_status = "not_attempted"
+    if not scaled_rows:
+        action = "no_data_returned"
+    elif apply:
+        write_lean_zip(output_zip, ticker, scaled_rows, merge_with_existing=True)
+        action = "written"
+        config_status = add_asset_to_config(
+            config_path,
+            {
+                "ticker": ticker,
+                "security_type": security_type,
+                "market": class_config["market"],
+                "data_path": output_zip.relative_to(ROOT).as_posix(),
+                "available_from": suggested_from.isoformat(),
+                "available_to": suggested_to.isoformat(),
+            },
+        )
+    else:
+        action = "dry_run"
+
+    return {
+        "ticker": ticker,
+        "asset_class": asset_class,
+        "yahoo_symbol": yahoo_symbol,
+        "data_path": str(output_zip),
+        "action": action,
+        "rows_fetched": len(rows),
+        "suggested_available_from": suggested_from.isoformat() if suggested_from else None,
+        "suggested_available_to": suggested_to.isoformat() if suggested_to else None,
+        "config_status": config_status,
+    }