alphaengine 1.1.0__tar.gz → 1.1.1__tar.gz

{alphaengine-1.1.0 → alphaengine-1.1.1}/.github/workflows/publish.yml

@@ -35,7 +35,7 @@ jobs:
           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)"
+          python -c "import os, tomllib, sys; v = tomllib.load(open('pyproject.toml', 'rb'))['project']['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.1.0 → alphaengine-1.1.1}/CHANGELOG.md

@@ -6,6 +6,24 @@ 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.1.1] - 2026-10-24
+
+### Added
+- **Single firm-key choke point (`alphaengine.auth.require_firm_key`):** Used by every gated command (`run`, `show`, `monitor`/`watch`, `validate`, `screen`, `diagnose`, `signal`, `stress`, `overlap`, `size`, `workflows`, `runs`, `gaps`, `tonight`, and the CLI OS: `init`, `log`, `diff`, `rerun`, `data`, `idea`, `seal`, `report`, `remote`, `push`, `pull`, `plugin`, `shell`). Free and keyless forever: `import alphaengine`, `alphaengine demo`, `alphaengine process`, and `ae verify`.
+- **OS keychain support & key redaction:** `auth.py` stores keys in the OS keychain (`keyring`) when available with `~/.config/alphaengine/credentials.json` (`0600`) as fallback, and `redact_secrets()` strips `ae_live_*` tokens from CLI output, error messages, tracebacks, and `--json` envelopes.
+- **Canonical SHA-256 contract & golden fixture (`alphaengine/contracts/hash_golden.json`):** Unified `content_sha256`, study seals, `.alphaengine/objects/` CAS blobs, dataset hashes, and parameter hashes on `canonical_sha256()` (Schema 1.2 sorted-key JSON, `.8f` float formatting, 64-hex SHA-256). Added `verify_study_mode()` so studies sealed under the pre-1.2 legacy format still verify and are labeled `"legacy"`.
+- **Free vs. Firm documentation (`docs/free-vs-firm.md`):** Documents the offline open-source library boundary, firm `ae_live_` Connect keys, and what uses the network.
+- **Socket-blocked offline smoke test:** Replaced the import-only check in `tests/test_smoke.py` with a socket-blocked test (`socket.socket` and `socket.create_connection` patched to raise) that imports `alphaengine` and executes `deflated_sharpe` (DSR), `pbo_cscv` (PBO via CSCV), `combinatorial_oos_stability`, `performance_report`, `compute_var_cvar`, `sweep`, `load_csv`, `from_quantconnect`, and `from_vectorbt`.
+
+### Changed
+- **Cumulative project-wide trials & DSR everywhere:** Project-wide cumulative trial counts (`project_trials` across `.alphaengine/ledger/trials.jsonl`) now feed every DSR — run output, headline `deflated_sharpe` and `n_trials`, `ae push` payloads, and `ae seal` studies — with no per-run or per-family reset.
+- **Identical re-run deduplication:** Re-running an identical configuration (`command`, `params_hash`, and `dataset_hashes` matching a prior run in `.alphaengine/ledger/runs.jsonl`) records `duplicate_of` and adds `0` new trials (`9 -> 9`), whereas distinct configurations always increment cumulative `N` (`9 -> 18`).
+- **Removed bare `except Exception: pass` in `sweep/runner.py`:** `_maybe_record_project_sweep` now raises a descriptive `RuntimeError` when a discovered `.alphaengine/` project ledger cannot be written.
+- **Metadata-driven `__version__` and naming cleanup:** `__version__` is loaded via `importlib.metadata.version("alphaengine")` with no hardcoded version strings; standardized `combinatorial_oos_stability` (with `cpcv_score` emitting `DeprecationWarning`) and `PBO via CSCV` across docs and top-level exports.
+
+### Removed
+- **Retail CLI path (`--retail` and `/api/retail/ledger/import`):** Removed `--retail` from `report` and CLI dispatch. Retail ledger import is performed via web upload in the quantOS portal.
+
 ## [1.1.0] - 2026-10-24
 
 ### Added

{alphaengine-1.1.0 → alphaengine-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 1.1.0
+Version: 1.1.1
 Summary: Validated research tooling for investment strategies: deflation, overfitting detection, and honest trial counts.
 Project-URL: Homepage, https://qosai.app
 Project-URL: Documentation, https://github.com/quantOSC/alphaengine#readme
@@ -170,16 +170,15 @@ Each is useful without the one above it. `login` lights the next one.
 
 | Rung | What you need | What you get |
 |---|---|---|
-| **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>`. |
+| **The maths** | nothing | `alphaengine demo`, `alphaengine process`, `ae verify`, and the full Python API (`import alphaengine`, `sweep`, `core`), offline, forever. No account. |
+| **Firm workflows & CLI OS** | a firm `ae_live_` key from **Connect** in your firm's quantOS portal (`login` or `QUANTOS_API_KEY`; see [docs/free-vs-firm.md](docs/free-vs-firm.md)) | The eight workflow commands (`diagnose`, `screen`, `signal`, `validate`, `stress`, `overlap`, `size`, `monitor`), `workflows`, `runs`, `gaps`, `tonight`, `run <workflow>`, and the Research OS (`init`, `log`, `show`, `diff`, `rerun`, `watch`, `data`, `idea`, `seal`, `report`, `remote`, `push`, `pull`, `plugin`, `shell`). |
 | **Ask anything** | your OWN model key (`login anthropic`) | Plain English in. Runs under your account, not ours. |
 
-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.
+The workflow commands and Research OS require a firm `ae_live_` key issued through
+**Connect** in your firm's quantOS portal (see [docs/free-vs-firm.md](docs/free-vs-firm.md)).
+There is no retail CLI key. `alphaengine demo`, `alphaengine process`, `ae verify`,
+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
@@ -197,7 +196,7 @@ at `login`). To delete the stored file at any time, run
 flowchart LR
   A["demo / import<br/>offline maths"] --> B["login<br/>QuantOS key"]
   B --> C["login anthropic<br/>your model"]
-  A -.->|"no account"| D["DSR · PBO · ICIR · HRP"]
+  A -.->|"no account"| D["DSR · PBO (CSCV) · ICIR · HRP"]
   B -.->|"ae_live_"| E["screen · validate · runs"]
   C -.->|"BYOK"| F["plain English in"]
 ```
@@ -249,11 +248,35 @@ distinction is the whole of the data boundary below.
 
 ---
 
-## Research OS quickstart
+## Quickstart: Offline First, Then Connect for Firms
 
-AlphaEngine works like `git` for quantitative research: initialize a local `.alphaengine/` project once, and every dataset registration, hypothesis, workflow run, parameter sweep, and sealed study is recorded in an append-only content-addressed ledger on your disk (see [project format](docs/project-format.md), [result envelope](docs/result-format.md), and [plugins](docs/plugins.md)). Both `alphaengine` and the short alias `ae` run the same entry point.
+### 1. Free and offline (no account, no API key)
+
+The Python library (`import alphaengine`), every validation and portfolio math primitive, `alphaengine demo`, `alphaengine process`, and `ae verify` run 100% offline with no key (see [Free vs. Firm](docs/free-vs-firm.md)):
+
+```bash
+pip install alphaengine
+
+# Run the built-in 9-trial parameter sweep and inspect the surface & DSR verdict
+alphaengine demo
+
+# Fit OU, GBM, jump-diffusion, and GARCH(1,1) processes and run DGP stress offline
+alphaengine process
+
+# Verify any sealed Study artifact (Schema 1.2 or legacy) without an account
+ae verify study.json
+```
+
+### 2. Connect for firms (`ae_live_` key from the quantOS portal)
+
+CLI workflows and the local-first Research OS (`ae init`, project ledgers, dataset registry, hypothesis tracking, sealing, memos, and workspace sync) require a firm `ae_live_` key issued through **Connect** in your firm's [quantOS portal](https://qosai.app). There is no retail CLI key or `--retail` flag.
+
+Both `alphaengine` and the short alias `ae` run the same entry point (see [Free vs. Firm](docs/free-vs-firm.md), [project format](docs/project-format.md), [result envelope](docs/result-format.md), and [plugins](docs/plugins.md)):
 
 ```bash
+# Sign in with your firm's Connect key (stored in OS keychain or 0600 fallback)
+ae login
+
 # 1. Initialize a local .alphaengine/ workspace
 ae init --name equity-momentum
 
@@ -274,7 +297,7 @@ ae log --family mom_20d
 ae show HEAD
 ae rerun HEAD
 
-# 6. Seal into a Schema 1.2 Study, verify against data, and export a committee memo
+# 6. Seal into a Schema 1.2 Study, verify against data (keyless), and export a committee memo
 ae seal HEAD
 ae verify .alphaengine/studies/HEAD.json
 ae report memo HEAD --format md
@@ -282,6 +305,18 @@ ae report memo HEAD --format md
 
 ---
 
+## What's new in 1.1.1
+
+- **Single firm-key choke point (`require_firm_key()`):** Every gated CLI workflow (`run`, `validate`, `screen`, `diagnose`, `signal`, `stress`, `overlap`, `size`, `monitor`) and Research OS command (`init`, `log`, `show`, `diff`, `rerun`, `watch`, `data`, `idea`, `seal`, `report`, `remote`, `push`, `pull`, `plugin`, `shell`) validates a firm `ae_live_` key upfront via `alphaengine.auth.require_firm_key()`. The library, `alphaengine demo`, `alphaengine process`, and `ae verify` remain free and keyless.
+- **OS keychain storage & secret redaction:** `auth.py` stores credentials in the OS keychain (`keyring`) when available with `~/.config/alphaengine/credentials.json` (`0600`) as fallback, and automatically redacts `ae_live_*` tokens from CLI output, errors, tracebacks, and `--json` envelopes.
+- **Retail CLI path removed:** Removed `--retail` and `/api/retail/ledger/import` from the CLI; retail ledger import happens via web upload in the quantOS portal.
+- **Unified canonical SHA-256 contract & golden fixture:** `canonical_sha256()` (Schema 1.2 sorted-key JSON with fixed `.8f` float formatting and full 64-hex SHA-256) powers `content_sha256`, study seals, CAS objects, dataset hashes, and parameter hashes. Legacy seals still verify and are labeled `"legacy"`. Shipped `alphaengine/contracts/hash_golden.json` in the wheel for cross-repo verification.
+- **Project-wide cumulative trials & DSR everywhere (with re-run deduplication):** The project-wide cumulative trial ledger feeds every DSR — run output, headline `deflated_sharpe` and `n_trials`, push payloads, and sealed studies — with no per-run or per-family reset. Re-running an identical configuration (`command` + `params_hash` + `dataset_hashes`) records `duplicate_of` and adds `0` new trials (`9 -> 9`), while distinct configurations increment cumulative `N` (`9 -> 18`).
+- **Metadata versioning & socket-blocked offline test:** `__version__` is read from `importlib.metadata.version("alphaengine")` with no hardcoded version strings, `combinatorial_oos_stability` and `PBO via CSCV` naming is standardized throughout, and `tests/test_smoke.py` enforces zero socket calls across DSR, PBO via CSCV, `combinatorial_oos_stability`, metrics, `sweep`, and loaders.
+- **Free vs. Firm guide:** Added [`docs/free-vs-firm.md`](docs/free-vs-firm.md).
+
+---
+
 ## What's new in 1.1.0
 
 - **Local-first project workspace (`ae init`):** Creates `.alphaengine/` (`project.toml`, `ledger/`, `data/`, `studies/`, `ideas/`, `universes/`, and SHA-256 content-addressed `objects/`). Commands walk up from the current directory to find the project; outside a project, every command behaves as a standalone call.
@@ -295,7 +330,7 @@ ae report memo HEAD --format md
 ## 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.
+- **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>` to ingest into quantOS.
 - **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"`).
 
@@ -316,7 +351,7 @@ A portal that rejects the trace does not fail the run.
 ## What's new in 0.8.0
 
 Named processes, Grinold, and a frozen chart contract. Existing goldens
-(deflated Sharpe, PBO, performance, screen) are byte-identical. New figures
+(deflated Sharpe, PBO via CSCV, performance, screen) are byte-identical. New figures
 are a public contract from this release. The study schema is **1.1**: optional
 `process` and `charts` fields; 1.0 studies still load.
 
@@ -345,7 +380,7 @@ a = grinold_alpha(panel, ic=0.05, vols=vols)  # alpha stays here; missing vols a
 ## What's new in 0.7.0
 
 The daily modelling morning, and the overnight book, without a third
-dependency. Existing goldens (deflated Sharpe, PBO, performance, screen) are
+dependency. Existing goldens (deflated Sharpe, PBO via CSCV, performance, screen) are
 byte-identical. New figures are a public contract from this release.
 
 | You have | You get | Module |
@@ -416,7 +451,7 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `watch <pipeline.yaml> [--interval SECONDS]` | re-run a declarative pipeline whenever a registered dataset file changes | shell + session |
 | `seal <study.json \| run \| idea>` | write canonical content_sha256 into a study (or seal a project run/idea) | shell + session |
 | `verify <study.json> [--data FILE]` | verify a study.json content_sha256 seal and optionally re-check figures | shell + session |
-| `report <study.json> [--retail] \| memo <idea \| run> [--format md \| pdf]` | send a study to quantOS, or export a cited committee memo (md/pdf) | shell + session |
+| `report <study.json> \| memo <idea \| run> [--format md \| pdf]` | send a study to quantOS (/api/me/runs/ingest), or export a cited committee memo | shell + session |
 | `<anything else>` | ask in plain English; your model picks a workflow and drives it | session |
 | `status` | the current run, and what is loaded | session |
 
@@ -477,7 +512,6 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `--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) |
 | `--name NAME` | name for the initialized project or registered dataset |
 | `--idea ID` | attach the run or filter the log to a local hypothesis id |
 | `--family FAMILY` | strategy or experiment family for cumulative trial counting |
@@ -532,7 +566,6 @@ alphaengine seal HEAD
 alphaengine verify study.json
 alphaengine verify study.json --data prices.csv
 alphaengine report study.json
-alphaengine report study.json --retail
 alphaengine report memo HEAD --format md
 alphaengine models
 alphaengine trace
@@ -587,7 +620,7 @@ above exists to copy:
 per-period returns themselves. `sweep` does `np.asarray(list(raw))`, so a dict
 of results iterates its *keys* and fails on the first string.
 
-**Return the same length for every combination.** PBO splits the trial matrix
+**Return the same length for every combination.** PBO via CSCV splits the trial matrix
 into time blocks and compares configurations within each block, which only means
 anything if they line up in time. Ragged output is refused rather than truncated,
 because silently trimming produces a confident number over series that do not
@@ -639,7 +672,7 @@ diffable, and versioned so it still parses in two years.
 
 | Module | Contents |
 |---|---|
-| `alphaengine.core` | deflated Sharpe, PSR, PBO via CSCV, CPCV, minimum track record length, performance and risk |
+| `alphaengine.core` | deflated Sharpe, PSR, PBO via CSCV, `combinatorial_oos_stability`, minimum track record length, performance and risk |
 | `alphaengine.core.panel` | cross-sectional rank, z-score, winsorize, neutralize |
 | `alphaengine.core.signals` | IC, ICIR, quantile returns, decay |
 | `alphaengine.core.cross_section` | Fama-MacBeth, quantile book with turnover |
@@ -678,14 +711,15 @@ 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. 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
+quantOS, summary figures are reported to your account, and full return series
+upload only with `--share-series` (or `ALPHAENGINE_SHARE_SERIES=1`). Without
+`--share-series`, 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
-only part that is not imported until you call it. `import alphaengine` still
-makes no network call.
+### What uses the network
+
+- **Zero network calls (completely offline):** `import alphaengine`, `sweep()`, `Study.save()`, `Study.load()`, every math primitive in `alphaengine.core` (`deflated_sharpe`, `pbo_cscv`, `combinatorial_oos_stability`, performance, risk, covariance, allocation, process calibration/stress, Grinold), local loaders (`load_csv`, `from_quantconnect`, `from_vectorbt`), `alphaengine demo`, `alphaengine process`, and `ae verify`.
+- **Uses the network (requires a firm `ae_live_` key from Connect):** `login` / `whoami`, CLI workflows (`validate`, `screen`, `diagnose`, `decompose`, `pairs`, `walkforward`, `compare`, `size`, `run`, `workflows`, `runs`, `gaps`, `tonight`), `Study.report()` / `ae report`, and workspace sync (`ae seal` key check, `ae push`, `ae pull`). Full return series upload **only** when `--share-series` is passed.
 
 ## Where this sits in QuantOS
 

{alphaengine-1.1.0 → alphaengine-1.1.1}/README.md

@@ -123,16 +123,15 @@ Each is useful without the one above it. `login` lights the next one.
 
 | Rung | What you need | What you get |
 |---|---|---|
-| **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>`. |
+| **The maths** | nothing | `alphaengine demo`, `alphaengine process`, `ae verify`, and the full Python API (`import alphaengine`, `sweep`, `core`), offline, forever. No account. |
+| **Firm workflows & CLI OS** | a firm `ae_live_` key from **Connect** in your firm's quantOS portal (`login` or `QUANTOS_API_KEY`; see [docs/free-vs-firm.md](docs/free-vs-firm.md)) | The eight workflow commands (`diagnose`, `screen`, `signal`, `validate`, `stress`, `overlap`, `size`, `monitor`), `workflows`, `runs`, `gaps`, `tonight`, `run <workflow>`, and the Research OS (`init`, `log`, `show`, `diff`, `rerun`, `watch`, `data`, `idea`, `seal`, `report`, `remote`, `push`, `pull`, `plugin`, `shell`). |
 | **Ask anything** | your OWN model key (`login anthropic`) | Plain English in. Runs under your account, not ours. |
 
-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.
+The workflow commands and Research OS require a firm `ae_live_` key issued through
+**Connect** in your firm's quantOS portal (see [docs/free-vs-firm.md](docs/free-vs-firm.md)).
+There is no retail CLI key. `alphaengine demo`, `alphaengine process`, `ae verify`,
+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
@@ -150,7 +149,7 @@ at `login`). To delete the stored file at any time, run
 flowchart LR
   A["demo / import<br/>offline maths"] --> B["login<br/>QuantOS key"]
   B --> C["login anthropic<br/>your model"]
-  A -.->|"no account"| D["DSR · PBO · ICIR · HRP"]
+  A -.->|"no account"| D["DSR · PBO (CSCV) · ICIR · HRP"]
   B -.->|"ae_live_"| E["screen · validate · runs"]
   C -.->|"BYOK"| F["plain English in"]
 ```
@@ -202,11 +201,35 @@ distinction is the whole of the data boundary below.
 
 ---
 
-## Research OS quickstart
+## Quickstart: Offline First, Then Connect for Firms
 
-AlphaEngine works like `git` for quantitative research: initialize a local `.alphaengine/` project once, and every dataset registration, hypothesis, workflow run, parameter sweep, and sealed study is recorded in an append-only content-addressed ledger on your disk (see [project format](docs/project-format.md), [result envelope](docs/result-format.md), and [plugins](docs/plugins.md)). Both `alphaengine` and the short alias `ae` run the same entry point.
+### 1. Free and offline (no account, no API key)
+
+The Python library (`import alphaengine`), every validation and portfolio math primitive, `alphaengine demo`, `alphaengine process`, and `ae verify` run 100% offline with no key (see [Free vs. Firm](docs/free-vs-firm.md)):
+
+```bash
+pip install alphaengine
+
+# Run the built-in 9-trial parameter sweep and inspect the surface & DSR verdict
+alphaengine demo
+
+# Fit OU, GBM, jump-diffusion, and GARCH(1,1) processes and run DGP stress offline
+alphaengine process
+
+# Verify any sealed Study artifact (Schema 1.2 or legacy) without an account
+ae verify study.json
+```
+
+### 2. Connect for firms (`ae_live_` key from the quantOS portal)
+
+CLI workflows and the local-first Research OS (`ae init`, project ledgers, dataset registry, hypothesis tracking, sealing, memos, and workspace sync) require a firm `ae_live_` key issued through **Connect** in your firm's [quantOS portal](https://qosai.app). There is no retail CLI key or `--retail` flag.
+
+Both `alphaengine` and the short alias `ae` run the same entry point (see [Free vs. Firm](docs/free-vs-firm.md), [project format](docs/project-format.md), [result envelope](docs/result-format.md), and [plugins](docs/plugins.md)):
 
 ```bash
+# Sign in with your firm's Connect key (stored in OS keychain or 0600 fallback)
+ae login
+
 # 1. Initialize a local .alphaengine/ workspace
 ae init --name equity-momentum
 
@@ -227,7 +250,7 @@ ae log --family mom_20d
 ae show HEAD
 ae rerun HEAD
 
-# 6. Seal into a Schema 1.2 Study, verify against data, and export a committee memo
+# 6. Seal into a Schema 1.2 Study, verify against data (keyless), and export a committee memo
 ae seal HEAD
 ae verify .alphaengine/studies/HEAD.json
 ae report memo HEAD --format md
@@ -235,6 +258,18 @@ ae report memo HEAD --format md
 
 ---
 
+## What's new in 1.1.1
+
+- **Single firm-key choke point (`require_firm_key()`):** Every gated CLI workflow (`run`, `validate`, `screen`, `diagnose`, `signal`, `stress`, `overlap`, `size`, `monitor`) and Research OS command (`init`, `log`, `show`, `diff`, `rerun`, `watch`, `data`, `idea`, `seal`, `report`, `remote`, `push`, `pull`, `plugin`, `shell`) validates a firm `ae_live_` key upfront via `alphaengine.auth.require_firm_key()`. The library, `alphaengine demo`, `alphaengine process`, and `ae verify` remain free and keyless.
+- **OS keychain storage & secret redaction:** `auth.py` stores credentials in the OS keychain (`keyring`) when available with `~/.config/alphaengine/credentials.json` (`0600`) as fallback, and automatically redacts `ae_live_*` tokens from CLI output, errors, tracebacks, and `--json` envelopes.
+- **Retail CLI path removed:** Removed `--retail` and `/api/retail/ledger/import` from the CLI; retail ledger import happens via web upload in the quantOS portal.
+- **Unified canonical SHA-256 contract & golden fixture:** `canonical_sha256()` (Schema 1.2 sorted-key JSON with fixed `.8f` float formatting and full 64-hex SHA-256) powers `content_sha256`, study seals, CAS objects, dataset hashes, and parameter hashes. Legacy seals still verify and are labeled `"legacy"`. Shipped `alphaengine/contracts/hash_golden.json` in the wheel for cross-repo verification.
+- **Project-wide cumulative trials & DSR everywhere (with re-run deduplication):** The project-wide cumulative trial ledger feeds every DSR — run output, headline `deflated_sharpe` and `n_trials`, push payloads, and sealed studies — with no per-run or per-family reset. Re-running an identical configuration (`command` + `params_hash` + `dataset_hashes`) records `duplicate_of` and adds `0` new trials (`9 -> 9`), while distinct configurations increment cumulative `N` (`9 -> 18`).
+- **Metadata versioning & socket-blocked offline test:** `__version__` is read from `importlib.metadata.version("alphaengine")` with no hardcoded version strings, `combinatorial_oos_stability` and `PBO via CSCV` naming is standardized throughout, and `tests/test_smoke.py` enforces zero socket calls across DSR, PBO via CSCV, `combinatorial_oos_stability`, metrics, `sweep`, and loaders.
+- **Free vs. Firm guide:** Added [`docs/free-vs-firm.md`](docs/free-vs-firm.md).
+
+---
+
 ## What's new in 1.1.0
 
 - **Local-first project workspace (`ae init`):** Creates `.alphaengine/` (`project.toml`, `ledger/`, `data/`, `studies/`, `ideas/`, `universes/`, and SHA-256 content-addressed `objects/`). Commands walk up from the current directory to find the project; outside a project, every command behaves as a standalone call.
@@ -248,7 +283,7 @@ ae report memo HEAD --format md
 ## 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.
+- **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>` to ingest into quantOS.
 - **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"`).
 
@@ -269,7 +304,7 @@ A portal that rejects the trace does not fail the run.
 ## What's new in 0.8.0
 
 Named processes, Grinold, and a frozen chart contract. Existing goldens
-(deflated Sharpe, PBO, performance, screen) are byte-identical. New figures
+(deflated Sharpe, PBO via CSCV, performance, screen) are byte-identical. New figures
 are a public contract from this release. The study schema is **1.1**: optional
 `process` and `charts` fields; 1.0 studies still load.
 
@@ -298,7 +333,7 @@ a = grinold_alpha(panel, ic=0.05, vols=vols)  # alpha stays here; missing vols a
 ## What's new in 0.7.0
 
 The daily modelling morning, and the overnight book, without a third
-dependency. Existing goldens (deflated Sharpe, PBO, performance, screen) are
+dependency. Existing goldens (deflated Sharpe, PBO via CSCV, performance, screen) are
 byte-identical. New figures are a public contract from this release.
 
 | You have | You get | Module |
@@ -369,7 +404,7 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `watch <pipeline.yaml> [--interval SECONDS]` | re-run a declarative pipeline whenever a registered dataset file changes | shell + session |
 | `seal <study.json \| run \| idea>` | write canonical content_sha256 into a study (or seal a project run/idea) | shell + session |
 | `verify <study.json> [--data FILE]` | verify a study.json content_sha256 seal and optionally re-check figures | shell + session |
-| `report <study.json> [--retail] \| memo <idea \| run> [--format md \| pdf]` | send a study to quantOS, or export a cited committee memo (md/pdf) | shell + session |
+| `report <study.json> \| memo <idea \| run> [--format md \| pdf]` | send a study to quantOS (/api/me/runs/ingest), or export a cited committee memo | shell + session |
 | `<anything else>` | ask in plain English; your model picks a workflow and drives it | session |
 | `status` | the current run, and what is loaded | session |
 
@@ -430,7 +465,6 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `--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) |
 | `--name NAME` | name for the initialized project or registered dataset |
 | `--idea ID` | attach the run or filter the log to a local hypothesis id |
 | `--family FAMILY` | strategy or experiment family for cumulative trial counting |
@@ -485,7 +519,6 @@ alphaengine seal HEAD
 alphaengine verify study.json
 alphaengine verify study.json --data prices.csv
 alphaengine report study.json
-alphaengine report study.json --retail
 alphaengine report memo HEAD --format md
 alphaengine models
 alphaengine trace
@@ -540,7 +573,7 @@ above exists to copy:
 per-period returns themselves. `sweep` does `np.asarray(list(raw))`, so a dict
 of results iterates its *keys* and fails on the first string.
 
-**Return the same length for every combination.** PBO splits the trial matrix
+**Return the same length for every combination.** PBO via CSCV splits the trial matrix
 into time blocks and compares configurations within each block, which only means
 anything if they line up in time. Ragged output is refused rather than truncated,
 because silently trimming produces a confident number over series that do not
@@ -592,7 +625,7 @@ diffable, and versioned so it still parses in two years.
 
 | Module | Contents |
 |---|---|
-| `alphaengine.core` | deflated Sharpe, PSR, PBO via CSCV, CPCV, minimum track record length, performance and risk |
+| `alphaengine.core` | deflated Sharpe, PSR, PBO via CSCV, `combinatorial_oos_stability`, minimum track record length, performance and risk |
 | `alphaengine.core.panel` | cross-sectional rank, z-score, winsorize, neutralize |
 | `alphaengine.core.signals` | IC, ICIR, quantile returns, decay |
 | `alphaengine.core.cross_section` | Fama-MacBeth, quantile book with turnover |
@@ -631,14 +664,15 @@ 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. 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
+quantOS, summary figures are reported to your account, and full return series
+upload only with `--share-series` (or `ALPHAENGINE_SHARE_SERIES=1`). Without
+`--share-series`, 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
-only part that is not imported until you call it. `import alphaengine` still
-makes no network call.
+### What uses the network
+
+- **Zero network calls (completely offline):** `import alphaengine`, `sweep()`, `Study.save()`, `Study.load()`, every math primitive in `alphaengine.core` (`deflated_sharpe`, `pbo_cscv`, `combinatorial_oos_stability`, performance, risk, covariance, allocation, process calibration/stress, Grinold), local loaders (`load_csv`, `from_quantconnect`, `from_vectorbt`), `alphaengine demo`, `alphaengine process`, and `ae verify`.
+- **Uses the network (requires a firm `ae_live_` key from Connect):** `login` / `whoami`, CLI workflows (`validate`, `screen`, `diagnose`, `decompose`, `pairs`, `walkforward`, `compare`, `size`, `run`, `workflows`, `runs`, `gaps`, `tonight`), `Study.report()` / `ae report`, and workspace sync (`ae seal` key check, `ae push`, `ae pull`). Full return series upload **only** when `--share-series` is passed.
 
 ## Where this sits in QuantOS
 

alphaengine-1.1.1/docs/free-vs-firm.md

@@ -0,0 +1,88 @@
+# Free Open-Source Library vs. Firm CLI Workflows (`Connect`)
+
+AlphaEngine has a strict, unambiguous boundary between what is **free and offline forever** for every researcher, and what requires a **firm `ae_live_` key** from **Connect** in the [quantOS portal](https://qosai.app).
+
+There is **no retail CLI key** and **no retail CLI path**. Retail ledger import happens by web upload in the quantOS portal, not through the CLI.
+
+---
+
+## 1. Free, Keyless, and 100% Offline
+
+Installing `pip install alphaengine` gives you the complete validation and research library with **no account, no API key, and zero network calls**:
+
+| Surface | Commands / Entry Points | Network Calls | Key Required |
+|---|---|---|---|
+| **Python Library** | `import alphaengine`, `sweep()`, `Study`, `save()`, `load()` | **None** | **No** |
+| **Validation Math** | `deflated_sharpe` (DSR), `probabilistic_sharpe_ratio` (PSR), `min_track_record_length`, `pbo_cscv` (PBO via CSCV), `combinatorial_oos_stability` | **None** | **No** |
+| **Portfolio & Process Math** | `performance_report`, `compute_var_cvar`, `alphaengine.core.panel`, `signals`, `cross_section`, `covariance`, `allocate`, `process`, `active` | **None** | **No** |
+| **Loaders** | `load_csv`, `load_delimited`, `from_quantconnect`, `from_vectorbt` | **None** | **No** |
+| **Offline CLI Demos** | `alphaengine demo`, `alphaengine process` | **None** | **No** |
+| **Study Verification** | `ae verify <study.json> [--data <file>]` | **None** | **No** |
+
+Anyone receiving a sealed `study.json` (whether an academic referee, a peer, or an allocator) can run `ae verify study.json --data prices.csv` offline without an account to verify both the canonical `content_sha256` seal (including legacy seals) and the 64-hex `data_hash`.
+
+### Quickstart: Offline First (No Account Needed)
+
+```bash
+pip install alphaengine
+
+# 1. Run the built-in 9-trial parameter sweep and inspect the surface & DSR verdict
+alphaengine demo
+
+# 2. Fit OU, GBM, jump-diffusion, and GARCH(1,1) processes and run DGP stress offline
+alphaengine process
+
+# 3. Verify any sealed Study artifact (Schema 1.2 or legacy)
+ae verify study.json
+```
+
+```python
+from alphaengine import (
+    combinatorial_oos_stability,
+    compute_var_cvar,
+    deflated_sharpe,
+    pbo_cscv,
+    performance_report,
+    sweep,
+)
+```
+
+---
+
+## 2. Connect for Firms (`ae_live_` Key Required)
+
+CLI workflows and the local-first Research OS (`ae init`, project ledgers, dataset registry, hypothesis tracking, sealing, memos, and workspace sync) are built for quantitative teams and require an `ae_live_` key issued to your firm through **Connect** in the quantOS portal:
+
+- **Core workflows:** `diagnose`, `screen`, `signal`, `validate`, `stress`, `overlap`, `size`, `monitor`, `run`, `workflows`, `runs`, `gaps`, `tonight`
+- **Research OS (`ae`):** `init`, `log`, `show`, `diff`, `rerun`, `watch`, `data`, `idea`, `seal`, `report`, `remote`, `push`, `pull`, `plugin`, `shell`
+
+Every gated command checks `alphaengine.auth.require_firm_key()` before executing. The server is the authority: the key's firm tier is verified server-side on every request, and a key stops working if its firm leaves an active firm tier.
+
+### Quickstart: Connect for Firms
+
+1. Open your firm's [quantOS portal](https://qosai.app) → **Connect** and issue an `ae_live_...` key.
+2. Sign in once from your terminal (stored in your OS keychain via `keyring` when available, or `~/.config/alphaengine/credentials.json` with `0600` permissions as fallback):
+
+```bash
+ae login
+# or set: export QUANTOS_API_KEY="ae_live_..."
+```
+
+3. Initialize your firm project and run workflows with cumulative project-wide trial accounting:
+
+```bash
+ae init --name equity-momentum
+ae data add prices.csv --name equities --asof-col date
+ae idea new "Cross-sectional 20d momentum holds net of costs" --kill-if "DSR < 0.9"
+ae validate --project research.momentum --idea idea_1
+ae seal HEAD
+ae push
+```
+
+---
+
+## 3. What Uses the Network (and What Never Leaves Your Machine)
+
+- **Makes zero network calls:** The Python library (`import alphaengine`), all math functions, `sweep()`, `Study.save()` / `load()`, `alphaengine demo`, `alphaengine process`, and `ae verify`. Enforced in CI by a socket-blocked test (`tests/test_smoke.py`).
+- **Uses the network:** `ae login` / `whoami`, CLI workflows (`validate`, `screen`, `diagnose`, etc.), `Study.report()` / `ae report`, and workspace sync (`ae push`, `ae pull`).
+- **Return series boundary:** By default, only summary figures and canonical SHA-256 hashes cross the wire; any list longer than 512 elements is refused by both client and server guards. Full return series upload **only** when you explicitly pass `--share-series` (or set `ALPHAENGINE_SHARE_SERIES=1`).

{alphaengine-1.1.0 → alphaengine-1.1.1}/docs/project-format.md

@@ -71,9 +71,11 @@ Each `.jsonl` file under `ledger/`, `data/`, and `ideas/` contains one UTF-8 JSO
 
 ---
 
-## 4. Discovery Rule
+## 4. Discovery Rule & Network Boundary
 
 When any `ae` / `alphaengine` command runs:
 1. It checks the current working directory and each parent directory for `.alphaengine/project.toml`.
 2. If found, the command attaches to that `Project` instance.
-3. If not found, commands that do not strictly require a project (`demo`, `process`, `seal <study.json>`, `report`, `version`, etc.) run in standalone mode without touching the filesystem.
+3. If not found, commands that do not strictly require a project (`demo`, `process`, `verify <study.json>`, `version`, etc.) run in standalone mode without touching the filesystem.
+
+**Network boundary:** The Python library (`import alphaengine`, `sweep`, DSR, PBO via CSCV, `combinatorial_oos_stability`, metrics, loaders), `alphaengine demo`, `alphaengine process`, and `ae verify` make no network calls. Network calls occur only during `login`/`whoami`, firm CLI workflows, `report`, and `seal`/`push`/`pull` against the configured remote. Full return series upload only when `--share-series` is explicitly passed; otherwise the 512-element wire guard rejects any series-length list.

{alphaengine-1.1.0 → alphaengine-1.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "alphaengine"
-dynamic = ["version"]
+version = "1.1.1"
 description = "Validated research tooling for investment strategies: deflation, overfitting detection, and honest trial counts."
 readme = "README.md"
 license = "Apache-2.0"
@@ -112,9 +112,6 @@ Documentation = "https://github.com/quantOSC/alphaengine#readme"
 Source = "https://github.com/quantOSC/alphaengine"
 Issues = "https://github.com/quantOSC/alphaengine/issues"
 
-[tool.hatch.version]
-path = "src/alphaengine/_version.py"
-
 [tool.hatch.build.targets.wheel]
 packages = ["src/alphaengine"]
 

{alphaengine-1.1.0 → alphaengine-1.1.1}/src/alphaengine/__init__.py

@@ -24,14 +24,23 @@ WHAT THIS LIBRARY IS NOT
 OFFLINE BY CONSTRUCTION
     Importing this module makes no network call and needs no account. numpy and
     scipy, nothing else. Everything above runs on a laptop with the wifi off.
-    A workflow run can also send a math trace — the formula, its inputs, and
-    the series that line was computed on — to the portal on its own channel.
-    Study ingest still refuses anything series-shaped.
+    Summary figures upload only when you explicitly run a firm CLI workflow or
+    `report()`; full return series upload only with `--share-series`.
 """
 
 from typing import Any
 
 from ._version import __version__
+from .core import (
+    combinatorial_oos_stability,
+    compute_var_cvar,
+    cpcv_score,
+    deflated_sharpe,
+    min_track_record_length,
+    pbo_cscv,
+    performance_report,
+    probabilistic_sharpe_ratio,
+)
 from .study import SCHEMA_VERSION, Study, load, save
 from .sweep import SweepResult, sweep
 
@@ -51,6 +60,14 @@ __all__ = [
     "ReportError",
     "SCHEMA_VERSION",
     "io",
+    "combinatorial_oos_stability",
+    "cpcv_score",
+    "deflated_sharpe",
+    "probabilistic_sharpe_ratio",
+    "min_track_record_length",
+    "pbo_cscv",
+    "performance_report",
+    "compute_var_cvar",
 ]
 
 

{alphaengine-1.1.0 → alphaengine-1.1.1}/src/alphaengine/_version.py

@@ -146,7 +146,7 @@ is what a changed figure costs. The API may still move underneath it.
 # cross-trial Sharpe dispersion into `deflated_sharpe` per Bailey & López de
 # Prado (2014). `combinatorial_oos_stability` replaces `cpcv_score` (kept as a
 # deprecated alias). Study schema 1.2 adds `content_sha256` sealing, full 64-hex
-# data hashes, `alphaengine seal`, `alphaengine report [--retail]`, and
+# data hashes, `alphaengine seal`, `alphaengine report`, and
 # `alphaengine.io` loaders (`from_quantconnect`, `from_vectorbt`). Series upload
 # on `/traces` is opt-in via `--share-series` or `ALPHAENGINE_SHARE_SERIES=1`.
 # 1.1.0 IS THE LOCAL-FIRST RESEARCH OS. No golden in tests/test_goldens.py
@@ -159,7 +159,9 @@ is what a changed figure costs. The API may still move underneath it.
 # prior-work warnings, export `[run_id]`-cited committee memos, discover
 # `alphaengine.plugins` entry points, watch datasets, monitor live drift, and
 # sync with quantOS on opt-in (`ae push` / `ae pull`).
-__version__ = "1.1.0"
+from importlib.metadata import version as _pkg_version
+
+__version__ = _pkg_version("alphaengine")
 
 #: Default workflow/ingest API host until a dedicated qosai.app API host exists.
 #: Overridable via ``ALPHAENGINE_API_URL`` (or ``QUANTOS_API_URL``).