aether-quant 0.0.1__tar.gz

aether_quant-0.0.1/.devcontainer/README.md

@@ -0,0 +1,12 @@
+# .devcontainer
+
+GitHub Codespaces / VS Code Dev Container definition for Aether Quant
+(`devcontainer.json`), plus a `dind-v1-test/` variant used to test
+Docker-in-Docker setups.
+
+The container is the `mcr.microsoft.com/devcontainers/python:3.11` image with
+an sshd feature (Codespaces training access) and a post-create command that
+installs the CPU PyTorch build plus both requirements files. This is the
+environment behind this project's own "train in the cloud" convention — see
+[`RUNBOOK.md`](../RUNBOOK.md) and
+[`development/infrastructure.md`](../development/infrastructure.md).

aether_quant-0.0.1/.devcontainer/devcontainer.json

@@ -0,0 +1,14 @@
+{
+    "name": "Aether Quant",
+    "image": "mcr.microsoft.com/devcontainers/python:3.11",
+    "features": {
+        "ghcr.io/devcontainers/features/sshd:1": {
+            "version": "latest"
+        }
+    },
+    "hostRequirements": {
+        "cpus": 2,
+        "memory": "8gb"
+    },
+    "postCreateCommand": "pip install torch --index-url https://download.pytorch.org/whl/cpu && pip install -r requirements/requirements.txt && pip install -r requirements/requirements-dev.txt"
+}

aether_quant-0.0.1/.devcontainer/dind-v1-test/devcontainer.json

@@ -0,0 +1,14 @@
+{
+    "name": "Aether Quant DinD v1 Test",
+    "image": "mcr.microsoft.com/devcontainers/python:3.11",
+    "features": {
+        "ghcr.io/devcontainers/features/sshd:1": {
+            "version": "latest"
+        },
+        "ghcr.io/devcontainers/features/docker-in-docker:1": {}
+    },
+    "hostRequirements": {
+        "cpus": 2,
+        "memory": "8gb"
+    }
+}

aether_quant-0.0.1/.dockerignore

@@ -0,0 +1,51 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+node_modules/
+webui/node_modules/
+webui/dist/
+backtests/
+.lean/
+.git/
+.claude/
+Aether-quant-Obsidian-Vault/
+# Large data directories not needed by the FastAPI server
+data/
+ml/
+storage/
+
+# Local secrets and broker/API credentials - mirrors .gitignore's own list.
+# Being .gitignore'd does NOT keep a file out of the image: the engine build
+# does `COPY . .`, and that same image is published to ghcr (single fat
+# target, no slim variant), so anything not excluded here is baked into a
+# public registry layer - recoverable via `docker history`/`docker save` even
+# if a later commit removes it. lean.live.json is the rendered, secret-bearing
+# config `aq render-lean-config` produces (execution/lean_config_render.py);
+# lean.json itself is git-tracked with empty placeholders but is excluded too,
+# so a locally-populated copy can never leak. Keep this list in sync with
+# .gitignore's "Local secrets" block.
+.env
+.env.*
+!.env.compose.example
+!.env.live.example
+ib_config.py
+*_config.local.py
+config.local.json
+lean.local.json
+lean.live.json
+lean.json
+*.key
+*.pem
+
+# cpp_inference_ext/'s compiled build artifacts - mirrors .gitignore's own
+# exclusion list. Docker now builds this extension fresh for the
+# container's own Python 3.11 (see Dockerfile) - a locally-pre-built
+# stray .pyd/.so from a developer's own (ABI-incompatible) host Python
+# must never leak into the build context and get baked into the image,
+# which is published to a public ghcr registry.
+cpp_inference_ext/build/
+cpp_inference_ext/*.egg-info/
+cpp_inference_ext/*.pyd
+cpp_inference_ext/*.so
+cpp_inference_ext/install_log*.txt

aether_quant-0.0.1/.env.compose.example

@@ -0,0 +1,12 @@
+# Copy this file to .env (untracked, .gitignore'd) and fill in real values.
+# docker-compose.yml reads .env automatically for ${VAR} substitutions.
+
+# PostgreSQL (defaults already work for local dev — override for anything else)
+POSTGRES_DB=aether_quant
+POSTGRES_USER=aether
+POSTGRES_PASSWORD=aether_dev_password
+
+# Telegram alerts (V2-19) — required for notifications.telegram_worker to
+# actually send messages; leave blank to run the worker as a safe no-op.
+AETHER_TELEGRAM_BOT_TOKEN=
+AETHER_TELEGRAM_CHAT_ID=

aether_quant-0.0.1/.env.live.example

@@ -0,0 +1,33 @@
+# Copy this file to .env.live (untracked, .gitignore'd) and fill in real
+# values before switching phase_v2.runtime.mode to "live" (V2-22). Never
+# commit .env.live.
+#
+# Two consumers read these AETHER_* vars:
+#  1. execution/live_credentials_io.py - a pre-flight credential-presence check.
+#  2. scripts/render_lean_credentials.py (`aq render-lean-config`) - renders a
+#     gitignored lean.live.json with these values overlaid onto the empty,
+#     tracked lean.json template, which live/paper deployment then uses via
+#     `--lean-config lean.live.json`. Lean does NOT expand env vars out of
+#     lean.json itself, which is why this render step exists (the tracked
+#     lean.json stays all-empty so it is safe to share; see
+#     development/infrastructure.md's "Live Deployment Betreiben (V2-22)"
+#     runbook and execution/lean_config_render.py).
+
+# --- Interactive Brokers live credentials ---
+AETHER_IB_ACCOUNT=
+AETHER_IB_USER_NAME=
+AETHER_IB_PASSWORD=
+AETHER_IB_TRADING_MODE=paper
+
+# --- Live market-data provider keys (only the one you actually use) ---
+# Populate whichever feed lean.json's live-paper/live environment is configured
+# for; leave the rest blank. These render into lean.json's matching fields.
+AETHER_POLYGON_API_KEY=
+AETHER_IEX_CLOUD_API_KEY=
+
+# --- Database password for live deployments ---
+# The default 'aether_dev_password' is fine for local dev but is published in
+# the repo. Live mode refuses to start while the Postgres DSN still uses that
+# default (execution/live_credentials.py::postgres_dsn_is_live_safe). Set a real
+# one here (and in .env / .env.compose) before going live.
+POSTGRES_PASSWORD=

aether_quant-0.0.1/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

aether_quant-0.0.1/.githooks/README.md

@@ -0,0 +1,14 @@
+# .githooks
+
+Optional git hooks, opt-in per clone (never auto-installed on a fresh
+checkout):
+
+```powershell
+git config core.hooksPath .githooks
+```
+
+Currently one hook: `pre-commit`, which invokes `aq secrets-check`
+(`execution/secret_scan.py`) and blocks the commit if a populated secret
+field is about to land in the tracked `lean.json` or a real `.env` file is
+tracked by git. This is what actually stops a secret from being committed —
+see [`SECURITY.md`](../SECURITY.md) for the reporting policy.

aether_quant-0.0.1/.githooks/pre-commit

@@ -0,0 +1,29 @@
+#!/bin/sh
+# Aether Quant pre-commit secret guard (Phase V2-22 security).
+#
+# Blocks a commit that would publish a secret: a populated secret field in the
+# tracked lean.json, or a tracked real `.env` file. All detection lives in
+# `aq secrets-check` (execution/secret_scan.py) - this hook just invokes it.
+#
+# Enable once per clone (opt-in, so it never surprises a fresh checkout):
+#     git config core.hooksPath .githooks
+#
+# Runs under git's POSIX sh (git-bash on Windows), so keep it portable.
+
+set -e
+
+repo_root=$(git rev-parse --show-toplevel)
+cd "$repo_root"
+
+# Prefer the installed `aq` console script; fall back to running the module
+# directly with whichever Python is on PATH (venv-activated shells get theirs).
+if command -v aq >/dev/null 2>&1; then
+    aq secrets-check
+elif command -v python >/dev/null 2>&1; then
+    python aq_cli.py secrets-check
+elif command -v python3 >/dev/null 2>&1; then
+    python3 aq_cli.py secrets-check
+else
+    echo "pre-commit: could not find 'aq' or 'python' to run secrets-check" >&2
+    exit 1
+fi

aether_quant-0.0.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,50 @@
+---
+name: Bug report
+about: Something is broken, wrong, or behaves differently than documented.
+title: "[bug] "
+labels: ["bug"]
+---
+
+## What happened
+
+<!-- One or two sentences. Lead with the observable failure. -->
+
+## Where
+
+<!-- File(s)/module(s)/CLI command(s) involved, e.g. `aq evaluate --rank-book`, portfolio/book_construction.py -->
+
+## Expected vs actual
+
+- **Expected:**
+- **Actual:**
+
+## Reproduction
+
+<!--
+  Minimal steps from a clean clone. Include the exact command(s) and any
+  config.json keys involved (`aq config get <dotted.key>` output helps).
+-->
+
+```text
+<commands / steps>
+```
+
+## Evidence
+
+<!-- Test output, log excerpt, or backtest artifact reference. Paste the
+smallest relevant slice; link large files instead of pasting them. -->
+
+```text
+<output>
+```
+
+## Environment
+
+- OS:
+- Python version:
+- Commit / tag:
+
+## Checklist
+
+- [ ] I ran `aq test` and can name the failing/passing state
+- [ ] I checked `development/Problems.md` for a known entry covering this

aether_quant-0.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question / usage help
+    url: https://github.com/leon1706-lol/Aether-quant/discussions
+    about: Ask here before opening an issue — most setup questions are answered in README.md, development/infrastructure.md, or CONTRIBUTING.md.
+  - name: Security vulnerability
+    url: https://github.com/leon1706-lol/Aether-quant/security/advisories/new
+    about: Report privately via GitHub Security Advisories — do NOT open a public issue (see SECURITY.md).

aether_quant-0.0.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,32 @@
+---
+name: Feature request
+about: A new subsystem, module, CLI capability, or behavioral improvement.
+title: "[feature] "
+labels: ["enhancement"]
+---
+
+## Problem to solve
+
+<!-- What can't you do today? Describe the user-facing need, not the implementation. -->
+
+## Proposed behavior
+
+<!-- What should exist after this ships? Include the intended CLI/config surface if any:
+     new `aq` command/flag? new `phase_v2.*` config block (remember: flags ship `false`
+     until verified)? new output artifact? -->
+
+## Scope guardrails
+
+<!-- This repo's conventions shape every feature. Confirm how yours fits: -->
+
+- [ ] Ships backward-compatible: additive `None`-default parameters / default-off config keys; an unmodified `config.json` reproduces today's behavior exactly.
+- [ ] Testable without Lean: pure logic lives in a package module, not `main.py`; tests planned/attached.
+- [ ] Docs plan: README/sub-readmes + `development/Changelog.md` entry (and `development/architecture.md` when it changes system structure).
+
+## Alternatives considered
+
+<!-- What did you rule out and why? -->
+
+## Extra context
+
+<!-- Related Problems.md entries (#N), prior Changelog rounds, or backtest evidence. -->

aether_quant-0.0.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+<!-- Title style: `V<version> <short what-and-why>` for release-bound PRs,
+     matching the repo's commit history; otherwise a plain descriptive title. -->
+
+## What & why
+
+<!-- One paragraph: what changed and the problem/round it belongs to.
+     Reference development/Problems.md entries (#N) where applicable. -->
+
+## Changes
+
+-
+-
+
+## Behavior contract
+
+<!-- This repo's hard rule: prove what changed and for whom. -->
+
+- [ ] Default behavior is byte-identical when new flags/params are absent (`None`-default / default-off convention), **or** the behavior change is intentional and listed below:
+  - <!-- intentional changes here -->
+- New config keys: <!-- `phase_v2.*` keys + defaults, or "none" -->
+
+## Verification
+
+<!-- How was this confirmed? The suite must be green before review. -->
+
+- [ ] `aq test` green (N passed): <!-- paste count -->
+- New tests: <!-- files + what they pin down -->
+- Manual checks: <!-- CLI dry-runs, real-data spot checks -->
+- Real Lean backtest: <!-- not run in PRs by convention; note if one is required before merge -->
+
+## Docs updated
+
+- [ ] README / sub-package README
+- [ ] `development/Changelog.md` (append-only entry)
+- [ ] `development/Problems.md` (if a bug was found/fixed)
+- [ ] `development/architecture.md` / `development/infrastructure.md` (if structure/services changed)
+- [ ] Obsidian vault regenerated (`generate_code_graph.py` → `regenerate_vault.py --append-handoff`)

aether_quant-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,158 @@
+name: CI
+
+# V5.3.9 - deep CI suite: windows+ubuntu pytest matrix with a calibrated
+# coverage fail-under gate (82% measured - 2), ruff lint, the full webui
+# vitest suite, an offline CLI smoke battery, and workflow self-validation.
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# V5.4.2 - cancel superseded runs on rapid-fire pushes (ported from Aether-Vault)
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python-tests:
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Syntax-check main.py (no Lean runtime available in CI - see development/Problems.md #69)
+        run: python -m py_compile main.py
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements/requirements.txt -r requirements/requirements-dev.txt
+          pip install pytest-cov
+
+      - name: Run full test suite with coverage gate
+        run: >
+          pytest -m "not lean_backtest" -ra
+          --cov --cov-report=term-missing --cov-report=xml
+          --cov-fail-under=80
+
+      - name: Upload coverage artifact
+        if: matrix.os == 'ubuntu-latest'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+
+  python-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      # V5.3.11 FIX: bare `ruff check .` — NOT `aq test --ruff` (which
+      # requires importing aq_cli → pandas via the full package chain, but
+      # this job intentionally has a minimal environment). Local devs use
+      # `aq test --ruff`; CI uses bare ruff for speed.
+      # V5.4.7: ruff is PINNED - the previous unbounded range let new ruff
+      # releases add rules and break CI independently of any repo change.
+      - name: Install ruff
+        run: pip install "ruff==0.16.4"
+
+      - name: Ruff check (E/F ruleset calibrated in pyproject.toml)
+        run: ruff check .
+
+      - name: Syntax-check main.py
+        run: python -m py_compile main.py
+
+  dependency-audit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install pip-audit
+        run: pip install pip-audit
+
+      - name: Audit runtime dependencies for known CVEs
+        run: |
+          pip install -r requirements/requirements.txt
+          pip-audit --requirement requirements/requirements.txt --desc
+
+      - name: Audit dev dependencies for known CVEs
+        run: |
+          pip-audit --requirement requirements/requirements-dev.txt --desc
+
+  webui-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    defaults:
+      run:
+        working-directory: webui
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: webui/package-lock.json
+
+      - run: npm ci
+      - run: npx tsc -b
+      - run: npx oxlint
+      # V5.3.9 - the full frontend suite finally runs in CI too.
+      - run: npx vitest run --pool=threads
+      - run: npm run build
+
+  cli-smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package editable
+        run: |
+          pip install -r requirements/requirements.txt
+          pip install -e .
+
+      - name: CLI smoke battery (offline, deterministic)
+        run: |
+          aq --help > /dev/null
+          aq evaluate --help > /dev/null
+          aq config get phase1.universe.name
+          aq secrets-check
+
+  workflows-lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+
+      # V5.3.10 - single-step pinned install + validate: the previous two-step
+      # pattern (PATH append, then bare `actionlint`) failed with
+      # "command not found" on the runner. Pinned to v1.7.7 for
+      # reproducibility (meta-tested in tests/test_ci_workflows.py).
+      - name: Validate workflow files (actionlint v1.7.7)
+        run: |
+          curl -sSL -o actionlint.tar.gz \
+            https://github.com/rhysd/actionlint/releases/download/v1.7.7/actionlint_1.7.7_linux_amd64.tar.gz
+          tar -xzf actionlint.tar.gz actionlint
+          ./actionlint -no-color -verbose

aether_quant-0.0.1/.github/workflows/release.yml

@@ -0,0 +1,130 @@
+name: Release
+
+# Releasing is a manual, deliberate act: tag a commit on main and push the
+# tag. Nothing else triggers this workflow - matches this project's existing
+# bias toward no uncontrolled automatic actions (see e.g. retraining's
+# manual promote/rollback).
+on:
+  push:
+    tags: ["v*.*.*"]
+
+jobs:
+  # V5.3.9 - NON-BLOCKING visibility job: runs the full offline suite on the
+  # tagged commit so release-time gaps are visible right next to the
+  # artifacts. Deliberately NOT wired into `needs:` of the publish jobs
+  # (user decision): releases proceed regardless; read this job's result to
+  # see where the gaps are.
+  tag-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements/requirements.txt -r requirements/requirements-dev.txt
+
+      - name: Run full offline suite (visibility only - does not gate the release)
+        run: pytest -m "not lean_backtest" -ra
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    environment: pypi # must match the Environment name configured in PyPI's Trusted Publisher setup
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC) - no PyPI token is ever
+      # stored as a secret. Requires a one-time Trusted Publisher setup on
+      # the PyPI project page (repo + this workflow filename).
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # full history/tags - required for setuptools-scm
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-docker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    env:
+      # Hardcoded lowercase, not derived from ${{ github.repository }}:
+      # the repo is leon1706-lol/Aether-quant (capital A), but Docker image
+      # references must be all-lowercase - using github.repository directly
+      # would fail with "invalid reference format".
+      IMAGE_NAME: ghcr.io/leon1706-lol/aether-quant
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=raw,value=latest
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          # GitHub Actions cache backend - without this, every release
+          # build started cold (no layer reuse across releases) even
+          # though the Dockerfile itself is already correctly ordered
+          # (deps installed before source COPY, see development/Problems.md).
+          # mode=max caches every intermediate layer, not just the final
+          # image, so the npm ci/pip install layers survive between runs.
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+  # Creates the GitHub Release itself, once per tag. Notes are auto-generated
+  # (commit list since the previous tag); the body additionally points at the
+  # matching development/Changelog.md entry, which is this repo's canonical
+  # per-version record (see CONTRIBUTING.md's versioning section).
+  github-release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Create GitHub Release with changelog link
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          VERSION="${TAG#v}"
+          BODY=$(cat <<EOF
+          See [development/Changelog.md](https://github.com/${GITHUB_REPOSITORY}/blob/main/development/Changelog.md) for the full entry for \`V${VERSION}\` and every prior release. This repo keeps its changelog as an append-only historical record; each tagged version corresponds to a \`## V<version>\` section there.
+
+          ---
+          EOF
+          )
+          gh release create "$TAG" \
+            --title "Aether Quant ${TAG}" \
+            --notes "$BODY" \
+            --generate-notes