alphaengine 1.0.2__tar.gz → 1.0.3__tar.gz

alphaengine-1.0.3/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Report a reproducible bug in AlphaEngine
+title: "[Bug]: "
+labels: ["bug"]
+assignees: []
+---
+
+## Summary
+
+A clear and concise description of what went wrong.
+
+## Reproduction
+
+Minimal Python snippet or CLI command that reproduces the issue (using synthetic data or `alphaengine demo`):
+
+```python
+import alphaengine
+# ...
+```
+
+## Expected vs. actual behavior
+
+- **Expected:**
+- **Actual:**
+
+## Environment
+
+- `alphaengine` version (`alphaengine version`):
+- Python version:
+- OS:
+- `numpy` / `scipy` versions:

alphaengine-1.0.3/.github/ISSUE_TEMPLATE/data_shape.md

@@ -0,0 +1,24 @@
+---
+name: Data shape / loader issue
+about: Report a CSV, Parquet, or interop data-shape edge case
+title: "[Data shape]: "
+labels: ["data-shape"]
+assignees: []
+---
+
+## Data source / format
+
+Which loader or flag was used (`--data`, `load_panel`, `alphaengine.io.from_quantconnect`, `alphaengine.io.from_vectorbt`, etc.)?
+
+## Anonymized header and sample rows
+
+Please paste 3–5 anonymized rows showing the header and column types (never paste proprietary price history):
+
+```csv
+date,symbol,close
+2026-01-02,AAA,100.00
+```
+
+## Current behavior / error message
+
+Paste the `DataShapeError` or unexpected behavior observed:

alphaengine-1.0.3/.github/ISSUE_TEMPLATE/method_request.md

@@ -0,0 +1,29 @@
+---
+name: Method request
+about: Propose a published quantitative or statistical method for alphaengine.core
+title: "[Method]: "
+labels: ["enhancement", "methods"]
+assignees: []
+---
+
+## Published reference
+
+Everything in `alphaengine.core` comes from peer-reviewed literature. Please cite the paper or textbook:
+
+- **Citation (authors, year, title, venue):**
+- **DOI / URL:**
+
+## What question does it answer?
+
+Describe the statistical or risk question this primitive answers and how it fits into the validation/research loop.
+
+## Proposed signature and inputs/outputs
+
+```python
+def proposed_method(returns, ...):
+    ...
+```
+
+## Dependencies
+
+Does this method run on `numpy` + `scipy` alone, or does it require an optional extra (e.g. `statsmodels`)?

alphaengine-1.0.3/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

alphaengine-1.0.3/.github/workflows/codeql.yml

@@ -0,0 +1,29 @@
+name: codeql
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "20 6 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (python)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: python
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3

{alphaengine-1.0.2 → alphaengine-1.0.3}/.github/workflows/publish.yml

@@ -33,6 +33,9 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
+      - name: Verify git tag matches __version__
+        run: |
+          python -c "import os, runpy, sys; v = runpy.run_path('src/alphaengine/_version.py')['__version__']; ref = os.environ.get('GITHUB_REF_NAME') or os.environ.get('GITHUB_REF', '').removeprefix('refs/tags/'); exp = f'v{v}'; sys.exit(f'Tag {ref!r} != {exp!r}' if ref != exp else 0)"
       - run: python -m pip install --upgrade build
       - run: python -m build
       - uses: actions/upload-artifact@v4

alphaengine-1.0.3/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to `alphaengine` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to Semantic Versioning (with computed golden values
+treated as part of the public contract).
+
+## [1.0.3] - 2026-10-24
+
+### Added
+- **Sealed studies (Schema 1.2):** Canonical-JSON SHA-256 content hash (`content_sha256` with sorted keys and fixed 8-decimal float formatting), full 64-hex `data_hash`, and optional per-trial ledger export (`SweepResult.ledger()`, `include_ledger=True`).
+- **CLI study verbs:** `alphaengine seal <study.json>` (writes `content_sha256` and verifies on re-run) and `alphaengine report <study.json> [--retail]` (reports to `/api/me/runs/ingest` by default or `/api/retail/ledger/import` with `--retail`).
+- **Complete study ingest payload:** `study/report.py` `_payload()` now includes `selection` (PBO), `psr_vs_zero`, `sr0_expected_max`, `min_track_record_length`, `grid_keys`, `n_failed_trials`, `content_sha256`, and optional `assignment_id` and `thesis_id`.
+- **Interop loaders (`alphaengine.io`):** `from_quantconnect(path)` and `from_vectorbt(portfolio_or_csv)` construct a `Study` with returns, performance metrics, data hash, and trial-count provenance (`"asserted"` when provided/present, `"not_recorded"` with verdict refusal when absent).
+- **Credentials purge:** `alphaengine logout --purge` removes `~/.config/alphaengine/credentials.json`, cleans up its config directory, and clears managed keys from the current process.
+- **API URL override:** `ALPHAENGINE_API_URL` environment variable and unified `DEFAULT_API_URL` constant across CLI and study reporting.
+- **Security & governance:** Weekly Dependabot configuration (pip + GitHub Actions), Python CodeQL workflow, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and GitHub issue templates.
+
+### Changed
+- **Opt-in series sharing on `/traces`:** `_report_trace` sends scalar figures only by default. Uploading full series to `/api/harness/runs/{id}/traces` requires `--share-series` or `ALPHAENGINE_SHARE_SERIES=1`; any payload sent without opt-in is guarded at most 512 elements.
+- **Deliberate math & golden updates:**
+  - `deflated_sharpe(..., n_trials=1)` no longer silently deflates as `N=2`. At `n_trials=1`, `sr0_expected_max` is `0.0` (was `0.037` on the `rets(9, 200)` golden) and `deflated_sharpe` equals `psr_vs_zero` (`0.8434`, was `0.6875` on the golden), with an explicit note that no multiple-testing deflation applies.
+  - `SweepResult.verdict()` passes the cross-trial Sharpe dispersion across valid grid trials into `deflated_sharpe` per Bailey & López de Prado (2014), falling back to single-series sampling error only when fewer than 2 valid trials exist.
+  - Renamed `cpcv_score` to `combinatorial_oos_stability` (keeping `cpcv_score` as a deprecated alias) to accurately describe single-stream purged/embargoed sub-sample stability.
+  - `pbo_cscv` validates `n_splits` (even integer $\ge 2$) and raises a clear `ValueError`.
+- **Neutral framing:** Added *"Research tool, not investment advice"* disclaimer to README, `--help`, and the boot screen; renamed user-facing bakeoff `survivor` / `survivor_weights` to `top_ranked_config` / `model_weights` while preserving backward-compatible dictionary keys.
+- **Release guard:** `.github/workflows/publish.yml` verifies that the git tag matches `v{__version__}` before building.
+
+## [1.0.2] - 2026-10-20
+
+### Added
+- **Four-pass adversarial GAN bakeoff:** `run_bakeoff` and `core.bakeoff.referee` run four passes (eight candidate proposals across `equal`, `hrp`, `risk_parity`, `inverse_vol`, `var_sorted`, `low_vol`, `momentum`, and `reversion` against eight regime, tail, rate, and crash-cluster attacks) under a hard 12-call, 60-second ceiling.
+- **Multi-pass bakeoff scorecard in PDF reports:** Cumulative wealth across passes, in-sample vs. post-attack Sharpe comparison, and candidate scorecard table.
+
+## [1.0.1] - 2026-10-19
+
+### Added
+- **Harness simulation tools:** Added `monte_carlo` and `scenarios` to the local session tool stack.
+- **Multi-page PDF & text reports:** Accepted session traces render multi-panel portfolio, scenario stress, Monte Carlo fan, and bakeoff reports to the user's `Downloads` folder.
+
+### Fixed
+- **Ledoit-Wolf sample-count divisor:** Fixed sample covariance scaling in `ledoit_wolf_cov` so `hrp_weights` and `risk_parity_weights` differentiate weights across wide panels.
+
+## [1.0.0] - 2026-10-18
+
+### Added
+- **Interactive terminal simulator (`alphaengine`):** Full-screen Textual session where plain-English questions execute as a deterministic stack of local tool calls (`profile`, `align`, `regime`, `price`, `reprice`, `correlation`, `covariance`, `cointegration`, `portfolio`, `overlap`, `performance`, `var`, `process`, `workflow`, `bakeoff`) with citation guarding.
+- **Pinned cash rate & statistical refinements:** Default risk-free rate pinned to the H.15 3-month Treasury constant maturity (`4.21%` as of `2026-10-06`, `DGS3MO`; pass `0` for excess of zero), automatic Newey-West HAC lag selection in factor regressions, and Benjamini-Hochberg FDR survivors in cointegration screening.

alphaengine-1.0.3/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers at **wfe818@gmail.com**. All complaints will
+be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.

alphaengine-1.0.3/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to AlphaEngine
+
+Thank you for your interest in contributing to AlphaEngine.
+
+## Core design constraints
+
+Before opening a pull request, please keep these architectural rules in mind:
+
+1. **Two runtime dependencies (`numpy` and `scipy`).** Optional extras (`factors`, `agents`, `connectors`, `tui`) are lazy-imported so `import alphaengine` never requires network clients, LLM SDKs, or UI frameworks.
+2. **Goldens are a public contract.** Computed values in `tests/test_goldens.py` are pinned so saved studies remain reproducible. Never modify a golden value simply to make a test pass; deliberate mathematical corrections require a version bump and a `CHANGELOG.md` entry explaining what changed and why.
+3. **Data boundary.** Computation runs locally. Without explicit opt-in (`--share-series` or `ALPHAENGINE_SHARE_SERIES=1`), no list longer than 512 elements may leave the machine.
+4. **Trial-count honesty.** Trial counts must be derived from the executed grid (`derived_from_grid`), explicitly marked (`asserted`), or `not_recorded` (which refuses an `edge` verdict).
+
+## Local development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows PowerShell: .\.venv\Scripts\Activate.ps1
+pip install -e ".[dev,factors]"
+```
+
+## Required checks before submitting
+
+Run all five CI gates locally before pushing:
+
+```bash
+python -m ruff check src tests
+python -m ruff format --check src tests
+python -m mypy src
+python -m pytest
+python -m pytest tests -m golden -q
+python scripts/gen_docs.py --check
+```
+
+If you add or modify CLI commands or flags in `src/alphaengine/commands.py`, regenerate the README command table with:
+
+```bash
+python scripts/gen_docs.py --write
+```

{alphaengine-1.0.2 → alphaengine-1.0.3}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 1.0.2
+Version: 1.0.3
 Summary: Validated research tooling for investment strategies: deflation, overfitting detection, and honest trial counts.
-Project-URL: Homepage, https://github.com/quantOSC/alphaengine
+Project-URL: Homepage, https://qosai.app
 Project-URL: Documentation, https://github.com/quantOSC/alphaengine#readme
 Project-URL: Source, https://github.com/quantOSC/alphaengine
 Project-URL: Issues, https://github.com/quantOSC/alphaengine/issues
@@ -53,8 +53,10 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <strong>The research loop, on your machine.</strong><br>
-  Ask what is worth looking at, whether it holds up, how much to hold,<br>
-  and whether anything has crossed a line. Your data never leaves.
+  Ask what is worth looking at, whether it holds up, what sizing the risk model implies,<br>
+  and whether anything has crossed a line.<br>
+  Computation runs locally; when you are signed in to quantOS, summary figures are reported to your account; full series are shared only if you opt in.<br>
+  <em>Research tool, not investment advice.</em>
 </p>
 
 <p align="center">
@@ -84,7 +86,7 @@ python -m alphaengine
 ┌──────────┬─────────────────────────────────────┬──────────────────┐
 │ ● maths  │  Ask in plain English.              │  sharpe          │
 │   always │                                     │  mean / std √252 │
-│ ○ flows  │  > which names are overbought?      │  ▁▂▃▅▇█▇▅▃       │
+│ ○ flows  │  > which names rank highest on RSI? │  ▁▂▃▅▇█▇▅▃       │
 │ ○ ask    │                                     │  0    0.0012     │
 │          │  chose screen_universe              │  1   -0.0040     │
 │ loaded   │                                     │                  │
@@ -103,8 +105,19 @@ alphaengine
 > screen
 ```
 
-Prices stay on this machine. A math line's series can travel on its own trace
-so it can be charted. The figures posted with the step stay summaries.
+Computation runs locally on this machine. When you are signed in to quantOS,
+summary figures are reported to your account; full series are shared on
+`/traces` only if you opt in (`--share-series` or `ALPHAENGINE_SHARE_SERIES=1`).
+
+---
+
+## Where this sits
+
+AlphaEngine computes locally on your machine against your own data.
+[quantOS](https://qosai.app) is the hosted research workspace that keeps the
+record and writes committee reports. Everything in AlphaEngine's math and sweep
+layer runs offline with no account; signing in connects local runs and sealed
+studies to your quantOS workspace.
 
 ---
 
@@ -121,7 +134,7 @@ IS the question; only two of them need code of yours.
 | Is this real, once you count the tries? | `validate` | `validate_study` | prices + your backtest |
 | Where does it break? | `stress` | `stress_study` | a return series |
 | Is it new, or my book again? | `overlap` | `check_overlap` | the candidate + the book |
-| How much should I hold? | `size` | `size_position` | a return series |
+| What sizing does the risk model imply? | `size` | `size_position` | a return series |
 | Still inside the lines? | `monitor` | `monitor_sleeve` | a return series |
 
 ```bash
@@ -141,7 +154,7 @@ Or say it in plain English and let your own model pick:
 
 ```bash
 alphaengine
-❯ which of my names are overbought on RSI?
+❯ which of my names rank highest on RSI?
 ```
 
 That second path is EXPLORATORY: the model chooses a workflow and then chooses
@@ -157,12 +170,28 @@ Each is useful without the one above it. `login` lights the next one.
 
 | Rung | What you need | What you get |
 |---|---|---|
-| **The maths** | nothing | Every statistic, offline, forever. No account. |
-| **Workflows** | a QuantOS `ae_live_` key (`login`) | The loop end to end, with the record. |
+| **The maths** | nothing | `alphaengine demo`, `alphaengine process`, and the full Python API (`import alphaengine`, `sweep`, `core`), offline, forever. No account. |
+| **Workflows** | a portal-issued `ae_live_` key (`login` or `QUANTOS_API_KEY`; request access at [https://qosai.app/access](https://qosai.app/access)) | The eight workflow commands (`diagnose`, `screen`, `signal`, `validate`, `stress`, `overlap`, `size`, `monitor`) plus `workflows`, `runs`, `gaps`, `tonight`, and `run <workflow>`. |
 | **Ask anything** | your OWN model key (`login anthropic`) | Plain English in. Runs under your account, not ours. |
 
-Nothing here stores a model key: it is read from your environment at call time
-and handed to the provider's own client. There is no field to put one in.
+The eight workflow commands (`diagnose`, `screen`, `signal`, `validate`,
+`stress`, `overlap`, `size`, `monitor`) and `workflows` / `runs` require a
+portal-issued `ae_live_` key because the workflow graph and account record live
+on the server (request access at [https://qosai.app/access](https://qosai.app/access)).
+`alphaengine demo`, `alphaengine process`, and the Python library (`import alphaengine`)
+work completely offline without an account or key.
+
+**How credentials are handled.** QuantOS never receives your LLM provider key:
+it goes directly from this process to your chosen provider. By default, keys can
+be supplied via environment variables (`QUANTOS_API_KEY`, `ANTHROPIC_API_KEY`,
+`OPENAI_API_KEY`, etc.), which touches nothing on disk. If you run `login` and
+say **yes** to *"Stay signed in on this machine?"*, `auth.py` writes an optional
+`~/.config/alphaengine/credentials.json` (`0600` permissions;
+`%APPDATA%\alphaengine\credentials.json` on Windows) so you do not have to
+re-paste in every terminal. Environment variables always win over that file.
+To avoid disk storage entirely, set environment variables only (or answer `n`
+at `login`). To delete the stored file at any time, run
+`alphaengine logout --purge` (or `alphaengine logout`).
 
 ```mermaid
 flowchart LR
@@ -220,6 +249,15 @@ distinction is the whole of the data boundary below.
 
 ---
 
+## What's new in 1.0.3
+
+- **Opt-in series sharing & 512-element wire guard:** By default, workflow step traces (`/api/harness/runs/{id}/traces`) report scalar figures only; full series are shared only when you pass `--share-series` or set `ALPHAENGINE_SHARE_SERIES=1`.
+- **Sealed studies (schema 1.2) & CLI reporting:** Studies now carry a canonical-JSON SHA-256 seal (`content_sha256`), a full 64-hex `data_hash`, and an optional per-trial ledger (`include_ledger=True`). Use `alphaengine seal <study.json>` to seal or verify a study file, and `alphaengine report <study.json> [--retail]` to ingest into quantOS or the retail experiment ledger.
+- **Math fixes:** `SweepResult.verdict()` passes cross-trial Sharpe dispersion into `deflated_sharpe` per Bailey & López de Prado (2014); `deflated_sharpe(n_trials=1)` returns `psr_vs_zero` with `sr0_expected_max = 0.0` instead of deflating as `N=2`; `combinatorial_oos_stability` replaces `cpcv_score` (kept as a deprecated alias); and `pbo_cscv` validates that `n_splits` is an even integer $\ge 2$.
+- **Interop loaders (`alphaengine.io`):** `from_quantconnect(path)` and `from_vectorbt(portfolio_or_csv)` build a `Study` with returns and preserve trial-count provenance (`"asserted"` vs. `"not_recorded"`).
+
+See [CHANGELOG.md](CHANGELOG.md) for 1.0.0–1.0.3 release notes.
+
 ## What's new in 0.9.0
 
 `next_open` fills wait for a prior close. The first bar of a next-open backtest
@@ -227,9 +265,10 @@ no longer trades that bar's own signal at that bar's open. Close fills are
 unchanged, and the published goldens do not move.
 
 The session is the full-screen terminal (`pip install "alphaengine[tui]"`).
-Each statistic keeps its formula, inputs, and series. Those series post to
-`/api/harness/runs/{id}/traces`. A portal that rejects the trace does not fail
-the run.
+Each statistic keeps its formula, inputs, and series locally. By default,
+`/api/harness/runs/{id}/traces` receives scalar figures only; full series are
+uploaded only when you opt in (`--share-series` or `ALPHAENGINE_SHARE_SERIES=1`).
+A portal that rejects the trace does not fail the run.
 
 ## What's new in 0.8.0
 
@@ -246,8 +285,8 @@ are a public contract from this release. The study schema is **1.1**: optional
 | Figures that already travel | `{kind, key, title}` hints a portal maps to a chart | `charts`, [figure contract](docs/figure_contract.md) |
 
 The terminal boot is the README banner: tracked `ALPHAENGINE`, the subtitle,
-a teal-left / amber-right mesh (plateau, valley, knife-edge ridge), and
-`your data never leaves.` `alphaengine process` fits a DGP offline, no account.
+a teal-left / amber-right mesh (plateau, valley, knife-edge ridge), and the
+local-computation notice. `alphaengine process` fits a DGP offline, no account.
 
 ```python
 from alphaengine.core import ou_calibrate, garch_calibrate, dgp_stress, grinold_alpha
@@ -323,9 +362,11 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `validate` | is this real? | shell + session |
 | `stress` | where does it break? | shell + session |
 | `overlap` | is it new, or my book again? | shell + session |
-| `size` | how much? | shell + session |
+| `size` | what sizing does the risk model imply? | shell + session |
 | `monitor` | still inside the lines? | shell + session |
 | `run <workflow>` | run one workflow exactly as written | shell + session |
+| `seal <study.json>` | write canonical content_sha256 into a study and verify on re-run | shell |
+| `report <study.json> [--retail]` | send a saved study to quantOS (/api/me/runs/ingest or --retail ledger) | shell |
 | `<anything else>` | ask in plain English; your model picks a workflow and drives it | session |
 | `status` | the current run, and what is loaded | session |
 
@@ -348,7 +389,7 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 
 | Command | Does | Where |
 |---|---|---|
-| `logout` | remove stored credentials from this machine | shell + session |
+| `logout [--purge]` | remove stored credentials from this machine | shell + session |
 | `version` | print the version | shell |
 | `help` | the short list: demo, login, load, then a question | session |
 | `quit` | leave the session | session |
@@ -376,8 +417,11 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `--input K=V` | a workflow input; repeatable |
 | `--quiet` | only the result, no step narration |
 | `--stream` | print the answer once the citation guard has passed |
+| `--share-series` | opt in to uploading full series on run traces (default off; or $ALPHAENGINE_SHARE_SERIES=1) |
 | `--limit N` | how many rows to show (default 25) |
 | `--budget N` | how many runs a night is worth (default 3) |
+| `--purge` | remove ~/.config/alphaengine/credentials.json and clean up its config directory |
+| `--retail` | send the study to the retail experiment ledger (/api/retail/ledger/import) |
 
 ### Examples
 
@@ -404,10 +448,14 @@ alphaengine commands
 alphaengine run screen_universe --universe sp500
 alphaengine run size_position --data returns.csv
 alphaengine run validate_study --project research.momentum
+alphaengine seal study.json
+alphaengine report study.json
+alphaengine report study.json --retail
 alphaengine models
 alphaengine trace
 alphaengine run screen_universe --thesis momentum
 alphaengine logout
+alphaengine logout --purge
 alphaengine version
 ```
 
@@ -461,7 +509,7 @@ def backtest_fn(*, data, fast, slow):
 ```
 
 `data` is whatever you want it to be — a DataFrame, a dict of series, an array.
-The package never inspects it and it never leaves your machine.
+The package never inspects it; computation runs locally on your machine.
 
 ## What it does
 
@@ -531,8 +579,10 @@ Study.from_sweep(r, label="momentum, 9 configs").report()
 
 What crosses is an explicit allowlist: the trial count and how it was obtained,
 a content hash of the data, the verdict, the shape of the neighbourhood, the
-performance figures. Your returns, your prices and your parameter grid stay on
-the machine, and a guard keyed on length rather than field name refuses to send
+performance figures. Computation runs locally; when you are signed in to
+quantOS, summary figures are reported to your account, and full series are
+shared only if you opt in (`--share-series` or `ALPHAENGINE_SHARE_SERIES=1`).
+Without opt-in, a guard keyed on length (at most 512 elements) refuses to send
 anything series-shaped whatever it is called.
 
 Reporting is the only part of this package that touches a network, so it is the
@@ -541,15 +591,16 @@ makes no network call.
 
 ## Where this sits in QuantOS
 
-AlphaEngine is the open research layer of the [QuantOS](https://github.com/quantOSC)
-platform. It is the piece that runs on your machine, against your data, and it
-is complete on its own: everything above works offline and forever, at no cost.
+AlphaEngine is the open research layer of [quantOS](https://qosai.app)
+([GitHub](https://github.com/quantOSC)). AlphaEngine computes locally on your
+machine, against your data, and is complete on its own: everything above works
+offline and forever, at no cost.
 
-The QuantOS platform builds on it. Studies produced here can be persisted to a
-firm's record, referenced when an idea becomes a position, and assembled into
-the reports that go to an investment committee or an allocator. The library
-computes; the platform remembers and reports. The two halves are separated so
-that the part touching your data has no reason to phone home.
+quantOS ([https://qosai.app](https://qosai.app)) is the hosted research workspace
+that keeps the record and writes committee reports. Studies produced here can be
+persisted to a firm's record, referenced when an idea becomes a position, and
+assembled into the reports that go to an investment committee or an allocator.
+The library computes; the platform remembers and reports.
 
 ## The methods
 
@@ -563,19 +614,35 @@ Frontier." *Journal of Risk* 15(2), 3 to 44.
 Bailey, D. H., and López de Prado, M. (2014). "The Deflated Sharpe Ratio:
 Correcting for Selection Bias, Backtest Overfitting, and Non-Normality."
 *Journal of Portfolio Management* 40(5), 94 to 107.
+*Implementation notes:* Grid trials are treated as independent (`N = len(grid)`
+with no effective-$N$ clustering adjustment). Cross-trial Sharpe dispersion
+($\sigma_{\text{SR}}$) is computed across valid grid trials when at least two
+exist, falling back to single-series Lo (2002) sampling error otherwise. At
+`n_trials=1`, no multiple-testing deflation applies (`sr0_expected_max = 0.0`,
+`deflated_sharpe = psr_vs_zero`). Verdict thresholds on `deflated_sharpe`:
+`< 0.5` is `likely_noise`, `0.5` to `< 0.9` is `marginal`, and `DSR >= 0.9` is
+`robust`.
 
 **Probability of Backtest Overfitting via CSCV**
 Bailey, D. H., Borwein, J., López de Prado, M., and Zhu, Q. J. (2017). "The
 Probability of Backtest Overfitting." *Journal of Computational Finance* 20(4),
 39 to 69.
 
-**Combinatorial purged cross-validation**
+**Combinatorial out-of-sample stability (`combinatorial_oos_stability`)**
 López de Prado, M. (2018). *Advances in Financial Machine Learning.* Wiley,
 chapters 7 and 12.
+*Implementation note:* Evaluates a single pre-computed return stream across all
+$\binom{G}{k}$ held-out block combinations with `purge` and `embargo` trimmed
+from each test block (no model re-fitting or stitched training predictions).
+`cpcv_score` is retained as a deprecated alias.
 
 **Hierarchical Risk Parity**
 López de Prado, M. (2016). "Building Diversified Portfolios that Outperform
 Out of Sample." *Journal of Portfolio Management* 42(4), 59 to 69.
+*Implementation note:* `hrp_weights` uses the correlation metric distance
+$d_{ij} = \sqrt{\frac{1}{2}(1 - \rho_{ij})}$ with single-linkage hierarchical
+clustering (`scipy.cluster.hierarchy.linkage(..., method="single")`), followed
+by quasi-diagonalization and recursive inverse-variance bisection.
 
 **Covariance shrinkage and spectral denoising**
 Ledoit, O., and Wolf, M. (2004). "A Well-Conditioned Estimator for
@@ -690,10 +757,11 @@ controls switched off. Only a run that could not execute a step exits non-zero.
 > CLI, is the one thing that cannot work here. You cannot have isolation and
 > in-process data access, and your data not moving is the point.
 
-**No LLM dependency and no key field.** `AgentDriver` takes a callable, so you
-bring your own model by passing a function. There is nowhere in this tool to put
-a model key, ours or yours, and that is how "runs under your own account" is
-satisfied structurally rather than promised.
+**No LLM dependency in the core.** `AgentDriver` takes a callable, so you bring
+your own model by passing a function or setting your provider's environment
+variable. LLM keys are never sent to QuantOS; if you choose to persist keys
+locally at `login`, they live in `~/.config/alphaengine/credentials.json`
+(mode `0600`) and are removed by `alphaengine logout --purge`.
 
 ## Development