fa-quant 1.2.1__py3-none-any.whl

financial_agent/harness/policy.py

@@ -0,0 +1,248 @@
+"""Rules-as-code: the numeric policy a model must never re-derive by hand.
+
+``equity_policy.toml`` holds the numbers from ``rules.md``; this module turns
+them into pure functions (mu prior, CI, VaR/CVaR, Kelly, score trace) and
+into a governance check for self-evolution proposals, so "only the evolution
+agent may change the mu table, with evidence" becomes a code path.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+DEFAULT_POLICY_PATH = Path(__file__).with_name("equity_policy.toml")
+FAMILIES = ("fund_z", "tech_z", "sent_z", "macro_z")
+_MISSING = object()
+
+
+@dataclass(frozen=True)
+class MuBand:
+    min_pctl: float
+    mu: float
+    sleeve: str
+
+
+@dataclass(frozen=True)
+class KellySizing:
+    raw: float
+    fractional: float  # fraction x raw, uncapped: the investability-gate input
+    weight: float  # fractional clipped to [0, single-name cap]: the sizing input
+    gate: str  # BLOCKED | PENALTY | OK | CAP_BINDING
+
+
+class Policy:
+    """Read-only view over a policy document with typed helpers."""
+
+    def __init__(self, data: Mapping[str, Any], source: str = "<memory>") -> None:
+        self.data = data
+        self.source = source
+
+    @property
+    def version(self) -> str:
+        return str(self.data["policy_version"])
+
+    @property
+    def effective_date(self) -> str:
+        return str(self.data["effective_date"])
+
+    def get(self, dotted: str) -> Any:
+        node: Any = self.data
+        for part in dotted.split("."):
+            node = node[part]
+        return node
+
+    def num(self, dotted: str) -> float:
+        return float(self.get(dotted))
+
+    @property
+    def family_weights(self) -> dict[str, float]:
+        return {k: float(v) for k, v in self.get("score.family_weights").items()}
+
+    @property
+    def shadow_families(self) -> tuple[str, ...]:
+        """Families computed as diagnostics only (rules.md § SHADOW Diagnostic
+        Tooling); they never count toward Adj Score or the thresholds."""
+        return tuple(self.get("score.shadow_families"))
+
+    @property
+    def gating_families(self) -> tuple[str, ...]:
+        shadow = set(self.shadow_families)
+        return tuple(f for f in FAMILIES if f not in shadow)
+
+    @property
+    def mu_bands(self) -> list[MuBand]:
+        bands = [
+            MuBand(float(b["min_pctl"]), float(b["mu"]), str(b["sleeve"]))
+            for b in self.get("forecast.mu_bands")
+        ]
+        return sorted(bands, key=lambda b: b.min_pctl, reverse=True)
+
+    def mu_prior(self, pctl: float) -> MuBand | None:
+        """Calibration-table band for a percentile; ``None`` means do not rank."""
+        return next((b for b in self.mu_bands if pctl >= b.min_pctl), None)
+
+    def spy_mu_prior(self, regime: str) -> float:
+        return float(self.get("market_forecast.spy_regime_prior")[regime])
+
+    def target_price(self, entry: float, mu: float) -> float:
+        return entry * (1 + mu)
+
+    def ci70(self, entry: float, mu: float, sigma: float) -> tuple[float, float]:
+        z = self.num("forecast.ci70_z")
+        return entry * (1 + mu - z * sigma), entry * (1 + mu + z * sigma)
+
+    def var95(self, mu: float, sigma: float) -> float:
+        """Parametric one-month VaR in return space (decimal, not percent)."""
+        return mu - self.num("forecast.var95_z") * sigma
+
+    def cvar95(self, mu: float, sigma: float) -> float:
+        return mu - self.num("forecast.cvar95_z") * sigma
+
+    def kelly(self, mu: float, sigma: float) -> KellySizing:
+        """``mu / sigma^2`` fallback Kelly, with both the gate and sizing views.
+
+        The two views are separate fields on purpose: historical ledgers store
+        one number called ``kelly_025`` that some runs cap at 5% and others do
+        not, which makes the ``< 2%`` and cap-binding gates unreproducible.
+        """
+        return self.kelly_sizing(mu / sigma**2)
+
+    def kelly_sizing(self, raw: float) -> KellySizing:
+        """Gate and sizing views of a raw Kelly edge from either method."""
+        fractional = self.num("kelly.fraction") * raw
+        cap = self.num("risk.max_single_name_weight")
+        weight = min(max(fractional, 0.0), cap)
+        if fractional <= self.num("kelly.block_at_or_below"):
+            gate = "BLOCKED"
+        elif fractional < self.num("kelly.penalty_below"):
+            gate = "PENALTY"
+        elif fractional >= cap:
+            gate = "CAP_BINDING"
+        else:
+            gate = "OK"
+        return KellySizing(raw=raw, fractional=fractional, weight=weight, gate=gate)
+
+    def composite_z(self, family_z: Mapping[str, float | None]) -> float:
+        """Weighted family z; an UNAVAILABLE family contributes the policy default."""
+        fallback = self.num("score.unavailable_family_contribution")
+        total = 0.0
+        for family, weight in self.family_weights.items():
+            z = family_z.get(family)
+            total += weight * (fallback if z is None else z)
+        return total
+
+    def adj_score(self, composite: float, dq: float, penalties: float) -> float:
+        return composite * dq - penalties
+
+
+def load_policy(path: Path | None = None) -> Policy:
+    target = path or DEFAULT_POLICY_PATH
+    with target.open("rb") as handle:
+        return Policy(tomllib.load(handle), source=str(target))
+
+
+def flatten(data: Mapping[str, Any], prefix: str = "") -> dict[str, Any]:
+    """Dotted-key view; lists of tables are indexed (``forecast.mu_bands[0].mu``)."""
+    out: dict[str, Any] = {}
+    for key, value in data.items():
+        dotted = f"{prefix}.{key}" if prefix else key
+        if isinstance(value, Mapping):
+            out.update(flatten(value, dotted))
+        elif (
+            isinstance(value, list)
+            and value
+            and all(isinstance(v, Mapping) for v in value)
+        ):
+            for index, item in enumerate(value):
+                out.update(flatten(item, f"{dotted}[{index}]"))
+        else:
+            out[dotted] = value
+    return out
+
+
+def _under(key: str, prefixes: list[str]) -> bool:
+    return any(
+        key == p or key.startswith(p + ".") or key.startswith(p + "[") for p in prefixes
+    )
+
+
+@dataclass(frozen=True)
+class MutationEvidence:
+    """What a proposal can show: canonical settlement counts + human sign-off."""
+
+    settled_n: int = 0
+    eff_n: int = 0
+    human_approved: bool = False
+
+
+@dataclass(frozen=True)
+class MutationVerdict:
+    decision: str  # NO_CHANGE | ACCEPTABLE | DEFER | REJECT
+    changed: tuple[str, ...]
+    reasons: tuple[str, ...]
+
+
+def check_mutation(
+    old: Policy, new: Policy, evidence: MutationEvidence
+) -> MutationVerdict:
+    """Govern a proposed policy diff with the *old* policy's limits.
+
+    ACCEPTABLE means the diff may be proposed for merge; adoption stays a
+    reviewed change (the harness never edits its own policy file).
+    """
+    before, after = flatten(old.data), flatten(new.data)
+    bookkeeping = {"policy_version", "effective_date"}
+    changed = tuple(
+        sorted(
+            key
+            for key in set(before) | set(after)
+            if key not in bookkeeping
+            and before.get(key, _MISSING) != after.get(key, _MISSING)
+        )
+    )
+    if not changed:
+        return MutationVerdict("NO_CHANGE", (), ())
+
+    rejects: list[str] = []
+    defers: list[str] = []
+    protected = list(old.get("evolution.protected"))
+    track_a = list(old.get("evolution.track_a"))
+    for key in changed:
+        if _under(key, protected) and not evidence.human_approved:
+            rejects.append(f"{key}: protected rule, requires human approval")
+    if new.version == old.version:
+        rejects.append("policy_version must change with any rule change")
+    if new.effective_date <= old.effective_date:
+        rejects.append("effective_date must move forward")
+
+    if any(_under(key, ["score.family_weights"]) for key in changed):
+        step = old.num("evolution.max_family_weight_step")
+        old_w, new_w = old.family_weights, new.family_weights
+        if set(old_w) != set(new_w):
+            rejects.append("score.family_weights: the family set cannot change")
+        else:
+            for family in FAMILIES:
+                delta = abs(new_w[family] - old_w[family])
+                if delta > step + 1e-12:
+                    rejects.append(
+                        f"score.family_weights.{family}: step {delta:.3f} "
+                        f"exceeds {step:.2f}"
+                    )
+            if abs(sum(new_w.values()) - 1.0) > 1e-9:
+                rejects.append("score.family_weights must sum to 1.0")
+
+    if any(_under(key, track_a) for key in changed):
+        min_n = int(old.num("evolution.track_a_min_settled_n"))
+        min_eff = int(old.num("evolution.track_a_min_eff_n"))
+        if evidence.settled_n < min_n or evidence.eff_n < min_eff:
+            defers.append(
+                f"Track A change needs settled n>={min_n} and eff_n>={min_eff} "
+                f"(have n={evidence.settled_n}, eff_n={evidence.eff_n}): "
+                "log as an observation and DEFER"
+            )
+
+    decision = "REJECT" if rejects else "DEFER" if defers else "ACCEPTABLE"
+    return MutationVerdict(decision, changed, tuple(rejects + defers))

financial_agent/harness/runner.py

@@ -0,0 +1,275 @@
+"""Run driver: the skeleton behind ``fa-harness run`` (plan §3.5, Phase 4).
+
+The runner owns the order of a run, the (model, date) lock, and the gated
+publish. Everything that does work (adapters, kernels, model calls) plugs in as
+a stage handler; a stage without a handler halts the run instead of being
+skipped, so a half-built pipeline can never publish.
+
+A handler for state ``S`` runs while the lifecycle is in ``S``; the runner then
+advances to the next state. ``RISK_REVIEW`` must return the run status, and the
+publish gate runs before the lifecycle moves to ``PUBLISHED``. A handler sees
+every earlier stage's result (``context.results``), so stages pass data forward
+without a side channel.
+
+Every run writes a journal, ``{output_dir}/.runs/{model}-{date}.json``, after each
+stage: transitions, per-stage notes, data and timings, gate failures, and the
+halt reason. It is the run's heartbeat while it runs and its record after.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+from financial_agent.harness.gates import publish_gate
+from financial_agent.harness.lifecycle import (
+    LifecycleError,
+    RunLifecycle,
+    RunState,
+    RunStatus,
+)
+from financial_agent.harness.policy import Policy, load_policy
+
+# States whose handler runs before the lifecycle advances, in order.
+PIPELINE = (
+    RunState.PRECHECK,
+    RunState.REFLECTION,
+    RunState.DATA_OK,
+    RunState.TECHNICALS_OK,
+    RunState.SCORED,
+    RunState.PORTFOLIO_DRAFT,
+    RunState.RISK_REVIEW,
+)
+POST_PUBLISH = RunState.EVOLUTION_REVIEW
+
+
+class RunLocked(RuntimeError):
+    """Another run holds the (model, date) lock, or a crashed one left it."""
+
+
+@dataclass(frozen=True)
+class StageResult:
+    note: str = ""
+    status: RunStatus | None = None  # required from the RISK_REVIEW handler
+    halt: str | None = None  # a handler's way to stop the run with a reason
+    data: Mapping[str, Any] = field(default_factory=dict)  # for later stages
+
+
+@dataclass(frozen=True)
+class RunContext:
+    model: str
+    date: str
+    package_dir: Path
+    policy: Policy | None = field(default=None, compare=False)
+    # Results of the stages that already ran, filled in by ``run``.
+    results: dict[RunState, StageResult] = field(default_factory=dict, compare=False)
+
+    @property
+    def run_id(self) -> str:
+        return f"{self.model}-{self.date}"
+
+
+Handler = Callable[[RunContext], StageResult]
+
+
+@dataclass
+class RunReport:
+    run_id: str
+    lifecycle: RunLifecycle
+    gate_failures: list[str] = field(default_factory=list)
+    stages: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    @property
+    def published(self) -> bool:
+        return self.lifecycle.status not in {None, RunStatus.HALTED}
+
+    @property
+    def halt_reason(self) -> str | None:
+        last = self.lifecycle.log[-1] if self.lifecycle.log else None
+        if last is not None and last.target is RunState.HALTED:
+            return last.note
+        return None
+
+
+class RunLock:
+    """``{output_dir}/.locks/{model}-{date}.lock``, created atomically.
+
+    Not reentrant and never stolen: a crashed run leaves the file, and a person
+    removes it after looking at the half-written package.
+    """
+
+    def __init__(self, output_dir: Path, run_id: str) -> None:
+        self.path = output_dir / ".locks" / f"{run_id}.lock"
+
+    def __enter__(self) -> "RunLock":
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            fd = os.open(self.path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            raise RunLocked(
+                f"{self.path} exists: a run is in progress or crashed; "
+                "inspect the package, then remove the lock"
+            ) from None
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(f"pid={os.getpid()}\n")
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.path.unlink(missing_ok=True)
+
+
+class RunJournal:
+    """``{output_dir}/.runs/{run_id}.json``, replaced atomically on every write."""
+
+    def __init__(self, output_dir: Path, run_id: str) -> None:
+        self.path = output_dir / ".runs" / f"{run_id}.json"
+        self.started_at = _now()
+
+    def write(self, report: RunReport, *, finished: bool = False) -> None:
+        lifecycle = report.lifecycle
+        body = {
+            "run_id": report.run_id,
+            "started_at": self.started_at,
+            "updated_at": _now(),
+            "finished": finished,
+            "state": lifecycle.state.value,
+            "status": lifecycle.status.value if lifecycle.status else None,
+            "transcript": lifecycle.transcript(),
+            "transitions": [
+                {
+                    "source": t.source.value,
+                    "target": t.target.value,
+                    "at": t.at,
+                    "note": t.note,
+                }
+                for t in lifecycle.log
+            ],
+            "stages": report.stages,
+            "gate_failures": report.gate_failures,
+            "halt_reason": report.halt_reason,
+        }
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        partial = self.path.with_suffix(".json.partial")
+        partial.write_text(json.dumps(body, indent=2, default=str), encoding="utf-8")
+        partial.replace(self.path)
+
+
+def _now() -> str:
+    return dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds")
+
+
+def run(
+    model: str,
+    date: str,
+    output_dir: Path,
+    handlers: Mapping[RunState, Handler],
+    *,
+    policy: Policy | None = None,
+) -> RunReport:
+    """Drive one run to ``EVOLUTION_REVIEW`` or ``HALTED``; never raises on a halt."""
+    policy = policy or load_policy()
+    context = RunContext(model, date, output_dir / f"{model}-{date}", policy)
+    report = RunReport(context.run_id, RunLifecycle(context.run_id))
+    with RunLock(output_dir, context.run_id):
+        journal = RunJournal(output_dir, context.run_id)
+        try:
+            _drive(context, report, handlers, policy, journal)
+        finally:
+            journal.write(report, finished=True)
+    return report
+
+
+def _drive(
+    context: RunContext,
+    report: RunReport,
+    handlers: Mapping[RunState, Handler],
+    policy: Policy,
+    journal: RunJournal,
+) -> None:
+    lifecycle = report.lifecycle
+    status: RunStatus | None = None
+    for index, state in enumerate(PIPELINE):
+        outcome = _stage(handlers, state, context, report)
+        journal.write(report)
+        if isinstance(outcome, str):
+            lifecycle.halt(outcome)
+            return
+        if outcome.halt:
+            lifecycle.halt(outcome.halt)
+            return
+        if state is RunState.RISK_REVIEW:
+            if outcome.status is None or outcome.status is RunStatus.HALTED:
+                lifecycle.halt("RISK_REVIEW handler returned no publishable status")
+                return
+            status = outcome.status
+            break
+        lifecycle.advance(PIPELINE[index + 1], outcome.note)
+    assert status is not None
+    report.gate_failures = _gate(context, policy)
+    try:
+        lifecycle.publish(status, report.gate_failures)
+    except LifecycleError as exc:
+        lifecycle.halt(str(exc))
+        return
+    journal.write(report)
+    if POST_PUBLISH in handlers:
+        outcome = _stage(handlers, POST_PUBLISH, context, report)
+        note = outcome if isinstance(outcome, str) else outcome.note
+    else:
+        note = "skipped: no handler"
+    lifecycle.advance(POST_PUBLISH, note)
+
+
+def _stage(
+    handlers: Mapping[RunState, Handler],
+    state: RunState,
+    context: RunContext,
+    report: RunReport,
+) -> StageResult | str:
+    """Run one stage and record it; a string result is the halt reason."""
+    started = time.monotonic()
+    outcome = _call(handlers, state, context)
+    entry: dict[str, Any] = {"seconds": round(time.monotonic() - started, 3)}
+    if isinstance(outcome, str):
+        entry["halt"] = outcome
+    else:
+        context.results[state] = outcome
+        entry.update(note=outcome.note, data=dict(outcome.data))
+        if outcome.halt:
+            entry["halt"] = outcome.halt
+    report.stages[state.value] = entry
+    return outcome
+
+
+def _call(
+    handlers: Mapping[RunState, Handler], state: RunState, context: RunContext
+) -> StageResult | str:
+    """A handler's result, or the halt reason when it is missing or raises."""
+    handler = handlers.get(state)
+    if handler is None:
+        return f"no handler for {state.value}"
+    try:
+        return handler(context)
+    except Exception as exc:  # a failed stage halts the run; it never publishes
+        return f"{state.value} handler failed: {type(exc).__name__}: {exc}"
+
+
+def _gate(context: RunContext, policy: Policy) -> list[str]:
+    if not context.package_dir.is_dir():
+        return [f"package directory {context.package_dir} was never created"]
+    return publish_gate(context.package_dir, policy)
+
+
+def default_handlers() -> Mapping[RunState, Handler]:
+    """Shipped handlers. Stages without one halt the run (plan Phase 2)."""
+    from financial_agent.harness.handlers import precheck_handler, reflection_handler
+
+    return {
+        RunState.PRECHECK: precheck_handler,
+        RunState.REFLECTION: reflection_handler,
+    }