Skip to content

Official Codebase of 3DCodeVerse

Python

models: eighteen files become eleven — one Gemini stack, one scheduling machine

gaoypengfa4680eb24e7
diff --git a/harness/codeverse/agents/gemini_cli.py b/harness/codeverse/agents/gemini_cli.py
index d660befb..36103d25 100644
--- a/harness/codeverse/agents/gemini_cli.py
+++ b/harness/codeverse/agents/gemini_cli.py
@@ -47,7 +47,7 @@ from codeverse.agents.watchdog import CompletedProc
from codeverse.config import get_settings
from codeverse.contracts.agent import AgentJob, AgentResult
from codeverse.contracts.common import Usage
-from codeverse.models.keypool import KeyPool, KeyPoolExhausted
+from codeverse.models.retry import KeyPool, KeyPoolExhausted
log = logging.getLogger(__name__)
diff --git a/harness/codeverse/cli/doctor.py b/harness/codeverse/cli/doctor.py
index 41c734cc..e90ed14b 100644
--- a/harness/codeverse/cli/doctor.py
+++ b/harness/codeverse/cli/doctor.py
@@ -157,7 +157,7 @@ def check_pool(live: bool) -> list[Row]:
Only meaningful once something has used the pool this process, so it is part
of ``--live`` (``check_keys`` makes one call just before)."""
from codeverse.models.gemini import shared_pool
- from codeverse.models.storm import all_gates
+ from codeverse.models.retry import all_gates
s = get_settings()
if not s.gemini_api_keys:
diff --git a/harness/codeverse/cli/texture_cmd.py b/harness/codeverse/cli/texture_cmd.py
index 8a2bebf4..5d606ffc 100644
--- a/harness/codeverse/cli/texture_cmd.py
+++ b/harness/codeverse/cli/texture_cmd.py
@@ -23,7 +23,7 @@ RunsDirOpt = Annotated[Path | None, typer.Option("--runs-dir", help="runs root (
def _image_model(name: str | None):
- GeminiImageModel = C.lazy("codeverse.models.gemini_image", "GeminiImageModel")
+ GeminiImageModel = C.lazy("codeverse.models.gemini", "GeminiImageModel")
return GeminiImageModel(name) if name else GeminiImageModel()
diff --git a/harness/codeverse/models/anthropic.py b/harness/codeverse/models/anthropic.py
index 6e2090ea..f79ca8f9 100644
--- a/harness/codeverse/models/anthropic.py
+++ b/harness/codeverse/models/anthropic.py
@@ -1,8 +1,12 @@
-"""``AnthropicModel`` — Messages API backend (images, tools, JSON via ``submit``
-tool, adaptive / budgeted thinking, cache-aware usage + cost, typed errors).
+"""ChatRequest ⇄ Anthropic Messages API dicts (messages, tools, thinking, parse).
-Retries (429 / 529 / 5xx / connection / timeouts) use ``with_retries``; the
-SDK's own retry is disabled so back-off is governed here.
+Model-family rules (Anthropic API, 2026-08):
+* 4.6+ family (opus-5, sonnet-5, fable-5, mythos, opus-4-6/7/8, sonnet-4-6):
+ ``thinking={"type":"adaptive"}`` + ``output_config.effort``; ``budget_tokens``
+ is rejected; sampling params are rejected on opus-5/sonnet-5/fable/4.7/4.8.
+* older models (haiku-4-5, sonnet-4-5, opus-4-1 …): ``thinking={"type":
+ "enabled","budget_tokens":N}`` (N < max_tokens), temperature must be left
+ at default while thinking is on.
"""
from __future__ import annotations
@@ -14,16 +18,222 @@ import time
from collections.abc import Callable
from typing import Any
-from codeverse.contracts.chat import ChatRequest, ChatResponse
+from codeverse.contracts.chat import (
+ ChatMessage,
+ ChatRequest,
+ ChatResponse,
+ ImagePart,
+ TextPart,
+ ToolCallPart,
+ ToolResultPart,
+ ToolSpec,
+)
from codeverse.contracts.common import Usage
-from codeverse.models.anthropic_convert import THINKING_BLOCKS, build_kwargs, parse_content
from codeverse.models.base import ModelError
-from codeverse.models.keypool import MAX_WAIT_S
-from codeverse.models.parts import Stopwatch
+from codeverse.models.parts import BoundedCache, Stopwatch, image_b64
from codeverse.models.pricing import cache_write_surcharge, estimate_cost
-from codeverse.models.retry import with_retries
-from codeverse.models.schema_utils import JsonParseError, parse_json_lenient, strip_control_chars
+from codeverse.models.retry import MAX_WAIT_S, with_retries
+from codeverse.models.schema_utils import (
+ JsonParseError,
+ parse_json_lenient,
+ strip_control_chars,
+ to_anthropic_schema,
+)
+SUBMIT_TOOL = "submit"
+THINKING_BUDGET: dict[str, int] = {"off": 0, "low": 1024, "medium": 4096, "high": 16000}
+EFFORT: dict[str, str] = {"off": "low", "low": "low", "medium": "medium", "high": "high"}
+
+_ADAPTIVE_MARKERS = (
+ "opus-5",
+ "sonnet-5",
+ "fable-5",
+ "mythos",
+ "opus-4-6",
+ "opus-4-7",
+ "opus-4-8",
+ "sonnet-4-6",
+)
+_ALWAYS_THINKING = ("fable-5", "mythos")
+_NO_SAMPLING = ("opus-5", "sonnet-5", "fable-5", "mythos", "opus-4-7", "opus-4-8")
+
+
+def uses_adaptive_thinking(model: str) -> bool:
+ m = model.lower()
+ return any(tok in m for tok in _ADAPTIVE_MARKERS)
+
+
+def thinking_always_on(model: str) -> bool:
+ m = model.lower()
+ return any(tok in m for tok in _ALWAYS_THINKING)
+
+
+def sampling_allowed(model: str) -> bool:
+ m = model.lower()
+ return not any(tok in m for tok in _NO_SAMPLING)
+
+
+#: Assistant turns that contain tool calls must be replayed WITH their
+#: thinking blocks on the next request. ``ToolCallPart`` cannot carry them,
+#: so we remember the blocks under the first tool-call id (bounded LRU).
+THINKING_BLOCKS: BoundedCache[list[dict[str, Any]]] = BoundedCache(2048)
+
+
+# ------------------------------------------------------------------ messages
+def _image_block(p: ImagePart) -> dict[str, Any]:
+ data, mime = image_b64(p)
+ return {"type": "image", "source": {"type": "base64", "media_type": mime, "data": data}}
+
+
+def to_messages(messages: list[ChatMessage]) -> list[dict[str, Any]]:
+ """ChatMessages → Anthropic ``messages``. ``tool`` role → user turn of
+ ``tool_result`` blocks; consecutive same-role turns are merged."""
+ out: list[dict[str, Any]] = []
+ for msg in messages:
+ role = "assistant" if msg.role == "assistant" else "user"
+ blocks: list[dict[str, Any]] = []
+ first_call_id: str | None = None
+ for p in msg.parts:
+ if isinstance(p, TextPart):
+ if p.text:
+ blocks.append({"type": "text", "text": p.text})
+ elif isinstance(p, ImagePart):
+ if p.label:
+ blocks.append({"type": "text", "text": f"[image: {p.label}]"})
+ blocks.append(_image_block(p))
+ elif isinstance(p, ToolCallPart):
+ first_call_id = first_call_id or p.id
+ blocks.append(
+ {"type": "tool_use", "id": p.id, "name": p.name, "input": dict(p.arguments)}
+ )
+ elif isinstance(p, ToolResultPart):
+ content: list[dict[str, Any]] = [
+ {"type": "text", "text": p.content or "(no output)"}
+ ]
+ for img in p.images:
+ if img.label:
+ content.append({"type": "text", "text": f"[image: {img.label}]"})
+ content.append(_image_block(img))
+ block: dict[str, Any] = {
+ "type": "tool_result",
+ "tool_use_id": p.call_id,
+ "content": content,
+ }
+ if p.is_error:
+ block["is_error"] = True
+ blocks.append(block)
+ if not blocks:
+ continue
+ if role == "assistant" and first_call_id:
+ blocks = list(THINKING_BLOCKS.get(first_call_id) or []) + blocks
+ if out and out[-1]["role"] == role:
+ out[-1]["content"].extend(blocks)
+ else:
+ out.append({"role": role, "content": blocks})
+ if not out:
+ raise ModelError("ChatRequest has no content to send")
+ if out[0]["role"] != "user":
+ out.insert(0, {"role": "user", "content": [{"type": "text", "text": "(continue)"}]})
+ return out
+
+
+# --------------------------------------------------------------------- tools
+def to_tool(t: ToolSpec) -> dict[str, Any]:
+ schema = (
+ to_anthropic_schema(t.parameters) if t.parameters else {"type": "object", "properties": {}}
+ )
+ return {"name": t.name, "description": t.description, "input_schema": schema}
+
+
+def submit_tool(schema: dict[str, Any]) -> dict[str, Any]:
+ return {
+ "name": SUBMIT_TOOL,
+ "description": "Submit the final answer. Call exactly once with the complete JSON object.",
+ "input_schema": to_anthropic_schema(schema),
+ }
+
+
+# ------------------------------------------------------------------- request
+def build_kwargs(request: ChatRequest, model: str, *, json_mode: str = "tool") -> dict[str, Any]:
+ """Build ``client.messages.create(**kwargs)`` (without ``model``/``timeout``).
+ ``json_mode``: ``"tool"`` forces a ``submit`` tool; ``"output_config"`` uses
+ ``output_config.format`` json_schema."""
+ kw: dict[str, Any] = {
+ "messages": to_messages(request.messages),
+ "max_tokens": request.max_output_tokens,
+ }
+ system = request.system
+ thinking_on = request.thinking != "off" or thinking_always_on(model)
+
+ if uses_adaptive_thinking(model):
+ if request.thinking != "off":
+ kw["thinking"] = {"type": "adaptive"}
+ kw["output_config"] = {"effort": EFFORT[request.thinking]}
+ elif not thinking_always_on(model):
+ kw["thinking"] = {"type": "disabled"}
+ else:
+ kw["output_config"] = {"effort": "low"}
+ elif request.thinking != "off":
+ budget = THINKING_BUDGET[request.thinking]
+ kw["thinking"] = {"type": "enabled", "budget_tokens": budget}
+ kw["max_tokens"] = max(request.max_output_tokens, budget + 2048)
+
+ if sampling_allowed(model) and not thinking_on:
+ kw["temperature"] = request.temperature
+
+ tools = [to_tool(t) for t in request.tools] if request.tools else []
+ if request.response_schema is not None:
+ if json_mode == "output_config":
+ kw.setdefault("output_config", {})["format"] = {
+ "type": "json_schema",
+ "schema": to_anthropic_schema(request.response_schema),
+ }
+ else:
+ tools.append(submit_tool(request.response_schema))
+ if not request.tools and not thinking_on:
+ kw["tool_choice"] = {"type": "tool", "name": SUBMIT_TOOL}
+ else:
+ # forced tool_choice is incompatible with thinking; nudge instead
+ system = (
+ (system + "\n\n" if system else "")
+ + f"When you have the final answer, call the `{SUBMIT_TOOL}` tool exactly once with the complete JSON object."
+ )
+ if tools:
+ kw["tools"] = tools
+ if system:
+ kw["system"] = system
+ return kw
+
+
+# ------------------------------------------------------------------ response
+def parse_content(content: list[Any]) -> tuple[str, list[ToolCallPart], Any, list[dict[str, Any]]]:
+ """→ ``(text, tool_calls, submit_input, thinking_blocks)`` from response blocks."""
+ texts: list[str] = []
+ calls: list[ToolCallPart] = []
+ submit: Any = None
+ thinking: list[dict[str, Any]] = []
+ for block in content:
+ btype = getattr(block, "type", None)
+ if btype == "text":
+ texts.append(block.text)
+ elif btype == "tool_use":
+ args = (
+ block.input
+ if isinstance(block.input, dict)
+ else json.loads(json.dumps(block.input))
+ )
+ if block.name == SUBMIT_TOOL:
+ submit = args
+ else:
+ calls.append(ToolCallPart(id=block.id, name=block.name, arguments=dict(args)))
+ elif btype in ("thinking", "redacted_thinking"):
+ dump = block.model_dump() if hasattr(block, "model_dump") else dict(block)
+ thinking.append(dump)
+ return "".join(texts), calls, submit, thinking
+
+
+# ===================================================================== anthropic
+# (merged from codeverse/models/anthropic.py, 2026-08-28)
log = logging.getLogger(__name__)
diff --git a/harness/codeverse/models/anthropic_convert.py b/harness/codeverse/models/anthropic_convert.py
deleted file mode 100644
index c393e5ca..00000000
--- a/harness/codeverse/models/anthropic_convert.py
+++ /dev/null
@@ -1,219 +0,0 @@
-"""ChatRequest ⇄ Anthropic Messages API dicts (messages, tools, thinking, parse).
-
-Model-family rules (Anthropic API, 2026-08):
-* 4.6+ family (opus-5, sonnet-5, fable-5, mythos, opus-4-6/7/8, sonnet-4-6):
- ``thinking={"type":"adaptive"}`` + ``output_config.effort``; ``budget_tokens``
- is rejected; sampling params are rejected on opus-5/sonnet-5/fable/4.7/4.8.
-* older models (haiku-4-5, sonnet-4-5, opus-4-1 …): ``thinking={"type":
- "enabled","budget_tokens":N}`` (N < max_tokens), temperature must be left
- at default while thinking is on.
-"""
-
-from __future__ import annotations
-
-import json
-from typing import Any
-
-from codeverse.contracts.chat import (
- ChatMessage,
- ChatRequest,
- ImagePart,
- TextPart,
- ToolCallPart,
- ToolResultPart,
- ToolSpec,
-)
-from codeverse.models.base import ModelError
-from codeverse.models.parts import BoundedCache, image_b64
-from codeverse.models.schema_utils import to_anthropic_schema
-
-SUBMIT_TOOL = "submit"
-THINKING_BUDGET: dict[str, int] = {"off": 0, "low": 1024, "medium": 4096, "high": 16000}
-EFFORT: dict[str, str] = {"off": "low", "low": "low", "medium": "medium", "high": "high"}
-
-_ADAPTIVE_MARKERS = (
- "opus-5",
- "sonnet-5",
- "fable-5",
- "mythos",
- "opus-4-6",
- "opus-4-7",
- "opus-4-8",
- "sonnet-4-6",
-)
-_ALWAYS_THINKING = ("fable-5", "mythos")
-_NO_SAMPLING = ("opus-5", "sonnet-5", "fable-5", "mythos", "opus-4-7", "opus-4-8")
-
-
-def uses_adaptive_thinking(model: str) -> bool:
- m = model.lower()
- return any(tok in m for tok in _ADAPTIVE_MARKERS)
-
-
-def thinking_always_on(model: str) -> bool:
- m = model.lower()
- return any(tok in m for tok in _ALWAYS_THINKING)
-
-
-def sampling_allowed(model: str) -> bool:
- m = model.lower()
- return not any(tok in m for tok in _NO_SAMPLING)
-
-
-#: Assistant turns that contain tool calls must be replayed WITH their
-#: thinking blocks on the next request. ``ToolCallPart`` cannot carry them,
-#: so we remember the blocks under the first tool-call id (bounded LRU).
-THINKING_BLOCKS: BoundedCache[list[dict[str, Any]]] = BoundedCache(2048)
-
-
-# ------------------------------------------------------------------ messages
-def _image_block(p: ImagePart) -> dict[str, Any]:
- data, mime = image_b64(p)
- return {"type": "image", "source": {"type": "base64", "media_type": mime, "data": data}}
-
-
-def to_messages(messages: list[ChatMessage]) -> list[dict[str, Any]]:
- """ChatMessages → Anthropic ``messages``. ``tool`` role → user turn of
- ``tool_result`` blocks; consecutive same-role turns are merged."""
- out: list[dict[str, Any]] = []
- for msg in messages:
- role = "assistant" if msg.role == "assistant" else "user"
- blocks: list[dict[str, Any]] = []
- first_call_id: str | None = None
- for p in msg.parts:
- if isinstance(p, TextPart):
- if p.text:
- blocks.append({"type": "text", "text": p.text})
- elif isinstance(p, ImagePart):
- if p.label:
- blocks.append({"type": "text", "text": f"[image: {p.label}]"})
- blocks.append(_image_block(p))
- elif isinstance(p, ToolCallPart):
- first_call_id = first_call_id or p.id
- blocks.append(
- {"type": "tool_use", "id": p.id, "name": p.name, "input": dict(p.arguments)}
- )
- elif isinstance(p, ToolResultPart):
- content: list[dict[str, Any]] = [
- {"type": "text", "text": p.content or "(no output)"}
- ]
- for img in p.images:
- if img.label:
- content.append({"type": "text", "text": f"[image: {img.label}]"})
- content.append(_image_block(img))
- block: dict[str, Any] = {
- "type": "tool_result",
- "tool_use_id": p.call_id,
- "content": content,
- }
- if p.is_error:
- block["is_error"] = True
- blocks.append(block)
- if not blocks:
- continue
- if role == "assistant" and first_call_id:
- blocks = list(THINKING_BLOCKS.get(first_call_id) or []) + blocks
- if out and out[-1]["role"] == role:
- out[-1]["content"].extend(blocks)
- else:
- out.append({"role": role, "content": blocks})
- if not out:
- raise ModelError("ChatRequest has no content to send")
- if out[0]["role"] != "user":
- out.insert(0, {"role": "user", "content": [{"type": "text", "text": "(continue)"}]})
- return out
-
-
-# --------------------------------------------------------------------- tools
-def to_tool(t: ToolSpec) -> dict[str, Any]:
- schema = (
- to_anthropic_schema(t.parameters) if t.parameters else {"type": "object", "properties": {}}
- )
- return {"name": t.name, "description": t.description, "input_schema": schema}
-
-
-def submit_tool(schema: dict[str, Any]) -> dict[str, Any]:
- return {
- "name": SUBMIT_TOOL,
- "description": "Submit the final answer. Call exactly once with the complete JSON object.",
- "input_schema": to_anthropic_schema(schema),
- }
-
-
-# ------------------------------------------------------------------- request
-def build_kwargs(request: ChatRequest, model: str, *, json_mode: str = "tool") -> dict[str, Any]:
- """Build ``client.messages.create(**kwargs)`` (without ``model``/``timeout``).
- ``json_mode``: ``"tool"`` forces a ``submit`` tool; ``"output_config"`` uses
- ``output_config.format`` json_schema."""
- kw: dict[str, Any] = {
- "messages": to_messages(request.messages),
- "max_tokens": request.max_output_tokens,
- }
- system = request.system
- thinking_on = request.thinking != "off" or thinking_always_on(model)
-
- if uses_adaptive_thinking(model):
- if request.thinking != "off":
- kw["thinking"] = {"type": "adaptive"}
- kw["output_config"] = {"effort": EFFORT[request.thinking]}
- elif not thinking_always_on(model):
- kw["thinking"] = {"type": "disabled"}
- else:
- kw["output_config"] = {"effort": "low"}
- elif request.thinking != "off":
- budget = THINKING_BUDGET[request.thinking]
- kw["thinking"] = {"type": "enabled", "budget_tokens": budget}
- kw["max_tokens"] = max(request.max_output_tokens, budget + 2048)
-
- if sampling_allowed(model) and not thinking_on:
- kw["temperature"] = request.temperature
-
- tools = [to_tool(t) for t in request.tools] if request.tools else []
- if request.response_schema is not None:
- if json_mode == "output_config":
- kw.setdefault("output_config", {})["format"] = {
- "type": "json_schema",
- "schema": to_anthropic_schema(request.response_schema),
- }
- else:
- tools.append(submit_tool(request.response_schema))
- if not request.tools and not thinking_on:
- kw["tool_choice"] = {"type": "tool", "name": SUBMIT_TOOL}
- else:
- # forced tool_choice is incompatible with thinking; nudge instead
- system = (
- (system + "\n\n" if system else "")
- + f"When you have the final answer, call the `{SUBMIT_TOOL}` tool exactly once with the complete JSON object."
- )
- if tools:
- kw["tools"] = tools
- if system:
- kw["system"] = system
- return kw
-
-
-# ------------------------------------------------------------------ response
-def parse_content(content: list[Any]) -> tuple[str, list[ToolCallPart], Any, list[dict[str, Any]]]:
- """→ ``(text, tool_calls, submit_input, thinking_blocks)`` from response blocks."""
- texts: list[str] = []
- calls: list[ToolCallPart] = []
- submit: Any = None
- thinking: list[dict[str, Any]] = []
- for block in content:
- btype = getattr(block, "type", None)
- if btype == "text":
- texts.append(block.text)
- elif btype == "tool_use":
- args = (
- block.input
- if isinstance(block.input, dict)
- else json.loads(json.dumps(block.input))
- )
- if block.name == SUBMIT_TOOL:
- submit = args
- else:
- calls.append(ToolCallPart(id=block.id, name=block.name, arguments=dict(args)))
- elif btype in ("thinking", "redacted_thinking"):
- dump = block.model_dump() if hasattr(block, "model_dump") else dict(block)
- thinking.append(dump)
- return "".join(texts), calls, submit, thinking
diff --git a/harness/codeverse/models/gemini.py b/harness/codeverse/models/gemini.py
index 7e53347a..939a5204 100644
--- a/harness/codeverse/models/gemini.py
+++ b/harness/codeverse/models/gemini.py
@@ -1,52 +1,289 @@
-"""``GeminiModel`` — google-genai backend with key rotation + retries.
-
-* one ``genai.Client`` per API key (cached, thread-safe),
-* ``KeyPool`` shared by every GeminiModel built on the same key list,
-* 429 → rotate to a fresh key (short pause; free while an untried key remains),
- then up to ``max_attempts`` tries with exponential backoff + jitter for 5xx /
- timeouts / empty candidates / 429s once every key has been tried,
-* key-scoped auth failures (401/403, ``API_KEY_INVALID`` …) → rotate for free and
- bench the key in the pool (``dead``) once a sibling key proves the request is
- fine; only when every key fails the same way is the error raised,
-* ``thinking`` → ``ThinkingConfig(thinking_budget=…)``; models that reject the
- field get one retry without it and a warning in ``response.raw["warnings"]``.
+"""ChatRequest ⇄ google-genai types (contents, config, tools, response parsing).
+
+Kept separate from ``gemini.py`` (which owns clients, keys, retries) so each
+module stays small and the conversions are unit-testable offline.
"""
from __future__ import annotations
+import io
+import json
import logging
import re
import threading
import time
-from collections.abc import Callable
-from typing import Any
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
import httpx
from google import genai
from google.genai import errors as genai_errors
from google.genai import types
-
-from codeverse.contracts.chat import ChatRequest, ChatResponse
+from PIL import Image
+
+from codeverse.contracts.chat import (
+ ChatMessage,
+ ChatRequest,
+ ChatResponse,
+ ImagePart,
+ TextPart,
+ ToolCallPart,
+ ToolResultPart,
+ ToolSpec,
+)
from codeverse.contracts.common import Usage
from codeverse.models.base import ModelError
-from codeverse.models.gemini_convert import (
- FATAL_FINISH,
- RETRYABLE_FINISH,
- build_config,
- clip_timeout,
- extract_candidate,
- parse_usage,
- to_contents,
-)
-from codeverse.models.keypool import MAX_WAIT_S, KeyPool, KeyPoolExhausted, Outcome
-from codeverse.models.parts import Stopwatch
+from codeverse.models.parts import BoundedCache, Stopwatch, image_bytes
from codeverse.models.pricing import estimate_cost
-from codeverse.models.retry import RETRY_DEADLINE_S, OnAttempt, _Try, rotate_with_retries
-from codeverse.models.schema_utils import JsonParseError, parse_json_lenient
-from codeverse.models.storm import StormGate
-from codeverse.models.storm import storm_gate as storm_gate_for
-from codeverse.models.tokens import request_tokens
+from codeverse.models.retry import (
+ MAX_WAIT_S,
+ RETRY_DEADLINE_S,
+ KeyPool,
+ KeyPoolExhausted,
+ OnAttempt,
+ Outcome,
+ StormGate,
+ _Try,
+ request_tokens,
+ rotate_with_retries,
+)
+from codeverse.models.retry import storm_gate as storm_gate_for
+from codeverse.models.schema_utils import JsonParseError, parse_json_lenient, to_gemini_schema
+
+#: INTERFACES.md mapping; ``off`` → 0 where the model allows it
+THINKING_BUDGET: dict[str, int] = {"off": 0, "low": 1024, "medium": 4096, "high": 16384}
+
+#: finish reasons that are worth one more attempt (transient model glitches)
+RETRYABLE_FINISH = {"RECITATION", "MALFORMED_FUNCTION_CALL", "OTHER", "UNEXPECTED_TOOL_CALL"}
+#: finish reasons that will not improve by retrying
+FATAL_FINISH = {"SAFETY", "PROHIBITED_CONTENT", "BLOCKLIST", "SPII", "IMAGE_SAFETY"}
+
+
+#: Gemini 3 function calls carry an opaque ``thought_signature`` that MUST be
+#: echoed back with the call on the next turn. ``ToolCallPart`` has no slot for
+#: it, so we remember signatures by our synthetic call id (bounded LRU).
+SIGNATURES: BoundedCache[bytes] = BoundedCache(4096)
+_call_counter = [0]
+_call_lock = threading.Lock()
+
+#: prefix of the ids WE mint when the provider sent none (``extract_candidate``).
+#: A synthetic id exists only to pair ToolCallPart/ToolResultPart locally and is
+#: NEVER echoed back to the provider; a GENUINE provider id is echoed verbatim on
+#: both ``FunctionCall`` and ``FunctionResponse``.
+SYNTHETIC_CALL_ID_PREFIX = "synth-call-"
+
+
+def _next_call_id() -> str:
+ with _call_lock:
+ _call_counter[0] += 1
+ return f"{SYNTHETIC_CALL_ID_PREFIX}{_call_counter[0]:06d}"
+
+
+def is_synthetic_call_id(call_id: str | None) -> bool:
+ """True for ids minted here rather than issued by the provider."""
+ return bool(call_id) and str(call_id).startswith(SYNTHETIC_CALL_ID_PREFIX)
+
+
+def _echo_id(call_id: str | None) -> str | None:
+ """The id to send back to Gemini: the provider's own id verbatim, never a synthetic one."""
+ return None if not call_id or is_synthetic_call_id(call_id) else str(call_id)
+
+
+# ------------------------------------------------------------------ contents
+def to_contents(messages: list[ChatMessage]) -> list[types.Content]:
+ """ChatMessages → Gemini ``Content`` list. ``tool`` messages become a user
+ turn of ``function_response`` parts (images attached as extra parts)."""
+ out: list[types.Content] = []
+ for msg in messages:
+ role = "model" if msg.role == "assistant" else "user"
+ parts: list[types.Part] = []
+ for p in msg.parts:
+ if isinstance(p, TextPart):
+ if p.text:
+ parts.append(types.Part.from_text(text=p.text))
+ elif isinstance(p, ImagePart):
+ raw, mime = image_bytes(p)
+ if p.label:
+ parts.append(types.Part.from_text(text=f"[image: {p.label}]"))
+ parts.append(types.Part.from_bytes(data=raw, mime_type=mime))
+ elif isinstance(p, ToolCallPart):
+ part = types.Part(
+ function_call=types.FunctionCall(
+ name=p.name, args=dict(p.arguments), id=_echo_id(p.id)
+ )
+ )
+ sig = SIGNATURES.get(p.id)
+ if sig:
+ part.thought_signature = sig
+ parts.append(part)
+ elif isinstance(p, ToolResultPart):
+ parts.append(_function_response_part(p))
+ for img in p.images:
+ raw, mime = image_bytes(img)
+ if img.label:
+ parts.append(types.Part.from_text(text=f"[image: {img.label}]"))
+ parts.append(types.Part.from_bytes(data=raw, mime_type=mime))
+ if not parts:
+ continue
+ # merge consecutive same-role turns (Gemini wants strict alternation)
+ if out and out[-1].role == role:
+ out[-1].parts.extend(parts) # type: ignore[union-attr]
+ else:
+ out.append(types.Content(role=role, parts=parts))
+ if not out:
+ raise ModelError("ChatRequest has no content to send")
+ return out
+
+
+def _function_response_part(p: ToolResultPart) -> types.Part:
+ payload: dict[str, Any]
+ try:
+ parsed = json.loads(p.content)
+ payload = parsed if isinstance(parsed, dict) else {"result": parsed}
+ except (json.JSONDecodeError, TypeError):
+ payload = {"result": p.content}
+ if p.is_error:
+ payload = {"error": payload.get("result", payload)} if "error" not in payload else payload
+ return types.Part(
+ function_response=types.FunctionResponse(name=p.name, response=payload, id=_echo_id(p.call_id))
+ )
+
+
+# -------------------------------------------------------------------- config
+def to_tools(tools: list[ToolSpec]) -> list[types.Tool]:
+ decls = [
+ types.FunctionDeclaration(
+ name=t.name,
+ description=t.description,
+ parameters=to_gemini_schema(t.parameters) if t.parameters else None,
+ )
+ for t in tools
+ ]
+ return [types.Tool(function_declarations=decls)]
+
+def build_config(
+ request: ChatRequest,
+ *,
+ timeout_ms: int,
+ use_thinking: bool = True,
+ warnings: list[str] | None = None,
+) -> types.GenerateContentConfig:
+ """Map a ChatRequest onto ``GenerateContentConfig``. Function calling and
+ JSON mode are mutually exclusive on Gemini: with tools, the schema is
+ dropped (the text is still parsed leniently) and a warning is recorded."""
+ cfg: dict[str, Any] = {
+ "temperature": request.temperature,
+ "max_output_tokens": request.max_output_tokens,
+ "http_options": types.HttpOptions(timeout=timeout_ms),
+ }
+ if request.system:
+ cfg["system_instruction"] = request.system
+ if use_thinking:
+ cfg["thinking_config"] = types.ThinkingConfig(
+ thinking_budget=THINKING_BUDGET[request.thinking], include_thoughts=False
+ )
+ if request.tools:
+ cfg["tools"] = to_tools(request.tools)
+ cfg["tool_config"] = types.ToolConfig(
+ function_calling_config=types.FunctionCallingConfig(mode="AUTO")
+ )
+ cfg["automatic_function_calling"] = types.AutomaticFunctionCallingConfig(disable=True)
+ if request.response_schema is not None and warnings is not None:
+ warnings.append(
+ "response_schema ignored: Gemini cannot combine function calling with JSON mode"
+ )
+ elif request.response_schema is not None:
+ cfg["response_mime_type"] = "application/json"
+ cfg["response_schema"] = to_gemini_schema(request.response_schema)
+ return types.GenerateContentConfig(**cfg)
+
+
+def clip_timeout(
+ config: types.GenerateContentConfig, timeout_ms: int
+) -> types.GenerateContentConfig:
+ """A copy of ``config`` whose per-request HTTP timeout is ``timeout_ms`` (the
+ SAME object when it already matches — the common full-budget case allocates
+ nothing). :func:`build_config` owns the initial ``timeout_ms``; this is the
+ one sanctioned way to shorten it for a single attempt whose remaining retry
+ budget is smaller than the configured read timeout
+ (``GeminiModel._attempt_config``)."""
+ current = config.http_options.timeout if config.http_options is not None else None
+ if current == timeout_ms:
+ return config
+ return config.model_copy(update={"http_options": types.HttpOptions(timeout=timeout_ms)})
+
+
+# ------------------------------------------------------------------ response
+def parse_usage(resp: types.GenerateContentResponse, model: str) -> Usage:
+ um = resp.usage_metadata
+ if um is None:
+ return Usage(backend="gemini", model=model)
+ return Usage(
+ backend="gemini",
+ model=resp.model_version or model,
+ input_tokens=(um.prompt_token_count or 0) + (um.tool_use_prompt_token_count or 0),
+ output_tokens=um.candidates_token_count or 0,
+ cached_tokens=um.cached_content_token_count or 0,
+ thoughts_tokens=um.thoughts_token_count or 0,
+ )
+
+
+def extract_candidate(
+ resp: types.GenerateContentResponse, usage: Usage | None = None
+) -> tuple[str, list[ToolCallPart], str]:
+ """→ ``(text, tool_calls, finish_reason)``. Raises ``ModelError`` on blocked
+ prompts (non-retryable) or empty candidates (retryable); ``usage`` (what the caller
+ already parsed off ``resp``) rides on the error, because every one of these
+ failures was billed."""
+ pf = resp.prompt_feedback
+ if pf is not None and pf.block_reason:
+ raise ModelError(
+ f"prompt blocked by Gemini: {pf.block_reason} {pf.block_reason_message or ''}".strip(),
+ retryable=False, usage=usage,
+ )
+ if not resp.candidates:
+ raise ModelError("Gemini returned no candidates", retryable=True, usage=usage)
+ cand = resp.candidates[0]
+ finish = str(cand.finish_reason.value if cand.finish_reason else "") or "UNKNOWN"
+ texts: list[str] = []
+ calls: list[ToolCallPart] = []
+ for part in cand.content.parts if cand.content and cand.content.parts else []:
+ if part.function_call is not None:
+ fc = part.function_call
+ # a genuine provider id is kept verbatim (and echoed back later); a synthetic
+ # one is minted, marked by its prefix, only so the parts pair locally
+ call_id = fc.id or _next_call_id()
+ SIGNATURES.put(call_id, part.thought_signature)
+ calls.append(
+ ToolCallPart(id=call_id, name=fc.name or "", arguments=dict(fc.args or {}))
+ )
+ elif part.text and not part.thought:
+ texts.append(part.text)
+ text = "".join(texts)
+ if not text and not calls:
+ if finish in FATAL_FINISH:
+ raise ModelError(
+ f"Gemini produced no content (finish_reason={finish})", retryable=False, usage=usage
+ )
+ if finish == "MAX_TOKENS":
+ # Gemini 3 models always think (budget 0 is accepted but ignored); a tiny
+ # max_output_tokens is eaten by thoughts. Retrying cannot help — and this is
+ # the most expensive failure on Gemini 3: every thought token was billed.
+ thoughts = resp.usage_metadata.thoughts_token_count if resp.usage_metadata else None
+ raise ModelError(
+ f"Gemini produced no content: max_output_tokens exhausted by thinking "
+ f"(thoughts_tokens={thoughts}); raise max_output_tokens",
+ retryable=False, usage=usage,
+ )
+ raise ModelError(f"Gemini produced no content (finish_reason={finish})",
+ retryable=True, usage=usage)
+ return text, calls, finish
+
+
+# ===================================================================== gemini
+# (merged from codeverse/models/gemini.py, 2026-08-28)
log = logging.getLogger(__name__)
_RETRY_DELAY_RE = re.compile(r"retryDelay['\"]?\s*:\s*['\"]?(\d+(?:\.\d+)?)s")
@@ -400,3 +637,286 @@ class GeminiModel:
return ChatResponse(
text=text, parsed=parsed, tool_calls=calls, finish_reason=finish, usage=usage, raw=raw
)
+
+
+# ===================================================================== gemini_image
+# (merged from codeverse/models/gemini_image.py, 2026-08-28)
+log = logging.getLogger(__name__)
+
+DEFAULT_IMAGE_MODEL = "gemini-3.1-flash-image"
+FALLBACK_IMAGE_MODEL = "gemini-2.5-flash-image"
+
+#: approximate USD per generated 1024² image (floor for cost accounting)
+IMAGE_USD: dict[str, float] = {
+ "gemini-3.1-flash-image": 0.067,
+ "gemini-2.5-flash-image": 0.039,
+}
+
+#: requested pixel size → Gemini ``image_size`` token
+_IMAGE_SIZE_TOKEN: dict[int, str] = {512: "1K", 1024: "1K", 2048: "2K", 4096: "4K"}
+
+
+@runtime_checkable
+class ImageModel(Protocol):
+ """Text-to-image backend. Implementations must be thread-safe."""
+
+ model: str
+
+ @property
+ def id(self) -> str: ...
+
+ def generate(
+ self,
+ prompt: str,
+ *,
+ size: int = 1024,
+ n: int = 1,
+ seed: int | None = None,
+ reference_images: Sequence[Image.Image | Path | str] = (),
+ ) -> list[Image.Image]: ...
+
+ def generate_with_usage(
+ self,
+ prompt: str,
+ *,
+ size: int = 1024,
+ n: int = 1,
+ seed: int | None = None,
+ reference_images: Sequence[Image.Image | Path | str] = (),
+ ) -> tuple[list[Image.Image], Usage]: ...
+
+
+def image_cost(model: str, usage: Usage, n_images: int) -> float:
+ """Token-priced cost floored by the per-image price (approximate)."""
+ token_cost = estimate_cost("gemini", model, usage)
+ per_image = IMAGE_USD.get(model.strip().lower(), 0.0)
+ return max(token_cost, per_image * max(0, n_images))
+
+
+def _to_part(ref: Image.Image | Path | str) -> types.Part:
+ if isinstance(ref, Image.Image):
+ buf = io.BytesIO()
+ ref.convert("RGB").save(buf, format="PNG")
+ return types.Part.from_bytes(data=buf.getvalue(), mime_type="image/png")
+ p = Path(ref)
+ if not p.is_file():
+ raise ModelError(f"reference image not found: {p}")
+ mime = "image/jpeg" if p.suffix.lower() in (".jpg", ".jpeg") else "image/png"
+ return types.Part.from_bytes(data=p.read_bytes(), mime_type=mime)
+
+
+def _is_model_missing(err: ModelError) -> bool:
+ s = str(err).lower()
+ return err.status == 404 or (err.status == 400 and ("not found" in s or "not supported" in s))
+
+
+def _record(usage: Usage, n_images: int) -> None:
+ """One ledger row per image batch (the image model is not a ChatModel, so
+ ``models.registry`` cannot meter it). Never raises."""
+ try:
+ from codeverse.cost import record_call
+ from codeverse.cost.types import Role, Stage
+
+ record_call(usage, stage=Stage.TEXTURE, role=Role.IMAGE, label="image",
+ backend="gemini-image", model=usage.model, n_calls=max(1, n_images))
+ except Exception: # noqa: BLE001 - accounting must never break a texture pass
+ pass
+
+
+class GeminiImageModel:
+ """See module docstring. ``model`` is the primary; ``fallback`` the second try."""
+
+ provider = "gemini"
+
+ def __init__(
+ self,
+ model: str = DEFAULT_IMAGE_MODEL,
+ *,
+ fallback: str | None = FALLBACK_IMAGE_MODEL,
+ keys: list[str] | None = None,
+ pool: KeyPool | None = None,
+ timeout_s: float = 180.0,
+ max_attempts: int = 4,
+ base_delay: float = 1.0,
+ max_delay: float = MAX_WAIT_S,
+ hedge: int = 1,
+ sleep: Callable[[float], None] = time.sleep,
+ client_factory: Callable[[str], Any] | None = None,
+ ) -> None:
+ self.model = model
+ self.fallback = fallback if fallback and fallback != model else None
+ #: no 503 hedge by default: an image is billed per image, so a hedge that
+ #: lands twice pays for two of them (the chat models default to 2)
+ self.hedge = max(1, int(hedge))
+ keys = list(keys) if keys is not None else _default_keys()
+ if pool is None and not keys:
+ raise ModelError("no Gemini API keys configured (GEMINI_API_KEYS / ~/.config/astra3d/gemini_keys.env)")
+ self.pool = pool or shared_pool(keys)
+ self.timeout_s = timeout_s
+ self.max_attempts = max(1, max_attempts)
+ self.base_delay = base_delay
+ self.max_delay = max_delay
+ self._sleep = sleep
+ # reuse GeminiModel's cached clients (same key → same genai.Client)
+ self._clients = GeminiModel(model, pool=self.pool, timeout_s=timeout_s, client_factory=client_factory)
+ self.storm_gate = self._clients.storm_gate
+ self._lock = threading.Lock()
+ self._primary_dead = False
+
+ @property
+ def id(self) -> str:
+ return f"gemini-image:{self.model}"
+
+ # ------------------------------------------------------------------ API
+ def generate(
+ self,
+ prompt: str,
+ *,
+ size: int = 1024,
+ n: int = 1,
+ seed: int | None = None,
+ reference_images: Sequence[Image.Image | Path | str] = (),
+ max_wait_s: float | None = None,
+ ) -> list[Image.Image]:
+ images, _ = self.generate_with_usage(prompt, size=size, n=n, seed=seed,
+ reference_images=reference_images, max_wait_s=max_wait_s)
+ return images
+
+ def generate_with_usage(
+ self,
+ prompt: str,
+ *,
+ size: int = 1024,
+ n: int = 1,
+ seed: int | None = None,
+ reference_images: Sequence[Image.Image | Path | str] = (),
+ max_wait_s: float | None = None,
+ ) -> tuple[list[Image.Image], Usage]:
+ """``max_wait_s`` is the caller's retry budget for ONE image (each of the
+ ``n`` images gets its own window, and a fallback model too), exactly like
+ ``ChatRequest.max_wait_s`` clips ``GeminiModel.generate``; ``None`` = the
+ full ``retry.RETRY_DEADLINE_S`` (900 s). Kept off the ``ImageModel``
+ protocol so fakes stay conformant; callers that hold a deadline pass it."""
+ if not prompt.strip():
+ raise ModelError("empty image prompt")
+ if n < 1:
+ raise ModelError("n must be >= 1")
+ images: list[Image.Image] = []
+ usage = Usage(backend="gemini-image", model=self.model)
+ for i in range(n):
+ got, u = self._one(prompt, size=size, seed=None if seed is None else seed + i,
+ refs=reference_images, max_wait_s=max_wait_s)
+ images.extend(got)
+ usage = usage + u
+ if len(images) > n:
+ images = images[:n]
+ _record(usage, len(images))
+ return images, usage
+
+ # ------------------------------------------------------------------ internals
+ def _models(self) -> list[str]:
+ with self._lock:
+ dead = self._primary_dead
+ order = [self.model] if not dead else []
+ if self.fallback:
+ order.append(self.fallback)
+ if not order:
+ order = [self.model]
+ return order
+
+ def _one(
+ self, prompt: str, *, size: int, seed: int | None,
+ refs: Sequence[Image.Image | Path | str], max_wait_s: float | None = None,
+ ) -> tuple[list[Image.Image], Usage]:
+ last: ModelError | None = None
+ for model in self._models():
+ try:
+ return self._attempts(model, prompt, size=size, seed=seed, refs=refs,
+ max_wait_s=max_wait_s)
+ except ModelError as err:
+ last = err
+ if model == self.model and self.fallback and (err.retryable or _is_model_missing(err)):
+ if _is_model_missing(err):
+ with self._lock:
+ self._primary_dead = True
+ log.warning("image model %s failed (%s); falling back to %s", model, err, self.fallback)
+ continue
+ raise
+ assert last is not None
+ raise last
+
+ def _attempts(
+ self, model: str, prompt: str, *, size: int, seed: int | None,
+ refs: Sequence[Image.Image | Path | str], max_wait_s: float | None = None,
+ ) -> tuple[list[Image.Image], Usage]:
+ parts: list[types.Part] = [_to_part(r) for r in refs]
+ parts.append(types.Part.from_text(text=prompt))
+ contents = [types.Content(role="user", parts=parts)]
+ config = types.GenerateContentConfig(
+ response_modalities=["IMAGE"],
+ image_config=types.ImageConfig(aspect_ratio="1:1", image_size=_IMAGE_SIZE_TOKEN.get(int(size), "1K")),
+ seed=seed,
+ http_options=types.HttpOptions(timeout=int(self.timeout_s * 1000)),
+ )
+ # the caller's budget clips the retry deadline, never extends it (the same
+ # contract as GeminiModel.generate with ChatRequest.max_wait_s), and each
+ # attempt's HTTP read timeout is the REMAINING budget, floored like
+ # GeminiModel._attempt_config — a 60 s image budget no longer holds a
+ # 180 s socket past its deadline.
+ budget = RETRY_DEADLINE_S if max_wait_s is None else min(RETRY_DEADLINE_S, float(max_wait_s))
+ deadline = time.monotonic() + budget
+
+ def _attempt_config() -> types.GenerateContentConfig:
+ remaining = max(HTTP_TIMEOUT_FLOOR_S, deadline - time.monotonic())
+ return clip_timeout(config, int(min(self.timeout_s, remaining) * 1000))
+
+ return rotate_with_retries(
+ self.pool,
+ lambda key: self._call(key, model, contents, _attempt_config(), size),
+ classify=classify_exception,
+ outcome_of=failure_outcome,
+ max_attempts=self.max_attempts,
+ base_delay=self.base_delay,
+ max_delay=self.max_delay,
+ max_total_s=budget,
+ hedge=self.hedge,
+ sleep=self._sleep,
+ retry_after=_retry_after_s,
+ tokens_of=lambda r: r[1].input_tokens,
+ storm_gate=self.storm_gate,
+ label=f"image {model}",
+ )
+
+ def _call(
+ self, key: str, model: str, contents: list[types.Content], config: types.GenerateContentConfig, size: int
+ ) -> tuple[list[Image.Image], Usage]:
+ client = self._clients._client(key)
+ with Stopwatch() as sw:
+ resp = client.models.generate_content(model=model, contents=contents, config=config)
+ usage = parse_usage(resp, model) # parsed first: the raises below were billed too
+ usage.backend = "gemini-image"
+ usage.latency_ms = sw.ms
+ pf = resp.prompt_feedback
+ if pf is not None and pf.block_reason:
+ raise ModelError(f"image prompt blocked: {pf.block_reason}", retryable=False, usage=usage)
+ if not resp.candidates:
+ raise ModelError("image model returned no candidates", retryable=True, usage=usage)
+ cand = resp.candidates[0]
+ finish = str(cand.finish_reason.name if cand.finish_reason is not None else "")
+ images: list[Image.Image] = []
+ for part in (cand.content.parts if cand.content and cand.content.parts else []):
+ blob = getattr(part, "inline_data", None)
+ if blob is not None and blob.data:
+ img = Image.open(io.BytesIO(blob.data))
+ img.load()
+ images.append(img.convert("RGB"))
+ if not images:
+ if finish in FATAL_FINISH:
+ raise ModelError(f"image generation refused (finish_reason={finish})",
+ retryable=False, usage=usage)
+ raise ModelError(f"image model returned no image (finish_reason={finish or 'unknown'})",
+ retryable=True, usage=usage)
+ usage.cost_usd = image_cost(model, usage, len(images))
+ if int(size) not in (0, 1024) and images[0].size != (size, size):
+ images = [im.resize((int(size), int(size)), Image.LANCZOS) for im in images]
+ return images, usage
diff --git a/harness/codeverse/models/gemini_convert.py b/harness/codeverse/models/gemini_convert.py
deleted file mode 100644
index 4c2075c2..00000000
--- a/harness/codeverse/models/gemini_convert.py
+++ /dev/null
@@ -1,257 +0,0 @@
-"""ChatRequest ⇄ google-genai types (contents, config, tools, response parsing).
-
-Kept separate from ``gemini.py`` (which owns clients, keys, retries) so each
-module stays small and the conversions are unit-testable offline.
-"""
-
-from __future__ import annotations
-
-import json
-import threading
-from typing import Any
-
-from google.genai import types
-
-from codeverse.contracts.chat import (
- ChatMessage,
- ChatRequest,
- ImagePart,
- TextPart,
- ToolCallPart,
- ToolResultPart,
- ToolSpec,
-)
-from codeverse.contracts.common import Usage
-from codeverse.models.base import ModelError
-from codeverse.models.parts import BoundedCache, image_bytes
-from codeverse.models.schema_utils import to_gemini_schema
-
-#: INTERFACES.md mapping; ``off`` → 0 where the model allows it
-THINKING_BUDGET: dict[str, int] = {"off": 0, "low": 1024, "medium": 4096, "high": 16384}
-
-#: finish reasons that are worth one more attempt (transient model glitches)
-RETRYABLE_FINISH = {"RECITATION", "MALFORMED_FUNCTION_CALL", "OTHER", "UNEXPECTED_TOOL_CALL"}
-#: finish reasons that will not improve by retrying
-FATAL_FINISH = {"SAFETY", "PROHIBITED_CONTENT", "BLOCKLIST", "SPII", "IMAGE_SAFETY"}
-
-
-#: Gemini 3 function calls carry an opaque ``thought_signature`` that MUST be
-#: echoed back with the call on the next turn. ``ToolCallPart`` has no slot for
-#: it, so we remember signatures by our synthetic call id (bounded LRU).
-SIGNATURES: BoundedCache[bytes] = BoundedCache(4096)
-_call_counter = [0]
-_call_lock = threading.Lock()
-
-#: prefix of the ids WE mint when the provider sent none (``extract_candidate``).
-#: A synthetic id exists only to pair ToolCallPart/ToolResultPart locally and is
-#: NEVER echoed back to the provider; a GENUINE provider id is echoed verbatim on
-#: both ``FunctionCall`` and ``FunctionResponse``.
-SYNTHETIC_CALL_ID_PREFIX = "synth-call-"
-
-
-def _next_call_id() -> str:
- with _call_lock:
- _call_counter[0] += 1
- return f"{SYNTHETIC_CALL_ID_PREFIX}{_call_counter[0]:06d}"
-
-
-def is_synthetic_call_id(call_id: str | None) -> bool:
- """True for ids minted here rather than issued by the provider."""
- return bool(call_id) and str(call_id).startswith(SYNTHETIC_CALL_ID_PREFIX)
-
-
-def _echo_id(call_id: str | None) -> str | None:
- """The id to send back to Gemini: the provider's own id verbatim, never a synthetic one."""
- return None if not call_id or is_synthetic_call_id(call_id) else str(call_id)
-
-
-# ------------------------------------------------------------------ contents
-def to_contents(messages: list[ChatMessage]) -> list[types.Content]:
- """ChatMessages → Gemini ``Content`` list. ``tool`` messages become a user
- turn of ``function_response`` parts (images attached as extra parts)."""
- out: list[types.Content] = []
- for msg in messages:
- role = "model" if msg.role == "assistant" else "user"
- parts: list[types.Part] = []
- for p in msg.parts:
- if isinstance(p, TextPart):
- if p.text:
- parts.append(types.Part.from_text(text=p.text))
- elif isinstance(p, ImagePart):
- raw, mime = image_bytes(p)
- if p.label:
- parts.append(types.Part.from_text(text=f"[image: {p.label}]"))
- parts.append(types.Part.from_bytes(data=raw, mime_type=mime))
- elif isinstance(p, ToolCallPart):
- part = types.Part(
- function_call=types.FunctionCall(
- name=p.name, args=dict(p.arguments), id=_echo_id(p.id)
- )
- )
- sig = SIGNATURES.get(p.id)
- if sig:
- part.thought_signature = sig
- parts.append(part)
- elif isinstance(p, ToolResultPart):
- parts.append(_function_response_part(p))
- for img in p.images:
- raw, mime = image_bytes(img)
- if img.label:
- parts.append(types.Part.from_text(text=f"[image: {img.label}]"))
- parts.append(types.Part.from_bytes(data=raw, mime_type=mime))
- if not parts:
- continue
- # merge consecutive same-role turns (Gemini wants strict alternation)
- if out and out[-1].role == role:
- out[-1].parts.extend(parts) # type: ignore[union-attr]
- else:
- out.append(types.Content(role=role, parts=parts))
- if not out:
- raise ModelError("ChatRequest has no content to send")
- return out
-
-
-def _function_response_part(p: ToolResultPart) -> types.Part:
- payload: dict[str, Any]
- try:
- parsed = json.loads(p.content)
- payload = parsed if isinstance(parsed, dict) else {"result": parsed}
- except (json.JSONDecodeError, TypeError):
- payload = {"result": p.content}
- if p.is_error:
- payload = {"error": payload.get("result", payload)} if "error" not in payload else payload
- return types.Part(
- function_response=types.FunctionResponse(name=p.name, response=payload, id=_echo_id(p.call_id))
- )
-
-
-# -------------------------------------------------------------------- config
-def to_tools(tools: list[ToolSpec]) -> list[types.Tool]:
- decls = [
- types.FunctionDeclaration(
- name=t.name,
- description=t.description,
- parameters=to_gemini_schema(t.parameters) if t.parameters else None,
- )
- for t in tools
- ]
- return [types.Tool(function_declarations=decls)]
-
-
-def build_config(
- request: ChatRequest,
- *,
- timeout_ms: int,
- use_thinking: bool = True,
- warnings: list[str] | None = None,
-) -> types.GenerateContentConfig:
- """Map a ChatRequest onto ``GenerateContentConfig``. Function calling and
- JSON mode are mutually exclusive on Gemini: with tools, the schema is
- dropped (the text is still parsed leniently) and a warning is recorded."""
- cfg: dict[str, Any] = {
- "temperature": request.temperature,
- "max_output_tokens": request.max_output_tokens,
- "http_options": types.HttpOptions(timeout=timeout_ms),
- }
- if request.system:
- cfg["system_instruction"] = request.system
- if use_thinking:
- cfg["thinking_config"] = types.ThinkingConfig(
- thinking_budget=THINKING_BUDGET[request.thinking], include_thoughts=False
- )
- if request.tools:
- cfg["tools"] = to_tools(request.tools)
- cfg["tool_config"] = types.ToolConfig(
- function_calling_config=types.FunctionCallingConfig(mode="AUTO")
- )
- cfg["automatic_function_calling"] = types.AutomaticFunctionCallingConfig(disable=True)
- if request.response_schema is not None and warnings is not None:
- warnings.append(
- "response_schema ignored: Gemini cannot combine function calling with JSON mode"
- )
- elif request.response_schema is not None:
- cfg["response_mime_type"] = "application/json"
- cfg["response_schema"] = to_gemini_schema(request.response_schema)
- return types.GenerateContentConfig(**cfg)
-
-
-def clip_timeout(
- config: types.GenerateContentConfig, timeout_ms: int
-) -> types.GenerateContentConfig:
- """A copy of ``config`` whose per-request HTTP timeout is ``timeout_ms`` (the
- SAME object when it already matches — the common full-budget case allocates
- nothing). :func:`build_config` owns the initial ``timeout_ms``; this is the
- one sanctioned way to shorten it for a single attempt whose remaining retry
- budget is smaller than the configured read timeout
- (``GeminiModel._attempt_config``)."""
- current = config.http_options.timeout if config.http_options is not None else None
- if current == timeout_ms:
- return config
- return config.model_copy(update={"http_options": types.HttpOptions(timeout=timeout_ms)})
-
-
-# ------------------------------------------------------------------ response
-def parse_usage(resp: types.GenerateContentResponse, model: str) -> Usage:
- um = resp.usage_metadata
- if um is None:
- return Usage(backend="gemini", model=model)
- return Usage(
- backend="gemini",
- model=resp.model_version or model,
- input_tokens=(um.prompt_token_count or 0) + (um.tool_use_prompt_token_count or 0),
- output_tokens=um.candidates_token_count or 0,
- cached_tokens=um.cached_content_token_count or 0,
- thoughts_tokens=um.thoughts_token_count or 0,
- )
-
-
-def extract_candidate(
- resp: types.GenerateContentResponse, usage: Usage | None = None
-) -> tuple[str, list[ToolCallPart], str]:
- """→ ``(text, tool_calls, finish_reason)``. Raises ``ModelError`` on blocked
- prompts (non-retryable) or empty candidates (retryable); ``usage`` (what the caller
- already parsed off ``resp``) rides on the error, because every one of these
- failures was billed."""
- pf = resp.prompt_feedback
- if pf is not None and pf.block_reason:
- raise ModelError(
- f"prompt blocked by Gemini: {pf.block_reason} {pf.block_reason_message or ''}".strip(),
- retryable=False, usage=usage,
- )
- if not resp.candidates:
- raise ModelError("Gemini returned no candidates", retryable=True, usage=usage)
- cand = resp.candidates[0]
- finish = str(cand.finish_reason.value if cand.finish_reason else "") or "UNKNOWN"
- texts: list[str] = []
- calls: list[ToolCallPart] = []
- for part in cand.content.parts if cand.content and cand.content.parts else []:
- if part.function_call is not None:
- fc = part.function_call
- # a genuine provider id is kept verbatim (and echoed back later); a synthetic
- # one is minted, marked by its prefix, only so the parts pair locally
- call_id = fc.id or _next_call_id()
- SIGNATURES.put(call_id, part.thought_signature)
- calls.append(
- ToolCallPart(id=call_id, name=fc.name or "", arguments=dict(fc.args or {}))
- )
- elif part.text and not part.thought:
- texts.append(part.text)
- text = "".join(texts)
- if not text and not calls:
- if finish in FATAL_FINISH:
- raise ModelError(
- f"Gemini produced no content (finish_reason={finish})", retryable=False, usage=usage
- )
- if finish == "MAX_TOKENS":
- # Gemini 3 models always think (budget 0 is accepted but ignored); a tiny
- # max_output_tokens is eaten by thoughts. Retrying cannot help — and this is
- # the most expensive failure on Gemini 3: every thought token was billed.
- thoughts = resp.usage_metadata.thoughts_token_count if resp.usage_metadata else None
- raise ModelError(
- f"Gemini produced no content: max_output_tokens exhausted by thinking "
- f"(thoughts_tokens={thoughts}); raise max_output_tokens",
- retryable=False, usage=usage,
- )
- raise ModelError(f"Gemini produced no content (finish_reason={finish})",
- retryable=True, usage=usage)
- return text, calls, finish
diff --git a/harness/codeverse/models/gemini_image.py b/harness/codeverse/models/gemini_image.py
deleted file mode 100644
index 2486556f..00000000
--- a/harness/codeverse/models/gemini_image.py
+++ /dev/null
@@ -1,333 +0,0 @@
-"""``GeminiImageModel`` — text (+ reference images) → PIL images via google-genai
-``generate_content(response_modalities=["IMAGE"])``.
-
-Shares the process-wide ``KeyPool`` / client cache / error classification with
-``GeminiModel`` (``models/gemini.py``), including its key-rotation semantics
-(``failure_outcome``): a 429 while an untried key remains is a FREE rotation
-(does not consume ``max_attempts``, 0.5 s courtesy pause); auth/permission
-errors classify as ``dead`` → rotate at once and bench the key only after a
-sibling key proves the request itself is fine (all keys dead → raise); 5xx /
-timeouts → exponential backoff; fatal finish reasons (safety) →
-``ModelError(retryable=False)``.
-A *fallback* model (default ``gemini-2.5-flash-image``) is tried when the primary
-model is rejected (404 / 400 "not found") or every attempt on it failed retryably.
-
-Cost: Gemini bills generated images as output tokens (≈1.1–1.3 k tokens per 1024²
-image) but the published per-image price is higher than the text-output rate, so
-``Usage.cost_usd`` is ``max(estimate_cost(tokens), n_images × IMAGE_USD[model])``
-(approximate; see ``IMAGE_USD``).
-
-Protocol (``ImageModel``): ``generate(prompt, *, size, n, seed, reference_images)
--> list[PIL.Image]`` and ``generate_with_usage(...) -> (images, Usage)``. Tests
-use ``codeverse.texturing.generate.FakeImageModel`` which implements the same.
-"""
-
-from __future__ import annotations
-
-import io
-import logging
-import threading
-import time
-from collections.abc import Callable, Sequence
-from pathlib import Path
-from typing import Any, Protocol, runtime_checkable
-
-from google.genai import types
-from PIL import Image
-
-from codeverse.contracts.common import Usage
-from codeverse.models.base import ModelError
-from codeverse.models.gemini import (
- HTTP_TIMEOUT_FLOOR_S,
- GeminiModel,
- _default_keys,
- _retry_after_s,
- classify_exception,
- failure_outcome,
- shared_pool,
-)
-from codeverse.models.gemini_convert import FATAL_FINISH, clip_timeout, parse_usage
-from codeverse.models.keypool import MAX_WAIT_S, KeyPool
-from codeverse.models.parts import Stopwatch
-from codeverse.models.pricing import estimate_cost
-from codeverse.models.retry import RETRY_DEADLINE_S, rotate_with_retries
-
-log = logging.getLogger(__name__)
-
-DEFAULT_IMAGE_MODEL = "gemini-3.1-flash-image"
-FALLBACK_IMAGE_MODEL = "gemini-2.5-flash-image"
-
-#: approximate USD per generated 1024² image (floor for cost accounting)
-IMAGE_USD: dict[str, float] = {
- "gemini-3.1-flash-image": 0.067,
- "gemini-2.5-flash-image": 0.039,
-}
-
-#: requested pixel size → Gemini ``image_size`` token
-_IMAGE_SIZE_TOKEN: dict[int, str] = {512: "1K", 1024: "1K", 2048: "2K", 4096: "4K"}
-
-
-@runtime_checkable
-class ImageModel(Protocol):
- """Text-to-image backend. Implementations must be thread-safe."""
-
- model: str
-
- @property
- def id(self) -> str: ...
-
- def generate(
- self,
- prompt: str,
- *,
- size: int = 1024,
- n: int = 1,
- seed: int | None = None,
- reference_images: Sequence[Image.Image | Path | str] = (),
- ) -> list[Image.Image]: ...
-
- def generate_with_usage(
- self,
- prompt: str,
- *,
- size: int = 1024,
- n: int = 1,
- seed: int | None = None,
- reference_images: Sequence[Image.Image | Path | str] = (),
- ) -> tuple[list[Image.Image], Usage]: ...
-
-
-def image_cost(model: str, usage: Usage, n_images: int) -> float:
- """Token-priced cost floored by the per-image price (approximate)."""
- token_cost = estimate_cost("gemini", model, usage)
- per_image = IMAGE_USD.get(model.strip().lower(), 0.0)
- return max(token_cost, per_image * max(0, n_images))
-
-
-def _to_part(ref: Image.Image | Path | str) -> types.Part:
- if isinstance(ref, Image.Image):
- buf = io.BytesIO()
- ref.convert("RGB").save(buf, format="PNG")
- return types.Part.from_bytes(data=buf.getvalue(), mime_type="image/png")
- p = Path(ref)
- if not p.is_file():
- raise ModelError(f"reference image not found: {p}")
- mime = "image/jpeg" if p.suffix.lower() in (".jpg", ".jpeg") else "image/png"
- return types.Part.from_bytes(data=p.read_bytes(), mime_type=mime)
-
-
-def _is_model_missing(err: ModelError) -> bool:
- s = str(err).lower()
- return err.status == 404 or (err.status == 400 and ("not found" in s or "not supported" in s))
-
-
-def _record(usage: Usage, n_images: int) -> None:
- """One ledger row per image batch (the image model is not a ChatModel, so
- ``models.registry`` cannot meter it). Never raises."""
- try:
- from codeverse.cost import record_call
- from codeverse.cost.types import Role, Stage
-
- record_call(usage, stage=Stage.TEXTURE, role=Role.IMAGE, label="image",
- backend="gemini-image", model=usage.model, n_calls=max(1, n_images))
- except Exception: # noqa: BLE001 - accounting must never break a texture pass
- pass
-
-
-class GeminiImageModel:
- """See module docstring. ``model`` is the primary; ``fallback`` the second try."""
-
- provider = "gemini"
-
- def __init__(
- self,
- model: str = DEFAULT_IMAGE_MODEL,
- *,
- fallback: str | None = FALLBACK_IMAGE_MODEL,
- keys: list[str] | None = None,
- pool: KeyPool | None = None,
- timeout_s: float = 180.0,
- max_attempts: int = 4,
- base_delay: float = 1.0,
- max_delay: float = MAX_WAIT_S,
- hedge: int = 1,
- sleep: Callable[[float], None] = time.sleep,
- client_factory: Callable[[str], Any] | None = None,
- ) -> None:
- self.model = model
- self.fallback = fallback if fallback and fallback != model else None
- #: no 503 hedge by default: an image is billed per image, so a hedge that
- #: lands twice pays for two of them (the chat models default to 2)
- self.hedge = max(1, int(hedge))
- keys = list(keys) if keys is not None else _default_keys()
- if pool is None and not keys:
- raise ModelError("no Gemini API keys configured (GEMINI_API_KEYS / ~/.config/astra3d/gemini_keys.env)")
- self.pool = pool or shared_pool(keys)
- self.timeout_s = timeout_s
- self.max_attempts = max(1, max_attempts)
- self.base_delay = base_delay
- self.max_delay = max_delay
- self._sleep = sleep
- # reuse GeminiModel's cached clients (same key → same genai.Client)
- self._clients = GeminiModel(model, pool=self.pool, timeout_s=timeout_s, client_factory=client_factory)
- self.storm_gate = self._clients.storm_gate
- self._lock = threading.Lock()
- self._primary_dead = False
-
- @property
- def id(self) -> str:
- return f"gemini-image:{self.model}"
-
- # ------------------------------------------------------------------ API
- def generate(
- self,
- prompt: str,
- *,
- size: int = 1024,
- n: int = 1,
- seed: int | None = None,
- reference_images: Sequence[Image.Image | Path | str] = (),
- max_wait_s: float | None = None,
- ) -> list[Image.Image]:
- images, _ = self.generate_with_usage(prompt, size=size, n=n, seed=seed,
- reference_images=reference_images, max_wait_s=max_wait_s)
- return images
-
- def generate_with_usage(
- self,
- prompt: str,
- *,
- size: int = 1024,
- n: int = 1,
- seed: int | None = None,
- reference_images: Sequence[Image.Image | Path | str] = (),
- max_wait_s: float | None = None,
- ) -> tuple[list[Image.Image], Usage]:
- """``max_wait_s`` is the caller's retry budget for ONE image (each of the
- ``n`` images gets its own window, and a fallback model too), exactly like
- ``ChatRequest.max_wait_s`` clips ``GeminiModel.generate``; ``None`` = the
- full ``retry.RETRY_DEADLINE_S`` (900 s). Kept off the ``ImageModel``
- protocol so fakes stay conformant; callers that hold a deadline pass it."""
- if not prompt.strip():
- raise ModelError("empty image prompt")
- if n < 1:
- raise ModelError("n must be >= 1")
- images: list[Image.Image] = []
- usage = Usage(backend="gemini-image", model=self.model)
- for i in range(n):
- got, u = self._one(prompt, size=size, seed=None if seed is None else seed + i,
- refs=reference_images, max_wait_s=max_wait_s)
- images.extend(got)
- usage = usage + u
- if len(images) > n:
- images = images[:n]
- _record(usage, len(images))
- return images, usage
-
- # ------------------------------------------------------------------ internals
- def _models(self) -> list[str]:
- with self._lock:
- dead = self._primary_dead
- order = [self.model] if not dead else []
- if self.fallback:
- order.append(self.fallback)
- if not order:
- order = [self.model]
- return order
-
- def _one(
- self, prompt: str, *, size: int, seed: int | None,
- refs: Sequence[Image.Image | Path | str], max_wait_s: float | None = None,
- ) -> tuple[list[Image.Image], Usage]:
- last: ModelError | None = None
- for model in self._models():
- try:
- return self._attempts(model, prompt, size=size, seed=seed, refs=refs,
- max_wait_s=max_wait_s)
- except ModelError as err:
- last = err
- if model == self.model and self.fallback and (err.retryable or _is_model_missing(err)):
- if _is_model_missing(err):
- with self._lock:
- self._primary_dead = True
- log.warning("image model %s failed (%s); falling back to %s", model, err, self.fallback)
- continue
- raise
- assert last is not None
- raise last
-
- def _attempts(
- self, model: str, prompt: str, *, size: int, seed: int | None,
- refs: Sequence[Image.Image | Path | str], max_wait_s: float | None = None,
- ) -> tuple[list[Image.Image], Usage]:
- parts: list[types.Part] = [_to_part(r) for r in refs]
- parts.append(types.Part.from_text(text=prompt))
- contents = [types.Content(role="user", parts=parts)]
- config = types.GenerateContentConfig(
- response_modalities=["IMAGE"],
- image_config=types.ImageConfig(aspect_ratio="1:1", image_size=_IMAGE_SIZE_TOKEN.get(int(size), "1K")),
- seed=seed,
- http_options=types.HttpOptions(timeout=int(self.timeout_s * 1000)),
- )
- # the caller's budget clips the retry deadline, never extends it (the same
- # contract as GeminiModel.generate with ChatRequest.max_wait_s), and each
- # attempt's HTTP read timeout is the REMAINING budget, floored like
- # GeminiModel._attempt_config — a 60 s image budget no longer holds a
- # 180 s socket past its deadline.
- budget = RETRY_DEADLINE_S if max_wait_s is None else min(RETRY_DEADLINE_S, float(max_wait_s))
- deadline = time.monotonic() + budget
-
- def _attempt_config() -> types.GenerateContentConfig:
- remaining = max(HTTP_TIMEOUT_FLOOR_S, deadline - time.monotonic())
- return clip_timeout(config, int(min(self.timeout_s, remaining) * 1000))
-
- return rotate_with_retries(
- self.pool,
- lambda key: self._call(key, model, contents, _attempt_config(), size),
- classify=classify_exception,
- outcome_of=failure_outcome,
- max_attempts=self.max_attempts,
- base_delay=self.base_delay,
- max_delay=self.max_delay,
- max_total_s=budget,
- hedge=self.hedge,
- sleep=self._sleep,
- retry_after=_retry_after_s,
- tokens_of=lambda r: r[1].input_tokens,
- storm_gate=self.storm_gate,
- label=f"image {model}",
- )
-
- def _call(
- self, key: str, model: str, contents: list[types.Content], config: types.GenerateContentConfig, size: int
- ) -> tuple[list[Image.Image], Usage]:
- client = self._clients._client(key)
- with Stopwatch() as sw:
- resp = client.models.generate_content(model=model, contents=contents, config=config)
- usage = parse_usage(resp, model) # parsed first: the raises below were billed too
- usage.backend = "gemini-image"
- usage.latency_ms = sw.ms
- pf = resp.prompt_feedback
- if pf is not None and pf.block_reason:
- raise ModelError(f"image prompt blocked: {pf.block_reason}", retryable=False, usage=usage)
- if not resp.candidates:
- raise ModelError("image model returned no candidates", retryable=True, usage=usage)
- cand = resp.candidates[0]
- finish = str(cand.finish_reason.name if cand.finish_reason is not None else "")
- images: list[Image.Image] = []
- for part in (cand.content.parts if cand.content and cand.content.parts else []):
- blob = getattr(part, "inline_data", None)
- if blob is not None and blob.data:
- img = Image.open(io.BytesIO(blob.data))
- img.load()
- images.append(img.convert("RGB"))
- if not images:
- if finish in FATAL_FINISH:
- raise ModelError(f"image generation refused (finish_reason={finish})",
- retryable=False, usage=usage)
- raise ModelError(f"image model returned no image (finish_reason={finish or 'unknown'})",
- retryable=True, usage=usage)
- usage.cost_usd = image_cost(model, usage, len(images))
- if int(size) not in (0, 1024) and images[0].size != (size, size):
- images = [im.resize((int(size), int(size)), Image.LANCZOS) for im in images]
- return images, usage
diff --git a/harness/codeverse/models/keypool.py b/harness/codeverse/models/keypool.py
deleted file mode 100644
index 69952b55..00000000
--- a/harness/codeverse/models/keypool.py
+++ /dev/null
@@ -1,428 +0,0 @@
-"""Multi-key pool with per-key rate limiting, 429 cooldown and a health score.
-
-Used by ``GeminiModel`` (22 keys on the owner's box) but provider-neutral.
-
-* ``acquire()`` picks the next healthy key round-robin, honouring per-key
- RPM / TPM token buckets and 429 cool-downs; it blocks (bounded) when every
- key is throttled and raises ``KeyPoolExhausted`` after ``timeout_s``.
- ``tokens_hint`` reserves the pending call's estimated prompt tokens, so a
- 200 k-token judge verdict and a 2 k-token caption are scheduled differently
- (``docs/COST.md`` Part III); ``max_in_flight`` additionally caps how many calls
- may be out at once, and :meth:`KeyPool.release` (a ``finally`` in
- ``rotate_with_retries``) hands the slot back. ``try_acquire()`` is the
- never-waiting variant a hedged retry uses for its extra keys.
-* ``report(key, outcome)`` feeds back ``ok | 429 | 5xx | error | dead`` so the
- pool can cool a key down and adjust its health score. ``dead`` is for
- key-scoped auth/permission failures (revoked / suspended / invalid key): the
- key is benched for ``dead_cooldown_s`` (default one hour) and re-probed once
- that elapses — a dead key must never keep failing its share of calls.
- ``report(..., tokens=actual, reserved=hint)`` reconciles the reservation with
- the provider's real prompt-token count (refund or top-up).
-* ``stats()`` exposes counters for logs / ``3dcv doctor --live``: per-key health
- and cooldown, pool RPM/TPM capacity and headroom, in-flight and peak in-flight.
-
-Thread-safe; ``clock`` / ``sleep`` are injectable for deterministic tests.
-"""
-
-from __future__ import annotations
-
-import threading
-import time
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from typing import Any, Literal
-
-Outcome = Literal["ok", "429", "5xx", "error", "dead"]
-
-
-class KeyPoolExhausted(RuntimeError):
- """Every key is cooling down / throttled and the wait budget ran out."""
-
-
-MAX_WAIT_S = 3.0
-"""The longest any single retry / cooldown wait may be (seconds).
-
-House rule (owner, 2026-08-24, tightened 5 s -> 3 s on 2026-08-27): with 22 keys
-there is always another key to try, so the harness rotates rather than sitting
-out a long backoff. Patience comes from the NUMBER of attempts, never from the
-length of one sleep. This is the single source for every wait — generic
-backoff, storm sleeps, 429 cooldowns and the storm gate's park all clip to it.
-"""
-
-ACQUIRE_TIMEOUT_S = 120.0
-"""Default total wait budget of one :meth:`KeyPool.acquire` (seconds).
-
-Covers BOTH the ``max_in_flight`` slot wait and the key/cooldown wait; a caller
-with a deadline passes something smaller (``retry.rotate_with_retries`` passes
-``min(ACQUIRE_TIMEOUT_S, remaining budget)``). ``None`` waits forever.
-"""
-
-
-@dataclass
-class TokenBucket:
- """Classic token bucket: ``capacity`` tokens, refilled at ``rate`` per second."""
-
- capacity: float
- rate: float
- tokens: float = field(default=0.0)
- updated: float = field(default=0.0)
-
- def __post_init__(self) -> None:
- self.tokens = self.capacity
-
- def _refill(self, now: float) -> None:
- if now > self.updated:
- self.tokens = min(self.capacity, self.tokens + (now - self.updated) * self.rate)
- self.updated = now
-
- def try_take(self, n: float, now: float) -> bool:
- self._refill(now)
- if self.tokens >= n:
- self.tokens -= n
- return True
- return False
-
- def charge(self, n: float, now: float) -> None:
- """Take ``n`` tokens unconditionally; ``n < 0`` gives tokens back.
-
- Unlike :meth:`try_take` the bucket is allowed to go negative, so an
- under-estimated reservation is paid off by the next refill instead of
- being silently forgiven. Used to reconcile a TPM reservation with the
- provider's real prompt-token count."""
- self._refill(now)
- self.tokens = min(self.capacity, self.tokens - n)
-
- def wait_for(self, n: float, now: float) -> float:
- """Seconds until ``n`` tokens are available (0 if already)."""
- self._refill(now)
- if self.tokens >= n:
- return 0.0
- return (n - self.tokens) / self.rate if self.rate > 0 else float("inf")
-
- def headroom(self, now: float) -> float:
- """Fraction of capacity currently available (0.0 – 1.0)."""
- self._refill(now)
- return max(0.0, min(1.0, self.tokens / self.capacity)) if self.capacity > 0 else 1.0
-
-
-@dataclass
-class _KeyState:
- key: str
- rpm: TokenBucket
- tpm: TokenBucket | None
- health: float = 1.0
- cooldown_until: float = 0.0
- dead_until: float = 0.0
- n_ok: int = 0
- n_429: int = 0
- n_5xx: int = 0
- n_error: int = 0
- n_dead: int = 0
- n_acquired: int = 0
- tokens_used: int = 0
- last_used: float = 0.0
- health_ts: float = 0.0
-
- def recover(self, now: float, rate: float = 0.01) -> None:
- """Passive health recovery: +``rate`` per idle second, capped at 1.0."""
- if now > self.health_ts:
- self.health = min(1.0, self.health + (now - self.health_ts) * rate)
- self.health_ts = now
-
- def available_at(self, now: float, tokens_hint: int) -> float:
- """Earliest time this key can be used (``now`` if ready)."""
- t = max(now, self.cooldown_until)
- t = max(t, now + self.rpm.wait_for(1.0, now))
- if self.tpm is not None and tokens_hint > 0:
- t = max(t, now + self.tpm.wait_for(float(tokens_hint), now))
- return t
-
-
-class KeyPool:
- """Round-robin key pool with per-key limiters. See module docstring."""
-
- def __init__(
- self,
- keys: list[str] | tuple[str, ...],
- *,
- rpm_per_key: int = 900,
- tpm_per_key: int | None = None,
- max_in_flight: int = 0,
- cooldown_s: float = MAX_WAIT_S,
- dead_cooldown_s: float = 3600.0,
- min_health: float = 0.3,
- clock: Callable[[], float] = time.monotonic,
- sleep: Callable[[float], None] = time.sleep,
- ) -> None:
- uniq = [k for i, k in enumerate(keys) if k and k not in keys[:i]]
- if not uniq:
- raise ValueError("KeyPool needs at least one non-empty key")
- self._clock = clock
- self._sleep = sleep
- self._cooldown_s = float(cooldown_s)
- self._dead_cooldown_s = float(dead_cooldown_s)
- self._min_health = min_health
- self._lock = threading.Lock()
- self._rr = 0
- self._in_flight = 0
- self._peak_in_flight = 0
- # Process-wide ceiling on concurrent model calls, independent of the caller's
- # thread pools: blender/node/chrome workers are CPU-bound and sized by cores,
- # while this is sized by the provider (docs/COST.md Part III). 0 = unlimited.
- self._max_in_flight = int(max_in_flight or 0)
- self._slots = threading.BoundedSemaphore(self._max_in_flight) if self._max_in_flight else None
- now = clock()
- self._states: list[_KeyState] = []
- for k in uniq:
- rpm = TokenBucket(capacity=float(rpm_per_key), rate=rpm_per_key / 60.0, updated=now)
- tpm = None
- if tpm_per_key:
- tpm = TokenBucket(capacity=float(tpm_per_key), rate=tpm_per_key / 60.0, updated=now)
- self._states.append(_KeyState(key=k, rpm=rpm, tpm=tpm, health_ts=now))
- self._by_key = {s.key: s for s in self._states}
-
- # ------------------------------------------------------------------ public
- def __len__(self) -> int:
- return len(self._states)
-
- @property
- def keys(self) -> list[str]:
- return [s.key for s in self._states]
-
- def acquire(
- self,
- *,
- tokens_hint: int = 0,
- exclude: set[str] | frozenset[str] | None = None,
- timeout_s: float | None = ACQUIRE_TIMEOUT_S,
- ) -> str:
- """Return the next usable key, blocking (bounded by ``timeout_s``) while all
- keys are throttled. ``exclude`` skips keys that already failed this call.
- Raises ``KeyPoolExhausted`` at once when no key can become available before
- the deadline (e.g. every key is dead) — availability only moves later.
-
- ``tokens_hint`` is the estimated prompt tokens of the pending call: they
- are reserved in the chosen key's TPM bucket now and reconciled by
- :meth:`report`. When ``max_in_flight`` is set the call also waits for a
- free concurrency slot; :meth:`release` hands it back. ``timeout_s`` bounds
- the slot wait AND the key wait together (``None`` = wait forever): the slot
- wait used to be unbounded, so a caller 20 s from its deadline could sit on
- the semaphore for minutes."""
- if self._slots is not None:
- t0 = self._clock()
- if not self._slots.acquire(timeout=timeout_s):
- raise KeyPoolExhausted(
- f"all {self._max_in_flight} in-flight slots busy; waited {timeout_s}s"
- )
- if timeout_s is not None:
- # the slot wait spent part of the budget; the key wait gets the rest
- timeout_s = max(0.0, timeout_s - (self._clock() - t0))
- try:
- return self._acquire_key(tokens_hint, exclude, timeout_s)
- except BaseException:
- if self._slots is not None:
- self._slots.release()
- raise
-
- def try_acquire(
- self,
- *,
- tokens_hint: int = 0,
- exclude: set[str] | frozenset[str] | None = None,
- ) -> str | None:
- """:meth:`acquire` that never waits: a key usable *right now* (and a free
- ``max_in_flight`` slot), else ``None`` — nothing is reserved or counted then.
-
- For the extra keys of a hedged retry (``rotate_with_retries(hedge=...)``): the
- primary request is already in flight, so a partner that is not free at once
- is not worth waiting for. A returned key holds a slot like any other and
- must be :meth:`release`-d."""
- if self._slots is not None and not self._slots.acquire(blocking=False):
- return None
- try:
- return self._acquire_key(tokens_hint, exclude, 0.0)
- except KeyPoolExhausted:
- if self._slots is not None:
- self._slots.release()
- return None
- except BaseException:
- if self._slots is not None:
- self._slots.release()
- raise
-
- def _acquire_key(
- self,
- tokens_hint: int,
- exclude: set[str] | frozenset[str] | None,
- timeout_s: float | None,
- ) -> str:
- deadline = None if timeout_s is None else self._clock() + timeout_s
- while True:
- with self._lock:
- now = self._clock()
- chosen = self._pick(now, tokens_hint, exclude or ())
- if chosen is not None:
- chosen.rpm.try_take(1.0, now)
- if chosen.tpm is not None and tokens_hint > 0:
- chosen.tpm.try_take(float(tokens_hint), now)
- chosen.n_acquired += 1
- chosen.last_used = now
- self._in_flight += 1
- self._peak_in_flight = max(self._peak_in_flight, self._in_flight)
- return chosen.key
- soonest = min(
- (
- s.available_at(now, tokens_hint)
- for s in self._states
- if s.key not in (exclude or ())
- ),
- default=float("inf"),
- )
- if soonest == float("inf"):
- raise KeyPoolExhausted("all keys excluded")
- if deadline is not None and soonest > deadline:
- raise KeyPoolExhausted(
- f"all {len(self._states)} keys throttled or dead; the earliest becomes "
- f"available in {soonest - now:.0f}s (> {timeout_s}s wait budget)"
- )
- wait = max(0.01, min(soonest - now, MAX_WAIT_S))
- if deadline is not None and self._clock() + wait > deadline:
- raise KeyPoolExhausted(
- f"all {len(self._states)} keys throttled; waited {timeout_s}s"
- )
- self._sleep(wait)
-
- def release(self) -> None:
- """Mark one :meth:`acquire`-d call finished (call it in a ``finally``).
-
- Frees the in-flight gauge and the ``max_in_flight`` slot; outcome
- accounting is :meth:`report`, which may legitimately be called more than
- once for one call (a key that looked dead is reported again once a
- sibling proves the request fine). A stray ``release`` is a no-op."""
- with self._lock:
- if self._in_flight <= 0:
- return
- self._in_flight -= 1
- if self._slots is not None:
- self._slots.release()
-
- def report(
- self,
- key: str,
- outcome: Outcome,
- *,
- tokens: int = 0,
- reserved: int = 0,
- retry_after_s: float | None = None,
- ) -> None:
- """Feed back the result of a call made with ``key``.
-
- ``tokens`` is what the provider says the call really cost (prompt
- tokens); ``reserved`` is the ``tokens_hint`` :meth:`acquire` already took
- out of the TPM bucket for it. The pool charges the *difference*, so an
- over-estimate is refunded and an under-estimate is paid off — pass both,
- or neither, and never the same tokens twice."""
- with self._lock:
- st = self._by_key.get(key)
- if st is None:
- return
- now = self._clock()
- st.recover(now)
- if outcome == "ok":
- st.n_ok += 1
- st.health = min(1.0, st.health + 0.2 * (1.0 - st.health))
- elif outcome == "429":
- st.n_429 += 1
- st.health *= 0.5
- cool = retry_after_s if retry_after_s and retry_after_s > 0 else self._cooldown_s
- # House rule (owner, 2026-08-24): no single wait exceeds MAX_WAIT_S — we
- # rotate to another key instead of sitting out a provider's suggested delay.
- cool = min(cool, MAX_WAIT_S)
- st.cooldown_until = max(st.cooldown_until, now + cool)
- elif outcome == "5xx":
- st.n_5xx += 1
- st.health *= 0.8
- elif outcome == "dead":
- # key-scoped failure: bench it; re-probed once the long cooldown passes
- st.n_dead += 1
- st.health = 0.0
- st.dead_until = max(st.dead_until, now + self._dead_cooldown_s)
- st.cooldown_until = max(st.cooldown_until, st.dead_until)
- else:
- st.n_error += 1
- st.health *= 0.9
- if st.tpm is not None and (tokens or reserved):
- # reconcile the reservation with reality; a call that never reached
- # the model (429 / capacity storm) reports tokens=0 and is refunded
- st.tpm.charge(float(tokens) - float(reserved), now)
- st.tokens_used += max(0, int(tokens))
-
- def stats(self) -> dict[str, Any]:
- """Counters per key (keys are redacted to their last 4 chars)."""
- with self._lock:
- now = self._clock()
- per_key = [
- {
- "key": f"…{s.key[-4:]}",
- "health": round(s.health, 3),
- "cooldown_s": round(max(0.0, s.cooldown_until - now), 1),
- "rpm_tokens": round(s.rpm.tokens, 1),
- "rpm_headroom": round(s.rpm.headroom(now), 3),
- "tpm_headroom": None if s.tpm is None else round(s.tpm.headroom(now), 3),
- "tokens_used": s.tokens_used,
- "acquired": s.n_acquired,
- "ok": s.n_ok,
- "429": s.n_429,
- "5xx": s.n_5xx,
- "error": s.n_error,
- "dead": s.n_dead,
- }
- for s in self._states
- ]
- n = len(self._states)
- return {
- "n_keys": n,
- "n_cooling": sum(1 for s in self._states if s.cooldown_until > now),
- "n_dead": sum(1 for s in self._states if s.dead_until > now),
- "in_flight": self._in_flight,
- "peak_in_flight": self._peak_in_flight,
- "rpm_capacity": int(sum(s.rpm.capacity for s in self._states)),
- "tpm_capacity": int(sum(s.tpm.capacity for s in self._states if s.tpm)),
- "rpm_headroom": round(sum(s.rpm.headroom(now) for s in self._states) / n, 3),
- "tpm_headroom": (
- None if self._states[0].tpm is None
- else round(sum(s.tpm.headroom(now) for s in self._states if s.tpm) / n, 3)
- ),
- "tokens_used": sum(s.tokens_used for s in self._states),
- "acquired": sum(s.n_acquired for s in self._states),
- "ok": sum(s.n_ok for s in self._states),
- "429": sum(s.n_429 for s in self._states),
- "5xx": sum(s.n_5xx for s in self._states),
- "error": sum(s.n_error for s in self._states),
- "dead": sum(s.n_dead for s in self._states),
- "keys": per_key,
- }
-
- # ----------------------------------------------------------------- private
- def _pick(self, now: float, tokens_hint: int, exclude) -> _KeyState | None:
- """Round-robin scan; prefer the first healthy, ready key; otherwise the
- healthiest ready key. Advances the RR cursor past the chosen key."""
- n = len(self._states)
- best: _KeyState | None = None
- best_idx = -1
- for step in range(n):
- idx = (self._rr + step) % n
- st = self._states[idx]
- if st.key in exclude:
- continue
- st.recover(now)
- if st.available_at(now, tokens_hint) > now:
- continue
- if st.health >= self._min_health:
- self._rr = (idx + 1) % n
- return st
- if best is None or st.health > best.health:
- best, best_idx = st, idx
- if best is not None:
- self._rr = (best_idx + 1) % n
- return best
diff --git a/harness/codeverse/models/openai.py b/harness/codeverse/models/openai.py
index bf1ebe16..bfe392da 100644
--- a/harness/codeverse/models/openai.py
+++ b/harness/codeverse/models/openai.py
@@ -1,26 +1,202 @@
-"""``OpenAIModel`` — Chat Completions backend (images as data URLs, function
-tools, ``json_schema`` response_format with strict→non-strict fallback,
-``reasoning_effort`` for o*/gpt-5* models, usage/cost, ``OPENAI_BASE_URL``).
+"""ChatRequest ⇄ OpenAI Chat Completions dicts (messages, tools, response_format).
+
+Chat Completions (not Responses) was chosen because every OpenAI-compatible
+endpoint (``OPENAI_BASE_URL``: vLLM, OpenRouter, Ollama, …) speaks it, while
+the Responses API is OpenAI-only.
"""
from __future__ import annotations
+import json
import logging
import threading
import time
from collections.abc import Callable
from typing import Any
-from codeverse.contracts.chat import ChatRequest, ChatResponse
+from codeverse.contracts.chat import (
+ ChatMessage,
+ ChatRequest,
+ ChatResponse,
+ ImagePart,
+ TextPart,
+ ToolCallPart,
+ ToolResultPart,
+ ToolSpec,
+)
from codeverse.contracts.common import Usage
from codeverse.models.base import ModelError
-from codeverse.models.keypool import MAX_WAIT_S
-from codeverse.models.openai_convert import build_kwargs, parse_choice
-from codeverse.models.parts import Stopwatch
+from codeverse.models.parts import Stopwatch, image_b64
from codeverse.models.pricing import estimate_cost
-from codeverse.models.retry import with_retries
-from codeverse.models.schema_utils import JsonParseError, parse_json_lenient
+from codeverse.models.retry import MAX_WAIT_S, with_retries
+from codeverse.models.schema_utils import (
+ JsonParseError,
+ inline_refs,
+ parse_json_lenient,
+ to_openai_strict_schema,
+)
+
+SCHEMA_NAME = "response"
+
+
+# ------------------------------------------------------------- model families
+def is_reasoning_model(model: str) -> bool:
+ m = model.lower()
+ return m.startswith(("o1", "o3", "o4", "gpt-5"))
+
+
+def reasoning_effort(model: str, thinking: str) -> str | None:
+ """Map ``thinking`` onto ``reasoning_effort`` (None for non-reasoning models)."""
+ if not is_reasoning_model(model):
+ return None
+ m = model.lower()
+ if thinking == "off":
+ if m.startswith("gpt-5.") and not m.startswith("gpt-5.0"):
+ return "none" # gpt-5.1+ accept "none"
+ if m.startswith("gpt-5"):
+ return "minimal"
+ return "low" # o-series has no off switch
+ return thinking
+
+
+# ------------------------------------------------------------------ messages
+def _image_block(p: ImagePart) -> dict[str, Any]:
+ data, mime = image_b64(p)
+ return {
+ "type": "image_url",
+ "image_url": {"url": f"data:{mime};base64,{data}", "detail": "auto"},
+ }
+
+
+def to_messages(messages: list[ChatMessage], system: str) -> list[dict[str, Any]]:
+ """ChatMessages → Chat Completions messages. Tool results become ``role:
+ tool`` messages; images inside tool results (unsupported there) are sent as
+ a follow-up user message."""
+ out: list[dict[str, Any]] = []
+ if system:
+ out.append({"role": "system", "content": system})
+ for msg in messages:
+ if msg.role == "assistant":
+ out.append(_assistant_message(msg))
+ continue
+ trailing_images: list[dict[str, Any]] = []
+ content: list[dict[str, Any]] = []
+ for p in msg.parts:
+ if isinstance(p, TextPart):
+ if p.text:
+ content.append({"type": "text", "text": p.text})
+ elif isinstance(p, ImagePart):
+ if p.label:
+ content.append({"type": "text", "text": f"[image: {p.label}]"})
+ content.append(_image_block(p))
+ elif isinstance(p, ToolResultPart):
+ if content:
+ out.append({"role": "user", "content": content})
+ content = []
+ out.append(
+ {
+ "role": "tool",
+ "tool_call_id": p.call_id,
+ "content": p.content or "(no output)",
+ }
+ )
+ for img in p.images:
+ if img.label:
+ trailing_images.append(
+ {"type": "text", "text": f"[image from {p.name}: {img.label}]"}
+ )
+ trailing_images.append(_image_block(img))
+ elif isinstance(p, ToolCallPart):
+ raise ModelError("ToolCallPart is only valid in assistant messages")
+ if content:
+ out.append({"role": "user", "content": content})
+ if trailing_images:
+ out.append({"role": "user", "content": trailing_images})
+ if not out or all(m["role"] == "system" for m in out):
+ raise ModelError("ChatRequest has no content to send")
+ return out
+
+
+def _assistant_message(msg: ChatMessage) -> dict[str, Any]:
+ text = "".join(p.text for p in msg.parts if isinstance(p, TextPart))
+ calls = [
+ {
+ "id": p.id,
+ "type": "function",
+ "function": {"name": p.name, "arguments": json.dumps(p.arguments)},
+ }
+ for p in msg.parts
+ if isinstance(p, ToolCallPart)
+ ]
+ m: dict[str, Any] = {"role": "assistant", "content": text or None}
+ if calls:
+ m["tool_calls"] = calls
+ return m
+
+
+# --------------------------------------------------------------------- tools
+def to_tool(t: ToolSpec) -> dict[str, Any]:
+ params = inline_refs(t.parameters) if t.parameters else {"type": "object", "properties": {}}
+ return {
+ "type": "function",
+ "function": {"name": t.name, "description": t.description, "parameters": params},
+ }
+
+
+def response_format(schema: dict[str, Any], *, strict: bool) -> dict[str, Any]:
+ body = to_openai_strict_schema(schema) if strict else inline_refs(schema)
+ return {
+ "type": "json_schema",
+ "json_schema": {"name": SCHEMA_NAME, "schema": body, "strict": strict},
+ }
+
+
+# ------------------------------------------------------------------- request
+def build_kwargs(request: ChatRequest, model: str, *, strict_schema: bool) -> dict[str, Any]:
+ """``client.chat.completions.create(**kwargs)`` minus ``model``."""
+ kw: dict[str, Any] = {
+ "messages": to_messages(request.messages, request.system),
+ "max_completion_tokens": request.max_output_tokens,
+ }
+ effort = reasoning_effort(model, request.thinking)
+ if effort is not None:
+ kw["reasoning_effort"] = effort
+ else:
+ kw["temperature"] = request.temperature
+ if request.tools:
+ kw["tools"] = [to_tool(t) for t in request.tools]
+ kw["tool_choice"] = "auto"
+ if request.response_schema is not None:
+ kw["response_format"] = response_format(request.response_schema, strict=strict_schema)
+ return kw
+
+
+# ------------------------------------------------------------------ response
+def parse_choice(choice: Any) -> tuple[str, list[ToolCallPart], str]:
+ """→ ``(text, tool_calls, finish_reason)``; bad tool-call JSON → ModelError(retryable)."""
+ msg = choice.message
+ text = msg.content or ""
+ if getattr(msg, "refusal", None):
+ raise ModelError(f"OpenAI refusal: {msg.refusal}", retryable=False)
+ calls: list[ToolCallPart] = []
+ for tc in msg.tool_calls or []:
+ fn = getattr(tc, "function", None)
+ if fn is None:
+ continue
+ try:
+ args = json.loads(fn.arguments or "{}")
+ except json.JSONDecodeError as exc:
+ raise ModelError(
+ f"tool call {fn.name} has invalid JSON arguments: {exc}", retryable=True
+ ) from exc
+ if not isinstance(args, dict):
+ args = {"value": args}
+ calls.append(ToolCallPart(id=tc.id, name=fn.name, arguments=args))
+ return text, calls, str(choice.finish_reason or "")
+
+# ===================================================================== openai
+# (merged from codeverse/models/openai.py, 2026-08-28)
log = logging.getLogger(__name__)
diff --git a/harness/codeverse/models/openai_convert.py b/harness/codeverse/models/openai_convert.py
deleted file mode 100644
index a9c08c04..00000000
--- a/harness/codeverse/models/openai_convert.py
+++ /dev/null
@@ -1,182 +0,0 @@
-"""ChatRequest ⇄ OpenAI Chat Completions dicts (messages, tools, response_format).
-
-Chat Completions (not Responses) was chosen because every OpenAI-compatible
-endpoint (``OPENAI_BASE_URL``: vLLM, OpenRouter, Ollama, …) speaks it, while
-the Responses API is OpenAI-only.
-"""
-
-from __future__ import annotations
-
-import json
-from typing import Any
-
-from codeverse.contracts.chat import (
- ChatMessage,
- ChatRequest,
- ImagePart,
- TextPart,
- ToolCallPart,
- ToolResultPart,
- ToolSpec,
-)
-from codeverse.models.base import ModelError
-from codeverse.models.parts import image_b64
-from codeverse.models.schema_utils import inline_refs, to_openai_strict_schema
-
-SCHEMA_NAME = "response"
-
-
-# ------------------------------------------------------------- model families
-def is_reasoning_model(model: str) -> bool:
- m = model.lower()
- return m.startswith(("o1", "o3", "o4", "gpt-5"))
-
-
-def reasoning_effort(model: str, thinking: str) -> str | None:
- """Map ``thinking`` onto ``reasoning_effort`` (None for non-reasoning models)."""
- if not is_reasoning_model(model):
- return None
- m = model.lower()
- if thinking == "off":
- if m.startswith("gpt-5.") and not m.startswith("gpt-5.0"):
- return "none" # gpt-5.1+ accept "none"
- if m.startswith("gpt-5"):
- return "minimal"
- return "low" # o-series has no off switch
- return thinking
-
-
-# ------------------------------------------------------------------ messages
-def _image_block(p: ImagePart) -> dict[str, Any]:
- data, mime = image_b64(p)
- return {
- "type": "image_url",
- "image_url": {"url": f"data:{mime};base64,{data}", "detail": "auto"},
- }
-
-
-def to_messages(messages: list[ChatMessage], system: str) -> list[dict[str, Any]]:
- """ChatMessages → Chat Completions messages. Tool results become ``role:
- tool`` messages; images inside tool results (unsupported there) are sent as
- a follow-up user message."""
- out: list[dict[str, Any]] = []
- if system:
- out.append({"role": "system", "content": system})
- for msg in messages:
- if msg.role == "assistant":
- out.append(_assistant_message(msg))
- continue
- trailing_images: list[dict[str, Any]] = []
- content: list[dict[str, Any]] = []
- for p in msg.parts:
- if isinstance(p, TextPart):
- if p.text:
- content.append({"type": "text", "text": p.text})
- elif isinstance(p, ImagePart):
- if p.label:
- content.append({"type": "text", "text": f"[image: {p.label}]"})
- content.append(_image_block(p))
- elif isinstance(p, ToolResultPart):
- if content:
- out.append({"role": "user", "content": content})
- content = []
- out.append(
- {
- "role": "tool",
- "tool_call_id": p.call_id,
- "content": p.content or "(no output)",
- }
- )
- for img in p.images:
- if img.label:
- trailing_images.append(
- {"type": "text", "text": f"[image from {p.name}: {img.label}]"}
- )
- trailing_images.append(_image_block(img))
- elif isinstance(p, ToolCallPart):
- raise ModelError("ToolCallPart is only valid in assistant messages")
- if content:
- out.append({"role": "user", "content": content})
- if trailing_images:
- out.append({"role": "user", "content": trailing_images})
- if not out or all(m["role"] == "system" for m in out):
- raise ModelError("ChatRequest has no content to send")
- return out
-
-
-def _assistant_message(msg: ChatMessage) -> dict[str, Any]:
- text = "".join(p.text for p in msg.parts if isinstance(p, TextPart))
- calls = [
- {
- "id": p.id,
- "type": "function",
- "function": {"name": p.name, "arguments": json.dumps(p.arguments)},
- }
- for p in msg.parts
- if isinstance(p, ToolCallPart)
- ]
- m: dict[str, Any] = {"role": "assistant", "content": text or None}
- if calls:
- m["tool_calls"] = calls
- return m
-
-
-# --------------------------------------------------------------------- tools
-def to_tool(t: ToolSpec) -> dict[str, Any]:
- params = inline_refs(t.parameters) if t.parameters else {"type": "object", "properties": {}}
- return {
- "type": "function",
- "function": {"name": t.name, "description": t.description, "parameters": params},
- }
-
-
-def response_format(schema: dict[str, Any], *, strict: bool) -> dict[str, Any]:
- body = to_openai_strict_schema(schema) if strict else inline_refs(schema)
- return {
- "type": "json_schema",
- "json_schema": {"name": SCHEMA_NAME, "schema": body, "strict": strict},
- }
-
-
-# ------------------------------------------------------------------- request
-def build_kwargs(request: ChatRequest, model: str, *, strict_schema: bool) -> dict[str, Any]:
- """``client.chat.completions.create(**kwargs)`` minus ``model``."""
- kw: dict[str, Any] = {
- "messages": to_messages(request.messages, request.system),
- "max_completion_tokens": request.max_output_tokens,
- }
- effort = reasoning_effort(model, request.thinking)
- if effort is not None:
- kw["reasoning_effort"] = effort
- else:
- kw["temperature"] = request.temperature
- if request.tools:
- kw["tools"] = [to_tool(t) for t in request.tools]
- kw["tool_choice"] = "auto"
- if request.response_schema is not None:
- kw["response_format"] = response_format(request.response_schema, strict=strict_schema)
- return kw
-
-
-# ------------------------------------------------------------------ response
-def parse_choice(choice: Any) -> tuple[str, list[ToolCallPart], str]:
- """→ ``(text, tool_calls, finish_reason)``; bad tool-call JSON → ModelError(retryable)."""
- msg = choice.message
- text = msg.content or ""
- if getattr(msg, "refusal", None):
- raise ModelError(f"OpenAI refusal: {msg.refusal}", retryable=False)
- calls: list[ToolCallPart] = []
- for tc in msg.tool_calls or []:
- fn = getattr(tc, "function", None)
- if fn is None:
- continue
- try:
- args = json.loads(fn.arguments or "{}")
- except json.JSONDecodeError as exc:
- raise ModelError(
- f"tool call {fn.name} has invalid JSON arguments: {exc}", retryable=True
- ) from exc
- if not isinstance(args, dict):
- args = {"value": args}
- calls.append(ToolCallPart(id=tc.id, name=fn.name, arguments=args))
- return text, calls, str(choice.finish_reason or "")
diff --git a/harness/codeverse/models/retry.py b/harness/codeverse/models/retry.py
index 62d28e10..ef5efca8 100644
--- a/harness/codeverse/models/retry.py
+++ b/harness/codeverse/models/retry.py
@@ -1,28 +1,572 @@
-"""Generic retry helpers: exponential backoff + full jitter, and the shared
-key-rotation state machine used by the Gemini backends.
+"""Multi-key pool with per-key rate limiting, 429 cooldown and a health score.
-* :func:`with_retries` — plain bounded retry; no provider knowledge.
-* :func:`rotate_with_retries` — the dead-key / 429-rotation / 503-hedge / backoff
- machine over a :class:`~codeverse.models.keypool.KeyPool`. Provider specifics
- (exception classification, outcome mapping, retry-after extraction) are
- injected as hooks, so this module stays provider-neutral.
+Used by ``GeminiModel`` (22 keys on the owner's box) but provider-neutral.
-``sleep`` is injectable everywhere so unit tests run instantly.
+* ``acquire()`` picks the next healthy key round-robin, honouring per-key
+ RPM / TPM token buckets and 429 cool-downs; it blocks (bounded) when every
+ key is throttled and raises ``KeyPoolExhausted`` after ``timeout_s``.
+ ``tokens_hint`` reserves the pending call's estimated prompt tokens, so a
+ 200 k-token judge verdict and a 2 k-token caption are scheduled differently
+ (``docs/COST.md`` Part III); ``max_in_flight`` additionally caps how many calls
+ may be out at once, and :meth:`KeyPool.release` (a ``finally`` in
+ ``rotate_with_retries``) hands the slot back. ``try_acquire()`` is the
+ never-waiting variant a hedged retry uses for its extra keys.
+* ``report(key, outcome)`` feeds back ``ok | 429 | 5xx | error | dead`` so the
+ pool can cool a key down and adjust its health score. ``dead`` is for
+ key-scoped auth/permission failures (revoked / suspended / invalid key): the
+ key is benched for ``dead_cooldown_s`` (default one hour) and re-probed once
+ that elapses — a dead key must never keep failing its share of calls.
+ ``report(..., tokens=actual, reserved=hint)`` reconciles the reservation with
+ the provider's real prompt-token count (refund or top-up).
+* ``stats()`` exposes counters for logs / ``3dcv doctor --live``: per-key health
+ and cooldown, pool RPM/TPM capacity and headroom, in-flight and peak in-flight.
+
+Thread-safe; ``clock`` / ``sleep`` are injectable for deterministic tests.
"""
from __future__ import annotations
import logging
import random
+import threading
import time
from collections.abc import Callable, Sequence
from concurrent.futures import Future, ThreadPoolExecutor, as_completed
-from dataclasses import dataclass
+from dataclasses import dataclass, field
from functools import partial
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, Any, Literal, TypeVar
+
+from codeverse.contracts.chat import ChatRequest, ImagePart, TextPart, ToolResultPart
+
+Outcome = Literal["ok", "429", "5xx", "error", "dead"]
+
+
+class KeyPoolExhausted(RuntimeError):
+ """Every key is cooling down / throttled and the wait budget ran out."""
+
+
+MAX_WAIT_S = 3.0
+"""The longest any single retry / cooldown wait may be (seconds).
+
+House rule (owner, 2026-08-24, tightened 5 s -> 3 s on 2026-08-27): with 22 keys
+there is always another key to try, so the harness rotates rather than sitting
+out a long backoff. Patience comes from the NUMBER of attempts, never from the
+length of one sleep. This is the single source for every wait — generic
+backoff, storm sleeps, 429 cooldowns and the storm gate's park all clip to it.
+"""
+
+ACQUIRE_TIMEOUT_S = 120.0
+"""Default total wait budget of one :meth:`KeyPool.acquire` (seconds).
+
+Covers BOTH the ``max_in_flight`` slot wait and the key/cooldown wait; a caller
+with a deadline passes something smaller (``retry.rotate_with_retries`` passes
+``min(ACQUIRE_TIMEOUT_S, remaining budget)``). ``None`` waits forever.
+"""
+
+
+@dataclass
+class TokenBucket:
+ """Classic token bucket: ``capacity`` tokens, refilled at ``rate`` per second."""
+
+ capacity: float
+ rate: float
+ tokens: float = field(default=0.0)
+ updated: float = field(default=0.0)
+
+ def __post_init__(self) -> None:
+ self.tokens = self.capacity
+
+ def _refill(self, now: float) -> None:
+ if now > self.updated:
+ self.tokens = min(self.capacity, self.tokens + (now - self.updated) * self.rate)
+ self.updated = now
+
+ def try_take(self, n: float, now: float) -> bool:
+ self._refill(now)
+ if self.tokens >= n:
+ self.tokens -= n
+ return True
+ return False
+
+ def charge(self, n: float, now: float) -> None:
+ """Take ``n`` tokens unconditionally; ``n < 0`` gives tokens back.
+
+ Unlike :meth:`try_take` the bucket is allowed to go negative, so an
+ under-estimated reservation is paid off by the next refill instead of
+ being silently forgiven. Used to reconcile a TPM reservation with the
+ provider's real prompt-token count."""
+ self._refill(now)
+ self.tokens = min(self.capacity, self.tokens - n)
+
+ def wait_for(self, n: float, now: float) -> float:
+ """Seconds until ``n`` tokens are available (0 if already)."""
+ self._refill(now)
+ if self.tokens >= n:
+ return 0.0
+ return (n - self.tokens) / self.rate if self.rate > 0 else float("inf")
+
+ def headroom(self, now: float) -> float:
+ """Fraction of capacity currently available (0.0 – 1.0)."""
+ self._refill(now)
+ return max(0.0, min(1.0, self.tokens / self.capacity)) if self.capacity > 0 else 1.0
+
+
+@dataclass
+class _KeyState:
+ key: str
+ rpm: TokenBucket
+ tpm: TokenBucket | None
+ health: float = 1.0
+ cooldown_until: float = 0.0
+ dead_until: float = 0.0
+ n_ok: int = 0
+ n_429: int = 0
+ n_5xx: int = 0
+ n_error: int = 0
+ n_dead: int = 0
+ n_acquired: int = 0
+ tokens_used: int = 0
+ last_used: float = 0.0
+ health_ts: float = 0.0
+
+ def recover(self, now: float, rate: float = 0.01) -> None:
+ """Passive health recovery: +``rate`` per idle second, capped at 1.0."""
+ if now > self.health_ts:
+ self.health = min(1.0, self.health + (now - self.health_ts) * rate)
+ self.health_ts = now
+
+ def available_at(self, now: float, tokens_hint: int) -> float:
+ """Earliest time this key can be used (``now`` if ready)."""
+ t = max(now, self.cooldown_until)
+ t = max(t, now + self.rpm.wait_for(1.0, now))
+ if self.tpm is not None and tokens_hint > 0:
+ t = max(t, now + self.tpm.wait_for(float(tokens_hint), now))
+ return t
+
+
+class KeyPool:
+ """Round-robin key pool with per-key limiters. See module docstring."""
+
+ def __init__(
+ self,
+ keys: list[str] | tuple[str, ...],
+ *,
+ rpm_per_key: int = 900,
+ tpm_per_key: int | None = None,
+ max_in_flight: int = 0,
+ cooldown_s: float = MAX_WAIT_S,
+ dead_cooldown_s: float = 3600.0,
+ min_health: float = 0.3,
+ clock: Callable[[], float] = time.monotonic,
+ sleep: Callable[[float], None] = time.sleep,
+ ) -> None:
+ uniq = [k for i, k in enumerate(keys) if k and k not in keys[:i]]
+ if not uniq:
+ raise ValueError("KeyPool needs at least one non-empty key")
+ self._clock = clock
+ self._sleep = sleep
+ self._cooldown_s = float(cooldown_s)
+ self._dead_cooldown_s = float(dead_cooldown_s)
+ self._min_health = min_health
+ self._lock = threading.Lock()
+ self._rr = 0
+ self._in_flight = 0
+ self._peak_in_flight = 0
+ # Process-wide ceiling on concurrent model calls, independent of the caller's
+ # thread pools: blender/node/chrome workers are CPU-bound and sized by cores,
+ # while this is sized by the provider (docs/COST.md Part III). 0 = unlimited.
+ self._max_in_flight = int(max_in_flight or 0)
+ self._slots = threading.BoundedSemaphore(self._max_in_flight) if self._max_in_flight else None
+ now = clock()
+ self._states: list[_KeyState] = []
+ for k in uniq:
+ rpm = TokenBucket(capacity=float(rpm_per_key), rate=rpm_per_key / 60.0, updated=now)
+ tpm = None
+ if tpm_per_key:
+ tpm = TokenBucket(capacity=float(tpm_per_key), rate=tpm_per_key / 60.0, updated=now)
+ self._states.append(_KeyState(key=k, rpm=rpm, tpm=tpm, health_ts=now))
+ self._by_key = {s.key: s for s in self._states}
+
+ # ------------------------------------------------------------------ public
+ def __len__(self) -> int:
+ return len(self._states)
+
+ @property
+ def keys(self) -> list[str]:
+ return [s.key for s in self._states]
+
+ def acquire(
+ self,
+ *,
+ tokens_hint: int = 0,
+ exclude: set[str] | frozenset[str] | None = None,
+ timeout_s: float | None = ACQUIRE_TIMEOUT_S,
+ ) -> str:
+ """Return the next usable key, blocking (bounded by ``timeout_s``) while all
+ keys are throttled. ``exclude`` skips keys that already failed this call.
+ Raises ``KeyPoolExhausted`` at once when no key can become available before
+ the deadline (e.g. every key is dead) — availability only moves later.
+
+ ``tokens_hint`` is the estimated prompt tokens of the pending call: they
+ are reserved in the chosen key's TPM bucket now and reconciled by
+ :meth:`report`. When ``max_in_flight`` is set the call also waits for a
+ free concurrency slot; :meth:`release` hands it back. ``timeout_s`` bounds
+ the slot wait AND the key wait together (``None`` = wait forever): the slot
+ wait used to be unbounded, so a caller 20 s from its deadline could sit on
+ the semaphore for minutes."""
+ if self._slots is not None:
+ t0 = self._clock()
+ if not self._slots.acquire(timeout=timeout_s):
+ raise KeyPoolExhausted(
+ f"all {self._max_in_flight} in-flight slots busy; waited {timeout_s}s"
+ )
+ if timeout_s is not None:
+ # the slot wait spent part of the budget; the key wait gets the rest
+ timeout_s = max(0.0, timeout_s - (self._clock() - t0))
+ try:
+ return self._acquire_key(tokens_hint, exclude, timeout_s)
+ except BaseException:
+ if self._slots is not None:
+ self._slots.release()
+ raise
+
+ def try_acquire(
+ self,
+ *,
+ tokens_hint: int = 0,
+ exclude: set[str] | frozenset[str] | None = None,
+ ) -> str | None:
+ """:meth:`acquire` that never waits: a key usable *right now* (and a free
+ ``max_in_flight`` slot), else ``None`` — nothing is reserved or counted then.
+
+ For the extra keys of a hedged retry (``rotate_with_retries(hedge=...)``): the
+ primary request is already in flight, so a partner that is not free at once
+ is not worth waiting for. A returned key holds a slot like any other and
+ must be :meth:`release`-d."""
+ if self._slots is not None and not self._slots.acquire(blocking=False):
+ return None
+ try:
+ return self._acquire_key(tokens_hint, exclude, 0.0)
+ except KeyPoolExhausted:
+ if self._slots is not None:
+ self._slots.release()
+ return None
+ except BaseException:
+ if self._slots is not None:
+ self._slots.release()
+ raise
+
+ def _acquire_key(
+ self,
+ tokens_hint: int,
+ exclude: set[str] | frozenset[str] | None,
+ timeout_s: float | None,
+ ) -> str:
+ deadline = None if timeout_s is None else self._clock() + timeout_s
+ while True:
+ with self._lock:
+ now = self._clock()
+ chosen = self._pick(now, tokens_hint, exclude or ())
+ if chosen is not None:
+ chosen.rpm.try_take(1.0, now)
+ if chosen.tpm is not None and tokens_hint > 0:
+ chosen.tpm.try_take(float(tokens_hint), now)
+ chosen.n_acquired += 1
+ chosen.last_used = now
+ self._in_flight += 1
+ self._peak_in_flight = max(self._peak_in_flight, self._in_flight)
+ return chosen.key
+ soonest = min(
+ (
+ s.available_at(now, tokens_hint)
+ for s in self._states
+ if s.key not in (exclude or ())
+ ),
+ default=float("inf"),
+ )
+ if soonest == float("inf"):
+ raise KeyPoolExhausted("all keys excluded")
+ if deadline is not None and soonest > deadline:
+ raise KeyPoolExhausted(
+ f"all {len(self._states)} keys throttled or dead; the earliest becomes "
+ f"available in {soonest - now:.0f}s (> {timeout_s}s wait budget)"
+ )
+ wait = max(0.01, min(soonest - now, MAX_WAIT_S))
+ if deadline is not None and self._clock() + wait > deadline:
+ raise KeyPoolExhausted(
+ f"all {len(self._states)} keys throttled; waited {timeout_s}s"
+ )
+ self._sleep(wait)
+
+ def release(self) -> None:
+ """Mark one :meth:`acquire`-d call finished (call it in a ``finally``).
+
+ Frees the in-flight gauge and the ``max_in_flight`` slot; outcome
+ accounting is :meth:`report`, which may legitimately be called more than
+ once for one call (a key that looked dead is reported again once a
+ sibling proves the request fine). A stray ``release`` is a no-op."""
+ with self._lock:
+ if self._in_flight <= 0:
+ return
+ self._in_flight -= 1
+ if self._slots is not None:
+ self._slots.release()
+
+ def report(
+ self,
+ key: str,
+ outcome: Outcome,
+ *,
+ tokens: int = 0,
+ reserved: int = 0,
+ retry_after_s: float | None = None,
+ ) -> None:
+ """Feed back the result of a call made with ``key``.
+
+ ``tokens`` is what the provider says the call really cost (prompt
+ tokens); ``reserved`` is the ``tokens_hint`` :meth:`acquire` already took
+ out of the TPM bucket for it. The pool charges the *difference*, so an
+ over-estimate is refunded and an under-estimate is paid off — pass both,
+ or neither, and never the same tokens twice."""
+ with self._lock:
+ st = self._by_key.get(key)
+ if st is None:
+ return
+ now = self._clock()
+ st.recover(now)
+ if outcome == "ok":
+ st.n_ok += 1
+ st.health = min(1.0, st.health + 0.2 * (1.0 - st.health))
+ elif outcome == "429":
+ st.n_429 += 1
+ st.health *= 0.5
+ cool = retry_after_s if retry_after_s and retry_after_s > 0 else self._cooldown_s
+ # House rule (owner, 2026-08-24): no single wait exceeds MAX_WAIT_S — we
+ # rotate to another key instead of sitting out a provider's suggested delay.
+ cool = min(cool, MAX_WAIT_S)
+ st.cooldown_until = max(st.cooldown_until, now + cool)
+ elif outcome == "5xx":
+ st.n_5xx += 1
+ st.health *= 0.8
+ elif outcome == "dead":
+ # key-scoped failure: bench it; re-probed once the long cooldown passes
+ st.n_dead += 1
+ st.health = 0.0
+ st.dead_until = max(st.dead_until, now + self._dead_cooldown_s)
+ st.cooldown_until = max(st.cooldown_until, st.dead_until)
+ else:
+ st.n_error += 1
+ st.health *= 0.9
+ if st.tpm is not None and (tokens or reserved):
+ # reconcile the reservation with reality; a call that never reached
+ # the model (429 / capacity storm) reports tokens=0 and is refunded
+ st.tpm.charge(float(tokens) - float(reserved), now)
+ st.tokens_used += max(0, int(tokens))
+
+ def stats(self) -> dict[str, Any]:
+ """Counters per key (keys are redacted to their last 4 chars)."""
+ with self._lock:
+ now = self._clock()
+ per_key = [
+ {
+ "key": f"…{s.key[-4:]}",
+ "health": round(s.health, 3),
+ "cooldown_s": round(max(0.0, s.cooldown_until - now), 1),
+ "rpm_tokens": round(s.rpm.tokens, 1),
+ "rpm_headroom": round(s.rpm.headroom(now), 3),
+ "tpm_headroom": None if s.tpm is None else round(s.tpm.headroom(now), 3),
+ "tokens_used": s.tokens_used,
+ "acquired": s.n_acquired,
+ "ok": s.n_ok,
+ "429": s.n_429,
+ "5xx": s.n_5xx,
+ "error": s.n_error,
+ "dead": s.n_dead,
+ }
+ for s in self._states
+ ]
+ n = len(self._states)
+ return {
+ "n_keys": n,
+ "n_cooling": sum(1 for s in self._states if s.cooldown_until > now),
+ "n_dead": sum(1 for s in self._states if s.dead_until > now),
+ "in_flight": self._in_flight,
+ "peak_in_flight": self._peak_in_flight,
+ "rpm_capacity": int(sum(s.rpm.capacity for s in self._states)),
+ "tpm_capacity": int(sum(s.tpm.capacity for s in self._states if s.tpm)),
+ "rpm_headroom": round(sum(s.rpm.headroom(now) for s in self._states) / n, 3),
+ "tpm_headroom": (
+ None if self._states[0].tpm is None
+ else round(sum(s.tpm.headroom(now) for s in self._states if s.tpm) / n, 3)
+ ),
+ "tokens_used": sum(s.tokens_used for s in self._states),
+ "acquired": sum(s.n_acquired for s in self._states),
+ "ok": sum(s.n_ok for s in self._states),
+ "429": sum(s.n_429 for s in self._states),
+ "5xx": sum(s.n_5xx for s in self._states),
+ "error": sum(s.n_error for s in self._states),
+ "dead": sum(s.n_dead for s in self._states),
+ "keys": per_key,
+ }
+
+ # ----------------------------------------------------------------- private
+ def _pick(self, now: float, tokens_hint: int, exclude) -> _KeyState | None:
+ """Round-robin scan; prefer the first healthy, ready key; otherwise the
+ healthiest ready key. Advances the RR cursor past the chosen key."""
+ n = len(self._states)
+ best: _KeyState | None = None
+ best_idx = -1
+ for step in range(n):
+ idx = (self._rr + step) % n
+ st = self._states[idx]
+ if st.key in exclude:
+ continue
+ st.recover(now)
+ if st.available_at(now, tokens_hint) > now:
+ continue
+ if st.health >= self._min_health:
+ self._rr = (idx + 1) % n
+ return st
+ if best is None or st.health > best.health:
+ best, best_idx = st, idx
+ if best is not None:
+ self._rr = (best_idx + 1) % n
+ return best
+
+
+# ===================================================================== storm
+# (merged from codeverse/models/storm.py, 2026-08-28)
+class StormGate:
+ """Shared 503 back-pressure for one model. See the module docstring."""
+
+ def __init__(
+ self,
+ name: str = "model",
+ *,
+ base_delay: float = 1.0,
+ max_wait_s: float = MAX_WAIT_S,
+ probe_lease_s: float = 30.0,
+ clock: Callable[[], float] = time.monotonic,
+ sleep: Callable[[float], None] = time.sleep,
+ ) -> None:
+ self.name = name
+ self._base = float(base_delay)
+ self._max_wait = float(max_wait_s)
+ self._probe_lease = float(probe_lease_s)
+ self._clock = clock
+ self._sleep = sleep
+ self._lock = threading.Lock()
+ self._storm = False
+ self._closed_until = 0.0
+ self._probe_until = 0.0
+ self._streak = 0
+ self.n_hits = 0
+ self.n_probes = 0
+ self.n_storms = 0
+ self.parked_s = 0.0
+
+ # ------------------------------------------------------------------ public
+ @property
+ def storming(self) -> bool:
+ return self._storm
+
+ def enter(self, deadline: float | None = None) -> float:
+ """Block until this thread may issue a call; returns the seconds waited.
+
+ ``deadline`` (a point on this gate's ``clock``) bounds the parking: each
+ wait is clipped to it and once it passes ``enter`` returns even though the
+ storm may still be on — the caller's own deadline machinery
+ (``retry.rotate_with_retries``), not the gate, decides to give up."""
+ t0 = self._clock()
+ while True:
+ with self._lock:
+ now = self._clock()
+ if not self._storm:
+ return now - t0
+ if deadline is not None and now >= deadline:
+ return now - t0 # budget exhausted: hand control back
+ if now < self._closed_until:
+ wait = min(self._max_wait, self._closed_until - now)
+ elif now >= self._probe_until:
+ # the window elapsed and no probe is in flight: this thread is it
+ self._probe_until = now + self._probe_lease
+ self._n_probe_hit()
+ return now - t0
+ else:
+ wait = min(self._max_wait, self._probe_until - now)
+ wait = max(0.01, wait)
+ if deadline is not None:
+ wait = min(wait, max(0.01, deadline - now))
+ self.parked_s += wait
+ self._sleep(wait)
+
+ def hit(self, retry_after_s: float | None = None) -> float:
+ """Record a capacity 503/529. Returns how long the gate is now closed."""
+ with self._lock:
+ now = self._clock()
+ if not self._storm:
+ self._storm = True
+ self.n_storms += 1
+ self.n_hits += 1
+ self._streak += 1
+ wanted = retry_after_s if retry_after_s and retry_after_s > 0 else (
+ self._base * (2 ** min(self._streak - 1, 8))
+ )
+ delay = min(self._max_wait, wanted)
+ self._closed_until = max(self._closed_until, now + delay)
+ self._probe_until = 0.0 # a fresh probe may go once the window elapses
+ return self._closed_until - now
+
+ def ok(self) -> None:
+ """Record a success: the model is answering again, so open the gate."""
+ if not self._storm:
+ return
+ with self._lock:
+ self._storm = False
+ self._streak = 0
+ self._closed_until = 0.0
+ self._probe_until = 0.0
+
+ def snapshot(self) -> dict[str, Any]:
+ with self._lock:
+ now = self._clock()
+ return {
+ "name": self.name,
+ "storming": self._storm,
+ "closed_for_s": round(max(0.0, self._closed_until - now), 1),
+ "storms": self.n_storms,
+ "hits": self.n_hits,
+ "probes": self.n_probes,
+ "parked_s": round(self.parked_s, 1),
+ }
+
+ # ----------------------------------------------------------------- private
+ def _n_probe_hit(self) -> None:
+ self.n_probes += 1
+
+
+_gates: dict[str, StormGate] = {}
+_gates_lock = threading.Lock()
+
+
+def storm_gate(name: str) -> StormGate:
+ """The process-wide gate for ``name`` (``"gemini:gemini-3.7-flash"``)."""
+ with _gates_lock:
+ gate = _gates.get(name)
+ if gate is None:
+ gate = StormGate(name)
+ _gates[name] = gate
+ return gate
-from codeverse.models.keypool import ACQUIRE_TIMEOUT_S, MAX_WAIT_S, KeyPoolExhausted
+def all_gates() -> list[StormGate]:
+ """Every gate this process has created (for ``3dcv doctor --live``)."""
+ with _gates_lock:
+ return list(_gates.values())
+
+
+# ===================================================================== retry
+# (merged from codeverse/models/retry.py, 2026-08-28)
#: the longest ONE logical call may spend being retried, waits and timeouts included.
#: The storm branch used to be bounded only in ATTEMPTS: 60 storm attempts x (a 300 s
#: read timeout + a <=5 s wait) is **5.1 hours** for a single call, though the docstring
@@ -43,8 +587,7 @@ DEFAULT_HEDGE = 2
if TYPE_CHECKING: # pragma: no cover
from codeverse.models.base import ModelError
- from codeverse.models.keypool import KeyPool, Outcome
- from codeverse.models.storm import StormGate
+ from codeverse.models.retry import KeyPool, Outcome, StormGate
log = logging.getLogger(__name__)
@@ -165,7 +708,7 @@ def rotate_with_retries[T](
from long sleeps that do NOT consume ``max_attempts``. Observed 2026-08-23: a
multi-minute gemini-3.7-flash "high demand" outage killed 8 bench runs
under the plain 6-attempt budget. A ``storm_gate`` (see
- :mod:`codeverse.models.storm`) shares that discovery across the process:
+ :mod:`codeverse.models.retry`) shares that discovery across the process:
workers park at the gate instead of each spending a round-trip to learn
the model is out of capacity, and one probe at a time reopens it.
* other retryable errors → exponential backoff + jitter until
@@ -194,7 +737,7 @@ def rotate_with_retries[T](
key, and a 503 last).
``tokens_hint`` is the estimated **prompt** tokens of the pending call
- (:func:`codeverse.models.tokens.request_tokens`); the pool reserves them in
+ (:func:`codeverse.models.retry.request_tokens`); the pool reserves them in
the per-key TPM bucket at ``acquire`` and the reservation is reconciled
against the provider's real count on ``report``, so a 200 k-token judge call
and a 2 k-token caption are scheduled differently.
@@ -504,3 +1047,44 @@ def _discard_loser(
except Exception as hook_exc: # noqa: BLE001 - accounting is best-effort
log.debug("on_attempt hook failed for hedge loser: %s", hook_exc)
log.debug("hedge loser …%s finished (%s); discarded", t.key[-4:], t.outcome)
+
+
+# ===================================================================== tokens
+# (merged from codeverse/models/tokens.py, 2026-08-28)
+#: longest edge we assume for an image part whose size we do not measure; the
+#: harness caps judge payloads at ``Settings.judge.max_px`` = 1024 (docs/COST.md §3)
+DEFAULT_IMAGE_PX = 1024
+
+
+def request_parts(request: ChatRequest) -> tuple[list[str], int]:
+ """``(text blocks, number of image parts)`` of a request, system prompt and
+ tool schemas included — everything the provider will count as prompt."""
+ blocks: list[str] = []
+ images = 0
+ if request.system:
+ blocks.append(request.system)
+ for tool in request.tools or ():
+ blocks.append(f"{tool.name}{tool.description}{tool.parameters}")
+ if request.response_schema is not None:
+ blocks.append(str(request.response_schema))
+ for msg in request.messages:
+ for part in msg.parts:
+ if isinstance(part, TextPart):
+ blocks.append(part.text)
+ elif isinstance(part, ImagePart):
+ images += 1
+ elif isinstance(part, ToolResultPart):
+ blocks.append(part.content)
+ images += len(part.images)
+ else: # ToolCallPart
+ blocks.append(f"{part.name}{part.arguments}")
+ return blocks, images
+
+
+def request_tokens(request: ChatRequest, *, model_id: str = "", image_px: int = DEFAULT_IMAGE_PX) -> int:
+ """Estimated **input** tokens of ``request`` (never negative)."""
+ from codeverse.cost.guard import estimate_call
+
+ blocks, images = request_parts(request)
+ est = estimate_call(model_id or "gemini:unknown", prompt=blocks, n_images=images, image_px=image_px)
+ return max(0, est.input_tokens)
diff --git a/harness/codeverse/models/storm.py b/harness/codeverse/models/storm.py
deleted file mode 100644
index 4733476f..00000000
--- a/harness/codeverse/models/storm.py
+++ /dev/null
@@ -1,165 +0,0 @@
-"""Process-wide "this model is out of capacity" signal (HTTP 503 / 529).
-
-A 429 is per key, so the :class:`~codeverse.models.keypool.KeyPool` cures it by
-rotating. A **capacity storm** is not: Gemini's *"This model is currently
-experiencing high demand"* comes back on every key at once, so rotation buys
-nothing and each worker that discovers the storm independently pays a full
-failed round-trip to learn what its 29 siblings already know.
-
-Measured on this box (``docs/COST.md`` Part III): 2 833 storm waits across the
-recorded batteries, 17.7 h of worker time asleep — 22 – 39 % of every battery's
-wall clock — plus one wasted round-trip per wait.
-
-``StormGate`` turns that into ONE shared wait:
-
-* the first worker to see a 503 calls :meth:`hit`, which closes the gate for a
- short, escalating window (never longer than ``max_wait_s`` — the house rule is
- that patience comes from the number of waits, not the length of one);
-* every other worker parks in :meth:`enter` instead of issuing a call that is
- almost certain to fail;
-* once the window elapses exactly **one** worker at a time is let through as a
- probe (a lease, so a crashed prober cannot wedge the gate). Its success
- (:meth:`ok`) reopens the gate for everybody.
-
-The gate never *adds* waiting: when no storm is running :meth:`enter` returns
-immediately without taking a lock hop that matters. ``clock`` / ``sleep`` are
-injectable so tests run on a fake clock.
-"""
-
-from __future__ import annotations
-
-import threading
-import time
-from collections.abc import Callable
-from typing import Any
-
-from codeverse.models.keypool import MAX_WAIT_S
-
-
-class StormGate:
- """Shared 503 back-pressure for one model. See the module docstring."""
-
- def __init__(
- self,
- name: str = "model",
- *,
- base_delay: float = 1.0,
- max_wait_s: float = MAX_WAIT_S,
- probe_lease_s: float = 30.0,
- clock: Callable[[], float] = time.monotonic,
- sleep: Callable[[float], None] = time.sleep,
- ) -> None:
- self.name = name
- self._base = float(base_delay)
- self._max_wait = float(max_wait_s)
- self._probe_lease = float(probe_lease_s)
- self._clock = clock
- self._sleep = sleep
- self._lock = threading.Lock()
- self._storm = False
- self._closed_until = 0.0
- self._probe_until = 0.0
- self._streak = 0
- self.n_hits = 0
- self.n_probes = 0
- self.n_storms = 0
- self.parked_s = 0.0
-
- # ------------------------------------------------------------------ public
- @property
- def storming(self) -> bool:
- return self._storm
-
- def enter(self, deadline: float | None = None) -> float:
- """Block until this thread may issue a call; returns the seconds waited.
-
- ``deadline`` (a point on this gate's ``clock``) bounds the parking: each
- wait is clipped to it and once it passes ``enter`` returns even though the
- storm may still be on — the caller's own deadline machinery
- (``retry.rotate_with_retries``), not the gate, decides to give up."""
- t0 = self._clock()
- while True:
- with self._lock:
- now = self._clock()
- if not self._storm:
- return now - t0
- if deadline is not None and now >= deadline:
- return now - t0 # budget exhausted: hand control back
- if now < self._closed_until:
- wait = min(self._max_wait, self._closed_until - now)
- elif now >= self._probe_until:
- # the window elapsed and no probe is in flight: this thread is it
- self._probe_until = now + self._probe_lease
- self._n_probe_hit()
- return now - t0
- else:
- wait = min(self._max_wait, self._probe_until - now)
- wait = max(0.01, wait)
- if deadline is not None:
- wait = min(wait, max(0.01, deadline - now))
- self.parked_s += wait
- self._sleep(wait)
-
- def hit(self, retry_after_s: float | None = None) -> float:
- """Record a capacity 503/529. Returns how long the gate is now closed."""
- with self._lock:
- now = self._clock()
- if not self._storm:
- self._storm = True
- self.n_storms += 1
- self.n_hits += 1
- self._streak += 1
- wanted = retry_after_s if retry_after_s and retry_after_s > 0 else (
- self._base * (2 ** min(self._streak - 1, 8))
- )
- delay = min(self._max_wait, wanted)
- self._closed_until = max(self._closed_until, now + delay)
- self._probe_until = 0.0 # a fresh probe may go once the window elapses
- return self._closed_until - now
-
- def ok(self) -> None:
- """Record a success: the model is answering again, so open the gate."""
- if not self._storm:
- return
- with self._lock:
- self._storm = False
- self._streak = 0
- self._closed_until = 0.0
- self._probe_until = 0.0
-
- def snapshot(self) -> dict[str, Any]:
- with self._lock:
- now = self._clock()
- return {
- "name": self.name,
- "storming": self._storm,
- "closed_for_s": round(max(0.0, self._closed_until - now), 1),
- "storms": self.n_storms,
- "hits": self.n_hits,
- "probes": self.n_probes,
- "parked_s": round(self.parked_s, 1),
- }
-
- # ----------------------------------------------------------------- private
- def _n_probe_hit(self) -> None:
- self.n_probes += 1
-
-
-_gates: dict[str, StormGate] = {}
-_gates_lock = threading.Lock()
-
-
-def storm_gate(name: str) -> StormGate:
- """The process-wide gate for ``name`` (``"gemini:gemini-3.7-flash"``)."""
- with _gates_lock:
- gate = _gates.get(name)
- if gate is None:
- gate = StormGate(name)
- _gates[name] = gate
- return gate
-
-
-def all_gates() -> list[StormGate]:
- """Every gate this process has created (for ``3dcv doctor --live``)."""
- with _gates_lock:
- return list(_gates.values())
diff --git a/harness/codeverse/models/tokens.py b/harness/codeverse/models/tokens.py
deleted file mode 100644
index 1ac5d3a7..00000000
--- a/harness/codeverse/models/tokens.py
+++ /dev/null
@@ -1,60 +0,0 @@
-"""How many tokens is this request about to spend? (TPM-aware key scheduling.)
-
-The :class:`~codeverse.models.keypool.KeyPool` schedules against a per-key
-tokens-per-minute quota, so it needs a number *before* the call: a 200 k-token
-judge verdict and a 2 k-token caption must not be admitted on the same terms.
-
-``request_tokens`` reuses the estimator the cost guard already ships
-(:func:`codeverse.cost.guard.estimate_call` — ~4 characters per token plus a flat
-count per image part) and returns **input** tokens only. That is what a Gemini
-key's TPM meter bills, and it is also what dominates: over the recorded corpus
-(6 021 priced calls, ``docs/COST.md`` Part III) output + thoughts were 2 % of
-input, so an output term would only add noise.
-
-Estimates are good to about ±15 %. The pool reconciles against the provider's
-own prompt-token count when the call returns
-(``KeyPool.report(..., tokens=actual, reserved=hint)``), so a bad estimate costs
-one minute of slightly-wrong pacing, never correctness.
-"""
-
-from __future__ import annotations
-
-from codeverse.contracts.chat import ChatRequest, ImagePart, TextPart, ToolResultPart
-
-#: longest edge we assume for an image part whose size we do not measure; the
-#: harness caps judge payloads at ``Settings.judge.max_px`` = 1024 (docs/COST.md §3)
-DEFAULT_IMAGE_PX = 1024
-
-
-def request_parts(request: ChatRequest) -> tuple[list[str], int]:
- """``(text blocks, number of image parts)`` of a request, system prompt and
- tool schemas included — everything the provider will count as prompt."""
- blocks: list[str] = []
- images = 0
- if request.system:
- blocks.append(request.system)
- for tool in request.tools or ():
- blocks.append(f"{tool.name}{tool.description}{tool.parameters}")
- if request.response_schema is not None:
- blocks.append(str(request.response_schema))
- for msg in request.messages:
- for part in msg.parts:
- if isinstance(part, TextPart):
- blocks.append(part.text)
- elif isinstance(part, ImagePart):
- images += 1
- elif isinstance(part, ToolResultPart):
- blocks.append(part.content)
- images += len(part.images)
- else: # ToolCallPart
- blocks.append(f"{part.name}{part.arguments}")
- return blocks, images
-
-
-def request_tokens(request: ChatRequest, *, model_id: str = "", image_px: int = DEFAULT_IMAGE_PX) -> int:
- """Estimated **input** tokens of ``request`` (never negative)."""
- from codeverse.cost.guard import estimate_call
-
- blocks, images = request_parts(request)
- est = estimate_call(model_id or "gemini:unknown", prompt=blocks, n_images=images, image_px=image_px)
- return max(0, est.input_tokens)
diff --git a/harness/codeverse/reference.py b/harness/codeverse/reference.py
index 30bfa47a..b172b23a 100644
--- a/harness/codeverse/reference.py
+++ b/harness/codeverse/reference.py
@@ -986,7 +986,7 @@ def _chat_model(model_id: str) -> Any:
def _image_model(model_id: str = "") -> Any:
- from codeverse.models.gemini_image import DEFAULT_IMAGE_MODEL, GeminiImageModel
+ from codeverse.models.gemini import DEFAULT_IMAGE_MODEL, GeminiImageModel
return GeminiImageModel(model_id or DEFAULT_IMAGE_MODEL)
diff --git a/harness/codeverse/texturing/run.py b/harness/codeverse/texturing/run.py
index 2c2f98b9..69484e1a 100644
--- a/harness/codeverse/texturing/run.py
+++ b/harness/codeverse/texturing/run.py
@@ -239,7 +239,7 @@ def texture_pass(
# 3. images
if image_model is None:
- from codeverse.models.gemini_image import GeminiImageModel
+ from codeverse.models.gemini import GeminiImageModel
image_model = GeminiImageModel()
tset = generate_textures(tplan, tex_dir, image_model, size=size, cache_dir=cache_dir)
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index d57a99e2..be5ddd26 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -93,13 +93,14 @@ codeverse/
lines so it stays a leaf
fanout.py bounded parallel fan-out (fan_out, split_results, FanOutReport) — shared by
tracks/judges/texturing/bench
- models/ ChatModel (base.py); gemini_convert.py anthropic_convert.py openai_convert.py
- (request/response shapes per provider), parts.py; gemini.py (dead-key + free 429 rotation), gemini_image.py (ImageModel),
- anthropic.py openai.py, keypool.py ('dead' outcome + TPM reservation/reconcile),
- tokens.py (prompt-token estimate for the TPM bucket), pricing.py (version-suffix-only
- fallback), retry.py (MAX_WAIT_S: no single wait > 3 s), storm.py (shared 503 gate —
- measured, ships OFF, see docs/COST.md §21), health.py (preflight probe: is the model
- serving? no retries, no backoff), schema_utils.py (strict schema), registry.py
+ models/ ChatModel (base.py), parts.py; gemini.py (the whole Gemini stack:
+ request/response shapes, dead-key + free 429 rotation, the image model);
+ anthropic.py openai.py (each with its own request/response shapes);
+ retry.py (the scheduling machine: key pool with 'dead' outcome + TPM
+ reservation/reconcile, rotation with MAX_WAIT_S ≤ 3 s single waits, the
+ shared 503 storm gate — ships OFF, docs/COST.md §21 — and the prompt-token
+ estimate); pricing.py (version-suffix-only fallback), health.py (preflight
+ probe: no retries, no backoff), schema_utils.py (strict schema), registry.py
agents/ CodingAgent (base.py); gemini_cli.py claude_code.py codex.py antigravity.py
(api_agent.py + api_tools.py + api_skills.py deleted 2026-08-28 —
the vendors already ship the loop), materialize.py, cli_common.py (sessions, retry
diff --git a/harness/docs/COST.md b/harness/docs/COST.md
index 783f1f47..b051202a 100644
--- a/harness/docs/COST.md
+++ b/harness/docs/COST.md
@@ -860,7 +860,7 @@ quota would allow 1 000 per key. So the meaningful limiter is a *token* rate:
`Settings.rate.tpm_per_key` (default 1 000 000) via `shared_pool`, whose registry key
now includes the quota so two different quotas cannot silently share one set of buckets.
* `acquire(tokens_hint=…)` **reserves** the estimated prompt tokens of the pending call.
- The estimate is `codeverse.models.tokens.request_tokens`, a thin wrapper over
+ The estimate is `codeverse.models.retry.request_tokens`, a thin wrapper over
`cost.guard.estimate_call` that walks the whole request (system prompt, tool schemas,
response schema, tool results, a flat 1 290 per image).
* `report(key, outcome, tokens=actual, reserved=hint)` **reconciles**: the bucket is
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 47dbbb52..abade1a5 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -59,7 +59,7 @@ resp = m.generate(ChatRequest(messages=[...], system=..., response_schema=..., t
# GeminiModel clips its retry deadline to it; api_agent 20-120 s per turn, VlmJudge 240 s per sample, planner 300 s
# resp.raw["key"] = "…ab12" (the key that answered), resp.raw["attempts"] = round-trips issued (hedged siblings included)
resp.parsed / resp.text / resp.tool_calls / resp.usage # Usage always has cost_usd (models.pricing)
-from codeverse.models.keypool import KeyPool, KeyPoolExhausted
+from codeverse.models.retry import KeyPool, KeyPoolExhausted
KeyPool(keys, *, rpm_per_key=900, tpm_per_key=None, cooldown_s=30, dead_cooldown_s=3600)
pool.acquire(*, tokens_hint=0, exclude=None, timeout_s=120) -> key # raises immediately when every key is dead/cooling past the deadline
pool.try_acquire(*, tokens_hint=0, exclude=None) -> key | None # never waits (a hedged retry's extra key); holds a slot like acquire
diff --git a/harness/tests/agents/test_gemini_cli.py b/harness/tests/agents/test_gemini_cli.py
index 234a4a69..d87c4546 100644
--- a/harness/tests/agents/test_gemini_cli.py
+++ b/harness/tests/agents/test_gemini_cli.py
@@ -167,7 +167,7 @@ def test_single_key_quota_failure_returns_budget_without_retry(tmp_ws: Workspace
def test_pool_exhausted_before_first_attempt_is_a_budget_result(tmp_ws: Workspace, agent: GeminiCliAgent, monkeypatch):
from codeverse.agents import gemini_cli as gc
- from codeverse.models.keypool import KeyPoolExhausted
+ from codeverse.models.retry import KeyPoolExhausted
class Dead:
def acquire(self, **kw):
diff --git a/harness/tests/cost/test_instrument.py b/harness/tests/cost/test_instrument.py
index c3ccf4c2..4b03a1b8 100644
--- a/harness/tests/cost/test_instrument.py
+++ b/harness/tests/cost/test_instrument.py
@@ -402,7 +402,7 @@ def test_a_hedge_losers_tokens_reach_the_ledger_when_it_lands(tmp_path: Path):
from codeverse.models.base import ModelError
from codeverse.models.gemini import GeminiModel
- from codeverse.models.keypool import KeyPool
+ from codeverse.models.retry import KeyPool
from tests.models.test_gemini import text_response
release_k2 = threading.Event()
diff --git a/harness/tests/cost/test_price_hygiene.py b/harness/tests/cost/test_price_hygiene.py
index 1791e5fa..694d6827 100644
--- a/harness/tests/cost/test_price_hygiene.py
+++ b/harness/tests/cost/test_price_hygiene.py
@@ -67,7 +67,7 @@ def test_image_models_have_a_per_image_price():
def test_image_price_agrees_with_the_image_backend():
"""``models/gemini_image.IMAGE_USD`` and the price table must not drift apart."""
- from codeverse.models.gemini_image import IMAGE_USD
+ from codeverse.models.gemini import IMAGE_USD
for model, usd in IMAGE_USD.items():
assert per_image_usd("gemini", model) == pytest.approx(usd), model
diff --git a/harness/tests/flywheel_cli/test_gemini_image.py b/harness/tests/flywheel_cli/test_gemini_image.py
index 863a1cb2..162f18a1 100644
--- a/harness/tests/flywheel_cli/test_gemini_image.py
+++ b/harness/tests/flywheel_cli/test_gemini_image.py
@@ -16,8 +16,8 @@ pytest.importorskip("google.genai")
from PIL import Image
from codeverse.models.base import ModelError
-from codeverse.models.gemini_image import GeminiImageModel
-from codeverse.models.keypool import KeyPool
+from codeverse.models.gemini import GeminiImageModel
+from codeverse.models.retry import KeyPool
def _png_bytes() -> bytes:
diff --git a/harness/tests/models/test_anthropic.py b/harness/tests/models/test_anthropic.py
index 96ffbf36..cbb76053 100644
--- a/harness/tests/models/test_anthropic.py
+++ b/harness/tests/models/test_anthropic.py
@@ -17,8 +17,13 @@ from codeverse.contracts.chat import (
ToolResultPart,
ToolSpec,
)
-from codeverse.models.anthropic import AnthropicModel, classify_exception
-from codeverse.models.anthropic_convert import THINKING_BLOCKS, build_kwargs, to_messages
+from codeverse.models.anthropic import (
+ THINKING_BLOCKS,
+ AnthropicModel,
+ build_kwargs,
+ classify_exception,
+ to_messages,
+)
from codeverse.models.base import ModelError
PNG_B64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
diff --git a/harness/tests/models/test_control_chars.py b/harness/tests/models/test_control_chars.py
index 0ead279b..3cd0ce1d 100644
--- a/harness/tests/models/test_control_chars.py
+++ b/harness/tests/models/test_control_chars.py
@@ -80,8 +80,7 @@ def test_the_anthropic_submit_tool_path_is_sanitised_too():
from types import SimpleNamespace as NS
from codeverse.contracts.chat import ChatMessage, ChatRequest
- from codeverse.models.anthropic import AnthropicModel
- from codeverse.models.anthropic_convert import SUBMIT_TOOL
+ from codeverse.models.anthropic import SUBMIT_TOOL, AnthropicModel
block = NS(type="tool_use", id="t1", name=SUBMIT_TOOL,
input={"description": "0.078 \x00 0.300 slab"})
diff --git a/harness/tests/models/test_gemini.py b/harness/tests/models/test_gemini.py
index d9e8f011..96261c13 100644
--- a/harness/tests/models/test_gemini.py
+++ b/harness/tests/models/test_gemini.py
@@ -20,9 +20,15 @@ from codeverse.contracts.chat import (
)
from codeverse.contracts.plan import StaticPlan
from codeverse.models.base import ModelError
-from codeverse.models.gemini import GeminiModel, classify_exception, failure_outcome
-from codeverse.models.gemini_convert import SIGNATURES, build_config, to_contents
-from codeverse.models.keypool import MAX_WAIT_S, KeyPool
+from codeverse.models.gemini import (
+ SIGNATURES,
+ GeminiModel,
+ build_config,
+ classify_exception,
+ failure_outcome,
+ to_contents,
+)
+from codeverse.models.retry import MAX_WAIT_S, KeyPool
PNG_1PX = base64.b64decode(
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
@@ -545,7 +551,7 @@ def _resp_with_calls(parts: list[types.Part]) -> types.GenerateContentResponse:
def test_synthetic_call_ids_are_never_echoed_to_the_provider():
"""When the provider sent NO id we mint one for local pairing — and it must
never travel back to Gemini (an id the provider did not issue)."""
- from codeverse.models.gemini_convert import is_synthetic_call_id
+ from codeverse.models.gemini import is_synthetic_call_id
tool = ToolSpec(name="measure", description="m", parameters={"type": "object", "properties": {}})
m, log, _ = make_model([call_response("measure", {"part": "all"}), text_response("ok")])
@@ -568,7 +574,7 @@ def test_two_parallel_same_name_calls_keep_their_provider_ids():
"""Two calls to the SAME tool in one turn: a GENUINE provider id is echoed verbatim on
BOTH the function_call replay and the function_response (both used to drop it), and only
those ids pair a response with its call — each keeping its own thought_signature."""
- from codeverse.models.gemini_convert import is_synthetic_call_id
+ from codeverse.models.gemini import is_synthetic_call_id
parts = []
for cid, target in (("id-a", "seat"), ("id-b", "leg")):
diff --git a/harness/tests/models/test_gemini_scheduling.py b/harness/tests/models/test_gemini_scheduling.py
index 1535417f..49033c2d 100644
--- a/harness/tests/models/test_gemini_scheduling.py
+++ b/harness/tests/models/test_gemini_scheduling.py
@@ -13,9 +13,7 @@ from google.genai import errors as genai_errors
from codeverse.contracts.chat import ChatMessage, ChatRequest, ImagePart
from codeverse.models.base import ModelError
from codeverse.models.gemini import GeminiModel, shared_pool
-from codeverse.models.keypool import KeyPool
-from codeverse.models.storm import StormGate
-from codeverse.models.tokens import request_tokens
+from codeverse.models.retry import KeyPool, StormGate, request_tokens
from tests.models.test_gemini import PNG_1PX, make_model, text_response
diff --git a/harness/tests/models/test_keypool.py b/harness/tests/models/test_keypool.py
index 9ed1ae38..ee2f8c2e 100644
--- a/harness/tests/models/test_keypool.py
+++ b/harness/tests/models/test_keypool.py
@@ -7,7 +7,7 @@ import time
import pytest
-from codeverse.models.keypool import MAX_WAIT_S, KeyPool, KeyPoolExhausted, TokenBucket
+from codeverse.models.retry import MAX_WAIT_S, KeyPool, KeyPoolExhausted, TokenBucket
class Clock:
diff --git a/harness/tests/models/test_keypool_tpm.py b/harness/tests/models/test_keypool_tpm.py
index ddc736e0..49d25948 100644
--- a/harness/tests/models/test_keypool_tpm.py
+++ b/harness/tests/models/test_keypool_tpm.py
@@ -8,7 +8,7 @@ import threading
import pytest
-from codeverse.models.keypool import KeyPool, KeyPoolExhausted
+from codeverse.models.retry import KeyPool, KeyPoolExhausted
class Clock:
diff --git a/harness/tests/models/test_openai.py b/harness/tests/models/test_openai.py
index ff203f02..8de59ab6 100644
--- a/harness/tests/models/test_openai.py
+++ b/harness/tests/models/test_openai.py
@@ -11,8 +11,13 @@ import pytest
from codeverse.contracts.chat import ChatMessage, ChatRequest, ImagePart, ToolResultPart, ToolSpec
from codeverse.models.base import ModelError
-from codeverse.models.openai import OpenAIModel, classify_exception
-from codeverse.models.openai_convert import build_kwargs, reasoning_effort, to_messages
+from codeverse.models.openai import (
+ OpenAIModel,
+ build_kwargs,
+ classify_exception,
+ reasoning_effort,
+ to_messages,
+)
PNG_B64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
diff --git a/harness/tests/models/test_retry.py b/harness/tests/models/test_retry.py
index 5f4892f0..fd7dda2c 100644
--- a/harness/tests/models/test_retry.py
+++ b/harness/tests/models/test_retry.py
@@ -11,20 +11,18 @@ import pytest
from codeverse.contracts.common import Usage
from codeverse.models.base import ModelError
from codeverse.models.gemini import HTTP_TIMEOUT_FLOOR_S
-from codeverse.models.keypool import (
+from codeverse.models.retry import (
ACQUIRE_TIMEOUT_S,
MAX_WAIT_S,
+ RETRY_DEADLINE_S,
KeyPool,
KeyPoolExhausted,
Outcome,
-)
-from codeverse.models.retry import (
- RETRY_DEADLINE_S,
+ StormGate,
backoff_delay,
rotate_with_retries,
with_retries,
)
-from codeverse.models.storm import StormGate
def test_backoff_grows_and_caps():
diff --git a/harness/tests/models/test_storm.py b/harness/tests/models/test_storm.py
index b305b602..cb1bdb3c 100644
--- a/harness/tests/models/test_storm.py
+++ b/harness/tests/models/test_storm.py
@@ -6,8 +6,7 @@ import threading
import pytest
-from codeverse.models.keypool import MAX_WAIT_S
-from codeverse.models.storm import StormGate, all_gates, storm_gate
+from codeverse.models.retry import MAX_WAIT_S, StormGate, all_gates, storm_gate
class Clock:
diff --git a/harness/tests/texturing/test_live.py b/harness/tests/texturing/test_live.py
index fdb06e8e..9b7126e6 100644
--- a/harness/tests/texturing/test_live.py
+++ b/harness/tests/texturing/test_live.py
@@ -9,7 +9,7 @@ import pytest
from codeverse.config import get_settings
from codeverse.contracts.plan import StaticPlan
from codeverse.contracts.spec import Spec
-from codeverse.models.gemini_image import GeminiImageModel
+from codeverse.models.gemini import GeminiImageModel
from codeverse.texturing.generate import seam_score
from codeverse.texturing.plan import compose_image_prompt, material_plan