spawnllm 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawnllm
-Version: 0.3.0
+Version: 0.4.0
 Summary: Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
 Keywords: 
 Author: Yasyf Mohamedali
@@ -113,13 +113,14 @@ The `claude` backend resolves `small` to Haiku, `medium` to Sonnet, and `large`
 
 ### 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 +130,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 +138,7 @@ class Capital(BaseModel):
     capital: str
 
 
-result = call(
+result = call_sync(
     "What is the capital of France?",
     backend=ClaudeCliBackend(),
     model="large",
@@ -149,6 +150,27 @@ 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.
 
+### Spec-driven runs
+
+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:
+
+```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
+```
+
 ## What problems does this solve?
 
 Every tool that shells out to `claude` or `codex` rebuilds the same plumbing: argv

{spawnllm-0.3.0 → spawnllm-0.4.0}/README.md

@@ -66,13 +66,14 @@ The `claude` backend resolves `small` to Haiku, `medium` to Sonnet, and `large`
 
 ### 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 +83,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 +91,7 @@ class Capital(BaseModel):
     capital: str
 
 
-result = call(
+result = call_sync(
     "What is the capital of France?",
     backend=ClaudeCliBackend(),
     model="large",
@@ -102,6 +103,27 @@ 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.
 
+### Spec-driven runs
+
+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:
+
+```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
+```
+
 ## What problems does this solve?
 
 Every tool that shells out to `claude` or `codex` rebuilds the same plumbing: argv

{spawnllm-0.3.0 → spawnllm-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spawnllm"
-version = "0.3.0"
+version = "0.4.0"
 description = "Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools."
 readme = "README.md"
 license = "MIT"

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

@@ -15,22 +15,26 @@ from spawnllm.backends import (
     BackendStatus,
     BackendUnavailable,
     ClaudeCliBackend,
+    CliBackend,
     CodexCliBackend,
     GeminiCliBackend,
     Invocation,
     LlmBackend,
     LlmBackends,
+    MlxBackend,
     select_backend,
 )
-from spawnllm.call import call
-from spawnllm.proc import arun_cli, collect_process, map_concurrent, run_cli
+from spawnllm.call import call, call_sync
+from spawnllm.proc import RunResult, arun_cli, collect_process, map_concurrent, run_cli
+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 TModel, TSpecialty
+from spawnllm.types import ProviderName, TModel, TSpecialty
 
 __all__ = [
     "AntigravityCliBackend",
@@ -40,21 +44,32 @@ __all__ = [
     "BackendStatus",
     "BackendUnavailable",
     "ClaudeCliBackend",
+    "ClaudeConfig",
+    "CliBackend",
     "CodexCliBackend",
+    "CodexConfig",
     "GeminiCliBackend",
+    "GeminiConfig",
     "Invocation",
     "LlmBackend",
     "LlmBackends",
+    "MlxBackend",
+    "ProviderName",
+    "RunResult",
+    "RunSpec",
     "TModel",
     "TSpecialty",
     "arun_cli",
     "call",
+    "call_sync",
     "collect_process",
     "extract_structured",
     "map_concurrent",
     "parse_result_envelope",
     "parse_structured_output",
     "resolve_schema_path",
+    "run",
     "run_cli",
+    "run_sync",
     "select_backend",
 ]

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

@@ -8,12 +8,14 @@ from spawnllm.backends.base import (
     BackendReady,
     BackendStatus,
     BackendUnavailable,
+    CliBackend,
     Invocation,
     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__ = [
@@ -24,10 +26,12 @@ __all__ = [
     "BackendStatus",
     "BackendUnavailable",
     "ClaudeCliBackend",
+    "CliBackend",
     "CodexCliBackend",
     "GeminiCliBackend",
     "Invocation",
     "LlmBackend",
     "LlmBackends",
+    "MlxBackend",
     "select_backend",
 ]

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

@@ -1,17 +1,22 @@
-"""Abstract interface for an LLM CLI backend."""
+"""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 RunResult, acapture_cli, capture_cli
+
 if TYPE_CHECKING:
     from pydantic import BaseModel
 
-    from spawnllm.types import TModel
+    from spawnllm.spec import RunSpec
+    from spawnllm.types import ProviderName, TModel
 
 
 @dataclass(frozen=True)
@@ -76,38 +81,47 @@ class Invocation:
 
 
 class LlmBackend(ABC):
-    """Abstract interface for an LLM CLI backend.
+    """Abstract execution contract for an LLM backend.
 
     Concrete backends map abstract model sizes to provider-specific model names
-    and encapsulate how to invoke the provider's CLI and parse the raw response.
+    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]]
-    binary: ClassVar[str]
-    install_hint: ClassVar[str]
+    provider: ClassVar[ProviderName]
 
     @abstractmethod
-    def build_command(self, model: str, schema_path: str | None, agent: bool) -> list[str]:
-        """Build the CLI argv for a single invocation (prompt delivered via stdin).
+    async def aexecute(self, spec: RunSpec) -> RunResult:
+        """Execute a single run asynchronously and capture its raw outcome.
 
         Args:
-            model: Provider-specific model name.
-            schema_path: Schema argument for structured output, or `None`.
-            agent: Whether the invocation may use tools / agent capabilities.
+            spec: The configured run to execute.
 
         Returns:
-            The argv list to execute.
+            The captured stdout, stderr, and exit code.
+        """
+
+    @abstractmethod
+    def execute(self, spec: RunSpec) -> RunResult:
+        """Execute a single run synchronously and capture its raw outcome.
+
+        Args:
+            spec: The configured run to execute.
+
+        Returns:
+            The captured stdout, stderr, and exit code.
         """
 
     @abstractmethod
     def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
-        """Parse raw CLI stdout into text or a validated model.
+        """Parse raw stdout into text or a validated model.
 
         Args:
-            raw: Raw stdout from the backend CLI.
+            raw: Raw stdout from the backend.
             response_model: Model to validate against, or `None` for raw text.
 
         Returns:
@@ -116,43 +130,36 @@ class LlmBackend(ABC):
 
     @abstractmethod
     def env(self) -> dict[str, str]:
-        """Return extra environment variables for the CLI invocation, merged over the inherited environment."""
+        """Return extra environment variables for the invocation, merged over the inherited environment."""
 
-    def check_status(self, *, timeout: int = 10) -> BackendStatus:
-        """Check whether this backend's CLI is installed and authenticated.
+    @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 authentication probe.
+            timeout: Seconds to wait for the credential probe.
 
         Returns:
-            `BackendReady` when authenticated, `BackendNotInstalled` when the CLI
-            is not on PATH, else `BackendNotAuthenticated`.
-
-        Raises:
-            subprocess.TimeoutExpired: If `is_authenticated` exceeds `timeout`.
+            `True` when the backend reports an authenticated session.
         """
-        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)
 
     @abstractmethod
-    def is_authenticated(self, *, timeout: int) -> bool:
-        """Probe whether the CLI holds valid credentials for its provider.
-
-        "Authenticated" means the CLI reports an active login session for the
-        provider, not merely that the executable is present on PATH.
+    def check_status(self, *, timeout: int = 10) -> BackendStatus:
+        """Check whether this backend is installed and authenticated.
 
         Args:
-            timeout: Seconds to wait for the credential probe.
+            timeout: Seconds to wait for the authentication probe.
 
         Returns:
-            `True` when the CLI reports an authenticated session.
+            `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's CLI expects.
+        """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.
@@ -165,7 +172,34 @@ class LlmBackend(ABC):
         """
         return json.dumps(model.model_json_schema())
 
-    def invocation(self, prompt: str, *, model: str, schema_path: str | None, agent: bool) -> Invocation:
+
+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
@@ -173,12 +207,60 @@ class LlmBackend(ABC):
         result from a file.
 
         Args:
-            prompt: The prompt text to deliver to the CLI.
-            model: Provider-specific model name.
-            schema_path: Schema argument for structured output, or `None`.
-            agent: Whether the invocation may use tools / agent capabilities.
+            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(model, schema_path, agent), prompt)
+        return Invocation(self.build_command(spec), spec.prompt)
+
+    async def aexecute(self, spec: RunSpec) -> RunResult:
+        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
+        finally:
+            for path in inv.cleanup_paths:
+                Path(path).unlink(missing_ok=True)
+        return RunResult(stdout, rr.stderr, rr.returncode)
+
+    def execute(self, spec: RunSpec) -> RunResult:
+        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
+        finally:
+            for path in inv.cleanup_paths:
+                Path(path).unlink(missing_ok=True)
+        return RunResult(stdout, rr.stderr, rr.returncode)
+
+    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)

spawnllm-0.4.0/spawnllm/backends/claude.py

@@ -0,0 +1,153 @@
+"""CliBackend for the Anthropic `claude` CLI, plus install/auth status checks."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import TYPE_CHECKING, ClassVar
+
+from spawnllm.backends.base import CliBackend
+from spawnllm.spec import ClaudeConfig
+from spawnllm.structured import parse_structured_output
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from spawnllm.spec import RunSpec
+    from spawnllm.types import ProviderName, TModel
+
+CLAUDE_MODELS: dict[TModel, str] = {"small": "haiku", "medium": "sonnet", "large": "opus"}
+
+
+class ClaudeCliBackend(CliBackend):
+    """`CliBackend` for the Anthropic `claude` CLI.
+
+    `build_command` translates a `RunSpec` into a `claude -p` argv with the prompt
+    delivered over stdin. The permission and system-prompt flags resolve through
+    three mutually exclusive branches: explicit `ClaudeConfig` agent fields, an
+    agent run, or a locked-down default. Orthogonal `ClaudeConfig` extras and the
+    output format are appended after.
+
+    Attributes:
+        models: Mapping from abstract model size to a Claude model alias
+            (`haiku`/`sonnet`/`opus`).
+
+    Example:
+        >>> from spawnllm.spec import RunSpec
+        >>> ClaudeCliBackend().build_command(RunSpec(prompt="hi", model="haiku"))[:5]
+        ['claude', '-p', '--no-session-persistence', '--model', 'haiku']
+    """
+
+    models: ClassVar[dict[TModel, str]] = CLAUDE_MODELS
+    provider: ClassVar[ProviderName] = "claude"
+    binary: ClassVar[str] = "claude"
+    install_hint: ClassVar[str] = "curl -fsSL https://claude.ai/install.sh | bash"
+
+    def build_command(self, spec: RunSpec) -> list[str]:
+        """Build the `claude -p` argv for one stdin-prompted invocation.
+
+        Args:
+            spec: The configured run to translate into argv.
+
+        Returns:
+            The argv list to execute; the prompt is delivered over stdin.
+        """
+        cfg = spec.config_for(ClaudeConfig) or ClaudeConfig()
+        explicit = (
+            cfg.permission_mode is not None
+            or cfg.mcp_config is not None
+            or cfg.append_system_prompt is not None
+            or cfg.system_prompt is not None
+            or cfg.settings is not None
+            or bool(cfg.disallowed_tools)
+            or cfg.strict_mcp
+        )
+        return [
+            "claude",
+            "-p",
+            "--no-session-persistence",
+            "--model",
+            spec.model,
+            *(
+                [
+                    *(["--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]
+                        if cfg.append_system_prompt is not None
+                        else []
+                    ),
+                    *(["--settings", cfg.settings] if cfg.settings is not None else []),
+                    *(["--max-budget-usd", str(cfg.max_budget_usd)] if cfg.max_budget_usd is not None else []),
+                ]
+                if explicit
+                else ["--permission-mode", "auto", "--max-budget-usd", "1"]
+                if spec.agent
+                else ["--system-prompt", "", "--setting-sources", "", "--strict-mcp-config"]
+            ),
+            *(["--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
+                else ["--output-format", cfg.output_format]
+                if cfg.output_format
+                else []
+            ),
+            *(["--verbose"] if cfg.verbose else []),
+        ]
+
+    def schema_for(self, model: type[BaseModel]) -> str:
+        """Serialize a Pydantic model into Anthropic's structured-output JSON schema.
+
+        Uses the Anthropic SDK's `transform_schema`, which recursively sets
+        `additionalProperties: false` while preserving Pydantic's `required`,
+        producing the standard JSON Schema the `claude --json-schema` flag expects.
+
+        Args:
+            model: The Pydantic model describing the structured output.
+
+        Returns:
+            A JSON-schema string passed inline to `--json-schema`.
+        """
+        from anthropic.lib._parse._transform import transform_schema
+
+        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.
+
+        Args:
+            raw: Raw stdout from the `claude` CLI.
+            response_model: Model to validate against, or `None` for raw text.
+
+        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 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 {}
+
+    def is_authenticated(self, *, timeout: int) -> bool:
+        """Report whether `claude auth status` exits cleanly, i.e. a claude.ai login is stored.
+
+        Args:
+            timeout: Seconds to wait for `claude auth status`.
+
+        Returns:
+            `True` when the OAuth-aware probe reports a stored claude.ai login.
+        """
+        return (
+            subprocess.run(
+                ["claude", "auth", "status"], capture_output=True, text=True, timeout=timeout, check=False
+            ).returncode
+            == 0
+        )