alphaengine 0.1.2__tar.gz → 0.2.0__tar.gz

{alphaengine-0.1.2 → alphaengine-0.2.0}/CHANGELOG.md

@@ -7,6 +7,96 @@ minor bump.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [Unreleased]
+
+## [0.2.0] - 2026-08-01
+
+**A COMPUTED VALUE CHANGED.** `score_backtest` can return a different `verdict`
+and a different `n_trials` for the same inputs. A study saved by 0.1.x whose
+scoring omitted `n_trials` will not reproduce here, deliberately — that is the
+whole point of the change, and it is why this is a minor bump under the
+versioning rule rather than a patch.
+
+### Added
+
+- **`alphaengine`, a terminal entry point.** The harness was complete on both
+  sides and nothing could start a run: the server held the workflow, this
+  package held the executor, and wiring them together was a Python script the
+  user had to write. `alphaengine run validate_study --project research.momentum`
+  is that script.
+
+  **Install it into your project venv, not with pipx.** `compute.*` ops execute
+  in-process against your own DataFrames, so tool isolation — the usual and
+  otherwise correct way to install a CLI — is the one thing that cannot work
+  here. You cannot have isolation and in-process data access, and the data not
+  moving is the point.
+
+  Your data and your simulator come from a PROJECT MODULE you write and we
+  import (`data`, `backtest_fn`), because that module already exists: it is the
+  notebook cell you were going to run anyway.
+
+  No new dependencies. Nothing to put a model key in.
+
+- **`emit.study` and `record.*` handlers** in `StepExecutor`. They were
+  vocabulary strings the server could issue and the client could not execute, so
+  a run that reached one could never produce the artifact it existed to produce.
+  `emit.study` takes the trial count FROM THE SWEEP THAT RAN, never from the
+  directive — a count arriving over the wire is one somebody upstream could have
+  chosen.
+
+### Fixed
+
+- **A step that cannot succeed no longer spins two hundred times.** The server
+  re-offers a failed step, which is right for a transient failure and
+  catastrophic for a permanent one: an op with no handler failed identically
+  every time, and `drive()` exhausted `max_steps` before raising an error that
+  named the wrong problem. Two identical failures now end the run with the op
+  and the reason.
+
+- **Separators no longer arrive as `�` on a Windows console.** The CLI uses `·`
+  and `→`, and `sys.stdout` there defaults to the console's legacy code page:
+  cp437 cannot encode either, and cp1252 encodes the mid-dot to a byte that
+  anything reading the log as UTF-8 renders as a replacement character.
+  `alphaengine run validate_study` printed `validate_study � https://...` on a
+  stock install.
+
+  The stream is now asked once what it can encode and the glyphs fall back to
+  ASCII when the answer is no — the same discipline already applied to colour,
+  which is suppressed when stdout is not a TTY. Forcing UTF-8 onto the stream
+  would override a choice the terminal made and trade one mojibake for another.
+  A separator is decoration; the words either side carry the meaning.
+
+### Changed
+
+- **`score_backtest(n_trials=...)` no longer defaults to 1. It defaults to
+  `None`, meaning NOT RECORDED, and an unrecorded count can no longer reach an
+  `edge` verdict.**
+
+  The old signature made omission the most generous answer arithmetic can
+  produce: no deflation at all, a fully populated `deflated_sharpe`, and — since
+  the moat only ever checked that the DSR was populated — the single cheapest
+  route to `edge`. The docstring advertising deflation as the overfitting moat
+  and the signature quietly undermining it shipped in the same function.
+
+  A deflated Sharpe is a ratio and `n_trials` is its denominator. Deflating by a
+  denominator nobody wrote down does not produce a weaker claim, it produces a
+  claim about nothing. So:
+
+  - `n_trials` comes back `null` rather than `1` when it was not supplied. "Not
+    recorded" and "I searched one configuration" are different facts and the
+    response no longer conflates them.
+  - `n_trials_source` is reported beside it — one of `derived_from_grid`,
+    `asserted`, `not_recorded`. A count that was COUNTED and a count that was
+    CLAIMED are different claims and every figure downstream rests on which.
+  - The DSR is still computed at an effective denominator of 1 and returned,
+    because the undeflated number is informative. It simply cannot clear a gate
+    alone.
+
+  **`sweep()` is unaffected in every respect.** It derives `n_trials` from the
+  grid as a property with no setter, so its source has always been
+  `derived_from_grid` and its figures are unchanged. If you were already passing
+  a trial count, nothing about your results moves either.
+
 ## [0.1.2] - 2026-07-31
 
 **No computed value changed.** Identical figures to 0.1.0 and 0.1.1.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alphaengine
-Version: 0.1.2
+Version: 0.2.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
@@ -59,6 +59,62 @@ r.verdict()    # deflated for the 9 trials that were actually run
 r.save()       # study.json, on your disk
 ```
 
+Everything above runs offline, with no account and no key.
+
+## Try it without writing anything
+
+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:
+
+```bash
+git clone https://github.com/quantOSC/alphaengine && cd alphaengine
+pip install -e .
+python -m examples.momentum
+```
+
+```
+trials     9  (derived_from_grid)
+verdict    marginal
+surface    ridge
+dsr        0.6352
+```
+
+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.**
+
+## Writing your own `backtest_fn`
+
+Two rules, both easy to get wrong the first time, and the reason the example
+above exists to copy:
+
+**Return a bare 1-D return series.** Not a dict, not a stats object — the
+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
+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
+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
+
+def backtest_fn(*, data, fast, slow):
+    close = data["close"]
+    return [
+        (close[i + 1] - close[i]) / close[i] * (1 if sma(close, fast, i) > sma(close, slow, i) else 0)
+        for i in range(WARMUP, len(close) - 1)
+    ]
+```
+
+`data` is whatever you want it to be — a DataFrame, a dict of series, an array.
+The package never inspects it and it never leaves your machine.
+
 ## What it does
 
 **Runs your parameter grid.** `sweep()` calls your backtest function once per
@@ -70,6 +126,13 @@ multiple testing need to know how many variants were tested. That number is
 almost never recorded, because nobody counts what they discarded. Running the
 grid makes it `len(grid)`, so it never has to be asked for or asserted.
 
+**Refuses to flatter an unrecorded count.** Since 0.2.0, omitting `n_trials`
+means `not_recorded` — not `1`. The trial count comes back `null`,
+`n_trials_source` travels beside it, and **a verdict of `edge` is unreachable
+without a recorded denominator.** A deflated Sharpe is a ratio; deflating by a
+denominator nobody wrote down does not produce a weaker claim, it produces a
+claim about nothing.
+
 **Shows you the neighbourhood.** The output is whether your result sits on a
 broad plateau or a knife edge, and where the robust region is centred. A single
 spike surrounded by failures is a result fitted to its own parameters.
@@ -78,6 +141,53 @@ 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 |
@@ -85,6 +195,8 @@ diffable, and versioned so it still parses in two years.
 | `alphaengine.core` | deflated Sharpe, PSR, PBO via CSCV, CPCV, minimum track record length, performance and risk statistics |
 | `alphaengine.sweep` | the grid runner and the sensitivity surface |
 | `alphaengine.study` | the study artifact and its schema |
+| `alphaengine.client` | the workflow client and the step executor |
+| `alphaengine.cli` | the `alphaengine` terminal entry point |
 
 Two runtime dependencies, numpy and scipy, both already present in a typical
 research environment. `import alphaengine` makes no network call and needs no
@@ -176,8 +288,18 @@ Statistical Association* 74(366), 427 to 431.
 
 The values these functions return are treated as a public contract. A study
 written today has to reproduce in two years, so a change to a computed value is
-a breaking change requiring a major version bump even when the signature is
-unchanged. CI fails if a pinned value moves.
+a breaking change requiring a version bump even when the signature is unchanged.
+While the leading digit is 0 the minor position carries that rule — 0.1 → 0.2 is
+what a changed figure costs — so every 0.2.x release produces identical numbers.
+CI fails if a pinned value moves.
+
+## 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 .
+```
 
 ## Licence
 

{alphaengine-0.1.2 → alphaengine-0.2.0}/README.md

@@ -18,6 +18,62 @@ r.verdict()    # deflated for the 9 trials that were actually run
 r.save()       # study.json, on your disk
 ```
 
+Everything above runs offline, with no account and no key.
+
+## Try it without writing anything
+
+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:
+
+```bash
+git clone https://github.com/quantOSC/alphaengine && cd alphaengine
+pip install -e .
+python -m examples.momentum
+```
+
+```
+trials     9  (derived_from_grid)
+verdict    marginal
+surface    ridge
+dsr        0.6352
+```
+
+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.**
+
+## Writing your own `backtest_fn`
+
+Two rules, both easy to get wrong the first time, and the reason the example
+above exists to copy:
+
+**Return a bare 1-D return series.** Not a dict, not a stats object — the
+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
+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
+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
+
+def backtest_fn(*, data, fast, slow):
+    close = data["close"]
+    return [
+        (close[i + 1] - close[i]) / close[i] * (1 if sma(close, fast, i) > sma(close, slow, i) else 0)
+        for i in range(WARMUP, len(close) - 1)
+    ]
+```
+
+`data` is whatever you want it to be — a DataFrame, a dict of series, an array.
+The package never inspects it and it never leaves your machine.
+
 ## What it does
 
 **Runs your parameter grid.** `sweep()` calls your backtest function once per
@@ -29,6 +85,13 @@ multiple testing need to know how many variants were tested. That number is
 almost never recorded, because nobody counts what they discarded. Running the
 grid makes it `len(grid)`, so it never has to be asked for or asserted.
 
+**Refuses to flatter an unrecorded count.** Since 0.2.0, omitting `n_trials`
+means `not_recorded` — not `1`. The trial count comes back `null`,
+`n_trials_source` travels beside it, and **a verdict of `edge` is unreachable
+without a recorded denominator.** A deflated Sharpe is a ratio; deflating by a
+denominator nobody wrote down does not produce a weaker claim, it produces a
+claim about nothing.
+
 **Shows you the neighbourhood.** The output is whether your result sits on a
 broad plateau or a knife edge, and where the robust region is centred. A single
 spike surrounded by failures is a result fitted to its own parameters.
@@ -37,6 +100,53 @@ 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 |
@@ -44,6 +154,8 @@ diffable, and versioned so it still parses in two years.
 | `alphaengine.core` | deflated Sharpe, PSR, PBO via CSCV, CPCV, minimum track record length, performance and risk statistics |
 | `alphaengine.sweep` | the grid runner and the sensitivity surface |
 | `alphaengine.study` | the study artifact and its schema |
+| `alphaengine.client` | the workflow client and the step executor |
+| `alphaengine.cli` | the `alphaengine` terminal entry point |
 
 Two runtime dependencies, numpy and scipy, both already present in a typical
 research environment. `import alphaengine` makes no network call and needs no
@@ -135,8 +247,18 @@ Statistical Association* 74(366), 427 to 431.
 
 The values these functions return are treated as a public contract. A study
 written today has to reproduce in two years, so a change to a computed value is
-a breaking change requiring a major version bump even when the signature is
-unchanged. CI fails if a pinned value moves.
+a breaking change requiring a version bump even when the signature is unchanged.
+While the leading digit is 0 the minor position carries that rule — 0.1 → 0.2 is
+what a changed figure costs — so every 0.2.x release produces identical numbers.
+CI fails if a pinned value moves.
+
+## 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 .
+```
 
 ## Licence
 

alphaengine-0.2.0/examples/momentum.py

@@ -0,0 +1,105 @@
+"""A project module you can actually run, so the CLI has something to point at.
+
+    alphaengine run validate_study --project examples.momentum
+
+A PROJECT MODULE IS NOT A CONFIG FILE. It is an ordinary Python module of yours
+that exposes two names:
+
+    data         whatever your backtest function takes — a DataFrame, a dict of
+                 series, an array. The harness never inspects it and it never
+                 leaves this machine.
+    backtest_fn  your simulator, called once per parameter combination as
+                 `backtest_fn(data=data, **params)`.
+
+That is the whole contract. It is deliberately the shape of the notebook cell
+you were going to write anyway, because the alternative — a YAML schema
+describing your strategy — means reimplementing your research in our vocabulary
+before you can find out whether it survives.
+
+TWO THINGS `backtest_fn` MUST DO, both easy to get wrong the first time:
+
+  1. RETURN A BARE 1-D RETURN SERIES. Not a dict, not a stats object — the
+     per-period returns themselves. `sweep` does `np.asarray(list(raw))`, so a
+     dict of results iterates its KEYS and fails on the first string.
+  2. RETURN THE SAME LENGTH FOR EVERY COMBINATION. PBO splits the trial matrix
+     into time blocks and compares configurations within each block, which is
+     only meaningful if they line up in time. Ragged output is refused rather
+     than truncated, because silently trimming would produce a confident number
+     over series that do not correspond. That is why `WARMUP` below is a
+     constant covering the slowest window in the grid, instead of each
+     configuration starting wherever its own window happens to fill.
+
+This one is a moving-average crossover on synthetic prices. The prices come from
+a fixed seed rather than a download, so the example runs offline, gives the same
+figures on every machine, and needs no data licence. It is a DEMONSTRATION OF
+THE WIRING, not a strategy: a crossover on a random walk has no edge, and the
+verdict at the end says so. That is the example working, not failing.
+"""
+
+from __future__ import annotations
+
+import random
+
+# Long enough to cover the slowest window in the documented grid (slow=200).
+# Every configuration starts here, so every return series is the same length.
+WARMUP = 200
+
+
+def _prices(n: int = 1200, seed: int = 7) -> list[float]:
+    """A synthetic close series. Fixed seed: the example must reproduce."""
+    rng = random.Random(seed)
+    px, out = 100.0, []
+    for _ in range(n):
+        px *= 1.0 + rng.gauss(0.0004, 0.011)
+        out.append(round(px, 4))
+    return out
+
+
+# What `--project examples.momentum` hands to the harness.
+data = {"close": _prices()}
+
+# The grid the README and the CLI examples use. Nine combinations, so a
+# derived trial count of exactly 9 — a number you can check by hand.
+GRID = {"fast": [5, 10, 20], "slow": [50, 100, 200]}
+
+
+def backtest_fn(*, data, fast: int = 10, slow: int = 50) -> list[float]:
+    """One moving-average crossover, long/flat, as a daily return series.
+
+    `fast >= slow` is a degenerate corner of the grid. It returns a flat series
+    of the right LENGTH rather than an empty one: a combination that fails is
+    still a combination that was tried, and dropping it would quietly shrink the
+    denominator every deflated figure downstream divides by.
+    """
+    close = data["close"]
+    n = len(close)
+
+    def sma(k: int, i: int) -> float:
+        return sum(close[i - k + 1 : i + 1]) / k
+
+    if fast >= slow or slow > WARMUP:
+        return [0.0] * (n - WARMUP - 1)
+
+    out: list[float] = []
+    position = 0
+    for i in range(WARMUP, n - 1):
+        position = 1 if sma(fast, i) > sma(slow, i) else 0
+        step = (close[i + 1] - close[i]) / close[i]
+        out.append(round(step * position, 8))
+    return out
+
+
+if __name__ == "__main__":
+    # `python -m examples.momentum` — the offline half. No server, no account,
+    # no network. This is the whole package working on its own.
+    from alphaengine import sweep
+
+    result = sweep(backtest_fn, GRID, data=data)
+    verdict = result.verdict()
+    surface = result.surface()
+
+    print(f"trials     {result.n_trials}  ({verdict.get('n_trials_source')})")
+    print(f"verdict    {verdict.get('verdict')}")
+    print(f"surface    {surface.get('shape')}")
+    dsr = verdict.get("deflated_sharpe")
+    print(f"dsr        {dsr if dsr is not None else 'not recorded'}")

{alphaengine-0.1.2 → alphaengine-0.2.0}/pyproject.toml

@@ -42,6 +42,19 @@ dependencies = [
     "scipy>=1.10",
 ]
 
+# THE TERMINAL ENTRY POINT. Deliberately adds nothing new: argparse from the
+# standard library, and the client's urllib transport. A CLI that dragged in a
+# TUI framework would break the two-dependency promise above on behalf of people
+# who may never run it.
+#
+# INSTALL THIS IN YOUR PROJECT VENV, NOT WITH pipx OR `uv tool install`.
+# `compute.*` ops execute in-process against your own DataFrames, so tool
+# isolation — the usual and otherwise correct way to install a CLI — is the one
+# thing that cannot work here. You cannot have isolation and in-process data
+# access, and the data not moving is the whole point.
+[project.scripts]
+alphaengine = "alphaengine.cli:main"
+
 [project.optional-dependencies]
 # Factor decomposition (OLS with HAC errors) and cointegration (ADF) need
 # statsmodels, which pulls pandas and patsy behind it. Kept OUT of the core so

{alphaengine-0.1.2 → alphaengine-0.2.0}/src/alphaengine/_version.py

@@ -12,4 +12,4 @@ While the leading digit is 0, the MINOR position carries that rule: 0.1 -> 0.2
 is what a changed figure costs. The API may still move underneath it.
 """
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"