spawnllm 0.1.2__tar.gz → 0.2.0__tar.gz

{spawnllm-0.1.2 → spawnllm-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawnllm
-Version: 0.1.2
+Version: 0.2.0
 Summary: Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
 Keywords: 
 Author: Yasyf Mohamedali
@@ -45,6 +45,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/)
@@ -95,14 +97,19 @@ mlx
 
 ## 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.1.2 → spawnllm-0.2.0}/README.md

@@ -1,5 +1,7 @@
 # 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/)
@@ -50,14 +52,19 @@ mlx
 
 ## 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.1.2 → spawnllm-0.2.0}/pyproject.toml

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

{spawnllm-0.1.2 → spawnllm-0.2.0}/spawnllm/__init__.py

@@ -1,22 +1,25 @@
 """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,
     LlmBackend,
     LlmBackends,
-    check_status,
+    select_backend,
 )
 from spawnllm.call import call
 from spawnllm.proc import arun_cli, collect_process, map_concurrent, run_cli
@@ -30,19 +33,21 @@ from spawnllm.structured import (
 from spawnllm.types import TModel, TSpecialty
 
 __all__ = [
+    "AntigravityCliBackend",
+    "BackendNotAuthenticated",
+    "BackendNotInstalled",
+    "BackendReady",
+    "BackendStatus",
+    "BackendUnavailable",
     "ClaudeCliBackend",
-    "ClaudeNotAuthenticated",
-    "ClaudeNotInstalled",
-    "ClaudeReady",
-    "ClaudeStatus",
     "CodexCliBackend",
+    "GeminiCliBackend",
     "LlmBackend",
     "LlmBackends",
     "TModel",
     "TSpecialty",
     "arun_cli",
     "call",
-    "check_status",
     "collect_process",
     "extract_structured",
     "map_concurrent",
@@ -51,4 +56,5 @@ __all__ = [
     "resolve_schema_path",
     "run_cli",
     "schema_for",
+    "select_backend",
 ]

spawnllm-0.2.0/spawnllm/backends/__init__.py

@@ -0,0 +1,31 @@
+"""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,
+    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",
+    "LlmBackend",
+    "LlmBackends",
+    "select_backend",
+]

spawnllm-0.2.0/spawnllm/backends/base.py

@@ -0,0 +1,152 @@
+"""Abstract interface for an LLM CLI backend."""
+
+from __future__ import annotations
+
+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)."""
+
+
+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 invocation(
+        self, prompt: str, *, model: str, schema_path: str | None, agent: bool
+    ) -> tuple[list[str], str | None]:
+        """Build the argv and stdin text for a single invocation.
+
+        The default delivers the prompt over stdin; subclasses override to
+        deliver it inline within the argv.
+
+        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:
+            A `(argv, stdin_text)` pair; `stdin_text` is `None` when the prompt is delivered inline.
+        """
+        return self.build_command(model, schema_path, agent), prompt

spawnllm-0.2.0/spawnllm/backends/claude.py

@@ -0,0 +1,176 @@
+"""LlmBackend for the Anthropic `claude` CLI, plus install/auth status checks."""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar
+
+from spawnllm.backends.base import LlmBackend
+from spawnllm.structured import parse_result_envelope, parse_structured_output
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from spawnllm.types import TModel
+
+CLAUDE_MODELS: dict[TModel, str] = {"small": "haiku", "medium": "sonnet", "large": "opus"}
+
+
+@dataclass(frozen=True)
+class ClaudeCliBackend(LlmBackend):
+    """`LlmBackend` for the Anthropic `claude` CLI.
+
+    The default (no-arg) construction delivers the prompt over stdin with abstract
+    model tiers and structured-output parsing. The `cc_sentiment` preset
+    configures inline `-p` prompting with `{is_error, result}` envelope parsing.
+
+    Attributes:
+        models: Mapping from abstract model size to a Claude model alias
+            (`haiku`/`sonnet`/`opus`).
+        inline_system_prompt: System prompt that `build_argv` passes via
+            `--system-prompt`.
+        verbose: Whether `build_argv` appends `--verbose`.
+
+    Example:
+        >>> ClaudeCliBackend().build_command("haiku", None, agent=False)[:5]
+        ['claude', '-p', '--no-session-persistence', '--model', 'haiku']
+    """
+
+    models: ClassVar[dict[TModel, str]] = CLAUDE_MODELS
+    binary: ClassVar[str] = "claude"
+    install_hint: ClassVar[str] = "curl -fsSL https://claude.ai/install.sh | bash"
+
+    inline_system_prompt: str = ""
+    verbose: bool = False
+
+    @classmethod
+    def cc_sentiment(cls, *, system_prompt: str, verbose: bool = False) -> ClaudeCliBackend:
+        """Build a backend preset for the sentiment/pushback scoring path.
+
+        Args:
+            system_prompt: System prompt that `build_argv` passes via
+                `--system-prompt`.
+            verbose: Whether `build_argv` appends `--verbose`.
+
+        Returns:
+            A `ClaudeCliBackend` for inline `-p` prompting; parse its stdout with `parse_result_envelope`.
+        """
+        return cls(inline_system_prompt=system_prompt, verbose=verbose)
+
+    def build_command(self, model: str, schema_path: str | None, agent: bool) -> list[str]:
+        """Build the `claude -p` argv for one stdin-prompted invocation.
+
+        Every invocation runs without session persistence. Agent invocations
+        add `--permission-mode auto` and a $1 `--max-budget-usd` cap;
+        non-agent invocations empty the system prompt, disable setting
+        sources, and load no MCP servers. A schema adds `--json-schema` with
+        `--output-format json`.
+
+        Args:
+            model: Claude model name or alias, e.g. `haiku`.
+            schema_path: Inline JSON schema passed to `--json-schema`, or `None`.
+            agent: Whether the invocation may use tools / agent capabilities.
+
+        Returns:
+            The argv list to execute.
+        """
+        return [
+            "claude",
+            "-p",
+            "--no-session-persistence",
+            "--model",
+            model,
+            *(
+                ["--permission-mode", "auto", "--max-budget-usd", "1"]
+                if agent
+                else ["--system-prompt", "", "--setting-sources", "", "--strict-mcp-config"]
+            ),
+            *(["--json-schema", schema_path, "--output-format", "json"] if schema_path else []),
+        ]
+
+    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
+        )
+
+    def build_argv(self, content: str, *, model: str) -> list[str]:
+        """Build the inline `-p` argv for the sentiment/pushback scoring path.
+
+        The prompt travels inline as the `-p` argument instead of over stdin.
+        The invocation uses `inline_system_prompt` as the system prompt, JSON
+        output, a single turn, no tools, and no slash commands; `verbose`
+        appends `--verbose`.
+
+        Args:
+            content: Prompt text passed inline via `-p`.
+            model: Claude model name or alias, e.g. `haiku`.
+
+        Returns:
+            The argv list to execute; parse its stdout with `parse_result_envelope`.
+        """
+        argv = [
+            "claude",
+            "-p",
+            content,
+            "--model",
+            model,
+            "--system-prompt",
+            self.inline_system_prompt,
+            "--output-format",
+            "json",
+            "--max-turns",
+            "1",
+            "--tools",
+            "",
+            "--disable-slash-commands",
+        ]
+        if self.verbose:
+            argv.append("--verbose")
+        return argv
+
+    @staticmethod
+    def parse_result_envelope(stdout: bytes, *, argv: list[str], stderr: bytes) -> str:
+        """Parse the `{is_error, result}` JSON envelope from `claude -p --output-format json`.
+
+        Args:
+            stdout: Raw stdout bytes holding the JSON envelope.
+            argv: The argv that produced the output, recorded on the raised error.
+            stderr: Raw stderr bytes, recorded on the raised error.
+
+        Returns:
+            The envelope's `result` string.
+
+        Raises:
+            subprocess.CalledProcessError: If the envelope's `is_error` flag is set.
+        """
+        return parse_result_envelope(stdout, argv=argv, stderr=stderr)

spawnllm-0.2.0/spawnllm/backends/codex.py

@@ -0,0 +1,91 @@
+"""LlmBackend for the OpenAI `codex` CLI."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import TYPE_CHECKING, ClassVar
+
+from spawnllm.backends.base import LlmBackend
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from spawnllm.types import TModel
+
+
+class CodexCliBackend(LlmBackend):
+    """`LlmBackend` for the OpenAI `codex` CLI.
+
+    Invokes `codex exec` with an ephemeral session and a read-only sandbox.
+
+    Attributes:
+        models: Mapping from abstract model size to an OpenAI model name.
+    """
+
+    models: ClassVar[dict[TModel, str]] = {
+        "small": "gpt-5.3-codex-spark",
+        "medium": "gpt-5.4-mini",
+        "large": "gpt-5.5",
+    }
+    binary: ClassVar[str] = "codex"
+    install_hint: ClassVar[str] = "npm install -g @openai/codex"
+
+    def build_command(self, model: str, schema_path: str | None, agent: bool) -> list[str]:
+        """Build the `codex exec` argv for one stdin-prompted invocation.
+
+        Every invocation runs an ephemeral session in a read-only sandbox.
+        Non-agent invocations disable Codex hooks and MCP servers. A schema
+        path adds `--output-schema`.
+
+        Args:
+            model: OpenAI model name, e.g. `gpt-5.5`.
+            schema_path: Path to a JSON schema file passed to
+                `--output-schema`, or `None`.
+            agent: Whether the invocation may use tools / agent capabilities.
+
+        Returns:
+            The argv list to execute.
+        """
+        return [
+            "codex",
+            "exec",
+            "--ephemeral",
+            "--sandbox",
+            "read-only",
+            "--model",
+            model,
+            *([] if agent else ["-c", "features.codex_hooks=false", "-c", "features.mcp_servers=false"]),
+            *(["--output-schema", schema_path] if schema_path else []),
+        ]
+
+    def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
+        """Parse `codex` stdout into text or a validated model.
+
+        Args:
+            raw: Raw stdout from the `codex` CLI.
+            response_model: Model to validate against, or `None` for raw text.
+
+        Returns:
+            `raw` when `response_model` is `None`; otherwise `raw` validated as JSON against `response_model`.
+        """
+        return raw if not response_model else response_model.model_validate_json(raw)
+
+    def env(self) -> dict[str, str]:
+        """Return no extra environment variables; the `codex` CLI runs with the inherited environment."""
+        return {}
+
+    def is_authenticated(self, *, timeout: int) -> bool:
+        """Report whether `codex login status` exits cleanly, i.e. the CLI is logged in.
+
+        Args:
+            timeout: Seconds to wait for `codex login status`.
+
+        Returns:
+            `True` when `codex login status` exits 0.
+        """
+        return (
+            subprocess.run(
+                ["codex", "login", "status"], capture_output=True, text=True, timeout=timeout, check=False
+            ).returncode
+            == 0
+        )