alphaengine 0.10.0__tar.gz → 1.0.0__tar.gz

{alphaengine-0.10.0 → alphaengine-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 0.10.0
+Version: 1.0.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

{alphaengine-0.10.0 → alphaengine-1.0.0}/src/alphaengine/_version.py

@@ -113,9 +113,28 @@ is what a changed figure costs. The API may still move underneath it.
 # at unit capital, so a loss on the first bar counts. Grinold alpha is empty
 # when no volatility is supplied, instead of treating every name as vol 1.
 # Breadth does not imply an IR until the names are declared independent or a
-# mean correlation is supplied.
-#
-# The same release answers a later question from the session record, and
-# builds a portfolio (hierarchical risk parity, or risk parity when asked)
-# from the loaded returns. Those two add no figure to the goldens.
-__version__ = "0.10.0"
+# mean correlation is supplied. The same release answers a later question
+# from the session record, and builds a portfolio (hierarchical risk parity,
+# or risk parity when asked) from the loaded returns. Those two add no
+# figure to the goldens.
+#
+# 0.11.0 MOVES THE CASH RATE, ON PURPOSE. An omitted rate is the H.15
+# 3-month Treasury constant maturity, investment basis, 4.21% as of
+# 2026-10-06 (DGS3MO). It is a pinned print, not a download. Pass 0 for
+# excess of zero. Sharpe, Sortino, the deflated Sharpe, and PSR versus a
+# Sharpe of zero all move because the excess is no longer the raw return.
+# The five-trial golden crosses from marginal to likely_noise (0.5090 to
+# 0.427). sr0 moves slightly because its sampling-error floor depends on
+# the Sharpe. Drawdown, total return, geometric CAGR, volatility, and PBO
+# do not use the rate and stay. HAC lags are the Newey-West automatic rule,
+# so a factor t-stat on a short sample uses fewer than five lags and reports
+# the lag it chose. A close below $1.50 is still a price when the path is
+# calm. The cointegration screen reports Benjamini-Hochberg survivors;
+# the single-test flag remains on the pair as cointegrated_raw.
+#
+# 1.0.0 IS THE FIRST RELEASE. Everything through 0.11 was the beta: the
+# maths, the session, the airlock. 1.0 is the simulator. A sentence is a
+# stack of tool calls. The trace is the product, drawn while the tools
+# run. A report file is written on this machine only when the user
+# accepts it. The golden figures stay the 0.11 contract.
+__version__ = "1.0.0"

alphaengine-1.0.0/src/alphaengine/agent/sim.py

@@ -0,0 +1,241 @@
+"""The simulator. A sentence becomes a stack of tool calls, and the stack is the product.
+
+The model chooses the next tool. The tool is deterministic. The trace is what
+gets shown, and what a report file is made of when the user accepts one.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ..events import data_dir
+
+Invoke = Callable[[str, dict[str, Any]], dict[str, Any]]
+Think = Callable[[str], str]
+
+MAX_CALLS = 8
+
+TOOLS: tuple[tuple[str, str], ...] = (
+    ("profile", "what is wrong with the loaded file"),
+    ("align", "shared dates across stocks and macro; gaps counted, never filled"),
+    ("regime", "two-state Hamilton filter on one named series"),
+    ("price", "Black-Scholes price and Greeks for one contract"),
+    ("reprice", "full reprice of that contract under a spot and vol shock"),
+    ("correlation", "correlation of the loaded names"),
+    ("covariance", "covariance of the loaded names"),
+    ("cointegration", "cointegrated pairs, FDR survivors"),
+    ("portfolio", "weights; args.method is hrp or risk_parity"),
+    ("overlap", "one name against the equal-weight of the others; args.symbol"),
+    ("performance", "Sharpe, drawdown, and the cash rate on the loaded book"),
+    ("var", "value at risk on the loaded book"),
+    ("process", "fit ou, gbm, jump, or garch and stress it; args.dgp"),
+    ("workflow", "a portal workflow by name, when the account offers it"),
+    ("done", "stop. args.answer may cite only numbers the tools returned"),
+)
+
+_PROMPT = """You are the simulator inside alphaengine 1.0.
+
+The user asked a question. You answer it by calling tools, as many as the
+scenario needs, one per reply. The math is already written. You decide the
+order. You do not invent a figure.
+
+Question:
+@@QUESTION@@
+
+What is already loaded and already known:
+@@CONTEXT@@
+
+Tools:
+@@TOOLS@@
+
+Calls already made this turn:
+@@CALLS@@
+
+Reply with ONE JSON object and nothing else.
+{"tool": "<name>", "args": {}}
+{"tool": "done", "args": {"answer": "two or three sentences citing only tool numbers"}}
+"""
+
+
+@dataclass
+class Call:
+    tool: str
+    args: dict[str, Any]
+    figures: dict[str, Any] = field(default_factory=dict)
+    note: str = ""
+    error: str | None = None
+
+    def line(self) -> str:
+        if self.error:
+            return f"{self.tool}  refused  {self.error}"
+        return f"{self.tool}  {self.note}".rstrip()
+
+
+@dataclass
+class Trace:
+    """The run, as a stack. This is the artifact. The answer is the last line of it."""
+
+    question: str
+    calls: list[Call] = field(default_factory=list)
+    answer: str = ""
+    refused: bool = False
+
+    def render(self) -> str:
+        lines = ["alphaengine 1.0", f"question  {self.question}", ""]
+        if not self.calls:
+            lines.append("no tools ran")
+        for i, call in enumerate(self.calls, start=1):
+            lines.append(f"{i:02d}  {call.line()}")
+            for key, value in _public(call.figures).items():
+                lines.append(f"    {key}  {value}")
+        lines.append("")
+        if self.answer:
+            lines.append(self.answer)
+        return "\n".join(lines)
+
+    def save(self, directory: Path | None = None) -> Path:
+        folder = directory or (data_dir() / "reports")
+        folder.mkdir(parents=True, exist_ok=True)
+        stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+        path = folder / f"trace-{stamp}.txt"
+        path.write_text(self.render() + "\n", encoding="utf-8")
+        return path
+
+
+def run_tools(
+    question: str,
+    think: Think,
+    invoke: Invoke,
+    *,
+    context: str = "",
+    max_calls: int = MAX_CALLS,
+    on_call: Callable[[Call], None] | None = None,
+) -> Trace:
+    """Call tools until the model says done, or the stack is full."""
+    trace = Trace(question=question)
+    known: dict[str, float] = {}
+    for _ in range(max_calls):
+        raw = think(_fill(question, context, trace))
+        parsed = parse_call(raw)
+        if parsed is None:
+            trace.answer = "The model did not return a tool call."
+            trace.refused = True
+            return trace
+        name = str(parsed.get("tool") or "")
+        args = parsed.get("args") if isinstance(parsed.get("args"), dict) else {}
+        if name == "done":
+            answer = str(args.get("answer") or parsed.get("answer") or "").strip()
+            trace.answer = _guard_answer(answer, known, question)
+            trace.refused = trace.answer.startswith("Refused")
+            return trace
+        if name not in {tool for tool, _ in TOOLS}:
+            call = Call(tool=name or "?", args=args, error="that tool is not in the stack")
+            trace.calls.append(call)
+            if on_call:
+                on_call(call)
+            continue
+        try:
+            figures = invoke(name, args)
+        except Exception as exc:  # noqa: BLE001 — the stack records the failure
+            figures = {"error": str(exc)}
+        if not isinstance(figures, dict):
+            figures = {"result": figures}
+        error = str(figures["error"]) if figures.get("error") else None
+        note = str(figures.get("note") or _note(figures))
+        call = Call(tool=name, args=args, figures=_public(figures), note=note, error=error)
+        trace.calls.append(call)
+        known.update(_numbers(call.figures))
+        if on_call:
+            on_call(call)
+    trace.answer = f"Stopped after {max_calls} tool calls. The stack above is the run."
+    return trace
+
+
+def parse_call(text: str) -> dict[str, Any] | None:
+    start = text.find("{")
+    end = text.rfind("}")
+    if start < 0 or end <= start:
+        return None
+    try:
+        obj = json.loads(text[start : end + 1])
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(obj, dict) or "tool" not in obj:
+        return None
+    return obj
+
+
+def _fill(question: str, context: str, trace: Trace) -> str:
+    calls = "\n".join(call.line() for call in trace.calls) if trace.calls else "none yet"
+    tools = "\n".join(f"- {name}: {purpose}" for name, purpose in TOOLS)
+    return (
+        _PROMPT.replace("@@QUESTION@@", question)
+        .replace("@@CONTEXT@@", context or "nothing loaded yet")
+        .replace("@@TOOLS@@", tools)
+        .replace("@@CALLS@@", calls)
+    )
+
+
+def _public(figures: dict[str, Any]) -> dict[str, Any]:
+    """Scalars and short lists. A path is not a figure."""
+    out: dict[str, Any] = {}
+    for key, value in figures.items():
+        if str(key).startswith("_"):
+            continue
+        if isinstance(value, dict):
+            continue
+        if isinstance(value, (list, tuple)):
+            if len(value) > 12:
+                continue
+            out[str(key)] = list(value)
+            continue
+        if isinstance(value, float) and not math.isfinite(value):
+            continue
+        out[str(key)] = value
+    return out
+
+
+def _note(figures: dict[str, Any]) -> str:
+    bits = []
+    for key, value in _public(figures).items():
+        if key in {"method", "note"}:
+            continue
+        bits.append(f"{key} {value}")
+        if len(bits) == 4:
+            break
+    return "  ".join(bits)
+
+
+def _numbers(figures: dict[str, Any]) -> dict[str, float]:
+    found: dict[str, float] = {}
+
+    def walk(node: Any, prefix: str) -> None:
+        if isinstance(node, bool):
+            return
+        if isinstance(node, (int, float)) and math.isfinite(float(node)):
+            found[prefix or "n"] = float(node)
+            return
+        if isinstance(node, dict):
+            for key, value in node.items():
+                walk(value, f"{prefix}.{key}" if prefix else str(key))
+
+    walk(figures, "")
+    return found
+
+
+def _guard_answer(answer: str, known: dict[str, float], question: str) -> str:
+    if not answer:
+        return "The stack above is the run."
+    from .answer import UncitedFigure, check_citations
+
+    try:
+        check_citations(answer, known, question)
+    except UncitedFigure as exc:
+        return f"Refused. {exc}"
+    return answer

{alphaengine-0.10.0 → alphaengine-1.0.0}/src/alphaengine/client/executor.py

@@ -562,7 +562,9 @@ class StepExecutor:
             "verdict": out.get("verdict"),
             "n_trials": n_trials,
             "n_trials_source": source,
-            "risk_free_rate": out.get("risk_free_rate", 0.0),
+            "risk_free_rate": out.get("risk_free_rate"),
+            "risk_free_rate_source": out.get("risk_free_rate_source"),
+            "risk_free_rate_as_of": out.get("risk_free_rate_as_of"),
         }
         # Kept so `emit.study` can carry the verdict this run actually produced
         # rather than deriving it a second time. Two derivations of one figure

{alphaengine-0.10.0 → alphaengine-1.0.0}/src/alphaengine/core/__init__.py

@@ -47,6 +47,7 @@ from .process import (
     ou_simulate,
 )
 from .profile import profile_data
+from .rates import TREASURY_BILL_AS_OF, TREASURY_BILL_RATE, TREASURY_BILL_SERIES
 from .risk import compute_var_cvar
 from .screen import screen_universe
 from .series_shapes import series_values
@@ -72,6 +73,9 @@ __all__ = [
     "cpcv_score",
     # performance and risk
     "performance_report",
+    "TREASURY_BILL_RATE",
+    "TREASURY_BILL_AS_OF",
+    "TREASURY_BILL_SERIES",
     "compute_var_cvar",
     # simulation and scoring
     "run_backtest",

{alphaengine-0.10.0 → alphaengine-1.0.0}/src/alphaengine/core/backtest.py

@@ -488,7 +488,13 @@ def _regime_attribution(trades: list, regime_series: dict) -> dict:
 
 
 def _attribution(
-    bt: dict, returns: list, prices, factor_returns, regime_series, risk_free_rate: float, not_computed: dict
+    bt: dict,
+    returns: list,
+    prices,
+    factor_returns,
+    regime_series,
+    risk_free_rate: float | None,
+    not_computed: dict,
 ) -> dict:
     """MAE/MFE + factor + regime attribution. Each leg is OPTIONAL and pure: it
     runs only when its caller-supplied input is present, else names itself in
@@ -521,7 +527,7 @@ def _attribution(
     return attribution
 
 
-def _cost_report(bt: dict, perf, risk_free_rate: float) -> dict | None:
+def _cost_report(bt: dict, perf, risk_free_rate: float | None) -> dict | None:
     """Turnover + net-of-cost vs gross Sharpe from the sim's cost bookkeeping.
 
     The equity curve is ALREADY net of slippage + commission + impact (they are
@@ -578,7 +584,7 @@ def score_backtest(
     *,
     n_trials: int | None = None,
     n_trials_source: str | None = None,
-    risk_free_rate: float = 0.0,
+    risk_free_rate: float | None = None,
     periods_per_year: int = 252,
     benchmark_returns: list | None = None,
     pnl_matrix=None,

{alphaengine-0.10.0 → alphaengine-1.0.0}/src/alphaengine/core/factors.py

@@ -2,8 +2,8 @@
 Risk, factor decomposition over supplied portfolio + factor return streams.
 
 Lifted (math-identical) from backend/quant/factors.compute_multi_factor_loadings,
-with the FRED rfr fetch and quant.limits import removed: the caller supplies the
-risk-free rate (default 0, excess of zero, not a Treasury bill) and the VIF
+with the FRED rfr fetch and quant.limits import removed: an omitted cash
+rate is the pinned H.15 print in ``core.rates``, not a download, and the VIF
 threshold is inlined. OLS
 with HAC standard errors (statsmodels) gives factor betas, alpha, t-stats, R²,
 and a multicollinearity diagnostic (VIF).
@@ -28,10 +28,10 @@ import math
 import numpy as np
 import statsmodels.api as sm
 
+from .rates import cash_rate, rate_fields
 from .trace import record
 
 VIF_MAX_THRESHOLD = 10.0
-_DEFAULT_RFR = 0.0
 
 
 def _clean(val):
@@ -68,6 +68,15 @@ def _compute_vif(X: np.ndarray, factor_names: list[str]) -> dict[str, float]:
     return vifs
 
 
+def _hac_lags(n: int) -> int:
+    """Newey-West (1994) automatic lag: floor(4 * (T/100)^(2/9)), at least 1.
+
+    A fixed 5 lags is a daily-sample habit. The same regression on a monthly
+    panel does not want five months of overlap.
+    """
+    return max(1, int(4.0 * (n / 100.0) ** (2.0 / 9.0)))
+
+
 def _model_label(factor_names: list[str]) -> str:
     core_set = set(factor_names)
     if {"market", "size", "value", "profitability", "low_vol", "momentum"}.issubset(core_set):
@@ -91,13 +100,14 @@ def decompose_factors(
     (annualized %), factor betas + t-stats, R²/adj-R², residual vol, and a VIF
     multicollinearity diagnostic.
 
-    The default rate is 0, the same as ``performance_report``: excess of zero,
-    not a bill. Pass the annual rate explicitly when the study uses one.
-    ``factors_are_excess`` is true for Ken French-style factors, which are
-    already above cash, so the rate is subtracted from the portfolio only.
-    Set it false when the factors are total returns. Alpha is the intercept
-    times ``periods_per_year``, an arithmetic annualization, not a CAGR.
-    HAC lags stay at 5, which is a daily-sample assumption paired with 252.
+    An omitted rate is the pinned H.15 3-month Treasury, the same bill as
+    ``performance_report``. Pass ``0`` for excess of zero, or another annual
+    rate for a different print. ``factors_are_excess`` is true for Ken
+    French-style factors, which are already above cash, so the rate is
+    subtracted from the portfolio only. Set it false when the factors are
+    total returns. Alpha is the intercept times ``periods_per_year``, an
+    arithmetic annualization, not a CAGR. HAC lags follow the Newey-West
+    automatic rule and the chosen lag is reported.
     """
     factor_names = list(factor_returns.keys())
     if not factor_names:
@@ -107,8 +117,9 @@ def decompose_factors(
     if min_len < 30:
         return {"error": "Need 30+ observations"}
 
-    rfr = float(risk_free_rate) if risk_free_rate is not None else _DEFAULT_RFR
+    rfr, _, _ = cash_rate(risk_free_rate)
     ppy = max(int(periods_per_year), 1)
+    hac_lags = _hac_lags(min_len)
     y = np.array(portfolio_returns[-min_len:], dtype=float)
     rf_per = rfr / ppy
     y_excess = y - rf_per
@@ -124,7 +135,7 @@ def decompose_factors(
         high_vif = [f for f, v in vifs.items() if math.isfinite(v) and v > VIF_MAX_THRESHOLD]
 
     X_const = sm.add_constant(X)
-    model = sm.OLS(y_excess, X_const).fit(cov_type="HAC", cov_kwds={"maxlags": 5})
+    model = sm.OLS(y_excess, X_const).fit(cov_type="HAC", cov_kwds={"maxlags": hac_lags})
 
     betas = {}
     tstats = {}
@@ -158,11 +169,12 @@ def decompose_factors(
         "residual_vol": _clean(round(float(np.std(model.resid, ddof=1) * np.sqrt(ppy) * 100), 2)),
         "residual_vol_ddof": 1,
         "n_observations": int(min_len),
-        "risk_free_rate": round(rfr, 4),
+        **rate_fields(risk_free_rate),
         "periods_per_year": ppy,
         "factors_are_excess": bool(factors_are_excess),
         "alpha_annualization": "arithmetic",
-        "hac_maxlags": 5,
+        "hac_maxlags": hac_lags,
+        "hac_rule": "newey_west_1994",
         "model": _model_label(factor_names),
         "vifs": {k: _clean(round(v, 2)) if math.isfinite(v) else None for k, v in vifs.items()},
         "high_vif_factors": high_vif,

alphaengine-1.0.0/src/alphaengine/core/market.py

@@ -0,0 +1,154 @@
+"""Read a loaded book as stocks and macro series that share a calendar.
+
+Gaps stay gaps. A missing print is counted, not carried forward, because a
+filled macro series is a series the file did not contain.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from .relations import _looks_like_prices
+from .series_shapes import series_values
+
+# FRED-style names a macro file actually uses. A ticker is not in this set.
+_MACRO = frozenset(
+    {
+        "dff",
+        "fedfunds",
+        "sofr",
+        "dgs1mo",
+        "dgs3mo",
+        "dgs6mo",
+        "dgs1",
+        "dgs2",
+        "dgs5",
+        "dgs7",
+        "dgs10",
+        "dgs20",
+        "dgs30",
+        "t10y2y",
+        "unrate",
+        "payems",
+        "cpi",
+        "cpiaucsl",
+        "pce",
+        "pcepilfe",
+        "gdp",
+        "gdpc1",
+        "indpro",
+        "vix",
+        "vixcls",
+        "mortgage30us",
+        "umcsent",
+        "walcl",
+    }
+)
+
+
+def series_kind(name: str, values: list[float]) -> str:
+    """`macro`, `price`, or `series`. The name wins when it is a known macro print."""
+    key = "".join(ch for ch in name.lower() if ch.isalnum())
+    if key in _MACRO or key.startswith("dgs"):
+        return "macro"
+    if values and _looks_like_prices(values):
+        return "price"
+    return "series"
+
+
+def _dated(series: Any) -> tuple[dict[str, float] | None, list[float]]:
+    """A `{date: value}` mapping keeps its dates. A list does not grow any."""
+    if isinstance(series, dict):
+        out: dict[str, float] = {}
+        for key, value in series.items():
+            try:
+                number = float(value)
+            except (TypeError, ValueError):
+                continue
+            if number == number:  # not NaN
+                out[str(key)] = number
+        if out:
+            return out, [out[k] for k in sorted(out)]
+    values, _dates = series_values(series)
+    if values.ndim != 1:
+        return None, []
+    clean = [float(v) for v in values.tolist() if np.isfinite(v)]
+    return None, clean
+
+
+def describe_market(data: Any) -> dict:
+    """What is loaded: how many names, which are macro, which are prices, whether dates exist."""
+    if not isinstance(data, dict) or not data:
+        n = len(data) if isinstance(data, (list, tuple)) else 0
+        return {"n_names": 1 if n else 0, "n_obs": n, "dates_supplied": False, "kind": "series"}
+    macro: list[str] = []
+    prices: list[str] = []
+    other: list[str] = []
+    dated = 0
+    shortest = None
+    for name, series in data.items():
+        if str(name) in {"returns", "pnl", "book_returns", "signal", "prices"}:
+            continue
+        mapping, values = _dated(series)
+        if not values:
+            continue
+        if mapping is not None:
+            dated += 1
+        kind = series_kind(str(name), values)
+        bucket = {"macro": macro, "price": prices}.get(kind, other)
+        bucket.append(str(name))
+        shortest = len(values) if shortest is None else min(shortest, len(values))
+    names = macro + prices + other
+    return {
+        "n_names": len(names),
+        "n_macro": len(macro),
+        "n_price": len(prices),
+        "n_other": len(other),
+        "dates_supplied": dated == len(names) and dated > 0,
+        "n_dated": dated,
+        "min_obs": shortest or 0,
+        "macro": macro[:12],
+        "prices": prices[:12],
+    }
+
+
+def align_market(data: Any) -> dict:
+    """The dates every supplied series actually shares. Missing prints are counted, not filled."""
+    if not isinstance(data, dict) or not data:
+        return {"error": "load a file of named series first", "n_common": 0}
+    dated: dict[str, dict[str, float]] = {}
+    undated: list[str] = []
+    for name, series in data.items():
+        if str(name) in {"returns", "pnl", "book_returns", "signal", "prices"}:
+            continue
+        mapping, values = _dated(series)
+        if mapping is None:
+            if values:
+                undated.append(str(name))
+            continue
+        dated[str(name)] = mapping
+    if len(dated) < 1:
+        return {
+            "error": "these series have no dates, so a calendar cannot be shared",
+            "n_undated": len(undated),
+            "dates_supplied": False,
+        }
+    common = set.intersection(*(set(series) for series in dated.values()))
+    union = set.union(*(set(series) for series in dated.values()))
+    ordered = sorted(common)
+    gaps = {name: len(union - set(series)) for name, series in dated.items()}
+    kinds = {name: series_kind(name, list(series.values())) for name, series in dated.items()}
+    return {
+        "n_names": len(dated),
+        "n_common": len(ordered),
+        "start": ordered[0] if ordered else None,
+        "end": ordered[-1] if ordered else None,
+        "n_macro": sum(1 for kind in kinds.values() if kind == "macro"),
+        "n_price": sum(1 for kind in kinds.values() if kind == "price"),
+        "gaps": {name: count for name, count in gaps.items() if count},
+        "n_undated": len(undated),
+        "dates_supplied": True,
+        "names": list(dated)[:24],
+    }