turnloop 0.1.0__py3-none-any.whl

turnloop/providers/openai_compat.py

@@ -0,0 +1,357 @@
+"""OpenAI Chat Completions adapter.
+
+Covers OpenAI itself, Groq, Together, Ollama, LM Studio, and any vLLM server —
+including the self-hosted GLM-5.2 this project targets. The GLM specifics are a
+constructor flag rather than a subclass, because there is exactly one behavioral
+difference on the wire: reasoning arrives in `reasoning_content` instead of
+`content`, courtesy of vLLM's `--reasoning-parser glm45`.
+
+Two wire-format facts drive the code below.
+
+1. `is_error` has no representation in this API. A tool result is just a string
+   in a `role: "tool"` message. So an error result is prefixed with "Error: " —
+   that text is the *only* signal the model receives, and dropping it makes
+   models retry blindly.
+
+2. Tool arguments stream as fragments of a JSON string across many deltas,
+   keyed by `index`, and `id`/`name` appear only on the first fragment. Nothing
+   is parseable until the choice finishes.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+
+import httpx
+
+from turnloop.core.events import (
+    MessageDone,
+    ProviderStatus,
+    StreamEvent,
+    TextDelta,
+    ThinkingDelta,
+    ToolUseArgsDelta,
+    ToolUseStart,
+)
+from turnloop.core.ids import new_id
+from turnloop.core.messages import (
+    ContentBlock,
+    Message,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    Usage,
+)
+from turnloop.providers.base import (
+    CompletionRequest,
+    Provider,
+    classify_error,
+    parse_retry_after,
+    raise_for_class,
+)
+from turnloop.providers.sse import iter_sse
+
+_STOP_REASONS = {
+    "stop": "end_turn",
+    "length": "max_tokens",
+    "tool_calls": "tool_use",
+    "function_call": "tool_use",
+    "content_filter": "refusal",
+}
+
+
+class OpenAICompatProvider(Provider):
+    kind = "openai_compat"
+
+    def __init__(self, *args, glm_reasoning: bool = False, extra_body: dict | None = None,
+                 **kwargs):
+        super().__init__(*args, **kwargs)
+        self.glm_reasoning = glm_reasoning
+        self.extra_body = extra_body or {}
+
+    def headers(self) -> dict[str, str]:
+        h = super().headers()
+        # vLLM on Modal is unauthenticated, but sending a bearer token is
+        # harmless and keeps one code path for every OpenAI-compatible endpoint.
+        if self.api_key:
+            h["authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    # --- request construction ---------------------------------------------
+
+    def build_payload(self, req: CompletionRequest) -> dict:
+        payload: dict = {
+            "model": self.model,
+            "messages": self.to_wire_messages(req),
+            "stream": True,
+            # Ask for usage on the final chunk. Standard OpenAI, honored by vLLM.
+            "stream_options": {"include_usage": True},
+        }
+        if req.max_tokens or self.caps.max_output:
+            payload["max_tokens"] = req.max_tokens or self.caps.max_output
+        if req.temperature is not None and self.caps.supports_temperature:
+            payload["temperature"] = req.temperature
+        if req.stop_sequences:
+            payload["stop"] = req.stop_sequences
+        if req.tools:
+            payload["tools"] = [t.to_openai() for t in req.tools]
+            if self.caps.supports_tool_choice:
+                payload["tool_choice"] = (
+                    "required" if req.tool_choice == "required" else req.tool_choice
+                )
+        payload.update(self.extra_body)
+        return payload
+
+    def to_wire_messages(self, req: CompletionRequest) -> list[dict]:
+        out: list[dict] = []
+        system_text = "\n\n".join(s for s in req.system if s.strip())
+        if system_text:
+            role = "system" if self.caps.supports_system_role else "user"
+            out.append({"role": role, "content": system_text})
+
+        for msg in req.messages:
+            if msg.role == "user":
+                out.extend(self._user_to_wire(msg))
+            else:
+                wire = self._assistant_to_wire(msg)
+                if wire:
+                    out.append(wire)
+        return out
+
+    def _user_to_wire(self, msg: Message) -> list[dict]:
+        """Split a user message into tool results plus any remaining text.
+
+        Tool results must each become their own `role: "tool"` message, and they
+        have to precede any user text in the same turn or providers complain
+        about a tool_call without a matching response.
+        """
+        tool_msgs = [
+            {
+                "role": "tool",
+                "tool_call_id": b.tool_use_id,
+                "content": (f"Error: {b.content}" if b.is_error else b.content) or "(no output)",
+            }
+            for b in msg.content
+            if isinstance(b, ToolResultBlock)
+        ]
+        text = "".join(b.text for b in msg.content if isinstance(b, TextBlock)).strip()
+        if text:
+            tool_msgs.append({"role": "user", "content": text})
+        return tool_msgs
+
+    def _assistant_to_wire(self, msg: Message) -> dict | None:
+        text = "".join(b.text for b in msg.content if isinstance(b, TextBlock))
+        calls = [
+            {
+                "id": b.id,
+                "type": "function",
+                "function": {"name": b.name, "arguments": json.dumps(b.args)},
+            }
+            for b in msg.content
+            if isinstance(b, ToolUseBlock)
+        ]
+        # Thinking is never sent back. There is no signature to verify, the API
+        # has no field for it, and on a 65k window it is pure overhead.
+        if not text and not calls:
+            return None
+        wire: dict = {"role": "assistant", "content": text or None}
+        if calls:
+            wire["tool_calls"] = calls
+        return wire
+
+    # --- streaming --------------------------------------------------------
+
+    async def _stream_once(self, req: CompletionRequest) -> AsyncIterator[StreamEvent]:
+        url = f"{self.base_url}/chat/completions"
+        payload = self.build_payload(req)
+        bytes_seen = 0
+
+        acc = _Accumulator(glm_reasoning=self.glm_reasoning)
+        try:
+            async with self.client.stream(
+                "POST", url, json=payload, headers=self.headers()
+            ) as resp:
+                if resp.status_code >= 400:
+                    body = (await resp.aread()).decode("utf-8", errors="replace")
+                    raise_for_class(
+                        classify_error(None, resp, body=body),
+                        f"{self.name}: HTTP {resp.status_code} {_brief(body)}",
+                        status=resp.status_code,
+                        body=body,
+                        retry_after=parse_retry_after(resp),
+                    )
+
+                async for frame in iter_sse(resp.aiter_lines()):
+                    bytes_seen += len(frame.data)
+                    if frame.is_done:
+                        break
+                    chunk = frame.json()
+                    if chunk is None:
+                        continue
+                    if err := chunk.get("error"):
+                        raise_for_class("fatal", f"{self.name}: {err}", body=json.dumps(err))
+                    for event in acc.feed(chunk):
+                        yield event
+        except (httpx.HTTPError, httpx.StreamError) as exc:
+            kind = classify_error(exc, None, bytes_seen)
+            if kind == "cold_boot":
+                # Surface as retryable so Provider.stream backs off and the next
+                # attempt re-runs preflight, which is what actually waits it out.
+                yield ProviderStatus(f"{self.name}: endpoint not answering", phase="cold_boot")
+            raise_for_class(
+                "fatal" if kind == "fatal" else "retryable", f"{self.name}: {type(exc).__name__}: {exc}"
+            )
+
+        yield acc.finish(self.name, self.model)
+
+
+class _Accumulator:
+    """Turns a sequence of chat-completion chunks into events plus a Message."""
+
+    def __init__(self, glm_reasoning: bool = False):
+        self.glm_reasoning = glm_reasoning
+        self.text: list[str] = []
+        self.thinking: list[str] = []
+        # index -> {"id", "name", "args"}
+        self.calls: dict[int, dict] = {}
+        self.stop_reason: str | None = None
+        self.usage = Usage()
+        self._started: set[int] = set()
+
+    def feed(self, chunk: dict) -> list[StreamEvent]:
+        events: list[StreamEvent] = []
+
+        if usage := chunk.get("usage"):
+            self.usage = _usage_from(usage)
+
+        for choice in chunk.get("choices") or []:
+            delta = choice.get("delta") or {}
+
+            # Reasoning first: vLLM's glm45 parser emits it as a sibling of
+            # `content`, and a chunk can legitimately carry both.
+            reasoning = delta.get("reasoning_content") or delta.get("reasoning")
+            if reasoning:
+                self.thinking.append(reasoning)
+                events.append(ThinkingDelta(reasoning))
+
+            if content := delta.get("content"):
+                self.text.append(content)
+                events.append(TextDelta(content))
+
+            # NVIDIA NIM's z-ai/glm-5.2 sends id, function.name, and the full
+            # function.arguments string fully formed in a single delta,
+            # immediately followed by finish_reason: "tool_calls" — unlike
+            # self-hosted vLLM's glm45 parser, which fragments arguments
+            # across chunks. No special casing needed: accumulating one
+            # fragment yields the same string as accumulating many.
+            for tc in delta.get("tool_calls") or []:
+                events.extend(self._feed_tool_call(tc))
+
+            if fr := choice.get("finish_reason"):
+                self.stop_reason = _STOP_REASONS.get(fr, "end_turn")
+
+        return events
+
+    def _feed_tool_call(self, tc: dict) -> list[StreamEvent]:
+        index = tc.get("index", 0)
+        slot = self.calls.setdefault(index, {"id": "", "name": "", "args": ""})
+
+        if tc.get("id"):
+            slot["id"] = tc["id"]
+        fn = tc.get("function") or {}
+        if fn.get("name"):
+            slot["name"] = fn["name"]
+
+        events: list[StreamEvent] = []
+        if index not in self._started and slot["name"]:
+            self._started.add(index)
+            if not slot["id"]:
+                # Some servers omit ids entirely; the loop needs one to pair the
+                # result back, so synthesize a stable one.
+                slot["id"] = new_id("call")
+            events.append(ToolUseStart(index=index, id=slot["id"], name=slot["name"]))
+
+        if (fragment := fn.get("arguments")) is not None:
+            slot["args"] += fragment
+            if fragment:
+                events.append(ToolUseArgsDelta(index=index, fragment=fragment))
+        return events
+
+    def finish(self, provider: str, model: str) -> MessageDone:
+        blocks: list[ContentBlock] = []
+        if thinking := "".join(self.thinking):
+            blocks.append(
+                ThinkingBlock(text=thinking, provider=f"{provider}:reasoning_content")
+            )
+        if text := "".join(self.text):
+            blocks.append(TextBlock(text=text))
+
+        for index in sorted(self.calls):
+            slot = self.calls[index]
+            if not slot["name"]:
+                continue
+            blocks.append(
+                ToolUseBlock(
+                    id=slot["id"] or new_id("call"),
+                    name=slot["name"],
+                    args=_parse_args(slot["args"]),
+                )
+            )
+
+        stop = self.stop_reason or ("tool_use" if self.calls else "end_turn")
+        # A model that emits tool calls but finish_reason "stop" (seen on some
+        # vLLM builds) still needs the loop to run the tools.
+        if self.calls and stop == "end_turn":
+            stop = "tool_use"
+
+        msg = Message(
+            role="assistant",
+            content=blocks,
+            usage=self.usage,
+            stop_reason=stop,  # type: ignore[arg-type]
+            meta={"provider": provider, "model": model},
+        )
+        return MessageDone(message=msg, usage=self.usage, stop_reason=stop)
+
+
+def _parse_args(raw: str) -> dict:
+    """Parse accumulated argument JSON, tolerating the ways models get it wrong.
+
+    A failure here is not an exception: it becomes `{}` plus a `_raw` field, and
+    schema validation in ToolRunner produces an error result the model can read
+    and correct. Counting these is precisely the tool-calling-reliability metric.
+    """
+    raw = (raw or "").strip()
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        # A truncated stream often leaves valid JSON one brace short.
+        for suffix in ('"}', "}", "]}", '"}]}'):
+            try:
+                parsed = json.loads(raw + suffix)
+                break
+            except json.JSONDecodeError:
+                continue
+        else:
+            return {"_raw": raw, "_parse_error": "arguments were not valid JSON"}
+    if isinstance(parsed, dict):
+        return parsed
+    return {"_raw": raw, "_parse_error": "arguments were not a JSON object"}
+
+
+def _usage_from(u: dict) -> Usage:
+    details = u.get("prompt_tokens_details") or {}
+    return Usage(
+        input_tokens=u.get("prompt_tokens", 0) or 0,
+        output_tokens=u.get("completion_tokens", 0) or 0,
+        cache_read_tokens=details.get("cached_tokens", 0) or 0,
+    )
+
+
+def _brief(body: str, limit: int = 400) -> str:
+    body = " ".join(body.split())
+    return body if len(body) <= limit else body[:limit] + "…"

turnloop/providers/pricing.py

@@ -0,0 +1,148 @@
+"""Capability and price presets per model.
+
+Prices are USD per million tokens, as published at the time of writing. They are
+data, not truth: `settings.json` can override any field, and a wrong number here
+only skews the cost column, never behavior.
+
+`glm-5.2` is the interesting entry. It has no token price at all — it is
+self-hosted on 4xH200 and billed by wall clock, so `cost_per_hour` carries the
+cost and `max_concurrent_requests` mirrors the server's `--max-num-seqs 16`.
+"""
+
+from __future__ import annotations
+
+from turnloop.providers.base import Capabilities
+
+_CLAUDE_COMMON = {
+    "max_context": 200_000,
+    "supports_prompt_caching": True,
+    "supports_parallel_tool_calls": True,
+    "native_thinking": True,
+    "price_cache_read_per_mtok": 0.0,  # filled per model below
+}
+
+PRESETS: dict[str, Capabilities] = {
+    # --- Anthropic ------------------------------------------------------
+    "claude-opus-4-5": Capabilities(
+        max_context=200_000, max_output=64_000, supports_prompt_caching=True,
+        native_thinking=True, price_in_per_mtok=5.0, price_out_per_mtok=25.0,
+        price_cache_read_per_mtok=0.5, price_cache_write_per_mtok=6.25,
+        max_concurrent_requests=8,
+    ),
+    "claude-sonnet-4-5": Capabilities(
+        max_context=200_000, max_output=64_000, supports_prompt_caching=True,
+        native_thinking=True, price_in_per_mtok=3.0, price_out_per_mtok=15.0,
+        price_cache_read_per_mtok=0.3, price_cache_write_per_mtok=3.75,
+        max_concurrent_requests=8,
+    ),
+    "claude-haiku-4-5": Capabilities(
+        max_context=200_000, max_output=64_000, supports_prompt_caching=True,
+        native_thinking=True, price_in_per_mtok=1.0, price_out_per_mtok=5.0,
+        price_cache_read_per_mtok=0.1, price_cache_write_per_mtok=1.25,
+        max_concurrent_requests=8,
+    ),
+    # --- self-hosted GLM-5.2 on Modal -----------------------------------
+    "glm-5.2": Capabilities(
+        max_context=65_536,
+        max_output=8_192,
+        supports_prompt_caching=False,
+        supports_parallel_tool_calls=True,
+        supports_reasoning_field=True,  # vLLM --reasoning-parser glm45
+        native_thinking=False,
+        cost_per_hour=18.16,  # 4xH200
+        max_concurrent_requests=16,  # vLLM --max-num-seqs 16
+    ),
+    # --- NVIDIA NIM -------------------------------------------------------
+    #
+    # NVIDIA hosts Z.ai's GLM-5.2 on NIM at 200k context — nothing like the
+    # 65k self-hosted deployment above. This key must be an exact model id
+    # ("z-ai/glm-5.2"), not a substring of it: `preset_for`'s fallback does
+    # `key in model`, and the self-hosted key "glm-5.2" is a substring of
+    # this one. Without an explicit exact entry, this model would silently
+    # inherit the self-hosted preset's 65k window and $18.16/hr cost.
+    #
+    # No published per-token price exists for this credit-based developer
+    # endpoint, so both prices are honestly 0.0 rather than fabricated.
+    "z-ai/glm-5.2": Capabilities(
+        max_context=200_000,
+        max_output=32_768,
+        supports_parallel_tool_calls=True,
+        supports_reasoning_field=True,  # reasoning_content, opt-in via extra_body
+        native_thinking=False,
+        price_in_per_mtok=0.0,
+        price_out_per_mtok=0.0,
+        # Measured, not guessed: an 84-run sweep triggered HTTP 429 almost
+        # immediately, and minutes later a single sequential request still
+        # got 429'd. No Retry-After or x-ratelimit-* headers are ever present,
+        # so there is nothing to back off against. That a lone request failed
+        # well after the burst suggests the free/credit tier's limit is a
+        # longer-window quota rather than a per-minute throttle, but the
+        # actual reset window is unknown — better to say so than invent one.
+        max_concurrent_requests=1,
+    ),
+    # --- OpenAI ---------------------------------------------------------
+    "gpt-4.1": Capabilities(
+        max_context=1_047_576, max_output=32_768, price_in_per_mtok=2.0,
+        price_out_per_mtok=8.0, price_cache_read_per_mtok=0.5,
+    ),
+    "gpt-4.1-mini": Capabilities(
+        max_context=1_047_576, max_output=32_768, price_in_per_mtok=0.4,
+        price_out_per_mtok=1.6, price_cache_read_per_mtok=0.1,
+    ),
+    # --- Blaxel (OpenAI-compatible sandbox) ------------------------------
+    #
+    # Blaxel's sandbox endpoint is pinned to gpt-4o-mini server-side — the
+    # `model` field in the request is accepted but ignored — so this preset
+    # exists to price and size the window for that one fixed model. Prices
+    # are OpenAI's published gpt-4o-mini list rates; Blaxel does not publish
+    # its own sandbox billing, so what this actually costs on Blaxel is
+    # unknown, not zero. `max_concurrent_requests=4` is a modest default, not
+    # a measured limit: ten consecutive requests totalling 390k input tokens
+    # drew zero 429s, so nothing here is throttling on purpose.
+    "gpt-4o-mini": Capabilities(
+        max_context=128_000, max_output=16_384, price_in_per_mtok=0.15,
+        price_out_per_mtok=0.60, max_concurrent_requests=4,
+    ),
+    # --- Groq -----------------------------------------------------------
+    #
+    # These numbers are the *free-tier rate limit*, not the model's capability.
+    # Groq's on-demand tier caps tokens-per-minute at 8,000 and — this is the part
+    # that surprises — counts the requested `max_tokens` against it. Asking for the
+    # model's real 32,768-token output with a 4k prompt is a 35k request and a hard
+    # 413 before a single token is generated.
+    #
+    # `max_context` is therefore set to what we may actually send, which is what the
+    # budget and compaction machinery consumes it as. Raise both on a paid tier.
+    "llama-3.3-70b-versatile": Capabilities(
+        max_context=7_000, max_output=1_500, price_in_per_mtok=0.59,
+        price_out_per_mtok=0.79, max_concurrent_requests=1,
+    ),
+    "openai/gpt-oss-120b": Capabilities(
+        max_context=7_000, max_output=1_500, supports_reasoning_field=True,
+        price_in_per_mtok=0.15, price_out_per_mtok=0.75, max_concurrent_requests=1,
+    ),
+    # --- Gemini ---------------------------------------------------------
+    "gemini-2.5-pro": Capabilities(
+        max_context=1_048_576, max_output=65_536, price_in_per_mtok=1.25,
+        price_out_per_mtok=10.0, price_cache_read_per_mtok=0.31,
+    ),
+    "gemini-2.5-flash": Capabilities(
+        max_context=1_048_576, max_output=65_536, price_in_per_mtok=0.30,
+        price_out_per_mtok=2.50, price_cache_read_per_mtok=0.075,
+    ),
+}
+
+
+def preset_for(model: str) -> Capabilities:
+    """Best-effort capability lookup: exact match, then prefix, then a default.
+
+    A conservative default (128k context, no caching) is safer than guessing
+    generously — under-estimating the window costs an extra compaction, while
+    over-estimating costs a hard 400 mid-session.
+    """
+    if model in PRESETS:
+        return PRESETS[model].model_copy(deep=True)
+    for key, caps in PRESETS.items():
+        if model.startswith(key) or key in model:
+            return caps.model_copy(deep=True)
+    return Capabilities(max_context=128_000, max_output=8_192)

turnloop/providers/registry.py

@@ -0,0 +1,75 @@
+"""Provider construction from configuration.
+
+The only module that imports every adapter. Everything above the provider layer
+resolves a provider by name through here, so adding a new backend touches one
+dict and one file.
+"""
+
+from __future__ import annotations
+
+import os
+
+from turnloop.errors import ConfigError
+from turnloop.providers.anthropic import AnthropicProvider
+from turnloop.providers.base import Provider
+from turnloop.providers.gemini import GeminiProvider
+from turnloop.providers.mock import MockProvider
+from turnloop.providers.openai_compat import OpenAICompatProvider
+
+_KINDS = {
+    "anthropic": AnthropicProvider,
+    "openai_compat": OpenAICompatProvider,
+    "gemini": GeminiProvider,
+    "mock": MockProvider,
+}
+
+
+def build_provider(name: str, cfg) -> Provider:
+    """Instantiate a provider from a ProviderConfig.
+
+    `cfg` is typed loosely to keep config.py from importing this module and back.
+    """
+    cls = _KINDS.get(cfg.kind)
+    if cls is None:
+        raise ConfigError(
+            f"provider '{name}': unknown kind '{cfg.kind}' "
+            f"(expected one of {', '.join(sorted(_KINDS))})"
+        )
+
+    api_key = cfg.api_key or ""
+    if cfg.api_key_env:
+        api_key = os.environ.get(cfg.api_key_env, "") or api_key
+        if not api_key and cfg.kind != "openai_compat":
+            # An OpenAI-compatible endpoint may legitimately be unauthenticated
+            # (vLLM on Modal is), so only hosted APIs hard-fail here.
+            raise ConfigError(
+                f"provider '{name}': environment variable {cfg.api_key_env} is not set"
+            )
+
+    kwargs: dict = {
+        "name": name,
+        "model": cfg.model,
+        "caps": cfg.caps,
+        "base_url": cfg.base_url,
+        "api_key": api_key,
+        "headers": dict(cfg.headers or {}),
+        "timeout_s": cfg.timeout_s,
+        "health_url": cfg.health_url,
+    }
+    if cfg.cold_boot_budget_s is not None:
+        kwargs["cold_boot_budget_s"] = cfg.cold_boot_budget_s
+
+    if cfg.kind == "openai_compat":
+        kwargs["glm_reasoning"] = cfg.glm_reasoning
+        kwargs["extra_body"] = dict(cfg.extra_body or {})
+    elif cfg.kind == "mock":
+        kwargs["mode"] = cfg.mock_mode
+        kwargs["seed"] = cfg.mock_seed
+        if cfg.mock_replay_path:
+            kwargs["replay_path"] = cfg.mock_replay_path
+
+    return cls(**kwargs)
+
+
+def available_kinds() -> list[str]:
+    return sorted(_KINDS)

turnloop/providers/sse.py

@@ -0,0 +1,114 @@
+"""Server-sent-events parsing.
+
+This file is the entire reason the project needs no vendor SDK. Every endpoint we
+speak to (Anthropic messages, OpenAI-compatible chat completions, Gemini
+streamGenerateContent) emits `event:`/`data:` framed text, and parsing it here
+means the raw JSON dict reaches the adapter untouched — which is how GLM's
+`reasoning_content` arrives without fighting a typed SDK model that has no field
+for it.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class SSEEvent:
+    event: str | None
+    data: str
+
+    def json(self) -> dict | None:
+        if not self.data or self.data == "[DONE]":
+            return None
+        try:
+            parsed = json.loads(self.data)
+        except json.JSONDecodeError:
+            return None
+        return parsed if isinstance(parsed, dict) else None
+
+    @property
+    def is_done(self) -> bool:
+        return self.data.strip() == "[DONE]"
+
+
+async def iter_sse(lines: AsyncIterator[str]) -> AsyncIterator[SSEEvent]:
+    """Yield one SSEEvent per blank-line-terminated frame.
+
+    Multi-line `data:` fields are joined with newlines per the SSE spec. A frame
+    is also flushed at end-of-stream even without a trailing blank line, because
+    some proxies drop it.
+    """
+    event_name: str | None = None
+    data_lines: list[str] = []
+
+    async for raw in lines:
+        line = raw.rstrip("\r\n")
+
+        if not line:
+            if data_lines or event_name:
+                yield SSEEvent(event=event_name, data="\n".join(data_lines))
+            event_name, data_lines = None, []
+            continue
+
+        if line.startswith(":"):  # comment / keepalive
+            continue
+
+        field, _, value = line.partition(":")
+        if value.startswith(" "):
+            value = value[1:]
+
+        if field == "event":
+            event_name = value
+        elif field == "data":
+            data_lines.append(value)
+        # `id` and `retry` are unused by any provider we target.
+
+    if data_lines or event_name:
+        yield SSEEvent(event=event_name, data="\n".join(data_lines))
+
+
+async def iter_json_array(chunks: AsyncIterator[bytes]) -> AsyncIterator[dict]:
+    """Stream objects out of a top-level JSON array as they complete.
+
+    Gemini's `streamGenerateContent` without `alt=sse` returns one growing JSON
+    array rather than SSE frames. Tracks brace depth outside of string literals.
+    """
+    buf = ""
+    depth = 0
+    start = -1
+    in_string = False
+    escape = False
+
+    async for chunk in chunks:
+        buf += chunk.decode("utf-8", errors="replace")
+        i = 0
+        while i < len(buf):
+            ch = buf[i]
+            if in_string:
+                if escape:
+                    escape = False
+                elif ch == "\\":
+                    escape = True
+                elif ch == '"':
+                    in_string = False
+            elif ch == '"':
+                in_string = True
+            elif ch == "{":
+                if depth == 0:
+                    start = i
+                depth += 1
+            elif ch == "}":
+                depth -= 1
+                if depth == 0 and start >= 0:
+                    try:
+                        obj = json.loads(buf[start : i + 1])
+                    except json.JSONDecodeError:
+                        obj = None
+                    if isinstance(obj, dict):
+                        yield obj
+                    buf = buf[i + 1 :]
+                    i, start = -1, -1
+            i += 1