spawnllm 0.2.0__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawnllm
-Version: 0.2.0
+Version: 0.3.1
 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'
@@ -83,18 +85,70 @@ 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
-codex
-mlx
+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

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

@@ -38,18 +38,70 @@ 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
-codex
-mlx
+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

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

@@ -1,6 +1,6 @@
 [project]
 name = "spawnllm"
-version = "0.2.0"
+version = "0.3.1"
 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.2.0 → spawnllm-0.3.1}/spawnllm/__init__.py

@@ -17,6 +17,7 @@ from spawnllm.backends import (
     ClaudeCliBackend,
     CodexCliBackend,
     GeminiCliBackend,
+    Invocation,
     LlmBackend,
     LlmBackends,
     select_backend,
@@ -28,7 +29,6 @@ from spawnllm.structured import (
     parse_result_envelope,
     parse_structured_output,
     resolve_schema_path,
-    schema_for,
 )
 from spawnllm.types import TModel, TSpecialty
 
@@ -42,6 +42,7 @@ __all__ = [
     "ClaudeCliBackend",
     "CodexCliBackend",
     "GeminiCliBackend",
+    "Invocation",
     "LlmBackend",
     "LlmBackends",
     "TModel",
@@ -55,6 +56,5 @@ __all__ = [
     "parse_structured_output",
     "resolve_schema_path",
     "run_cli",
-    "schema_for",
     "select_backend",
 ]

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

@@ -8,6 +8,7 @@ from spawnllm.backends.base import (
     BackendReady,
     BackendStatus,
     BackendUnavailable,
+    Invocation,
     LlmBackend,
 )
 from spawnllm.backends.claude import ClaudeCliBackend
@@ -25,6 +26,7 @@ __all__ = [
     "ClaudeCliBackend",
     "CodexCliBackend",
     "GeminiCliBackend",
+    "Invocation",
     "LlmBackend",
     "LlmBackends",
     "select_backend",

{spawnllm-0.2.0 → spawnllm-0.3.1}/spawnllm/backends/base.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import shutil
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
@@ -56,6 +57,24 @@ 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.
 
@@ -132,13 +151,26 @@ class LlmBackend(ABC):
             `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.
+    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; subclasses override to
-        deliver it inline within the argv.
+        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.
@@ -147,6 +179,6 @@ class LlmBackend(ABC):
             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.
+            An `Invocation` carrying the argv, stdin text, and result source.
         """
-        return self.build_command(model, schema_path, agent), prompt
+        return Invocation(self.build_command(model, schema_path, agent), prompt)

{spawnllm-0.2.0 → spawnllm-0.3.1}/spawnllm/backends/claude.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import subprocess
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, ClassVar
@@ -89,6 +90,23 @@ class ClaudeCliBackend(LlmBackend):
             *(["--json-schema", schema_path, "--output-format", "json"] if schema_path 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.
 

{spawnllm-0.2.0 → spawnllm-0.3.1}/spawnllm/backends/codex.py

@@ -2,10 +2,13 @@
 
 from __future__ import annotations
 
+import json
+import os
 import subprocess
+import tempfile
 from typing import TYPE_CHECKING, ClassVar
 
-from spawnllm.backends.base import LlmBackend
+from spawnllm.backends.base import Invocation, LlmBackend
 
 if TYPE_CHECKING:
     from pydantic import BaseModel
@@ -58,11 +61,54 @@ class CodexCliBackend(LlmBackend):
             *(["--output-schema", schema_path] if schema_path else []),
         ]
 
+    def invocation(self, prompt: str, *, model: str, schema_path: str | None, agent: bool) -> Invocation:
+        """Build the `codex exec` invocation, capturing the final message to a file.
+
+        `codex exec` streams an interactive log to stdout, so the result is read
+        from the `-o`/`--output-last-message` file instead. The result file and
+        the schema temp file (when present) are removed after the run.
+
+        Args:
+            prompt: The prompt text, delivered over stdin.
+            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:
+            An `Invocation` whose result is read from the `-o` file.
+        """
+        fd, result_path = tempfile.mkstemp(suffix=".json")
+        os.close(fd)
+        return Invocation(
+            self.build_command(model, schema_path, agent) + ["-o", result_path],
+            prompt,
+            result_path=result_path,
+            cleanup_paths=(result_path, *((schema_path,) if schema_path else ())),
+        )
+
+    def schema_for(self, model: type[BaseModel]) -> str:
+        """Serialize a Pydantic model into an OpenAI strict JSON schema.
+
+        Uses the OpenAI SDK's `to_strict_json_schema`, which recursively sets
+        `additionalProperties: false` and forces every property into `required`
+        across `$defs`, `anyOf`, and array items — the form the Responses API
+        requires behind `codex exec --output-schema`.
+
+        Args:
+            model: The Pydantic model describing the structured output.
+
+        Returns:
+            A strict JSON-schema string written to the `--output-schema` file.
+        """
+        from openai.lib._pydantic import to_strict_json_schema
+
+        return json.dumps(to_strict_json_schema(model))
+
     def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
-        """Parse `codex` stdout into text or a validated model.
+        """Parse the final message `codex` wrote to its `-o` file into text or a validated model.
 
         Args:
-            raw: Raw stdout from the `codex` CLI.
+            raw: The final message read from the `-o`/`--output-last-message` file.
             response_model: Model to validate against, or `None` for raw text.
 
         Returns:

{spawnllm-0.2.0 → spawnllm-0.3.1}/spawnllm/backends/gemini.py

@@ -11,7 +11,7 @@ from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import TYPE_CHECKING, ClassVar
 
-from spawnllm.backends.base import LlmBackend
+from spawnllm.backends.base import Invocation, LlmBackend
 from spawnllm.structured import extract_json_block
 
 if TYPE_CHECKING:
@@ -48,14 +48,12 @@ class GeminiFamilyBackend(LlmBackend, ABC):
     def prompt_args(self, text: str) -> list[str]:
         return ["-p", text]
 
-    def invocation(
-        self, prompt: str, *, model: str, schema_path: str | None, agent: bool
-    ) -> tuple[list[str], str | None]:
+    def invocation(self, prompt: str, *, model: str, schema_path: str | None, agent: bool) -> Invocation:
         """Build the argv and inline prompt for a single invocation.
 
         The prompt travels inline via `-p`; structured output appends the JSON
         schema and an instruction to emit only conforming JSON. An empty stdin
-        forces the CLI into non-interactive mode.
+        forces the CLI into non-interactive mode, and the result is read from stdout.
 
         Args:
             prompt: The prompt text to deliver inline.
@@ -64,10 +62,10 @@ class GeminiFamilyBackend(LlmBackend, ABC):
             agent: Whether the invocation may use tools / agent capabilities.
 
         Returns:
-            A `(argv, "")` pair; the empty stdin forces non-interactive output.
+            An `Invocation` with an empty stdin that forces non-interactive output.
         """
         text = prompt if schema_path is None else f"{prompt}\n\n{SCHEMA_PROMPT}\n{schema_path}"
-        return self.build_command(model, None, agent) + self.prompt_args(text), ""
+        return Invocation(self.build_command(model, None, agent) + self.prompt_args(text), "")
 
     def parse_response(self, raw: str, response_model: type[BaseModel] | None) -> str | BaseModel:
         """Parse Gemini-family stdout into text or a validated model.

{spawnllm-0.2.0 → spawnllm-0.3.1}/spawnllm/call.py

@@ -3,11 +3,12 @@
 from __future__ import annotations
 
 import os
+from pathlib import Path
 from typing import TYPE_CHECKING
 
 from spawnllm.backends.registry import select_backend
 from spawnllm.proc import run_cli
-from spawnllm.structured import resolve_schema_path, schema_for
+from spawnllm.structured import resolve_schema_path
 
 if TYPE_CHECKING:
     from pydantic import BaseModel
@@ -24,6 +25,8 @@ def call(
     model: TModel = "small",
     agent: bool = False,
     response_model: type[BaseModel] | None = None,
+    cwd: str | None = None,
+    timeout: int = 180,
 ) -> str | BaseModel:
     """Run one CLI-backed LLM call and parse its response.
 
@@ -36,13 +39,20 @@ def call(
         model: Abstract model tier (`small`/`medium`/`large`).
         agent: Whether the call may use tools / agent capabilities.
         response_model: Pydantic model for structured output, or `None` for text.
+        cwd: Working directory for the CLI process; `None` inherits the caller's.
+        timeout: Seconds to wait before the CLI process is killed.
 
     Returns:
         The raw text response, or a validated `response_model` instance.
     """
     backend = backend or select_backend(specialty=specialty)
-    schema = schema_for(response_model) if response_model is not None else None
+    schema = backend.schema_for(response_model) if response_model is not None else None
     schema_path = resolve_schema_path(backend, schema)
-    argv, stdin = backend.invocation(prompt, model=backend.models[model], schema_path=schema_path, agent=agent)
-    raw = run_cli(argv, input=stdin, env=os.environ | backend.env(), timeout=180)
-    return backend.parse_response(raw, response_model)
+    inv = backend.invocation(prompt, model=backend.models[model], schema_path=schema_path, agent=agent)
+    try:
+        stdout = run_cli(inv.argv, input=inv.stdin, env=os.environ | backend.env(), timeout=timeout, cwd=cwd)
+        raw = Path(inv.result_path).read_text() if inv.result_path else stdout
+        return backend.parse_response(raw, response_model)
+    finally:
+        for path in inv.cleanup_paths:
+            Path(path).unlink(missing_ok=True)

{spawnllm-0.2.0 → spawnllm-0.3.1}/spawnllm/structured.py

@@ -1,4 +1,4 @@
-"""Structured-output helpers: JSON-schema build, schema-path resolution, response parsing."""
+"""Structured-output helpers: schema-path resolution and response parsing."""
 
 from __future__ import annotations
 
@@ -22,23 +22,31 @@ __all__ = [
     "parse_result_envelope",
     "parse_structured_output",
     "resolve_schema_path",
-    "schema_for",
 ]
 
 JSON_FENCE = re.compile(r"```(?:json)?\s*\n?(.*?)\n?```", re.DOTALL)
 
 
-def schema_for(model: type[BaseModel]) -> str:
-    """Serialize a Pydantic model's JSON schema, with `additionalProperties` set to false."""
-    return json.dumps(model.model_json_schema() | {"additionalProperties": False})
+def first_json_value(source: str) -> str | None:
+    """Return the first complete JSON object/array in `source`, or `None` when there is none."""
+    decoder = json.JSONDecoder()
+    for index, char in enumerate(source):
+        if char in "{[":
+            try:
+                end = decoder.raw_decode(source, index)[1]
+            except (json.JSONDecodeError, RecursionError):
+                continue
+            return source[index:end]
+    return None
 
 
 def extract_json_block(text: str) -> str:
-    """Extract a JSON object/array from model text, tolerating ```json fences or surrounding prose."""
-    if match := JSON_FENCE.search(text):
-        return match.group(1).strip()
-    start = min((i for i in (text.find("{"), text.find("[")) if i != -1), default=0)
-    return text[start : max(text.rfind("}"), text.rfind("]")) + 1]
+    """Extract the first complete JSON value from model text, tolerating ```json fences or surrounding prose."""
+    fenced = match.group(1) if (match := JSON_FENCE.search(text)) else None
+    for source in (fenced, text):
+        if source is not None and (value := first_json_value(source)) is not None:
+            return value
+    raise ValueError(f"no JSON value found in model output: {text!r}")
 
 
 def resolve_schema_path(backend: LlmBackend, schema: str | None) -> str | None: