polyllmkit 0.2.0__tar.gz → 0.2.1__tar.gz

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "polyllmkit"
-version = "0.2.0"
+version = "0.2.1"
 description = "Streaming, multi-provider LLM bridge + markdown rendering toolkit for terminal apps."
 requires-python = ">=3.11"
 dependencies = []

{polyllmkit-0.2.0 → 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.2.0"
+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.

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

@@ -172,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
 

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

@@ -15,12 +15,14 @@ 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 Deadline, build_client
 from .config import Config, Provider
@@ -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 = ""
 
@@ -125,7 +127,7 @@ def with_defaults(provider: Provider) -> Provider:
 
 
 # ── 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).
@@ -139,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
@@ -157,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
@@ -221,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
 
 
@@ -309,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."""

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)