spawnllm 0.5.4__tar.gz → 0.6.0__tar.gz

spawnllm-0.6.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: spawnllm
+Version: 0.6.0
+Summary: Delete your subprocess wrappers around claude, codex, and gemini.
+Keywords: 
+Author: Yasyf Mohamedali
+Author-email: Yasyf Mohamedali <yasyfm@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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'
+Requires-Dist: anyio>=4 ; extra == 'dev'
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.8 ; extra == 'dev'
+Requires-Dist: ty>=0.0.44 ; extra == 'dev'
+Requires-Dist: zstandard>=0.25.0 ; extra == 'dev'
+Requires-Dist: numpy>=1.26 ; extra == 'dev'
+Requires-Dist: orjson>=3.10 ; extra == 'dev'
+Requires-Dist: zstandard>=0.25.0 ; extra == 'mlx'
+Requires-Dist: numpy>=1.26 ; extra == 'mlx'
+Requires-Dist: orjson>=3.10 ; extra == 'mlx'
+Requires-Dist: anyio>=4.4 ; extra == 'mlx'
+Requires-Dist: huggingface-hub>=0.25 ; extra == 'mlx'
+Requires-Dist: mlx-lm>=0.31.3 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'mlx'
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/yasyf/spawnllm
+Project-URL: Documentation, https://yasyf.github.io/spawnllm/
+Project-URL: Repository, https://github.com/yasyf/spawnllm
+Project-URL: Issues, https://github.com/yasyf/spawnllm/issues
+Project-URL: Changelog, https://github.com/yasyf/spawnllm/blob/main/CHANGELOG.md
+Provides-Extra: adapter
+Provides-Extra: dev
+Provides-Extra: mlx
+Description-Content-Type: text/markdown
+
+# ![spawnllm](https://github.com/yasyf/spawnllm/raw/main/docs/assets/readme-banner.webp)
+
+**Delete your subprocess wrappers around claude, codex, and gemini.** spawnllm subshells all three CLIs plus local MLX and returns one Pydantic-validated Response, so the per-model plumbing you hand-rolled goes away.
+
+[![CI](https://github.com/yasyf/spawnllm/actions/workflows/ci.yml/badge.svg)](https://github.com/yasyf/spawnllm/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/spawnllm)](https://pypi.org/project/spawnllm/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/yasyf/spawnllm/blob/main/LICENSE)
+
+## Get started
+
+```bash
+uvx spawnllm status
+```
+
+<img src="https://github.com/yasyf/spawnllm/raw/main/docs/assets/demo.png" alt="Terminal running 'uvx spawnllm status' — every backend reports ready and auto-selection picks claude" width="700">
+
+Driving with an agent? Paste this:
+
+```text
+Run `uv add spawnllm` in this project.
+Replace our hand-rolled claude/codex subprocess code with spawnllm's `call_sync`,
+or `extract_sync` with a Pydantic response model for structured output.
+Verify available backends with `uvx spawnllm status`.
+Docs: https://yasyf.github.io/spawnllm/
+```
+
+---
+
+## Use cases
+
+### Delete your hand-rolled claude/codex subprocess plumbing
+
+Every small tool grows its own `subprocess.run(["claude", "-p", ...])` — argv quirks, stdin piping, exit-code guesswork — and each copy drifts. One call replaces all of it:
+
+```python
+from spawnllm import call_sync
+
+print(call_sync("Reply with just the word: pong"))
+```
+
+Prints `pong`. With no `backend=`, spawnllm auto-selects the first installed, authenticated CLI, pipes the prompt over stdin, and retries transient 529/overloaded/rate-limit failures with capped backoff.
+
+### Get a validated Pydantic object back, not a string to parse
+
+Scraping JSON out of a model's stdout means regexes, code fences, and silent schema drift. `extract_sync` validates instead:
+
+```python
+from pydantic import BaseModel
+
+from spawnllm import extract_sync
+
+
+class Capital(BaseModel):
+    country: str
+    capital: str
+
+
+result = extract_sync("What is the capital of France?", Capital)
+print(result.capital)  # Paris
+```
+
+The backend turns `Capital` into a JSON-schema constraint on the call itself, and a non-conforming reply raises `pydantic.ValidationError` instead of sneaking downstream.
+
+### Run Apple-Silicon MLX models with fused adapters and prompt-cache reuse
+
+Shipping a LoRA-tuned local model means hand-rolling adapter fusion, model caching, and worker-thread lifecycle. The MLX extra owns all three:
+
+```bash
+uv add "spawnllm[mlx]"
+```
+
+`AdapterFuser.ensure_fused` fuses your compressed adapter into the base model once and caches the result in the Hugging Face hub layout; `MlxEngine` loads it on a dedicated worker thread, precomputes a prompt cache for your shared prefix messages, and batches generation. Wrap the engine in an `MlxBackend` and the same `run_sync` call works.
+
+## More in the docs
+
+- **Spec-driven runs** — a literal model id, per-provider flag passthrough, and envelope-aware retry via `RunSpec` — [Running reference](https://yasyf.github.io/spawnllm/reference/#running)
+- **Backend selection** — the priority chain, plus `specialty=` routing (`debugging` and `review` go to Codex, `general` to Claude) — [Backends reference](https://yasyf.github.io/spawnllm/reference/#backends)
+- **Transport helpers** — `run_cli`, `collect_process`, and `map_concurrent`, the subprocess plumbing shared by every CLI backend — [Transport reference](https://yasyf.github.io/spawnllm/reference/#transport)
+- **The CLI** — `spawnllm call`, `status`, and `backends` from any shell — [CLI reference](https://yasyf.github.io/spawnllm/reference/cli/)
+- **MLX internals** — the adapter codec, fuser, and runtime patches behind the local engine — [MLX reference](https://yasyf.github.io/spawnllm/reference/#mlx)
+
+Read the [docs](https://yasyf.github.io/spawnllm/) for the full guide and API reference. Licensed under [MIT](https://github.com/yasyf/spawnllm/blob/main/LICENSE).

spawnllm-0.6.0/README.md

@@ -0,0 +1,82 @@
+# ![spawnllm](https://github.com/yasyf/spawnllm/raw/main/docs/assets/readme-banner.webp)
+
+**Delete your subprocess wrappers around claude, codex, and gemini.** spawnllm subshells all three CLIs plus local MLX and returns one Pydantic-validated Response, so the per-model plumbing you hand-rolled goes away.
+
+[![CI](https://github.com/yasyf/spawnllm/actions/workflows/ci.yml/badge.svg)](https://github.com/yasyf/spawnllm/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/spawnllm)](https://pypi.org/project/spawnllm/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/yasyf/spawnllm/blob/main/LICENSE)
+
+## Get started
+
+```bash
+uvx spawnllm status
+```
+
+<img src="https://github.com/yasyf/spawnllm/raw/main/docs/assets/demo.png" alt="Terminal running 'uvx spawnllm status' — every backend reports ready and auto-selection picks claude" width="700">
+
+Driving with an agent? Paste this:
+
+```text
+Run `uv add spawnllm` in this project.
+Replace our hand-rolled claude/codex subprocess code with spawnllm's `call_sync`,
+or `extract_sync` with a Pydantic response model for structured output.
+Verify available backends with `uvx spawnllm status`.
+Docs: https://yasyf.github.io/spawnllm/
+```
+
+---
+
+## Use cases
+
+### Delete your hand-rolled claude/codex subprocess plumbing
+
+Every small tool grows its own `subprocess.run(["claude", "-p", ...])` — argv quirks, stdin piping, exit-code guesswork — and each copy drifts. One call replaces all of it:
+
+```python
+from spawnllm import call_sync
+
+print(call_sync("Reply with just the word: pong"))
+```
+
+Prints `pong`. With no `backend=`, spawnllm auto-selects the first installed, authenticated CLI, pipes the prompt over stdin, and retries transient 529/overloaded/rate-limit failures with capped backoff.
+
+### Get a validated Pydantic object back, not a string to parse
+
+Scraping JSON out of a model's stdout means regexes, code fences, and silent schema drift. `extract_sync` validates instead:
+
+```python
+from pydantic import BaseModel
+
+from spawnllm import extract_sync
+
+
+class Capital(BaseModel):
+    country: str
+    capital: str
+
+
+result = extract_sync("What is the capital of France?", Capital)
+print(result.capital)  # Paris
+```
+
+The backend turns `Capital` into a JSON-schema constraint on the call itself, and a non-conforming reply raises `pydantic.ValidationError` instead of sneaking downstream.
+
+### Run Apple-Silicon MLX models with fused adapters and prompt-cache reuse
+
+Shipping a LoRA-tuned local model means hand-rolling adapter fusion, model caching, and worker-thread lifecycle. The MLX extra owns all three:
+
+```bash
+uv add "spawnllm[mlx]"
+```
+
+`AdapterFuser.ensure_fused` fuses your compressed adapter into the base model once and caches the result in the Hugging Face hub layout; `MlxEngine` loads it on a dedicated worker thread, precomputes a prompt cache for your shared prefix messages, and batches generation. Wrap the engine in an `MlxBackend` and the same `run_sync` call works.
+
+## More in the docs
+
+- **Spec-driven runs** — a literal model id, per-provider flag passthrough, and envelope-aware retry via `RunSpec` — [Running reference](https://yasyf.github.io/spawnllm/reference/#running)
+- **Backend selection** — the priority chain, plus `specialty=` routing (`debugging` and `review` go to Codex, `general` to Claude) — [Backends reference](https://yasyf.github.io/spawnllm/reference/#backends)
+- **Transport helpers** — `run_cli`, `collect_process`, and `map_concurrent`, the subprocess plumbing shared by every CLI backend — [Transport reference](https://yasyf.github.io/spawnllm/reference/#transport)
+- **The CLI** — `spawnllm call`, `status`, and `backends` from any shell — [CLI reference](https://yasyf.github.io/spawnllm/reference/cli/)
+- **MLX internals** — the adapter codec, fuser, and runtime patches behind the local engine — [MLX reference](https://yasyf.github.io/spawnllm/reference/#mlx)
+
+Read the [docs](https://yasyf.github.io/spawnllm/) for the full guide and API reference. Licensed under [MIT](https://github.com/yasyf/spawnllm/blob/main/LICENSE).

{spawnllm-0.5.4 → spawnllm-0.6.0}/pyproject.toml

@@ -1,8 +1,8 @@
 [project]
 name = "spawnllm"
 # Inert sentinel: the real version is set from the release tag (uv version --frozen).
-version = "0.5.4"
-description = "Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools."
+version = "0.6.0"
+description = "Delete your subprocess wrappers around claude, codex, and gemini."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -126,10 +126,5 @@ docs = [
     # griffe (2.x) distribution, overriding the legacy griffe<2 pin great-docs
     # itself still declares.
     "griffelib>=2.0",
-    # Tracking great-docs main until a release newer than 0.13.0: main carries
-    # build-time GitHub widget stats (embedded via the CI GITHUB_TOKEN), which
-    # drop the navbar widget's client-side API calls — the source of GitHub 403
-    # errors on the published site.
-    # TODO(bootstrap): revert to a PyPI pin (`great-docs>=0.14`) once released.
-    "great-docs @ git+https://github.com/posit-dev/great-docs@main",
+    "great-docs>=0.14",
 ]

{spawnllm-0.5.4 → spawnllm-0.6.0}/spawnllm/__init__.py

@@ -28,7 +28,7 @@ from spawnllm.backends import (
 )
 from spawnllm.call import call, call_sync
 from spawnllm.extract import extract, extract_sync
-from spawnllm.response import Error, Output, Response, Result
+from spawnllm.response import DiscardedAttempt, Error, Output, Response, Result
 from spawnllm.run import run, run_sync
 from spawnllm.spec import ClaudeConfig, CodexConfig, GeminiConfig, RunSpec
 from spawnllm.types import ProviderName, TModel, TSpecialty
@@ -46,6 +46,7 @@ __all__ = [
     "CliBackend",
     "CodexCliBackend",
     "CodexConfig",
+    "DiscardedAttempt",
     "Error",
     "GeminiCliBackend",
     "GeminiConfig",

{spawnllm-0.5.4 → spawnllm-0.6.0}/spawnllm/backends/base.py

@@ -80,12 +80,16 @@ class Invocation:
         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.
+        stdout_path: File the capture machinery redirects the child's stdout to;
+            when set, stdout goes to this regular file instead of a pipe and is
+            read back as the capture, dodging a Node child's async-pipe truncation.
         cleanup_paths: Temp files to remove once the invocation completes.
     """
 
     argv: list[str]
     stdin: str | None = None
     result_path: str | None = None
+    stdout_path: str | None = None
     cleanup_paths: tuple[str, ...] = ()
 
 
@@ -244,6 +248,21 @@ class LlmBackend(ABC):
         """Return the provider's error message from an error envelope, or `None` on success."""
         return None
 
+    def accounting(self, raw: str) -> tuple[float | None, dict[str, object] | None]:
+        """Return the `(cost_usd, usage)` an attempt's output reports, or `(None, None)` when it carries neither.
+
+        The retry loop calls this on each transient failure it discards, so a
+        caller reconciling spend can still see the cost. The default parses
+        nothing; a backend whose envelope records spend overrides it.
+
+        Args:
+            raw: The raw output read wherever the provider wrote it.
+
+        Returns:
+            A `(cost_usd, usage)` pair, each `None` when the output does not carry it.
+        """
+        return None, None
+
 
 class CliBackend(LlmBackend):
     """Execution contract for the subprocess-backed LLM family.
@@ -300,6 +319,7 @@ class CliBackend(LlmBackend):
                     env=os.environ | self.env(spec) | (spec.env or {}),
                     cwd=spec.cwd,
                     timeout=spec.timeout,
+                    stdout_path=inv.stdout_path,
                 )
             except TimeoutError:
                 return self.timed_out(spec)
@@ -319,6 +339,7 @@ class CliBackend(LlmBackend):
                     env=os.environ | self.env(spec) | (spec.env or {}),
                     cwd=spec.cwd,
                     timeout=spec.timeout,
+                    stdout_path=inv.stdout_path,
                 )
             except subprocess.TimeoutExpired:
                 return self.timed_out(spec)

{spawnllm-0.5.4 → spawnllm-0.6.0}/spawnllm/backends/claude.py

@@ -11,9 +11,9 @@ import subprocess
 import sys
 import tempfile
 from pathlib import Path
-from typing import TYPE_CHECKING, ClassVar
+from typing import TYPE_CHECKING, ClassVar, cast
 
-from spawnllm.backends.base import CliBackend
+from spawnllm.backends.base import CliBackend, Invocation
 from spawnllm.spec import ClaudeConfig
 from spawnllm.structured import structured_value
 
@@ -142,6 +142,27 @@ class ClaudeCliBackend(CliBackend):
             *(["--verbose"] if cfg.verbose else []),
         ]
 
+    def invocation(self, spec: RunSpec) -> Invocation:
+        """Build the `claude -p` invocation, capturing stdout to a real file.
+
+        `claude` is a Node process that writes its single-blob result to stdout
+        asynchronously; when stdout is a pipe and the process exits before that
+        write drains, Node drops the tail (observed truncating at exactly 64 KiB).
+        Pointing stdout at a regular file makes Node's write synchronous, so the
+        full result survives; the file is read back as stdout and removed after
+        the run.
+
+        Args:
+            spec: The configured run to translate into an invocation.
+
+        Returns:
+            An `Invocation` whose stdout is captured to a temp file.
+        """
+        argv = self.build_command(spec)
+        fd, stdout_path = tempfile.mkstemp(suffix=".json")
+        os.close(fd)
+        return Invocation(argv, spec.prompt, stdout_path=stdout_path, cleanup_paths=(stdout_path,))
+
     def schema_for(self, model: type[BaseModel]) -> str:
         """Serialize a Pydantic model into Anthropic's structured-output JSON schema.
 
@@ -175,6 +196,17 @@ class ClaudeCliBackend(CliBackend):
             return event["result"] if isinstance(event.get("result"), str) else "claude reported an error"
         return None
 
+    def accounting(self, raw: str) -> tuple[float | None, dict[str, object] | None]:
+        """Return `total_cost_usd` and `usage` from the `claude` result envelope, or `(None, None)` when absent."""
+        if (event := result_event(raw)) is None:
+            return None, None
+        cost = event.get("total_cost_usd")
+        usage = event.get("usage")
+        return (
+            float(cost) if isinstance(cost, int | float) else None,
+            cast("dict[str, object]", usage) if isinstance(usage, dict) else None,
+        )
+
     def env(self, spec: RunSpec) -> dict[str, str]:
         """Point an isolated run at a fresh, host-free `CLAUDE_CONFIG_DIR`; otherwise add nothing.
 

{spawnllm-0.5.4 → spawnllm-0.6.0}/spawnllm/backends/codex.py

@@ -23,7 +23,9 @@ class CodexCliBackend(CliBackend):
 
     `build_command` translates a `RunSpec` into a `codex exec` argv that runs an
     ephemeral session in a read-only sandbox; `invocation` resolves the schema to
-    a temp file and captures the final message to an `-o` file. An optional
+    a temp file and captures the final message to an `-o` file. The argv carries
+    `--skip-git-repo-check` so a run in an untrusted or non-git `cwd` is not refused —
+    the sandbox already confines it, so the trust gate adds nothing here. An optional
     `CodexConfig` overrides the sandbox and re-enables Codex hooks or MCP servers.
 
     Attributes:
@@ -70,6 +72,7 @@ class CodexCliBackend(CliBackend):
             "--ephemeral",
             "--sandbox",
             cfg.sandbox or "read-only",
+            "--skip-git-repo-check",
             "--model",
             model,
             *(["-c", f"model_reasoning_effort={effort}"] if effort else []),

{spawnllm-0.5.4 → spawnllm-0.6.0}/spawnllm/proc.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import subprocess
 from collections.abc import Awaitable, Callable, Sequence
 from dataclasses import dataclass
+from pathlib import Path
 
 __all__ = ["RunResult", "acapture_cli", "arun_cli", "capture_cli", "collect_process", "map_concurrent", "run_cli"]
 
@@ -76,6 +78,7 @@ def capture_cli(
     timeout: int = 180,
     env: dict[str, str] | None = None,
     cwd: str | None = None,
+    stdout_path: str | None = None,
 ) -> RunResult:
     """Run a CLI command to completion and capture its full outcome.
 
@@ -88,6 +91,10 @@ def capture_cli(
         timeout: Seconds to wait before the process is killed.
         env: Environment for the process; `None` inherits the current environment.
         cwd: Working directory for the process.
+        stdout_path: When set, the child writes stdout to this file (a regular
+            fd) instead of a pipe; the file is read back into `RunResult.stdout`.
+            A file makes a Node child's stdout writes synchronous, so a large
+            single-blob write is not truncated when the process exits.
 
     Returns:
         The captured stdout, stderr, and exit code.
@@ -95,16 +102,19 @@ def capture_cli(
     Raises:
         subprocess.TimeoutExpired: When the process outlives `timeout`.
     """
-    result = subprocess.run(
-        argv,
-        input=input,
-        capture_output=True,
-        text=True,
-        timeout=timeout,
-        env=env,
-        cwd=cwd,
-    )
-    return RunResult(result.stdout, result.stderr, result.returncode)
+    with open(stdout_path, "wb") if stdout_path is not None else contextlib.nullcontext() as stdout_file:
+        result = subprocess.run(
+            argv,
+            input=input,
+            stdout=stdout_file if stdout_file is not None else subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=timeout,
+            env=env,
+            cwd=cwd,
+        )
+    stdout = Path(stdout_path).read_text() if stdout_path is not None else result.stdout
+    return RunResult(stdout, result.stderr, result.returncode)
 
 
 async def collect_process(
@@ -115,20 +125,22 @@ async def collect_process(
     """Drain a subprocess's stdout and stderr concurrently and wait for it to exit.
 
     Args:
-        proc: A process created with both stdout and stderr piped.
+        proc: A process created with stderr piped and stdout either piped or
+            redirected to a file. A file-backed stdout (a `None` pipe) is not
+            drained here and comes back empty for the caller to read from the file.
         stderr_tee: Callback invoked with each stderr line as it arrives.
 
     Returns:
         A `(stdout, stderr, returncode)` tuple.
     """
     assert proc.stderr is not None, "create_subprocess_exec was called with stderr=PIPE"
-    assert proc.stdout is not None, "create_subprocess_exec was called with stdout=PIPE"
     stderr_buf = bytearray()
     async with asyncio.TaskGroup() as tg:
+        stdout_task = tg.create_task(proc.stdout.read()) if proc.stdout is not None else None
         tg.create_task(_tee_stderr(proc.stderr, stderr_buf, stderr_tee))
-        stdout_task = tg.create_task(proc.stdout.read())
         rc_task = tg.create_task(proc.wait())
-    return stdout_task.result(), bytes(stderr_buf), rc_task.result()
+    stdout = stdout_task.result() if stdout_task is not None else b""
+    return stdout, bytes(stderr_buf), rc_task.result()
 
 
 async def _tee_stderr(
@@ -142,6 +154,23 @@ async def _tee_stderr(
             stderr_tee(raw)
 
 
+async def _reap(proc: asyncio.subprocess.Process, *, grace: float = 2.0) -> None:
+    """Terminate a still-running child (SIGTERM, then SIGKILL after `grace`) and wait for it to exit.
+
+    A no-op once the child has exited on its own; on a timed-out or cancelled
+    capture it stops the orphan — which keeps running and spending — before the
+    caller unlinks its output file.
+    """
+    if proc.returncode is not None:
+        return
+    proc.terminate()
+    try:
+        await asyncio.wait_for(proc.wait(), grace)
+    except TimeoutError:
+        proc.kill()
+        await proc.wait()
+
+
 async def arun_cli(
     argv: list[str],
     *,
@@ -191,6 +220,7 @@ async def acapture_cli(
     env: dict[str, str] | None = None,
     cwd: str | None = None,
     timeout: int | None = None,
+    stdout_path: str | None = None,
 ) -> RunResult:
     """Run a CLI command asynchronously and capture its full outcome.
 
@@ -203,6 +233,11 @@ async def acapture_cli(
         env: Environment for the process; `None` inherits the current environment.
         cwd: Working directory for the process.
         timeout: Seconds to wait before the wait is abandoned; `None` waits forever.
+        stdout_path: When set, the child writes stdout to this file (a regular
+            fd) instead of a pipe; the file is read back into `RunResult.stdout`.
+            A file makes a Node child's stdout writes synchronous, so a large
+            single-blob write is not truncated when the process exits before the
+            async pipe write drains.
 
     Returns:
         The captured stdout, stderr, and exit code.
@@ -210,21 +245,28 @@ async def acapture_cli(
     Raises:
         TimeoutError: When the process outlives `timeout`.
     """
-    proc = await asyncio.create_subprocess_exec(
-        *argv,
-        stdin=asyncio.subprocess.PIPE if input is not None else None,
-        stdout=asyncio.subprocess.PIPE,
-        stderr=asyncio.subprocess.PIPE,
-        env=env,
-        cwd=cwd,
-    )
-    if input is not None:
-        assert proc.stdin is not None, "create_subprocess_exec was called with stdin=PIPE"
-        proc.stdin.write(input.encode())
-        await proc.stdin.drain()
-        proc.stdin.close()
-    collect = collect_process(proc)
-    stdout, stderr, rc = await (asyncio.wait_for(collect, timeout) if timeout is not None else collect)
+    with open(stdout_path, "wb") if stdout_path is not None else contextlib.nullcontext() as stdout_file:
+        proc = await asyncio.create_subprocess_exec(
+            *argv,
+            stdin=asyncio.subprocess.PIPE if input is not None else None,
+            stdout=stdout_file if stdout_file is not None else asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=env,
+            cwd=cwd,
+        )
+        try:
+            if input is not None:
+                assert proc.stdin is not None, "create_subprocess_exec was called with stdin=PIPE"
+                proc.stdin.write(input.encode())
+                await proc.stdin.drain()
+                proc.stdin.close()
+            collect = collect_process(proc)
+            stdout, stderr, rc = await (asyncio.wait_for(collect, timeout) if timeout is not None else collect)
+        finally:
+            await _reap(proc)
+    if stdout_path is not None:
+        # Read after the direct child has exited; a descendant that writes here afterward is not captured.
+        stdout = Path(stdout_path).read_bytes()
     return RunResult(stdout.decode(), stderr.decode(), rc)
 
 

{spawnllm-0.5.4 → spawnllm-0.6.0}/spawnllm/response.py

@@ -57,6 +57,28 @@ class Output:
     raw: str
 
 
+@dataclass(frozen=True, slots=True)
+class DiscardedAttempt:
+    """A transient failure the retry loop threw away, summarized for spend accounting.
+
+    `run`/`run_sync` return only the final attempt's `Response`, so a caller
+    tracking spend never sees the cost of the retries that preceded it. Each
+    discarded attempt is summarized here: `cost_usd` and `usage` when the
+    attempt's output carried parseable accounting, else `None`; `raw_bytes` is
+    always the UTF-8 byte length of the discarded output. `attempt` is the
+    zero-based index and `error` the discarded exception's class name.
+
+    Example:
+        >>> DiscardedAttempt(attempt=0, error="BackendCallError", cost_usd=0.02, usage=None, raw_bytes=57)
+    """
+
+    attempt: int
+    error: str
+    cost_usd: float | None
+    usage: dict[str, object] | None
+    raw_bytes: int
+
+
 @dataclass(frozen=True, slots=True)
 class Response:
     """A backend's fully-resolved outcome: the spec, the raw output, and exactly one of result/error.
@@ -66,7 +88,8 @@ class Response:
     `output` are always present (the raw bytes live in `output.raw` even on
     failure); exactly one of `result`/`error` is set. Every failure — a nonzero
     exit, an error envelope, a timeout, or a validation error — routes through
-    `error`, never a raise from `run`.
+    `error`, never a raise from `run`. `discarded_attempts` carries the transient
+    failures `run` retried away before this one, empty when there were none.
 
     Example:
         >>> Response(spec=spec, output=Output(raw="hi"), result=Result(raw="hi"))
@@ -76,3 +99,4 @@ class Response:
     output: Output
     result: Result | None = None
     error: Error | None = None
+    discarded_attempts: tuple[DiscardedAttempt, ...] = ()

{spawnllm-0.5.4 → spawnllm-0.6.0}/spawnllm/run.py

@@ -4,9 +4,11 @@ from __future__ import annotations
 
 import asyncio
 import time
+from dataclasses import replace
 from typing import TYPE_CHECKING
 
 from spawnllm.backends.registry import select_backend
+from spawnllm.response import DiscardedAttempt
 from spawnllm.structured import backoff, is_transient
 
 if TYPE_CHECKING:
@@ -17,6 +19,25 @@ if TYPE_CHECKING:
 __all__ = ["run", "run_sync"]
 
 
+def _discarded(backend: LlmBackend, resp: Response, attempt: int) -> DiscardedAttempt:
+    """Summarize a transient `resp` the retry loop is about to discard on attempt `attempt`.
+
+    `accounting` is best-effort by contract, so a parse failure on a malformed
+    envelope degrades to no cost/usage rather than aborting the retry loop.
+    """
+    try:
+        cost_usd, usage = backend.accounting(resp.output.raw)
+    except Exception:
+        cost_usd, usage = None, None
+    return DiscardedAttempt(
+        attempt=attempt,
+        error=type(resp.error.ex).__name__,
+        cost_usd=cost_usd,
+        usage=usage,
+        raw_bytes=len(resp.output.raw.encode()),
+    )
+
+
 async def run(spec: RunSpec, *, backend: LlmBackend | None = None) -> Response:
     """Execute a `RunSpec` asynchronously, retrying transient failures with backoff.
 
@@ -32,15 +53,18 @@ async def run(spec: RunSpec, *, backend: LlmBackend | None = None) -> Response:
         backend: The backend to run on; defaults to `select_backend()`.
 
     Returns:
-        The resolved `Response` of the last attempt.
+        The resolved `Response` of the last attempt, carrying every retried-away
+        attempt in `discarded_attempts`.
     """
     backend = backend or select_backend()
+    discarded: list[DiscardedAttempt] = []
     for attempt in range(spec.max_attempts):
         resp = await backend.aexecute(spec)
-        if not is_transient(resp):
+        if not is_transient(resp) or attempt + 1 == spec.max_attempts:
             break
+        discarded.append(_discarded(backend, resp, attempt))
         await asyncio.sleep(backoff(attempt))
-    return resp
+    return replace(resp, discarded_attempts=tuple(discarded)) if discarded else resp
 
 
 def run_sync(spec: RunSpec, *, backend: LlmBackend | None = None) -> Response:
@@ -55,12 +79,15 @@ def run_sync(spec: RunSpec, *, backend: LlmBackend | None = None) -> Response:
         backend: The backend to run on; defaults to `select_backend()`.
 
     Returns:
-        The resolved `Response` of the last attempt.
+        The resolved `Response` of the last attempt, carrying every retried-away
+        attempt in `discarded_attempts`.
     """
     backend = backend or select_backend()
+    discarded: list[DiscardedAttempt] = []
     for attempt in range(spec.max_attempts):
         resp = backend.execute(spec)
-        if not is_transient(resp):
+        if not is_transient(resp) or attempt + 1 == spec.max_attempts:
             break
+        discarded.append(_discarded(backend, resp, attempt))
         time.sleep(backoff(attempt))
-    return resp
+    return replace(resp, discarded_attempts=tuple(discarded)) if discarded else resp

spawnllm-0.5.4/PKG-INFO

@@ -1,174 +0,0 @@
-Metadata-Version: 2.4
-Name: spawnllm
-Version: 0.5.4
-Summary: Subshell + MLX LLM-calling backends (Claude/Codex CLI, local MLX) shared across tools.
-Keywords: 
-Author: Yasyf Mohamedali
-Author-email: Yasyf Mohamedali <yasyfm@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-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'
-Requires-Dist: anyio>=4 ; extra == 'dev'
-Requires-Dist: pytest>=8.0 ; extra == 'dev'
-Requires-Dist: ruff>=0.8 ; extra == 'dev'
-Requires-Dist: ty>=0.0.44 ; extra == 'dev'
-Requires-Dist: zstandard>=0.25.0 ; extra == 'dev'
-Requires-Dist: numpy>=1.26 ; extra == 'dev'
-Requires-Dist: orjson>=3.10 ; extra == 'dev'
-Requires-Dist: zstandard>=0.25.0 ; extra == 'mlx'
-Requires-Dist: numpy>=1.26 ; extra == 'mlx'
-Requires-Dist: orjson>=3.10 ; extra == 'mlx'
-Requires-Dist: anyio>=4.4 ; extra == 'mlx'
-Requires-Dist: huggingface-hub>=0.25 ; extra == 'mlx'
-Requires-Dist: mlx-lm>=0.31.3 ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'mlx'
-Requires-Python: >=3.13
-Project-URL: Homepage, https://github.com/yasyf/spawnllm
-Project-URL: Documentation, https://yasyf.github.io/spawnllm/
-Project-URL: Repository, https://github.com/yasyf/spawnllm
-Project-URL: Issues, https://github.com/yasyf/spawnllm/issues
-Project-URL: Changelog, https://github.com/yasyf/spawnllm/blob/main/CHANGELOG.md
-Provides-Extra: adapter
-Provides-Extra: dev
-Provides-Extra: mlx
-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/)
-[![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
-
-Run the CLI with [uvx](https://docs.astral.sh/uv/):
-
-```bash
-uvx spawnllm --help
-```
-
-For the local MLX engine (Apple Silicon only), pull the extra: `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. Run `uvx spawnllm --help` for the full flag list.
-
-### From Python
-
-`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_sync
-
-print(call_sync("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_sync, ClaudeCliBackend
-
-
-class Capital(BaseModel):
-    country: str
-    capital: str
-
-
-result = call_sync(
-    "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.
-
-### 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
-```
-
-## How it works
-
-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
-
-[Read the docs](https://yasyf.github.io/spawnllm/) for the full guide and API reference.

spawnllm-0.5.4/README.md

@@ -1,127 +0,0 @@
-# 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
-
-Run the CLI with [uvx](https://docs.astral.sh/uv/):
-
-```bash
-uvx spawnllm --help
-```
-
-For the local MLX engine (Apple Silicon only), pull the extra: `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. Run `uvx spawnllm --help` for the full flag list.
-
-### From Python
-
-`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_sync
-
-print(call_sync("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_sync, ClaudeCliBackend
-
-
-class Capital(BaseModel):
-    country: str
-    capital: str
-
-
-result = call_sync(
-    "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.
-
-### 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
-```
-
-## How it works
-
-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
-
-[Read the docs](https://yasyf.github.io/spawnllm/) for the full guide and API reference.