spawnllm 0.3.1__tar.gz → 0.5.0__tar.gz

{spawnllm-0.3.1 → spawnllm-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawnllm
-Version: 0.3.1
+Version: 0.5.0
 Summary: Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
 Keywords: 
 Author: Yasyf Mohamedali
@@ -64,24 +64,13 @@ domain logic instead of its own copy of the backends.
 
 ## Install
 
-No install needed — run everything through [uvx](https://docs.astral.sh/uv/):
+Run the CLI with [uvx](https://docs.astral.sh/uv/):
 
 ```bash
 uvx spawnllm --help
 ```
 
-`uvx` fetches spawnllm into a throwaway environment and runs it. To add it
-to a project instead:
-
-```bash
-uv add spawnllm
-```
-
-For the local MLX engine (Apple Silicon only), pull the extra:
-
-```bash
-uv add "spawnllm[mlx]"
-```
+For the local MLX engine (Apple Silicon only), pull the extra: `uv add "spawnllm[mlx]"`.
 
 ## Quickstart
 
@@ -107,19 +96,20 @@ uvx spawnllm call --backend claude "What is 2+2? Reply with just the number."
 4
 ```
 
-`--model small|medium|large` swaps the tier, which each backend maps to a concrete model.
-The `claude` backend resolves `small` to Haiku, `medium` to Sonnet, and `large` to Opus. Add
-`--agent` to let the call use tools.
+`--model small|medium|large` swaps the tier, which each backend maps to a concrete model — the
+`claude` backend resolves `small` to Haiku, `medium` to Sonnet, and `large` to Opus. Add
+`--agent` to let the call use tools. Run `uvx spawnllm --help` for the full flag list.
 
 ### From Python
 
-`call` runs one request and returns the response. With no `backend`, it auto-selects the
-first installed, authenticated CLI:
+`call_sync` runs one request and returns the response. With no `backend`, it auto-selects
+the first installed, authenticated CLI (its async companion `call` mirrors the same
+signature):
 
 ```python
-from spawnllm import call
+from spawnllm import call_sync
 
-print(call("Reply with just the word: pong"))
+print(call_sync("Reply with just the word: pong"))
 # pong
 ```
 
@@ -129,7 +119,7 @@ instead of text:
 ```python
 from pydantic import BaseModel
 
-from spawnllm import call, ClaudeCliBackend
+from spawnllm import call_sync, ClaudeCliBackend
 
 
 class Capital(BaseModel):
@@ -137,7 +127,7 @@ class Capital(BaseModel):
     capital: str
 
 
-result = call(
+result = call_sync(
     "What is the capital of France?",
     backend=ClaudeCliBackend(),
     model="large",
@@ -149,21 +139,35 @@ print(result.capital)  # Paris
 When you don't pin a backend, set `specialty=` to scope auto-selection by task. The
 `debugging` and `review` specialties route to Codex, and `general` routes to Claude.
 
-## What problems does this solve?
+### Spec-driven runs
 
-Every tool that shells out to `claude` or `codex` rebuilds the same plumbing: argv
-construction, stdin/stdout piping, stderr teeing, and turning non-zero exits into useful
-errors. spawnllm holds it once.
+For full control, build a `RunSpec` and execute it with `run_sync` (or its async companion
+`run`). A `RunSpec` takes a literal provider model id — no tier mapping — and per-provider
+flag passthrough via `provider_configs`. The call returns a `RunResult` with raw stdout,
+stderr, and exit code, retrying transient `529`/overloaded/rate-limit failures with backoff:
 
-Structured output is boilerplate too. A Pydantic model becomes a JSON-schema constraint
-and a parsed, validated result, identically for both CLI backends.
+```python
+from spawnllm import run_sync, RunSpec, ClaudeConfig, ClaudeCliBackend
+
+result = run_sync(
+    RunSpec(
+        prompt="What is 2+2? Reply with just the number.",
+        model="opus",
+        provider_configs={"claude": ClaudeConfig(permission_mode="bypassPermissions")},
+    ),
+    backend=ClaudeCliBackend(),
+)
+print(result.stdout)  # 4
+```
 
-Local MLX is fiddly. Adapter fusion, prompt-cache reuse, worker-thread lifecycle, and
-batched single-token generation live behind one engine instead of in every consumer.
+## How it works
 
-Behavior drift goes away with the duplication: two tools that call the same models stay
-byte-for-byte consistent because they share the backend layer, not a pair of diverging
-copies.
+Each backend holds plumbing that consumers would otherwise rebuild: the CLI backends own argv
+construction, stdin/stdout piping, stderr teeing, and turning non-zero exits into useful errors,
+and they turn a Pydantic model into a JSON-schema constraint plus a parsed, validated result. The
+MLX engine wraps adapter fusion, prompt-cache reuse, worker-thread lifecycle, and batched
+single-token generation. Tools that share the layer stay byte-for-byte consistent instead of
+drifting across diverging copies.
 
 ## Docs
 

{spawnllm-0.3.1 → spawnllm-0.5.0}/README.md

@@ -17,24 +17,13 @@ domain logic instead of its own copy of the backends.
 
 ## Install
 
-No install needed — run everything through [uvx](https://docs.astral.sh/uv/):
+Run the CLI with [uvx](https://docs.astral.sh/uv/):
 
 ```bash
 uvx spawnllm --help
 ```
 
-`uvx` fetches spawnllm into a throwaway environment and runs it. To add it
-to a project instead:
-
-```bash
-uv add spawnllm
-```
-
-For the local MLX engine (Apple Silicon only), pull the extra:
-
-```bash
-uv add "spawnllm[mlx]"
-```
+For the local MLX engine (Apple Silicon only), pull the extra: `uv add "spawnllm[mlx]"`.
 
 ## Quickstart
 
@@ -60,19 +49,20 @@ uvx spawnllm call --backend claude "What is 2+2? Reply with just the number."
 4
 ```
 
-`--model small|medium|large` swaps the tier, which each backend maps to a concrete model.
-The `claude` backend resolves `small` to Haiku, `medium` to Sonnet, and `large` to Opus. Add
-`--agent` to let the call use tools.
+`--model small|medium|large` swaps the tier, which each backend maps to a concrete model — the
+`claude` backend resolves `small` to Haiku, `medium` to Sonnet, and `large` to Opus. Add
+`--agent` to let the call use tools. Run `uvx spawnllm --help` for the full flag list.
 
 ### From Python
 
-`call` runs one request and returns the response. With no `backend`, it auto-selects the
-first installed, authenticated CLI:
+`call_sync` runs one request and returns the response. With no `backend`, it auto-selects
+the first installed, authenticated CLI (its async companion `call` mirrors the same
+signature):
 
 ```python
-from spawnllm import call
+from spawnllm import call_sync
 
-print(call("Reply with just the word: pong"))
+print(call_sync("Reply with just the word: pong"))
 # pong
 ```
 
@@ -82,7 +72,7 @@ instead of text:
 ```python
 from pydantic import BaseModel
 
-from spawnllm import call, ClaudeCliBackend
+from spawnllm import call_sync, ClaudeCliBackend
 
 
 class Capital(BaseModel):
@@ -90,7 +80,7 @@ class Capital(BaseModel):
     capital: str
 
 
-result = call(
+result = call_sync(
     "What is the capital of France?",
     backend=ClaudeCliBackend(),
     model="large",
@@ -102,21 +92,35 @@ print(result.capital)  # Paris
 When you don't pin a backend, set `specialty=` to scope auto-selection by task. The
 `debugging` and `review` specialties route to Codex, and `general` routes to Claude.
 
-## What problems does this solve?
+### Spec-driven runs
 
-Every tool that shells out to `claude` or `codex` rebuilds the same plumbing: argv
-construction, stdin/stdout piping, stderr teeing, and turning non-zero exits into useful
-errors. spawnllm holds it once.
+For full control, build a `RunSpec` and execute it with `run_sync` (or its async companion
+`run`). A `RunSpec` takes a literal provider model id — no tier mapping — and per-provider
+flag passthrough via `provider_configs`. The call returns a `RunResult` with raw stdout,
+stderr, and exit code, retrying transient `529`/overloaded/rate-limit failures with backoff:
 
-Structured output is boilerplate too. A Pydantic model becomes a JSON-schema constraint
-and a parsed, validated result, identically for both CLI backends.
+```python
+from spawnllm import run_sync, RunSpec, ClaudeConfig, ClaudeCliBackend
+
+result = run_sync(
+    RunSpec(
+        prompt="What is 2+2? Reply with just the number.",
+        model="opus",
+        provider_configs={"claude": ClaudeConfig(permission_mode="bypassPermissions")},
+    ),
+    backend=ClaudeCliBackend(),
+)
+print(result.stdout)  # 4
+```
 
-Local MLX is fiddly. Adapter fusion, prompt-cache reuse, worker-thread lifecycle, and
-batched single-token generation live behind one engine instead of in every consumer.
+## How it works
 
-Behavior drift goes away with the duplication: two tools that call the same models stay
-byte-for-byte consistent because they share the backend layer, not a pair of diverging
-copies.
+Each backend holds plumbing that consumers would otherwise rebuild: the CLI backends own argv
+construction, stdin/stdout piping, stderr teeing, and turning non-zero exits into useful errors,
+and they turn a Pydantic model into a JSON-schema constraint plus a parsed, validated result. The
+MLX engine wraps adapter fusion, prompt-cache reuse, worker-thread lifecycle, and batched
+single-token generation. Tools that share the layer stay byte-for-byte consistent instead of
+drifting across diverging copies.
 
 ## Docs
 

{spawnllm-0.3.1 → spawnllm-0.5.0}/pyproject.toml

@@ -1,6 +1,7 @@
 [project]
 name = "spawnllm"
-version = "0.3.1"
+# Inert sentinel: the real version is set from the release tag (uv version --frozen).
+version = "0.5.0"
 description = "Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools."
 readme = "README.md"
 license = "MIT"

spawnllm-0.5.0/spawnllm/__init__.py

@@ -0,0 +1,66 @@
+"""Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
+
+The top-level namespace exposes the three primitives — `run`/`call`/`extract`
+and their `_sync` companions — over a `Backend` family that fully encapsulates
+execution and returns one shared `Response`. The MLX engine lives under
+`spawnllm.mlx`, whose imports are lazy so that `import spawnllm` never pulls
+`mlx_lm`/`zstandard`.
+"""
+
+from __future__ import annotations
+
+from spawnllm.backends import (
+    AntigravityCliBackend,
+    BackendCallError,
+    BackendNotAuthenticated,
+    BackendNotInstalled,
+    BackendReady,
+    BackendStatus,
+    BackendUnavailable,
+    ClaudeCliBackend,
+    CliBackend,
+    CodexCliBackend,
+    GeminiCliBackend,
+    LlmBackend,
+    LlmBackends,
+    MlxBackend,
+    select_backend,
+)
+from spawnllm.call import call, call_sync
+from spawnllm.extract import extract, extract_sync
+from spawnllm.response import Response
+from spawnllm.run import run, run_sync
+from spawnllm.spec import ClaudeConfig, CodexConfig, GeminiConfig, RunSpec
+from spawnllm.types import ProviderName, TModel, TSpecialty
+
+__all__ = [
+    "AntigravityCliBackend",
+    "BackendCallError",
+    "BackendNotAuthenticated",
+    "BackendNotInstalled",
+    "BackendReady",
+    "BackendStatus",
+    "BackendUnavailable",
+    "ClaudeCliBackend",
+    "ClaudeConfig",
+    "CliBackend",
+    "CodexCliBackend",
+    "CodexConfig",
+    "GeminiCliBackend",
+    "GeminiConfig",
+    "LlmBackend",
+    "LlmBackends",
+    "MlxBackend",
+    "ProviderName",
+    "Response",
+    "RunSpec",
+    "TModel",
+    "TSpecialty",
+    "call",
+    "call_sync",
+    "extract",
+    "extract_sync",
+    "run",
+    "run_sync",
+    "select_backend",
+]

{spawnllm-0.3.1 → spawnllm-0.5.0}/spawnllm/backends/__init__.py

@@ -3,31 +3,35 @@
 from __future__ import annotations
 
 from spawnllm.backends.base import (
+    BackendCallError,
     BackendNotAuthenticated,
     BackendNotInstalled,
     BackendReady,
     BackendStatus,
     BackendUnavailable,
-    Invocation,
+    CliBackend,
     LlmBackend,
 )
 from spawnllm.backends.claude import ClaudeCliBackend
 from spawnllm.backends.codex import CodexCliBackend
 from spawnllm.backends.gemini import AntigravityCliBackend, GeminiCliBackend
+from spawnllm.backends.mlx import MlxBackend
 from spawnllm.backends.registry import LlmBackends, select_backend
 
 __all__ = [
     "AntigravityCliBackend",
+    "BackendCallError",
     "BackendNotAuthenticated",
     "BackendNotInstalled",
     "BackendReady",
     "BackendStatus",
     "BackendUnavailable",
     "ClaudeCliBackend",
+    "CliBackend",
     "CodexCliBackend",
     "GeminiCliBackend",
-    "Invocation",
     "LlmBackend",
     "LlmBackends",
+    "MlxBackend",
     "select_backend",
 ]

spawnllm-0.5.0/spawnllm/backends/base.py

@@ -0,0 +1,313 @@
+"""Abstract execution contract for an LLM backend and its subprocess family."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar
+
+from spawnllm.proc import acapture_cli, capture_cli
+from spawnllm.response import Response
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from spawnllm.spec import RunSpec
+    from spawnllm.types import ProviderName, TModel
+
+
+@dataclass(frozen=True)
+class BackendReady:
+    """A backend whose CLI is installed and authenticated.
+
+    Attributes:
+        binary: Name of the backend's CLI executable on PATH.
+    """
+
+    binary: str
+
+
+@dataclass(frozen=True)
+class BackendNotInstalled:
+    """A backend whose CLI is not on PATH.
+
+    Attributes:
+        binary: Name of the backend's CLI executable.
+        install_hint: Suggested shell command to install the CLI.
+    """
+
+    binary: str
+    install_hint: str
+
+
+@dataclass(frozen=True)
+class BackendNotAuthenticated:
+    """A backend whose CLI is installed but not authenticated.
+
+    Attributes:
+        binary: Name of the backend's CLI executable on PATH.
+    """
+
+    binary: str
+
+
+BackendStatus = BackendReady | BackendNotInstalled | BackendNotAuthenticated
+"""Result of `LlmBackend.check_status`: `BackendReady`, `BackendNotInstalled`, or `BackendNotAuthenticated`."""
+
+
+class BackendUnavailable(RuntimeError):
+    """Raised when no backend is ready (installed and authenticated)."""
+
+
+class BackendCallError(RuntimeError):
+    """Raised by `call`/`extract` when a backend returns a provider error.
+
+    Carries the backend's error string (a nonzero exit with stderr, or an error
+    envelope), attached both as the message and as a note for tracebacks.
+    """
+
+    def __init__(self, error: str) -> None:
+        super().__init__(error)
+        self.add_note(error)
+
+
+@dataclass(frozen=True)
+class Invocation:
+    """A built CLI invocation: argv, optional stdin, and where to read the result.
+
+    Attributes:
+        argv: The argv list to execute.
+        stdin: Prompt text delivered over stdin, or `None` when delivered inline.
+        result_path: File the backend writes its final message to; when set, the
+            result is read from this file instead of stdout.
+        cleanup_paths: Temp files to remove once the invocation completes.
+    """
+
+    argv: list[str]
+    stdin: str | None = None
+    result_path: str | None = None
+    cleanup_paths: tuple[str, ...] = ()
+
+
+class LlmBackend(ABC):
+    """Abstract execution contract for an LLM backend.
+
+    Concrete backends map abstract model sizes to provider-specific model names
+    and encapsulate how to execute a `RunSpec` and parse the raw response.
+
+    Attributes:
+        models: Mapping from abstract model size to the provider's model name.
+        provider: Provider identifier keying a `RunSpec`'s `provider_configs`.
+    """
+
+    models: ClassVar[dict[TModel, str]]
+    provider: ClassVar[ProviderName]
+
+    @abstractmethod
+    async def aexecute(self, spec: RunSpec) -> Response:
+        """Execute a single run asynchronously and resolve it to a `Response`.
+
+        The backend runs the process, reads its output wherever the provider
+        writes it, detects failure, and validates against `spec.response_model`.
+
+        Args:
+            spec: The configured run to execute.
+
+        Returns:
+            The resolved `Response`.
+        """
+
+    @abstractmethod
+    def execute(self, spec: RunSpec) -> Response:
+        """Execute a single run synchronously and resolve it to a `Response`.
+
+        Args:
+            spec: The configured run to execute.
+
+        Returns:
+            The resolved `Response`.
+        """
+
+    @abstractmethod
+    def env(self) -> dict[str, str]:
+        """Return extra environment variables for the invocation, merged over the inherited environment."""
+
+    @abstractmethod
+    def is_authenticated(self, *, timeout: int) -> bool:
+        """Probe whether the backend holds valid credentials for its provider.
+
+        "Authenticated" means the backend reports an active login session for the
+        provider, not merely that an executable is present on PATH.
+
+        Args:
+            timeout: Seconds to wait for the credential probe.
+
+        Returns:
+            `True` when the backend reports an authenticated session.
+        """
+
+    @abstractmethod
+    def check_status(self, *, timeout: int = 10) -> BackendStatus:
+        """Check whether this backend is installed and authenticated.
+
+        Args:
+            timeout: Seconds to wait for the authentication probe.
+
+        Returns:
+            `BackendReady` when authenticated, `BackendNotInstalled` when the
+            backend is not available, else `BackendNotAuthenticated`.
+        """
+
+    def schema_for(self, model: type[BaseModel]) -> str:
+        """Serialize a Pydantic model into the JSON-schema string this backend expects.
+
+        The default emits the model's plain JSON schema; provider backends
+        override to apply their SDK's strict-schema transform.
+
+        Args:
+            model: The Pydantic model describing the structured output.
+
+        Returns:
+            A JSON-schema string suitable for this backend's structured-output argument.
+        """
+        return json.dumps(model.model_json_schema())
+
+    def schema_arg(self, spec: RunSpec) -> str | None:
+        """Return the JSON-schema string for `spec`'s `response_model`, or `None` when absent."""
+        return self.schema_for(spec.response_model) if spec.response_model is not None else None
+
+    def to_response(self, raw: str, *, returncode: int, stderr: str, spec: RunSpec) -> Response:
+        """Resolve a raw capture into a `Response`: detect failure, extract text, validate.
+
+        A nonzero exit or an error envelope becomes `Response.error`; otherwise
+        the text comes from `result_text` and, when `spec.response_model` is set,
+        the validated model from `result_value`. A `pydantic.ValidationError`
+        from a non-conforming model propagates.
+
+        Args:
+            raw: The raw output read wherever the provider wrote it.
+            returncode: The process exit code.
+            stderr: The captured stderr.
+            spec: The configured run, carrying the optional `response_model`.
+
+        Returns:
+            The resolved `Response`.
+        """
+        if returncode != 0:
+            return Response(error=f"{self.provider} exited {returncode}: {stderr.strip()[-2000:]}", result=None)
+        if (err := self.envelope_error(raw)) is not None:
+            return Response(error=err, result=None)
+        if spec.response_model is None:
+            return Response(error=None, result=self.result_text(raw))
+        return Response(
+            error=None, result=self.result_text(raw), parsed=spec.response_model.model_validate(self.result_value(raw))
+        )
+
+    def result_text(self, raw: str) -> str:
+        """Return the final text output from a raw capture; the default is `raw` unchanged."""
+        return raw
+
+    def result_value(self, raw: str) -> object:
+        """Return the JSON value to validate from a raw capture; the default parses `raw` as JSON."""
+        return json.loads(raw)
+
+    def envelope_error(self, raw: str) -> str | None:
+        """Return the provider's error message from an error envelope, or `None` on success."""
+        return None
+
+
+class CliBackend(LlmBackend):
+    """Execution contract for the subprocess-backed LLM family.
+
+    Concrete CLI backends build an argv from a `RunSpec`; `aexecute`/`execute`
+    run it, merge environment overrides, and resolve the result from stdout or a
+    designated result file.
+
+    Attributes:
+        binary: Name of the backend's CLI executable on PATH.
+        install_hint: Suggested shell command to install the CLI.
+    """
+
+    binary: ClassVar[str]
+    install_hint: ClassVar[str]
+
+    @abstractmethod
+    def build_command(self, spec: RunSpec) -> list[str]:
+        """Build the CLI argv for a single invocation.
+
+        Args:
+            spec: The configured run to translate into argv.
+
+        Returns:
+            The argv list to execute.
+        """
+
+    def invocation(self, spec: RunSpec) -> Invocation:
+        """Build the argv, stdin, and result source for a single invocation.
+
+        The default delivers the prompt over stdin and reads the result from
+        stdout; subclasses override to deliver the prompt inline or to read the
+        result from a file.
+
+        Args:
+            spec: The configured run to translate into an invocation.
+
+        Returns:
+            An `Invocation` carrying the argv, stdin text, and result source.
+        """
+        return Invocation(self.build_command(spec), spec.prompt)
+
+    async def aexecute(self, spec: RunSpec) -> Response:
+        inv = self.invocation(spec)
+        try:
+            rr = await acapture_cli(
+                inv.argv,
+                input=inv.stdin,
+                env=os.environ | self.env() | (spec.env or {}),
+                cwd=spec.cwd,
+                timeout=spec.timeout,
+            )
+            raw = Path(inv.result_path).read_text() if inv.result_path else rr.stdout
+        finally:
+            for path in inv.cleanup_paths:
+                Path(path).unlink(missing_ok=True)
+        return self.to_response(raw, returncode=rr.returncode, stderr=rr.stderr, spec=spec)
+
+    def execute(self, spec: RunSpec) -> Response:
+        inv = self.invocation(spec)
+        try:
+            rr = capture_cli(
+                inv.argv,
+                input=inv.stdin,
+                env=os.environ | self.env() | (spec.env or {}),
+                cwd=spec.cwd,
+                timeout=spec.timeout,
+            )
+            raw = Path(inv.result_path).read_text() if inv.result_path else rr.stdout
+        finally:
+            for path in inv.cleanup_paths:
+                Path(path).unlink(missing_ok=True)
+        return self.to_response(raw, returncode=rr.returncode, stderr=rr.stderr, spec=spec)
+
+    def check_status(self, *, timeout: int = 10) -> BackendStatus:
+        """Check whether this backend's CLI is installed and authenticated.
+
+        Args:
+            timeout: Seconds to wait for the authentication probe.
+
+        Returns:
+            `BackendReady` when authenticated, `BackendNotInstalled` when the CLI
+            is not on PATH, else `BackendNotAuthenticated`.
+
+        Raises:
+            subprocess.TimeoutExpired: If `is_authenticated` exceeds `timeout`.
+        """
+        if not shutil.which(self.binary):
+            return BackendNotInstalled(binary=self.binary, install_hint=self.install_hint)
+        if self.is_authenticated(timeout=timeout):
+            return BackendReady(binary=self.binary)
+        return BackendNotAuthenticated(binary=self.binary)