alphaengine 0.7.0__tar.gz → 0.8.0__tar.gz

{alphaengine-0.7.0 → alphaengine-0.8.0}/AGENTS.md

@@ -56,13 +56,16 @@ animated parameter-surface canvas at boot and while Working) plus
   that is a version bump (`_version.py`).
 - **Compute ops on the executor** include the 0.6 workflow set (`backtest`,
   `score_backtest`, `cpcv`, `factors`, `pairs`, `cointegrated_pairs`,
-  `walk_forward`, `book_overlap`) and the 0.7 CS / book set
+  `walk_forward`, `book_overlap`), the 0.7 CS / book set
   (`panel_transform`, `signal_icir`, `fama_macbeth`, `quantile_book`,
-  `ewma_cov`, `denoise_cov`, `hrp`, `risk_parity`, `vol_target`). Panels and
-  covariance matrices stay in the workspace; figures go over the wire. The
+  `ewma_cov`, `denoise_cov`, `hrp`, `risk_parity`, `vol_target`), and the
+  0.8 process / Grinold set (`ou_calibrate`, `ou_simulate`, `gbm_calibrate`,
+  `jump_calibrate`, `garch`, `dgp_stress`, `grinold_alpha`, `breadth_ir`,
+  `detone_cov`). Panels, covariance matrices, GARCH variance paths, OU paths
+  and alpha vectors stay in the workspace; figures go over the wire. The
   portal must offer an op in a workflow graph or it sits unused; the CLI
-  remains useful without them. Short names in a panel are skipped and counted,
-  they do not shrink the rest of the book.
+  `process` command runs the DGP stress offline without a portal. Short names
+  in a panel are skipped and counted, they do not shrink the rest of the book.
 - `sweep(..., jobs=N)` defaults to 1. Greater than 1 is opt-in and must keep
   trial index identity, including failures.
 - The `connectors` extra is lazy: parquet via `pyarrow`, HTTP via `httpx` to a

{alphaengine-0.7.0 → alphaengine-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 0.7.0
+Version: 0.8.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
@@ -60,17 +60,14 @@ Description-Content-Type: text/markdown
   <img src="https://img.shields.io/badge/deps-numpy%20%2B%20scipy-C4893A?style=flat-square" alt="Two dependencies: numpy and scipy">
 </p>
 
-<p align="center">
-  <img src="docs/assets/mark.png" alt="AlphaEngine mark" width="96">
-</p>
-
 ```bash
 pip install alphaengine
 alphaengine demo          # the whole offline half, no account, no data of your own
+alphaengine process       # fit a DGP to the demo walk and stress it
 ```
 
 <p align="center">
-  <img src="docs/assets/session.png" alt="The session canvas: a living parameter surface, then demo, login, load" width="92%">
+  <img src="docs/assets/session.png" alt="The session canvas: tracked ALPHAENGINE over a teal plateau and amber ridge, then your data never leaves." width="92%">
 </p>
 
 The session is the product. Sign in, load something, then ask:
@@ -196,6 +193,35 @@ distinction is the whole of the data boundary below.
 
 ---
 
+## What's new in 0.8.0
+
+Named processes, Grinold, and a frozen chart contract. Existing goldens
+(deflated Sharpe, PBO, performance, screen) are byte-identical. New figures
+are a public contract from this release. The study schema is **1.1**: optional
+`process` and `charts` fields; 1.0 studies still load.
+
+| You have | You get | Module |
+|---|---|---|
+| A spread or a close | OU / GBM / jump / GARCH(1,1) calibration, then Monte Carlo stress under that law | `core.process` |
+| An IC and a cross-section | Grinold alpha, breadth, transfer coefficient | `core.active` |
+| A return panel | Detoned covariance and a PCA variance-explained table | `core.covariance` |
+| Figures that already travel | `{kind, key, title}` hints a portal maps to a chart | `charts`, [figure contract](docs/figure_contract.md) |
+
+The terminal boot is the README banner: tracked `ALPHAENGINE`, the subtitle,
+a teal-left / amber-right mesh (plateau, valley, knife-edge ridge), and
+`your data never leaves.` `alphaengine process` fits a DGP offline, no account.
+
+```python
+from alphaengine.core import ou_calibrate, garch_calibrate, dgp_stress, grinold_alpha
+
+ou = ou_calibrate(spread)            # kappa, theta, half_life; or not mean-reverting
+g = garch_calibrate(returns)         # omega, alpha, beta, persistence in (0, 1)
+s = dgp_stress(close, dgp="ou")      # n_trials = n_paths, source monte_carlo
+a = grinold_alpha(panel, ic=0.05)    # alpha vector stays here; scalars travel
+```
+
+---
+
 ## What's new in 0.7.0
 
 The daily modelling morning, and the overnight book, without a third
@@ -237,6 +263,7 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | Command | Does | Where |
 |---|---|---|
 | `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 |
 | `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 |
@@ -320,6 +347,8 @@ alphaengine overlap
 alphaengine size
 alphaengine monitor
 alphaengine demo
+alphaengine process
+alphaengine process ou
 alphaengine runs
 alphaengine runs --limit 50
 alphaengine gaps
@@ -423,8 +452,11 @@ diffable, and versioned so it still parses in two years.
 | `alphaengine.core.panel` | cross-sectional rank, z-score, winsorize, neutralize |
 | `alphaengine.core.signals` | IC, ICIR, quantile returns, decay |
 | `alphaengine.core.cross_section` | Fama-MacBeth, quantile book with turnover |
-| `alphaengine.core.covariance` | EWMA, Ledoit-Wolf, Marchenko-Pastur denoise, detone |
-| `alphaengine.core.allocate` | HRP, risk parity, vol target |
+| `alphaengine.core.covariance` | EWMA, Ledoit-Wolf, Marchenko-Pastur denoise, detone, variance explained |
+| `alphaengine.core.allocate` | HRP, risk parity, vol target (EWMA or GARCH) |
+| `alphaengine.core.process` | OU, GBM, jumps, GARCH(1,1), DGP stress |
+| `alphaengine.core.active` | Grinold alpha, breadth, transfer coefficient |
+| `alphaengine.charts` | frozen `{kind, key, title}` hints; see [figure contract](docs/figure_contract.md) |
 | `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 |
@@ -518,6 +550,22 @@ Management* 42(1), 13 to 28.
 Fama, E. F., and MacBeth, J. D. (1973). "Risk, Return, and Equilibrium:
 Empirical Tests." *Journal of Political Economy* 81(3), 607 to 636.
 
+**Ornstein-Uhlenbeck / Vasicek**
+Vasicek, O. (1977). "An Equilibrium Characterization of the Term Structure."
+*Journal of Financial Economics* 5(2), 177 to 188.
+
+**GARCH(1,1)**
+Bollerslev, T. (1986). "Generalized Autoregressive Conditional
+Heteroskedasticity." *Journal of Econometrics* 31(3), 307 to 327.
+
+**Jump-diffusion**
+Merton, R. C. (1976). "Option Pricing When Underlying Stock Returns Are
+Discontinuous." *Journal of Financial Economics* 3(1-2), 125 to 144.
+
+**The fundamental law of active management**
+Grinold, R. C., and Kahn, R. N. (2000). *Active Portfolio Management.* 2nd ed.
+McGraw-Hill.
+
 **Downside deviation**
 Sortino, F. A., and Price, L. N. (1994). "Performance Measurement in a Downside
 Risk Framework." *Journal of Investing* 3(3), 59 to 64.

{alphaengine-0.7.0 → alphaengine-0.8.0}/README.md

@@ -18,17 +18,14 @@
   <img src="https://img.shields.io/badge/deps-numpy%20%2B%20scipy-C4893A?style=flat-square" alt="Two dependencies: numpy and scipy">
 </p>
 
-<p align="center">
-  <img src="docs/assets/mark.png" alt="AlphaEngine mark" width="96">
-</p>
-
 ```bash
 pip install alphaengine
 alphaengine demo          # the whole offline half, no account, no data of your own
+alphaengine process       # fit a DGP to the demo walk and stress it
 ```
 
 <p align="center">
-  <img src="docs/assets/session.png" alt="The session canvas: a living parameter surface, then demo, login, load" width="92%">
+  <img src="docs/assets/session.png" alt="The session canvas: tracked ALPHAENGINE over a teal plateau and amber ridge, then your data never leaves." width="92%">
 </p>
 
 The session is the product. Sign in, load something, then ask:
@@ -154,6 +151,35 @@ distinction is the whole of the data boundary below.
 
 ---
 
+## What's new in 0.8.0
+
+Named processes, Grinold, and a frozen chart contract. Existing goldens
+(deflated Sharpe, PBO, performance, screen) are byte-identical. New figures
+are a public contract from this release. The study schema is **1.1**: optional
+`process` and `charts` fields; 1.0 studies still load.
+
+| You have | You get | Module |
+|---|---|---|
+| A spread or a close | OU / GBM / jump / GARCH(1,1) calibration, then Monte Carlo stress under that law | `core.process` |
+| An IC and a cross-section | Grinold alpha, breadth, transfer coefficient | `core.active` |
+| A return panel | Detoned covariance and a PCA variance-explained table | `core.covariance` |
+| Figures that already travel | `{kind, key, title}` hints a portal maps to a chart | `charts`, [figure contract](docs/figure_contract.md) |
+
+The terminal boot is the README banner: tracked `ALPHAENGINE`, the subtitle,
+a teal-left / amber-right mesh (plateau, valley, knife-edge ridge), and
+`your data never leaves.` `alphaengine process` fits a DGP offline, no account.
+
+```python
+from alphaengine.core import ou_calibrate, garch_calibrate, dgp_stress, grinold_alpha
+
+ou = ou_calibrate(spread)            # kappa, theta, half_life; or not mean-reverting
+g = garch_calibrate(returns)         # omega, alpha, beta, persistence in (0, 1)
+s = dgp_stress(close, dgp="ou")      # n_trials = n_paths, source monte_carlo
+a = grinold_alpha(panel, ic=0.05)    # alpha vector stays here; scalars travel
+```
+
+---
+
 ## What's new in 0.7.0
 
 The daily modelling morning, and the overnight book, without a third
@@ -195,6 +221,7 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | Command | Does | Where |
 |---|---|---|
 | `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 |
 | `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 |
@@ -278,6 +305,8 @@ alphaengine overlap
 alphaengine size
 alphaengine monitor
 alphaengine demo
+alphaengine process
+alphaengine process ou
 alphaengine runs
 alphaengine runs --limit 50
 alphaengine gaps
@@ -381,8 +410,11 @@ diffable, and versioned so it still parses in two years.
 | `alphaengine.core.panel` | cross-sectional rank, z-score, winsorize, neutralize |
 | `alphaengine.core.signals` | IC, ICIR, quantile returns, decay |
 | `alphaengine.core.cross_section` | Fama-MacBeth, quantile book with turnover |
-| `alphaengine.core.covariance` | EWMA, Ledoit-Wolf, Marchenko-Pastur denoise, detone |
-| `alphaengine.core.allocate` | HRP, risk parity, vol target |
+| `alphaengine.core.covariance` | EWMA, Ledoit-Wolf, Marchenko-Pastur denoise, detone, variance explained |
+| `alphaengine.core.allocate` | HRP, risk parity, vol target (EWMA or GARCH) |
+| `alphaengine.core.process` | OU, GBM, jumps, GARCH(1,1), DGP stress |
+| `alphaengine.core.active` | Grinold alpha, breadth, transfer coefficient |
+| `alphaengine.charts` | frozen `{kind, key, title}` hints; see [figure contract](docs/figure_contract.md) |
 | `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 |
@@ -476,6 +508,22 @@ Management* 42(1), 13 to 28.
 Fama, E. F., and MacBeth, J. D. (1973). "Risk, Return, and Equilibrium:
 Empirical Tests." *Journal of Political Economy* 81(3), 607 to 636.
 
+**Ornstein-Uhlenbeck / Vasicek**
+Vasicek, O. (1977). "An Equilibrium Characterization of the Term Structure."
+*Journal of Financial Economics* 5(2), 177 to 188.
+
+**GARCH(1,1)**
+Bollerslev, T. (1986). "Generalized Autoregressive Conditional
+Heteroskedasticity." *Journal of Econometrics* 31(3), 307 to 327.
+
+**Jump-diffusion**
+Merton, R. C. (1976). "Option Pricing When Underlying Stock Returns Are
+Discontinuous." *Journal of Financial Economics* 3(1-2), 125 to 144.
+
+**The fundamental law of active management**
+Grinold, R. C., and Kahn, R. N. (2000). *Active Portfolio Management.* 2nd ed.
+McGraw-Hill.
+
 **Downside deviation**
 Sortino, F. A., and Price, L. N. (1994). "Performance Measurement in a Downside
 Risk Framework." *Journal of Investing* 3(3), 59 to 64.

alphaengine-0.8.0/docs/figure_contract.md

@@ -0,0 +1,46 @@
+# Figure contract
+
+A figure that travels is a **named kind**, not a series. The executor attaches
+`charts: [{kind, key, title}]` hints. The portal maps `kind` + `key` to a
+component. Old portals ignore `charts` and still have the raw keys
+(`ic_by_period`, `best_curve`, …).
+
+No hint carries a nested series. Titles are one line, no em dash.
+
+Study schema **1.1** may also store `charts` and `process` on the artifact.
+Both are optional. A 1.0 study still loads.
+
+## Kinds
+
+| Kind | Payload | Draws as |
+|---|---|---|
+| `curve` | `{i, v}` | line |
+| `period` | `{p, ic}` or `{p, lambda}` | CS time series |
+| `band` | `{i, lo, mid, hi}` | fan / Monte Carlo quantile |
+| `hist` | `{edges, counts}` | histogram |
+| `cost` | `{bps, sharpe}` | cost ladder |
+| `scatter` | `{x, y}` | overlap |
+| `triangle` | `{a, b, v}` | covariance heatmap |
+| `rows` | bounded dict rows | table |
+| `quantiles` | `[float]` | bar |
+
+`i` is a position index into the original series, never a timestamp. Timestamps
+stay on the machine that holds the data.
+
+Lists longer than 512 are a series, not a figure, and the wire guard refuses
+them. Sketches (`path_sketch`, `vol_path`, `mean_path`, `band`) are bucketed
+below that cap before they travel.
+
+## Who emits what
+
+| Op | Typical hints |
+|---|---|
+| `compute.ou_calibrate` | `curve` / `path_sketch` |
+| `compute.ou_simulate` | `curve` / `mean_path`, `band` / `band` |
+| `compute.garch` | `curve` / `vol_path` |
+| `compute.dgp_stress` | `hist` / `sharpe_hist` |
+| `compute.denoise_cov` | `triangle` / `triangle`, `rows` / `variance_explained` |
+| `compute.detone_cov` | same |
+| `compute.grinold_alpha` | scalars only; the alpha vector stays in the workspace |
+
+The Python helper is `alphaengine.charts.chart(kind, key, title)`.

alphaengine-0.8.0/docs/workflows/evaluate_process.json

@@ -0,0 +1,18 @@
+{
+  "name": "evaluate_process",
+  "schema": "alphaengine.workflow/1",
+  "title": "what law describes this path?",
+  "reproducible": true,
+  "needs": ["data"],
+  "selection": "all",
+  "note": "Portal harness copies this. Agents still only index permitted; these ops sit unused until registered.",
+  "stages": [
+    {"op": "data.resolve"},
+    {"op": "compute.gbm_calibrate"},
+    {"op": "compute.ou_calibrate"},
+    {"op": "compute.jump_calibrate"},
+    {"op": "compute.garch"},
+    {"op": "compute.dgp_stress", "params": {"dgp": "gbm"}},
+    {"op": "emit.process_report"}
+  ]
+}

alphaengine-0.8.0/docs/workflows/research_week.json

@@ -0,0 +1,29 @@
+{
+  "name": "research_week",
+  "schema": "alphaengine.workflow/1",
+  "title": "gaps the modeling suite closes once the portal registers the ops",
+  "gaps": [
+    {
+      "question": "what law describes this path?",
+      "workflow": "evaluate_process",
+      "op": "compute.dgp_stress",
+      "cli": "alphaengine process"
+    },
+    {
+      "question": "where does it break under a named DGP?",
+      "workflow": "stress_study",
+      "stage": "dgp_stress",
+      "cli": "alphaengine process ou"
+    },
+    {
+      "question": "how much alpha does the IC imply?",
+      "workflow": "size_position",
+      "op": "compute.grinold_alpha"
+    },
+    {
+      "question": "is the book the market in disguise?",
+      "workflow": "size_position",
+      "op": "compute.detone_cov"
+    }
+  ]
+}

alphaengine-0.8.0/docs/workflows/stress_study.json

@@ -0,0 +1,14 @@
+{
+  "name": "stress_study",
+  "schema": "alphaengine.workflow/1",
+  "title": "where does it break?",
+  "note": "Additive DGP stage for the existing stress_study graph. Copy into the portal harness. The CLI spelling that does not wait on the portal is `alphaengine process` or `stress --input dgp=ou` once this stage is live.",
+  "add_stage": {
+    "id": "dgp_stress",
+    "op": "compute.dgp_stress",
+    "input": "dgp",
+    "default": "gbm",
+    "values": ["ou", "gbm", "jump", "garch"],
+    "after": "compute.cost_ladder"
+  }
+}

{alphaengine-0.7.0 → alphaengine-0.8.0}/src/alphaengine/_version.py

@@ -63,12 +63,10 @@ is what a changed figure costs. The API may still move underneath it.
 # doors, same refusals. The published artefact is a new wheel because 0.6.0
 # already left the building.
 #
-# 0.7.0 IS NEW PUBLIC FIGURES, AND A SIMPLER OS AROUND THEM. Existing DSR /
-# PBO / performance / screen goldens stay byte-identical. The artefact grew
-# the daily cross-section (rank, z-score, winsorize, neutralize, ICIR,
-# Fama-MacBeth, quantile book with turnover) and the overnight book
-# (EWMA / Ledoit-Wolf / Marchenko-Pastur covariance, HRP, risk parity, vol
-# target), plus a living parameter-surface canvas and one-verb `login` /
-# `load`. New numbers are a public contract from this release; old numbers
-# did not move.
-__version__ = "0.7.0"
+# 0.8.0 IS THE MODELING SUITE THE REST OF THE LIBRARY WAS MISSING. Existing
+# DSR / PBO / performance / screen goldens stay byte-identical. The artefact
+# grew named processes (OU, GBM, jumps, GARCH), DGP stress with an honest
+# Monte Carlo trial count, Grinold alpha / breadth / TC, a frozen chart
+# vocabulary, and a terminal boot that is the README banner in glyphs.
+# New figures are a public contract from this release; old numbers did not move.
+__version__ = "0.8.0"

alphaengine-0.8.0/src/alphaengine/charts.py

@@ -0,0 +1,56 @@
+"""Frozen chart vocabulary the portal draws from figures.
+
+A FIGURE IS A NAMED KIND, not a series. The executor attaches
+`charts: [{kind, key, title}]` hints. The portal maps kind+key to a component.
+Old portals ignore `charts` and still have the raw keys (`ic_by_period`,
+`best_curve`, ...).
+
+KINDS
+    curve     {i, v}              line
+    period    {p, ic|lambda}      CS time series
+    band      {i, lo, mid, hi}    fan / Monte Carlo quantile
+    hist      {edges, counts}     histogram
+    cost      {bps, sharpe}       cost ladder
+    scatter   {x, y}              overlap
+    triangle  {a, b, v}           covariance heatmap
+    rows      bounded dict rows   table
+    quantiles [float]             bar
+
+No hint may carry a nested series. Titles are one line, no em dash.
+"""
+
+from __future__ import annotations
+
+__all__ = ["CHART_KINDS", "chart", "charts"]
+
+CHART_KINDS = frozenset(
+    {
+        "curve",
+        "period",
+        "band",
+        "hist",
+        "cost",
+        "scatter",
+        "triangle",
+        "rows",
+        "quantiles",
+    }
+)
+
+
+def chart(kind: str, key: str, title: str) -> dict[str, str]:
+    """One portal hint. `kind` must be in CHART_KINDS."""
+    k = str(kind)
+    if k not in CHART_KINDS:
+        raise ValueError(f"unknown chart kind {k!r}; expected one of {sorted(CHART_KINDS)}")
+    return {"kind": k, "key": str(key), "title": str(title)}
+
+
+def charts(*items: dict[str, str]) -> list[dict[str, str]]:
+    """Hint list. Empty is allowed: the portal then uses raw keys only."""
+    out: list[dict[str, str]] = []
+    for item in items:
+        if not item:
+            continue
+        out.append(chart(item["kind"], item["key"], item["title"]) if "kind" in item else dict(item))
+    return out