alphaengine 0.9.4__tar.gz → 0.10.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 0.9.4
+Version: 0.10.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
 ```
 
 ---
@@ -334,6 +334,10 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `book [<name> \| status]` | show or load sleeves on the multi-strategy book | session |
 | `load <file \| module \| universe>` | a CSV, a project module, or a portal universe | session |
 | `thesis [<name> \| clear]` | choose a portal thesis for the next run | session |
+| `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.4 → alphaengine-0.10.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
 ```
 
 ---
@@ -289,6 +289,10 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `book [<name> \| status]` | show or load sleeves on the multi-strategy book | session |
 | `load <file \| module \| universe>` | a CSV, a project module, or a portal universe | session |
 | `thesis [<name> \| clear]` | choose a portal thesis for the next run | session |
+| `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.4 → alphaengine-0.10.0}/src/alphaengine/_version.py

@@ -92,4 +92,30 @@ is what a changed figure costs. The API may still move underneath it.
 # 0.9.4 IS THE SESSION, NOT THE MATHS. No computed value moved. The session
 # opens on the desk: what is loaded, the thesis on its own lines, and the
 # next thing to type.
-__version__ = "0.9.4"
+#
+# 0.9.5 IS THE SESSION, NOT THE MATHS. No golden moved. Correlation, covariance,
+# and cointegration run on the universe already loaded, and the square matrix
+# 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.
+#
+# 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.
+__version__ = "0.10.0"

{alphaengine-0.9.4 → alphaengine-0.10.0}/src/alphaengine/charts.py

@@ -12,7 +12,14 @@ KINDS
     hist      {edges, counts}     histogram
     cost      {bps, sharpe}       cost ladder
     scatter   {x, y}              overlap
-    triangle  {a, b, v}           covariance heatmap
+    triangle  {a, b, v}           covariance heatmap, only when the
+                                  upper triangle fits in 512 cells
+    matrix    names + matrix      full square heatmap. `names[i]` labels
+                                  `matrix[i][j]`. Each row is at most 512
+                                  long, so a book larger than that is truncated
+                                  and `truncated` is true. This is the shape a
+                                  100-name correlation uses; `triangle` cannot
+                                  carry it.
     rows      bounded dict rows   table
     quantiles [float]             bar
 
@@ -32,6 +39,7 @@ CHART_KINDS = frozenset(
         "cost",
         "scatter",
         "triangle",
+        "matrix",
         "rows",
         "quantiles",
     }

{alphaengine-0.9.4 → alphaengine-0.10.0}/src/alphaengine/cli.py

@@ -1131,6 +1131,22 @@ def preflight(catalogue: list[dict[str, Any]], name: str, *, data: Any, backtest
     if not missing:
         return None
 
+    # check_overlap wants one candidate and a separate book. A loaded universe
+    # already holds both: name one symbol and the other names are the book.
+    # Telling somebody to pass --symbol and then discarding the rest of the
+    # names was the loop. The session builds that book itself; this message is
+    # the shell form of the same move.
+    if name == "check_overlap" and _looks_like_universe(data) and isinstance(data, dict):
+        example = next(iter(sorted(str(k) for k in data)), "MU")
+        return (
+            f"check_overlap compares ONE name with the equal-weight of the others, "
+            f"and a universe of {len(data)} names is loaded.\n"
+            f"      run check_overlap --symbol {example}\n"
+            "  That name is the candidate. The other names are the book.\n"
+            "  For every name against every other name:\n"
+            "      run correlation"
+        )
+
     # THE ANSWER THE LOADED DATA MAKES POSSIBLE, before the generic doors. A
     # user with a universe loaded who is told "load a universe" is in a loop
     # with no exit — the real move is naming which of their names to measure.
@@ -1653,16 +1669,145 @@ def _drive(run: Any, *, quiet: bool = False) -> None:
                 return
 
 
+def _publish_panel(session: Any, result: dict[str, Any], *, thesis_id: str | None = None) -> None:
+    """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
+
+    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:
+        say(yellow(str(exc)))
+        return
+    filed = session.file_panel(figures, thesis_id=thesis_id)
+    if not isinstance(filed, dict):
+        return
+    if filed.get("filed"):
+        say(dim("  filed to the portal"))
+        return
+    if filed.get("reason") == "missing":
+        say(dim("  held on this machine; the portal has no panels route yet"))
+        return
+    if filed.get("reason") and filed.get("reason") != "offline":
+        say(dim(f"  held on this machine ({filed.get('reason')})"))
+
+
+def _print_cross(
+    data: Any,
+    kind: str,
+    *,
+    session: Any = None,
+    thesis_id: str | None = None,
+) -> int:
+    from .core.relations import cointegration, correlation, covariance, summary_lines
+
+    try:
+        if kind == "correlation":
+            result = correlation(data)
+        elif kind == "covariance":
+            result = covariance(data)
+        else:
+            result = cointegration(data)
+    except ValueError as exc:
+        say(red(str(exc)))
+        return 2
+    for line in summary_lines(result):
+        say(line)
+    _publish_panel(session, result, thesis_id=thesis_id)
+    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
+
+    if not _looks_like_universe(data):
+        return None
+    try:
+        prepared = overlap_against_the_rest(data, symbol)
+    except ValueError as exc:
+        say(red(str(exc)))
+        return None
+    others = len(prepared["book_names"])
+    say(dim(f"  {prepared['symbol']} against the equal-weight of {others} other names."))
+    return {"returns": prepared["returns"], "book_returns": prepared["book_returns"]}
+
+
 def cmd_run(args: argparse.Namespace) -> int:
     from .client import Offline, ServerError
+    from .core.relations import KINDS
 
     session, url = _session(args.url, args.key)
+    kind = KINDS.get(str(args.workflow).lower().replace("-", "_"))
+    if kind:
+        try:
+            data, _fn = resolve_data(args, session)
+        except (ProjectError, ValueError) as exc:
+            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:
+        resolve_args = argparse.Namespace(**vars(args))
+        resolve_args.symbol = None
     try:
-        data, backtest_fn = resolve_data(args, session)
+        data, backtest_fn = resolve_data(resolve_args, session)
         workspace_id = None
     except (ProjectError, ValueError) as exc:
         say(red(str(exc)))
         return 2
+    if args.workflow == "check_overlap" and _looks_like_universe(data):
+        if symbol:
+            payload = _overlap_payload(data, str(symbol))
+            if payload is None:
+                return 2
+            data = payload
+        else:
+            say("  check_overlap measures one name against the equal-weight of the others.")
+            say(dim("  No name was given, so this is every name against every other name."))
+            return _print_cross(data, "correlation", session=session)
 
     inputs: dict[str, Any] = {}
     for pair in args.input or []:
@@ -3391,6 +3536,22 @@ def _ask(
             except Exception as exc:  # noqa: BLE001 - reachable and unloadable: say so, refuse below
                 say(yellow(f"  {wanted} is on your account and could not be loaded: {exc}"))
 
+    # check_overlap on a universe is one name against the equal-weight of the
+    # rest. Collapsing --symbol here used to throw the book away, which is why
+    # the next line was "needs book_returns, and none was loaded."
+    if name == "check_overlap" and _looks_like_universe(data):
+        sym = _symbol_in(request, data)
+        if sym:
+            payload = _overlap_payload(data, sym)
+            if payload is None:
+                return None
+            data = payload
+        else:
+            say("  check_overlap measures one name against the equal-weight of the others.")
+            say(dim("  No name was given, so this is every name against every other name."))
+            _print_cross(data, "correlation", session=session, thesis_id=thesis_id)
+            return None
+
     # "size MU" against a loaded universe is a complete instruction: the name
     # the question mentions picks the series out of the caller's own data.
     # One match only — two is a real ambiguity and the refusal below names the

{alphaengine-0.9.4 → alphaengine-0.10.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,7 @@ class StepExecutor:
             "verdict": out.get("verdict"),
             "n_trials": n_trials,
             "n_trials_source": source,
+            "risk_free_rate": out.get("risk_free_rate", 0.0),
         }
         # Kept so `emit.study` can carry the verdict this run actually produced
         # rather than deriving it a second time. Two derivations of one figure
@@ -788,6 +796,22 @@ class StepExecutor:
                     out["rolling_window"] = window
                     out["max_rolling_correlation"] = round(max(clean), 6)
                     out["min_rolling_correlation"] = round(min(clean), 6)
+        if isinstance(self.data, dict):
+            symbol = self.data.get("symbol")
+            if symbol:
+                out["symbol"] = str(symbol)
+            book_names = self.data.get("book_names")
+            if isinstance(book_names, list):
+                out["n_book_names"] = len(book_names)
+                if len(book_names) <= MAX_FIGURE_LIST:
+                    out["book_names"] = [str(name) for name in book_names]
+        hints = []
+        if out.get("overlap_scatter"):
+            hints.append(chart("scatter", "overlap_scatter", "candidate vs the book"))
+        if out.get("rolling_correlation"):
+            hints.append(chart("curve", "rolling_correlation", "rolling correlation"))
+        if hints:
+            out["charts"] = hints
         return out
 
     # ── the rest of the modeling week, previously library-only ─────────────
@@ -837,11 +861,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 {
@@ -858,6 +888,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,
@@ -866,6 +901,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,
             )
         )
 
@@ -882,9 +918,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:
@@ -1267,12 +1307,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.4 → alphaengine-0.10.0}/src/alphaengine/client/session.py

@@ -506,6 +506,44 @@ class Session:
     # to `/api/me/proposals/from-os` and `/api/me/sleeves`. Those left with the
     # agent desk in 0.5.0. Selecting a thesis is the read above, not that writer.
 
+    def file_panel(
+        self,
+        figures: Figures,
+        *,
+        thesis_id: str | None = None,
+        label: str | None = None,
+    ) -> Figures:
+        """File a client-computed panel so the portal can draw it.
+
+        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__
+
+        kind = str(figures.get("kind") or "panel")
+        n = figures.get("n_names")
+        body: Figures = {
+            "kind": kind,
+            "label": label or (f"{kind}  {n} names" if n else kind),
+            "engine": f"alphaengine@{__version__}",
+            "figures": figures,
+        }
+        if thesis_id:
+            body["thesis_id"] = thesis_id
+        try:
+            out = self._post("/api/me/panels", body)
+        except ServerError as exc:
+            if exc.status in (404, 405):
+                return {"filed": False, "reason": "missing"}
+            return {"filed": False, "reason": str(exc)}
+        except Offline:
+            return {"filed": False, "reason": "offline"}
+        panel_id = out.get("id") if isinstance(out, dict) else None
+        return {"filed": True, "id": panel_id}
+
     def post_event(self, run_id: str, event: dict[str, Any]) -> Figures:
         """Allowlisted model/run event. 404-tolerant at the sink, not here.
 

{alphaengine-0.9.4 → alphaengine-0.10.0}/src/alphaengine/commands.py

@@ -490,6 +490,65 @@ COMMANDS: tuple[Command, ...] = _question_commands() + (
             "alphaengine run screen_universe --thesis momentum",
         ),
     ),
+    Command(
+        verb="correlation",
+        group="data",
+        args="",
+        scope="repl",
+        purpose="the correlation of every loaded name with every other name",
+        body=(
+            "Runs on the universe already loaded. Closes become returns. The full "
+            "matrix stays on this machine and opens on the right of the session.\n\n"
+            "`covariance` is the same panel as a sample covariance. "
+            "`cointegration` screens the closes, pairwise, and needs the factors extra.\n\n"
+            "`check_overlap` is a different question: one name against the equal-weight "
+            "of the others. Name it with `run check_overlap --symbol MU`. With no name, "
+            "that command shows this matrix instead of refusing."
+        ),
+        examples=("correlation", "run check_overlap --symbol MU"),
+    ),
+    Command(
+        verb="covariance",
+        group="data",
+        args="",
+        scope="repl",
+        purpose="the sample covariance of every loaded name with every other name",
+        body=(
+            "Same panel as `correlation`: the universe already loaded, closes "
+            "turned into returns, full matrix on the right of the session."
+        ),
+        examples=("covariance",),
+    ),
+    Command(
+        verb="cointegration",
+        group="data",
+        args="",
+        scope="repl",
+        purpose="which loaded names are cointegrated",
+        body=(
+            "Engle-Granger across the loaded closes, every pair. Needs the factors "
+            "extra (`pip install 'alphaengine[factors]'`). A hundred names is a few "
+            "thousand tests and takes a while. The pairs open on the right."
+        ),
+        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",

alphaengine-0.10.0/src/alphaengine/context.py

@@ -0,0 +1,130 @@
+"""What this session has already done, in a form a model may quote.
+
+A generic question should not start a new workflow when the desk already
+holds the answer. The notes are short on purpose: counts, a few pairs, a
+few weights. A return series never goes into a note, and an answer that
+cites a number the notes do not contain is refused.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+__all__ = ["remember", "loaded_note", "result_note", "consider"]
+
+_MAX_NOTES = 12
+
+_PROMPT = """You are answering from a research session that is already in progress.
+
+The question:
+{question}
+
+What this session has already recorded. These are the only facts you may use:
+{notes}
+
+Reply with ONE JSON object and nothing else.
+{"answer": "two or three sentences"} when the notes already contain the answer.
+{"workflow": true} when the question asks for a calculation the notes do not contain.
+
+Quote only numbers that appear in the notes. If the notes do not answer the
+question, reply {"workflow": true}.
+"""
+
+
+def remember(notes: list[str], text: str) -> list[str]:
+    """Append one note. The oldest falls off so the window stays the recent desk."""
+    clean = " ".join(str(text).split())
+    if not clean:
+        return list(notes)
+    return [*notes, clean][-_MAX_NOTES:]
+
+
+def loaded_note(label: str, data: Any) -> str:
+    """The shape of what was loaded, never the series."""
+    from .core.relations import as_closes
+
+    closes = as_closes(data) if isinstance(data, dict) else {}
+    if len(closes) >= 1:
+        longest = max(len(values) for values in closes.values())
+        return f"loaded {label}: {len(closes)} names, about {longest} observations"
+    if isinstance(data, (list, tuple)):
+        return f"loaded {label}: {len(data)} returns"
+    return f"loaded {label}"
+
+
+def result_note(result: dict[str, Any]) -> str:
+    """One line a later question can quote."""
+    kind = str(result.get("kind") or "")
+    if kind in ("correlation", "covariance"):
+        names = result.get("names") or []
+        top = ""
+        pairs = result.get("pairs") or []
+        if pairs:
+            pair = pairs[0]
+            top = f" Strongest {pair.get('a')} {pair.get('b')} {pair.get('value')}."
+        return f"{kind}: {len(names)} names, {result.get('n_obs')} observations.{top}"
+    if kind == "cointegration":
+        return (
+            f"cointegration: {result.get('n_cointegrated')} of {result.get('n_pairs')} pairs"
+            f" across {len(result.get('names') or [])} names."
+        )
+    if kind == "portfolio":
+        weights = result.get("weights") or {}
+        largest = ""
+        if weights:
+            name, weight = max(weights.items(), key=lambda item: float(item[1]))
+            largest = f" Largest weight {weight} on {name}."
+        return (
+            f"portfolio {result.get('method')}: {result.get('n_assets')} names,"
+            f" weights sum to {result.get('weight_sum')}.{largest}"
+        )
+    return kind
+
+
+def consider(question: str, notes: list[str], think: Any) -> tuple[str, str]:
+    """("answer", text), ("refuse", reason), or ("workflow", "").
+
+    "workflow" means the notes do not answer it, so the caller should run one.
+    A missing model is "workflow" too: the catalogue path already says what is missing.
+    """
+    if not notes or think is None:
+        return "workflow", ""
+    brief = "\n".join(f"- {note}" for note in notes)
+    raw = think(_PROMPT.replace("{question}", question).replace("{notes}", brief))
+    parsed = _parse(raw)
+    if not isinstance(parsed, dict):
+        return "workflow", ""
+    if parsed.get("workflow") is True:
+        return "workflow", ""
+    answer = str(parsed.get("answer") or "").strip()
+    if not answer:
+        return "workflow", ""
+    bad = _uncited(answer, brief)
+    if bad:
+        return "refuse", f"The answer cited {bad}, which this session has not recorded."
+    return "answer", answer
+
+
+def _parse(raw: str) -> dict[str, Any] | None:
+    text = str(raw or "").strip()
+    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
+    return obj if isinstance(obj, dict) else None
+
+
+def _uncited(answer: str, notes: str) -> str | None:
+    from .agent.answer import _numbers_in, _quotes
+
+    recorded = _numbers_in(notes)
+    for cited, decimals in _numbers_in(answer):
+        if any(_quotes(cited, decimals, value) for value, _decimals in recorded):
+            continue
+        return str(cited)
+    return None