aether-quant 0.0.1__py3-none-any.whl

audit/redis_queue.py

@@ -0,0 +1,124 @@
+"""Redis Stream publisher for the audit log (development/Problems.md #42).
+
+Mirrors experience/redis_queue.py exactly - same fire-and-forget, never-raises
+publish contract, so audit logging can be called from main.py's hot per-bar
+order-placement path (and from execution/'s credential-load/live-mode-transition
+call sites) without ever risking a real trade or a live process on a Postgres
+round-trip. All Redis failures are caught and logged; nothing downstream of
+this queue is ever blocking.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from json_safety import dumps_json_safe
+
+logger = logging.getLogger(__name__)
+
+# The three event categories development/Problems.md #42 named as needing a
+# tamper-evident trail before real capital. Kept as a closed set (not
+# free-form strings) so a typo at a call site fails loudly in tests rather
+# than silently creating a new, unqueryable event_type.
+ORDER_PLACEMENT = "order_placement"
+CREDENTIAL_LOAD = "credential_load"
+LIVE_MODE_TRANSITION = "live_mode_transition"
+EVENT_TYPES = (ORDER_PLACEMENT, CREDENTIAL_LOAD, LIVE_MODE_TRANSITION)
+
+
+def build_audit_event(event_type: str, payload: dict, actor: str = "system") -> dict[str, Any]:
+    """Construct a standardised audit event dict. Pure - no I/O.
+
+    `payload` should never contain a raw secret value - callers logging a
+    credential-load event pass field NAMES that were populated (see
+    execution/lean_config_render.py's own "never the values" convention),
+    never the credential itself. `actor` defaults to "system" (an automated
+    call site, e.g. main.py's order placement) - execution/'s CLI-driven
+    call sites (aq render-lean-config) pass "cli" instead."""
+    if event_type not in EVENT_TYPES:
+        raise ValueError(f"Unknown audit event_type: {event_type!r} (expected one of {EVENT_TYPES})")
+    return {
+        "event_id": str(uuid.uuid4()),
+        "event_type": event_type,
+        "created_at": datetime.now(tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "actor": actor,
+        "payload": payload,
+    }
+
+
+class AuditQueue:
+    """Fire-and-forget Redis Stream publisher for audit events.
+
+    Identical shape/contract to experience.redis_queue.ExperienceQueue -
+    all failures (connection errors, XADD errors, missing package) are
+    caught and logged at WARNING level. push() never raises.
+
+    Parameters
+    ----------
+    enabled     : kill switch - if False, push() is always a no-op
+    redis_url   : connection URL; overridden by AETHER_REDIS_URL env var
+    stream_name : Redis key for XADD (default: "aether:audit")
+    maxlen      : approximate cap on stream length (MAXLEN ~)
+    _client     : pre-built Redis client for test injection
+    """
+
+    def __init__(
+        self,
+        enabled: bool = True,
+        redis_url: str = "redis://localhost:6380/0",
+        stream_name: str = "aether:audit",
+        maxlen: int = 500_000,
+        _client=None,
+    ) -> None:
+        self.enabled = enabled
+        self.stream_name = stream_name
+        self.maxlen = maxlen
+        self._client = None
+
+        if not enabled:
+            return
+
+        if _client is not None:
+            self._client = _client
+            return
+
+        url = os.environ.get("AETHER_REDIS_URL", redis_url) or "redis://localhost:6380/0"
+        try:
+            import redis as redis_lib  # deferred — not always installed in Lean environments
+
+            client = redis_lib.from_url(url, socket_connect_timeout=2, socket_timeout=2)
+            client.ping()
+            self._client = client
+            logger.info(
+                "AuditQueue connected to %s (stream=%s, maxlen=%d)",
+                url,
+                stream_name,
+                maxlen,
+            )
+        except Exception as exc:
+            logger.warning(
+                "AuditQueue: Redis unavailable at %s — audit events will be skipped. (%s)",
+                url,
+                exc,
+            )
+
+    def push(self, event: dict) -> bool:
+        """Publish one event dict to the Redis Stream. Returns True on
+        success, False on any failure. Never raises."""
+        if not self.enabled or self._client is None:
+            return False
+        try:
+            self._client.xadd(
+                self.stream_name,
+                {"payload": dumps_json_safe(event)},
+                maxlen=self.maxlen,
+                approximate=True,
+            )
+            return True
+        except Exception as exc:
+            logger.warning("AuditQueue.push failed: %s", exc)
+            return False

audit/status_export.py

@@ -0,0 +1,62 @@
+"""Dashboard/monitoring JSON export for the audit log (development/Problems.md
+#42). Same reason as retraining/status_export.py: main.py never connects to
+Postgres, only Redis, so monitoring/api_server.py can't query audit_log
+directly - this module is the sole writer of
+visualization/grafana/audit_log.json, refreshed by audit/postgres_worker.py
+after every batch it persists (real-time-ish, not a periodic cron export,
+since a stale audit trail defeats its own purpose).
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from json_safety import atomic_write_json
+from .hash_chain import verify_chain
+from .postgres_audit import fetch_all_events_ordered, fetch_recent_events
+
+ROOT_DIR = Path(__file__).resolve().parent.parent
+DEFAULT_STATUS_PATH = ROOT_DIR / "visualization" / "grafana" / "audit_log.json"
+
+# Dashboard snapshot only ever shows the most recent N entries (unlike
+# `aq audit-log`'s CLI, which can page further back) - the webui panel is
+# "what's happened recently," not a full audit browser.
+_DASHBOARD_ENTRY_LIMIT = 50
+
+
+def _json_safe(value: Any) -> Any:
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if isinstance(value, dict):
+        return {key: _json_safe(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_json_safe(item) for item in value]
+    return value
+
+
+def build_audit_status_view(conn) -> dict:
+    """{generated_at, recent_events, chain_valid, total_entries}. Chain
+    verification runs over the FULL table (fetch_all_events_ordered), not
+    just the dashboard's recent-N slice - a tampered OLD entry must still
+    surface as chain_valid=False even if it's scrolled off the recent list."""
+    recent = fetch_recent_events(conn, limit=_DASHBOARD_ENTRY_LIMIT)
+    all_rows = fetch_all_events_ordered(conn)
+    chain_valid, broken_index = verify_chain(all_rows)
+
+    return {
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "total_entries": len(all_rows),
+        "chain_valid": chain_valid,
+        "chain_broken_at_event_id": all_rows[broken_index]["event_id"] if broken_index is not None else None,
+        "recent_events": [_json_safe(event) for event in recent],
+    }
+
+
+def write_status_file(status: dict, path: Path = DEFAULT_STATUS_PATH) -> None:
+    # V5.4.7 (Problems.md #120): atomic + finite-safe - the API reader
+    # previously raced this write and 500'd on torn JSON.
+    atomic_write_json(path, status, indent=2)
+
+

data_pipeline/README.md

@@ -0,0 +1,257 @@
+# data_pipeline
+
+Owns the Lean-data pipeline contract and the data-ingestion tooling around
+it.
+
+The core rule stays simple and important: training and backtesting use the local Lean `data/` folder. This package describes that contract for the downstream modules (MoE experts, regime detection, topology modeling, dynamic risk, the dashboards) so they can depend on a stable manifest.
+
+It does not replace `train.py`; it wraps and documents the existing dataset pipeline.
+
+## Modules
+
+- `v2_manifest.py` — the V2 metadata contract for the Lean-data training
+  pipeline (the "stable manifest" the rule above promises).
+- `fetch.py` — `aq fetch` (see below).
+- `yfinance_backfill.py` — Yahoo Finance historical backfill (see below).
+- `fred_backfill.py` — Treasury yield/credit-spread backfill (see below).
+- `ib_backfill.py` — Interactive Brokers futures/options backfill (see below).
+- `factor_file_backfill.py` — Lean-format split/dividend **factor-file**
+  backfill (the price-adjustment factors Lean reads alongside the price
+  zips; the missing-factor-file class of data-quality issue behind
+  `development/Problems.md` #91/#97/#99).
+- `dividend_backfill.py` — real ex-dividend history via `yfinance`, with
+  next-date projection from historical cadence; feeds
+  `portfolio/options_assignment_risk.py`'s early-assignment scoring.
+- `bar_synthesis.py` (V5.3.10) — pure functions extracted from `main.py`
+  so they are unit-testable without a Lean runtime:
+  `midpoint_bar_from_quote_bar()` (synthesizes a bar from forex/crypto
+  quote bars) and `pad_sequence_history()` (pads short history for the
+  sequence encoder), plus the adaptive sell-threshold helper. Parity-tested
+  in `tests/test_bar_synthesis_parity.py`.
+
+## Yahoo Finance historical data backfill
+
+`yfinance_backfill.py` is a deliberate, narrow exception to the rule above:
+it is the first thing in this package that reaches outside the local Lean
+`data/` folder, to fill gaps in thin series (initially `ETHUSD`/`LTCUSD`,
+which have only a few scattered days of real Coinbase minute data — see
+`train.py::ensure_derived_crypto_daily_series()` and this repo's Changelog).
+It is a **manual, offline maintenance script** — never invoked from
+`train.py`, `main.py`, or any Docker worker; no network calls happen during
+training or a backtest.
+
+- Per-asset opt-in via a `"backfill"` sub-block in `config.json`'s
+  `phase1.universe.assets[]` entries (`source`, `symbol`, `backfill_from`,
+  `backfill_to`). Assets without it are skipped entirely.
+- Fetched Yahoo rows are converted to the exact Lean zip format
+  (`train.py::ensure_derived_crypto_daily_series()`'s row/member-name
+  convention) and merged into the existing zip — **existing real Lean rows
+  always win on any overlapping date**; Yahoo data only fills genuine gaps.
+- **Dry run by default.** Writing zip files requires an explicit `--apply`
+  flag. Regardless of `--apply`, this script **never** edits `config.json`'s
+  `available_from`/`available_to` — it only prints the suggested new values,
+  because `train.py::build_asset_quality()` only counts rows inside those
+  configured windows, so a human must deliberately widen them for the extra
+  history to actually affect training/backtesting.
+
+Usage: `python -m data_pipeline.yfinance_backfill [--tickers ETHUSD LTCUSD] [--apply]`.
+`yfinance` is a dev-only dependency (`requirements/requirements-dev.txt`),
+never in `requirements.txt` (the one requirements file the consolidated
+`aether-quant-engine` Docker image installs).
+
+## 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.
+
+### Two data-provenance contracts, by design (`aq fetch` tickers are pre-adjusted)
+
+Every ticker fetched via `fetch_adhoc_asset()` (the bond ETF sleeve added in
+Phase 1 of the 5/10 -> 9/10 roadmap is the first real-universe example) goes
+through `fetch_yahoo_ohlcv()`'s `auto_adjust=True` — Yahoo applies its own
+split/dividend adjustment **before** the data ever reaches a Lean zip. This
+is a second, deliberate data-provenance contract living alongside the
+original one: the original ~15 equities (AAPL, SPY, ...) use **raw** Lean
+prices, adjusted separately at train time via a checked-in
+`data/equity/usa/factor_files/<ticker>.csv`
+(`train.py::apply_split_adjustments()`/`load_factor_file()`). An
+`aq fetch`-added ticker deliberately has **no** factor file — adding one
+would double-adjust already-adjusted prices — and `load_factor_file()`'s
+existing "return `None` when missing" behavior is the correct, intended
+no-op for this path, not an accidental gap (see
+`tests/test_train_pipeline.py::test_apply_split_adjustments_noop_is_the_intended_contract_for_aq_fetch_tickers`).
+This matters more for bond ETFs than most equities, since they distribute
+income frequently (often monthly) — an un-adjusted bond ETF price series
+would show a fake "return" on every distribution date.
+
+`fetch_adhoc_asset()` also does **not** write a Lean
+`data/equity/usa/map_files/<ticker>.csv` — that file is Lean's own
+local-disk security-resolution convention (a two-row identity map,
+`<start_date>,<ticker>,Q` / `20501231,<ticker>,Q`, mirroring e.g.
+`aapl.csv`) and every currently-active equity ticker in this universe
+already has one (bundled with QuantConnect's sample data, since no prior
+`aq fetch`-added ticker had ever been wired into an active universe before
+Phase 1). Since this repo's Lean backtests are run manually by the user
+(see the Runbook), rather than block on an automated `lean backtest` check
+this repo doesn't currently have Docker access to run, map files were
+created proactively for the bond ETF sleeve, following the exact identity
+format above — any future `aq fetch`-added ticker destined for the real
+universe should get one the same way until/unless a real Lean run confirms
+it's unnecessary.
+
+## Real Treasury yield/credit-spread backfill (`fred_backfill.py`)
+
+A third sibling, alongside `yfinance_backfill.py`/`fetch.py` above, backing
+`features/bond_features.py`'s real-data yield-curve/credit-spread features
+(distinct from `features/macro_features.py`'s price-momentum proxies).
+Fetches FRED's public graph CSV endpoint — **no API key required**, stdlib
+`urllib.request` only (no new runtime dependency, unlike
+`yfinance_backfill.py`'s deferred `import yfinance`). Same
+dry-run-by-default/`--apply` safety convention; writes a local cache
+(`data/reference/fred_series/*.csv`, never committed as real market data
+the way Lean zips are) rather than editing `config.json` at all — nothing
+in this codebase's asset universe schema needs to change for bond features
+to exist, since they're cross-asset macro signals broadcast to every asset,
+not a new configured ticker.
+
+`load_cached_fred_series()` is the read-side: loaded once at
+`train.py`/`main.py` startup (never fetched live mid-backtest — Lean
+backtests are date-bounded), `{}` if the cache was never populated (fresh
+clone), in which case every bond feature neutral-defaults to `0.0` — the
+same "missing reference -> 0.0" convention `macro_features.py` already
+established, never a crash.
+
+V5.4.7 (#123): cache writes MERGE by date — a narrow `--start/--end`
+refetch no longer destroys observations outside its window (new rows win
+their own dates). Same round: Yahoo NaN-frame rows are filtered before any
+zip write, and `aq fetch --apply`'s config.json rewrite is atomic.
+
+Usage: `python -m data_pipeline.fred_backfill [--series treasury_10yr ...] [--apply]`.
+
+### Alt-data extension (Phase 4.12, `development/Problems.md` #71)
+
+The same fetcher, generic series-ID passthrough, and cache convention
+above now also back `features/alt_data_features.py`: `VIXCLS` (CBOE VIX),
+`VXVCLS` (3-month VIX), and `NFCI` (Chicago Fed financial conditions) —
+`DEFAULT_ALT_DATA_REFERENCE_SERIES`. `--group {bond,alt,all}` selects which
+reference-series set to fetch (`reference_series(config, group="all")`,
+`alt_data_reference_series(config)`); `aq backfill fred --group alt
+--apply` fetches only the new three.
+
+**Publication lag is the one thing that matters here.** VIX/VXV are
+same-day CBOE closes (lag `0`), but NFCI is Friday-dated and not released
+until the following Wednesday — `ALT_DATA_PUBLICATION_LAG_DAYS` records
+each series' lag in days, and `series_value_asof(rows, current_date,
+publication_lag_days)`/`series_change_asof(rows, current_date,
+publication_lag_days, periods_back)` are the lag-aware lookups both
+`train.py::build_alt_data_features_by_date()` and
+`main.py::_build_alt_data_payload()` use — deliberately **not** the bare
+`_fred_series_asof()` bisect the bond features use, since that helper has
+no lag parameter and would silently look ahead on a lagged series.
+
+Candidate series were screened before adding (`BAMLH0A0HYM2` dropped for
+insufficient free-endpoint history, `STLFSI4` rejected as near-collinear
+with `NFCI`) — see `development/Changelog.md` for the screening details.
+
+## Interactive Brokers historical backfill (`ib_backfill.py`) — futures/options only
+
+The futures/options sibling to `fetch.py`, but a fundamentally different
+data source: `ib_insync` (a **dev-only** dependency,
+`requirements/requirements-dev.txt`, never in `requirements.txt` — this
+module is importable with `ib_insync` absent as long as IB stays
+disabled, same deferred-import convention as `yfinance_backfill.py`).
+
+This is deliberately a **separate integration** from Lean's own native
+live/paper Interactive Brokers brokerage (`lean.json`'s
+`ib-account`/`ib-user-name`/`ib-password`/`ib-trading-mode` fields, and
+`environments.live-interactive` — untouched by this module, see root
+`README.md`'s `aq ib` section for the full explanation of why there are
+two IB integrations, not one). Lean's `environments.backtesting` is
+hardcoded to `FileSystemDataFeed`/`SubscriptionDataReaderHistoryProvider`
+— it never talks to IB regardless of `lean.json`'s contents — so
+historical futures/options bars still need this separate, offline
+data-prep step to land as local Lean-format zip files before any backtest
+can use them.
+
+- **"IB ready" requires both**: `config.json`'s `phase_v2.ib.enabled ==
+  true` (Aether's own app-level feature flag) AND `lean.json`'s
+  `ib-account`/`ib-user-name` non-empty (Lean's own credential fields,
+  read-only from this module's perspective). `phase_v2.ib.host`/`port`/
+  `client_id` are TWS/IB Gateway **socket API connection settings only**
+  (not credentials — your Gateway session already handles login), a
+  second, independent API client alongside whatever Lean's own brokerage
+  uses when live-deployed (standard IB API pattern — Gateway supports
+  multiple simultaneous API clients).
+- Every public function raises `IBNotConfiguredError` — never a raw
+  traceback — when IB isn't ready, so `aq fetch futures`/`aq fetch
+  options` fail cleanly with a message pointing at `aq ib status`.
+- Plugs into `fetch.py::ASSET_CLASS_CONFIG`'s `"futures"`/`"options"`
+  entries the same way `yfinance_backfill.py`'s functions plug into
+  `"crypto"`/`"stock"` — `aq_cli.py::cmd_fetch()` builds a closure binding
+  the connected IB client + contract spec/expiry/strike/right before
+  calling the same `fetch_adhoc_asset()` every asset class shares.
+
+Usage: `aq fetch futures --ticker ES --start ... --end ... --expiry ... [--apply]`,
+`aq fetch options --ticker SPY --start ... --end ... --expiry ... --strike ... --right call [--apply]`
+— see root `README.md`'s CLI Reference.
+
+### Building a real training-time derivatives dataset (manual, per-contract)
+
+`train.py::build_derivatives_macro_features_by_date()` computes real
+futures term structure / options put-call-ratio / IV-skew features from
+whatever future/option assets are configured in `config.json` — but IB's
+historical API is per-contract and rate-limited, so there is no single
+bulk-fetch command for this. Building a useful training window means
+repeating `aq fetch futures`/`aq fetch options` once per contract:
+
+- **Futures term structure** needs at least two same-root contracts tagged
+  with the same `--family-ticker` and *different* `--contract-month`
+  (`YYYYMM`), e.g.:
+  ```text
+  aq fetch futures --ticker ES_FRONT --family-ticker ES --contract-month 202603 --start ... --end ... --expiry ... --apply
+  aq fetch futures --ticker ES_NEXT  --family-ticker ES --contract-month 202606 --start ... --end ... --expiry ... --apply
+  ```
+  Without `--contract-month`, `aq fetch futures` fetches Lean's default
+  *continuous* contract — fine for price/return features, but a single
+  continuous series can't produce a term-structure slope; you need two
+  distinct dated contracts for that.
+- **Options sentiment (put/call ratio, IV skew)** needs option assets
+  tagged with `--family-ticker <underlying>` (matching
+  `phase1.features.derivatives_reference_tickers.options_sentiment` in
+  `config.json`, default `"SPY"`) plus their own `--strike`/`--expiry`/
+  `--right`, e.g.:
+  ```text
+  aq fetch options --ticker SPY_500C --family-ticker SPY --strike 500 --expiry 2026-08-21 --right call --start ... --end ... --apply
+  aq fetch options --ticker SPY_490P --family-ticker SPY --strike 490 --expiry 2026-08-21 --right put  --start ... --end ... --apply
+  ```
+- Any family/underlying with too few tagged contracts (or missing
+  `strike`/`expiry`/`right` metadata) resolves to the neutral default
+  (0.0) for that feature, silently — never a crash. This is the honest
+  "no data configured" case, not a bug; run `aq assets status` to see
+  what's currently configured.
+- After fetching, run `python train.py --dataset-only` (then `python
+  train.py` when ready) to actually train on the new data — `aq fetch`
+  never trains anything itself.
+

data_pipeline/__init__.py

@@ -0,0 +1,6 @@
+"""Lean-data pipeline helpers for Aether Quant V2."""
+
+from .v2_manifest import build_v2_pipeline_manifest
+
+__all__ = ["build_v2_pipeline_manifest"]
+

data_pipeline/bar_synthesis.py

@@ -0,0 +1,97 @@
+"""V5.3.10 - pure functions extracted from main.py so the live-path logic
+they implement becomes unit-testable outside Lean's runtime (established
+pattern: evaluate_non_model_exit(), compute_incremental_order_quantity(),
+etc.). Each function is a VERBATIM copy of the corresponding main.py
+method body - see each function's docstring for its origin line."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+
+def midpoint_bar_from_quote_bar(quote_bar):
+    """V4.6 - forex quote-bar (bid/ask) to trade-bar-shaped midpoint OHLC
+    (main.py::_midpoint_bar_from_quote_bar verbatim). Volume is always
+    0.0 - forex quote data carries no trade-volume concept. Returns None
+    (never raises) when no quote bar exists or it's missing a bid/ask side."""
+    if quote_bar is None or quote_bar.Bid is None or quote_bar.Ask is None:
+        return None
+    return SimpleNamespace(
+        open=(float(quote_bar.Bid.Open) + float(quote_bar.Ask.Open)) / 2.0,
+        high=(float(quote_bar.Bid.High) + float(quote_bar.Ask.High)) / 2.0,
+        low=(float(quote_bar.Bid.Low) + float(quote_bar.Ask.Low)) / 2.0,
+        close=(float(quote_bar.Bid.Close) + float(quote_bar.Ask.Close)) / 2.0,
+        volume=0.0,
+    )
+
+
+def pad_sequence_history(history: list[list[float]], window_size: int) -> list[list[float]]:
+    """Left-pads a rolling per-symbol feature-history buffer with zero
+    vectors up to window_size (main.py::_pad_sequence_history verbatim).
+    Pure, no side effects. An empty history returns `window_size` all-zero
+    vectors of the model's width when inferable, else raises a clear
+    ValueError instead of IndexError (V5.4.7 #123)."""
+    if not history:
+        raise ValueError(
+            "pad_sequence_history: empty history - feature width cannot be "
+            "inferred; callers guard this before calling (main.py's own "
+            "truthy filters), so reaching here means a caller contract broke."
+        )
+    input_width = len(history[0])
+    padding_needed = window_size - len(history)
+    return [[0.0] * input_width for _ in range(max(0, padding_needed))] + list(history)
+
+
+def adaptive_sell_threshold(
+    *,
+    sell_threshold: float,
+    history: list[float] | None,
+    band_enabled: bool,
+    min_observations: int,
+    band_percentile: float,
+) -> float:
+    """Pure lookup + percentile over accumulated probability_up history
+    (main.py::_effective_sell_threshold verbatim). Never adapts ABOVE the
+    static threshold - the band only makes selling easier."""
+    if not band_enabled:
+        return sell_threshold
+    if history is None or len(history) < min_observations:
+        return sell_threshold
+    sorted_history = sorted(history)
+    index = max(0, min(len(sorted_history) - 1, int(band_percentile * len(sorted_history))))
+    return min(sell_threshold, sorted_history[index])
+
+
+def derive_signal(
+    probability_up: float,
+    *,
+    decision_threshold: float,
+    buy_threshold: float,
+    effective_sell_threshold: float,
+    max_position_weight: float,
+    record_observation=None,
+    symbol_key: str | None = None,
+) -> tuple[str, float, float]:
+    """Signal classification extracted from main.py::_derive_signal()
+    (verbatim arithmetic). `record_observation(symbol_key, probability_up)`
+    is an optional callback so callers can preserve the observation-recording
+    side effect without this function needing state."""
+    confidence = abs(probability_up - decision_threshold) / max(1.0 - decision_threshold, decision_threshold)
+    confidence = max(0.0, min(confidence, 1.0))
+
+    def _record():
+        if record_observation is not None and symbol_key is not None:
+            record_observation(symbol_key, probability_up)
+
+    if probability_up >= buy_threshold:
+        target_weight = min(max_position_weight, 0.10 + 0.15 * confidence)
+        _record()
+        return "buy", confidence, target_weight
+
+    if probability_up <= effective_sell_threshold:
+        target_weight = -min(max_position_weight, 0.10 + 0.15 * confidence)
+        _record()
+        return "sell", confidence, target_weight
+
+    _record()
+    return "hold", confidence, 0.0