spawnllm 0.5.5__tar.gz → 0.6.1__tar.gz

{spawnllm-0.5.5 → spawnllm-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawnllm
-Version: 0.5.5
+Version: 0.6.1
 Summary: Delete your subprocess wrappers around claude, codex, and gemini.
 Keywords: 
 Author: Yasyf Mohamedali
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Typing :: Typed
 Requires-Dist: click>=8
+Requires-Dist: httpx>=0.27
 Requires-Dist: loguru>=0.7
 Requires-Dist: pydantic>=2
 Requires-Dist: openai>=2.43

{spawnllm-0.5.5 → spawnllm-0.6.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "spawnllm"
 # Inert sentinel: the real version is set from the release tag (uv version --frozen).
-version = "0.5.5"
+version = "0.6.1"
 description = "Delete your subprocess wrappers around claude, codex, and gemini."
 readme = "README.md"
 license = "MIT"
@@ -19,6 +19,7 @@ classifiers = [
 requires-python = ">=3.13"
 dependencies = [
     "click>=8",
+    "httpx>=0.27",
     "loguru>=0.7",
     "pydantic>=2",
     # Per-backend strict-schema transforms: openai.lib._pydantic.to_strict_json_schema
@@ -126,10 +127,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.5 → spawnllm-0.6.1}/spawnllm/__init__.py

@@ -24,11 +24,12 @@ from spawnllm.backends import (
     LlmBackend,
     LlmBackends,
     MlxBackend,
+    OpenAiEndpointBackend,
     select_backend,
 )
 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,12 +47,14 @@ __all__ = [
     "CliBackend",
     "CodexCliBackend",
     "CodexConfig",
+    "DiscardedAttempt",
     "Error",
     "GeminiCliBackend",
     "GeminiConfig",
     "LlmBackend",
     "LlmBackends",
     "MlxBackend",
+    "OpenAiEndpointBackend",
     "Output",
     "ProviderName",
     "Response",

{spawnllm-0.5.5 → spawnllm-0.6.1}/spawnllm/backends/__init__.py

@@ -16,6 +16,7 @@ from spawnllm.backends.claude import ClaudeCliBackend
 from spawnllm.backends.codex import CodexCliBackend
 from spawnllm.backends.gemini import AntigravityCliBackend, GeminiCliBackend
 from spawnllm.backends.mlx import MlxBackend
+from spawnllm.backends.openai_endpoint import OpenAiEndpointBackend
 from spawnllm.backends.registry import LlmBackends, select_backend
 
 __all__ = [
@@ -33,5 +34,6 @@ __all__ = [
     "LlmBackend",
     "LlmBackends",
     "MlxBackend",
+    "OpenAiEndpointBackend",
     "select_backend",
 ]

{spawnllm-0.5.5 → spawnllm-0.6.1}/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.5 → spawnllm-0.6.1}/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.6.1/spawnllm/backends/openai_endpoint.py

@@ -0,0 +1,137 @@
+"""HTTP backend for any OpenAI-compatible `/chat/completions` endpoint."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, ClassVar
+
+import httpx
+
+from spawnllm.backends.base import BackendReady, LlmBackend
+from spawnllm.structured import extract_json_block
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+    from spawnllm.backends.base import BackendStatus
+    from spawnllm.response import Response
+    from spawnllm.spec import RunSpec
+    from spawnllm.types import ProviderName, TModel
+
+
+class OpenAiEndpointBackend(LlmBackend):
+    """`LlmBackend` that POSTs to an OpenAI-compatible `/chat/completions` endpoint.
+
+    Unlike the CLI backends this drives a raw `httpx` request rather than a
+    subprocess, and it is never auto-selected; the consumer constructs it
+    explicitly with a `base_url` and a literal `model`. Every abstract tier maps
+    to that one pinned `model`, and `RunSpec.model` is ignored at request time —
+    the endpoint always serves the constructor's `model`. Structured output rides
+    on `response_format` with a strict `json_schema`; text output reads
+    `choices[0].message.content`.
+
+    Args:
+        base_url: Root URL of the server; `/chat/completions` is appended.
+        model: The literal model id sent in every request body.
+        api_key: Bearer token for the `Authorization` header; defaults to
+            `"local"` for self-hosted servers that ignore it.
+        transport: Async transport injected into the `httpx.AsyncClient` used by
+            `aexecute` — e.g. a record/replay caching transport; `None` uses
+            httpx's default transport. The synchronous `execute` path always uses
+            the default transport.
+
+    Example:
+        >>> backend = OpenAiEndpointBackend("http://localhost:8000/v1", "qwen3")
+        >>> backend.execute(RunSpec(prompt="ping", model="qwen3"))
+    """
+
+    provider: ClassVar[ProviderName] = "openai_endpoint"
+
+    def __init__(
+        self, base_url: str, model: str, *, api_key: str = "local", transport: httpx.AsyncBaseTransport | None = None
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.model = model
+        self.api_key = api_key
+        self.transport = transport
+        self.models: dict[TModel, str] = {"small": model, "medium": model, "large": model}
+
+    @property
+    def url(self) -> str:
+        return f"{self.base_url}/chat/completions"
+
+    def headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    def payload(self, spec: RunSpec) -> dict[str, object]:
+        base: dict[str, object] = {"model": self.model, "messages": [{"role": "user", "content": spec.prompt}]}
+        if (schema := self.schema_arg(spec)) is None:
+            return base
+        json_schema = {"name": "response", "strict": True, "schema": json.loads(schema)}
+        return base | {"response_format": {"type": "json_schema", "json_schema": json_schema}}
+
+    def resolve(self, resp: httpx.Response, spec: RunSpec) -> Response:
+        return self.to_response(
+            resp.text,
+            returncode=0 if resp.is_success else resp.status_code,
+            stderr="" if resp.is_success else resp.text,
+            spec=spec,
+        )
+
+    async def aexecute(self, spec: RunSpec) -> Response:
+        async with httpx.AsyncClient(timeout=spec.timeout, transport=self.transport) as client:
+            resp = await client.post(self.url, headers=self.headers(), json=self.payload(spec))
+        return self.resolve(resp, spec)
+
+    def execute(self, spec: RunSpec) -> Response:
+        with httpx.Client(timeout=spec.timeout) as client:
+            resp = client.post(self.url, headers=self.headers(), json=self.payload(spec))
+        return self.resolve(resp, spec)
+
+    def schema_for(self, model: type[BaseModel]) -> str:
+        """Serialize a Pydantic model into an OpenAI strict JSON schema for `response_format`.
+
+        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 a `json_schema`
+        `response_format` requires.
+
+        Args:
+            model: The Pydantic model describing the structured output.
+
+        Returns:
+            A strict JSON-schema string embedded in the request body.
+        """
+        from openai.lib._pydantic import to_strict_json_schema
+
+        return json.dumps(to_strict_json_schema(model))
+
+    def result_text(self, raw: str) -> str:
+        """Return `choices[0].message.content` from the chat-completion response body."""
+        return json.loads(raw)["choices"][0]["message"]["content"]
+
+    def result_value(self, raw: str) -> object:
+        """Return the JSON value parsed from the message content, tolerating fences or surrounding prose."""
+        return json.loads(extract_json_block(self.result_text(raw)))
+
+    def envelope_error(self, raw: str) -> str | None:
+        """Return the message from an OpenAI `{"error": {...}}` body carried on a 2xx response, else `None`."""
+        match json.loads(raw):
+            case {"error": {"message": str(msg)}}:
+                return msg
+            case {"error": str(msg)}:
+                return msg
+            case _:
+                return None
+
+    def env(self, _spec: RunSpec) -> dict[str, str]:
+        """Return no extra environment variables; the endpoint is reached over HTTP with nothing to isolate."""
+        return {}
+
+    def is_authenticated(self, *, timeout: int) -> bool:
+        """Report `True`; credentials travel inline as the `Authorization` bearer token on every request."""
+        return True
+
+    def check_status(self, *, timeout: int = 10) -> BackendStatus:
+        """Report `BackendReady`; the endpoint is reached per-request and carries its own auth."""
+        return BackendReady(binary="openai_endpoint")

{spawnllm-0.5.5 → spawnllm-0.6.1}/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.5 → spawnllm-0.6.1}/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.5 → spawnllm-0.6.1}/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.5 → spawnllm-0.6.1}/spawnllm/types.py

@@ -12,5 +12,5 @@ TSpecialty = Literal["debugging", "review", "general"]
 TModel = Literal["small", "medium", "large"]
 """Abstract model tier; each backend maps it to a provider-specific model name."""
 
-ProviderName = Literal["claude", "codex", "gemini", "antigravity", "mlx"]
+ProviderName = Literal["claude", "codex", "gemini", "antigravity", "mlx", "openai_endpoint"]
 """Backend provider identifier; keys the per-backend `provider_configs` on a `RunSpec`."""