alphaengine 0.2.0__tar.gz → 0.3.0__tar.gz

{alphaengine-0.2.0 → alphaengine-0.3.0}/.github/workflows/ci.yml

@@ -45,6 +45,12 @@ jobs:
       - run: ruff check src tests
       - run: ruff format --check src tests
       - run: mypy src
+      # THE FIFTH COPY GUARD. The command list lived in three hand-maintained
+      # places and none of them agreed: `--data` and `--universe` shipped and
+      # appeared in one. It is generated from `commands.py` now, and this fails
+      # the build when the README falls behind rather than letting a stale list
+      # quietly tell somebody a feature does not exist.
+      - run: python scripts/gen_docs.py --check
 
   # The numbers this library returns are a public contract once published: a
   # study written today has to reproduce in two years. This job exists to make

alphaengine-0.3.0/.gitignore

@@ -0,0 +1,30 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+.civenv/
+
+# CREDENTIALS. Nothing here was ignored, so a `.env` created while working on
+# this repo would have been committed to a PUBLIC repository with nothing to
+# stop it. Found in a sweep 2026-08-02; no secret was ever actually committed.
+.env
+.env.*
+*.pem
+*.key
+secrets.json
+credentials.json
+
+# Artifacts the package itself writes. `r.save()` drops study.json in the
+# working directory by default, so running the example in a clone leaves one
+# staged for the next `git add .`.
+study.json
+*.study.json

{alphaengine-0.2.0 → alphaengine-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alphaengine
-Version: 0.2.0
+Version: 0.3.0
 Summary: Validated research tooling for investment strategies: deflation, overfitting detection, and honest trial counts.
 Project-URL: Homepage, https://github.com/quantOSC/alphaengine
 Project-URL: Documentation, https://github.com/quantOSC/alphaengine#readme
@@ -41,49 +41,216 @@ Description-Content-Type: text/markdown
 
 # AlphaEngine
 
-Validated research tooling for investment strategies. Run a parameter search,
-get back the shape of the result and an honest read on whether it survives the
-number of things you tried.
+**The research loop, on your machine.** Ask what is worth looking at, whether it
+holds up, how much to hold, and whether anything has crossed a line. Your data
+never leaves.
 
 ```bash
 pip install alphaengine
+alphaengine demo          # the whole offline half, no account, no data of your own
 ```
 
-```python
-from alphaengine import sweep
+## What it answers
 
-r = sweep(backtest_fn, {"fast": [5, 10, 20], "slow": [50, 100, 200]}, data=prices)
+Eight questions, in the order a research week actually asks them. The command
+IS the question; only two of them need code of yours.
+
+| Ask | Command | Workflow | Needs |
+|---|---|---|---|
+| Can I trust this data? | `diagnose` | `diagnose_data` | prices |
+| What is worth a look? | `screen` | `screen_universe` | prices |
+| Does this signal carry information? | `signal` | `evaluate_signal` | a signal panel + prices |
+| Is this real, once you count the tries? | `validate` | `validate_study` | prices + your backtest |
+| Where does it break? | `stress` | `stress_study` | a return series |
+| Is it new, or my book again? | `overlap` | `check_overlap` | the candidate + the book |
+| How much should I hold? | `size` | `size_position` | a return series |
+| Still inside the lines? | `monitor` | `monitor_sleeve` | a return series |
+
+```bash
+alphaengine diagnose --data prices.csv     # before anything runs on it
+alphaengine screen --universe sp500
+alphaengine size --data returns.csv
+```
+
+**The refusals are the point.** A screen over a universe that mostly could not
+be measured is refused as a survivorship artifact rather than ranked. A size on
+a record shorter than its own minimum track length is refused outright, because
+a small position is still a claim and the caveat does not travel with it into a
+book. A monitor with no stated tolerances reports `unchecked` — never a green
+light. A stop exits 0: "this did not clear the bar" is the system working.
 
-r.surface()    # is the result a broad plateau or a single lucky configuration?
-r.verdict()    # deflated for the 9 trials that were actually run
-r.save()       # study.json, on your disk
+Or say it in plain English and let your own model pick:
+
+```bash
+alphaengine
+> which of my names are overbought on RSI?
 ```
 
-Everything above runs offline, with no account and no key.
+That second path is EXPLORATORY: the model chooses a workflow and then chooses
+each step from what the server permits. Two runs of the same question may
+differ, and the run says so. `run <workflow>` is SCRIPTED and reproducible.
+Both are legitimate; presenting one as the other is not.
+
+## The three rungs
+
+Each is useful without the one above it. The boot screen shows which are lit.
 
-## Try it without writing anything
+| Rung | What you need | What you get |
+|---|---|---|
+| **The maths** | nothing | Every statistic, offline, forever. No account. |
+| **Workflows** | a QuantOS `ae_live_` key | The loop end to end, with the record. |
+| **Ask anything** | your OWN model key | Plain English in. Runs under your account, not ours. |
 
-The repo ships a runnable project module, so you can see the whole offline half
-work before deciding whether any of this is for you:
+Nothing here stores a model key: it is read from your environment at call time
+and handed to the provider's own client. There is no field to put one in.
+
+## Getting your data in
+
+Three doors, and nothing is ever fetched on your behalf.
 
 ```bash
-git clone https://github.com/quantOSC/alphaengine && cd alphaengine
-pip install -e .
-python -m examples.momentum
+alphaengine run screen_universe --data prices.csv          # a local CSV
+alphaengine run screen_universe --universe sp500           # registered in the portal
+alphaengine run validate_study --project research.momentum # a module of yours
 ```
 
+`--data` reads three shapes, decided by the header and nothing else:
+
 ```
-trials     9  (derived_from_grid)
-verdict    marginal
-surface    ridge
-dsr        0.6352
+wide     date,AAPL,MSFT,NVDA      one column per name
+long     date,symbol,close        one row per name per day
+series   date,close               a single series, or one bare column of numbers
 ```
 
-That is a moving-average crossover on **synthetic prices from a fixed seed** —
-no download, no data licence, same numbers on every machine. It is a
-demonstration of the wiring, not a strategy. A crossover on a random walk has no
-edge, and the verdict says so rather than flattering it. **That is the example
-working, not failing.**
+A file it cannot place raises and names all three rather than guessing. A loader
+that guesses eventually guesses wrong on somebody's book, and the failure is not
+an error: it is a screen that ranked returns as prices and produced a shortlist
+nobody can tell is wrong.
+
+`--project` is the only door that can carry a **simulator**, because a simulator
+is code. That is why `validate_study` needs it — and `evaluate_signal` needs it
+for the scores it measures — while the rest run on prices alone.
+
+`--universe` brings the closes you stored with it in the portal. That is your own
+upload decrypted back to your own account, not us fetching market data, and the
+distinction is the whole of the data boundary below.
+
+## Command reference
+
+`alphaengine commands` prints this directory in the terminal, and
+`alphaengine commands run` expands any one of them.
+
+<!-- COMMANDS:START -->
+<!-- Generated by scripts/gen_docs.py from src/alphaengine/commands.py.
+     Do not edit by hand; run `python scripts/gen_docs.py --write`. -->
+
+### Get started
+
+| Command | Does | Where |
+|---|---|---|
+| `demo` | run the built-in example offline, with no account and no data | shell + session |
+| `workflows` | what the server offers, what each needs, and which reproduce | shell + session |
+| `key [quantos \| anthropic \| openai]` | enter a credential now, or see which rungs are unlocked | session |
+| `commands [verb]` | this directory, or one command in full | shell + session |
+
+### Do the work
+
+| Command | Does | Where |
+|---|---|---|
+| `diagnose` | can I trust this data? | shell + session |
+| `screen` | what is worth a look? | shell + session |
+| `signal` | does this signal carry information? | shell + session |
+| `validate` | is this real? | shell + session |
+| `stress` | where does it break? | shell + session |
+| `overlap` | is it new, or my book again? | shell + session |
+| `size` | how much? | shell + session |
+| `monitor` | still inside the lines? | shell + session |
+| `run <workflow>` | run one workflow exactly as written | 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 |
+
+### Bring your data
+
+| Command | Does | Where |
+|---|---|---|
+| `universe <name>` | load a universe you registered in the portal, with its closes | session |
+| `data <file.csv>` | load a local CSV without leaving the session | session |
+| `project <module>` | load `data` and `backtest_fn` from a module of yours | session |
+
+### Session
+
+| Command | Does | Where |
+|---|---|---|
+| `logout` | remove stored credentials from this machine | shell + session |
+| `version` | print the version | shell |
+| `help` | the short list | session |
+| `quit` | leave the session | session |
+
+### Data flags
+
+| Flag | What it takes |
+|---|---|
+| `--data FILE` | a local CSV. Wide (date,AAPL,MSFT), long (date,symbol,close), or one series. |
+| `--universe NAME` | a universe you registered in the portal, with the closes you stored. |
+| `--project MODULE` | a Python module. The only door that can carry a simulator. |
+
+### Flags
+
+| Flag | Does |
+|---|---|
+| `--url URL` | workflow server (default $QUANTOS_API_URL or the public API) |
+| `--key KEY` | portal-issued ae_live_ key (default $QUANTOS_API_KEY) |
+| `--project MODULE` | a module exposing `data` and `backtest_fn` |
+| `--data FILE` | a local CSV: wide, long, or a single series |
+| `--universe NAME` | a universe registered in the portal, with its stored closes |
+| `--symbol TICKER` | one name out of a loaded universe; its closes become the return series |
+| `--sleeve NAME` | the sleeve this run belongs to, and the budget it is bound by |
+| `--thesis ID` | a draft thesis to propose this run's shortlist as a sleeve for |
+| `--label TEXT` | what to call the artifact this run produces |
+| `--input K=V` | a workflow input; repeatable |
+| `--quiet` | only the result, no step narration |
+
+### Examples
+
+```bash
+alphaengine diagnose --universe <name>
+alphaengine screen --universe <name>
+alphaengine signal
+alphaengine validate
+alphaengine stress
+alphaengine overlap
+alphaengine size
+alphaengine monitor
+alphaengine demo
+alphaengine workflows
+alphaengine commands
+alphaengine run screen_universe --universe sp500
+alphaengine run size_position --data returns.csv
+alphaengine run validate_study --project research.momentum
+alphaengine logout
+alphaengine version
+```
+
+<!-- COMMANDS:END -->
+
+## The library, without the CLI
+
+The commands above are a wrapper. Everything they compute is importable, runs
+offline, and needs no account:
+
+```python
+from alphaengine import sweep
+
+r = sweep(backtest_fn, {"fast": [5, 10, 20], "slow": [50, 100, 200]}, data=prices)
+
+r.surface()  # is the result a broad plateau or a single lucky configuration?
+r.verdict()  # deflated for the 9 trials that were actually run
+r.save()  # study.json, on your disk
+```
+
+The trial count is **derived from the grid that ran**, never asserted. Omit it
+and it is recorded as `not_recorded` rather than defaulting to a flattering 1,
+and an unrecorded denominator cannot reach an `edge` verdict at all.
 
 ## Writing your own `backtest_fn`
 
@@ -102,7 +269,8 @@ correspond. In practice: pick a warm-up long enough for the slowest window in
 your grid and start every configuration there.
 
 ```python
-WARMUP = 200   # covers the slowest `slow` in the grid
+WARMUP = 200  # covers the slowest `slow` in the grid
+
 
 def backtest_fn(*, data, fast, slow):
     close = data["close"]
@@ -141,53 +309,6 @@ spike surrounded by failures is a result fitted to its own parameters.
 back, and a content hash of the data it ran on. Readable in a text editor,
 diffable, and versioned so it still parses in two years.
 
-## Running a workflow from the terminal
-
-The offline half above is complete on its own. A *workflow* adds a sequence — 
-what to run, in what order, and what stops the run — and that sequence lives on
-a QuantOS workflow server, so this part needs an account.
-
-```bash
-alphaengine version                                        # no account needed
-alphaengine workflows                                      # what your workspace offers
-alphaengine run validate_study --project examples.momentum
-```
-
-The run narrates itself, because a loop you cannot watch is a loop you cannot
-trust. The server names an op, this machine executes it and hands back figures:
-
-```
-validate_study · <your workflow server>
-  server →  compute.sweep
-  local  ·  done
-  server →  compute.deflated_sharpe
-  local  ·  done
-  server →  Stop: the surface is a ridge, not a plateau
-```
-
-`--project` names an ordinary module of yours exposing `data` and, if the
-workflow sweeps, `backtest_fn`. Authenticate with a key from the portal:
-
-```bash
-export QUANTOS_API_KEY=ae_live_...     # QUANTOS_API_URL for self-hosted or VPC
-```
-
-**A stop exits 0.** "This did not clear the bar" is the system working, not a
-broken build — a non-zero exit there would make every CI pipeline treat an
-honest refusal as a failure, which is exactly the pressure that gets honesty
-controls switched off. Only a run that could not execute a step exits non-zero.
-
-> **Install this into the venv you do research in — not with `pipx` or
-> `uv tool install`.** The compute steps execute in-process against your own
-> DataFrames, so tool isolation, which is normally the right way to install a
-> CLI, is the one thing that cannot work here. You cannot have isolation and
-> in-process data access, and your data not moving is the point.
-
-**No LLM dependency and no key field.** `AgentDriver` takes a callable, so you
-bring your own model by passing a function. There is nowhere in this tool to put
-a model key, ours or yours, and that is how "runs under your own account" is
-satisfied structurally rather than promised.
-
 ## What is in it
 
 | Module | Contents |
@@ -212,10 +333,10 @@ the PM who will act on it, `report()` sends the study — and only the study.
 import os
 from alphaengine import Study, sweep
 
-os.environ["QUANTOS_API_KEY"] = "ae_live_..."   # created in the portal
+os.environ["QUANTOS_API_KEY"] = "ae_live_..."  # created in the portal
 
 r = sweep(backtest_fn, grid, data=prices)
-r.save()                                        # yours, on your disk, always
+r.save()  # yours, on your disk, always
 
 Study.from_sweep(r, label="momentum, 9 configs").report()
 ```
@@ -293,12 +414,83 @@ While the leading digit is 0 the minor position carries that rule — 0.1 → 0.
 what a changed figure costs — so every 0.2.x release produces identical numbers.
 CI fails if a pinned value moves.
 
+## Installing: "command not found"
+
+The console script lives in your venv's `Scripts/` (Windows) or `bin/` (POSIX),
+which joins your PATH only while that venv is **activated**. A fresh install
+followed by `alphaengine` therefore says *command not found*, which reads as a
+broken install and is not one.
+
+```powershell
+.\.venv\Scripts\Activate.ps1     # Windows PowerShell
+source .venv/bin/activate        # macOS / Linux
+alphaengine
+```
+
+Or skip activation entirely — **`python -m alphaengine` always works**, because
+the interpreter that can import the package can always run it:
+
+```bash
+.venv/Scripts/python.exe -m alphaengine      # Windows, unactivated
+.venv/bin/python -m alphaengine              # POSIX, unactivated
+```
+
+This is the price of in-process data access, and it is the one cost we will not
+engineer around: a launcher that worked from anywhere would have to run in its
+own environment, which is exactly the isolation that makes `compute.*` unable to
+see your DataFrames.
+
+The run narrates itself, because a loop you cannot watch is a loop you cannot
+trust. The server names an op, this machine executes it and hands back figures:
+
+```
+validate_study · <your workflow server>
+  server →  compute.sweep
+  local  ·  done
+  server →  compute.deflated_sharpe
+  local  ·  done
+  server →  Stop: the surface is a ridge, not a plateau
+```
+
+`--project` names an ordinary module of yours exposing `data` and, if the
+workflow sweeps, `backtest_fn`. Authenticate with a key from the portal:
+
+```bash
+export QUANTOS_API_KEY=ae_live_...     # QUANTOS_API_URL for self-hosted or VPC
+```
+
+**A stop exits 0.** "This did not clear the bar" is the system working, not a
+broken build — a non-zero exit there would make every CI pipeline treat an
+honest refusal as a failure, which is exactly the pressure that gets honesty
+controls switched off. Only a run that could not execute a step exits non-zero.
+
+> **Install this into the venv you do research in — not with `pipx` or
+> `uv tool install`.** The compute steps execute in-process against your own
+> DataFrames, so tool isolation, which is normally the right way to install a
+> CLI, is the one thing that cannot work here. You cannot have isolation and
+> in-process data access, and your data not moving is the point.
+
+**No LLM dependency and no key field.** `AgentDriver` takes a callable, so you
+bring your own model by passing a function. There is nowhere in this tool to put
+a model key, ours or yours, and that is how "runs under your own account" is
+satisfied structurally rather than promised.
+
 ## Development
 
 ```bash
-python -m venv .venv && .venv/bin/pip install -e '.[factors]' pytest ruff
-.venv/bin/python -m pytest -q
-.venv/bin/python -m ruff check .
+python -m venv .venv && .venv/bin/pip install -e '.[dev,factors]'
+```
+
+CI runs five gates. Run all of them before pushing — `ruff check` and
+`ruff format` are different tools with different opinions, and passing one
+says nothing about the other:
+
+```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      # the frozen figures
 ```
 
 ## Licence