rote-cli 0.1.0__py3-none-any.whl

rote/graduator/__init__.py

@@ -0,0 +1,259 @@
+"""The graduator orchestrator.
+
+The :class:`Graduator` is the high-level entry point used by
+``rote graduate``. It:
+
+1. Picks a driver (auto-detect or explicit ``--agent``).
+2. Locates the rote-graduate skill bundle.
+3. Creates a temp work directory.
+4. Calls ``driver.run()`` to produce ``pipeline.yaml`` (and any
+   extracted modules / signature stubs).
+5. Validates the produced ``pipeline.yaml`` via
+   :func:`rote.ir.load_pipeline`.
+6. Moves the work directory contents into the user's output directory.
+7. Returns a :class:`GraduationResult`.
+
+This module deliberately knows nothing about specific runtimes
+(Temporal, Inngest, etc.) — that's the adapter layer's job. The
+graduator's only output is the validated IR + the stub files;
+``rote.adapters`` consumes those to emit runnable code.
+"""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from rote.graduator.drivers import (
+    DriverError,
+    GraduatorDriver,
+    auto_detect,
+    available_drivers,
+    get_driver,
+)
+from rote.ir import Pipeline, load_pipeline
+
+
+class GraduatorError(RuntimeError):
+    """High-level graduator failure.
+
+    Wraps driver errors and validation errors with a user-facing
+    message. The CLI prints the message to stderr and exits non-zero.
+    """
+
+
+@dataclass
+class GraduationResult:
+    """The output of a successful graduation."""
+
+    pipeline: Pipeline
+    output_dir: Path
+    driver_name: str
+    driver_metadata: dict[str, Any] = field(default_factory=dict)
+
+
+def _default_graduator_skill_dir() -> Path:
+    """Locate the rote-graduate skill bundled with the rote source.
+
+    Two layouts exist, checked in order:
+
+    1. **Wheel install.** ``pyproject.toml`` force-includes the
+       repo-root ``skills/rote-graduate/`` into the wheel at
+       ``rote/skills/rote-graduate/``, so the bundle sits next to the
+       package's ``__file__``.
+    2. **Editable install / source checkout.** The skill lives at
+       ``<repo>/skills/rote-graduate/``; ``rote.__file__`` is
+       ``<repo>/src/rote/__init__.py``, so the repo root is three
+       parents up.
+    """
+    import rote
+
+    rote_pkg_dir = Path(rote.__file__).resolve().parent
+    candidates = [
+        rote_pkg_dir / "skills" / "rote-graduate",
+        rote_pkg_dir.parent.parent / "skills" / "rote-graduate",
+    ]
+    for candidate in candidates:
+        if candidate.is_dir() and (candidate / "SKILL.md").is_file():
+            return candidate
+    searched = ", ".join(str(c) for c in candidates)
+    raise GraduatorError(
+        f"Could not locate the rote-graduate skill (searched: {searched}). "
+        "Pass an explicit graduator_skill_dir to Graduator() pointing "
+        "at a rote-graduate skill bundle."
+    )
+
+
+class Graduator:
+    """High-level orchestrator for graduating a skill into a pipeline."""
+
+    def __init__(
+        self,
+        agent: str | None = None,
+        graduator_skill_dir: Path | None = None,
+        model: str | None = None,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        agent
+            Driver name (``"claude"``, ``"codex"``, ``"api"``) or
+            ``None`` for auto-detect.
+        graduator_skill_dir
+            Path to the rote-graduate skill bundle. Defaults to the
+            bundled one inside the rote source tree.
+        model
+            Override the LLM model the driver uses for the graduator
+            (e.g. ``"claude-opus-4-6"`` to use Opus instead of the
+            default Sonnet). ``None`` uses the driver's default.
+        """
+        self.agent = agent
+        self._explicit_graduator_skill_dir = graduator_skill_dir
+        self.model = model
+
+    @property
+    def graduator_skill_dir(self) -> Path:
+        if self._explicit_graduator_skill_dir is not None:
+            return self._explicit_graduator_skill_dir
+        return _default_graduator_skill_dir()
+
+    def select_driver(self) -> GraduatorDriver:
+        """Choose a driver based on the agent setting or auto-detect.
+
+        When a non-default ``model`` was passed to the ``Graduator``
+        constructor, it's forwarded to the driver via ``get_driver``
+        kwargs. Auto-detect finds an available driver first (using
+        a zero-arg probe), then re-constructs it with the kwargs so
+        the override is honored.
+        """
+        driver_kwargs: dict[str, object] = {}
+        if self.model is not None:
+            driver_kwargs["model"] = self.model
+
+        if self.agent:
+            try:
+                driver = get_driver(self.agent, **driver_kwargs)
+            except KeyError as e:
+                raise GraduatorError(str(e.args[0])) from None
+            available, reason = driver.is_available()
+            if not available:
+                raise GraduatorError(f"Driver {self.agent!r} is not available: {reason}")
+            return driver
+
+        probe = auto_detect()
+        if probe is None:
+            lines = [
+                "No graduator driver is available. Tried:",
+            ]
+            for name, _avail, reason in available_drivers():
+                lines.append(f"  - {name}: {reason}")
+            lines.append("")
+            lines.append(
+                "Install one of the supported coding agent CLIs, or set "
+                "ANTHROPIC_API_KEY and `pip install rote[api]`."
+            )
+            raise GraduatorError("\n".join(lines))
+
+        # Re-construct the detected driver with user-specified kwargs
+        # (e.g. model override) instead of returning the probe instance
+        # directly.
+        return get_driver(probe.name, **driver_kwargs)
+
+    async def graduate(
+        self,
+        skill_dir: Path | str,
+        output_dir: Path | str,
+    ) -> GraduationResult:
+        """Run the full graduation flow.
+
+        Parameters
+        ----------
+        skill_dir
+            Path to the source skill bundle (must contain a SKILL.md).
+        output_dir
+            Where to write the graduated artifacts. Created if missing;
+            existing files of the same name are overwritten.
+
+        Returns
+        -------
+        GraduationResult
+            A validated :class:`Pipeline` plus the output directory and
+            driver metadata.
+
+        Raises
+        ------
+        GraduatorError
+            For any user-actionable failure: missing skill bundle,
+            unavailable driver, driver failure, or invalid produced
+            pipeline.yaml.
+        """
+        skill_dir = Path(skill_dir).resolve()
+        output_dir = Path(output_dir).resolve()
+
+        if not skill_dir.is_dir():
+            raise GraduatorError(f"Skill directory does not exist: {skill_dir}")
+        if not (skill_dir / "SKILL.md").is_file():
+            raise GraduatorError(f"Not a skill bundle (no SKILL.md found): {skill_dir}")
+
+        driver = self.select_driver()
+
+        with tempfile.TemporaryDirectory(prefix="rote-graduate-") as work_dir_str:
+            work_dir = Path(work_dir_str)
+
+            try:
+                result = await driver.run(
+                    skill_dir=skill_dir,
+                    graduator_skill_dir=self.graduator_skill_dir,
+                    work_dir=work_dir,
+                )
+            except DriverError as e:
+                detail = f"\n\n{e.details}" if getattr(e, "details", None) else ""
+                raise GraduatorError(f"Driver {driver.name!r} failed: {e}{detail}") from e
+
+            try:
+                pipeline = load_pipeline(result.pipeline_yaml_path)
+            except Exception as e:
+                raise GraduatorError(
+                    f"Driver {driver.name!r} produced an invalid "
+                    f"pipeline.yaml at {result.pipeline_yaml_path}: {e}"
+                ) from e
+
+            self._move_work_dir_to_output(result.work_dir, output_dir)
+
+            # Re-point the result's path to the moved location for the
+            # caller's benefit.
+            return GraduationResult(
+                pipeline=pipeline,
+                output_dir=output_dir,
+                driver_name=result.driver_name,
+                driver_metadata=result.metadata,
+            )
+
+    @staticmethod
+    def _move_work_dir_to_output(work_dir: Path, output_dir: Path) -> None:
+        """Move every entry in ``work_dir`` into ``output_dir``.
+
+        Existing entries with the same name in ``output_dir`` are
+        replaced. We use ``shutil.move`` per-entry rather than moving
+        the whole directory because ``output_dir`` may already exist
+        and may contain unrelated files.
+        """
+        output_dir.mkdir(parents=True, exist_ok=True)
+        for item in work_dir.iterdir():
+            target = output_dir / item.name
+            if target.exists():
+                if target.is_dir():
+                    shutil.rmtree(target)
+                else:
+                    target.unlink()
+            shutil.move(str(item), str(target))
+
+
+__all__ = [
+    "Graduator",
+    "GraduationResult",
+    "GraduatorError",
+]

rote/graduator/drivers/__init__.py

@@ -0,0 +1,226 @@
+"""Graduator drivers — pluggable backends for running the graduator agent.
+
+Every driver implements the :class:`GraduatorDriver` Protocol and is
+registered in :data:`DRIVERS`. The CLI dispatches to a driver by name
+(``rote graduate --agent claude``) or by auto-detection
+(:func:`auto_detect`).
+
+See ``docs/agent-runtime.md`` for the full design record, including the
+rationale for the three-driver lineup (Claude Code, Codex CLI,
+Anthropic SDK) and the explicit non-use of ``claude-agent-sdk``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+# ───────── Shared types ─────────
+
+
+class DriverError(RuntimeError):
+    """Raised when a driver fails to produce a graduated pipeline.yaml.
+
+    The message is user-facing and should explain what went wrong and
+    what the user can do about it. Driver implementations should attach
+    any captured stdout / stderr via the ``details`` attribute.
+    """
+
+    def __init__(self, message: str, *, details: str | None = None) -> None:
+        super().__init__(message)
+        self.details = details
+
+
+@dataclass
+class DriverResult:
+    """The output of a successful driver run.
+
+    Attributes
+    ----------
+    pipeline_yaml_path
+        Path to the produced ``pipeline.yaml`` inside ``work_dir``.
+    work_dir
+        Scratch directory the driver wrote into. May contain additional
+        artifacts (``extracted/*.py``, ``signatures/*.py``, etc.) that
+        the graduator orchestrator will move into the user's output
+        directory.
+    driver_name
+        The name of the driver that produced this result (e.g.
+        ``"claude"``, ``"codex"``, ``"api"``).
+    metadata
+        Free-form dict of driver-specific metadata: token counts,
+        estimated cost, duration, model name, session id, etc. Used for
+        the Phase 7 graduation report but not the IR itself.
+    """
+
+    pipeline_yaml_path: Path
+    work_dir: Path
+    driver_name: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class GraduatorDriver(Protocol):
+    """Protocol every graduator driver implements.
+
+    The driver's only responsibility is: **given a source skill and the
+    rote-graduate rubric, run the agent loop and make sure
+    ``work_dir/pipeline.yaml`` exists when it returns.** How it gets
+    there — subprocess, in-process, remote — is the driver's business.
+    """
+
+    name: str
+    """Short identifier used in the CLI (``--agent <name>``)."""
+
+    def is_available(self) -> tuple[bool, str]:
+        """Check whether this driver can run right now.
+
+        Returns
+        -------
+        tuple[bool, str]
+            ``(available, reason)``. When ``available`` is ``True``, the
+            reason may be an empty string. When ``False``, ``reason`` is
+            a user-facing message explaining what needs to happen
+            (install the CLI, run login, set an env var).
+        """
+        ...
+
+    async def run(
+        self,
+        skill_dir: Path,
+        graduator_skill_dir: Path,
+        work_dir: Path,
+    ) -> DriverResult:
+        """Run the graduator agent against ``skill_dir``.
+
+        Parameters
+        ----------
+        skill_dir
+            The source skill bundle to graduate (read-only to the agent).
+        graduator_skill_dir
+            The ``rote-graduate`` skill with SKILL.md and references/.
+        work_dir
+            A scratch directory where the agent writes ``pipeline.yaml``
+            and any extracted/signature stubs. The caller ensures this
+            directory exists and is empty.
+
+        Returns
+        -------
+        DriverResult
+            A result pointing at ``work_dir/pipeline.yaml``.
+
+        Raises
+        ------
+        DriverError
+            If the driver cannot produce a valid ``pipeline.yaml``.
+        """
+        ...
+
+
+# ───────── Driver registry ─────────
+
+
+def _claude_driver_factory(**kwargs: Any) -> GraduatorDriver:
+    from rote.graduator.drivers.claude import ClaudeDriver
+
+    return ClaudeDriver(**kwargs)
+
+
+def _codex_driver_factory(**kwargs: Any) -> GraduatorDriver:
+    from rote.graduator.drivers.codex import CodexDriver
+
+    return CodexDriver(**kwargs)
+
+
+def _anthropic_driver_factory(**kwargs: Any) -> GraduatorDriver:
+    from rote.graduator.drivers.anthropic_api import AnthropicApiDriver
+
+    return AnthropicApiDriver(**kwargs)
+
+
+#: Name → factory. Keep the values lazy so we don't pay the import cost
+#: of the anthropic SDK on every CLI invocation. Factories accept
+#: ``**kwargs`` which are forwarded to the driver constructor (e.g.
+#: ``model``, ``max_turns``).
+DRIVERS: dict[str, Callable[..., GraduatorDriver]] = {
+    "claude": _claude_driver_factory,
+    "codex": _codex_driver_factory,
+    "api": _anthropic_driver_factory,
+}
+
+#: Order used by :func:`auto_detect`. Claude first because Claude Max/Pro
+#: is the most likely subscription rote's audience already has.
+AUTO_DETECT_ORDER: tuple[str, ...] = ("claude", "codex", "api")
+
+
+def get_driver(name: str, **kwargs: Any) -> GraduatorDriver:
+    """Return a driver instance by name, configured with ``kwargs``.
+
+    ``kwargs`` are forwarded to the driver's constructor (e.g. ``model``
+    for ``ClaudeDriver`` and ``AnthropicApiDriver``). Drivers ignore
+    kwargs they don't understand via ``**kwargs`` absorption in their
+    factories.
+
+    Raises :class:`KeyError` with a helpful message when the name is
+    unknown.
+    """
+    try:
+        factory = DRIVERS[name]
+    except KeyError:
+        available = ", ".join(sorted(DRIVERS))
+        raise KeyError(f"Unknown agent driver {name!r}. Available: {available}") from None
+    return factory(**kwargs)
+
+
+def auto_detect() -> GraduatorDriver | None:
+    """Return the first available driver in :data:`AUTO_DETECT_ORDER`.
+
+    Returns ``None`` when no driver is available. The CLI translates
+    that into a helpful error listing setup instructions for each
+    driver.
+    """
+    for name in AUTO_DETECT_ORDER:
+        try:
+            driver = DRIVERS[name]()
+        except Exception:
+            # A factory raising at import time (e.g. a missing optional
+            # dep that isn't gracefully handled) should never block
+            # auto-detect from trying the next driver.
+            continue
+        try:
+            available, _reason = driver.is_available()
+        except Exception:
+            continue
+        if available:
+            return driver
+    return None
+
+
+def available_drivers() -> list[tuple[str, bool, str]]:
+    """Return a diagnostic list of ``(name, available, reason)`` triples.
+
+    Used by the CLI's ``--agent auto`` failure path to produce a clear
+    message telling the user what each driver needs.
+    """
+    out: list[tuple[str, bool, str]] = []
+    for name in AUTO_DETECT_ORDER:
+        try:
+            driver = DRIVERS[name]()
+            available, reason = driver.is_available()
+            out.append((name, available, reason))
+        except Exception as e:
+            out.append((name, False, f"driver failed to load: {e}"))
+    return out
+
+
+__all__ = [
+    "DriverError",
+    "DriverResult",
+    "GraduatorDriver",
+    "DRIVERS",
+    "AUTO_DETECT_ORDER",
+    "get_driver",
+    "auto_detect",
+    "available_drivers",
+]