spawnllm 0.4.0__tar.gz → 0.5.1__tar.gz

{spawnllm-0.4.0 → spawnllm-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawnllm
-Version: 0.4.0
+Version: 0.5.1
 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,9 +96,9 @@ 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
 
@@ -171,21 +160,14 @@ result = run_sync(
 print(result.stdout)  # 4
 ```
 
-## What problems does this solve?
-
-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.
-
-Structured output is boilerplate too. A Pydantic model becomes a JSON-schema constraint
-and a parsed, validated result, identically for both CLI backends.
-
-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.4.0 → spawnllm-0.5.1}/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,9 +49,9 @@ 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
 
@@ -124,21 +113,14 @@ result = run_sync(
 print(result.stdout)  # 4
 ```
 
-## What problems does this solve?
-
-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.
-
-Structured output is boilerplate too. A Pydantic model becomes a JSON-schema constraint
-and a parsed, validated result, identically for both CLI backends.
-
-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.4.0 → spawnllm-0.5.1}/pyproject.toml

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

{spawnllm-0.4.0 → spawnllm-0.5.1}/spawnllm/__init__.py

@@ -1,14 +1,17 @@
 """Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
 
-The top-level namespace exposes the CLI backends, subprocess transport, and
-structured-output helpers. The MLX engine lives under `spawnllm.mlx`, whose
-imports are lazy so that `import spawnllm` never pulls `mlx_lm`/`zstandard`.
+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,
@@ -18,26 +21,21 @@ from spawnllm.backends import (
     CliBackend,
     CodexCliBackend,
     GeminiCliBackend,
-    Invocation,
     LlmBackend,
     LlmBackends,
     MlxBackend,
     select_backend,
 )
 from spawnllm.call import call, call_sync
-from spawnllm.proc import RunResult, arun_cli, collect_process, map_concurrent, run_cli
+from spawnllm.extract import extract, extract_sync
+from spawnllm.response import Error, Output, Response, Result
 from spawnllm.run import run, run_sync
 from spawnllm.spec import ClaudeConfig, CodexConfig, GeminiConfig, RunSpec
-from spawnllm.structured import (
-    extract_structured,
-    parse_result_envelope,
-    parse_structured_output,
-    resolve_schema_path,
-)
 from spawnllm.types import ProviderName, TModel, TSpecialty
 
 __all__ = [
     "AntigravityCliBackend",
+    "BackendCallError",
     "BackendNotAuthenticated",
     "BackendNotInstalled",
     "BackendReady",
@@ -48,28 +46,24 @@ __all__ = [
     "CliBackend",
     "CodexCliBackend",
     "CodexConfig",
+    "Error",
     "GeminiCliBackend",
     "GeminiConfig",
-    "Invocation",
     "LlmBackend",
     "LlmBackends",
     "MlxBackend",
+    "Output",
     "ProviderName",
-    "RunResult",
+    "Response",
+    "Result",
     "RunSpec",
     "TModel",
     "TSpecialty",
-    "arun_cli",
     "call",
     "call_sync",
-    "collect_process",
-    "extract_structured",
-    "map_concurrent",
-    "parse_result_envelope",
-    "parse_structured_output",
-    "resolve_schema_path",
+    "extract",
+    "extract_sync",
     "run",
-    "run_cli",
     "run_sync",
     "select_backend",
 ]

{spawnllm-0.4.0 → spawnllm-0.5.1}/spawnllm/backends/__init__.py

@@ -3,13 +3,13 @@
 from __future__ import annotations
 
 from spawnllm.backends.base import (
+    BackendCallError,
     BackendNotAuthenticated,
     BackendNotInstalled,
     BackendReady,
     BackendStatus,
     BackendUnavailable,
     CliBackend,
-    Invocation,
     LlmBackend,
 )
 from spawnllm.backends.claude import ClaudeCliBackend
@@ -20,6 +20,7 @@ from spawnllm.backends.registry import LlmBackends, select_backend
 
 __all__ = [
     "AntigravityCliBackend",
+    "BackendCallError",
     "BackendNotAuthenticated",
     "BackendNotInstalled",
     "BackendReady",
@@ -29,7 +30,6 @@ __all__ = [
     "CliBackend",
     "CodexCliBackend",
     "GeminiCliBackend",
-    "Invocation",
     "LlmBackend",
     "LlmBackends",
     "MlxBackend",

{spawnllm-0.4.0 → spawnllm-0.5.1}/spawnllm/backends/base.py

@@ -5,12 +5,14 @@ from __future__ import annotations
 import json
 import os
 import shutil
+import subprocess
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, ClassVar
 
-from spawnllm.proc import RunResult, acapture_cli, capture_cli
+from spawnllm.proc import acapture_cli, capture_cli
+from spawnllm.response import Error, Output, Response, Result
 
 if TYPE_CHECKING:
     from pydantic import BaseModel
@@ -62,6 +64,13 @@ 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.
+    """
+
+
 @dataclass(frozen=True)
 class Invocation:
     """A built CLI invocation: argv, optional stdin, and where to read the result.
@@ -95,37 +104,28 @@ class LlmBackend(ABC):
     provider: ClassVar[ProviderName]
 
     @abstractmethod
-    async def aexecute(self, spec: RunSpec) -> RunResult:
-        """Execute a single run asynchronously and capture its raw outcome.
+    async def aexecute(self, spec: RunSpec) -> Response:
+        """Execute a single run asynchronously and resolve it to a `Response`.
 
-        Args:
-            spec: The configured run to execute.
-
-        Returns:
-            The captured stdout, stderr, and exit code.
-        """
-
-    @abstractmethod
-    def execute(self, spec: RunSpec) -> RunResult:
-        """Execute a single run synchronously and capture its raw outcome.
+        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 captured stdout, stderr, and exit code.
+            The resolved `Response`.
         """
 
     @abstractmethod
-    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
-        """Parse raw stdout into text or a validated model.
+    def execute(self, spec: RunSpec) -> Response:
+        """Execute a single run synchronously and resolve it to a `Response`.
 
         Args:
-            raw: Raw stdout from the backend.
-            response_model: Model to validate against, or `None` for raw text.
+            spec: The configured run to execute.
 
         Returns:
-            `raw` when `response_model` is `None`, else a validated instance.
+            The resolved `Response`.
         """
 
     @abstractmethod
@@ -172,6 +172,73 @@ class LlmBackend(ABC):
         """
         return json.dumps(model.model_json_schema())
 
+    def schema_arg(self, spec: RunSpec) -> str | None:
+        """Return the JSON-schema string for `spec`, from a `response_model` or a raw `schema`.
+
+        A `response_model` is run through `schema_for` (the provider's
+        strict-schema transform); a raw `schema` passes verbatim — a dict is
+        `json.dumps`'d, a string is returned unchanged. Returns `None` when
+        neither is set.
+
+        Args:
+            spec: The configured run, carrying the optional `response_model` or `schema`.
+
+        Returns:
+            The JSON-schema string for this backend's structured-output argument, or `None`.
+        """
+        if spec.response_model is not None:
+            return self.schema_for(spec.response_model)
+        if spec.schema is not None:
+            return json.dumps(spec.schema) if isinstance(spec.schema, dict) else spec.schema
+        return None
+
+    def to_response(self, raw: str, *, returncode: int, stderr: str, spec: RunSpec) -> Response:
+        """Resolve a raw capture into a structured `Response`: detect failure, extract text, validate.
+
+        `output` always carries the full raw stream. A nonzero exit, an error
+        envelope, or a `pydantic.ValidationError` from a non-conforming model all
+        route through `error` (with the underlying exception preserved in
+        `error.ex`) and leave `result` as `None`; a success yields `result` (text
+        from `result_text`, plus the validated model from `result_value` when
+        `spec.response_model` is set) and `error` as `None`.
+
+        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` or `schema`.
+
+        Returns:
+            The resolved `Response`.
+        """
+        import pydantic
+
+        output = Output(raw)
+        if returncode != 0:
+            msg = f"{self.provider} exited {returncode}: {stderr.strip()[-2000:]}"
+            return Response(spec=spec, output=output, error=Error(msg, BackendCallError(msg)))
+        if (err := self.envelope_error(raw)) is not None:
+            return Response(spec=spec, output=output, error=Error(err, BackendCallError(err)))
+        if spec.response_model is None:
+            return Response(spec=spec, output=output, result=Result(raw=self.result_text(raw)))
+        try:
+            parsed = spec.response_model.model_validate(self.result_value(raw))
+        except pydantic.ValidationError as e:
+            return Response(spec=spec, output=output, error=Error(str(e), e))
+        return Response(spec=spec, output=output, result=Result(raw=self.result_text(raw), parsed=parsed))
+
+    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.
@@ -214,37 +281,47 @@ class CliBackend(LlmBackend):
         """
         return Invocation(self.build_command(spec), spec.prompt)
 
-    async def aexecute(self, spec: RunSpec) -> RunResult:
+    def timed_out(self, spec: RunSpec) -> Response:
+        msg = f"{self.provider} timed out after {spec.timeout}s"
+        return Response(spec=spec, output=Output(""), error=Error(msg, TimeoutError(msg)))
+
+    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,
-            )
-            stdout = Path(inv.result_path).read_text() if inv.result_path else rr.stdout
+            try:
+                rr = await acapture_cli(
+                    inv.argv,
+                    input=inv.stdin,
+                    env=os.environ | self.env() | (spec.env or {}),
+                    cwd=spec.cwd,
+                    timeout=spec.timeout,
+                )
+            except TimeoutError:
+                return self.timed_out(spec)
+            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 RunResult(stdout, rr.stderr, rr.returncode)
+        return self.to_response(raw, returncode=rr.returncode, stderr=rr.stderr, spec=spec)
 
-    def execute(self, spec: RunSpec) -> RunResult:
+    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,
-            )
-            stdout = Path(inv.result_path).read_text() if inv.result_path else rr.stdout
+            try:
+                rr = capture_cli(
+                    inv.argv,
+                    input=inv.stdin,
+                    env=os.environ | self.env() | (spec.env or {}),
+                    cwd=spec.cwd,
+                    timeout=spec.timeout,
+                )
+            except subprocess.TimeoutExpired:
+                return self.timed_out(spec)
+            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 RunResult(stdout, rr.stderr, rr.returncode)
+        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.

{spawnllm-0.4.0 → spawnllm-0.5.1}/spawnllm/backends/claude.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, ClassVar
 
 from spawnllm.backends.base import CliBackend
 from spawnllm.spec import ClaudeConfig
-from spawnllm.structured import parse_structured_output
+from spawnllm.structured import structured_value
 
 if TYPE_CHECKING:
     from pydantic import BaseModel
@@ -19,6 +19,21 @@ if TYPE_CHECKING:
 CLAUDE_MODELS: dict[TModel, str] = {"small": "haiku", "medium": "sonnet", "large": "opus"}
 
 
+def result_event(raw: str) -> dict[str, object] | None:
+    """Return the `claude` result envelope: the dict itself, or the `type=="result"` stream-json event, else `None`."""
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    match data:
+        case {"is_error": _} | {"result": _}:
+            return data
+        case list():
+            return next((e for e in data if isinstance(e, dict) and e.get("type") == "result"), None)
+        case _:
+            return None
+
+
 class ClaudeCliBackend(CliBackend):
     """`CliBackend` for the Anthropic `claude` CLI.
 
@@ -53,6 +68,7 @@ class ClaudeCliBackend(CliBackend):
             The argv list to execute; the prompt is delivered over stdin.
         """
         cfg = spec.config_for(ClaudeConfig) or ClaudeConfig()
+        schema = self.schema_arg(spec)
         explicit = (
             cfg.permission_mode is not None
             or cfg.mcp_config is not None
@@ -68,11 +84,12 @@ class ClaudeCliBackend(CliBackend):
             "--no-session-persistence",
             "--model",
             spec.model,
+            *(["--setting-sources", ""] if spec.isolated else []),
+            *(["--strict-mcp-config"] if spec.isolated or cfg.strict_mcp else []),
             *(
                 [
                     *(["--permission-mode", cfg.permission_mode] if cfg.permission_mode is not None else []),
                     *(["--mcp-config", cfg.mcp_config] if cfg.mcp_config is not None else []),
-                    *(["--strict-mcp-config"] if cfg.strict_mcp else []),
                     *(["--disallowedTools", *cfg.disallowed_tools] if cfg.disallowed_tools else []),
                     *(
                         ["--append-system-prompt", cfg.append_system_prompt]
@@ -85,15 +102,15 @@ class ClaudeCliBackend(CliBackend):
                 if explicit
                 else ["--permission-mode", "auto", "--max-budget-usd", "1"]
                 if spec.agent
-                else ["--system-prompt", "", "--setting-sources", "", "--strict-mcp-config"]
+                else ["--system-prompt", ""]
             ),
             *(["--system-prompt", cfg.system_prompt] if cfg.system_prompt is not None else []),
             *(["--max-turns", str(cfg.max_turns)] if cfg.max_turns is not None else []),
             *(["--tools", cfg.tools] if cfg.tools is not None else []),
             *(["--disable-slash-commands"] if cfg.disable_slash_commands else []),
             *(
-                ["--json-schema", spec.schema, "--output-format", "json"]
-                if spec.schema
+                ["--json-schema", schema, "--output-format", "json"]
+                if schema
                 else ["--output-format", cfg.output_format]
                 if cfg.output_format
                 else []
@@ -118,22 +135,30 @@ class ClaudeCliBackend(CliBackend):
 
         return json.dumps(transform_schema(model))
 
-    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
-        """Parse `claude` stdout into text or a validated model.
+    def result_text(self, raw: str) -> str:
+        """Return the `result` text from the `claude` envelope, falling back to `raw` for plain text."""
+        if (event := result_event(raw)) is not None and isinstance(text := event.get("result"), str):
+            return text
+        return raw
 
-        Args:
-            raw: Raw stdout from the `claude` CLI.
-            response_model: Model to validate against, or `None` for raw text.
+    def result_value(self, raw: str) -> object:
+        """Return the `structured_output` from the `claude` stream-json result event, else `raw` parsed as JSON."""
+        return structured_value(raw)
 
-        Returns:
-            `raw` for text calls; otherwise the validated `structured_output` from the result event, else `raw` as JSON.
-        """
-        return parse_structured_output(raw, response_model)
+    def envelope_error(self, raw: str) -> str | None:
+        """Return the error message when the `claude` result event marks the run as an error, else `None`."""
+        if (event := result_event(raw)) is not None and event.get("is_error"):
+            return event["result"] if isinstance(event.get("result"), str) else "claude reported an error"
+        return None
 
     def env(self) -> dict[str, str]:
-        """Return no extra environment variables; the `claude` CLI runs with the inherited environment."""
-        # CLAUDE_CODE_SIMPLE=1 breaks claude.ai keychain auth ("Not logged in")
-        # on current CLIs; --setting-sources ""/--strict-mcp-config already trim startup.
+        """Return no extra environment variables; the `claude` CLI runs with the inherited environment.
+
+        Isolation is flag-only (`--setting-sources ""`/`--strict-mcp-config`). A fresh
+        `CLAUDE_CONFIG_DIR` would log the CLI out: the keychain token is keyed to the
+        `oauthAccount` recorded in `~/.claude.json`, absent from a relocated dir.
+        (`CLAUDE_CODE_SIMPLE=1` likewise breaks claude.ai keychain auth.)
+        """
         return {}
 
     def is_authenticated(self, *, timeout: int) -> bool: