@senpi/runtime 3.0.9-dev.20260710204324 → 3.0.9-dev.feat-strategy-compos.20260716233548

package/dist/composer/authoring/answers.py

@@ -0,0 +1,297 @@
+"""answers — the typed interview-answers object (D7 step 1; the elicitation contract).
+
+The 7 decisions are the *type signature of* ``scan(...)`` (HLD "Elicitation"): archetype,
+universe, intervals, cardinality, memory, exit preset, and risk knobs, plus the user's
+EDGE carried verbatim as free text the machine never interprets. This module is the typed
+form of that contract. It is deliberately entry-mode agnostic — a structured authoring
+session and an ambient "make a strategy from this" both land here; ``composer new`` does
+not care where the answers came from.
+
+Two acceptance paths, one contract (D7):
+  * an answers-file (YAML or JSON) parsed into a dict, and/or
+  * individual CLI flags that OVERRIDE the file field-by-field.
+Both feed :func:`load_answers`, which deep-merges (flags win) and constructs :class:`Answers`.
+
+Answer domains are registry-derived where possible (D4): a strategy that names a source or
+capability the registry does not have is not a crash — it is turned into a structured GAP
+REPORT before anything is written (see ``composer.authoring.gaps``). The
+:attr:`Answers.requires` field is how an answer references registry capability names: each
+entry is checked against the registry and, if absent, named in the gap report.
+
+Exit / protection (slice 9 — PROTECTION BY DEFAULT). ``exit_preset`` is now LIVE (default
+``protected_standard``): the composer emits a complete standalone ``runtime.yaml`` whose
+``exit:`` section is the resolved preset (``composer.authoring.presets``). ``unmanaged=True``
+is the explicit, deliberate opt-out (no exit section); leaving it False without an exit is a
+RED check (CMP120). The ``Risk`` model also carries the guard-rail / pause knobs the composer
+owns (drawdown halt, post-loss cooldown, entry cap) — declarative ``runtime.yaml`` fields the
+runtime enforces (design §4).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class Risk(BaseModel):
+    """Sizing knobs + the guard-rail / pause knobs the composer owns (D7 step 3; design §4).
+
+    ``margin_pct``/``leverage`` size the emitted signal. The four pause knobs are optional
+    overrides onto the preset's ``risk.guard_rails`` default — ``None`` means "use the
+    preset default" (``composer.authoring.presets.resolve_guard_rails``). These are
+    declarative ``runtime.yaml`` fields the runtime enforces (auto-halt / post-loss cooldown /
+    per-day entry cap); a LIVE operational pause (stopping the box) is an ops action, not the
+    composer's (design §4)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    margin_pct: float = 5.0   # PERCENT of withdrawable, (0,100] (never a fraction/USD)
+    leverage: float = 3.0
+    # guard_rails overrides (None -> preset default); see presets.resolve_guard_rails.
+    drawdown_halt_pct: Optional[float] = None       # equity-drawdown circuit breaker (halt %)
+    max_consecutive_losses: Optional[int] = None    # stop after N losses
+    cooldown_seconds: Optional[int] = None          # post-loss cooldown (>= 60)
+    max_entries_per_day: Optional[int] = None        # per-day entry cap (>= 1)
+
+
+class Universe(BaseModel):
+    """How the tradeable set is chosen. A superset of the corpus shapes; each archetype
+    reads the fields it needs (D4 — the answer stays declarative, the template binds it):
+
+      * ``whitelist``               — a fixed asset list (stag/hawk/bison shape).
+      * ``long_basket``/``short_basket`` — the two legs of a fixed macro basket (thesis-fund).
+      * ``discover`` (+ params)     — derive the universe each tick from the live instrument
+                                      board by a funding/leverage/volume signature (magpie).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    whitelist: tuple[str, ...] = ()
+    long_basket: tuple[str, ...] = ()
+    short_basket: tuple[str, ...] = ()
+    discover: bool = False
+    dex: str = ""
+    name_prefix: str = ""
+    max_leverage_cap: float = 5.0
+    min_day_volume: float = 0.0
+
+
+class Scoring(BaseModel):
+    """OPTIONAL re-selection of the scorer's hard gates / weighted contributors / floor (F1).
+
+    The scoring surface lets the answers move the hard-vs-weighted split AMONG the graph's
+    feature nodes without hand-editing the emitted graph. Every field is ``None`` = "keep the
+    archetype's working default"; a set field OVERRIDES it (D7 "answers override else current
+    defaults"). Names are SOURCE NODE IDS — the same keys the scorer merges its ``features`` by
+    (e.g. ``breakout_detect`` wired as ``brk`` is referenced as ``"brk"``). A name matching no
+    feature node in the graph is a generation error (``archetypes._common.resolve_scoring``),
+    never a silent drop. Absent entirely (the default), the emitted graph is byte-identical to
+    the pre-F1 output."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    required_gates: Optional[tuple[str, ...]] = None   # feature ids that must ALL be truthy
+    weights: Optional[dict[str, float]] = None          # feature id -> weighted-sum weight
+    min_score: Optional[float] = None                   # minimum score to emit
+
+
+class Indicator(BaseModel):
+    """An ADDITIONAL registry indicator node the answers ask the archetype to add and wire (F1).
+
+    Each entry adds a real registry node (``node``) under ``id``, feeds it the graph's candles,
+    and merges its feature output into the scorer's ``features`` — so the id becomes addressable
+    from :class:`Scoring` (as a gate or a weight). ``with`` carries the node's params; ``port``
+    names which output feeds the scorer (defaults to the node's sole output). A ``node`` the
+    registry lacks — or a ``port`` the node does not declare — is a generation error, never a
+    silent drop. This is how an answer requests, e.g., ``breakout_detect`` with ``window: 168``
+    on an archetype whose fixed indicator set does not already carry it.
+
+    ``source`` (optional, C1b) CHAINS this indicator's input off another feature node instead
+    of the graph's candles: when set, the node's data input wires from ``source``'s output
+    (``source`` names an EARLIER ``indicators`` entry's id or a built-in feature node of the
+    archetype), with the port types checked against the registry — a mismatch or an unknown
+    ``source`` is a generation error. This is what lets a ``threshold_gate`` read a raw
+    ``recent_high_bars_ago`` output (``fresh = threshold_gate(op: lte, value: 5, source:
+    fresh_raw)``) — a thresholded gate, not the inverted truthiness gate the raw feature had."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    id: str
+    node: str
+    with_: dict[str, Any] = Field(default_factory=dict, alias="with")
+    port: Optional[str] = None
+    source: Optional[str] = None
+
+
+class RequiredCapability(BaseModel):
+    """A registry capability an answer says the strategy needs (D4 feasibility surface).
+
+    ``name`` is matched against the registry; a name the registry lacks becomes a gap-report
+    entry. ``kind`` and ``need`` are carried into the report so the boundary reads honestly
+    ("``top_traders_discovery`` (source): rank traders by realized PnL") rather than as a
+    bare missing symbol.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    kind: str = "node"
+    need: str = ""
+
+
+class Answers(BaseModel):
+    """The typed interview answers — a COMPLETE, VALID graph's input (D7 step 1)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    archetype: str
+    strategy: str = "unnamed"
+    universe: Universe = Field(default_factory=Universe)
+    intervals: tuple[str, ...] = ("4h",)
+    max_positions: int = 1          # cardinality -> ranker choice (single-best vs pool-cap)
+    ttl_seconds: int = 240          # memory -> ttl_dedup_state dedup window
+    # LIVE: emitted as the runtime.yaml exit: section. Default None = "unset"; `composer new`
+    # BINDS protected_standard unless overridden (protection-by-default). A graph reaching
+    # `check` with exit_preset unset AND unmanaged False is the RED CMP120 contradiction.
+    exit_preset: Optional[str] = None
+    unmanaged: bool = False         # explicit opt-out: no exit section (else CMP120 RED at check)
+    risk: Risk = Field(default_factory=Risk)
+    edge: str = ""                  # the user's EDGE, verbatim; the machine never interprets it
+    requires: tuple[RequiredCapability, ...] = ()
+    # F1 — OPTIONAL expressiveness surface. Absent (the defaults below) => byte-identical to
+    # the pre-F1 output; present => the archetype re-selects gates/weights (scoring) and adds
+    # registry indicator nodes (indicators) mechanically, no hand edit. See the two submodels.
+    scoring: Optional[Scoring] = None
+    indicators: tuple[Indicator, ...] = ()
+
+    @field_validator("exit_preset")
+    @classmethod
+    def _known_preset(cls, value: Optional[str]) -> Optional[str]:
+        """Reject an unknown exit preset early (a typo, not a crash). ``None`` is allowed (unset
+        -> `composer new` binds the default, or `check` flags CMP120). Names live in
+        ``composer.authoring.presets.EXIT_PRESETS`` (protection-by-default policy)."""
+        if value is None:
+            return None
+        from .presets import EXIT_PRESETS  # local import: presets is answers-independent
+        if value not in EXIT_PRESETS:
+            raise ValueError(
+                f"unknown exit_preset {value!r}; choose one of {sorted(EXIT_PRESETS)} "
+                f"(or pass unmanaged=true to deliberately run with NO exit protection)."
+            )
+        return value
+
+    @field_validator("requires", mode="before")
+    @classmethod
+    def _coerce_requires(cls, value: Any) -> Any:
+        """Accept `requires:` entries as bare strings or full mappings."""
+        if value is None:
+            return ()
+        out = []
+        for item in value:
+            if isinstance(item, str):
+                out.append({"name": item})
+            else:
+                out.append(item)
+        return out
+
+    def metadata_block(self) -> dict:
+        """The answers as an ordered plain-dict for the emitted graph's metadata (D7:
+        the spec file IS the state; interview answers live in the metadata block)."""
+        block: dict = {
+            "archetype": self.archetype,
+            "strategy": self.strategy,
+            "universe": {
+                "whitelist": list(self.universe.whitelist),
+                "long_basket": list(self.universe.long_basket),
+                "short_basket": list(self.universe.short_basket),
+                "discover": self.universe.discover,
+                "dex": self.universe.dex,
+                "name_prefix": self.universe.name_prefix,
+                "max_leverage_cap": self.universe.max_leverage_cap,
+                "min_day_volume": self.universe.min_day_volume,
+            },
+            "intervals": list(self.intervals),
+            "max_positions": self.max_positions,
+            "ttl_seconds": self.ttl_seconds,
+            "exit_preset": self.exit_preset,   # LIVE: the emitted runtime.yaml exit preset
+            "unmanaged": self.unmanaged,        # explicit protection opt-out
+            "risk": {
+                "margin_pct": self.risk.margin_pct,
+                "leverage": self.risk.leverage,
+                "drawdown_halt_pct": self.risk.drawdown_halt_pct,
+                "max_consecutive_losses": self.risk.max_consecutive_losses,
+                "cooldown_seconds": self.risk.cooldown_seconds,
+                "max_entries_per_day": self.risk.max_entries_per_day,
+            },
+            "edge": self.edge,
+            "requires": [
+                {"name": c.name, "kind": c.kind, "need": c.need} for c in self.requires
+            ],
+        }
+        # F1: emit the optional surface ONLY when set, so answers without it round-trip
+        # byte-identically to the pre-F1 metadata block (the HARD regression constraint).
+        # Both survive `Answers(**block)` deterministically (the deploy metadata re-derive path).
+        if self.scoring is not None:
+            scoring: dict = {}
+            if self.scoring.required_gates is not None:
+                scoring["required_gates"] = list(self.scoring.required_gates)
+            if self.scoring.weights is not None:
+                scoring["weights"] = dict(self.scoring.weights)
+            if self.scoring.min_score is not None:
+                scoring["min_score"] = self.scoring.min_score
+            block["scoring"] = scoring
+        if self.indicators:
+            block["indicators"] = [
+                {"id": i.id, "node": i.node, "with": dict(i.with_), "port": i.port,
+                 "source": i.source}
+                for i in self.indicators
+            ]
+        return block
+
+
+def _deep_merge(base: dict, over: dict) -> dict:
+    """Field-by-field merge (``over`` wins); nested dicts merge, scalars/lists replace."""
+    out = dict(base)
+    for key, val in over.items():
+        if isinstance(val, dict) and isinstance(out.get(key), dict):
+            out[key] = _deep_merge(out[key], val)
+        else:
+            out[key] = val
+    return out
+
+
+def load_answers_file(path: str | Path) -> dict:
+    """Parse a YAML or JSON answers-file into a plain dict (raises on non-mapping)."""
+    text = Path(path).read_text(encoding="utf-8")
+    data = yaml.safe_load(text)          # YAML is a JSON superset, so this reads both (D6)
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError(f"answers file {path} must be a mapping, got {type(data).__name__}")
+    return data
+
+
+def load_answers(
+    file_data: Optional[dict] = None,
+    overrides: Optional[dict] = None,
+) -> Answers:
+    """Build :class:`Answers` from an optional answers-file dict + CLI-flag overrides.
+
+    Overrides win field-by-field (D7: "individual flag overrides"). Unknown keys raise a
+    pydantic ``ValidationError`` (``extra="forbid"``) so a typo is caught, not silently
+    dropped.
+    """
+    merged = _deep_merge(file_data or {}, overrides or {})
+    return Answers(**merged)
+
+
+def dumps_answers_template(archetype: str) -> str:
+    """A blank answers-file skeleton for an archetype (used by `composer new --help`-style
+    scaffolding and the docs); deterministic."""
+    return yaml.safe_dump(
+        Answers(archetype=archetype).metadata_block(), sort_keys=False
+    )

package/dist/composer/authoring/archetypes/__init__.py

@@ -0,0 +1,26 @@
+"""archetypes — the CI-checked archetype templates (D7 step 2; HLD "templates are derived").
+
+Each archetype is CODE that builds a graph from the same registry types (see
+``composer.authoring.builder``), so a template that names a nonexistent node/port fails at
+construction — the CI guarantee that templates cannot drift from the vocabulary. The
+archetypes the POC graphs need are here (trend_momentum / breakout / classifier /
+thesis_fund); an unrecognised archetype falls to the minimal ``skeleton`` (D7 step 5), which
+is NOT in ``ARCHETYPES`` because "no matching archetype" is its trigger.
+
+Each module exposes ``build(answers) -> GraphBuilder`` and a ``BANNER`` header.
+"""
+
+from __future__ import annotations
+
+from . import breakout, classifier, skeleton, thesis_fund, trend_momentum
+
+ARCHETYPES = {
+    "trend_momentum": trend_momentum,
+    "breakout": breakout,
+    "classifier": classifier,
+    "thesis_fund": thesis_fund,
+}
+
+SKELETON = skeleton
+
+__all__ = ["ARCHETYPES", "SKELETON"]