alphaengine 1.0.2__tar.gz → 1.1.0__tar.gz

alphaengine-1.1.0/.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.1.0/.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.1.0/.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.1.0/.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.1.0/.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.1.0}/.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.1.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# 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.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
+- **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.1.0/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.1.0/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
+```