gooseloop 0.1.0__py3-none-any.whl

gooseloop/__init__.py

@@ -0,0 +1,42 @@
+"""gooseloop — an execution shell for goose-recipe pipelines.
+
+Public surface:
+
+    GooseLooper        - the execution shell
+    Engine             - abstract base for engines
+    Environment        - abstract base for environments (just env_vars)
+    Phase              - one recipe invocation in a Pipeline
+    Pipeline           - named-slot dataclass: review + body + summary
+    Context            - passed to phase callables; typed ledger methods
+    BranchPolicy       - per-recipe rules for routing[] -> Phase building
+    LooperConfig       - resolved gooseloop.toml as a value object
+    predicates         - success_predicate factories
+    protocol           - ReviewOutput / OperatorAction / RoutingEntry types
+    toolkit            - stdlib-only engine helpers (Source, fetch_url, state io)
+    artifact           - versioned artifact contracts for engine composition
+"""
+
+from . import artifact, predicates, protocol, toolkit
+from .branch_policy import BranchPolicy
+from .config import LooperConfig
+from .engine import Engine
+from .environment import Environment
+from .looper import GooseLooper
+from .phase import Context, Phase, Pipeline
+
+__all__ = [
+    "BranchPolicy",
+    "Context",
+    "Engine",
+    "Environment",
+    "GooseLooper",
+    "LooperConfig",
+    "Phase",
+    "Pipeline",
+    "artifact",
+    "predicates",
+    "protocol",
+    "toolkit",
+]
+
+__version__ = "0.1.0"

gooseloop/__main__.py

@@ -0,0 +1,181 @@
+"""`gooseloop` CLI entry point.
+
+Subcommands:
+    run                          Run the configured engine, one pass.
+        --review-only            Stop after the review phase.
+        --review-overlay PATH    Stack a review-recipe overlay (repeatable).
+        --summary-overlay PATH   Stack a summary-recipe overlay (repeatable).
+        --no-save                Don't write a session folder.
+        --no-validate            Skip engine.precheck().
+        --model NAME             Override the configured model.
+
+    recipe --resolve NAME        Print the fully-merged recipe NAME.
+
+    engines                      Print the configured engine module.
+
+Engine discovery: gooseloop.toml's [gooseloop] engine_module = "..." is
+imported and its module-level `engine` attribute is instantiated. Engines
+expose their class as a module-level callable in their __init__.py.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+from pathlib import Path
+
+from .config import LooperConfig
+from .engine import Engine
+from .environment import Environment
+from .looper import GooseLooper
+from .recipe_merge import load_layered_recipe, resolved_recipe_yaml
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="gooseloop")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    run = sub.add_parser("run", help="run the configured engine, one pass")
+    run.add_argument("-e", "--engine", default=None, metavar="MODULE",
+                     help="override the engine module (default: from gooseloop.toml)")
+    run.add_argument("--review-only", action="store_true",
+                     help="stop after the review phase")
+    run.add_argument("--review-overlay", action="append", default=[],
+                     metavar="PATH", help="stack a review-recipe overlay")
+    run.add_argument("--summary-overlay", action="append", default=[],
+                     metavar="PATH", help="stack a summary-recipe overlay")
+    run.add_argument("--no-save", action="store_true",
+                     help="do not write a session folder")
+    run.add_argument("--no-validate", action="store_true",
+                     help="skip engine.precheck()")
+    run.add_argument("--model", default=None, help="override the configured model")
+
+    rec = sub.add_parser("recipe", help="recipe utilities")
+    rec.add_argument("--resolve", metavar="NAME",
+                     help="print the fully-merged recipe NAME")
+    rec.add_argument("--overlay", action="append", default=[], metavar="PATH",
+                     help="extra overlay path to include in the merge")
+
+    sub.add_parser("engines", help="show the configured engine module")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "run":
+        return _cmd_run(args)
+    if args.cmd == "recipe":
+        return _cmd_recipe(args)
+    if args.cmd == "engines":
+        return _cmd_engines(args)
+    parser.error(f"unknown command: {args.cmd}")
+    return 2  # unreachable
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    config = LooperConfig.load()
+    engine, environment = _load_engine_and_environment(config, engine_override=args.engine)
+    looper = GooseLooper(
+        engine=engine,
+        environment=environment,
+        config=config,
+        model=args.model,
+        save=not args.no_save,
+        validate=not args.no_validate,
+        review_only=args.review_only,
+        review_overlays=[Path(p) for p in args.review_overlay],
+        summary_overlays=[Path(p) for p in args.summary_overlay],
+    )
+    result = looper.begin_loop()
+    return 0 if result.get("review_status") != "error" else 1
+
+
+def _cmd_recipe(args: argparse.Namespace) -> int:
+    if not args.resolve:
+        print("usage: gooseloop recipe --resolve NAME [--overlay PATH ...]",
+              file=sys.stderr)
+        return 2
+    config = LooperConfig.load()
+    base_path = (config.anchor / args.resolve).resolve()
+    if not base_path.exists():
+        # Try with .yaml suffix if user passed a bare name.
+        candidate = base_path.with_suffix(".yaml")
+        if candidate.exists():
+            base_path = candidate
+        else:
+            print(f"recipe not found: {base_path}", file=sys.stderr)
+            return 1
+    local = base_path.with_suffix("").with_name(base_path.stem + ".local").with_suffix(".yaml")
+    overlay_paths = [Path(p) for p in args.overlay]
+    merged = load_layered_recipe(
+        base_path,
+        local_path=local if local.exists() else None,
+        overlay_paths=overlay_paths,
+    )
+    print(resolved_recipe_yaml(merged))
+    return 0
+
+
+def _cmd_engines(args: argparse.Namespace) -> int:
+    config = LooperConfig.load()
+    print(f"engine_module: {config.engine_module}")
+    try:
+        mod = importlib.import_module(config.engine_module)
+        engine_cls = getattr(mod, "engine", None)
+        if engine_cls is None:
+            print("  (module has no `engine` attribute)", file=sys.stderr)
+            return 1
+        print(f"engine class:  {engine_cls.__module__}.{engine_cls.__name__}")
+    except ImportError as e:
+        print(f"  import failed: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _load_engine_and_environment(
+    config: LooperConfig,
+    *,
+    engine_override: str | None = None,
+) -> tuple[Engine, Environment | None]:
+    """Import the engine module; instantiate its `engine` attribute.
+
+    Convention: an engine package exposes a module-level `engine`
+    callable (often the class itself) and optionally an `environment`
+    callable. Both are instantiated with no arguments by default.
+    Engines requiring constructor arguments should ship factory
+    callables in those slots.
+
+    `engine_override` (from `-e`/`--engine`) supersedes
+    `config.engine_module` when provided.
+    """
+    module_name = engine_override or config.engine_module
+    sys.path.insert(0, str(config.anchor))
+    try:
+        mod = importlib.import_module(module_name)
+    except ImportError as e:
+        raise SystemExit(
+            f"gooseloop: cannot import engine module {module_name!r}: {e}"
+        )
+    engine_obj = getattr(mod, "engine", None)
+    if engine_obj is None:
+        raise SystemExit(
+            f"gooseloop: engine module {module_name!r} has no `engine` attribute"
+        )
+    engine = engine_obj() if callable(engine_obj) and not isinstance(engine_obj, Engine) else engine_obj
+    if not isinstance(engine, Engine):
+        raise SystemExit(
+            f"gooseloop: {module_name}.engine did not yield an Engine instance"
+        )
+
+    env_obj = getattr(mod, "environment", None)
+    environment: Environment | None = None
+    if env_obj is not None:
+        environment = env_obj() if callable(env_obj) and not isinstance(env_obj, Environment) else env_obj
+        if not isinstance(environment, Environment):
+            raise SystemExit(
+                f"gooseloop: {module_name}.environment did not yield an Environment instance"
+            )
+    return engine, environment
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gooseloop/artifact.py

@@ -0,0 +1,82 @@
+"""Versioned artifact contracts: how engines compose without knowing each other.
+
+Per PROTOCOL.md §12. When one engine's output is another engine's input, the
+artifact file is the interface between them, and an interface needs a version.
+The producing engine stamps a `schema_version` key into the artifact; the
+consuming engine checks it at read time with check_artifact_version().
+
+The semantics deliberately mirror the review protocol_version check in
+protocol.py, because it is the same problem one level up:
+
+    - Same major, any minor: compatible. Additive schema changes (a new
+      optional field, a new enum value the reader ignores) bump the minor.
+    - Different major, or an unparseable version: refused loudly with
+      ArtifactVersionError. A major mismatch means the reader may
+      misinterpret every entry; limping along is the silent time bomb.
+    - Missing version: the artifact is still read, and a problem string is
+      returned nudging the operator to stamp the file. Fail-safe runs in the
+      KEEP direction: data we cannot positively classify is kept and named
+      out loud, never refused on a technicality. (Pre-versioning artifacts
+      sealed by hand exist; they should not stop working the day the
+      contract gains a version key.)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ArtifactVersionError(Exception):
+    """The artifact declares a schema version this reader cannot honour."""
+
+
+def check_artifact_version(
+    data: dict[str, Any],
+    supported: str,
+    *,
+    key: str = "schema_version",
+    what: str = "artifact",
+) -> list[str]:
+    """Check a parsed artifact's declared schema version against `supported`.
+
+    Returns a list of problem strings (empty when the version is present and
+    compatible). Raises ArtifactVersionError on a major mismatch or an
+    unparseable declared version.
+
+    Parameters:
+        data: the parsed artifact (the top-level mapping).
+        supported: the version this reader ships, e.g. "1.0".
+        key: the version key inside the artifact.
+        what: human name for the artifact, used in messages.
+    """
+    supported_major = _major(supported, what=f"supported version for {what}")
+
+    declared = data.get(key)
+    if declared is None or str(declared).strip() == "":
+        return [
+            f"{what} has no {key}; assuming {supported} - "
+            f'add `{key} = "{supported}"` to the file'
+        ]
+
+    declared = str(declared).strip()
+    try:
+        declared_major = _major(declared, what=what)
+    except ArtifactVersionError:
+        raise ArtifactVersionError(
+            f"{what} declares {key} {declared!r}, which is not parseable; "
+            f"this reader supports major {supported_major}"
+        ) from None
+
+    if declared_major != supported_major:
+        raise ArtifactVersionError(
+            f"{what} declares {key} {declared!r} (major {declared_major}); "
+            f"this reader supports major {supported_major} only"
+        )
+    return []
+
+
+def _major(version: str, *, what: str) -> int:
+    try:
+        return int(str(version).split(".", 1)[0])
+    except (ValueError, IndexError):
+        raise ArtifactVersionError(f"{what}: version {version!r} is not parseable")

gooseloop/branch_policy.py

@@ -0,0 +1,49 @@
+"""BranchPolicy — per-recipe rules the framework applies when building body Phases.
+
+Per ADR 0007 and PROTOCOL.md §5. The framework consults the engine's
+branch_policies dict for each routing[] entry the review emitted, looking
+up by recipe name. Recipes with no entry get BranchPolicy() defaults
+(no skip, no path tracking, no extra predicate, intent unchecked).
+
+Authors of an engine register policies like:
+
+    class MyEngine(Engine):
+        branch_policies = {
+            "to-outreach": BranchPolicy(
+                skip_when=lambda p: (outreach_dir / f"{p['slug']}.md").exists(),
+                output_path=lambda p: outreach_dir / f"{p['slug']}.md",
+                intent="produce",
+            ),
+        }
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Literal, Optional
+
+
+Intent = Literal["produce", "edit", "edit-or-produce"]
+
+
+@dataclass
+class BranchPolicy:
+    """Per-recipe rules. All fields optional; the default is the no-op policy.
+
+    skip_when: called with the routing entry's params dict.
+        Truthy return skips the phase. A str return is used as the
+        skip reason in the session log.
+    output_path: called with the params dict to compute the deterministic
+        file path the recipe is expected to write. The framework uses this
+        to derive a default success predicate (file_nonempty) and to log
+        the path on success.
+    predicate: explicit success predicate override. Takes the recipe's
+        stdout. If unset and output_path is set, the framework derives a
+        file_nonempty predicate from output_path.
+    intent: declarative tag for the recipe's intent against output_path.
+        Currently informational; reserved for future intent-reconciliation
+        checks. None = unchecked.
+    """
+    skip_when: Optional[Callable[[dict[str, Any]], "bool | str | None"]] = None
+    output_path: Optional[Callable[[dict[str, Any]], Optional[Path]]] = None
+    predicate: Optional[Callable[[str], bool]] = None
+    intent: Optional[Intent] = None

gooseloop/config.py

@@ -0,0 +1,104 @@
+"""LooperConfig — value object for gooseloop.toml.
+
+Loaded once at the top of a run via LooperConfig.load() and passed
+explicitly. No module-level singleton, no clear-cache shims, no global
+state. Tests construct LooperConfig directly with overrides.
+"""
+
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+CONFIG_FILENAME = "gooseloop.toml"
+
+
+DEFAULTS: dict[str, Any] = {
+    "gooseloop": {
+        "default_model": "openrouter/owl-alpha",
+        "sessions_dir": "reviews/sessions",
+        "engine_module": "engines.hello_world",
+        "environment_config": "",
+        "max_queue_depth": 50,
+        "review_recipe": "review.yaml",
+        "summary_recipe": "summary.yaml",
+        "retry": {
+            "max_retries": 6,
+            "base_delay": 5,
+        },
+    },
+}
+
+
+@dataclass
+class RetrySettings:
+    max_retries: int = 6
+    base_delay: int = 5
+
+
+@dataclass
+class LooperConfig:
+    """Resolved gooseloop.toml. Construct via LooperConfig.load(); never global."""
+    default_model: str = "openrouter/owl-alpha"
+    sessions_dir: Path = field(default_factory=lambda: Path("reviews/sessions"))
+    engine_module: str = "engines.hello_world"
+    environment_config: Path | None = None
+    max_queue_depth: int = 50
+    review_recipe: str = "review.yaml"
+    summary_recipe: str = "summary.yaml"
+    retry: RetrySettings = field(default_factory=RetrySettings)
+    anchor: Path = field(default_factory=Path.cwd)
+
+    @classmethod
+    def load(cls, anchor: Path | None = None, *, warn_on_missing: bool = True) -> "LooperConfig":
+        """Load gooseloop.toml from `anchor` (default: cwd). Missing file = defaults."""
+        anchor = (anchor or Path.cwd()).resolve()
+        path = anchor / CONFIG_FILENAME
+        if path.exists():
+            with open(path, "rb") as f:
+                raw = tomllib.load(f)
+            merged = _deep_merge(DEFAULTS, raw)
+        else:
+            if warn_on_missing:
+                print(
+                    f"[gooseloop] {CONFIG_FILENAME} not found in {anchor}; using defaults.",
+                    file=sys.stderr,
+                )
+            merged = DEFAULTS
+        return cls._from_merged(merged, anchor)
+
+    @classmethod
+    def _from_merged(cls, merged: dict[str, Any], anchor: Path) -> "LooperConfig":
+        section = merged["gooseloop"]
+        env_cfg = section.get("environment_config", "") or ""
+        return cls(
+            default_model=section["default_model"],
+            sessions_dir=_resolve(section["sessions_dir"], anchor),
+            engine_module=section["engine_module"],
+            environment_config=_resolve(env_cfg, anchor) if env_cfg else None,
+            max_queue_depth=int(section["max_queue_depth"]),
+            review_recipe=section.get("review_recipe", "review.yaml"),
+            summary_recipe=section.get("summary_recipe", "summary.yaml"),
+            retry=RetrySettings(
+                max_retries=int(section["retry"]["max_retries"]),
+                base_delay=int(section["retry"]["base_delay"]),
+            ),
+            anchor=anchor,
+        )
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    out = dict(base)
+    for k, v in override.items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def _resolve(path_str: str, anchor: Path) -> Path:
+    p = Path(path_str)
+    return p if p.is_absolute() else (anchor / p).resolve()