alphaengine 0.9.5__tar.gz → 1.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 0.9.5
+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
@@ -253,7 +253,7 @@ from alphaengine.core import ou_calibrate, garch_calibrate, dgp_stress, grinold_
 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
+a = grinold_alpha(panel, ic=0.05, vols=vols)  # alpha stays here; missing vols are not treated as 1
 ```
 
 ---
@@ -337,6 +337,7 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `correlation` | the correlation of every loaded name with every other name | session |
 | `covariance` | the sample covariance of every loaded name with every other name | session |
 | `cointegration` | which loaded names are cointegrated | session |
+| `portfolio` | weights for the names already loaded | session |
 | `universe <name>` | same as load: a universe registered in the portal | session |
 | `data <file>` | same as load: a local CSV or parquet | session |
 | `project <module>` | same as load: a module with data and backtest_fn | session |

{alphaengine-0.9.5 → alphaengine-1.0.0}/README.md

@@ -208,7 +208,7 @@ from alphaengine.core import ou_calibrate, garch_calibrate, dgp_stress, grinold_
 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
+a = grinold_alpha(panel, ic=0.05, vols=vols)  # alpha stays here; missing vols are not treated as 1
 ```
 
 ---
@@ -292,6 +292,7 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `correlation` | the correlation of every loaded name with every other name | session |
 | `covariance` | the sample covariance of every loaded name with every other name | session |
 | `cointegration` | which loaded names are cointegrated | session |
+| `portfolio` | weights for the names already loaded | session |
 | `universe <name>` | same as load: a universe registered in the portal | session |
 | `data <file>` | same as load: a local CSV or parquet | session |
 | `project <module>` | same as load: a module with data and backtest_fn | session |

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

@@ -98,4 +98,43 @@ is what a changed figure costs. The API may still move underneath it.
 # is filed for the portal. check_overlap keeps that universe: one named symbol
 # against the equal-weight of the others. The correlation and beta are the
 # same numbers; the step now also names the candidate and the book.
-__version__ = "0.9.5"
+#
+# 0.10.0 MOVES ONE GOLDEN, ON PURPOSE. Parametric VaR is
+# max(0, -mean*h + z*std*sqrt(h)). The 0.9 figure was z*std*sqrt(h), so the
+# pinned seed goes 1.91 -> 1.84. Historical VaR and CVaR scale the same way:
+# the mean over the horizon, the shock over its square root. At one day a
+# negative percentile is still its absolute value. Daily vol is unchanged.
+# Deflated Sharpe, PBO, and the performance golden stay: the default cash
+# rate is 0, excess of zero, not a bill. The factor regression used to assume
+# 4% when the caller passed nothing; it now uses 0, and reports that, plus
+# whether the factors were already excess and that alpha is an arithmetic
+# annualization. A supplied dollar equity curve is no longer read as a return
+# by subtracting 1 from its last mark. A drawdown built from returns starts
+# 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.
+#
+# 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.9.5 → alphaengine-1.0.0}/src/alphaengine/cli.py

@@ -1670,13 +1670,22 @@ def _drive(run: Any, *, quiet: bool = False) -> None:
 
 
 def _publish_panel(session: Any, result: dict[str, Any], *, thesis_id: str | None = None) -> None:
-    """Hand the matrix or the pair table to the portal. A missing route is not a failure."""
+    """Hand a matrix, a pair table, or portfolio weights to the portal.
+
+    A missing route is not a failure. The result is already on this machine.
+    """
     if session is None or not hasattr(session, "file_panel"):
         return
     from .client.executor import _guard
-    from .core.relations import portal_figures
 
-    figures = portal_figures(result)
+    if result.get("kind") == "portfolio":
+        from .core.portfolio import portfolio_figures
+
+        figures = portfolio_figures(result)
+    else:
+        from .core.relations import portal_figures
+
+        figures = portal_figures(result)
     try:
         _guard(figures)
     except ValueError as exc:
@@ -1720,6 +1729,28 @@ def _print_cross(
     return 0
 
 
+def _print_portfolio(
+    data: Any,
+    *,
+    session: Any = None,
+    thesis_id: str | None = None,
+    method: str = "hrp",
+) -> int:
+    """One-shot portfolio. The session path can also ask for risk parity."""
+    from .core.portfolio import build_portfolio
+
+    try:
+        result = build_portfolio(data, method=method)
+    except ValueError as exc:
+        say(red(str(exc)))
+        return 2
+    say(f"  {result['method']}  {result['n_assets']} names  Ledoit-Wolf covariance")
+    for row in (result.get("rows") or [])[:8]:
+        say(f"  {row['name']}  {row['weight']}")
+    _publish_panel(session, result, thesis_id=thesis_id)
+    return 0
+
+
 def _overlap_payload(data: Any, symbol: str) -> dict[str, Any] | None:
     """Candidate plus the equal-weight of the other loaded names, or None."""
     from .core.relations import overlap_against_the_rest
@@ -1749,6 +1780,13 @@ def cmd_run(args: argparse.Namespace) -> int:
             say(red(str(exc)))
             return 2
         return _print_cross(data, kind, session=session)
+    if str(args.workflow).lower().replace("-", "_") in ("portfolio", "allocate"):
+        try:
+            data, _fn = resolve_data(args, session)
+        except (ProjectError, ValueError) as exc:
+            say(red(str(exc)))
+            return 2
+        return _print_portfolio(data, session=session)
     symbol = getattr(args, "symbol", None)
     resolve_args = args
     if args.workflow == "check_overlap" and symbol:

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

@@ -470,12 +470,14 @@ class StepExecutor:
         # sampling across a trough understates the risk in exactly the
         # direction that flatters.
         best = _trial_column(result, result.best.index)
-        equity = np.cumprod(1.0 + np.asarray(best, dtype=float))
-        cum: list[float] = (equity - 1.0).tolist()
+        from ..core.performance import wealth_from_returns
+
+        wealth = wealth_from_returns(np.asarray(best, dtype=float))
+        cum: list[float] = (wealth[1:] - 1.0).tolist()
         figures["best_curve"] = [{"i": i, "v": round(v, 6)} for i, v in _bucketed(cum, CURVE_POINTS, _last)]
-        peak = np.maximum.accumulate(equity)
+        peak = np.maximum.accumulate(wealth)
         with np.errstate(divide="ignore", invalid="ignore"):
-            dd: list[float] = np.where(peak > 0, equity / peak - 1.0, 0.0).tolist()
+            dd: list[float] = np.where(peak > 0, wealth / peak - 1.0, 0.0)[1:].tolist()
         figures["drawdown_curve"] = [{"i": i, "v": round(v, 6)} for i, v in _bucketed(dd, CURVE_POINTS, min)]
         return figures
 
@@ -547,7 +549,12 @@ class StepExecutor:
             ws["verdict"] = figures
             return figures
 
-        out = deflated_sharpe(self._returns_column(ws), n_trials=n_trials)
+        rf_kwargs: dict[str, Any] = {}
+        if params.get("risk_free_rate") is not None:
+            rf_kwargs["risk_free_rate"] = float(params["risk_free_rate"])
+        if params.get("periods_per_year") is not None:
+            rf_kwargs["periods_per_year"] = int(params["periods_per_year"])
+        out = deflated_sharpe(self._returns_column(ws), n_trials=n_trials, **rf_kwargs)
         figures = {
             "deflated_sharpe": out.get("deflated_sharpe"),
             "psr_vs_zero": out.get("psr_vs_zero"),
@@ -555,6 +562,9 @@ class StepExecutor:
             "verdict": out.get("verdict"),
             "n_trials": n_trials,
             "n_trials_source": source,
+            "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
@@ -853,11 +863,17 @@ class StepExecutor:
         sweep = ws.get("sweep")
         if sweep is not None and n_trials is None:
             n_trials, source = int(sweep.n_trials), "derived_from_grid"
+        score_kwargs: dict[str, Any] = {}
+        if params.get("risk_free_rate") is not None:
+            score_kwargs["risk_free_rate"] = float(params["risk_free_rate"])
+        if params.get("periods_per_year") is not None:
+            score_kwargs["periods_per_year"] = int(params["periods_per_year"])
         scored = score_backtest(
             bt,
             n_trials=None if n_trials is None else int(n_trials),
             n_trials_source=source,
             cpcv=bool(params.get("cpcv")),
+            **score_kwargs,
         )
         ws["score"] = scored
         return {
@@ -874,6 +890,11 @@ class StepExecutor:
         sweep = ws.get("sweep")
         if sweep is not None and n_trials is None:
             n_trials = int(sweep.n_trials)
+        cpcv_kwargs: dict[str, Any] = {}
+        if params.get("risk_free_rate") is not None:
+            cpcv_kwargs["risk_free_rate"] = float(params["risk_free_rate"])
+        if params.get("periods_per_year") is not None:
+            cpcv_kwargs["periods_per_year"] = int(params["periods_per_year"])
         return dict(
             cpcv_score(
                 returns,
@@ -882,6 +903,7 @@ class StepExecutor:
                 purge=int(params.get("purge") or 1),
                 embargo=int(params.get("embargo") or 1),
                 n_trials=int(n_trials) if n_trials is not None else 1,
+                **cpcv_kwargs,
             )
         )
 
@@ -898,9 +920,13 @@ class StepExecutor:
         portfolio = _as_returns(data) or data.get("returns")
         if portfolio is None:
             raise UnsupportedOp("compute.factors found factor_returns but no portfolio returns.")
-        kwargs = {}
+        kwargs: dict[str, Any] = {}
         if params.get("risk_free_rate") is not None:
             kwargs["risk_free_rate"] = float(params["risk_free_rate"])
+        if params.get("periods_per_year") is not None:
+            kwargs["periods_per_year"] = int(params["periods_per_year"])
+        if params.get("factors_are_excess") is not None:
+            kwargs["factors_are_excess"] = bool(params["factors_are_excess"])
         return dict(decompose_factors(list(portfolio), data["factor_returns"], **kwargs))
 
     def _pairs(self, params: Figures, ws: Workspace) -> Figures:
@@ -1283,12 +1309,18 @@ class StepExecutor:
         ideal = params.get("ideal") if isinstance(params.get("ideal"), dict) else ws.get("alpha")
         if isinstance(ideal, dict) and not holdings:
             ideal = None
+        breadth_kwargs: dict[str, Any] = {}
+        if params.get("independent") is not None:
+            breadth_kwargs["independent"] = bool(params["independent"])
+        if params.get("mean_correlation") is not None:
+            breadth_kwargs["mean_correlation"] = float(params["mean_correlation"])
         return dict(
             breadth_ir(
                 ic=float(ic),
                 n_names=int(n_names or 0),
                 holdings=holdings,
                 ideal=ideal if isinstance(ideal, dict) else None,
+                **breadth_kwargs,
             )
         )
 

{alphaengine-0.9.5 → alphaengine-1.0.0}/src/alphaengine/client/session.py

@@ -515,11 +515,11 @@ class Session:
     ) -> Figures:
         """File a client-computed panel so the portal can draw it.
 
-        Correlation, covariance, and cointegration are not catalogue workflows.
-        Their matrix does not fit a `triangle` figure, so it travels here as
-        `figures.matrix` plus `figures.names`. A 404 means this portal has no
-        panels route yet: the maths already happened on this machine, and the
-        missing route must not fail that.
+        Correlation, covariance, cointegration, and a portfolio are not catalogue
+        workflows. A matrix travels as `figures.matrix` plus `figures.names`;
+        portfolio weights travel as rows. A 404 means this portal has no panels
+        route yet: the maths already happened on this machine, and the missing
+        route must not fail that.
         """
         from .._version import __version__
 

{alphaengine-0.9.5 → alphaengine-1.0.0}/src/alphaengine/commands.py

@@ -532,6 +532,23 @@ COMMANDS: tuple[Command, ...] = _question_commands() + (
         ),
         examples=("cointegration",),
     ),
+    Command(
+        verb="portfolio",
+        group="data",
+        args="",
+        scope="repl",
+        purpose="weights for the names already loaded",
+        body=(
+            "Hierarchical risk parity on a Ledoit-Wolf covariance of the loaded "
+            "returns. Say `portfolio risk parity` for equal risk contribution.\n\n"
+            "If this session already ran a correlation, covariance, or "
+            "cointegration, the book is the names that calculation kept, and "
+            "those readings stay attached so a later question can quote them. "
+            "The weights themselves come from the covariance, not from mixing "
+            "those readings into a second optimiser."
+        ),
+        examples=("portfolio", "portfolio risk parity"),
+    ),
     Command(
         verb="universe",
         group="data",