polyllmkit 0.1.2__tar.gz → 0.2.1__tar.gz

{polyllmkit-0.1.2 → polyllmkit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: polyllmkit
-Version: 0.1.2
+Version: 0.2.1
 Summary: Streaming, multi-provider LLM bridge + markdown rendering toolkit for terminal apps.
 Requires-Dist: openai>=1.0 ; extra == 'all'
 Requires-Dist: claude-agent-sdk>=0.2 ; extra == 'all'

{polyllmkit-0.1.2 → polyllmkit-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "polyllmkit"
-version = "0.1.2"
+version = "0.2.1"
 description = "Streaming, multi-provider LLM bridge + markdown rendering toolkit for terminal apps."
 requires-python = ">=3.11"
 dependencies = []
@@ -30,8 +30,13 @@ build-backend = "uv_build"
 module-root = "src"
 module-name = "llmkit"
 
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
 [dependency-groups]
 dev = [
     "ruff>=0.6",
     "mypy>=1.10",
+    "pytest>=9.2.0",
 ]

{polyllmkit-0.1.2 → polyllmkit-0.2.1}/pyproject.toml.orig

@@ -4,7 +4,7 @@
 # module-name below): consumers keep `import llmkit`, `pip install polyllmkit`.
 [project]
 name = "polyllmkit"
-version = "0.1.2"
+version = "0.2.1"
 description = "Streaming, multi-provider LLM bridge + markdown rendering toolkit for terminal apps."
 requires-python = ">=3.11"  # tomllib (bridge.config) is stdlib only from 3.11
 # Base install pulls nothing — pick the subpackage(s) you need via extras.
@@ -48,4 +48,11 @@ module-name = "llmkit"
 dev = [
     "ruff>=0.6",
     "mypy>=1.10",
+    "pytest>=9.2.0",
 ]
+
+# Resolve imports from the project venv (not an activated $VIRTUAL_ENV, which
+# may hold an older installed llmkit and shadow src/).
+[tool.pyright]
+venvPath = "."
+venv = ".venv"

polyllmkit-0.2.1/src/llmkit/bridge/_spawn.py

@@ -0,0 +1,178 @@
+"""Start child processes WITHOUT fork().
+
+Why: on macOS, once a process has used Apple's Network.framework (a host's
+DuckDB Quack client does, through its HTTP stack), the framework's fork handler
+(``nw_settings_child_has_forked``) segfaults the child of every later fork()
+before it can exec. llmkit is embedded in such hosts (cribsheet's daemon), so
+an adapter that launches a program — ``claude_code`` starting the ``claude``
+CLI — must never fork. posix_spawn runs no fork handlers.
+
+CPython takes the posix_spawn path only when the program is an explicit path,
+there is no ``cwd``, file descriptors are inherited (macOS has no posix_spawn
+closefrom), and none of preexec_fn / start_new_session / pass_fds / umask /
+process_group / user / group are set. :func:`open_process` arranges all of it:
+
+- the program is resolved to an absolute path (a missing one raises
+  FileNotFoundError, exactly as ``subprocess`` would);
+- ``close_fds=False``: safe, because Python's own fds are non-inheritable
+  (PEP 446);
+- a ``cwd`` is applied by ``/bin/sh`` (``cd``, then ``exec`` the program);
+- options that would force fork() are refused, not silently forked.
+
+The Claude Agent SDK spawns the CLI itself, through ``anyio.open_process``,
+which has no ``close_fds`` parameter and so always forks. :func:`cli_transport`
+returns an SDK transport whose ``connect`` routes that call (and the CLI version
+probe) through :func:`open_process` instead; any other user of the SDK in the
+same process is untouched.
+"""
+
+from __future__ import annotations
+
+import contextvars
+import errno
+import os
+import shutil
+from collections.abc import Sequence
+from subprocess import PIPE
+from typing import Any
+
+_SH = "/bin/sh"
+# $1 is the directory; the rest is the program and its arguments.
+_CD_EXEC = 'cd -- "$1" || exit 127; shift; exec "$@"'
+# Options that force CPython back onto fork(), with the default that doesn't
+# (anyio.open_process forwards several of these at their defaults).
+_FORK_FREE_DEFAULTS: dict[str, Any] = {
+    "preexec_fn": None,
+    "start_new_session": False,
+    "pass_fds": (),
+    "process_group": None,
+    "user": None,
+    "group": None,
+    "extra_groups": None,
+    "umask": -1,
+    "executable": None,
+    "startupinfo": None,
+    "creationflags": 0,
+}
+
+# Set while a :func:`cli_transport` is connecting: only then does the SDK's
+# ``anyio.open_process`` go through :func:`open_process`.
+_SPAWNING: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    "llmkit_spawning", default=False
+)
+
+
+def spawn_argv(
+    cmd: Sequence[str | os.PathLike[str]], cwd: str | os.PathLike[str] | None = None
+) -> list[str]:
+    """``cmd`` rewritten so CPython can posix_spawn it: an absolute program
+    path, and ``cwd`` (if any) applied by ``/bin/sh`` rather than by Popen."""
+    if not cmd:
+        raise ValueError("empty command")
+    args = [os.fspath(a) for a in cmd]
+    prog = args[0]
+    exe = prog if os.path.dirname(prog) else shutil.which(prog)
+    if exe is None:
+        raise FileNotFoundError(
+            errno.ENOENT, f"No such file or directory: {prog!r}", prog
+        )
+    exe = os.path.abspath(exe)
+    if cwd is None:
+        return [exe, *args[1:]]
+    d = os.fspath(cwd)
+    if not os.path.isdir(d):
+        raise FileNotFoundError(errno.ENOENT, f"No such directory: {d!r}", d)
+    return [_SH, "-c", _CD_EXEC, "llmkit", d, exe, *args[1:]]
+
+
+async def open_process(
+    command: Sequence[str | os.PathLike[str]],
+    *,
+    stdin: Any = PIPE,
+    stdout: Any = PIPE,
+    stderr: Any = PIPE,
+    cwd: str | os.PathLike[str] | None = None,
+    env: Any = None,
+    **kwargs: Any,
+) -> Any:
+    """``anyio.open_process``, spawned without fork(). Returns an
+    ``anyio.abc.Process``."""
+    if isinstance(command, (str, bytes)):
+        raise ValueError("llmkit spawn takes an argv sequence, not a shell string")
+    forking = sorted(
+        k
+        for k, v in kwargs.items()
+        if k not in _FORK_FREE_DEFAULTS or v != _FORK_FREE_DEFAULTS[k]
+    )
+    if forking:
+        raise ValueError(f"llmkit spawn refuses options that force fork(): {forking}")
+    # anyio.open_process can't pass close_fds; its backend forwards any kwarg
+    # to Popen (asyncio and trio alike). Not re-exported publicly by anyio.
+    from anyio._core._eventloop import get_async_backend
+
+    return await get_async_backend().open_process(
+        spawn_argv(command, cwd),
+        stdin=stdin,
+        stdout=stdout,
+        stderr=stderr,
+        env=env,
+        close_fds=False,
+    )
+
+
+class _AnyioProxy:
+    """Stands in for ``anyio`` inside the SDK's transport module: everything
+    passes through, except ``open_process`` while a spawn transport connects."""
+
+    def __init__(self, real: Any) -> None:
+        self._real = real
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._real, name)
+
+    async def open_process(self, command: Any, **kwargs: Any) -> Any:
+        if _SPAWNING.get():
+            return await open_process(command, **kwargs)
+        return await self._real.open_process(command, **kwargs)
+
+
+_transport_cls: Any = None
+# The SDK transport module's `import anyio` binding.
+_SDK_ANYIO = "anyio"
+
+
+def _spawn_transport_cls() -> Any:
+    global _transport_cls
+    if _transport_cls is not None:
+        return _transport_cls
+    from claude_agent_sdk._internal.transport import subprocess_cli as sc
+
+    if not hasattr(sc, _SDK_ANYIO) or not hasattr(sc, "SubprocessCLITransport"):
+        raise RuntimeError(
+            "llmkit: claude_agent_sdk's subprocess transport changed shape; "
+            "can't guarantee a fork-free CLI launch"
+        )
+    # The module's own `import anyio` binding, swapped for the proxy (attribute
+    # access by name: it isn't a re-export).
+    real = getattr(sc, _SDK_ANYIO)
+    if not isinstance(real, _AnyioProxy):
+        setattr(sc, _SDK_ANYIO, _AnyioProxy(real))
+
+    class SpawnCLITransport(sc.SubprocessCLITransport):  # type: ignore[misc, name-defined]
+        """The SDK's CLI transport, launching the CLI with posix_spawn."""
+
+        async def connect(self) -> None:
+            token = _SPAWNING.set(True)
+            try:
+                await super().connect()
+            finally:
+                _SPAWNING.reset(token)
+
+    _transport_cls = SpawnCLITransport
+    return _transport_cls
+
+
+def cli_transport(prompt: Any, options: Any) -> Any:
+    """A Claude Agent SDK transport for ``sdk.query(..., transport=...)`` that
+    starts the ``claude`` CLI without fork()."""
+    return _spawn_transport_cls()(prompt=prompt, options=options)

{polyllmkit-0.1.2 → polyllmkit-0.2.1}/src/llmkit/bridge/adapters/anthropic.py

@@ -33,7 +33,7 @@ from typing import Any, Optional
 from urllib.parse import urlsplit, urlunsplit
 
 from ..bridge import DEFAULT_ENDPOINT, ChatRequest, _Emitter
-from ..client import resolved_headers
+from ..client import Deadline, resolved_headers, timeout_kwargs
 from ..config import Provider
 
 
@@ -102,6 +102,7 @@ def stream_anthropic(
 
     kwargs: dict[str, Any] = dict(
         api_key=_resolve_api_key(provider),
+        **timeout_kwargs(provider),
     )
     # The bridge fills endpoint with the openai/ollama default; only forward an
     # endpoint the user actually customised (an Anthropic-compatible gateway),
@@ -137,8 +138,10 @@ def stream_anthropic(
     else:
         create["thinking"] = _thinking_config(provider.enable_thinking)
 
+    deadline = Deadline(provider.timeout)
     with client.messages.stream(**create) as stream:
         for event in stream:
+            deadline.check()
             # Any event is a sign of life — fire TTFT before the first non-empty
             # delta (mirrors the openai adapter's explicit signal).
             emitter.signal_streaming()

{polyllmkit-0.1.2 → polyllmkit-0.2.1}/src/llmkit/bridge/adapters/claude_code.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 import os
 from typing import Any
 
+from .._spawn import cli_transport
 from ..bridge import ChatRequest, _Emitter
 from ..config import Provider
 
@@ -131,7 +132,16 @@ def stream_claude_code(
     sdk = _require_sdk()
     import anyio  # bundled with the SDK
 
-    anyio.run(_run, sdk, provider, request, emitter)
+    anyio.run(_bounded, provider.timeout, _run(sdk, provider, request, emitter))
+
+
+async def _bounded(timeout: float | None, coro: Any) -> None:
+    """Await ``coro``, cancelling it after ``timeout`` seconds (TimeoutError).
+    Cancellation unwinds the SDK's query, which terminates the CLI."""
+    import anyio
+
+    with anyio.fail_after(timeout):
+        await coro
 
 
 async def _run(
@@ -139,7 +149,10 @@ async def _run(
 ) -> None:
     options = _build_options(sdk, provider, request)
     saw_delta = False
-    async for message in sdk.query(prompt=request.user, options=options):
+    transport = cli_transport(request.user, options)
+    async for message in sdk.query(
+        prompt=request.user, options=options, transport=transport
+    ):
         if isinstance(message, sdk.StreamEvent):
             if _handle_event(message.event, emitter):
                 saw_delta = True
@@ -159,9 +172,10 @@ def structured_claude_code(
     """Structured output via the SDK's native ``output_format`` (set in
     ``_build_options`` when the request carries a schema). Runs the single-turn
     query and returns ``(exit_code, structured_output)`` from the ResultMessage —
-    the parsed object matching the schema, or ``(0, None)`` if the model produced
-    none, or ``(1, None)`` on an SDK-reported error. No text parsing: the CLI does
-    the schema enforcement + JSON parse and hands back a Python object."""
+    the parsed object matching the schema, ``(0, None)`` if the model produced
+    none (``chat_structured`` turns that into a failure), or ``(1, None)`` on an
+    SDK-reported error. No text parsing: the CLI does the schema enforcement +
+    JSON parse and hands back a Python object."""
     sdk = _require_sdk()
     import anyio  # bundled with the SDK
 
@@ -169,10 +183,13 @@ def structured_claude_code(
 
     async def _run_structured() -> None:
         options = _build_options(sdk, provider, request)
-        async for message in sdk.query(prompt=request.user, options=options):
+        transport = cli_transport(request.user, options)
+        async for message in sdk.query(
+            prompt=request.user, options=options, transport=transport
+        ):
             if isinstance(message, sdk.ResultMessage):
                 out["data"] = getattr(message, "structured_output", None)
                 out["error"] = bool(getattr(message, "is_error", False))
 
-    anyio.run(_run_structured)
+    anyio.run(_bounded, provider.timeout, _run_structured())
     return (1 if out["error"] else 0), out["data"]

{polyllmkit-0.1.2 → polyllmkit-0.2.1}/src/llmkit/bridge/adapters/google.py

@@ -23,7 +23,7 @@ import os
 from typing import Any, Optional
 
 from ..bridge import DEFAULT_ENDPOINT, ChatRequest, _Emitter
-from ..client import resolved_headers
+from ..client import Deadline, resolved_headers
 from ..config import Provider
 
 
@@ -76,6 +76,8 @@ def stream_google(provider: Provider, request: ChatRequest, emitter: _Emitter) -
     headers = resolved_headers(provider)
     if headers:
         http_opts["headers"] = headers
+    if provider.timeout is not None:
+        http_opts["timeout"] = int(provider.timeout * 1000)  # milliseconds
     if http_opts:
         client_kwargs["http_options"] = types.HttpOptions(**http_opts)
     client = genai.Client(**client_kwargs)
@@ -87,9 +89,11 @@ def stream_google(provider: Provider, request: ChatRequest, emitter: _Emitter) -
         thinking_config=_thinking_config(types, provider.enable_thinking),
     )
 
+    deadline = Deadline(provider.timeout)
     for chunk in client.models.generate_content_stream(
         model=provider.model, contents=request.user, config=config
     ):
+        deadline.check()
         emitter.signal_streaming()
         for candidate in getattr(chunk, "candidates", None) or []:
             content = getattr(candidate, "content", None)

{polyllmkit-0.1.2 → polyllmkit-0.2.1}/src/llmkit/bridge/adapters/openai.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from ..client import build_client, enable_thinking_extra
+from ..client import Deadline, build_client, enable_thinking_extra
 from ..config import Provider
 
 # Imported under TYPE_CHECKING-free runtime: bridge imports this lazily, so a
@@ -42,7 +42,9 @@ def stream_openai(provider: Provider, request: ChatRequest, emitter: _Emitter) -
         kwargs.pop("extra_body", None)
     kwargs["stream"] = True
 
+    deadline = Deadline(provider.timeout)
     for chunk in client.chat.completions.create(**kwargs):
+        deadline.check()
         if not chunk.choices:
             continue
         # Fire "streaming" on the FIRST chunk that has choices — even a

{polyllmkit-0.1.2 → polyllmkit-0.2.1}/src/llmkit/bridge/bridge.py

@@ -15,14 +15,16 @@ failure semantics. ``complete`` (FIM) remains ``openai-compatible``-only.
 
 from __future__ import annotations
 
+import contextlib
 import dataclasses
 import io
 import os
 import sys
+from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any, Callable, Optional, TextIO
+from typing import Any, TextIO
 
-from .client import build_client
+from .client import Deadline, build_client
 from .config import Config, Provider
 from .sinks import close_sink, open_target
 from .stream import StreamSplitter
@@ -43,7 +45,7 @@ ADAPTERS = ("openai-compatible", "anthropic", "google", "claude_code")
 _COMPLETE_ADAPTERS = frozenset({"openai-compatible"})
 
 
-def adapter_supports_complete(adapter: Optional[str]) -> bool:
+def adapter_supports_complete(adapter: str | None) -> bool:
     """Whether ``adapter`` (``None`` → the default) can serve ``complete`` (FIM).
 
     Queryable up front so a consumer can disable a FIM keybinding / widget for
@@ -84,9 +86,9 @@ class ChatRequest:
     """
 
     user: str
-    system: Optional[str] = None
-    enable_thinking: Optional[str] = None
-    schema: Optional[dict] = None
+    system: str | None = None
+    enable_thinking: str | None = None
+    schema: dict | None = None
     schema_name: str = "emit"
     schema_description: str = ""
 
@@ -119,12 +121,13 @@ def with_defaults(provider: Provider) -> Provider:
         enable_thinking=provider.enable_thinking or "auto",
         stop=provider.stop,
         headers=provider.headers,
+        timeout=provider.timeout,
         extra=provider.extra,
     )
 
 
 # ── status events ───────────────────────────────────────────────────────────
-def _open_status(path: str) -> Optional[TextIO]:
+def _open_status(path: str) -> TextIO | None:
     """Open a status file (regular file OR fifo) for line-buffered writes.
     O_RDWR | O_APPEND | O_NONBLOCK so it works against either kind without
     blocking on fifo connect (and without truncating regular files).
@@ -138,7 +141,7 @@ def _open_status(path: str) -> Optional[TextIO]:
         return None
 
 
-def _write_status(fp: Optional[TextIO], event: str) -> None:
+def _write_status(fp: TextIO | None, event: str) -> None:
     """Best-effort status line write. Never raises."""
     if fp is None:
         return
@@ -156,7 +159,7 @@ class _Emitter:
     :meth:`signal_streaming` directly when a chunk arrives that carries
     neither."""
 
-    def __init__(self, splitter: StreamSplitter, status_fp: Optional[TextIO]) -> None:
+    def __init__(self, splitter: StreamSplitter, status_fp: TextIO | None) -> None:
         self._splitter = splitter
         self._status_fp = status_fp
         self._started = False
@@ -220,17 +223,13 @@ def _run_chat(
     finally:
         # ALWAYS flush — interrupts and exceptions still get the close wrap
         # emitted, so downstream readers see a complete document.
-        try:
+        with contextlib.suppress(Exception):
             splitter.finish()
-        except Exception:
-            pass
         close_sink(content_sink)
         close_sink(thinking_sink)
         if status_fp is not None:
-            try:
+            with contextlib.suppress(OSError):
                 status_fp.close()
-            except OSError:
-                pass
     return rc
 
 
@@ -308,31 +307,45 @@ def chat_structured(
     status_file: str = "",
 ) -> tuple[int, Any]:
     """Structured output: for a ``request`` carrying a ``schema``, capture the
-    model's schema-filled JSON and return ``(exit_code, parsed)``. Returns
-    ``(code, None)`` on a non-zero exit or unparseable output — the caller
-    decides whether to fall back. Thinking is off (forced tool-use excludes it)."""
-    import json
+    model's schema-filled JSON and return ``(exit_code, parsed)``. A non-zero
+    code always comes with ``None``, and ``0`` always comes with an object that
+    fits the schema: a reply with no usable JSON is a failure (code 1, reason
+    on stderr), never a silent success. The reply is parsed leniently (see
+    :mod:`llmkit.bridge.structured`) because an openai-compatible server may
+    ignore ``response_format`` and answer in fenced prose. Thinking is off
+    (forced tool-use excludes it)."""
+    from .structured import StructuredOutputError, conform, parse_structured
 
     # claude_code enforces the schema via the SDK's native output_format and returns
     # a parsed object in ResultMessage.structured_output — no text round-trip.
     if provider.adapter == "claude_code":
         from .adapters.claude_code import structured_claude_code
-        return structured_claude_code(with_defaults(provider), request)
+        code, data = structured_claude_code(with_defaults(provider), request)
+        if code != 0:
+            return code, None
+        try:
+            if data is None:
+                raise StructuredOutputError("the CLI returned no structured_output")
+            return 0, conform(data, request.schema)
+        except StructuredOutputError as e:
+            print(f"llmkit: structured output: {e}", file=sys.stderr)
+            return 1, None
 
     code, text = chat_to_str(provider, request, thinking="none", status_file=status_file)
     if code != 0:
         return code, None
     try:
-        return code, json.loads(text)
-    except (ValueError, TypeError):
-        return code, None
+        return 0, parse_structured(text, request.schema)
+    except StructuredOutputError as e:
+        print(f"llmkit: structured output: {e}", file=sys.stderr)
+        return 1, None
 
 
 def complete(
     provider: Provider,
     request: CompleteRequest,
     *,
-    out: Optional[TextIO] = None,
+    out: TextIO | None = None,
 ) -> int:
     """Run a text-completion (FIM) request, streaming text to ``out``
     (default stdout). ``openai-compatible`` only."""
@@ -360,8 +373,10 @@ def complete(
     if request.stop:
         kwargs["stop"] = list(request.stop)
     kwargs["stream"] = True
+    deadline = Deadline(provider.timeout)
     try:
         for chunk in client.completions.create(**kwargs):
+            deadline.check()
             t = chunk.choices[0].text if chunk.choices else ""
             if t:
                 sink.write(t)

{polyllmkit-0.1.2 → polyllmkit-0.2.1}/src/llmkit/bridge/cli.py

@@ -45,6 +45,14 @@ def _add_common(s: argparse.ArgumentParser) -> None:
         "escape for a literal $). Use for gateway routing keys the SDK won't "
         "set (e.g. --header x-opencode-request=zsh-ai for OpenCode Zen).",
     )
+    s.add_argument(
+        "--timeout",
+        type=float,
+        default=None,
+        metavar="SECONDS",
+        help="bound the whole call: connect, each read, and a total deadline "
+        "across the stream (default: the SDK's own, 600 s per read)",
+    )
     s.add_argument(
         "--adapter",
         choices=["openai-compatible", "claude_code", "anthropic", "google"],
@@ -85,6 +93,7 @@ def _provider_from_args(args: argparse.Namespace) -> Provider:
         max_tokens=args.max_tokens,
         temperature=args.temperature,
         headers=_parse_headers(args.header),
+        timeout=args.timeout,
     )
 
 

{polyllmkit-0.1.2 → polyllmkit-0.2.1}/src/llmkit/bridge/client.py

@@ -64,9 +64,33 @@ def build_client(provider: Provider) -> Any:
         base_url=provider.endpoint,
         api_key=_resolve_api_key(provider),
         default_headers=resolved_headers(provider),
+        **timeout_kwargs(provider),
     )
 
 
+def timeout_kwargs(provider: Provider) -> Dict[str, Any]:
+    """Client kwargs for the openai/anthropic SDKs: ``timeout`` (connect and
+    each socket read) and no SDK retries, so a retry can't silently restart
+    the clock past the caller's budget. Empty when no timeout is set."""
+    if provider.timeout is None:
+        return {}
+    return {"timeout": provider.timeout, "max_retries": 0}
+
+
+class Deadline:
+    """A total wall-clock budget for one call, checked between stream chunks.
+    The SDK's per-read timeout catches a stalled read; this catches a stream
+    that keeps trickling past the budget. ``None`` never expires."""
+
+    def __init__(self, seconds: Optional[float]) -> None:
+        self._seconds = seconds
+        self._end = None if seconds is None else time.monotonic() + seconds
+
+    def check(self) -> None:
+        if self._end is not None and time.monotonic() > self._end:
+            raise TimeoutError(f"no complete response within {self._seconds:g}s")
+
+
 def _resolve_api_key(provider: Provider) -> str:
     if provider.api_key_env:
         return os.environ.get(provider.api_key_env, "") or "placeholder"

{polyllmkit-0.1.2 → polyllmkit-0.2.1}/src/llmkit/bridge/config.py

@@ -51,6 +51,7 @@ _PROVIDER_FIELDS = frozenset(
         "enable_thinking",
         "stop",
         "headers",
+        "timeout",
     }
 )
 
@@ -140,6 +141,13 @@ class Provider:
     # OpenCode Zen's ``x-opencode-request``, which its qwen pool requires (absent
     # it, zen 503s ``failover_exhausted``). Merges per-key over ``[defaults]``.
     headers: Mapping[str, str] = field(default_factory=dict)
+    # Seconds. Bounds one call end to end: the HTTP adapters pass it to the SDK
+    # client (connect, and each socket read — so a stalled stream raises) and
+    # also check it as a total deadline between stream chunks (so a slow
+    # trickle is bounded too); claude_code cancels the CLI run when it expires.
+    # A stalled read can overshoot the deadline by up to one more ``timeout``.
+    # ``None`` leaves each SDK's own default (openai/anthropic: 600 s per read).
+    timeout: Optional[float] = None
     # Forward-compat passthrough for unknown [providers.*] keys.
     extra: Mapping[str, "TomlValue"] = field(default_factory=dict)
 
@@ -160,6 +168,7 @@ class Provider:
             enable_thinking=_normalise_thinking(raw.get("enable_thinking")),
             stop=_as_stop(raw.get("stop")),
             headers=_as_headers(raw.get("headers")),
+            timeout=_opt_float(raw.get("timeout")),
             extra=cast("Mapping[str, TomlValue]", extra),
         )
 

polyllmkit-0.2.1/src/llmkit/bridge/structured.py

@@ -0,0 +1,120 @@
+"""Recover a schema-shaped object from a model's structured-output reply.
+
+Adapters ask for structured output natively (``response_format`` for
+openai-compatible, a forced tool for anthropic, ``output_format`` for
+claude_code), but an openai-compatible server is free to ignore
+``response_format``: e.g. GLM at ollama.com answers in ordinary content, with
+the JSON fenced in ````` ```json ````` and missing the schema's wrapper object
+(a bare ``[...]`` where the schema says ``{"symbols": [...]}``). So the reply
+is parsed leniently here, then checked against the schema, and any failure
+raises :class:`StructuredOutputError` with the reason. Callers must never
+mistake "nothing usable came back" for success.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+_FENCE = re.compile(r"```[A-Za-z0-9_-]*[ \t]*\n(.*?)\n?```", re.DOTALL)
+_TYPES: dict[str, tuple[type, ...]] = {
+    "object": (dict,),
+    "array": (list,),
+    "string": (str,),
+    "integer": (int,),
+    "number": (int, float),
+    "boolean": (bool,),
+    "null": (type(None),),
+}
+
+
+class StructuredOutputError(ValueError):
+    """The reply held no JSON matching the requested schema."""
+
+
+def extract_json(text: str) -> Any:
+    """The JSON value in ``text``: the whole text, else the first fenced code
+    block that parses, else the first ``{``/``[`` value found in prose."""
+    s = text.strip()
+    if not s:
+        raise StructuredOutputError("empty reply")
+    try:
+        return json.loads(s)
+    except ValueError:
+        pass
+    for m in _FENCE.finditer(s):
+        try:
+            return json.loads(m.group(1))
+        except ValueError:
+            continue
+    dec = json.JSONDecoder()
+    for i, ch in enumerate(s):
+        if ch in "{[":
+            try:
+                return dec.raw_decode(s, i)[0]
+            except ValueError:
+                continue
+    raise StructuredOutputError(f"no JSON value in reply: {s[:120]!r}")
+
+
+def _sole_array_property(schema: dict[str, Any]) -> str | None:
+    """The one array-typed property of an object schema, if it has exactly
+    one property (or exactly one required one) and that property is an array."""
+    props = schema.get("properties") or {}
+    required = schema.get("required") or []
+    names = list(props) if len(props) == 1 else list(required)
+    if len(names) == 1 and (props.get(names[0]) or {}).get("type") == "array":
+        return names[0]
+    return None
+
+
+def _check(value: Any, schema: dict[str, Any], path: str) -> None:
+    """A JSON Schema subset: type, enum, required, properties, items. Enough to
+    tell a schema-shaped reply from a wrong one, without a jsonschema dep."""
+    t = schema.get("type")
+    types = [t] if isinstance(t, str) else (t or [])
+    if types:
+        ok = any(
+            isinstance(value, _TYPES.get(name, ()))
+            # bool is an int subclass; JSON keeps them apart.
+            and not (isinstance(value, bool) and name in ("integer", "number"))
+            for name in types
+        )
+        if not ok:
+            raise StructuredOutputError(
+                f"{path or 'reply'}: expected {'/'.join(types)}, "
+                f"got {type(value).__name__}"
+            )
+    if "enum" in schema and value not in schema["enum"]:
+        raise StructuredOutputError(f"{path or 'reply'}: {value!r} not in enum")
+    if isinstance(value, dict):
+        for key in schema.get("required") or []:
+            if key not in value:
+                raise StructuredOutputError(f"{path or 'reply'}: missing {key!r}")
+        for key, sub in (schema.get("properties") or {}).items():
+            if key in value and isinstance(sub, dict):
+                _check(value[key], sub, f"{path}.{key}" if path else key)
+    if isinstance(value, list) and isinstance(schema.get("items"), dict):
+        for i, item in enumerate(value):
+            _check(item, schema["items"], f"{path}[{i}]")
+
+
+def conform(value: Any, schema: dict[str, Any] | None) -> Any:
+    """``value`` checked against ``schema``. A bare array where the schema is an
+    object with a single array property is wrapped into that property first
+    (the shape models produce when they skip the wrapper). Raises
+    :class:`StructuredOutputError` if it still doesn't fit."""
+    if not schema:
+        return value
+    if isinstance(value, list) and schema.get("type") == "object":
+        key = _sole_array_property(schema)
+        if key is not None:
+            value = {key: value}
+    _check(value, schema, "")
+    return value
+
+
+def parse_structured(text: str, schema: dict[str, Any] | None) -> Any:
+    """Parse a structured-output reply and check it against ``schema``."""
+    return conform(extract_json(text), schema)