alphaengine 0.5.0__tar.gz → 0.6.1__tar.gz

alphaengine-0.6.1/AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+AlphaEngine is a pure-Python CLI + library (`alphaengine`) for validated quant
+research. There is no GUI; all interaction is via the terminal or
+`import alphaengine`.
+
+### Environment
+
+- Dependencies live in `.venv` (Python 3.12). Use `.venv/bin/<tool>` or
+  `source .venv/bin/activate`. The console script is `.venv/bin/alphaengine`.
+- Installed editable with `dev` and `factors` extras so statsmodels is present.
+
+### Lint / test / build / run
+
+- Lint: `.venv/bin/python -m ruff check src tests` and
+  `.venv/bin/python -m ruff format --check src tests`
+- Types: `.venv/bin/python -m mypy src`
+- Tests: `.venv/bin/python -m pytest` and
+  `.venv/bin/python -m pytest tests -m golden -q`
+- Docs guard: `.venv/bin/python scripts/gen_docs.py --check`
+  (regenerate with `--write`). A benign `SyntaxWarning: invalid escape sequence '\|'`
+  is pre-existing.
+- Offline app: `.venv/bin/alphaengine demo`
+
+### Non-obvious gotchas
+
+- **Three rungs.** `demo` and the importable library are fully offline. Workflow
+  CLI verbs (`diagnose`, `screen`, …, `run <workflow>`) need a portal
+  `ae_live_` key (`QUANTOS_API_KEY`). Plain-English mode also needs a **model**
+  key. Any OpenAI-compatible key works: Anthropic, OpenAI (`OPENAI_BASE_URL` for
+  gateways), Gemini, Groq, OpenRouter, Azure, or
+  `ALPHAENGINE_API_KEY`+`ALPHAENGINE_BASE_URL`. `alphaengine models` lists what
+  this machine can actually use. Keys may persist in
+  `~/.config/alphaengine/credentials.json` (mode 0600) if the user says yes at
+  `key <provider>`; env always wins. LLM keys are never sent to QuantOS.
+- **A stop / `marginal` verdict exits 0.** Only a step that could not execute
+  exits non-zero. Unauthenticated workflow calls exit 2.
+- **Data never leaves.** Executor and study-report guards refuse lists longer
+  than 512 by length. Model telemetry (choices, why, post-guard answers, prompt
+  hashes) may POST to `/api/harness/runs/{id}/events` when logged in; a 404 is
+  swallowed and the same allowlist is always written to
+  `~/.local/share/alphaengine/runs/<id>.jsonl`. Never send prompts, series, or
+  keys. `alphaengine trace` reads the local dump.
+- **Goldens are a public contract.** Do not "fix" a golden to land a speedup;
+  that is a version bump (`_version.py`).
+- **New compute ops** (`backtest`, `score_backtest`, `cpcv`, `factors`, `pairs`,
+  `cointegrated_pairs`, `walk_forward`, `book_overlap`) are on the executor.
+  The portal must offer them in a workflow graph or they sit unused; the CLI
+  remains useful without them.
+- `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
+  URL the caller names. `import alphaengine` must not import httpx.

{alphaengine-0.5.0 → alphaengine-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: alphaengine
-Version: 0.5.0
+Version: 0.6.1
 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
@@ -26,6 +26,7 @@ Requires-Dist: numpy>=1.24
 Requires-Dist: scipy>=1.10
 Provides-Extra: agents
 Requires-Dist: anthropic>=0.40; extra == 'agents'
+Requires-Dist: openai>=1.0; extra == 'agents'
 Provides-Extra: connectors
 Requires-Dist: httpx>=0.27; extra == 'connectors'
 Requires-Dist: pyarrow>=15.0; extra == 'connectors'
@@ -153,8 +154,11 @@ distinction is the whole of the data boundary below.
 | `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 |
-| `key [quantos \| anthropic \| openai]` | enter a credential now, or see which rungs are unlocked | session |
+| `key [quantos \| anthropic \| openai \| gemini \| groq \| azure \| openrouter \| gateway]` | enter a credential now, or see which rungs are unlocked | session |
 | `commands [verb]` | this directory, or one command in full | shell + session |
+| `models` | which model providers this machine can actually use | shell + session |
+| `model [<provider[:name]>]` | pin the model for this session, or show the pin | session |
+| `trace [run_id]` | local model/run events for a run, hashed prompts only | shell + session |
 
 ### Do the work
 
@@ -176,8 +180,9 @@ distinction is the whole of the data boundary below.
 
 | Command | Does | Where |
 |---|---|---|
+| `book [<name> \| status]` | show or load sleeves on the multi-strategy book | session |
 | `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 |
+| `data <file>` | load a local CSV or parquet without leaving the session | session |
 | `project <module>` | load `data` and `backtest_fn` from a module of yours | session |
 
 ### Session
@@ -210,6 +215,7 @@ distinction is the whole of the data boundary below.
 | `--label TEXT` | what to call the artifact this run produces |
 | `--input K=V` | a workflow input; repeatable |
 | `--quiet` | only the result, no step narration |
+| `--stream` | print the answer once the citation guard has passed |
 | `--limit N` | how many rows to show (default 25) |
 | `--budget N` | how many runs a night is worth (default 3) |
 
@@ -235,6 +241,8 @@ alphaengine commands
 alphaengine run screen_universe --universe sp500
 alphaengine run size_position --data returns.csv
 alphaengine run validate_study --project research.momentum
+alphaengine models
+alphaengine trace
 alphaengine logout
 alphaengine version
 ```

{alphaengine-0.5.0 → alphaengine-0.6.1}/README.md

@@ -112,8 +112,11 @@ distinction is the whole of the data boundary below.
 | `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 |
-| `key [quantos \| anthropic \| openai]` | enter a credential now, or see which rungs are unlocked | session |
+| `key [quantos \| anthropic \| openai \| gemini \| groq \| azure \| openrouter \| gateway]` | enter a credential now, or see which rungs are unlocked | session |
 | `commands [verb]` | this directory, or one command in full | shell + session |
+| `models` | which model providers this machine can actually use | shell + session |
+| `model [<provider[:name]>]` | pin the model for this session, or show the pin | session |
+| `trace [run_id]` | local model/run events for a run, hashed prompts only | shell + session |
 
 ### Do the work
 
@@ -135,8 +138,9 @@ distinction is the whole of the data boundary below.
 
 | Command | Does | Where |
 |---|---|---|
+| `book [<name> \| status]` | show or load sleeves on the multi-strategy book | session |
 | `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 |
+| `data <file>` | load a local CSV or parquet without leaving the session | session |
 | `project <module>` | load `data` and `backtest_fn` from a module of yours | session |
 
 ### Session
@@ -169,6 +173,7 @@ distinction is the whole of the data boundary below.
 | `--label TEXT` | what to call the artifact this run produces |
 | `--input K=V` | a workflow input; repeatable |
 | `--quiet` | only the result, no step narration |
+| `--stream` | print the answer once the citation guard has passed |
 | `--limit N` | how many rows to show (default 25) |
 | `--budget N` | how many runs a night is worth (default 3) |
 
@@ -194,6 +199,8 @@ alphaengine commands
 alphaengine run screen_universe --universe sp500
 alphaengine run size_position --data returns.csv
 alphaengine run validate_study --project research.momentum
+alphaengine models
+alphaengine trace
 alphaengine logout
 alphaengine version
 ```

{alphaengine-0.5.0 → alphaengine-0.6.1}/pyproject.toml

@@ -68,6 +68,7 @@ factors = [
 # Sharpe should not need an LLM dependency to get one.
 agents = [
     "anthropic>=0.40",
+    "openai>=1.0",
 ]
 # Pulling data from a provider the customer already pays for.
 connectors = [
@@ -178,5 +179,5 @@ ignore_missing_imports = true
 # import is an error, so this is the difference between a build that passes on a
 # machine that happens to have them and one that passes anywhere.
 [[tool.mypy.overrides]]
-module = ["scipy.*", "statsmodels.*"]
+module = ["scipy.*", "statsmodels.*", "pyarrow.*", "httpx"]
 ignore_missing_imports = true

{alphaengine-0.5.0 → alphaengine-0.6.1}/src/alphaengine/_version.py

@@ -44,4 +44,22 @@ is what a changed figure costs. The API may still move underneath it.
 # `tonight`. The record already knew which workflow closes each open gap and
 # nothing traversed those edges; these two read that derivation, so the terminal
 # can now answer "what have I NOT tried" and "what will run while I sleep".
-__version__ = "0.5.0"
+#
+# 0.6.0 IS THE SAME RULE READ AS A FEATURE RELEASE. No computed value moved.
+# The artefact grew a research OS around the maths that already shipped: any
+# BYOK model (Anthropic, OpenAI-compatible, Gemini, Groq, OpenRouter, Azure,
+# a private gateway), the workflow ops that were library-only (`backtest`,
+# CPCV, factors, pairs, walk-forward, book overlap), allowlisted traces that
+# stay on disk when the portal has no route, a session with history and slash
+# verbs, and a screen that paints the parameter surface it is judging.
+#
+# A new published wheel is a new thing people `pip install`. While the leading
+# digit is 0 the MINOR position carries that, the same way 0.5.0 carried a
+# surface change that left every figure byte-identical.
+#
+# 0.6.1 IS THE SCREEN, NOT THE MATHS. No computed value moved. The session is a
+# transcript now: a hue-cycling wait-star over a travelling plateau, cards for
+# what a step found, a composer instead of a dashboard. Same rungs, same
+# doors, same refusals. The published artefact is a new wheel because 0.6.0
+# already left the building.
+__version__ = "0.6.1"

{alphaengine-0.5.0 → alphaengine-0.6.1}/src/alphaengine/auth.py

@@ -55,7 +55,22 @@ __all__ = ["config_path", "load_stored", "save_key", "clear_stored", "apply_stor
 #: `QUANTOS_API_KEY` is ours. The provider keys are here because a user who has
 #: said "sign me in" means all of it, and leaving one of the three to be pasted
 #: every session defeats the point.
-MANAGED = ("QUANTOS_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY")
+MANAGED = (
+    "QUANTOS_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "OPENAI_API_KEY",
+    "GEMINI_API_KEY",
+    "GOOGLE_API_KEY",
+    "GROQ_API_KEY",
+    "OPENROUTER_API_KEY",
+    "AZURE_OPENAI_API_KEY",
+    "AZURE_OPENAI_ENDPOINT",
+    "ALPHAENGINE_API_KEY",
+    "ALPHAENGINE_BASE_URL",
+    "ALPHAENGINE_MODEL",
+    "ALPHAENGINE_PROVIDER",
+    "OPENAI_BASE_URL",
+)
 
 
 def config_path() -> Path:

alphaengine-0.6.1/src/alphaengine/book.py

@@ -0,0 +1,158 @@
+"""A multi-strategy book: named sleeves, figures, never an OMS.
+
+WHAT THIS IS
+    The overlap/size/monitor questions, asked of a STACK of return series rather
+    than one candidate vs one book series. A desk that runs six sleeves needs to
+    know how a seventh sits on the whole stack, and whether any sleeve is
+    already outside its lines.
+
+WHAT THIS IS NOT
+    Orders, shares, brokers, or target weights that become fills. `save_signals`
+    still files ticker/rank/score/weight. A book here is a research object.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+from .core.risk import compute_var_cvar
+from .core.stress import overlap_stats
+from .core.validation import min_track_record_length
+
+__all__ = ["Book", "MAX_SLEEVES"]
+
+#: A correlation matrix over 2000 names is a data export. Cap the book so the
+#: figures that leave it stay figures.
+MAX_SLEEVES = 16
+
+
+def _as_returns(values: Any) -> list[float]:
+    if isinstance(values, dict) and "returns" in values:
+        values = values["returns"]
+    return [float(x) for x in list(values)]
+
+
+@dataclass
+class Book:
+    """Named sleeves of return series, plus optional current weights."""
+
+    sleeves: dict[str, list[float]] = field(default_factory=dict)
+    weights: dict[str, float] = field(default_factory=dict)
+
+    def add(self, name: str, returns: Any, *, weight: float | None = None) -> None:
+        if len(self.sleeves) >= MAX_SLEEVES and name not in self.sleeves:
+            raise ValueError(f"a book holds at most {MAX_SLEEVES} sleeves; remove one first")
+        self.sleeves[str(name)] = _as_returns(returns)
+        if weight is not None:
+            self.weights[str(name)] = float(weight)
+
+    def drop(self, name: str) -> None:
+        self.sleeves.pop(name, None)
+        self.weights.pop(name, None)
+
+    @property
+    def names(self) -> list[str]:
+        return list(self.sleeves)
+
+    def combined_returns(self) -> list[float]:
+        """Equal-weight (or stated-weight) stack, aligned from the most recent end."""
+        if not self.sleeves:
+            return []
+        series = {k: np.asarray(v, dtype=float) for k, v in self.sleeves.items()}
+        n = min(int(a.size) for a in series.values())
+        if n <= 0:
+            return []
+        stacked = np.column_stack([a[-n:] for a in series.values()])
+        w = np.array([self.weights.get(k, 1.0) for k in series], dtype=float)
+        if float(w.sum()) == 0:
+            w = np.ones_like(w)
+        w = w / w.sum()
+        return [float(x) for x in (stacked @ w).tolist()]
+
+    def overlap_matrix(
+        self, candidate: Any | None = None, *, candidate_name: str = "candidate"
+    ) -> dict[str, Any]:
+        """Pairwise correlation/beta, bounded. Candidate optional."""
+        names = list(self.sleeves)
+        series = dict(self.sleeves)
+        if candidate is not None:
+            series[candidate_name] = _as_returns(candidate)
+            names = [candidate_name, *names]
+        names = names[:MAX_SLEEVES]
+        pairs: list[dict[str, Any]] = []
+        for i, a in enumerate(names):
+            for b in names[i + 1 :]:
+                stats = overlap_stats(series[a], series[b])
+                pairs.append(
+                    {
+                        "a": a,
+                        "b": b,
+                        "correlation": stats.get("correlation"),
+                        "beta_to_book": stats.get("beta_to_book"),
+                        "n_obs": stats.get("n_obs"),
+                    }
+                )
+        return {
+            "n_sleeves": len(names),
+            "names": names,
+            "pairs": pairs,
+        }
+
+    def residual_weight(self, name: str, *, target: float = 1.0) -> dict[str, Any]:
+        """How much of `target` is left after the sleeves already held.
+
+        Refuses rather than sizing small when the candidate record is shorter
+        than MinTRL — a small weight is still a claim.
+        """
+        if name not in self.sleeves:
+            raise KeyError(name)
+        returns = self.sleeves[name]
+        mintrl = min_track_record_length(returns)
+        if mintrl.get("error") or not mintrl.get("sufficient"):
+            return {
+                "name": name,
+                "refused": True,
+                "reason": "record_too_short",
+                "min_track_record_length": mintrl,
+            }
+        held = sum(self.weights.get(k, 0.0) for k in self.sleeves if k != name)
+        residual = max(0.0, float(target) - held)
+        risk = compute_var_cvar(returns)
+        return {
+            "name": name,
+            "refused": False,
+            "held_weight": round(held, 6),
+            "residual_weight": round(residual, 6),
+            "cvar": risk.get("cvar"),
+            "min_track_record_length": mintrl,
+        }
+
+    def monitor(self) -> dict[str, Any]:
+        """Per-sleeve status. Nothing checked never reads as all-clear."""
+        rows: list[dict[str, Any]] = []
+        for name, returns in self.sleeves.items():
+            if len(returns) < 2:
+                rows.append({"name": name, "status": "unchecked", "n_obs": len(returns)})
+                continue
+            risk = compute_var_cvar(returns)
+            mintrl = min_track_record_length(returns)
+            status = "ok" if mintrl.get("sufficient") else "undetermined"
+            rows.append(
+                {
+                    "name": name,
+                    "status": status,
+                    "n_obs": len(returns),
+                    "cvar": risk.get("cvar"),
+                    "sufficient": mintrl.get("sufficient"),
+                }
+            )
+        if not rows or any(r["status"] == "unchecked" for r in rows):
+            overall = "unchecked"
+        elif any(r["status"] != "ok" for r in rows):
+            overall = "undetermined"
+        else:
+            overall = "ok"
+        return {"overall": overall, "sleeves": rows, "n_sleeves": len(rows)}