alphaengine 1.0.3__tar.gz → 1.1.0__tar.gz

{alphaengine-1.0.3 → alphaengine-1.1.0}/CHANGELOG.md

@@ -6,6 +6,20 @@ 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.0] - 2026-10-24
+
+### Added
+- **Project workspace (`ae init` and `ae` alias):** Initializes `.alphaengine/` (`project.toml`, `ledger/`, `data/`, `studies/`, `ideas/`, `universes/`, and SHA-256 content-addressed `objects/`). Commands walk up from the current directory to locate the project; documented in `docs/project-format.md`.
+- **Project-wide ledger (`ae log`, `ae show`, `ae diff`, `ae rerun`):** Every run and `sweep()` inside a project writes an append-only run record and accumulates trial counts across runs on the same `idea_id` or `family`.
+- **Dataset registry (`ae data add`, `ae data list`, `ae data show`, `ae data lineage`):** Registers CSV and Parquet datasets locally with full 64-hex SHA-256 hashes, row counts, date ranges, column schemas, and checks for duplicate timestamps, gaps, look-ahead rows (`--asof-col`), and survivorship hints.
+- **Standard result envelope (`v1.0`), pipes, and declarative YAML pipelines:** Added `--json` and `--stdin` support across commands (`ae screen --json | ae validate --stdin | ae size --stdin`), `ae run <pipeline.yaml>`, two example pipelines in `examples/`, and `docs/result-format.md`.
+- **Hypotheses as objects (`ae idea new`, `ae idea list`, `ae idea status`, `ae idea show`):** First-class hypothesis tracking with `--kill-if` rule evaluation, `--idea <id>` run linking, and pre-run prior-work checks.
+- **Extended seal, verify, and committee memos:** `ae seal <run|idea>`, `ae verify <study.json> [--data <file>]`, and `ae report memo <idea|run> --format md|pdf` where every figure cites its `[run_id]`.
+- **Research shell (`ae shell`):** Interactive shell with tab completion over verbs, run IDs, dataset names, and idea IDs, a project status line with cumulative trial count, inline ledger/idea commands, and automatic ledger recording of agent proposals.
+- **Entry-point plugin system (`alphaengine.plugins`, `ae plugin list`):** Supports `loader`, `method`, and `template` plugins, with `quantconnect`, `vectorbt`, `csv`, `deflated_sharpe`, `combinatorial_oos_stability`, and `committee_memo` registered as built-ins (`docs/plugins.md`).
+- **Local file watcher & live drift monitor:** `ae watch <pipeline.yaml>` re-runs pipelines when watched datasets change on disk; `ae monitor <run> --live <file>` compares live returns against the backtest's bootstrapped 95% intervals.
+- **Opt-in workspace sync (`ae remote`, `ae push [--dry-run]`, `ae pull`):** Syncs sealed studies, allowlisted ledger runs, and ideas to `POST /api/workspace/sync` (with 404 fallback to `POST /api/me/runs/ingest`), enforcing the 512-element series cap and never uploading dataset rows.
+
 ## [1.0.3] - 2026-10-24
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 1.0.3
+Version: 1.1.0
 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
@@ -249,6 +249,49 @@ distinction is the whole of the data boundary below.
 
 ---
 
+## Research OS quickstart
+
+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.
+
+```bash
+# 1. Initialize a local .alphaengine/ workspace
+ae init --name equity-momentum
+
+# 2. Register a local CSV (or Parquet) dataset and run hygiene checks
+ae data add prices.csv --name equities --asof-col date
+ae data show equities
+
+# 3. Record a falsifiable hypothesis with an explicit kill rule
+ae idea new "Cross-sectional 20d momentum holds net of costs" --kill-if "DSR < 0.9" --family mom_20d
+
+# 4. Run a validation, declarative YAML pipeline, or Unix JSON pipe
+ae validate --project alphaengine.demo --idea idea_1
+ae run examples/screen_validate_size.yaml
+ae screen --data equities --json | ae validate --stdin --json | ae size --stdin
+
+# 5. Inspect the append-only project ledger, cumulative trials, and diffs
+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
+ae seal HEAD
+ae verify .alphaengine/studies/HEAD.json
+ae report memo HEAD --format 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.
+- **Project-wide ledger & cumulative trial counting (`ae log`, `ae show`, `ae diff`, `ae rerun`):** Runs and sweeps inside a project automatically record parameter hashes, dataset hashes, and figures, accumulating trial counts across runs on the same `idea_id` or `family`.
+- **Dataset registry (`ae data add|list|show|lineage`):** Tracks local CSV and Parquet datasets by full SHA-256, row count, date range, column schema, and hygiene diagnostics (duplicate timestamps, missing/calendar gaps, `--asof-col` look-ahead hints, and survivorship hints).
+- **Versioned `v1.0` JSON result envelope, `--stdin` pipes, & YAML pipelines:** Every command supports `--json` and `--stdin` (`ae screen --json | ae validate --stdin | ae size --stdin`), plus declarative multi-step recipes (`ae run pipeline.yaml`).
+- **Hypotheses as objects (`ae idea new|list|status|show`):** Link runs with `--idea <id>`, evaluate `--kill-if` rules against cumulative figures, and receive automatic prior-work warnings before running overlapping parameter sets.
+- **Seal, verify, & cited committee memos:** `ae seal <run|idea>`, `ae verify <study.json> [--data <file>]`, and `ae report memo <idea|run> --format md|pdf` (where every figure cites `[run_id]`).
+- **Research shell (`ae shell`), plugins (`ae plugin list`), watcher (`ae watch`), live drift monitor (`ae monitor <run> --live <file>`), & opt-in sync (`ae remote`, `ae push [--dry-run]`, `ae pull`).**
+
 ## 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`.
@@ -339,9 +382,13 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 
 | Command | Does | Where |
 |---|---|---|
+| `init [--name NAME]` | initialize a local .alphaengine/ research project in this directory | shell + session |
 | `demo` | run the built-in example offline, with no account and no data | shell + session |
 | `process [ou \| gbm \| jump \| garch]` | fit a named process to a series and stress it, offline | shell + session |
 | `runs [--limit N]` | your own week: what ran, what it decided, what it filed | shell + session |
+| `log [--idea ID] [--family FAMILY] [--since DATE] [--verdict VERDICT]` | list local project ledger runs, trial counts, and verdicts | shell + session |
+| `show <run>` | inspect one recorded project run, its hashes, trials, and figures | shell + session |
+| `diff <run-a> <run-b>` | compare data, parameter, trial, and figure changes between two runs | shell + session |
 | `gaps` | what your record says is UNANSWERED, and what closes each one | shell + session |
 | `tonight [--budget N]` | what would run unattended tonight, without running any of it | shell + session |
 | `workflows` | what the server offers, what each needs, and which reproduce | shell + session |
@@ -365,8 +412,11 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `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 |
+| `rerun <run>` | reproduce a recorded project run from its inputs and check figures | shell + session |
+| `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 |
 | `<anything else>` | ask in plain English; your model picks a workflow and drives it | session |
 | `status` | the current run, and what is loaded | session |
 
@@ -376,19 +426,25 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 |---|---|---|
 | `book [<name> \| status]` | show or load sleeves on the multi-strategy book | session |
 | `load <file \| module \| universe>` | a CSV, a project module, or a portal universe | session |
+| `idea new "<thesis>" --kill-if "<rule>" [--family FAMILY] \| list \| status <id> <state> \| show <id>` | create, list, update, and evaluate local research hypotheses | shell + session |
 | `thesis [<name> \| clear]` | choose a portal thesis for the next run | session |
 | `correlation` | the correlation of every loaded name with every other name | session |
 | `covariance` | the sample covariance of every loaded name with every other name | session |
 | `cointegration` | which loaded names are cointegrated | session |
 | `portfolio` | weights for the names already loaded | session |
 | `universe <name>` | same as load: a universe registered in the portal | session |
-| `data <file>` | same as load: a local CSV or parquet | session |
+| `data add <file> [--name NAME] [--asof-col COL] \| list \| show <name> \| lineage <run>` | register, inspect, and trace local CSV/Parquet datasets | shell + session |
 | `project <module>` | same as load: a module with data and backtest_fn | session |
 
 ### Session
 
 | Command | Does | Where |
 |---|---|---|
+| `remote add <name> [url] \| list` | configure or list remote sync endpoints in .alphaengine/project.toml | shell + session |
+| `push [remote] [--dry-run] [--share-series]` | sync sealed studies, ledger runs, and ideas to quantOS (opt-in network) | shell + session |
+| `pull [remote]` | pull team runs and ideas from quantOS into the local ledger (read-only) | shell + session |
+| `plugin list` | list installed loader, method, and report template plugins | shell + session |
+| `shell` | open the interactive research shell with project completion and status | shell |
 | `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 |
@@ -422,6 +478,20 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `--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 |
+| `--since DATE` | filter project log to runs on or after YYYY-MM-DD |
+| `--verdict VERDICT` | filter project log by verdict (e.g. robust, marginal, likely_noise) |
+| `--asof-col COL` | as-of column name or cutoff date for look-ahead checks in data add |
+| `--json` | emit a versioned v1.0 JSON result envelope to stdout |
+| `--stdin` | read an upstream JSON result envelope from standard input |
+| `--kill-if RULE` | kill rule for a hypothesis, e.g. 'DSR < 0.9' |
+| `--format FMT` | output format for report memo: md or pdf (default md) |
+| `--dry-run` | print the exact sync payload without making a network call |
+| `--live FILE` | live return series CSV to compare against a recorded backtest run |
+| `--interval SECONDS` | polling interval in seconds for watch (default 1.0) |
+| `--cycles N` | number of polling cycles for watch before exiting (0 means continuous) |
 
 ### Examples
 
@@ -434,11 +504,17 @@ alphaengine stress
 alphaengine overlap
 alphaengine size
 alphaengine monitor
+alphaengine init
+alphaengine init --name momentum
 alphaengine demo
 alphaengine process
 alphaengine process ou
 alphaengine runs
 alphaengine runs --limit 50
+alphaengine log
+alphaengine log --family momentum --verdict likely_noise
+alphaengine show HEAD
+alphaengine diff run_a run_b
 alphaengine gaps
 alphaengine tonight
 alphaengine tonight --budget 5
@@ -448,12 +524,34 @@ alphaengine commands
 alphaengine run screen_universe --universe sp500
 alphaengine run size_position --data returns.csv
 alphaengine run validate_study --project research.momentum
+alphaengine run examples/screen_validate_size.yaml
+alphaengine rerun HEAD
+alphaengine watch examples/screen_validate_size.yaml
 alphaengine seal study.json
+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
+alphaengine idea new "Cross-sectional momentum holds" --kill-if "DSR < 0.9" --family momentum
+alphaengine idea list
+alphaengine idea status idea_1 testing
+alphaengine idea show idea_1
 alphaengine run screen_universe --thesis momentum
+alphaengine data add prices.csv --name equities
+alphaengine data list
+alphaengine data show equities
+alphaengine data lineage HEAD
+alphaengine remote add quantos
+alphaengine remote add quantos https://qosai.app
+alphaengine push --dry-run
+alphaengine push
+alphaengine pull
+alphaengine plugin list
+alphaengine shell
 alphaengine logout
 alphaengine logout --purge
 alphaengine version

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

@@ -202,6 +202,49 @@ distinction is the whole of the data boundary below.
 
 ---
 
+## Research OS quickstart
+
+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.
+
+```bash
+# 1. Initialize a local .alphaengine/ workspace
+ae init --name equity-momentum
+
+# 2. Register a local CSV (or Parquet) dataset and run hygiene checks
+ae data add prices.csv --name equities --asof-col date
+ae data show equities
+
+# 3. Record a falsifiable hypothesis with an explicit kill rule
+ae idea new "Cross-sectional 20d momentum holds net of costs" --kill-if "DSR < 0.9" --family mom_20d
+
+# 4. Run a validation, declarative YAML pipeline, or Unix JSON pipe
+ae validate --project alphaengine.demo --idea idea_1
+ae run examples/screen_validate_size.yaml
+ae screen --data equities --json | ae validate --stdin --json | ae size --stdin
+
+# 5. Inspect the append-only project ledger, cumulative trials, and diffs
+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
+ae seal HEAD
+ae verify .alphaengine/studies/HEAD.json
+ae report memo HEAD --format 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.
+- **Project-wide ledger & cumulative trial counting (`ae log`, `ae show`, `ae diff`, `ae rerun`):** Runs and sweeps inside a project automatically record parameter hashes, dataset hashes, and figures, accumulating trial counts across runs on the same `idea_id` or `family`.
+- **Dataset registry (`ae data add|list|show|lineage`):** Tracks local CSV and Parquet datasets by full SHA-256, row count, date range, column schema, and hygiene diagnostics (duplicate timestamps, missing/calendar gaps, `--asof-col` look-ahead hints, and survivorship hints).
+- **Versioned `v1.0` JSON result envelope, `--stdin` pipes, & YAML pipelines:** Every command supports `--json` and `--stdin` (`ae screen --json | ae validate --stdin | ae size --stdin`), plus declarative multi-step recipes (`ae run pipeline.yaml`).
+- **Hypotheses as objects (`ae idea new|list|status|show`):** Link runs with `--idea <id>`, evaluate `--kill-if` rules against cumulative figures, and receive automatic prior-work warnings before running overlapping parameter sets.
+- **Seal, verify, & cited committee memos:** `ae seal <run|idea>`, `ae verify <study.json> [--data <file>]`, and `ae report memo <idea|run> --format md|pdf` (where every figure cites `[run_id]`).
+- **Research shell (`ae shell`), plugins (`ae plugin list`), watcher (`ae watch`), live drift monitor (`ae monitor <run> --live <file>`), & opt-in sync (`ae remote`, `ae push [--dry-run]`, `ae pull`).**
+
 ## 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`.
@@ -292,9 +335,13 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 
 | Command | Does | Where |
 |---|---|---|
+| `init [--name NAME]` | initialize a local .alphaengine/ research project in this directory | shell + session |
 | `demo` | run the built-in example offline, with no account and no data | shell + session |
 | `process [ou \| gbm \| jump \| garch]` | fit a named process to a series and stress it, offline | shell + session |
 | `runs [--limit N]` | your own week: what ran, what it decided, what it filed | shell + session |
+| `log [--idea ID] [--family FAMILY] [--since DATE] [--verdict VERDICT]` | list local project ledger runs, trial counts, and verdicts | shell + session |
+| `show <run>` | inspect one recorded project run, its hashes, trials, and figures | shell + session |
+| `diff <run-a> <run-b>` | compare data, parameter, trial, and figure changes between two runs | shell + session |
 | `gaps` | what your record says is UNANSWERED, and what closes each one | shell + session |
 | `tonight [--budget N]` | what would run unattended tonight, without running any of it | shell + session |
 | `workflows` | what the server offers, what each needs, and which reproduce | shell + session |
@@ -318,8 +365,11 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `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 |
+| `rerun <run>` | reproduce a recorded project run from its inputs and check figures | shell + session |
+| `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 |
 | `<anything else>` | ask in plain English; your model picks a workflow and drives it | session |
 | `status` | the current run, and what is loaded | session |
 
@@ -329,19 +379,25 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 |---|---|---|
 | `book [<name> \| status]` | show or load sleeves on the multi-strategy book | session |
 | `load <file \| module \| universe>` | a CSV, a project module, or a portal universe | session |
+| `idea new "<thesis>" --kill-if "<rule>" [--family FAMILY] \| list \| status <id> <state> \| show <id>` | create, list, update, and evaluate local research hypotheses | shell + session |
 | `thesis [<name> \| clear]` | choose a portal thesis for the next run | session |
 | `correlation` | the correlation of every loaded name with every other name | session |
 | `covariance` | the sample covariance of every loaded name with every other name | session |
 | `cointegration` | which loaded names are cointegrated | session |
 | `portfolio` | weights for the names already loaded | session |
 | `universe <name>` | same as load: a universe registered in the portal | session |
-| `data <file>` | same as load: a local CSV or parquet | session |
+| `data add <file> [--name NAME] [--asof-col COL] \| list \| show <name> \| lineage <run>` | register, inspect, and trace local CSV/Parquet datasets | shell + session |
 | `project <module>` | same as load: a module with data and backtest_fn | session |
 
 ### Session
 
 | Command | Does | Where |
 |---|---|---|
+| `remote add <name> [url] \| list` | configure or list remote sync endpoints in .alphaengine/project.toml | shell + session |
+| `push [remote] [--dry-run] [--share-series]` | sync sealed studies, ledger runs, and ideas to quantOS (opt-in network) | shell + session |
+| `pull [remote]` | pull team runs and ideas from quantOS into the local ledger (read-only) | shell + session |
+| `plugin list` | list installed loader, method, and report template plugins | shell + session |
+| `shell` | open the interactive research shell with project completion and status | shell |
 | `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 |
@@ -375,6 +431,20 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `--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 |
+| `--since DATE` | filter project log to runs on or after YYYY-MM-DD |
+| `--verdict VERDICT` | filter project log by verdict (e.g. robust, marginal, likely_noise) |
+| `--asof-col COL` | as-of column name or cutoff date for look-ahead checks in data add |
+| `--json` | emit a versioned v1.0 JSON result envelope to stdout |
+| `--stdin` | read an upstream JSON result envelope from standard input |
+| `--kill-if RULE` | kill rule for a hypothesis, e.g. 'DSR < 0.9' |
+| `--format FMT` | output format for report memo: md or pdf (default md) |
+| `--dry-run` | print the exact sync payload without making a network call |
+| `--live FILE` | live return series CSV to compare against a recorded backtest run |
+| `--interval SECONDS` | polling interval in seconds for watch (default 1.0) |
+| `--cycles N` | number of polling cycles for watch before exiting (0 means continuous) |
 
 ### Examples
 
@@ -387,11 +457,17 @@ alphaengine stress
 alphaengine overlap
 alphaengine size
 alphaengine monitor
+alphaengine init
+alphaengine init --name momentum
 alphaengine demo
 alphaengine process
 alphaengine process ou
 alphaengine runs
 alphaengine runs --limit 50
+alphaengine log
+alphaengine log --family momentum --verdict likely_noise
+alphaengine show HEAD
+alphaengine diff run_a run_b
 alphaengine gaps
 alphaengine tonight
 alphaengine tonight --budget 5
@@ -401,12 +477,34 @@ alphaengine commands
 alphaengine run screen_universe --universe sp500
 alphaengine run size_position --data returns.csv
 alphaengine run validate_study --project research.momentum
+alphaengine run examples/screen_validate_size.yaml
+alphaengine rerun HEAD
+alphaengine watch examples/screen_validate_size.yaml
 alphaengine seal study.json
+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
+alphaengine idea new "Cross-sectional momentum holds" --kill-if "DSR < 0.9" --family momentum
+alphaengine idea list
+alphaengine idea status idea_1 testing
+alphaengine idea show idea_1
 alphaengine run screen_universe --thesis momentum
+alphaengine data add prices.csv --name equities
+alphaengine data list
+alphaengine data show equities
+alphaengine data lineage HEAD
+alphaengine remote add quantos
+alphaengine remote add quantos https://qosai.app
+alphaengine push --dry-run
+alphaengine push
+alphaengine pull
+alphaengine plugin list
+alphaengine shell
 alphaengine logout
 alphaengine logout --purge
 alphaengine version

alphaengine-1.1.0/docs/plugins.md

@@ -0,0 +1,60 @@
+# Authoring AlphaEngine Plugins (`alphaengine.plugins`)
+
+AlphaEngine discovers plugins through standard Python package entry points under the group `"alphaengine.plugins"`.
+
+Three plugin kinds are supported:
+
+1. **`loader`**: Reads external data formats or backtest artifacts (for example, the built-in `quantconnect`, `vectorbt`, and `csv` loaders).
+2. **`method`**: Runs a statistical validation or diagnostic function and returns a versioned `v1.0` JSON result envelope (or a `figures` dictionary that AlphaEngine wraps into an envelope).
+3. **`template`**: Renders a study or project run into a custom report or memo (for example, `committee_memo`).
+
+Inspect installed plugins at any time with:
+
+```bash
+ae plugin list
+```
+
+---
+
+## Minimal Example
+
+### 1. Write your plugin module (`my_ae_plugin.py`)
+
+```python
+from alphaengine.plugins import PluginSpec
+
+
+def tail_ratio_diagnostic(returns: list[float], *, n_trials: int = 1) -> dict:
+    """95th-percentile gain divided by 5th-percentile loss magnitude."""
+    import numpy as np
+
+    arr = np.asarray(returns, dtype=float)
+    q95 = float(np.quantile(arr, 0.95))
+    q05 = abs(float(np.quantile(arr, 0.05)))
+    ratio = round(q95 / max(q05, 1e-9), 4)
+    return {
+        "tail_ratio": ratio,
+        "n_trials": n_trials,
+        "n_trials_source": "asserted",
+        "verdict": "robust" if ratio >= 1.2 else "marginal",
+    }
+
+
+def register() -> PluginSpec:
+    return PluginSpec(
+        name="tail_ratio",
+        kind="method",
+        description="95th/5th percentile tail ratio diagnostic",
+        fn=tail_ratio_diagnostic,
+        source="my-ae-plugin",
+    )
+```
+
+### 2. Declare the entry point in `pyproject.toml`
+
+```toml
+[project.entry-points."alphaengine.plugins"]
+tail_ratio = "my_ae_plugin:register"
+```
+
+After `pip install -e .`, `ae plugin list` will display `tail_ratio` under `method`, and `run_method_plugin("tail_ratio", returns)` will execute it and return a standard `v1.0` result envelope.

alphaengine-1.1.0/docs/project-format.md

@@ -0,0 +1,79 @@
+# AlphaEngine Project On-Disk Format (`v1.0`)
+
+**Format Version:** `1.0` (`PROJECT_FORMAT_VERSION = "1.0"`)
+
+AlphaEngine stores a local research workspace inside a `.alphaengine/` directory at the root of your project, discovered by walking up from the current working directory (the same way `git` locates `.git/`). Outside a project directory, every CLI command and Python function behaves as a standalone call.
+
+No database process or third-party storage library is required: all state is plain TOML, append-only JSON Lines (`.jsonl`), and content-addressed JSON blobs named by their full 64-character SHA-256 digest.
+
+---
+
+## Directory Layout
+
+Running `ae init` (or `alphaengine init`) creates:
+
+```text
+.alphaengine/
+├── project.toml          # Project metadata and configured remotes
+├── ledger/
+│   ├── runs.jsonl        # Append-only run records (every command/step executed)
+│   └── trials.jsonl      # Append-only trial records across sweeps and ideas
+├── data/
+│   └── datasets.jsonl    # Append-only dataset registry and hygiene diagnostics
+├── studies/
+│   └── <id>.json         # Sealed Study artifacts (schema 1.2)
+├── ideas/
+│   └── ideas.jsonl       # Append-only hypothesis definitions and status transitions
+├── universes/
+│   └── <name>.json       # Local universe definitions
+└── objects/
+    └── <sha256>.json     # Content-addressed immutable JSON objects
+```
+
+---
+
+## 1. `project.toml`
+
+Stores the project's human-readable name, UTC creation timestamp, on-disk format version, and optional sync remotes:
+
+```toml
+# AlphaEngine local research project configuration
+name = "equity-momentum"
+created = "2026-10-24T18:00:00+00:00"
+schema_version = "1.0"
+
+[remotes]
+quantos = "https://alpha-backend-production-51df.up.railway.app"
+```
+
+---
+
+## 2. Content-Addressed Object Store (`objects/<sha256>.json`)
+
+Every structured record written to the ledger, dataset registry, or idea log is also serialized into canonical JSON:
+- Dictionary keys sorted lexicographically (`sort_keys=True`)
+- Compact separators (`(",", ":")`)
+- Finite floats rounded deterministically; non-finite values mapped to `null`
+- Encoded as UTF-8
+
+The 64-character hex SHA-256 of those bytes determines the file path `.alphaengine/objects/<sha256>.json`. Reading an object via `Project.get_object(sha256)` re-hashes the file on disk and raises `ValueError` if the content was modified.
+
+---
+
+## 3. Append-Only Logs (`.jsonl`)
+
+Each `.jsonl` file under `ledger/`, `data/`, and `ideas/` contains one UTF-8 JSON object per line, in chronological order:
+
+- **`ledger/runs.jsonl`**: Every command or pipeline step executed inside the project (`run_id`, `timestamp`, `command`, `idea_id`, `family`, `params_hash`, `dataset_hashes`, `n_trials`, `n_trials_source`, `cumulative_trials`, `figures`, `verdict`, `engine_version`, `object_sha256`).
+- **`ledger/trials.jsonl`**: Per-trial entries (`run_id`, `idea_id`, `family`, `index`, `params_hash`, `sharpe`, `failed`, `timestamp`).
+- **`data/datasets.jsonl`**: Registered local datasets (`name`, `path`, `sha256`, `format`, `n_rows`, `start_date`, `end_date`, `columns`, `checks`, `registered_at`, `object_sha256`).
+- **`ideas/ideas.jsonl`**: Hypothesis creation and status updates (`idea_id`, `thesis`, `family`, `kill_if`, `status`, `created_at`, `updated_at`, `object_sha256`).
+
+---
+
+## 4. Discovery Rule
+
+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.

alphaengine-1.1.0/docs/result-format.md

@@ -0,0 +1,89 @@
+# AlphaEngine Result Envelope (`v1.0`) & Declarative Pipelines
+
+**Envelope Schema Version:** `1.0` (`ENVELOPE_SCHEMA_VERSION = "1.0"`)
+
+Every AlphaEngine CLI command can emit a structured JSON result envelope with `--json` and read an upstream envelope from standard input with `--stdin`.
+
+```bash
+ae screen --data prices.csv --json | ae validate --stdin --json | ae size --stdin --json
+```
+
+---
+
+## 1. JSON Result Envelope Schema (`v1.0`)
+
+```json
+{
+  "schema_version": "1.0",
+  "engine_version": "1.0.3",
+  "run_id": "run_a1b2c3d4e5f6",
+  "timestamp": "2026-10-24T18:30:00+00:00",
+  "command": "screen_universe",
+  "idea_id": "idea_01",
+  "family": "cross_sectional_momentum",
+  "params_hash": "8f2a9c...",
+  "dataset_hashes": [
+    "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+  ],
+  "n_trials": 60,
+  "n_trials_source": "derived_from_universe",
+  "cumulative_trials": 60,
+  "project_trials": 60,
+  "verdict": "ranked",
+  "figures": {
+    "universe_size": 60,
+    "n_evaluated": 60,
+    "n_passing": 60,
+    "n_insufficient": 0,
+    "cumulative_trials": 60,
+    "project_trials": 60
+  },
+  "context": {
+    "data_path": "prices.csv",
+    "project_module": null,
+    "top_symbol": "SYM00",
+    "shortlist": ["SYM00", "SYM07", "SYM14"],
+    "returns": [0.0012, -0.0034, 0.0041]
+  }
+}
+```
+
+### Field Reference
+
+| Field | Type | Description |
+|---|---|---|
+| `schema_version` | `string` | Envelope format version (`"1.0"`). |
+| `engine_version` | `string` | AlphaEngine package version (`__version__`). |
+| `run_id` | `string` | Unique run identifier (`run_<12-hex>`). |
+| `timestamp` | `string` | ISO-8601 UTC timestamp when the run completed. |
+| `command` | `string` | Canonical command or workflow name executed. |
+| `idea_id` | `string \| null` | Linked hypothesis id (`--idea`), if attached. |
+| `family` | `string` | Strategy or experiment family used for cumulative trial counting. |
+| `params_hash` | `string` | 64-hex SHA-256 of the run's input parameters. |
+| `dataset_hashes` | `list[string]` | 64-hex SHA-256 digests of the input datasets. |
+| `n_trials` | `int \| null` | Trial count for this individual run (`null` when `"not_recorded"`). |
+| `n_trials_source` | `string` | Provenance of `n_trials` (`derived_from_grid`, `asserted`, `monte_carlo`, `not_recorded`, etc.). |
+| `cumulative_trials` | `int` | Accumulated trial count across all project runs on the same `idea_id` or `family`. |
+| `project_trials` | `int` | Total trials accumulated across the entire `.alphaengine/` project. |
+| `verdict` | `string \| null` | Statistical or diagnostic verdict (`robust`, `marginal`, `likely_noise`, `clean`, `sized`, etc.; `null` when refused). |
+| `figures` | `object` | Computed scalar figures and bounded tables (never > 512 elements). |
+| `context` | `object` | Local pipe handoff context (`top_symbol`, `shortlist`, `returns`, `data_path`) consumed when piping into `--stdin`. |
+
+---
+
+## 2. Declarative Pipelines (`ae run pipeline.yaml`)
+
+Multi-step research recipes can be declared in YAML and executed with `ae run <pipeline.yaml>`. Each step receives the upstream envelope and writes its own run record to `.alphaengine/ledger/runs.jsonl`.
+
+```yaml
+name: momentum-validation-pipeline
+family: equity_momentum
+steps:
+  - command: diagnose
+  - command: screen
+    inputs:
+      rank_by: return_pct
+      top_n: 5
+  - command: validate
+  - command: size
+```

alphaengine-1.1.0/examples/process_stress_monitor.yaml

@@ -0,0 +1,15 @@
+# Example 2: Process Calibration -> Stress -> Monitor Pipeline
+# Run with: ae run examples/process_stress_monitor.yaml
+name: process-stress-monitor
+family: ou_mean_reversion
+steps:
+  - command: process
+    dgp: ou
+    inputs:
+      n_paths: 80
+  - command: stress
+    inputs:
+      turnover: 0.15
+  - command: monitor
+    inputs:
+      tolerances: '{"max_drawdown_pct": 25.0, "var_pct": 4.0}'

alphaengine-1.1.0/examples/screen_validate_size.yaml

@@ -0,0 +1,12 @@
+# Example 1: Screen -> Validate -> Size Pipeline
+# Run with: ae run examples/screen_validate_size.yaml
+name: screen-validate-size
+family: cross_sectional_momentum
+steps:
+  - command: diagnose
+  - command: screen
+    inputs:
+      rank_by: return_pct
+      top_n: 5
+  - command: validate
+  - command: size