gooseloop 0.1.0__py3-none-any.whl

gooseloop/phase.py

@@ -0,0 +1,146 @@
+"""Core data types: Phase, Pipeline, Context.
+
+See ADRs 0001, 0006, 0007 and PROTOCOL.md for the contracts these
+types implement. The Pipeline is the bookend dataclass with named review /
+body / summary slots; Context carries typed methods for body phases to
+extend the session ledger.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from .protocol import OperatorAction, RoutingEntry
+
+if TYPE_CHECKING:
+    from .environment import Environment
+
+
+@dataclass
+class Context:
+    """Carried through a single begin_loop() pass.
+
+    `session_dir` is None when the Looper was constructed with save=False.
+    `artifacts` is the engine's scratchpad; engines store extension data
+    here and read each other's contributions across phases. The framework
+    reserves a few well-known keys:
+
+        artifacts["review_output"] -> dict (the parsed ReviewOutput payload)
+        artifacts["operator_actions"] -> list[OperatorAction]
+        artifacts["outputs_written"] -> list[str]
+
+    Body phases should mutate these via the typed methods below
+    (add_operator_action / record_output / session_log) rather than poking
+    artifacts directly; the methods enforce the schema.
+    """
+    model: str
+    session_dir: Optional[Path]
+    base_env: dict[str, str]
+    artifacts: dict[str, Any] = field(default_factory=dict)
+    environment: Optional["Environment"] = None
+
+    def add_operator_action(self, action: str, why: str = "", **extras: Any) -> None:
+        """Append an operator action to the session ledger.
+
+        Dedup is by (action, why); calling twice with the same pair is a
+        no-op so cadence phases that re-detect the same condition do not
+        flood the ledger. Extras are stored alongside.
+
+        `action` must be a non-empty string. `why` is optional and may
+        be empty — some actions don't need a stated reason; the action
+        itself is the operator-facing artifact.
+        """
+        if not isinstance(action, str) or not action:
+            raise TypeError("add_operator_action: 'action' must be a non-empty str")
+        if not isinstance(why, str):
+            raise TypeError("add_operator_action: 'why' must be a str (may be empty)")
+        ledger: list[OperatorAction] = self.artifacts.setdefault("operator_actions", [])
+        for existing in ledger:
+            if existing.get("action") == action and existing.get("why") == why:
+                return
+        entry: OperatorAction = {"action": action, "why": why}
+        entry.update(extras)  # type: ignore[typeddict-item]
+        ledger.append(entry)
+
+    @property
+    def operator_actions(self) -> list[OperatorAction]:
+        """Read-only view of the current ledger. Mutate via add_operator_action."""
+        return list(self.artifacts.get("operator_actions", []))
+
+    def record_output(self, path: Path | str) -> None:
+        """Track a file body phases produced. Summary and footer render these."""
+        outputs: list[str] = self.artifacts.setdefault("outputs_written", [])
+        as_str = str(path)
+        if as_str not in outputs:
+            outputs.append(as_str)
+
+    def session_log(self, message: str) -> None:
+        """Append a timestamped line to the session log, if a session is open."""
+        if self.session_dir is None:
+            return
+        from .session import log_step
+        log_step(self.session_dir, message)
+
+    @property
+    def review_routing(self) -> list[RoutingEntry]:
+        """Routing entries the review emitted (frozen at bookend)."""
+        return list(self.artifacts.get("review_routing", []))
+
+
+# Callable type aliases for Phase fields.
+BuildEnv = Callable[[Context], dict[str, str]]
+SuccessPredicate = Callable[[str], bool]
+PostProcess = Callable[[str, Context], Optional[list["Phase"]]]
+# SkipIf returns falsy to run, True for a generic skip, or a str carrying
+# the reason. The reason lands in the session log.
+SkipIf = Callable[[Context], "bool | str | None"]
+
+
+def _empty_env(_ctx: Context) -> dict[str, str]:
+    return {}
+
+
+@dataclass
+class Phase:
+    """A single recipe invocation, with optional pre/post hooks.
+
+    Attributes:
+        name: shown in banners and logs.
+        recipe_path: relative path to the recipe yaml.
+        build_env: returns env vars merged with base_env for this call.
+        success_predicate: optional override for "did this attempt succeed?".
+            None falls through to the looper's transient-error check.
+        post_process: called after a successful run. May return a list of
+            child Phases for the Looper to enqueue.
+        skip_if: called before the recipe runs. Truthy return skips the
+            Phase. A string return is used as the skip reason in the log.
+        label: optional override for the per-call footer label. Useful when
+            multiple phases reuse the same recipe (review-spawned branches).
+    """
+    name: str
+    recipe_path: str
+    build_env: BuildEnv = _empty_env
+    success_predicate: Optional[SuccessPredicate] = None
+    post_process: Optional[PostProcess] = None
+    skip_if: Optional[SkipIf] = None
+    label: Optional[str] = None
+
+
+@dataclass
+class Pipeline:
+    """Named-slot pipeline. Framework owns review-first / summary-last ordering.
+
+    Engines return this from Engine.pipeline(). Per ADR 0006:
+
+        - review runs first; its post_process and the framework parse the
+          review output and spawn child phases (via the BranchPolicy
+          registry) that go to the HEAD of the body queue.
+        - body runs after, in queue order. May be empty.
+        - summary runs last, with access to the final operator_actions
+          ledger and outputs list.
+
+    `--review-only` runs review and stops; body and summary skip.
+    """
+    review: Phase
+    body: list[Phase] = field(default_factory=list)
+    summary: Optional[Phase] = None

gooseloop/predicates.py

@@ -0,0 +1,69 @@
+"""Reusable success-predicate factories.
+
+A Phase's success_predicate decides whether a recipe attempt succeeded.
+Three named shapes cover the common cases:
+
+    file_freshly_touched(path, pre_mtime)  - strict: exists, non-empty, newer than pre_mtime
+    file_nonempty(path)                    - loose: exists and non-empty
+    json_in_stdout(required_keys)          - sentinel JSON parses and has keys
+
+Phase(success_predicate=None) falls through to the looper's transient-error
+check; that is the explicit "no extra validation" option. No no-op
+predicate factory is shipped (per YAGNI; six characters of lambda if a
+recipe ever genuinely needs one).
+"""
+
+from pathlib import Path
+from typing import Callable, Iterable
+
+from .extract import extract_json
+
+
+SuccessPredicate = Callable[[str], bool]
+
+
+def file_freshly_touched(path: Path, pre_mtime: float = 0.0) -> SuccessPredicate:
+    """Strict: `path` exists, is non-empty, AND its mtime is strictly newer
+    than `pre_mtime`.
+
+    Snapshot pre_mtime BEFORE the recipe runs; if the file didn't exist,
+    pass 0.0. Use when the recipe writes to a deterministic path and you
+    need to detect both "model didn't write" and "model wrote a different
+    file so this one is stale."
+    """
+    def predicate(_output: str) -> bool:
+        if not path.exists():
+            return False
+        if path.stat().st_size == 0:
+            return False
+        return path.stat().st_mtime > pre_mtime
+    return predicate
+
+
+def file_nonempty(path: Path) -> SuccessPredicate:
+    """Loose: `path` exists and is non-empty.
+
+    Safe only when you already know the file didn't exist before the
+    recipe ran (otherwise a pre-existing file passes without proof the
+    recipe wrote anything).
+    """
+    def predicate(_output: str) -> bool:
+        return path.exists() and path.stat().st_size > 0
+    return predicate
+
+
+def json_in_stdout(required_keys: Iterable[str] | None = None) -> SuccessPredicate:
+    """The recipe's stdout contains sentinel-wrapped JSON with all required_keys.
+
+    Use for stdout-deliverable recipes (the JSON IS the artifact). Catches
+    the "model emitted a thin stub instead of the full schema" failure
+    mode.
+    """
+    keys = list(required_keys or [])
+
+    def predicate(output: str) -> bool:
+        data = extract_json(output)
+        if data is None:
+            return False
+        return all(k in data for k in keys)
+    return predicate

gooseloop/protocol.py

@@ -0,0 +1,197 @@
+"""TypedDicts and validation for the gooseloop review protocol.
+
+See PROTOCOL.md for the canonical contract and ADR 0007 for
+the rationale. The framework reads these keys; engines may add arbitrary
+extension keys to any of these structures.
+
+Validation is **liberal in what it accepts, strict in what the schema
+guarantees on the way out**:
+
+  - Status synonyms (success/ok/complete/failed/incomplete/...) canonicalise
+    to the three-value enum. Unknown synonyms raise.
+  - Non-load-bearing keys (insights, operator_actions) default to [] when
+    missing. They're informational; absence is "model had nothing to say"
+    not "model broke the contract."
+  - Load-bearing keys (protocol_version, status, summary, routing) are
+    strictly required. Absence means the review can't drive the framework.
+  - protocol_version major must match what we ship.
+
+This is the validate-side companion to the parser-side leniency in
+gooseloop.extract: accept what's obviously the same intent in a slightly
+different shape, fail loud on actual contract violations.
+"""
+
+from typing import Any, Literal, TypedDict
+
+
+PROTOCOL_VERSION = "1.0"
+PROTOCOL_MAJOR = 1
+
+
+class RoutingEntry(TypedDict, total=False):
+    """One entry in the review's routing[] list."""
+    recipe: str
+    params: dict[str, Any]
+    reason: str
+
+
+class OperatorAction(TypedDict, total=False):
+    """One entry in the session's operator_actions ledger."""
+    action: str
+    why: str
+
+
+ReviewStatus = Literal["done", "partial", "error"]
+
+
+class ReviewOutput(TypedDict, total=False):
+    """Canonical review payload after validation."""
+    protocol_version: str
+    status: ReviewStatus
+    summary: str
+    insights: list[str]
+    routing: list[RoutingEntry]
+    operator_actions: list[OperatorAction]
+
+
+# Keys the framework can't function without. A review missing any of
+# these can't drive routing or the session ledger; refuse loud.
+REQUIRED_KEYS = ("protocol_version", "status", "summary", "routing")
+
+# Keys the framework reads but treats as optional in the schema. Missing
+# = "model had nothing to add"; default to empty list and proceed.
+DEFAULTED_LIST_KEYS = ("insights", "operator_actions")
+
+# Status synonyms. Models drift on the status enum more than on any
+# other field; canonicalise here so downstream code only sees the three
+# canonical values. Unknown values raise (a fresh synonym should land
+# in this table, not slip past the validator).
+_STATUS_SYNONYMS: dict[str, ReviewStatus] = {
+    "done": "done",
+    "success": "done",
+    "ok": "done",
+    "complete": "done",
+    "completed": "done",
+    "finished": "done",
+    "partial": "partial",
+    "incomplete": "partial",
+    "in_progress": "partial",
+    "in-progress": "partial",
+    "pending": "partial",
+    "error": "error",
+    "errored": "error",
+    "failed": "error",
+    "failure": "error",
+    "broken": "error",
+}
+
+
+class ProtocolVersionError(RuntimeError):
+    """Raised when a review declares a major version the framework does not support."""
+
+
+def validate_review(payload: dict) -> ReviewOutput:
+    """Canonicalise + validate a review payload.
+
+    Returns a NEW dict with synonyms canonicalised, defaulted lists
+    filled in, and entry shapes normalised. The original payload is
+    not mutated.
+
+    Normalisations performed (liberal in what we accept):
+
+      - status: synonyms ("success", "ok", ...) collapse to the
+        three-value enum.
+      - insights/operator_actions: missing or None becomes [].
+      - operator_actions entries: a bare string becomes
+        {"action": <string>, "why": ""}. A dict missing "why" gets
+        why="". Malformed entries (non-string, non-dict, or dict with
+        no "action") are dropped.
+      - routing entries: a dict missing optional fields gets default
+        params={} and reason="". Entries without a "recipe" string
+        are dropped.
+    """
+    missing = [k for k in REQUIRED_KEYS if k not in payload]
+    if missing:
+        raise ValueError(f"review missing required keys: {missing}")
+
+    _check_protocol_version(str(payload["protocol_version"]))
+
+    raw_status = str(payload["status"]).strip().lower()
+    canonical_status = _STATUS_SYNONYMS.get(raw_status)
+    if canonical_status is None:
+        raise ValueError(
+            f"review status {payload['status']!r} not recognised "
+            f"(known: {sorted(set(_STATUS_SYNONYMS))})"
+        )
+
+    out: dict[str, Any] = dict(payload)
+    out["status"] = canonical_status
+    for key in DEFAULTED_LIST_KEYS:
+        if key not in out or out[key] is None:
+            out[key] = []
+    out["operator_actions"] = _normalise_operator_actions(out["operator_actions"])
+    out["routing"] = _normalise_routing(out["routing"])
+    return out  # type: ignore[return-value]
+
+
+def _normalise_operator_actions(entries: Any) -> list[OperatorAction]:
+    """Coerce loose shapes into well-formed OperatorAction dicts."""
+    if not isinstance(entries, list):
+        return []
+    out: list[OperatorAction] = []
+    for entry in entries:
+        if isinstance(entry, str):
+            action = entry.strip()
+            if action:
+                out.append({"action": action, "why": ""})  # type: ignore[typeddict-item]
+            continue
+        if isinstance(entry, dict):
+            action = str(entry.get("action", "")).strip()
+            if not action:
+                continue
+            normalised: OperatorAction = {  # type: ignore[typeddict-item]
+                "action": action,
+                "why": str(entry.get("why", "")),
+            }
+            for k, v in entry.items():
+                if k not in ("action", "why"):
+                    normalised[k] = v  # type: ignore[literal-required]
+            out.append(normalised)
+    return out
+
+
+def _normalise_routing(entries: Any) -> list[RoutingEntry]:
+    """Coerce loose shapes into well-formed RoutingEntry dicts."""
+    if not isinstance(entries, list):
+        return []
+    out: list[RoutingEntry] = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        recipe = entry.get("recipe")
+        if not isinstance(recipe, str) or not recipe.strip():
+            continue
+        normalised: RoutingEntry = {  # type: ignore[typeddict-item]
+            "recipe": recipe.strip(),
+            "params": entry.get("params") if isinstance(entry.get("params"), dict) else {},
+            "reason": str(entry.get("reason", "")),
+        }
+        out.append(normalised)
+    return out
+
+
+def _check_protocol_version(declared: str) -> None:
+    try:
+        major = int(declared.split(".", 1)[0])
+    except (ValueError, IndexError):
+        raise ProtocolVersionError(
+            f"protocol_version {declared!r} is not parseable; "
+            f"framework supports major {PROTOCOL_MAJOR}"
+        )
+    if major != PROTOCOL_MAJOR:
+        raise ProtocolVersionError(
+            f"review declares protocol_version {declared!r} (major {major}); "
+            f"framework supports major {PROTOCOL_MAJOR} only"
+        )
+
+

gooseloop/recipe_merge.py

@@ -0,0 +1,152 @@
+"""Compose-style recipe overlay merge.
+
+Per ADR 0008 and PROTOCOL.md §6. Two YAML documents merge according to a
+type-and-name-dispatched rule table:
+
+    scalars           - later wins (full replace)
+    dicts             - deep-merge; scalar leaves: later wins
+    context list      - keyed by 'label'; same label overrides, new appends
+    extensions list   - keyed by (type, name); same key overrides, new appends
+    plain lists       - later replaces fully
+
+A keyed-list overlay entry with `source: REMOVE` (the removal sentinel)
+deletes that entry from the merge result.
+
+Layer order is `merge_recipes(base, *overlays)`; later overlays override
+earlier ones. The looper composes layers in the order: base file ->
+<name>.local.yaml -> --review-overlay X1 -> --review-overlay X2 -> ...
+"""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+REMOVE_SENTINEL = "REMOVE"
+
+
+def merge_recipes(base: dict, *overlays: dict) -> dict:
+    """Merge `base` with successive overlays, returning a new dict.
+
+    The merge is pure: input dicts are never mutated. Per ADR 0008 the
+    merge rules dispatch on field name (for keyed lists) and value type
+    (everything else).
+    """
+    out = _copy(base)
+    for overlay in overlays:
+        out = _merge_dict(out, overlay, path=())
+    return out
+
+
+def load_layered_recipe(
+    base_path: Path,
+    *,
+    local_path: Path | None = None,
+    overlay_paths: list[Path] | None = None,
+) -> dict:
+    """Resolve a recipe by loading base + local + CLI overlays.
+
+    Convention: `<name>.local.yaml` sits next to the base recipe in the
+    same directory; the caller computes the local path and passes it.
+    Missing local file is fine (skipped).
+    """
+    base = _read_yaml(base_path)
+    overlays: list[dict] = []
+    if local_path is not None and local_path.exists():
+        overlays.append(_read_yaml(local_path))
+    for p in overlay_paths or []:
+        overlays.append(_read_yaml(p))
+    return merge_recipes(base, *overlays)
+
+
+def resolved_recipe_yaml(merged: dict) -> str:
+    """Render the merged recipe back to YAML (for --resolve debug output)."""
+    return yaml.safe_dump(merged, sort_keys=False, default_flow_style=False)
+
+
+# ---- internals ------------------------------------------------------
+
+# Keyed-list rules: list-field name -> the key function on each entry.
+_KEYED_LISTS: dict[str, Any] = {
+    "context": lambda entry: entry.get("label"),
+    "extensions": lambda entry: (entry.get("type"), entry.get("name")),
+}
+
+
+def _read_yaml(path: Path) -> dict:
+    text = path.read_text()
+    data = yaml.safe_load(text)
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ValueError(f"recipe at {path} must be a YAML mapping at top level")
+    return data
+
+
+def _copy(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {k: _copy(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_copy(v) for v in value]
+    return value
+
+
+def _merge_dict(base: dict, overlay: dict, *, path: tuple[str, ...]) -> dict:
+    out = _copy(base)
+    for k, ov in overlay.items():
+        if k not in out:
+            out[k] = _copy(ov)
+            continue
+        bv = out[k]
+        if isinstance(bv, dict) and isinstance(ov, dict):
+            out[k] = _merge_dict(bv, ov, path=path + (k,))
+        elif isinstance(bv, list) and isinstance(ov, list):
+            out[k] = _merge_list(bv, ov, list_name=k)
+        else:
+            out[k] = _copy(ov)
+    return out
+
+
+def _merge_list(base: list, overlay: list, *, list_name: str) -> list:
+    keyer = _KEYED_LISTS.get(list_name)
+    if keyer is None:
+        # Plain list: later replaces fully.
+        return _copy(overlay)
+    return _merge_keyed_list(base, overlay, keyer=keyer)
+
+
+def _merge_keyed_list(base: list, overlay: list, *, keyer) -> list:
+    """Merge two keyed lists by item identity.
+
+    Walk overlay in order. For each entry:
+      - If key matches an existing base entry: merge fields (overlay wins).
+        REMOVE sentinel on `source` field deletes the base entry.
+      - If key is new: append to the result.
+
+    Preserves base order for retained entries; new entries land at the
+    end in overlay order.
+    """
+    result: list = [_copy(b) for b in base]
+    by_key: dict[Any, int] = {}
+    for i, entry in enumerate(result):
+        if isinstance(entry, dict):
+            by_key[keyer(entry)] = i
+
+    for entry in overlay:
+        if not isinstance(entry, dict):
+            result.append(_copy(entry))
+            continue
+        key = keyer(entry)
+        if key in by_key:
+            if entry.get("source") == REMOVE_SENTINEL:
+                idx = by_key.pop(key)
+                result[idx] = None  # tombstone
+                continue
+            idx = by_key[key]
+            merged = _merge_dict(result[idx], entry, path=())
+            result[idx] = merged
+        else:
+            result.append(_copy(entry))
+
+    return [r for r in result if r is not None]

gooseloop/session.py

@@ -0,0 +1,41 @@
+"""Session folder management: create timestamped dirs, log steps.
+
+The Looper owns the session layout:
+
+    <sessions_dir>/<UTC-timestamp>/
+        session.meta.json   - model, engine, timestamps
+        session.log         - append-only event log
+        actions/            - Phase outputs land here
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .text import Color, banner
+
+
+def new_session(sessions_dir: Path, model: str, engine_name: str) -> Path:
+    """Create a timestamped session directory and print a banner."""
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H-%M-%S")
+    session_dir = sessions_dir / ts
+    session_dir.mkdir(parents=True, exist_ok=True)
+    (session_dir / "actions").mkdir(exist_ok=True)
+
+    meta = {
+        "session_started": datetime.now(timezone.utc).isoformat(),
+        "model": model,
+        "engine": engine_name,
+    }
+    with open(session_dir / "session.meta.json", "w") as f:
+        json.dump(meta, f, indent=2)
+
+    banner(f"Session started: {session_dir}", Color.GREEN)
+    return session_dir
+
+
+def log_step(session_dir: Path, message: str) -> None:
+    """Append a timestamped line to session.log."""
+    ts = datetime.now(timezone.utc).isoformat()
+    with open(session_dir / "session.log", "a") as f:
+        f.write(f"[{ts}] {message}\n")

gooseloop/text.py

@@ -0,0 +1,60 @@
+"""Terminal text helpers: ANSI colours, banners, ANSI stripping.
+
+JSON extraction used to live here; it moved to gooseloop/extract.py once
+it grew a recognizer dispatch table. text.py is now scoped strictly to
+terminal-output utilities.
+"""
+
+import re
+
+
+class Color:
+    RESET   = '\033[0m'
+    BOLD    = '\033[1m'
+    RED     = '\033[91m'
+    GREEN   = '\033[92m'
+    YELLOW  = '\033[93m'
+    BLUE    = '\033[94m'
+    MAGENTA = '\033[95m'
+    CYAN    = '\033[96m'
+    WHITE   = '\033[97m'
+
+
+def colored(text: str, color: str) -> str:
+    return f"{color}{text}{Color.RESET}"
+
+
+_ANSI_RE = re.compile(r'\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])')
+
+
+def strip_ansi(text: str) -> str:
+    return _ANSI_RE.sub('', text)
+
+
+def banner(text: str, color: str = Color.CYAN, width: int = 70) -> None:
+    """Print a colourful double-line box around the given text."""
+    top = "╔" + "═" * (width - 2) + "╗"
+    bot = "╚" + "═" * (width - 2) + "╝"
+
+    max_text_width = width - 4
+    words = text.split()
+    lines: list[str] = []
+    current = ""
+    for w in words:
+        if len(current) + len(w) + 1 > max_text_width:
+            lines.append(current.strip())
+            current = w
+        else:
+            current = (current + " " + w).strip() if current else w
+    if current:
+        lines.append(current.strip())
+    if not lines:
+        lines = [""]
+
+    print(colored(top, color))
+    for line in lines:
+        padding = max_text_width - len(line)
+        left = padding // 2
+        right = padding - left
+        print(colored("║ " + " " * left + line + " " * right + " ║", color))
+    print(colored(bot, color))