polyllmkit 0.1.2__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: polyllmkit
-Version: 0.1.2
+Version: 0.2.0
 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.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "polyllmkit"
-version = "0.1.2"
+version = "0.2.0"
 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.0}/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.0"
 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.0/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.0}/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.0}/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
@@ -169,10 +182,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.0}/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.0}/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.0}/src/llmkit/bridge/bridge.py

@@ -22,7 +22,7 @@ import sys
 from dataclasses import dataclass
 from typing import Any, Callable, Optional, 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
@@ -119,6 +119,7 @@ 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,
     )
 
@@ -360,8 +361,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.0}/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.0}/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.0}/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),
         )