alphaengine 0.9.5__tar.gz → 0.10.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 0.9.5
+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
 ```
 
 ---
@@ -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-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
 ```
 
 ---
@@ -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-0.10.0}/src/alphaengine/_version.py

@@ -98,4 +98,24 @@ 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.
+__version__ = "0.10.0"

{alphaengine-0.9.5 → alphaengine-0.10.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-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
@@ -853,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 {
@@ -874,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,
@@ -882,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,
             )
         )
 
@@ -898,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:
@@ -1283,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.5 → alphaengine-0.10.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-0.10.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",

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

{alphaengine-0.9.5 → alphaengine-0.10.0}/src/alphaengine/core/active.py

@@ -43,18 +43,27 @@ def grinold_alpha(
                 vol_map[str(k)] = abs(float(v if not isinstance(v, (list, tuple)) else v[-1]))
             except (TypeError, ValueError):
                 continue
+    missing_vol = [name for name in names if name not in vol_map]
     for name in names:
+        if name not in vol_map:
+            continue
         score = float(scores[name][-1])
-        vol = vol_map.get(name, 1.0)
-        alpha[name] = round(vol * ic_f * score, _RND)
+        alpha[name] = round(vol_map[name] * ic_f * score, _RND)
     abs_vals = [abs(v) for v in alpha.values()]
+    note = None
+    if not vol_map:
+        note = "no volatility was supplied, so alpha is not reported as a return"
+    elif missing_vol:
+        note = f"{len(missing_vol)} names had no volatility and were left out of alpha"
     return {
         "alpha": alpha,
         "mean_abs_alpha": round(float(np.mean(abs_vals)), _RND) if abs_vals else None,
         "ic_used": round(ic_f, _RND),
         "n_names": len(alpha),
-        "n_skipped": len(skipped) + (len(scores) - len(names)),
+        "n_skipped": len(skipped) + (len(scores) - len(names)) + len(missing_vol),
         "skipped": skipped,
+        "n_missing_vol": len(missing_vol),
+        "note": note,
         "method": "grinold",
     }
 
@@ -65,8 +74,16 @@ def breadth_ir(
     n_names: int,
     holdings: dict | None = None,
     ideal: dict | None = None,
+    independent: bool = False,
+    mean_correlation: float | None = None,
 ) -> dict[str, Any]:
-    """Implied IR = TC * IC * sqrt(breadth). TC is 1 when holdings are absent."""
+    """Implied IR = TC * IC * sqrt(breadth). TC is 1 when holdings are absent.
+
+    Breadth is the name count only when ``independent`` is set, or
+    ``N / (1 + (N - 1) * rho)`` when ``mean_correlation`` is supplied.
+    Omitting both leaves ``implied_ir`` empty rather than treating the names
+    as independent bets.
+    """
     ic_f = float(ic)
     br = max(int(n_names), 0)
     tc = 1.0
@@ -85,11 +102,26 @@ def breadth_ir(
             tc = 0.0
         else:
             tc = 0.0
-    ir = tc * ic_f * math.sqrt(br) if br else 0.0
+    breadth_used: float | None = None
+    assumption = "not_assumed"
+    ir: float | None = None
+    if mean_correlation is not None and br:
+        rho = float(mean_correlation)
+        denom = 1.0 + (br - 1) * rho
+        breadth_used = br / denom if denom > 0 else 0.0
+        assumption = "mean_correlation"
+        ir = tc * ic_f * math.sqrt(breadth_used) if breadth_used > 0 else 0.0
+    elif independent:
+        breadth_used = float(br)
+        assumption = "independent"
+        ir = tc * ic_f * math.sqrt(br) if br else 0.0
     return {
         "ic": round(ic_f, _RND),
         "breadth": br,
+        "effective_breadth": None if breadth_used is None else round(breadth_used, _RND),
+        "breadth_assumption": assumption,
+        "mean_correlation": None if mean_correlation is None else round(float(mean_correlation), _RND),
         "transfer_coefficient": round(tc, _RND),
-        "implied_ir": round(ir, _RND),
+        "implied_ir": None if ir is None else round(ir, _RND),
         "method": "fundamental_law",
     }

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

@@ -579,6 +579,7 @@ def score_backtest(
     n_trials: int | None = None,
     n_trials_source: str | None = None,
     risk_free_rate: float = 0.0,
+    periods_per_year: int = 252,
     benchmark_returns: list | None = None,
     pnl_matrix=None,
     trials_sharpe_std: float | None = None,
@@ -636,10 +637,19 @@ def score_backtest(
         equity_curve=bt.get("equity_curve"),
         benchmark_returns=benchmark_returns,
         risk_free_rate=risk_free_rate,
+        periods_per_year=periods_per_year,
+    )
+    dsr = deflated_sharpe(
+        returns,
+        n_trials=n_trials_eff,
+        trials_sharpe_std=trials_sharpe_std,
+        risk_free_rate=risk_free_rate,
+        periods_per_year=periods_per_year,
     )
-    dsr = deflated_sharpe(returns, n_trials=n_trials_eff, trials_sharpe_std=trials_sharpe_std)
     pbo = pbo_cscv(pnl_matrix) if pnl_matrix is not None else None
-    mintrl = min_track_record_length(returns)
+    mintrl = min_track_record_length(
+        returns, risk_free_rate=risk_free_rate, periods_per_year=periods_per_year
+    )
 
     dsr_ok = isinstance(dsr, dict) and "error" not in dsr
     pbo_ok = isinstance(pbo, dict) and "error" not in pbo
@@ -711,6 +721,8 @@ def score_backtest(
             purge=cpcv_purge,
             embargo=cpcv_embargo,
             n_trials=n_trials_eff,
+            risk_free_rate=risk_free_rate,
+            periods_per_year=periods_per_year,
         )
         if isinstance(cp, dict) and "error" not in cp:
             validation["cpcv"] = cp

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

@@ -3,7 +3,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 (defaults to 0.04 annual) and the VIF threshold is inlined. OLS
+risk-free rate (default 0, excess of zero, not a Treasury bill) and the VIF
+threshold is inlined. OLS
 with HAC standard errors (statsmodels) gives factor betas, alpha, t-stats, R²,
 and a multicollinearity diagnostic (VIF).
 
@@ -30,7 +31,7 @@ import statsmodels.api as sm
 from .trace import record
 
 VIF_MAX_THRESHOLD = 10.0
-_DEFAULT_RFR = 0.04
+_DEFAULT_RFR = 0.0
 
 
 def _clean(val):
@@ -81,18 +82,22 @@ def decompose_factors(
     factor_returns: dict[str, list[float]],
     *,
     risk_free_rate: float | None = None,
+    periods_per_year: int = 252,
+    factors_are_excess: bool = True,
 ) -> dict:
     """Multi-factor regression (FF5 + Momentum style) over supplied returns.
 
     `factor_returns` = {"market": [...], "size": [...]...}. Returns alpha
     (annualized %), factor betas + t-stats, R²/adj-R², residual vol, and a VIF
-    multicollinearity diagnostic.     Excess returns use the supplied rfr (annual),
-    defaulting to 4%.
-
-    That 4% is not the same default as ``performance_report``, which uses 0.
-    A missing rate there must not invent a T-bill. This default is the rate
-    the backend copy used when the caller did not pass one. Pass
-    ``risk_free_rate`` explicitly when the two have to agree.
+    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.
     """
     factor_names = list(factor_returns.keys())
     if not factor_names:
@@ -103,11 +108,14 @@ def decompose_factors(
         return {"error": "Need 30+ observations"}
 
     rfr = float(risk_free_rate) if risk_free_rate is not None else _DEFAULT_RFR
+    ppy = max(int(periods_per_year), 1)
     y = np.array(portfolio_returns[-min_len:], dtype=float)
-    rf_daily = rfr / 252
-    y_excess = y - rf_daily
+    rf_per = rfr / ppy
+    y_excess = y - rf_per
 
     X = np.column_stack([np.array(factor_returns[f][-min_len:], dtype=float) for f in factor_names])
+    if not factors_are_excess:
+        X = X - rf_per
 
     vifs: dict[str, float] = {}
     high_vif: list[str] = []
@@ -128,12 +136,18 @@ def decompose_factors(
     record(
         "factor_alpha",
         "annualised intercept of excess portfolio returns on the factor panel, HAC errors",
-        inputs={"n_observations": int(min_len), "risk_free_rate": rfr, "n_factors": len(factor_names)},
+        inputs={
+            "n_observations": int(min_len),
+            "risk_free_rate": rfr,
+            "periods_per_year": ppy,
+            "factors_are_excess": bool(factors_are_excess),
+            "n_factors": len(factor_names),
+        },
         series={"portfolio_excess": y_excess},
-        result=round(float(model.params[0] * 252 * 100), 2),
+        result=round(float(model.params[0] * ppy * 100), 2),
     )
     return {
-        "alpha": _clean(round(float(model.params[0] * 252 * 100), 2)),
+        "alpha": _clean(round(float(model.params[0] * ppy * 100), 2)),
         "alpha_tstat": _clean(round(float(model.tvalues[0]), 2)),
         "alpha_pvalue": _clean(round(alpha_pvalue, 4)),
         "alpha_significant_at_5pct": bool(alpha_pvalue < 0.05),
@@ -141,8 +155,14 @@ def decompose_factors(
         "factor_tstats": tstats,
         "r_squared": _clean(round(float(model.rsquared), 3)),
         "adj_r_squared": _clean(round(float(model.rsquared_adj), 3)),
-        "residual_vol": _clean(round(float(np.std(model.resid) * np.sqrt(252) * 100), 2)),
+        "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),
+        "periods_per_year": ppy,
+        "factors_are_excess": bool(factors_are_excess),
+        "alpha_annualization": "arithmetic",
+        "hac_maxlags": 5,
         "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,