spawnllm 0.1.3__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawnllm
-Version: 0.1.3
+Version: 0.3.0
 Summary: Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
 Keywords: 
 Author: Yasyf Mohamedali
@@ -16,6 +16,8 @@ Classifier: Typing :: Typed
 Requires-Dist: click>=8
 Requires-Dist: loguru>=0.7
 Requires-Dist: pydantic>=2
+Requires-Dist: openai>=2.43
+Requires-Dist: anthropic>=0.111
 Requires-Dist: zstandard>=0.25.0 ; extra == 'adapter'
 Requires-Dist: numpy>=1.26 ; extra == 'adapter'
 Requires-Dist: orjson>=3.10 ; extra == 'adapter'
@@ -45,6 +47,8 @@ Description-Content-Type: text/markdown
 
 # spawnllm
 
+![spawnllm banner](https://github.com/yasyf/spawnllm/raw/main/docs/assets/readme-banner.webp)
+
 [![PyPI](https://img.shields.io/pypi/v/spawnllm.svg)](https://pypi.org/project/spawnllm/)
 [![Python](https://img.shields.io/pypi/pyversions/spawnllm.svg)](https://pypi.org/project/spawnllm/)
 [![Docs](https://img.shields.io/github/actions/workflow/status/yasyf/spawnllm/docs.yml?branch=main&label=docs)](https://yasyf.github.io/spawnllm/)
@@ -81,28 +85,85 @@ uv add "spawnllm[mlx]"
 
 ## Quickstart
 
-List the backends spawnllm can drive:
+See which backends are installed and authenticated, and which one auto-selection picks:
 
 ```bash
-uvx spawnllm backends
+uvx spawnllm status
+```
+
+```
+claude: ready
+codex: ready
+selected: claude
 ```
 
+Make a request by passing a prompt as the argument, or piping it over stdin:
+
+```bash
+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.
+
+### From Python
+
+`call` runs one request and returns the response. With no `backend`, it auto-selects the
+first installed, authenticated CLI:
+
+```python
+from spawnllm import call
+
+print(call("Reply with just the word: pong"))
+# pong
 ```
-claude
-codex
-mlx
+
+Pin a backend and tier explicitly, or pass a Pydantic model to get a validated object back
+instead of text:
+
+```python
+from pydantic import BaseModel
+
+from spawnllm import call, ClaudeCliBackend
+
+
+class Capital(BaseModel):
+    country: str
+    capital: str
+
+
+result = call(
+    "What is the capital of France?",
+    backend=ClaudeCliBackend(),
+    model="large",
+    response_model=Capital,
+)
+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?
 
-- **Duplicate subshell plumbing.** Building `claude`/`codex` argv, piping stdin/stdout, teeing
-  stderr, and turning non-zero exits into useful errors — written once, not re-derived per tool.
-- **Structured-output boilerplate.** A Pydantic model becomes a JSON-schema constraint and a
-  parsed, validated result the same way for every backend.
-- **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.
-- **Behavior drift.** Two tools that call the same models stay byte-for-byte consistent because
-  they share the backend layer rather than each maintaining a copy.
+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.
+
+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.
 
 ## Docs
 

spawnllm-0.3.0/README.md

@@ -0,0 +1,123 @@
+# spawnllm
+
+![spawnllm banner](https://github.com/yasyf/spawnllm/raw/main/docs/assets/readme-banner.webp)
+
+[![PyPI](https://img.shields.io/pypi/v/spawnllm.svg)](https://pypi.org/project/spawnllm/)
+[![Python](https://img.shields.io/pypi/pyversions/spawnllm.svg)](https://pypi.org/project/spawnllm/)
+[![Docs](https://img.shields.io/github/actions/workflow/status/yasyf/spawnllm/docs.yml?branch=main&label=docs)](https://yasyf.github.io/spawnllm/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/yasyf/spawnllm/blob/main/LICENSE)
+
+Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
+
+spawnllm centralizes the LLM-calling plumbing that small tools keep re-inventing: driving the
+`claude` and `codex` CLIs as subshells — with structured Pydantic output, model tiers, and
+faithful error capture — and running local Apple-Silicon MLX models with adapter fusion,
+prompt-cache reuse, and batched generation. Depend on it once and each tool keeps only its
+domain logic instead of its own copy of the backends.
+
+## Install
+
+No install needed — run everything through [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]"
+```
+
+## Quickstart
+
+See which backends are installed and authenticated, and which one auto-selection picks:
+
+```bash
+uvx spawnllm status
+```
+
+```
+claude: ready
+codex: ready
+selected: claude
+```
+
+Make a request by passing a prompt as the argument, or piping it over stdin:
+
+```bash
+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.
+
+### From Python
+
+`call` runs one request and returns the response. With no `backend`, it auto-selects the
+first installed, authenticated CLI:
+
+```python
+from spawnllm import call
+
+print(call("Reply with just the word: pong"))
+# pong
+```
+
+Pin a backend and tier explicitly, or pass a Pydantic model to get a validated object back
+instead of text:
+
+```python
+from pydantic import BaseModel
+
+from spawnllm import call, ClaudeCliBackend
+
+
+class Capital(BaseModel):
+    country: str
+    capital: str
+
+
+result = call(
+    "What is the capital of France?",
+    backend=ClaudeCliBackend(),
+    model="large",
+    response_model=Capital,
+)
+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?
+
+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.
+
+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.
+
+## Docs
+
+[Read the docs](https://yasyf.github.io/spawnllm/) for the full guide and API reference.

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

@@ -1,6 +1,6 @@
 [project]
 name = "spawnllm"
-version = "0.1.3"
+version = "0.3.0"
 description = "Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools."
 readme = "README.md"
 license = "MIT"
@@ -20,6 +20,11 @@ dependencies = [
     "click>=8",
     "loguru>=0.7",
     "pydantic>=2",
+    # Per-backend strict-schema transforms: openai.lib._pydantic.to_strict_json_schema
+    # and anthropic.lib._parse._transform.transform_schema. Both import paths are
+    # SDK-private, so the floors pin verified-working versions.
+    "openai>=2.43",
+    "anthropic>=0.111",
 ]
 
 [project.optional-dependencies]

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

@@ -1,22 +1,26 @@
 """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 :mod:`spawnllm.mlx` and is
-imported lazily so that ``import spawnllm`` never pulls ``mlx_lm``/``zstandard``.
+structured-output helpers. 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,
+    BackendNotAuthenticated,
+    BackendNotInstalled,
+    BackendReady,
+    BackendStatus,
+    BackendUnavailable,
     ClaudeCliBackend,
-    ClaudeNotAuthenticated,
-    ClaudeNotInstalled,
-    ClaudeReady,
-    ClaudeStatus,
     CodexCliBackend,
+    GeminiCliBackend,
+    Invocation,
     LlmBackend,
     LlmBackends,
-    check_status,
+    select_backend,
 )
 from spawnllm.call import call
 from spawnllm.proc import arun_cli, collect_process, map_concurrent, run_cli
@@ -25,24 +29,26 @@ from spawnllm.structured import (
     parse_result_envelope,
     parse_structured_output,
     resolve_schema_path,
-    schema_for,
 )
 from spawnllm.types import TModel, TSpecialty
 
 __all__ = [
+    "AntigravityCliBackend",
+    "BackendNotAuthenticated",
+    "BackendNotInstalled",
+    "BackendReady",
+    "BackendStatus",
+    "BackendUnavailable",
     "ClaudeCliBackend",
-    "ClaudeNotAuthenticated",
-    "ClaudeNotInstalled",
-    "ClaudeReady",
-    "ClaudeStatus",
     "CodexCliBackend",
+    "GeminiCliBackend",
+    "Invocation",
     "LlmBackend",
     "LlmBackends",
     "TModel",
     "TSpecialty",
     "arun_cli",
     "call",
-    "check_status",
     "collect_process",
     "extract_structured",
     "map_concurrent",
@@ -50,5 +56,5 @@ __all__ = [
     "parse_structured_output",
     "resolve_schema_path",
     "run_cli",
-    "schema_for",
+    "select_backend",
 ]

spawnllm-0.3.0/spawnllm/backends/__init__.py

@@ -0,0 +1,33 @@
+"""LLM CLI backends (Claude/Codex/Gemini family) and the specialty registry."""
+
+from __future__ import annotations
+
+from spawnllm.backends.base import (
+    BackendNotAuthenticated,
+    BackendNotInstalled,
+    BackendReady,
+    BackendStatus,
+    BackendUnavailable,
+    Invocation,
+    LlmBackend,
+)
+from spawnllm.backends.claude import ClaudeCliBackend
+from spawnllm.backends.codex import CodexCliBackend
+from spawnllm.backends.gemini import AntigravityCliBackend, GeminiCliBackend
+from spawnllm.backends.registry import LlmBackends, select_backend
+
+__all__ = [
+    "AntigravityCliBackend",
+    "BackendNotAuthenticated",
+    "BackendNotInstalled",
+    "BackendReady",
+    "BackendStatus",
+    "BackendUnavailable",
+    "ClaudeCliBackend",
+    "CodexCliBackend",
+    "GeminiCliBackend",
+    "Invocation",
+    "LlmBackend",
+    "LlmBackends",
+    "select_backend",
+]

spawnllm-0.3.0/spawnllm/backends/base.py

@@ -0,0 +1,184 @@
+"""Abstract interface for an LLM CLI backend."""
+
+from __future__ import annotations
+
+import json
+import shutil
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from spawnllm.types import 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)."""
+
+
+@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 interface for an LLM CLI 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.
+
+    Attributes:
+        models: Mapping from abstract model size to the provider's model name.
+    """
+
+    models: ClassVar[dict[TModel, str]]
+    binary: ClassVar[str]
+    install_hint: ClassVar[str]
+
+    @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).
+
+        Args:
+            model: Provider-specific model name.
+            schema_path: Schema argument for structured output, or `None`.
+            agent: Whether the invocation may use tools / agent capabilities.
+
+        Returns:
+            The argv list to execute.
+        """
+
+    @abstractmethod
+    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
+        """Parse raw CLI stdout into text or a validated model.
+
+        Args:
+            raw: Raw stdout from the backend CLI.
+            response_model: Model to validate against, or `None` for raw text.
+
+        Returns:
+            `raw` when `response_model` is `None`, else a validated instance.
+        """
+
+    @abstractmethod
+    def env(self) -> dict[str, str]:
+        """Return extra environment variables for the CLI invocation, merged over the inherited environment."""
+
+    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)
+
+    @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.
+
+        Args:
+            timeout: Seconds to wait for the credential probe.
+
+        Returns:
+            `True` when the CLI reports an authenticated session.
+        """
+
+    def schema_for(self, model: type[BaseModel]) -> str:
+        """Serialize a Pydantic model into the JSON-schema string this backend's CLI 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 invocation(self, prompt: str, *, model: str, schema_path: str | None, agent: bool) -> 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:
+            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.
+
+        Returns:
+            An `Invocation` carrying the argv, stdin text, and result source.
+        """
+        return Invocation(self.build_command(model, schema_path, agent), prompt)