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.pyindex 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 CompletedProcfrom codeverse.config import get_settingsfrom codeverse.contracts.agent import AgentJob, AgentResultfrom codeverse.contracts.common import Usage-from codeverse.models.keypool import KeyPool, KeyPoolExhausted+from codeverse.models.retry import KeyPool, KeyPoolExhaustedlog = logging.getLogger(__name__)diff --git a/harness/codeverse/cli/doctor.py b/harness/codeverse/cli/doctor.pyindex 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 partof ``--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_gatess = get_settings()if not s.gemini_api_keys:diff --git a/harness/codeverse/cli/texture_cmd.py b/harness/codeverse/cli/texture_cmd.pyindex 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.pyindex 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 timefrom collections.abc import Callablefrom 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_contentfrom 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_b64from 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.pydeleted file mode 100644index 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, thinkingdiff --git a/harness/codeverse/models/gemini.py b/harness/codeverse/models/gemini.pyindex 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 jsonimport loggingimport reimport threadingimport 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_checkableimport httpxfrom google import genaifrom google.genai import errors as genai_errorsfrom 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 Usagefrom 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_bytesfrom 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, usagediff --git a/harness/codeverse/models/gemini_convert.py b/harness/codeverse/models/gemini_convert.pydeleted file mode 100644index 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, finishdiff --git a/harness/codeverse/models/gemini_image.py b/harness/codeverse/models/gemini_image.pydeleted file mode 100644index 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, usagediff --git a/harness/codeverse/models/keypool.py b/harness/codeverse/models/keypool.pydeleted file mode 100644index 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 bestdiff --git a/harness/codeverse/models/openai.py b/harness/codeverse/models/openai.pyindex 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 jsonimport loggingimport threadingimport timefrom collections.abc import Callablefrom 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 Usagefrom 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_b64from 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.pydeleted file mode 100644index 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.pyindex 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 annotationsimport loggingimport random+import threadingimport timefrom collections.abc import Callable, Sequencefrom concurrent.futures import Future, ThreadPoolExecutor, as_completed-from dataclasses import dataclass+from dataclasses import dataclass, fieldfrom 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 = 2if TYPE_CHECKING: # pragma: no coverfrom 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, StormGatelog = 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: amulti-minute gemini-3.7-flash "high demand" outage killed 8 bench runsunder 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 learnthe 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 inthe per-key TPM bucket at ``acquire`` and the reservation is reconciledagainst the provider's real count on ``report``, so a 200 k-token judge calland 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-effortlog.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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pyindex 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, GeminiImageModelreturn GeminiImageModel(model_id or DEFAULT_IMAGE_MODEL)diff --git a/harness/codeverse/texturing/run.py b/harness/codeverse/texturing/run.pyindex 2c2f98b9..69484e1a 100644--- a/harness/codeverse/texturing/run.py+++ b/harness/codeverse/texturing/run.py@@ -239,7 +239,7 @@ def texture_pass(# 3. imagesif image_model is None:- from codeverse.models.gemini_image import GeminiImageModel+ from codeverse.models.gemini import GeminiImageModelimage_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.mdindex d57a99e2..be5ddd26 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -93,13 +93,14 @@ codeverse/lines so it stays a leaffanout.py bounded parallel fan-out (fan_out, split_results, FanOutReport) — shared bytracks/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.pyagents/ 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, retrydiff --git a/harness/docs/COST.md b/harness/docs/COST.mdindex 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 keynow 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 isdiff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 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, KeyPoolExhaustedKeyPool(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 deadlinepool.try_acquire(*, tokens_hint=0, exclude=None) -> key | None # never waits (a hedged retry's extra key); holds a slot like acquirediff --git a/harness/tests/agents/test_gemini_cli.py b/harness/tests/agents/test_gemini_cli.pyindex 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: Workspacedef 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 KeyPoolExhaustedclass Dead:def acquire(self, **kw):diff --git a/harness/tests/cost/test_instrument.py b/harness/tests/cost/test_instrument.pyindex 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 ModelErrorfrom codeverse.models.gemini import GeminiModel- from codeverse.models.keypool import KeyPool+ from codeverse.models.retry import KeyPoolfrom tests.models.test_gemini import text_responserelease_k2 = threading.Event()diff --git a/harness/tests/cost/test_price_hygiene.py b/harness/tests/cost/test_price_hygiene.pyindex 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_USDfor model, usd in IMAGE_USD.items():assert per_image_usd("gemini", model) == pytest.approx(usd), modeldiff --git a/harness/tests/flywheel_cli/test_gemini_image.py b/harness/tests/flywheel_cli/test_gemini_image.pyindex 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 Imagefrom 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 KeyPooldef _png_bytes() -> bytes:diff --git a/harness/tests/models/test_anthropic.py b/harness/tests/models/test_anthropic.pyindex 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 ModelErrorPNG_B64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="diff --git a/harness/tests/models/test_control_chars.py b/harness/tests/models/test_control_chars.pyindex 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 NSfrom 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, AnthropicModelblock = 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.pyindex 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 StaticPlanfrom 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, KeyPoolPNG_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 mustnever 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_idtool = 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 onBOTH the function_call replay and the function_response (both used to drop it), and onlythose 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_idparts = []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.pyindex 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_errorsfrom codeverse.contracts.chat import ChatMessage, ChatRequest, ImagePartfrom codeverse.models.base import ModelErrorfrom 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_tokensfrom tests.models.test_gemini import PNG_1PX, make_model, text_responsediff --git a/harness/tests/models/test_keypool.py b/harness/tests/models/test_keypool.pyindex 9ed1ae38..ee2f8c2e 100644--- a/harness/tests/models/test_keypool.py+++ b/harness/tests/models/test_keypool.py@@ -7,7 +7,7 @@ import timeimport pytest-from codeverse.models.keypool import MAX_WAIT_S, KeyPool, KeyPoolExhausted, TokenBucket+from codeverse.models.retry import MAX_WAIT_S, KeyPool, KeyPoolExhausted, TokenBucketclass Clock:diff --git a/harness/tests/models/test_keypool_tpm.py b/harness/tests/models/test_keypool_tpm.pyindex ddc736e0..49d25948 100644--- a/harness/tests/models/test_keypool_tpm.py+++ b/harness/tests/models/test_keypool_tpm.py@@ -8,7 +8,7 @@ import threadingimport pytest-from codeverse.models.keypool import KeyPool, KeyPoolExhausted+from codeverse.models.retry import KeyPool, KeyPoolExhaustedclass Clock:diff --git a/harness/tests/models/test_openai.py b/harness/tests/models/test_openai.pyindex ff203f02..8de59ab6 100644--- a/harness/tests/models/test_openai.py+++ b/harness/tests/models/test_openai.py@@ -11,8 +11,13 @@ import pytestfrom codeverse.contracts.chat import ChatMessage, ChatRequest, ImagePart, ToolResultPart, ToolSpecfrom 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.pyindex 5f4892f0..fd7dda2c 100644--- a/harness/tests/models/test_retry.py+++ b/harness/tests/models/test_retry.py@@ -11,20 +11,18 @@ import pytestfrom codeverse.contracts.common import Usagefrom codeverse.models.base import ModelErrorfrom 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 StormGatedef test_backoff_grows_and_caps():diff --git a/harness/tests/models/test_storm.py b/harness/tests/models/test_storm.pyindex b305b602..cb1bdb3c 100644--- a/harness/tests/models/test_storm.py+++ b/harness/tests/models/test_storm.py@@ -6,8 +6,7 @@ import threadingimport 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_gateclass Clock:diff --git a/harness/tests/texturing/test_live.py b/harness/tests/texturing/test_live.pyindex fdb06e8e..9b7126e6 100644--- a/harness/tests/texturing/test_live.py+++ b/harness/tests/texturing/test_live.py@@ -9,7 +9,7 @@ import pytestfrom codeverse.config import get_settingsfrom codeverse.contracts.plan import StaticPlanfrom codeverse.contracts.spec import Spec-from codeverse.models.gemini_image import GeminiImageModel+from codeverse.models.gemini import GeminiImageModelfrom codeverse.texturing.generate import seam_scorefrom codeverse.texturing.plan import compose_image_prompt, material_plan