spinekit 0.2.0__py3-none-any.whl

spine_backends/sqlite.py

@@ -0,0 +1,103 @@
+"""SQLite checkpoint backend — durable state for crash recovery and resume.
+
+Uses the stdlib ``sqlite3`` driver offloaded to a worker thread (via anyio) so
+the async kernel never blocks. WAL mode keeps reads and writes concurrent. A
+monotonic ``revision`` column supports optimistic-locking checks.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+
+import anyio
+
+from spine_backends.migrations import migrate
+from spine_core.registry import register_checkpoint
+from spine_core.state import State
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS checkpoints (
+    session_id TEXT PRIMARY KEY,
+    version    INTEGER NOT NULL,
+    revision   INTEGER NOT NULL DEFAULT 1,
+    data       TEXT    NOT NULL,
+    updated    REAL    NOT NULL
+)
+"""
+
+
+class SQLiteCheckpoint:
+    """Durable :class:`~spine_core.checkpoint.CheckpointStore` over SQLite."""
+
+    def __init__(self, path: str | Path = "spine.db") -> None:
+        self.path = str(path)
+        self._init()
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.path)
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA busy_timeout=5000")
+        return conn
+
+    def _init(self) -> None:
+        with self._connect() as conn:
+            conn.execute(_SCHEMA)
+
+    async def put(self, state: State) -> None:
+        await anyio.to_thread.run_sync(self._put_sync, state)
+
+    def _put_sync(self, state: State) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO checkpoints (session_id, version, revision, data, updated)
+                VALUES (?, ?, 1, ?, ?)
+                ON CONFLICT(session_id) DO UPDATE SET
+                    version  = excluded.version,
+                    revision = checkpoints.revision + 1,
+                    data     = excluded.data,
+                    updated  = excluded.updated
+                """,
+                (state.session_id, state.version, state.model_dump_json(), time.time()),
+            )
+
+    async def get(self, session_id: str) -> State | None:
+        return await anyio.to_thread.run_sync(self._get_sync, session_id)
+
+    def _get_sync(self, session_id: str) -> State | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT data FROM checkpoints WHERE session_id = ?", (session_id,)
+            ).fetchone()
+        if row is None:
+            return None
+        raw = migrate(json.loads(row[0]))
+        return State.model_validate(raw)
+
+    async def delete(self, session_id: str) -> None:
+        await anyio.to_thread.run_sync(self._delete_sync, session_id)
+
+    def _delete_sync(self, session_id: str) -> None:
+        with self._connect() as conn:
+            conn.execute("DELETE FROM checkpoints WHERE session_id = ?", (session_id,))
+
+    async def revision(self, session_id: str) -> int:
+        """Current optimistic-lock revision for a session (0 if absent)."""
+        return await anyio.to_thread.run_sync(self._revision_sync, session_id)
+
+    def _revision_sync(self, session_id: str) -> int:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT revision FROM checkpoints WHERE session_id = ?", (session_id,)
+            ).fetchone()
+        return int(row[0]) if row is not None else 0
+
+
+def register() -> None:
+    register_checkpoint("sqlite", lambda path="spine.db", **_: SQLiteCheckpoint(path))
+
+
+register()

spine_cli/__init__.py

@@ -0,0 +1,5 @@
+"""Spine CLI — scaffold, run, doctor, and inspect plugins."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"  # x-release-please-version

spine_cli/app.py

@@ -0,0 +1,363 @@
+"""The ``spine`` CLI — Typer commands with Rich output.
+
+Project operations are declarative and reproducible: ``init`` scaffolds, ``run``
+executes an agent defined in the project, ``doctor`` validates config + plugin
+compatibility, and ``plugin`` inspects installed extensions.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from spine_cli import templates
+from spine_cli.config import ConfigError, find_config, load_config
+from spine_cli.plugins import discover, load_all
+
+app = typer.Typer(no_args_is_help=True, add_completion=False, help="Spine — agent runtime CLI.")
+plugin_app = typer.Typer(no_args_is_help=True, help="Manage and inspect plugins.")
+app.add_typer(plugin_app, name="plugin")
+
+console = Console()
+
+
+@app.command()
+def version() -> None:
+    """Print the installed Spine version."""
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _pkg_version
+
+    try:
+        ver = _pkg_version("spinekit")
+    except PackageNotFoundError:
+        from spine_core import __version__ as ver
+
+    console.print(f"spinekit [bold]{ver}[/]")
+
+
+@app.command()
+def init(
+    name: str = typer.Argument(..., help="Project directory to create."),
+    template: str = typer.Option("minimal", "--template", "-t", help="Project template."),
+    path: Path = typer.Option(Path("."), help="Where to create the project."),
+) -> None:
+    """Scaffold a new Spine project (like ``uv init``)."""
+    try:
+        files = templates.render(name, template)
+    except ValueError as exc:
+        console.print(f"[red]error:[/] {exc}")
+        raise typer.Exit(1) from exc
+
+    root = (path / name).resolve()
+    if root.exists() and any(root.iterdir()):
+        console.print(f"[red]error:[/] {root} already exists and is not empty")
+        raise typer.Exit(1)
+
+    for relpath, content in files.items():
+        dest = root / relpath
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content)
+
+    console.print(f"[green]✓[/] created [bold]{name}[/] ({template}) at {root}")
+    console.print(f'  next: [cyan]cd {name} && uv sync && uv run spine run assistant "hi"[/]')
+
+
+@app.command()
+def run(
+    target: str = typer.Argument(..., help="Agent to run: 'assistant' or 'module:attr'."),
+    input: str = typer.Argument(..., help="The input message for the agent."),
+    path: Path = typer.Option(Path("."), help="Project root."),
+) -> None:
+    """Run an agent defined in the project and print its answer."""
+    project_root = _project_root(path)
+    try:
+        agent = _load_agent(target, project_root)
+    except (ImportError, AttributeError) as exc:
+        console.print(f"[red]error:[/] could not load agent '{target}': {exc}")
+        raise typer.Exit(1) from exc
+
+    result = agent.run_sync(input)
+    if result.stopped_reason.value == "error":
+        console.print(f"[red]run failed:[/] {result.error}")
+        raise typer.Exit(1)
+    if result.interrupted:
+        console.print(f"[yellow]⏸ interrupted[/] (resume token: {result.resume_token})")
+        console.print(result.interrupt)
+        return
+    console.print(result.answer or "")
+    console.print(
+        f"\n[dim]stopped: {result.stopped_reason.value} · steps: {result.state.step} · "
+        f"${result.usage.cost_usd:.4f} · {result.usage.total_tokens} tok[/]"
+    )
+
+
+@app.command()
+def doctor(path: Path = typer.Option(Path("."), help="Project root.")) -> None:
+    """Validate config, environment, and plugin compatibility."""
+    import os
+
+    from spine_core import ProviderError, resolve_provider
+
+    rows: list[tuple[str, str, str]] = []
+    failed = False
+
+    config_path = find_config(path)
+    if config_path is None:
+        rows.append(("config", "[red]fail[/]", "no spine.toml found"))
+        _render_doctor(rows)
+        raise typer.Exit(1)
+    rows.append(("config", "[green]ok[/]", str(config_path)))
+
+    try:
+        config = load_config(config_path)
+    except ConfigError as exc:
+        rows.append(("config parse", "[red]fail[/]", str(exc)))
+        _render_doctor(rows)
+        raise typer.Exit(1) from exc
+
+    loaded = load_all()
+    rows.append(
+        ("plugins", "[green]ok[/]", f"{sum(p.loaded for p in loaded)}/{len(loaded)} loaded")
+    )
+    for plugin in loaded:
+        if plugin.error:
+            failed = True
+            rows.append((f"  {plugin.name}", "[red]fail[/]", plugin.error))
+
+    try:
+        resolve_provider(config.default_model)
+        rows.append(("model", "[green]ok[/]", config.default_model))
+    except ProviderError as exc:
+        failed = True
+        rows.append(("model", "[red]fail[/]", str(exc)))
+
+    scheme = config.default_model.split(":", 1)[0]
+    if scheme == "anthropic" and not os.environ.get("ANTHROPIC_API_KEY"):
+        rows.append(("ANTHROPIC_API_KEY", "[yellow]warn[/]", "unset (needed to call the model)"))
+
+    from spine_core import list_checkpoints, list_middleware
+
+    known_mw = set(list_middleware())
+    for name in config.middleware.chain:
+        if name in known_mw:
+            rows.append((f"mw:{name}", "[green]ok[/]", "registered"))
+        else:
+            failed = True
+            rows.append((f"mw:{name}", "[red]fail[/]", "not registered (install its plugin)"))
+
+    backend = config.backends.checkpoint
+    if backend and backend not in set(list_checkpoints()):
+        failed = True
+        rows.append((f"checkpoint:{backend}", "[red]fail[/]", "backend not registered"))
+    elif backend:
+        rows.append((f"checkpoint:{backend}", "[green]ok[/]", "registered"))
+
+    _render_doctor(rows)
+    if failed:
+        raise typer.Exit(1)
+
+
+@plugin_app.command("list")
+def plugin_list() -> None:
+    """List installed Spine plugins (entry points)."""
+    plugins = discover()
+    if not plugins:
+        console.print("[dim]no spine.plugins entry points installed[/]")
+        return
+    table = Table("name", "target", "origin")
+    for plugin in plugins:
+        origin = "first-party" if plugin.first_party else "[yellow]third-party[/]"
+        table.add_row(plugin.name, plugin.value, origin)
+    console.print(table)
+
+
+@app.command("eval")
+def eval_cmd(
+    suite: str = typer.Argument(..., help="Path to the eval dataset (.yaml/.json)."),
+    path: Path = typer.Option(Path("."), help="Project root."),
+    scorer: str = typer.Option("contains", help="Built-in scorer: contains | exact."),
+) -> None:
+    """Run the eval harness for the spine.toml agent against a dataset."""
+    import functools
+
+    import anyio
+
+    try:
+        from spine_eval import Contains, ExactMatch, Scorer, evaluate, load_dataset
+    except ImportError as exc:
+        console.print("[red]error:[/] spine-eval is not installed ([cyan]uv add spine-eval[/])")
+        raise typer.Exit(1) from exc
+
+    config_path = find_config(path)
+    if config_path is None:
+        console.print("[red]error:[/] no spine.toml found")
+        raise typer.Exit(1)
+    config = load_config(config_path)
+    project_root = config_path.parent
+
+    suite_path = Path(suite)
+    if not suite_path.is_absolute():
+        suite_path = project_root / suite
+    if not suite_path.is_file():
+        console.print(f"[red]error:[/] no eval suite at {suite_path}")
+        raise typer.Exit(1)
+
+    from spine_cli.builder import build_agent
+
+    agent = build_agent(config, project_root)
+    dataset = load_dataset(suite_path)
+    options: dict[str, list[Scorer]] = {"contains": [Contains()], "exact": [ExactMatch()]}
+    scorers = options.get(scorer)
+    if scorers is None:
+        console.print(f"[red]error:[/] unknown scorer {scorer!r} (use contains|exact)")
+        raise typer.Exit(1)
+
+    report = anyio.run(functools.partial(evaluate, agent, dataset, scorers))
+
+    table = Table("metric", "value")
+    table.add_row("cases", str(report.total))
+    table.add_row("pass rate", f"{report.pass_rate:.0%} ({report.passed}/{report.total})")
+    table.add_row("error rate", f"{report.error_rate:.0%}")
+    table.add_row("cost (total)", f"${report.cost_total_usd:.4f}")
+    table.add_row("latency avg / p95", f"{report.latency_avg_s:.2f}s / {report.latency_p95_s:.2f}s")
+    for name, mean in report.scorer_means.items():
+        table.add_row(f"scorer:{name}", f"{mean:.2f}")
+    console.print(table)
+    if report.error_rate > 0 or report.pass_rate < 1.0:
+        raise typer.Exit(1)
+
+
+@app.command()
+def dev(
+    input: str = typer.Argument(..., help="The input message."),
+    path: Path = typer.Option(Path("."), help="Project root."),
+) -> None:
+    """Run the spine.toml agent and stream every step's trace event live."""
+    import anyio
+
+    from spine_cli.builder import build_agent, save_trace
+
+    config_path = find_config(path)
+    if config_path is None:
+        console.print("[red]error:[/] no spine.toml found")
+        raise typer.Exit(1)
+    config = load_config(config_path)
+    project_root = config_path.parent
+    agent = build_agent(config, project_root)
+
+    async def go() -> None:
+        async for event in agent.stream(input):
+            detail = ", ".join(f"{k}={v}" for k, v in event.data.items())
+            console.print(f"[dim]{event.seq:>3}[/] [cyan]{event.type}[/] {detail}")
+
+    anyio.run(go)
+    result = agent.last_result
+    if result is not None:
+        save_trace(project_root, result)
+        console.print(f"\n[bold]{result.answer or '(' + result.stopped_reason.value + ')'}[/]")
+
+
+@app.command()
+def chat(
+    input: str = typer.Argument(..., help="The input message."),
+    path: Path = typer.Option(Path("."), help="Project root."),
+) -> None:
+    """Run the agent described by spine.toml (model, guards, middleware, backend)."""
+    from spine_cli.builder import build_agent, save_trace
+
+    config_path = find_config(path)
+    if config_path is None:
+        console.print("[red]error:[/] no spine.toml found")
+        raise typer.Exit(1)
+    try:
+        config = load_config(config_path)
+    except ConfigError as exc:
+        console.print(f"[red]error:[/] {exc}")
+        raise typer.Exit(1) from exc
+
+    project_root = config_path.parent
+    agent = build_agent(config, project_root)
+    result = agent.run_sync(input)
+    trace_path = save_trace(project_root, result)
+
+    if result.stopped_reason.value == "error":
+        console.print(f"[red]run failed:[/] {result.error}")
+        raise typer.Exit(1)
+    console.print(result.answer or f"[yellow]stopped: {result.stopped_reason.value}[/]")
+    console.print(
+        f"\n[dim]stopped: {result.stopped_reason.value} · steps: {result.state.step} · "
+        f"${result.usage.cost_usd:.4f} · {result.usage.total_tokens} tok · "
+        f"trace: {trace_path}[/]"
+    )
+
+
+@app.command()
+def trace(
+    session: str = typer.Argument(None, help="Session id to inspect; omit to list recent."),
+    path: Path = typer.Option(Path("."), help="Project root."),
+) -> None:
+    """Inspect a recorded run trace (saved by `spine chat`)."""
+    import json
+
+    from spine_cli.builder import TRACES_DIR
+
+    project_root = _project_root(path)
+    traces_dir = project_root / TRACES_DIR
+    if not traces_dir.is_dir():
+        console.print("[dim]no traces recorded yet[/]")
+        return
+
+    if session is None:
+        files = sorted(traces_dir.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)
+        table = Table("session", "stopped", "events")
+        for file in files[:20]:
+            data = json.loads(file.read_text())
+            table.add_row(
+                file.stem, data.get("stopped_reason", "?"), str(len(data.get("events", [])))
+            )
+        console.print(table)
+        return
+
+    file = traces_dir / f"{session}.json"
+    if not file.is_file():
+        console.print(f"[red]error:[/] no trace for session {session!r}")
+        raise typer.Exit(1)
+    data = json.loads(file.read_text())
+    table = Table("seq", "step", "type", "detail")
+    for event in data.get("events", []):
+        detail = ", ".join(f"{k}={v}" for k, v in event.get("data", {}).items())
+        table.add_row(str(event.get("seq")), str(event.get("step")), event.get("type", ""), detail)
+    console.print(table)
+
+
+# -- helpers ----------------------------------------------------------------
+
+
+def _project_root(path: Path) -> Path:
+    config_path = find_config(path)
+    return config_path.parent if config_path is not None else path.resolve()
+
+
+def _load_agent(target: str, project_root: Path) -> Any:
+    root = str(project_root)
+    if root not in sys.path:
+        sys.path.insert(0, root)
+    module_name, _, attr = target.partition(":")
+    if not attr:
+        module_name, attr = f"agents.{target}", "agent"
+    module = importlib.import_module(module_name)
+    agent = getattr(module, attr)
+    return agent
+
+
+def _render_doctor(rows: list[tuple[str, str, str]]) -> None:
+    table = Table("check", "status", "detail")
+    for check, status, detail in rows:
+        table.add_row(check, status, detail)
+    console.print(table)

spine_cli/builder.py

@@ -0,0 +1,86 @@
+"""Build a live :class:`Agent` from declarative ``spine.toml`` config.
+
+This closes the gap between the declared config (model, guards, middleware chain,
+checkpoint backend) and a running agent: names in the chain are resolved through
+the core registries, which installed plugins populate.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from spine_cli.config import SpineConfig
+from spine_cli.plugins import load_all
+from spine_core import (
+    Agent,
+    Provider,
+    Result,
+    Tool,
+    resolve_checkpoint,
+    resolve_middleware,
+)
+
+TRACES_DIR = ".spine/traces"
+
+
+def _ensure_on_path(project_root: Path) -> None:
+    root = str(project_root)
+    if root not in sys.path:
+        sys.path.insert(0, root)
+
+
+def discover_tools(project_root: Path) -> list[Tool]:
+    """Collect ``@tool`` instances exposed by the project's ``tools`` package."""
+    _ensure_on_path(project_root)
+    # Drop any cached "tools" so discovery always reads the current project's.
+    sys.modules.pop("tools", None)
+    try:
+        module = importlib.import_module("tools")
+    except ImportError:
+        return []
+    return [value for value in vars(module).values() if isinstance(value, Tool)]
+
+
+def build_agent(
+    config: SpineConfig,
+    project_root: Path,
+    *,
+    provider: Provider | str | None = None,
+) -> Agent:
+    """Construct an Agent from config: model, guards, middleware, backend, tools."""
+    load_all()  # import installed plugins so registry names resolve
+
+    middleware = [
+        resolve_middleware(name, **config.plugins.get(name, {})) for name in config.middleware.chain
+    ]
+    checkpoint = None
+    if config.backends.checkpoint:
+        backend = config.backends.checkpoint
+        checkpoint = resolve_checkpoint(backend, **config.plugins.get(backend, {}))
+
+    return Agent(
+        provider or config.default_model,
+        tools=discover_tools(project_root),
+        guards=config.guards,
+        middleware=middleware,
+        checkpoint=checkpoint,
+        system=config.system,
+    )
+
+
+def save_trace(project_root: Path, result: Result) -> Path:
+    """Persist a run's trace under ``.spine/traces/<session>.json`` for `spine trace`."""
+    directory = project_root / TRACES_DIR
+    directory.mkdir(parents=True, exist_ok=True)
+    path = directory / f"{result.state.session_id}.json"
+    payload: dict[str, Any] = {
+        "session_id": result.state.session_id,
+        "stopped_reason": result.stopped_reason.value,
+        "events": [event.model_dump() for event in result.trace],
+    }
+    path.write_text(json.dumps(payload, default=str, indent=2))
+    return path

spine_cli/config.py

@@ -0,0 +1,92 @@
+"""``spine.toml`` loader.
+
+An agent's full behavior is reproducible from version control: model, guards,
+middleware order, and backends are declared here. Secrets are never inlined —
+``${ENV_VAR}`` references are interpolated from the environment at load time.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from spine_core import Guards
+
+_ENV_REF = re.compile(r"\$\{([^}]+)\}")
+
+CONFIG_FILENAME = "spine.toml"
+
+
+class MiddlewareConfig(BaseModel):
+    chain: list[str] = Field(default_factory=list)
+
+
+class BackendsConfig(BaseModel):
+    checkpoint: str | None = None
+    memory: str | None = None
+
+
+class SpineConfig(BaseModel):
+    default_model: str = "anthropic:claude-sonnet-4-6"
+    system: str | None = None
+    guards: Guards = Field(default_factory=Guards)
+    middleware: MiddlewareConfig = Field(default_factory=MiddlewareConfig)
+    backends: BackendsConfig = Field(default_factory=BackendsConfig)
+    plugins: dict[str, dict[str, Any]] = Field(default_factory=dict)
+
+
+class ConfigError(Exception):
+    """``spine.toml`` is missing, malformed, or references an unset env var."""
+
+
+def _interpolate(value: Any) -> Any:
+    """Recursively replace ``${VAR}`` with the environment value."""
+    if isinstance(value, str):
+
+        def repl(match: re.Match[str]) -> str:
+            name = match.group(1)
+            resolved = os.environ.get(name)
+            if resolved is None:
+                raise ConfigError(
+                    f"environment variable '{name}' referenced in spine.toml is unset"
+                )
+            return resolved
+
+        return _ENV_REF.sub(repl, value)
+    if isinstance(value, dict):
+        return {k: _interpolate(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_interpolate(v) for v in value]
+    return value
+
+
+def find_config(start: Path) -> Path | None:
+    """Search ``start`` and its parents for ``spine.toml``."""
+    start = start.resolve()
+    for directory in (start, *start.parents):
+        candidate = directory / CONFIG_FILENAME
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load_config(path: Path) -> SpineConfig:
+    """Load and validate ``spine.toml`` at ``path`` (a file or its directory)."""
+    config_path = path if path.is_file() else path / CONFIG_FILENAME
+    if not config_path.is_file():
+        raise ConfigError(f"no {CONFIG_FILENAME} found at {config_path}")
+    try:
+        raw = tomllib.loads(config_path.read_text())
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{config_path} is not valid TOML: {exc}") from exc
+
+    section = _interpolate(raw.get("spine", {}))
+    try:
+        return SpineConfig.model_validate(section)
+    except Exception as exc:  # pydantic ValidationError
+        raise ConfigError(f"invalid [spine] config in {config_path}: {exc}") from exc