fa-quant 1.2.1__py3-none-any.whl

financial_agent/harness/ledger.py

@@ -0,0 +1,325 @@
+"""Provenance by construction: the ``01_preflight.md`` Source Ledger as code.
+
+Today the model hand-writes ~180 ledger rows per run and then re-types their
+values into five other artifacts. Here every fact enters through a method
+that stamps provenance, derived facts inherit UNAVAILABLE from any missing
+input (``rules.md`` § Source Ledger Contract, hard rule 2), the Price
+Sourcing Standard is a function rather than a paragraph, and narrative text
+cites ``{{L012}}`` placeholders that the renderer fills -- so a transcription
+error has nowhere to happen.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from dataclasses import dataclass, field, replace
+from typing import Callable, Sequence
+from urllib.parse import urlparse
+
+FRESHNESS_TAGS = (
+    "LIVE",
+    "DELAYED",
+    "OFFICIAL_FILING",
+    "HISTORICAL",
+    "ILLUSTRATIVE_REF",
+    "UNAVAILABLE",
+)
+# Weakest input wins when facts are combined.
+_FRESHNESS_RANK = {tag: rank for rank, tag in enumerate(FRESHNESS_TAGS)}
+CLAIM_TYPES = ("OBSERVED", "DERIVED", "INFERRED", "ILLUSTRATIVE", "UNAVAILABLE")
+PRICE_AGREEMENT = 0.01  # rules.md § Price Sourcing Standard: two sources within 1%
+
+Value = float | str | None
+_REF_RE = re.compile(r"\{\{(L\d+[a-z]?)(?:\|(\w+))?\}\}")
+# Decimals (optionally %), integer percentages, count ratios like 27/27,
+# thousands-grouped integers, and bare integers of three or more digits.
+_LITERAL_NUMBER_RE = re.compile(
+    r"(?<![\w.{/])(?:[-+]?\d[\d,]*\.\d+%?|[-+]?\d+%|\d+/\d+|\d{1,3}(?:,\d{3})+"
+    r"|\d{3,})(?![\w}/])"
+)
+_DATE_RE = re.compile(r"\b\d{4}-\d{2}-\d{2}\b")
+
+
+class LedgerError(ValueError):
+    """A fact without provenance, an unknown row, or a malformed citation."""
+
+
+@dataclass(frozen=True)
+class Quote:
+    """One observed price from one source, stamped when it was fetched."""
+
+    source: str
+    value: float
+    retrieved_at: str
+    from_market_data_tool: bool = False
+
+
+@dataclass(frozen=True)
+class LedgerRow:
+    row_id: str
+    field: str
+    entity: str
+    value: Value
+    unit: str
+    observation_date: str | None
+    source: str
+    freshness_tag: str
+    claim_type: str
+    inputs: tuple[str, ...] = ()
+    used_by: tuple[str, ...] = ()
+
+    @property
+    def available(self) -> bool:
+        return self.claim_type != "UNAVAILABLE"
+
+
+def _host(source: str) -> str:
+    parsed = urlparse(source)
+    return (parsed.netloc or source).lower().removeprefix("www.")
+
+
+@dataclass
+class SourceLedger:
+    run_id: str
+    rows: dict[str, LedgerRow] = field(default_factory=dict)
+    _next: int = 1
+
+    # -- writing ---------------------------------------------------------
+
+    def _add(self, row: LedgerRow) -> str:
+        if row.freshness_tag not in _FRESHNESS_RANK:
+            raise LedgerError(f"freshness_tag {row.freshness_tag!r} not allowed")
+        if row.claim_type not in CLAIM_TYPES:
+            raise LedgerError(f"claim_type {row.claim_type!r} not allowed")
+        self.rows[row.row_id] = row
+        return row.row_id
+
+    def _new_id(self) -> str:
+        row_id = f"L{self._next:03d}"
+        self._next += 1
+        return row_id
+
+    def observe(
+        self,
+        field_name: str,
+        entity: str,
+        value: float | str,
+        *,
+        unit: str,
+        observation_date: str,
+        source: str,
+        freshness_tag: str,
+        retrieved_at: str,
+    ) -> str:
+        """A fact read directly from a cited source during this run."""
+        if not source or not retrieved_at:
+            raise LedgerError("an OBSERVED row needs a source and retrieved_at")
+        try:
+            dt.date.fromisoformat(observation_date)
+        except ValueError:
+            raise LedgerError(f"observation_date {observation_date!r}") from None
+        return self._add(
+            LedgerRow(
+                row_id=self._new_id(),
+                field=field_name,
+                entity=entity,
+                value=value,
+                unit=unit,
+                observation_date=observation_date,
+                source=f"{source} retrieved_at {retrieved_at}",
+                freshness_tag=freshness_tag,
+                claim_type="OBSERVED",
+            )
+        )
+
+    def unavailable(self, field_name: str, entity: str, reason: str) -> str:
+        return self._add(
+            LedgerRow(
+                row_id=self._new_id(),
+                field=field_name,
+                entity=entity,
+                value=None,
+                unit="",
+                observation_date=None,
+                source=reason,
+                freshness_tag="UNAVAILABLE",
+                claim_type="UNAVAILABLE",
+            )
+        )
+
+    def observe_price(
+        self,
+        entity: str,
+        quotes: Sequence[Quote],
+        *,
+        observation_date: str,
+        freshness_tag: str,
+        unit: str = "USD",
+    ) -> str:
+        """Price Sourcing Standard as code: a market-data tool quote, or two
+        independent sources agreeing within 1%; anything else is UNAVAILABLE."""
+        tool = [q for q in quotes if q.from_market_data_tool]
+        if tool:
+            q = tool[0]
+            return self.observe(
+                "close",
+                entity,
+                q.value,
+                unit=unit,
+                observation_date=observation_date,
+                source=q.source,
+                freshness_tag=freshness_tag,
+                retrieved_at=q.retrieved_at,
+            )
+        by_host: dict[str, Quote] = {}
+        for q in quotes:
+            by_host.setdefault(_host(q.source), q)
+        independent = list(by_host.values())
+        if len(independent) < 2:
+            return self.unavailable(
+                "close",
+                entity,
+                f"price grounding failed: {len(independent)} independent source(s)",
+            )
+        values = [q.value for q in independent]
+        spread = max(values) / min(values) - 1
+        if spread > PRICE_AGREEMENT:
+            return self.unavailable(
+                "close",
+                entity,
+                f"price grounding failed: sources disagree {spread:.2%}",
+            )
+        primary = independent[0]
+        cross = "; ".join(f"{q.source}={q.value}" for q in independent[1:])
+        return self.observe(
+            "close",
+            entity,
+            primary.value,
+            unit=unit,
+            observation_date=observation_date,
+            source=f"{primary.source} (cross-check {cross}, spread {spread:.2%})",
+            freshness_tag=freshness_tag,
+            retrieved_at=primary.retrieved_at,
+        )
+
+    def derive(
+        self,
+        field_name: str,
+        entity: str,
+        *,
+        formula: str,
+        inputs: Sequence[str],
+        compute: Callable[..., float],
+        unit: str,
+    ) -> str:
+        """A computed fact; any UNAVAILABLE input makes the result UNAVAILABLE."""
+        rows = [self.row(i) for i in inputs]
+        if not rows:
+            raise LedgerError("a DERIVED row must cite at least one input row")
+        if not all(r.available for r in rows):
+            missing = ", ".join(r.row_id for r in rows if not r.available)
+            return self._add(
+                LedgerRow(
+                    row_id=self._new_id(),
+                    field=field_name,
+                    entity=entity,
+                    value=None,
+                    unit=unit,
+                    observation_date=None,
+                    source=f"DERIVED: {formula}; input(s) {missing} UNAVAILABLE",
+                    freshness_tag="UNAVAILABLE",
+                    claim_type="UNAVAILABLE",
+                    inputs=tuple(inputs),
+                )
+            )
+        value = compute(*(r.value for r in rows))
+        dates = [r.observation_date for r in rows if r.observation_date]
+        weakest = max((r.freshness_tag for r in rows), key=_FRESHNESS_RANK.__getitem__)
+        return self._add(
+            LedgerRow(
+                row_id=self._new_id(),
+                field=field_name,
+                entity=entity,
+                value=value,
+                unit=unit,
+                observation_date=max(dates) if dates else None,
+                source=f"DERIVED: {formula}; inputs {', '.join(inputs)}",
+                freshness_tag=weakest,
+                claim_type="DERIVED",
+                inputs=tuple(inputs),
+            )
+        )
+
+    # -- reading ---------------------------------------------------------
+
+    def row(self, row_id: str) -> LedgerRow:
+        try:
+            return self.rows[row_id]
+        except KeyError:
+            raise LedgerError(f"unknown ledger row {row_id}") from None
+
+    def cite(self, row_id: str, artifact: str) -> Value:
+        """Read a value *and* record which artifact used it (``used_by``)."""
+        row = self.row(row_id)
+        if artifact not in row.used_by:
+            self.rows[row_id] = replace(row, used_by=row.used_by + (artifact,))
+        return row.value
+
+    def render(self, template: str, artifact: str) -> str:
+        """Fill ``{{L012}}`` / ``{{L012|pct}}`` citations from the ledger."""
+
+        def fill(match: re.Match[str]) -> str:
+            row_id, fmt = match.group(1), match.group(2)
+            value = self.cite(row_id, artifact)
+            if value is None:
+                return f"UNAVAILABLE ({row_id})"
+            if fmt == "pct" and isinstance(value, float):
+                return f"{value:+.2%} ({row_id})"
+            if isinstance(value, float):
+                return f"{value:,.2f} ({row_id})"
+            return f"{value} ({row_id})"
+
+        return _REF_RE.sub(fill, template)
+
+    def to_markdown(self) -> str:
+        """The Source Ledger table in the ``runbook.md § 01`` schema."""
+        header = (
+            "| artifact | field | ticker/entity | value | unit | observation_date "
+            "| source | freshness_tag | claim_type | used_by |\n"
+            "|---|---|---|---|---|---|---|---|---|---|"
+        )
+        lines = [header]
+        for row in self.rows.values():
+            value = "UNAVAILABLE" if row.value is None else row.value
+            cells = [
+                row.row_id,
+                row.field,
+                row.entity,
+                str(value),
+                row.unit,
+                row.observation_date or "UNAVAILABLE",
+                row.source.replace("|", "\\|"),
+                row.freshness_tag,
+                row.claim_type,
+                ", ".join(row.used_by),
+            ]
+            lines.append("| " + " | ".join(cells) + " |")
+        return "\n".join(lines)
+
+
+def lint_literal_numbers(template: str, allow: Sequence[str] = ()) -> list[str]:
+    """Numbers typed into model-authored text instead of cited via ``{{L...}}``.
+
+    ISO dates and one- or two-digit integers ("3 of 4 families") pass;
+    decimals, percentages, count ratios (``27/27``), and integers of three or
+    more digits must come from the ledger unless listed in ``allow``.
+    """
+    allowed = set(allow)
+    findings: list[str] = []
+    for line_no, line in enumerate(template.splitlines(), start=1):
+        scrubbed = _DATE_RE.sub("", _REF_RE.sub("", line))
+        for match in _LITERAL_NUMBER_RE.finditer(scrubbed):
+            if match.group(0) not in allowed:
+                findings.append(f"line {line_no}: literal number {match.group(0)!r}")
+    return findings

financial_agent/harness/lifecycle.py

@@ -0,0 +1,127 @@
+"""Run lifecycle: the ``main.md`` state machine enforced in code.
+
+``main.md`` says "a run is a state machine, not an essay". Today the model
+narrates the transitions; here the harness owns them, so a skipped stage, an
+extra revision pass, or publishing without a passing gate is an exception,
+not a sentence in a manifest.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class RunState(str, Enum):
+    PRECHECK = "PRECHECK"
+    REFLECTION = "REFLECTION"
+    DATA_OK = "DATA_OK"
+    TECHNICALS_OK = "TECHNICALS_OK"
+    SCORED = "SCORED"
+    PORTFOLIO_DRAFT = "PORTFOLIO_DRAFT"
+    RISK_REVIEW = "RISK_REVIEW"
+    PUBLISHED = "PUBLISHED"
+    CLOSE_LOGGED = "CLOSE_LOGGED"
+    EVOLUTION_REVIEW = "EVOLUTION_REVIEW"
+    HALTED = "HALTED"
+
+
+class RunStatus(str, Enum):
+    GO = "GO"
+    NO_TRADE = "NO_TRADE"
+    REVIEW_ONLY = "REVIEW_ONLY"
+    HALTED = "HALTED"
+
+
+_FORWARD: dict[RunState, frozenset[RunState]] = {
+    RunState.PRECHECK: frozenset({RunState.REFLECTION}),
+    RunState.REFLECTION: frozenset({RunState.DATA_OK}),
+    RunState.DATA_OK: frozenset({RunState.TECHNICALS_OK}),
+    RunState.TECHNICALS_OK: frozenset({RunState.SCORED}),
+    RunState.SCORED: frozenset({RunState.PORTFOLIO_DRAFT}),
+    RunState.PORTFOLIO_DRAFT: frozenset({RunState.RISK_REVIEW}),
+    RunState.RISK_REVIEW: frozenset({RunState.PUBLISHED}),
+    RunState.PUBLISHED: frozenset({RunState.CLOSE_LOGGED, RunState.EVOLUTION_REVIEW}),
+    RunState.CLOSE_LOGGED: frozenset({RunState.EVOLUTION_REVIEW}),
+    RunState.EVOLUTION_REVIEW: frozenset(),
+    RunState.HALTED: frozenset(),
+}
+# rules.md § Intra-Loop Revision Limit: one portfolio<->risk revision pass and
+# one clarification back to factor scoring.
+_REVISIONS: dict[tuple[RunState, RunState], str] = {
+    (RunState.RISK_REVIEW, RunState.PORTFOLIO_DRAFT): "risk_revision",
+    (RunState.PORTFOLIO_DRAFT, RunState.SCORED): "scoring_clarification",
+    (RunState.RISK_REVIEW, RunState.SCORED): "scoring_clarification",
+}
+REVISION_BUDGET = {"risk_revision": 1, "scoring_clarification": 1}
+
+
+class LifecycleError(RuntimeError):
+    """An illegal transition, an exhausted revision budget, or a failed gate."""
+
+
+@dataclass(frozen=True)
+class Transition:
+    source: RunState
+    target: RunState
+    at: str
+    note: str
+
+
+@dataclass
+class RunLifecycle:
+    run_id: str
+    state: RunState = RunState.PRECHECK
+    status: RunStatus | None = None
+    log: list[Transition] = field(default_factory=list)
+    revisions_used: dict[str, int] = field(default_factory=dict)
+
+    def advance(
+        self, target: RunState, note: str = "", *, at: str | None = None
+    ) -> None:
+        if target is RunState.PUBLISHED:
+            raise LifecycleError("use publish(): PUBLISHED requires a status and gate")
+        self._move(target, note, at)
+
+    def halt(self, reason: str, *, at: str | None = None) -> None:
+        if self.state in {RunState.HALTED, RunState.EVOLUTION_REVIEW}:
+            raise LifecycleError(f"cannot halt from terminal state {self.state.value}")
+        self.status = RunStatus.HALTED
+        self._record(RunState.HALTED, reason, at)
+
+    def publish(
+        self, status: RunStatus, gate_failures: list[str], *, at: str | None = None
+    ) -> None:
+        """Publish only when every publish-gate check passed."""
+        if gate_failures:
+            raise LifecycleError("publish gate failed: " + "; ".join(gate_failures))
+        if status is RunStatus.HALTED:
+            raise LifecycleError("use halt(): HALTED is not a publication status")
+        self._move(RunState.PUBLISHED, f"status={status.value}", at)
+        self.status = status
+
+    def _move(self, target: RunState, note: str, at: str | None) -> None:
+        budget_key = _REVISIONS.get((self.state, target))
+        if budget_key is not None:
+            used = self.revisions_used.get(budget_key, 0)
+            if used >= REVISION_BUDGET[budget_key]:
+                raise LifecycleError(
+                    f"{budget_key} budget exhausted ({used}); publish NO_TRADE or halt"
+                )
+            self.revisions_used[budget_key] = used + 1
+        elif target not in _FORWARD[self.state]:
+            raise LifecycleError(
+                f"illegal transition {self.state.value} -> {target.value}"
+            )
+        self._record(target, note, at)
+
+    def _record(self, target: RunState, note: str, at: str | None) -> None:
+        stamp = at or dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds")
+        self.log.append(Transition(self.state, target, stamp, note))
+        self.state = target
+
+    def transcript(self) -> str:
+        """The manifest's state-transition line, generated rather than typed."""
+        states = [RunState.PRECHECK.value] + [t.target.value for t in self.log]
+        return " -> ".join(states)

financial_agent/harness/manifest.py

@@ -0,0 +1,113 @@
+"""Manifest sections generated from the package directory (plan §3.5 step 7).
+
+Three manifests in the history listed artifacts that were never written. The
+checklist here is read from disk after the files exist, next to the gate result,
+the status replay, and the content hash, so none of it is typed by a model.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from financial_agent.harness.fingerprint import artifact_digests, package_digest
+from financial_agent.harness.gates import (
+    ALWAYS_ARTIFACTS,
+    CHECKPOINT_ARTIFACTS,
+    PREDICTIONS_FILE,
+    StatusReplay,
+    publish_gate,
+    replay_status,
+)
+from financial_agent.harness.policy import Policy
+
+
+def replay_lines(replay: StatusReplay) -> list[str]:
+    """Calendar, structural GO blockers, and per-threshold rejections."""
+    lines = []
+    if replay.session is not None:
+        lines.append(f"Session: {replay.session.describe()}.")
+    reach = replay.reachability
+    if reach is not None:
+        if reach.reachable:
+            lines.append(
+                f"GO reachable with {', '.join(reach.gating_families)} scoring."
+            )
+        else:
+            lines.append("GO unreachable: " + "; ".join(reach.blockers) + ".")
+    if replay.blocking:
+        counts = ", ".join(f"{k}: {v}" for k, v in sorted(replay.blocking.items()))
+        lines.append(f"Names rejected per evidence threshold: {counts}.")
+    return lines
+
+
+def replay_dict(replay: StatusReplay) -> dict[str, Any]:
+    reach = replay.reachability
+    return {
+        "status": replay.decision.status.value,
+        "reasons": list(replay.decision.reasons),
+        "published": replay.published,
+        "agrees": replay.agrees,
+        "investable": replay.investable,
+        "session": None if replay.session is None else vars(replay.session),
+        "blocking": replay.blocking,
+        "go_reachable": None if reach is None else reach.reachable,
+        "go_blockers": [] if reach is None else list(reach.blockers),
+    }
+
+
+def gate_report(package_dir: Path, policy: Policy) -> dict[str, Any]:
+    """The publish gate, status replay, and content hash as one JSON object."""
+    failures = publish_gate(package_dir, policy)
+    replay = replay_status(package_dir, policy)
+    return {
+        "package": package_dir.name,
+        "pass": not failures,
+        "failures": failures,
+        "content_hash": f"sha256:{package_digest(package_dir)}",
+        "replay": None if replay is None else replay_dict(replay),
+    }
+
+
+def render_manifest_sections(
+    package_dir: Path, policy: Policy
+) -> tuple[str, list[str]]:
+    """Markdown for the manifest's generated sections, and the gate failures."""
+    digests = artifact_digests(package_dir)
+    failures = publish_gate(package_dir, policy)
+    lines = [
+        "## Artifact checklist (generated from the directory)",
+        "",
+        "| Artifact | Present | sha256 |",
+        "|---|---|---|",
+    ]
+    for name in (*ALWAYS_ARTIFACTS, PREDICTIONS_FILE):
+        digest = digests.get(name)
+        lines.append(
+            f"| `{name}` | {'yes' if digest else '**NO**'} | "
+            f"{f'`{digest[:12]}`' if digest else '-'} |"
+        )
+    for name in CHECKPOINT_ARTIFACTS:
+        if name in digests:
+            lines.append(f"| `{name}` (checkpoint) | yes | `{digests[name][:12]}` |")
+    lines += ["", f"Content hash: `sha256:{package_digest(package_dir)}`", ""]
+
+    replay = replay_status(package_dir, policy)
+    lines.append("## Status replay")
+    lines.append("")
+    if replay is None:
+        lines.append(f"No `{PREDICTIONS_FILE}`: nothing to replay.")
+    else:
+        reasons = "; ".join(replay.decision.reasons)
+        lines.append(
+            f"Replay: `{replay.decision.status.value}` ({reasons}); "
+            f"published: `{replay.published}`; "
+            f"{len(replay.investable)} investable. Required inputs assumed grounded."
+        )
+        lines += ["", *replay_lines(replay)]
+    lines += ["", "## Publish gate", ""]
+    if failures:
+        lines.extend(f"- FAIL: {failure}" for failure in failures)
+    else:
+        lines.append("PASS")
+    return "\n".join(lines), failures

financial_agent/harness/market_calendar.py

@@ -0,0 +1,50 @@
+"""The exchange calendar for run dates: one rule set for every model.
+
+The same market holiday has been labelled three ways in the run history, and
+weekend runs publish ``REVIEW_ONLY`` under one model and ``NO_TRADE`` under
+another. A session is computed here from the NYSE calendar that
+``settlement_ledger.py`` already uses for settlement timing, so status replay,
+the run driver, and settlement agree on what a trading day is.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+
+from financial_agent.harness.helpers import load_helper
+
+TRADING = "TRADING"
+WEEKEND = "WEEKEND"
+HOLIDAY = "HOLIDAY"
+
+
+@dataclass(frozen=True)
+class Session:
+    date: str
+    kind: str  # TRADING | WEEKEND | HOLIDAY
+    basis_date: str  # the most recent trading day at or before ``date``
+
+    @property
+    def trading_day(self) -> bool:
+        return self.kind == TRADING
+
+    def describe(self) -> str:
+        if self.trading_day:
+            return f"{self.date} is a trading day"
+        what = "a weekend" if self.kind == WEEKEND else "a market holiday"
+        return f"{self.date} is {what}; last close {self.basis_date}"
+
+
+def session(day: str | dt.date) -> Session:
+    """Classify ``day`` (``YYYY-MM-DD``) against the NYSE calendar."""
+    date = dt.date.fromisoformat(day) if isinstance(day, str) else day
+    ledger = load_helper("settlement_ledger")
+    if ledger.is_trading_day(date):
+        kind = TRADING
+    elif date.weekday() >= 5:
+        kind = WEEKEND
+    else:
+        kind = HOLIDAY
+    basis = ledger.most_recent_trading_day_at_or_before(date)
+    return Session(date.isoformat(), kind, basis.isoformat())