@yahyahammad/venastine 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
package/core/client.py ADDED
@@ -0,0 +1,1548 @@
1
+ from dataclasses import dataclass, field
2
+ from typing import Optional
3
+ from uuid import UUID, uuid4
4
+ import json
5
+ import logging
6
+ import os
7
+
8
+ import credentials
9
+ from credentials import load_provider_data, no_providers_message, \
10
+ unknown_provider_message
11
+ import config
12
+
13
+ # ROADMAP_v2 §33 W7 (#135). The three provider SDKs are NOT imported here.
14
+ #
15
+ # core.loop imports this module and main.py imports core.loop, so a module
16
+ # -scope `from openai import OpenAI` is paid by every invocation of either
17
+ # shell -- `--help`, `--summary`, a mistyped flag, the thread picker --
18
+ # before argparse runs. Measured on Windows: 5.6s to print --help, of
19
+ # which 3.5s was the three SDKs, and no run uses more than one of them.
20
+ #
21
+ # Each import therefore sits at the point of use, INSIDE the branch that
22
+ # needs it rather than at the top of the enclosing function: a
23
+ # GOOGLE-only name imported at the top of `_messages_for_provider` would
24
+ # be paid on every Anthropic turn, which is most of them, and would leave
25
+ # the defect in place while looking fixed.
26
+ #
27
+ # Deferred imports are otherwise not this file's idiom. The trade is
28
+ # stated here rather than left to be re-derived: `import` is cached after
29
+ # the first call, so the cost is a dict lookup per call on the hot path
30
+ # and seconds saved on every launch that never makes one.
31
+
32
+ logger = logging.getLogger(__name__)
33
+
34
+ # Caches initialized clients so repeated calls for the same provider don't
35
+ # rebuild the client (and re-read the credentials file) every time.
36
+ _client_cache: dict[str, object] = {}
37
+
38
+
39
+ def api_initialization(provider_name: str):
40
+ if provider_name in _client_cache:
41
+ return _client_cache[provider_name]
42
+
43
+ provider_data = load_provider_data()
44
+
45
+ # #24. The file's absence and the provider's absence are different
46
+ # problems and now say so: the first names the path that was checked
47
+ # and its remedy, the second names what IS configured, like /model's
48
+ # refusal. Still ValueError either way -- callers (and tests) catch
49
+ # the type, not the text. The constant is read THROUGH the module,
50
+ # not imported: a from-import would freeze the value at this module's
51
+ # import time and a test's monkeypatch of credentials.LLM_PROVIDERS_FILE
52
+ # would not be seen here.
53
+ if not provider_data and not os.path.exists(
54
+ credentials.LLM_PROVIDERS_FILE):
55
+ raise ValueError(no_providers_message())
56
+ if provider_name not in provider_data:
57
+ raise ValueError(unknown_provider_message(provider_name, provider_data))
58
+
59
+ entry = provider_data[provider_name]
60
+
61
+ if entry.get("is_v1_compatible", False):
62
+ from openai import OpenAI
63
+ client = OpenAI(base_url=entry["API_URL"], api_key=entry["API_KEY"])
64
+ elif provider_name == "GOOGLE":
65
+ from google import genai
66
+ client = genai.Client(api_key=entry["API_KEY"])
67
+ elif provider_name == "ANTHROPIC":
68
+ from anthropic import Anthropic
69
+ client = Anthropic(api_key=entry["API_KEY"])
70
+ # Add further proprietary API formats here
71
+ else:
72
+ raise ValueError(f"Provider {provider_name} is not currently supported")
73
+
74
+ _client_cache[provider_name] = client
75
+ return client
76
+
77
+
78
+ # ============================================================================
79
+ # ---- Normalized response shape ---------------------------------------------
80
+ # ============================================================================
81
+
82
+ @dataclass
83
+ class ToolCallRequest:
84
+ id: str
85
+ name: str
86
+ input: dict
87
+ # §33 W2 (#37). Set when the provider's `arguments` string could not
88
+ # be read as a JSON object -- most often because the response was cut
89
+ # off mid-arguments by the token limit. TRANSPORT ONLY: it describes
90
+ # one wire read, not the thread, so `add_assistant_message` persists
91
+ # {id, name, input} exactly as before and this never reaches storage.
92
+ #
93
+ # The call is still constructed rather than dropped. The model made a
94
+ # call and is owed an answer about it; a silently missing tool_result
95
+ # is M4's pairing defect, and `input={}` with no error would run the
96
+ # tool with arguments nobody sent.
97
+ parse_error: Optional[str] = None
98
+
99
+
100
+ @dataclass
101
+ class ModelResponse:
102
+ text: str
103
+ tool_calls: list[ToolCallRequest] = field(default_factory=list)
104
+ usage: dict = field(default_factory=lambda: {"input_tokens": 0, "output_tokens": 0})
105
+ stop_reason: str = "complete" # set by RunAgentLoop._run(), not here -- see core/loop.py
106
+ thread_id: Optional[UUID] = None # set by the entry points (stream_deep_research_mode,
107
+ # continue_conversation) so callers can persist/retry
108
+ # against the same thread. call_model() itself NEVER
109
+ # sets this -- it has no thread concept.
110
+ # §25: calls that proceeded on a PRE-FLIGHT grant rather than a live
111
+ # approval. Set by _run() (like stop_reason), never by call_model().
112
+ #
113
+ # Authorization moved up-front, so accountability moves after: this is
114
+ # the record of what a single launch-time yes actually authorised,
115
+ # written into the run artifacts for a pipeline nobody was watching.
116
+ # Empty for every run that granted nothing, which is every run today.
117
+ granted_calls: list = field(default_factory=list)
118
+ # ROADMAP_v2 §21: compaction notices raised during this run, each a
119
+ # {"kind", "text"} dict. Set by _run() like stop_reason and
120
+ # granted_calls, never by call_model().
121
+ #
122
+ # Carried here as well as yielded as a LoopEvent because
123
+ # run_to_completion() discards non-final events: the TUI watches the
124
+ # generator, but the CLI and the pipeline drain it, so a notice with
125
+ # only the event route would be invisible in two shells out of three.
126
+ notices: list = field(default_factory=list)
127
+ # #4 (batch 27): the two per-turn figures the loop computes, set by
128
+ # _run() like stop_reason -- never by call_model(), which has no turn
129
+ # concept. UNPRICED APPROXIMATIONS, deliberately: raw provider counts,
130
+ # no cache-read/write pricing and no currency anywhere. Precise spend
131
+ # lives in the provider's dashboard; these exist for RELATIVE reasoning
132
+ # ("is this turn ballooning the context?"), not billing truth.
133
+ #
134
+ # turn_billed_tokens: cumulative input+output over this user-turn so
135
+ # far -- the spend meter's running total (the prompt is re-sent every
136
+ # step, so this grows quadratically in a tool-using turn, which is
137
+ # correct: that is what the provider bills).
138
+ # turn_new_tokens: what THIS TURN added to the thread -- output plus
139
+ # positive input deltas, the first call's inherited prompt excluded
140
+ # and mid-turn compaction shrinks clamped away. This is the figure
141
+ # anything reasoning about SIZE reads; the spend meter must never be
142
+ # read that way again (TECHNICAL_DEBT item 9, closed batch 27).
143
+ turn_billed_tokens: Optional[int] = None
144
+ turn_new_tokens: Optional[int] = None
145
+ # Batch 44 (§44). The turn's reasoning, as the PROVIDER'S OWN BLOCKS
146
+ # rather than as the text §38 streams for display:
147
+ #
148
+ # {"provider": ..., "model": ..., "blocks": [ ...native... ]}
149
+ #
150
+ # §38's O1 made thinking display-only -- never persisted, never back
151
+ # on the wire -- and sidestepped "does a provider need its own
152
+ # thinking returned next turn?" by never returning it. That answer
153
+ # stopped being free once it was clear the model had never seen its
154
+ # own reasoning at ALL: not across a restart, and not between two
155
+ # turns of one live session, so a turn re-derives what it already
156
+ # worked out. O1 is amended here.
157
+ #
158
+ # BLOCKS, NOT THE STREAMED TEXT, and that is the whole reason this is
159
+ # a field rather than an accumulation in core/loop.py. An Anthropic
160
+ # thinking block carries a `signature`; the model reuses its own state
161
+ # through the block, not through the prose, so a re-serialised copy of
162
+ # the deltas would be unsigned and rejected. The blocks are read off
163
+ # get_final_message(), which already has them in hand.
164
+ #
165
+ # `provider` and `model` ride along because the replay rule is
166
+ # per-model: blocks go back UNCHANGED to the model that produced them
167
+ # and are dropped for anything else.
168
+ thinking: Optional[dict] = None
169
+
170
+
171
+ def _tool_arguments(raw_args: str, tool_name: str,
172
+ finish_reason: Optional[str] = None) -> tuple:
173
+ """(input, parse_error) for one provider `arguments` string.
174
+
175
+ The ONLY place a wire string is parsed as JSON. Google and Anthropic
176
+ hand back dicts, so this is the OpenAI-compatible branch's alone --
177
+ which is the branch a local model server takes, and truncated or
178
+ malformed tool arguments are likeliest there.
179
+
180
+ §33 W1 (#37): a failure is RETURNED, not raised. `dispatch()` turning
181
+ handler exceptions into {"error": ...} is the whole reason a raising
182
+ TOOL cannot kill a run; nothing played that role for a raising
183
+ TRANSLATION one layer up, so a response cut mid-arguments took a
184
+ JSONDecodeError out of this generator, out of _run(), and into the
185
+ pipeline's `except Exception` -- recording status='failed' on a
186
+ finished ten-pass run.
187
+
188
+ §33 W4: `finish_reason` is what separates "the provider emitted bad
189
+ JSON" from "the answer was cut off", which is the likeliest cause by
190
+ far and the only one the model can act on.
191
+ """
192
+ # W9: no arguments is not an error. `get_time` declares properties=[]
193
+ # and `pin` has no required parameters, so this is a live path -- and
194
+ # json.loads("") raises. Dropping this fallback was green on the whole
195
+ # suite when audit unit 3 ran mutation P10.
196
+ if not raw_args:
197
+ return {}, None
198
+
199
+ try:
200
+ parsed = json.loads(raw_args)
201
+ except json.JSONDecodeError as exc:
202
+ if finish_reason == "length":
203
+ return {}, (
204
+ f"The arguments for {tool_name} were cut off by the response "
205
+ f"token limit, so the call could not be made. Reissue it with "
206
+ f"shorter arguments."
207
+ )
208
+ return {}, (
209
+ f"The arguments for {tool_name} were not valid JSON ({exc.msg}), "
210
+ f"so the call could not be made. Reissue it with valid JSON "
211
+ f"arguments."
212
+ )
213
+
214
+ # Valid JSON that is not an object -- "null", "[1,2]", "3". Rarer than
215
+ # a truncation and caught in the same place because the consequence is
216
+ # the same: dispatch() would be handed something that is not params.
217
+ if not isinstance(parsed, dict):
218
+ return {}, (
219
+ f"The arguments for {tool_name} parsed as "
220
+ f"{type(parsed).__name__}, not a JSON object, so the call could "
221
+ f"not be made. Reissue it with a JSON object."
222
+ )
223
+
224
+ return parsed, None
225
+
226
+
227
+ @dataclass
228
+ class StreamToken:
229
+ """One token-level event yielded by call_model_stream(). Exactly one
230
+ field is populated per yield: text_delta for incremental text,
231
+ thinking_delta for incremental REASONING text, or final_response for
232
+ the terminal ModelResponse (with accumulated tool calls and usage).
233
+
234
+ §38 O1: thinking is DISPLAY-ONLY. It never joins the accumulated
235
+ `text`, is never persisted, and is never sent back on the wire -- so
236
+ the ModelResponse each branch produces is byte-identical to what it
237
+ produced before thinking was captured, and D20's persisted turn and
238
+ M4's fold boundary keep exactly the bytes they have today.
239
+
240
+ Which providers actually populate it (§38 O2): Anthropic, and every
241
+ OpenAI-compatible provider that streams `reasoning_content` or
242
+ `reasoning` (DeepSeek, Qwen, Z.AI, OpenRouter). It stays empty on
243
+ OPENAI -- its Chat Completions endpoint returns no reasoning text at
244
+ all -- and on GOOGLE, whose request deliberately does not ask for
245
+ thought summaries. Absence is not a bug there; see O2.
246
+ """
247
+ text_delta: Optional[str] = None
248
+ thinking_delta: Optional[str] = None
249
+ final_response: Optional[ModelResponse] = None
250
+
251
+
252
+ # ============================================================================
253
+ # ---- Tool schema translation ------------------------------------------------
254
+ # ============================================================================
255
+
256
+ def _tools_for_provider(provider_name: str, tool_schemas: list[dict]):
257
+ """
258
+ tool_schemas arrive in Anthropic's native shape (name/description/
259
+ input_schema), since that's what every tool's TOOL_SCHEMA already
260
+ produces. Translate into whatever shape the target provider expects.
261
+ """
262
+ if not tool_schemas:
263
+ return None
264
+
265
+ if provider_name == "ANTHROPIC":
266
+ return tool_schemas
267
+
268
+ if provider_name == "GOOGLE":
269
+ from google.genai import types as genai_types
270
+ return [genai_types.Tool(
271
+ function_declarations=[
272
+ genai_types.FunctionDeclaration(
273
+ name=s["name"],
274
+ description=s["description"],
275
+ parameters=s["input_schema"],
276
+ )
277
+ for s in tool_schemas
278
+ ]
279
+ )]
280
+
281
+ # OpenAI-compatible providers
282
+ return [
283
+ {
284
+ "type": "function",
285
+ "function": {
286
+ "name": s["name"],
287
+ "description": s["description"],
288
+ "parameters": s["input_schema"],
289
+ },
290
+ }
291
+ for s in tool_schemas
292
+ ]
293
+
294
+
295
+ # ============================================================================
296
+ # ---- Message history translation -------------------------------------------
297
+ # ============================================================================
298
+ # core/memory.py stores history in a provider-neutral shape (see that
299
+ # file's docstring). This is the counterpart to _tools_for_provider above,
300
+ # applied to conversation history instead of tool schemas -- the ONLY
301
+ # place either provider's specific message wire format should exist.
302
+
303
+ def _is_tool_result_message(msg: dict) -> bool:
304
+ return isinstance(msg.get("content"), list) and all(
305
+ isinstance(b, dict) and b.get("type") == "tool_result" for b in msg["content"]
306
+ )
307
+
308
+
309
+ def _is_empty_assistant_turn(msg: dict) -> bool:
310
+ """An assistant turn carrying neither text nor tool calls (#13, #36).
311
+
312
+ Produced when the model returns nothing at all -- a safety filter, a
313
+ truncation, an empty pass response. `core/loop.py` persists it because
314
+ D20 requires the assistant turn to be written before any stop-condition
315
+ branching, so it reaches translation on every resume of that thread.
316
+
317
+ It is meaningless on every provider, and each branch used to mangle it
318
+ differently from the same neutral input:
319
+
320
+ OPENAI: {"role": "assistant", "content": null} <- #13
321
+ ANTHROPIC: {"role": "assistant", "content": []} <- #36
322
+ GOOGLE: skipped entirely <- guarded
323
+
324
+ Only Google was guarded, and only because Google was the provider being
325
+ debugged when it surfaced. Dropping it above the branch split is
326
+ AGENTS.md's *fix at the producer, not the consumer*: all three branches
327
+ become correct at once, and so does the next one.
328
+
329
+ Requiring BOTH halves to be empty is load-bearing. An empty text WITH
330
+ tool calls is legitimate on the OpenAI schema -- a tool-call-only turn
331
+ -- and `test_messages_openai_assistant_with_null_text` covers it, so a
332
+ guard keyed on text alone breaks a valid case.
333
+ """
334
+ return (msg.get("role") == "assistant"
335
+ and not msg.get("text")
336
+ and not msg.get("tool_calls"))
337
+
338
+
339
+ def _echoed_blocks(provider_name: str, model: Optional[str],
340
+ msg: dict) -> list:
341
+ """This turn's stored thinking blocks, if they may go back (§44).
342
+
343
+ THE GATE IS THE PAIR, and it is the whole safety argument. A stored
344
+ record names the provider and model that produced it; blocks go back
345
+ UNCHANGED to that model and to nothing else. An Anthropic block carries
346
+ a signature the model verifies against its own state, so handing it to
347
+ a different model is at best ignored and at worst a 400 -- and after a
348
+ /model switch the thread is full of blocks the new model never wrote.
349
+ Dropping them is always safe: the harness then does exactly what it did
350
+ before this batch.
351
+
352
+ Empty for every message written before §44, which is what keeps the
353
+ translation byte-identical for every existing thread.
354
+ """
355
+ record = msg.get("thinking")
356
+ if not isinstance(record, dict) or not model:
357
+ return []
358
+ if record.get("provider") != provider_name or record.get("model") != model:
359
+ return []
360
+ return [b for b in record.get("blocks") or [] if isinstance(b, dict)]
361
+
362
+
363
+ def _messages_for_provider(provider_name: str, neutral_messages: list[dict],
364
+ model: Optional[str] = None,
365
+ echo_reasoning: bool = False) -> list:
366
+ """The wire shape for one provider.
367
+
368
+ `model` and `echo_reasoning` are §44's: they decide whether a stored
369
+ thinking record may travel. Both DEFAULT to the pre-§44 behaviour --
370
+ no model means no echo, and the OpenAI-compatible side is opt-in per
371
+ provider -- so a caller that does not pass them gets exactly the
372
+ translation this function produced before.
373
+ """
374
+ # One rule, above the split (#13, #36). Note this can leave two
375
+ # consecutive user turns -- which is the shape Google's branch has
376
+ # always produced here, and which
377
+ # `test_messages_google_empty_assistant_turn_skipped` has always
378
+ # asserted.
379
+ neutral_messages = [m for m in neutral_messages
380
+ if not _is_empty_assistant_turn(m)]
381
+
382
+ if provider_name == "GOOGLE":
383
+ from google.genai import types as genai_types
384
+ # Build a {tool_call_id: function_name} lookup from assistant
385
+ # messages so we can populate FunctionResponse.name (required by
386
+ # Google but absent from the neutral tool-result shape).
387
+ call_id_to_name: dict[str, str] = {}
388
+ for msg in neutral_messages:
389
+ if msg["role"] == "assistant":
390
+ for tc in msg.get("tool_calls", []):
391
+ call_id_to_name[tc["id"]] = tc["name"]
392
+
393
+ translated = []
394
+ for msg in neutral_messages:
395
+ role = msg["role"]
396
+
397
+ if role == "user":
398
+ translated.append(genai_types.Content(
399
+ role="user",
400
+ parts=[genai_types.Part(text=msg["content"])],
401
+ ))
402
+
403
+ elif role == "assistant":
404
+ parts = []
405
+ if msg.get("text"):
406
+ parts.append(genai_types.Part(text=msg["text"]))
407
+ for tc in msg.get("tool_calls", []):
408
+ parts.append(genai_types.Part(
409
+ function_call=genai_types.FunctionCall(
410
+ name=tc["name"],
411
+ args=tc["input"],
412
+ id=tc["id"],
413
+ )
414
+ ))
415
+ # Google rejects Content with empty parts. The turn that
416
+ # produced them is now dropped above the branch split, so
417
+ # this branch no longer needs its own guard -- one rule
418
+ # rather than two that can disagree (#36).
419
+ translated.append(genai_types.Content(role="model", parts=parts))
420
+
421
+ elif role == "tool":
422
+ name = call_id_to_name.get(msg["tool_call_id"])
423
+ if name is None:
424
+ raise ValueError(
425
+ f"Tool result references tool_call_id={msg['tool_call_id']!r} "
426
+ f"but no assistant message in the history made that call"
427
+ )
428
+ part = genai_types.Part(
429
+ function_response=genai_types.FunctionResponse(
430
+ name=name,
431
+ response={"result": msg["content"]},
432
+ )
433
+ )
434
+ # Batch consecutive tool results into a single user
435
+ # Content — Google requires strict user/model alternation.
436
+ if (translated
437
+ and translated[-1].role == "user"
438
+ and all(p.function_response is not None for p in translated[-1].parts)):
439
+ translated[-1].parts.append(part)
440
+ else:
441
+ translated.append(genai_types.Content(role="user", parts=[part]))
442
+
443
+ return translated
444
+
445
+ if provider_name == "ANTHROPIC":
446
+ translated: list[dict] = []
447
+ for msg in neutral_messages:
448
+ role = msg["role"]
449
+
450
+ if role == "user":
451
+ translated.append({"role": "user", "content": msg["content"]})
452
+
453
+ elif role == "assistant":
454
+ # §44. FIRST in the content array, because that is the
455
+ # order the model emitted them in and the order the API
456
+ # documents for the replay -- a signed block after the
457
+ # text it preceded is not the same message.
458
+ content = list(_echoed_blocks(provider_name, model, msg))
459
+ if msg.get("text"):
460
+ content.append({"type": "text", "text": msg["text"]})
461
+ for tc in msg.get("tool_calls", []):
462
+ content.append({
463
+ "type": "tool_use", "id": tc["id"], "name": tc["name"], "input": tc["input"],
464
+ })
465
+ translated.append({"role": "assistant", "content": content})
466
+
467
+ elif role == "tool":
468
+ # Anthropic wants every tool result from one turn batched
469
+ # into a SINGLE user message with multiple tool_result
470
+ # blocks, not one message per result -- merge consecutive
471
+ # tool-role entries into the same message rather than
472
+ # appending a new one each time.
473
+ block = {
474
+ "type": "tool_result",
475
+ "tool_use_id": msg["tool_call_id"],
476
+ "content": msg["content"],
477
+ }
478
+ if translated and translated[-1]["role"] == "user" and _is_tool_result_message(translated[-1]):
479
+ translated[-1]["content"].append(block)
480
+ else:
481
+ translated.append({"role": "user", "content": [block]})
482
+
483
+ return translated
484
+
485
+ # OpenAI-compatible: close to 1:1, each tool result is its own message
486
+ translated = []
487
+ for msg in neutral_messages:
488
+ role = msg["role"]
489
+
490
+ if role == "user":
491
+ translated.append({"role": "user", "content": msg["content"]})
492
+
493
+ elif role == "assistant":
494
+ entry: dict = {"role": "assistant", "content": msg.get("text") or None}
495
+ # §44, and OPT-IN PER PROVIDER rather than on by default.
496
+ # There is no standard for sending reasoning back on this wire
497
+ # the way there is for receiving it: DeepSeek documents that
498
+ # reasoning_content must not be supplied on input and 400s,
499
+ # while OpenRouter accepts it for some models and ignores it
500
+ # for others. Off means today's behaviour exactly, so a
501
+ # provider that has never been tried cannot be broken by this.
502
+ if echo_reasoning:
503
+ echoed = "\n\n".join(
504
+ b.get("text", "") for b in _echoed_blocks(
505
+ provider_name, model, msg)
506
+ if b.get("text"))
507
+ if echoed:
508
+ entry["reasoning_content"] = echoed
509
+ if msg.get("tool_calls"):
510
+ entry["tool_calls"] = [
511
+ {
512
+ "id": tc["id"],
513
+ "type": "function",
514
+ "function": {"name": tc["name"], "arguments": json.dumps(tc["input"])},
515
+ }
516
+ for tc in msg["tool_calls"]
517
+ ]
518
+ translated.append(entry)
519
+
520
+ elif role == "tool":
521
+ translated.append({
522
+ "role": "tool", "tool_call_id": msg["tool_call_id"], "content": msg["content"],
523
+ })
524
+
525
+ return translated
526
+
527
+
528
+ # ============================================================================
529
+ # ---- The actual call --------------------------------------------------------
530
+ # ============================================================================
531
+
532
+ # ============================================================================
533
+ # ---- Sampling + reasoning-effort translation (ROADMAP_v2 §16) ---------------
534
+ # ============================================================================
535
+ #
536
+ # Both helpers below are the same "translate at the boundary, once" case that
537
+ # _tools_for_provider / _messages_for_provider exist for: the three providers
538
+ # express these concepts differently enough that no caller should have to know.
539
+
540
+ # (provider_name, model) -> supported effort levels. Populated lazily; the
541
+ # Anthropic branch queries the API once per process rather than per call.
542
+ _effort_levels_cache: dict[tuple[str, str], list[str]] = {}
543
+
544
+ # (provider_name, model) -> context window in tokens, or None for "asked,
545
+ # and this provider does not report one". Same lazy, once-per-process
546
+ # posture as the effort cache above; see context_window_for() for why None
547
+ # is cached and a raised query is not.
548
+ _context_window_cache: dict[tuple[str, str], Optional[int]] = {}
549
+
550
+ # (provider_name, model) -> how many times the query has RAISED.
551
+ #
552
+ # The middle ground between #35's two bad options. Caching a failure makes
553
+ # one transient error suppress the query for the life of the process;
554
+ # never caching one means a provider with no /models endpoint at all --
555
+ # Grok, Fireworks, Z.AI -- is asked again on every turn, which across a
556
+ # ten-pass research run is ten failing HTTP calls to learn the same thing.
557
+ # So a failure is retried, and after this many it settles on the table and
558
+ # says so once. Transient blips still recover; a permanent 404 costs three
559
+ # calls per process, not one per turn.
560
+ _context_window_failures: dict[tuple[str, str], int] = {}
561
+ MAX_CONTEXT_WINDOW_QUERY_ATTEMPTS = 3
562
+
563
+
564
+ def _sampling_kwargs(provider_name: str, model: str, temperature) -> dict:
565
+ """Sampling parameters for this call, or {} when the model rejects them.
566
+
567
+ Current Anthropic models removed temperature/top_p/top_k outright (any
568
+ value returns a 400) and Sonnet 5 rejects non-default values. Sending
569
+ one anyway is not a degraded request, it is a failed one -- which is how
570
+ ROADMAP §10's ensemble mode came to be built, documented as working, and
571
+ incapable of running against this harness's own default model.
572
+
573
+ Dropping the parameter is logged at WARNING rather than done silently.
574
+
575
+ THIS FUNCTION NOW HAS NO CALLER THAT DEPENDS ON IT, and the warning is
576
+ what makes that safe. Ensemble mode used to be the one, and
577
+ orchestrator.py carried a guard refusing to run it on a model in the set
578
+ below. §10's revisit replaced sampling variation with a roster of
579
+ different models, so the guard is gone and nothing in the harness passes
580
+ a temperature any more.
581
+
582
+ Kept rather than removed: `temperature` still threads through
583
+ core/loop.py, this is still the correct boundary translation for it, and
584
+ the next caller to want sampling variation needs to be told rather than
585
+ silently ignored. If this warning ever fires, something new is relying on
586
+ sampling variation without knowing it cannot have it -- which is exactly
587
+ how §10 came to be built, documented as working, and incapable of running
588
+ against this harness's own default model.
589
+ """
590
+ if temperature is None:
591
+ return {}
592
+ if model in config.MODELS_REJECTING_SAMPLING_PARAMS:
593
+ logger.warning(
594
+ "Dropping temperature=%s: model %r rejects sampling parameters. "
595
+ "Steer via prompting or reasoning effort instead.",
596
+ temperature, model,
597
+ )
598
+ return {}
599
+ return {"temperature": temperature}
600
+
601
+
602
+ def effort_for(client, provider_name: str, model: str,
603
+ requested: Optional[str]) -> Optional[str]:
604
+ """The effort level to actually SEND to (provider_name, model), or None.
605
+
606
+ One validator for every send site, because nothing else checked a
607
+ level against the model that would receive it. Three ways a wrong one
608
+ used to reach the wire, all of them 400ing every turn until the user
609
+ intervened by hand:
610
+
611
+ * a persisted settings.json `tui.effort` was trusted as-is;
612
+ * the TUI's current level was inherited by an agent that declares
613
+ its OWN model/provider, so a level validated for one model was
614
+ sent to a different one;
615
+ * nothing revalidated after a /model or agent switch.
616
+
617
+ `effort=None` sends nothing on every provider and is the one
618
+ universally safe value, so dropping is always available as an answer.
619
+
620
+ On a FAILED lookup the requested level is passed through unverified
621
+ with a warning rather than dropped: a transient network blip must not
622
+ silently downgrade a deliberate choice. A genuinely wrong level still
623
+ fails at the provider, which is the honest outcome.
624
+ """
625
+ if not requested:
626
+ return None
627
+ levels, authoritative = _effort_levels(client, provider_name, model)
628
+ if requested in levels:
629
+ return requested
630
+ if not authoritative:
631
+ logger.warning(
632
+ "Could not verify effort %r for %s/%s; sending it unverified.",
633
+ requested, provider_name, model)
634
+ return requested
635
+ logger.warning(
636
+ "Dropping effort %r: %s/%s accepts %s. Sending no effort parameter.",
637
+ requested, provider_name, model, levels or "no effort control")
638
+ return None
639
+
640
+
641
+ def effort_levels_for_model(client, provider_name: str, model: str) -> list[str]:
642
+ """Reasoning-effort levels this model accepts, most-to-least capable last.
643
+
644
+ Anthropic is queried, not tabulated: its Models API reports per-model
645
+ effort support (`capabilities.effort.<level>.supported`), so a newly
646
+ released Anthropic model needs no manual entry here. Every other provider
647
+ is tabulated because there is nothing to ask -- no OpenAI-compatible
648
+ provider in providers.json exposes a capability endpoint, and Google
649
+ expresses depth as an integer budget rather than a level set at all.
650
+
651
+ Falling back logs at WARNING, matching §21's MODEL_CONTEXT_WINDOWS
652
+ posture: a static table is honest about being incomplete, but it should
653
+ say so out loud when it is the thing answering.
654
+
655
+ Returns [] when the model supports no effort control, which callers must
656
+ treat as "offer no picker and send no effort parameter".
657
+ """
658
+ return _effort_levels(client, provider_name, model)[0]
659
+
660
+
661
+ def _effort_levels(client, provider_name: str, model: str) -> tuple:
662
+ """(levels, authoritative).
663
+
664
+ `authoritative` is False when the answer came from the static table
665
+ after the capability QUERY failed, as opposed to because no query was
666
+ ever possible for that provider. Only effort_for() needs the
667
+ distinction -- an unverified answer must not be used to drop a level
668
+ the user deliberately chose.
669
+ """
670
+ key = (provider_name, model)
671
+ if key in _effort_levels_cache:
672
+ return _effort_levels_cache[key], True
673
+
674
+ levels: Optional[list[str]] = None
675
+ query_failed = False
676
+ if provider_name == "GOOGLE" and not _google_supports_thinking_budget():
677
+ # Reporting no levels is the honest answer, not a silent [] : on the
678
+ # pinned SDK there is no field to put a budget in, so a picker
679
+ # offering levels would be offering something unsendable.
680
+ _effort_levels_cache[key] = []
681
+ return [], True
682
+ if provider_name == "ANTHROPIC":
683
+ try:
684
+ # ATTRIBUTES, not subscripts (#35). This read used to be
685
+ # `capabilities["effort"]` with `effort.get(name)` and
686
+ # `isinstance(..., dict)`. On the exactly-pinned SDK those are
687
+ # pydantic models -- ModelCapabilities, EffortCapability,
688
+ # CapabilitySupport -- supporting neither [] nor .get(), so the
689
+ # TypeError was caught below, query_failed was set, and the
690
+ # query FELL BACK EVERY SINGLE TIME. Not "failed sometimes":
691
+ # it could not succeed. All three dict spellings were wrong,
692
+ # so correcting the subscript alone would have failed one line
693
+ # further down.
694
+ #
695
+ # No dict/attribute dual path on purpose. A defensive default
696
+ # is only safe where absence is impossible, requirements.txt
697
+ # pins anthropic exactly, and test_sdk_conformance.py exists
698
+ # to go red when the pinned shape moves -- which is a better
699
+ # signal than a fallback that silently keeps guessing.
700
+ info = client.models.retrieve(model)
701
+ # ONE retrieve, TWO readings (§21's revisit). The context
702
+ # window is on this SAME ModelInfo as `max_input_tokens`, so
703
+ # recording it here IS the entire Anthropic half of the
704
+ # window query: no second call, no second failure mode, and
705
+ # it lands on the path every send already crosses
706
+ # (core/loop.py calls effort_for before the wire). §21
707
+ # rejected a window query on the belief that there was
708
+ # nothing to ask; for this provider the answer was already
709
+ # in hand and being dropped. See context_window_for below.
710
+ _record_window(provider_name, model,
711
+ getattr(info, "max_input_tokens", None))
712
+ capabilities = info.capabilities
713
+ effort = capabilities.effort
714
+ levels = [
715
+ name for name in ("low", "medium", "high", "xhigh", "max")
716
+ # getattr, because `xhigh` is Optional on the pinned type
717
+ # and a model that does not offer a level reports None
718
+ # rather than supported=False.
719
+ if getattr(getattr(effort, name, None), "supported", False)
720
+ ]
721
+ except Exception as e:
722
+ # Network failure, an SDK too old to expose capabilities, or a
723
+ # model the endpoint doesn't know. Fall through to the table.
724
+ query_failed = True
725
+ logger.warning(
726
+ "Could not read effort capabilities for %r from the Anthropic "
727
+ "Models API (%s); falling back to the static table.", model, e,
728
+ )
729
+
730
+ if levels is None:
731
+ levels = config.MODEL_EFFORT_LEVELS.get(model)
732
+ if levels is None:
733
+ logger.warning(
734
+ "No effort levels known for %r on %s; assuming %s. Add an entry "
735
+ "to config.MODEL_EFFORT_LEVELS if this is wrong.",
736
+ model, provider_name, config.DEFAULT_EFFORT_LEVELS,
737
+ )
738
+ levels = list(config.DEFAULT_EFFORT_LEVELS)
739
+
740
+ if query_failed:
741
+ # Do NOT cache a failure-derived guess. Caching it made one
742
+ # transient error permanently suppress the query that is this
743
+ # function's entire reason to exist: for the whole process life
744
+ # the picker would offer a guessed level set, and every selection
745
+ # from it could 400 with no path back short of a restart.
746
+ return levels, False
747
+
748
+ _effort_levels_cache[key] = levels
749
+ return levels, True
750
+
751
+
752
+ # The field names a provider might report a context window under, in the
753
+ # order they are tried. ONE reader covers every OpenAI-compatible provider
754
+ # rather than one adapter each, because openai.types.Model is declared
755
+ # `extra="allow"` -- a field the SDK does not model survives on the parsed
756
+ # object and reaches `.model_extra`. Verified against the pinned openai
757
+ # 2.45.0 in test_sdk_conformance.py, because that permissiveness is the
758
+ # whole reason this is one function.
759
+ #
760
+ # context_window Groq
761
+ # context_length Together, OpenRouter, Cohere (native /v1 only)
762
+ # max_context_length Mistral
763
+ # max_input_tokens Anthropic's spelling, accepted here so a gateway
764
+ # proxying Anthropic through an OpenAI-shaped API
765
+ # is not silently unreadable
766
+ #
767
+ # OpenAI, DeepSeek and Perplexity report NONE of these -- they answer with
768
+ # id/created/object/owned_by and nothing else. That is not a failure, it is
769
+ # the answer, and it is why config.MODEL_CONTEXT_WINDOWS still exists.
770
+ _WINDOW_FIELD_ALIASES = (
771
+ "context_window",
772
+ "context_length",
773
+ "max_context_length",
774
+ "max_input_tokens",
775
+ )
776
+
777
+ #: Returned by _model_info when a COMPLETE listing did not contain the model.
778
+ #: Distinct from a raise: the provider answered, so there is nothing to retry.
779
+ _NOT_LISTED = object()
780
+
781
+
782
+ def _window_from_model_object(info) -> Optional[int]:
783
+ """The context window off one provider model object, or None.
784
+
785
+ Declared fields first, then model_extra -- the same object may carry
786
+ either depending on whether the installed SDK models the field.
787
+ ATTRIBUTES not subscripts, for #35's reason: these are pydantic objects
788
+ on every pinned SDK here.
789
+
790
+ `top_provider.context_length` is the one NESTED spelling, and it is
791
+ OpenRouter's: the flat `context_length` is the model's maximum across
792
+ every backend, while top_provider carries the routed one. Read second,
793
+ so the flat value still wins where both exist -- this is a fallback for
794
+ entries that carry only the nested form, not a preference for the
795
+ narrower number.
796
+ """
797
+ extra = getattr(info, "model_extra", None) or {}
798
+ for name in _WINDOW_FIELD_ALIASES:
799
+ value = getattr(info, name, None)
800
+ if value is None:
801
+ value = extra.get(name)
802
+ if value is not None:
803
+ return value
804
+ top = extra.get("top_provider")
805
+ if isinstance(top, dict):
806
+ return top.get("context_length")
807
+ return None
808
+
809
+
810
+ def _model_info(client, model):
811
+ """The provider's object for one model, via retrieve or via the listing.
812
+
813
+ THE ROUTE WAS THE BUG, NOT THE READER (batch 44). This asked
814
+ `client.models.retrieve(model)` alone, which is `GET {base}/models/{id}`
815
+ -- and OpenRouter implements `GET /api/v1/models` plus
816
+ `/models/:author/:slug/endpoints` and no plain per-id retrieve, so an id
817
+ containing a slash (`minimax/minimax-m3`) turns the path into a route
818
+ that does not exist. 404, every time, on a provider whose listing has
819
+ carried `context_length` all along and which _WINDOW_FIELD_ALIASES'
820
+ own comment names. NVIDIA's endpoint has the same shape, and so does
821
+ every other provider whose ids are `vendor/model`.
822
+
823
+ Retrieve stays FIRST: it is one call and it is the right one for Groq,
824
+ Together and Mistral, and a listing can be hundreds of entries. The
825
+ fallback costs one extra call per provider per process, on the path
826
+ that was previously three failures and a permanent give-up.
827
+
828
+ Three outcomes, deliberately distinct:
829
+ an object something answered
830
+ _NOT_LISTED a complete listing came back without this model, which
831
+ is an ANSWER ("this provider has nothing to say about
832
+ it") and must not be retried like a network blip
833
+ raises neither route could answer; the caller counts it
834
+ """
835
+ try:
836
+ return client.models.retrieve(model)
837
+ except Exception as retrieve_error:
838
+ listing = getattr(getattr(client, "models", None), "list", None)
839
+ if listing is None:
840
+ raise
841
+ try:
842
+ entries = list(listing())
843
+ except Exception:
844
+ # The listing is not a second opinion about the retrieve; it is
845
+ # the same question by another route. Report the FIRST failure,
846
+ # which is the one that names the endpoint the caller asked for.
847
+ raise retrieve_error from None
848
+ for entry in entries:
849
+ if getattr(entry, "id", None) == model:
850
+ return entry
851
+ if not entries:
852
+ # An empty listing answered nothing at all; report the failure
853
+ # that names the endpoint the caller actually asked for.
854
+ raise retrieve_error from None
855
+ return _NOT_LISTED
856
+
857
+
858
+ def _record_window(provider_name: str, model: str, value) -> Optional[int]:
859
+ """Cache a queried window, coercing anything unusable to None.
860
+
861
+ A POSITIVE int or nothing. The Anthropic Models API types
862
+ `max_input_tokens` as nullable and its own documented example carries
863
+ a placeholder 0, so "present" is not "usable" -- and a 0 reaching
864
+ compaction would make `context_limit - backstop` clamp to the floor
865
+ and compact continuously. Anything that is not a positive int is
866
+ recorded as None, which means "asked, got no usable answer" and sends
867
+ the caller to the static table.
868
+ """
869
+ window = value if isinstance(value, int) and not isinstance(value, bool) else None
870
+ if window is not None and window <= 0:
871
+ window = None
872
+ _context_window_cache[(provider_name, model)] = window
873
+ return window
874
+
875
+
876
+ def known_context_window(provider_name: str, model: str) -> Optional[int]:
877
+ """The queried window for (provider, model), or None if none is known.
878
+
879
+ CACHE ONLY -- this never makes a call, which is what lets
880
+ core/compaction.py ask the question without holding a client or
881
+ importing an SDK. The cache is primed by context_window_for() on the
882
+ path core/loop.py already crosses before every send, so by the time a
883
+ compaction check runs the answer is there if the provider had one.
884
+ """
885
+ return _context_window_cache.get((provider_name, model))
886
+
887
+
888
+ def context_window_for(client, provider_name: str, model: str) -> tuple:
889
+ """(window_or_None, authoritative). Queries the provider once per process.
890
+
891
+ §21 rejected this as needing "fifteen adapters" for a roster where no
892
+ uniform endpoint existed. Re-measured against the PINNED SDKs, that
893
+ premise did not hold, and the shape below is what it actually costs:
894
+
895
+ ANTHROPIC already answered. _effort_levels retrieves the ModelInfo
896
+ to read capabilities.effort and max_input_tokens rides
897
+ along on it, so this branch is usually a cache hit and
898
+ makes no call at all.
899
+ GOOGLE models.get(...).input_token_limit, one field on the
900
+ pinned google-genai type.
901
+ v1-compat ONE alias sniff over model_extra, not thirteen adapters,
902
+ because openai.types.Model allows extra fields -- over
903
+ whichever of models.retrieve() and models.list() answers
904
+ (see _model_info: providers whose ids carry a slash have
905
+ no per-id route, so retrieve 404s on them).
906
+
907
+ §21's CONCLUSION survives intact and is why the table remains: OpenAI,
908
+ DeepSeek and Perplexity report nothing, so a fallback constant is
909
+ still needed at the end of it.
910
+
911
+ THE FAILURE/SILENCE SPLIT IS THE POINT, and it is _effort_levels'
912
+ query_failed rule (#35's lesson) applied to a second query. A call
913
+ that RAISED is warned and NOT cached: a transient network error must
914
+ not permanently suppress the query for the life of the process. A
915
+ call that SUCCEEDED and reported no window IS cached as None, because
916
+ that is a real and stable answer, and re-asking it on every
917
+ compaction evaluation would spend a request per step to learn the
918
+ same thing.
919
+ """
920
+ key = (provider_name, model)
921
+ if key in _context_window_cache:
922
+ return _context_window_cache[key], True
923
+
924
+ try:
925
+ if provider_name == "GOOGLE":
926
+ info = client.models.get(model=model)
927
+ return _record_window(
928
+ provider_name, model,
929
+ getattr(info, "input_token_limit", None)), True
930
+ info = _model_info(client, model)
931
+ if info is _NOT_LISTED:
932
+ # Asked and answered by a listing that did not name it.
933
+ return _record_window(provider_name, model, None), True
934
+ window = _window_from_model_object(info)
935
+ if window is not None:
936
+ return _record_window(provider_name, model, window), True
937
+ # Asked and answered: this provider reports no window.
938
+ return _record_window(provider_name, model, None), True
939
+ except Exception as e:
940
+ # Network failure, a provider with no models endpoint at all, or a
941
+ # model the endpoint does not know. Not cached as an ANSWER -- see
942
+ # the docstring -- but counted, so a permanent failure stops being
943
+ # re-asked once it has proved it is not a blip.
944
+ attempts = _context_window_failures.get(key, 0) + 1
945
+ _context_window_failures[key] = attempts
946
+ giving_up = attempts >= MAX_CONTEXT_WINDOW_QUERY_ATTEMPTS
947
+ logger.warning(
948
+ "Could not read a context window for %r from %s (%s); "
949
+ "config.MODEL_CONTEXT_WINDOWS will answer instead.%s",
950
+ model, provider_name, e,
951
+ " Not asking again this session." if giving_up else "")
952
+ if giving_up:
953
+ _record_window(provider_name, model, None)
954
+ return None, False
955
+
956
+
957
+ _google_budget_support: Optional[bool] = None
958
+
959
+
960
+ def _google_supports_thinking_budget() -> bool:
961
+ """Whether the INSTALLED google-genai can express a thinking budget.
962
+
963
+ Checked rather than assumed, and the check earns its keep: the pinned
964
+ google-genai (1.0.0) ships a ThinkingConfig whose only field is
965
+ `include_thoughts` -- `thinking_budget` arrived in a later release. So
966
+ the obvious implementation, ThinkingConfig(thinking_budget=N), raises a
967
+ TypeError against the version this repo actually pins.
968
+
969
+ Rather than bump the pin (which would put §9's verified Google
970
+ implementation back in play for a feature Google users can do without),
971
+ reasoning effort is simply unavailable on Google until the pin moves.
972
+ D22's rule, applied: check the dependency's real shape, don't assume it.
973
+ """
974
+ from google.genai import types as genai_types
975
+
976
+ global _google_budget_support
977
+ if _google_budget_support is None:
978
+ fields = getattr(genai_types.ThinkingConfig, "model_fields", {})
979
+ _google_budget_support = "thinking_budget" in fields
980
+ if not _google_budget_support:
981
+ logger.info(
982
+ "Installed google-genai has no ThinkingConfig.thinking_budget; "
983
+ "reasoning effort is unavailable on GOOGLE until the pin moves."
984
+ )
985
+ return _google_budget_support
986
+
987
+
988
+ def _thinking_record(provider_name: str, model: str,
989
+ blocks: list) -> Optional[dict]:
990
+ """The turn's reasoning in the shape ModelResponse.thinking carries.
991
+
992
+ None when the turn produced none, so "no reasoning" and "a provider
993
+ that reports none" stay one thing and no row is written for either.
994
+ """
995
+ if not blocks:
996
+ return None
997
+ return {"provider": provider_name, "model": model, "blocks": blocks}
998
+
999
+
1000
+ def _thinking_for_provider(provider_name: str, effort: Optional[str]) -> dict:
1001
+ """Reasoning-effort kwargs for this provider, or {} when no effort is set.
1002
+
1003
+ Effort is opt-in: `effort=None` sends nothing at all and every provider
1004
+ behaves exactly as it did before §16. That matters because the parameter
1005
+ is not universally safe -- `reasoning_effort` is rejected by
1006
+ OpenAI-compatible NON-reasoning models, and `thinking: {"type": "adaptive"}`
1007
+ is rejected by pre-4.6 Anthropic models. Callers are expected to offer
1008
+ only the levels effort_levels_for_model() reported, and to offer nothing
1009
+ when it reported none.
1010
+
1011
+ Returned keys are merged into the provider's own kwargs by the caller;
1012
+ the Google entry is nested inside GenerateContentConfig rather than sent
1013
+ top-level, matching how that provider takes every other setting.
1014
+ """
1015
+ if not effort:
1016
+ return {}
1017
+ if provider_name == "ANTHROPIC":
1018
+ # Adaptive thinking + an effort level is the current-model pairing;
1019
+ # `display` is EXPLICIT because its default changed under us. On
1020
+ # Fable 5, Opus 5, Opus 4.8/4.7 and Sonnet 5 it defaults to
1021
+ # "omitted", which still streams thinking blocks but with EMPTY
1022
+ # text -- so §38's whole feature rendered nothing at all on
1023
+ # Anthropic: ev.thinking was "", core/loop.py's `if
1024
+ # token.thinking_delta` never fired, and neither the inline block
1025
+ # nor ThinkingIndicator ever appeared. It looked like it worked
1026
+ # because the OpenAI-compatible branch reads reasoning_content and
1027
+ # is unaffected. The raw chain of thought is never exposed on any
1028
+ # model; "summarized" is the readable form, and it is what the
1029
+ # blocks captured below carry back to the model that wrote them.
1030
+ # budget_tokens was removed and returns a 400.
1031
+ return {
1032
+ "thinking": {"type": "adaptive", "display": "summarized"},
1033
+ "output_config": {"effort": effort},
1034
+ }
1035
+ if provider_name == "GOOGLE":
1036
+ from google.genai import types as genai_types
1037
+ budget = config.GOOGLE_THINKING_BUDGETS.get(effort)
1038
+ if budget is None or not _google_supports_thinking_budget():
1039
+ return {}
1040
+ return {"thinking_config": genai_types.ThinkingConfig(thinking_budget=budget)}
1041
+ return {"reasoning_effort": effort}
1042
+
1043
+
1044
+ # ============================================================================
1045
+ # ---- Streaming call + helpers -----------------------------------------------
1046
+ # ============================================================================
1047
+
1048
+ def call_model_stream(
1049
+ client,
1050
+ provider_name: str,
1051
+ model: str,
1052
+ messages: list[dict],
1053
+ system_prompt: str,
1054
+ tool_schemas: list[dict],
1055
+ temperature: Optional[float] = None,
1056
+ effort: Optional[str] = None,
1057
+ ):
1058
+ """The one model call, for every provider. Yields StreamToken
1059
+ events: text_delta for incremental text, thinking_delta for
1060
+ incremental reasoning text where the provider sends any (§38 O2),
1061
+ final_response for the terminal ModelResponse with accumulated tool
1062
+ calls and usage.
1063
+
1064
+ Three provider implementations — Anthropic typed events, Google
1065
+ chunked candidates, OpenAI-compatible index-accumulated tool-call
1066
+ fragments — which must agree with each other about the ModelResponse
1067
+ they produce for the same inputs.
1068
+
1069
+ There used to be a non-streaming `call_model()` beside this, and this
1070
+ docstring used to promise the two were identical. They were not: it
1071
+ set ModelResponse.raw and no streaming branch did, which is what a
1072
+ second implementation nobody runs accumulates (#38). It is gone, and
1073
+ with it `raw`; the only thing left to keep in step is the three
1074
+ branches below.
1075
+
1076
+ D21 (usage-or-raise): if the provider is marked as supporting stream
1077
+ usage but the stream completes with zero usage, raise rather than
1078
+ silently reporting zero (which disables budget enforcement and §21's
1079
+ compaction trigger).
1080
+ """
1081
+ # Read once so every branch applies the same D21 usage-or-raise rule --
1082
+ # all three of them, since audit #40. This comment used to claim that in
1083
+ # its first sentence and take it back in the second ("the flag only gates
1084
+ # the Google and OpenAI-compatible branches"), which left the one
1085
+ # provider whose example config ships the flag `true` as the one provider
1086
+ # where setting it did nothing.
1087
+ provider_data = load_provider_data()
1088
+ supports_stream_usage = provider_data.get(provider_name, {}).get(
1089
+ "supports_stream_usage", False
1090
+ )
1091
+ # §44. Whether this OpenAI-compatible provider accepts its own
1092
+ # reasoning back on the next request. supports_stream_usage's
1093
+ # precedent: a per-provider fact that cannot be discovered and must not
1094
+ # be guessed, so it lives beside the endpoint it describes and defaults
1095
+ # to the conservative answer.
1096
+ echoes_reasoning = provider_data.get(provider_name, {}).get(
1097
+ "echoes_reasoning", False
1098
+ )
1099
+
1100
+ translated_messages = _messages_for_provider(
1101
+ provider_name, messages, model, echoes_reasoning)
1102
+ sampling = _sampling_kwargs(provider_name, model, temperature)
1103
+ thinking = _thinking_for_provider(provider_name, effort)
1104
+
1105
+ if provider_name == "ANTHROPIC":
1106
+ stream_kwargs = dict(
1107
+ model=model,
1108
+ max_tokens=config.MAX_TOKENS,
1109
+ system=system_prompt,
1110
+ messages=translated_messages,
1111
+ tools=_tools_for_provider(provider_name, tool_schemas),
1112
+ )
1113
+ stream_kwargs.update(sampling)
1114
+ stream_kwargs.update(thinking)
1115
+
1116
+ with client.messages.stream(**stream_kwargs) as stream:
1117
+ # §38 O3. Iterating the STREAM rather than stream.text_stream,
1118
+ # because text_stream yields text deltas only and there is no
1119
+ # way to have both: `text_stream` is an instance attribute
1120
+ # built from the same underlying iterator in MessageStream's
1121
+ # __init__, so consuming one consumes the other.
1122
+ #
1123
+ # The SDK emits its own synthetic events beside the raw ones --
1124
+ # TextEvent(type="text", text=<delta>) and
1125
+ # ThinkingEvent(type="thinking", thinking=<delta>) -- which is
1126
+ # why this reads two attribute names rather than unpacking
1127
+ # content_block_delta by hand. Verified against the pinned
1128
+ # anthropic==0.116.0 rather than assumed (D22), and pinned in
1129
+ # tests/test_sdk_conformance.py.
1130
+ #
1131
+ # Every other event kind is ignored on purpose: `text` is the
1132
+ # accumulated answer read off get_final_message() below, not
1133
+ # off these deltas, so nothing here can change what this
1134
+ # branch returns.
1135
+ for ev in stream:
1136
+ kind = getattr(ev, "type", None)
1137
+ if kind == "text":
1138
+ yield StreamToken(text_delta=ev.text)
1139
+ elif kind == "thinking":
1140
+ yield StreamToken(thinking_delta=ev.thinking)
1141
+ final_msg = stream.get_final_message()
1142
+ text = "\n".join(
1143
+ b.text for b in final_msg.content if b.type == "text"
1144
+ )
1145
+ calls = [
1146
+ ToolCallRequest(id=b.id, name=b.name, input=b.input)
1147
+ for b in final_msg.content if b.type == "tool_use"
1148
+ ]
1149
+ # model_dump() rather than a hand-built dict: what goes back on
1150
+ # the wire has to be what came off it, field for field, or the
1151
+ # signature does not verify. redacted_thinking is included for
1152
+ # the same reason -- it is opaque to us and meaningful to the
1153
+ # model, so dropping it would silently break a turn that had
1154
+ # one.
1155
+ thinking_blocks = [
1156
+ b.model_dump() for b in final_msg.content
1157
+ if b.type in ("thinking", "redacted_thinking")
1158
+ ]
1159
+ usage_obj = getattr(final_msg, "usage", None)
1160
+ usage = {
1161
+ "input_tokens": getattr(usage_obj, "input_tokens", 0) if usage_obj else 0,
1162
+ "output_tokens": getattr(usage_obj, "output_tokens", 0) if usage_obj else 0,
1163
+ }
1164
+
1165
+ # D21 parity with the other two branches (audit #40). This branch
1166
+ # used to be exempt on the reasoning that get_final_message() always
1167
+ # carries usage -- which is very likely right for anthropic==0.116.0,
1168
+ # and is exactly the kind of assumption D21 exists because nobody can
1169
+ # verify from inside. The getattr defaults above are the softened
1170
+ # form D21's own note forbids, so on the DEFAULT provider an SDK
1171
+ # field rename would have zeroed the budget silently, disabling both
1172
+ # the budget stop condition and §21's compaction trigger. That is the
1173
+ # mcp v1->v2 failure mode, and #35 is this file's live example of it.
1174
+ #
1175
+ # Honouring the flag rather than always raising keeps it meaning ONE
1176
+ # thing on all three providers, which is the coherence #40 is about;
1177
+ # providers.json.example ships it true for ANTHROPIC, so the default
1178
+ # posture is the checked one, and a proxy that genuinely omits usage
1179
+ # can still opt out instead of being unable to run.
1180
+ if supports_stream_usage and usage["input_tokens"] == 0 and usage["output_tokens"] == 0:
1181
+ raise RuntimeError(
1182
+ f"Streaming call to {provider_name} completed without usage "
1183
+ f"data despite supports_stream_usage=True. The stream may "
1184
+ f"have been interrupted before the final usage chunk."
1185
+ )
1186
+
1187
+ yield StreamToken(final_response=ModelResponse(
1188
+ text=text, tool_calls=calls, usage=usage,
1189
+ thinking=_thinking_record(provider_name, model, thinking_blocks),
1190
+ ))
1191
+ return
1192
+
1193
+ if provider_name == "GOOGLE":
1194
+ from google.genai import types as genai_types
1195
+ genai_config_kwargs = dict(
1196
+ system_instruction=system_prompt,
1197
+ tools=_tools_for_provider(provider_name, tool_schemas),
1198
+ max_output_tokens=config.MAX_TOKENS,
1199
+ )
1200
+ genai_config_kwargs.update(sampling)
1201
+ genai_config_kwargs.update(thinking)
1202
+
1203
+ text_parts = []
1204
+ calls = []
1205
+ usage = {"input_tokens": 0, "output_tokens": 0}
1206
+
1207
+ for chunk in client.models.generate_content_stream(
1208
+ model=model,
1209
+ contents=translated_messages,
1210
+ config=genai_types.GenerateContentConfig(**genai_config_kwargs),
1211
+ ):
1212
+ candidate = chunk.candidates[0] if chunk.candidates else None
1213
+ content = candidate.content if candidate else None
1214
+ parts = content.parts if content else []
1215
+ for p in parts:
1216
+ if p.text is not None:
1217
+ text_parts.append(p.text)
1218
+ yield StreamToken(text_delta=p.text)
1219
+ if p.function_call is not None:
1220
+ fc = p.function_call
1221
+ calls.append(ToolCallRequest(
1222
+ id=fc.id or str(uuid4()),
1223
+ name=fc.name,
1224
+ input=fc.args or {},
1225
+ ))
1226
+ usage_meta = getattr(chunk, "usage_metadata", None)
1227
+ if usage_meta:
1228
+ usage["input_tokens"] = getattr(usage_meta, "prompt_token_count", 0)
1229
+ usage["output_tokens"] = getattr(usage_meta, "candidates_token_count", 0)
1230
+
1231
+ # D21 parity with the OpenAI branch: raise if marked as supporting
1232
+ # stream usage but the stream completed with zero usage.
1233
+ if supports_stream_usage and usage["input_tokens"] == 0 and usage["output_tokens"] == 0:
1234
+ raise RuntimeError(
1235
+ f"Streaming call to {provider_name} completed without usage "
1236
+ f"data despite supports_stream_usage=True. The stream may "
1237
+ f"have been interrupted before the final usage chunk."
1238
+ )
1239
+
1240
+ yield StreamToken(final_response=ModelResponse(
1241
+ text="".join(text_parts), tool_calls=calls, usage=usage,
1242
+ ))
1243
+ return
1244
+
1245
+ # OpenAI-compatible path (supports_stream_usage already read above)
1246
+ full_messages = [{"role": "system", "content": system_prompt}] + translated_messages
1247
+ openai_kwargs = dict(
1248
+ model=model,
1249
+ messages=full_messages,
1250
+ max_completion_tokens=config.MAX_TOKENS,
1251
+ tools=_tools_for_provider(provider_name, tool_schemas),
1252
+ stream=True,
1253
+ )
1254
+ openai_kwargs.update(sampling)
1255
+ openai_kwargs.update(thinking)
1256
+ if supports_stream_usage:
1257
+ openai_kwargs["stream_options"] = {"include_usage": True}
1258
+
1259
+ text_parts = []
1260
+ reasoning_parts = []
1261
+ tool_fragments: dict[int, dict] = {}
1262
+ usage = {"input_tokens": 0, "output_tokens": 0}
1263
+
1264
+ finish_reason = None
1265
+ for chunk in client.chat.completions.create(**openai_kwargs):
1266
+ if chunk.choices:
1267
+ # W4 (#37): free -- chunk.choices[0] is already read here. The
1268
+ # provider sets this on the last content chunk, and `or
1269
+ # finish_reason` keeps it once seen because the usage chunk
1270
+ # that follows carries none. getattr because a chunk is only
1271
+ # required to have `delta`.
1272
+ choice = chunk.choices[0]
1273
+ finish_reason = getattr(choice, "finish_reason", None) or finish_reason
1274
+ delta = choice.delta
1275
+ if delta.content:
1276
+ text_parts.append(delta.content)
1277
+ yield StreamToken(text_delta=delta.content)
1278
+ # §38 O3. Reasoning text, where the provider sends any. There
1279
+ # is no standard field: DeepSeek, Qwen and Z.AI use
1280
+ # `reasoning_content`, OpenRouter and Groq use `reasoning`,
1281
+ # and OpenAI's own endpoint sends neither. openai's ChoiceDelta
1282
+ # is extra="allow" (pinned in test_sdk_conformance.py), so an
1283
+ # unknown-to-the-SDK field arrives as a real attribute.
1284
+ #
1285
+ # NEVER appended to text_parts: reasoning is not the answer,
1286
+ # and folding it in would change every ModelResponse this
1287
+ # branch returns and put reasoning into the thread as though
1288
+ # the model had said it. It is accumulated SEPARATELY instead
1289
+ # (batch 44), into ModelResponse.thinking, where it is kept as
1290
+ # this provider's own field name rather than as prose -- an
1291
+ # echo back on the wire has to spell it the way the provider
1292
+ # spelled it.
1293
+ reasoning = (getattr(delta, "reasoning_content", None)
1294
+ or getattr(delta, "reasoning", None))
1295
+ if isinstance(reasoning, str) and reasoning:
1296
+ reasoning_parts.append(reasoning)
1297
+ yield StreamToken(thinking_delta=reasoning)
1298
+ if delta.tool_calls:
1299
+ for tc_delta in delta.tool_calls:
1300
+ idx = tc_delta.index
1301
+ if idx not in tool_fragments:
1302
+ tool_fragments[idx] = {
1303
+ "id": "", "name_parts": [], "arguments_parts": [],
1304
+ }
1305
+ if tc_delta.id:
1306
+ tool_fragments[idx]["id"] = tc_delta.id
1307
+ # Accumulate name like arguments: some v1-compatible
1308
+ # providers split function.name across deltas, so a
1309
+ # last-write-wins assignment would corrupt the name.
1310
+ if tc_delta.function and tc_delta.function.name:
1311
+ tool_fragments[idx]["name_parts"].append(
1312
+ tc_delta.function.name
1313
+ )
1314
+ if tc_delta.function and tc_delta.function.arguments:
1315
+ tool_fragments[idx]["arguments_parts"].append(
1316
+ tc_delta.function.arguments
1317
+ )
1318
+ usage_obj = getattr(chunk, "usage", None)
1319
+ if usage_obj:
1320
+ usage["input_tokens"] = getattr(usage_obj, "prompt_tokens", 0)
1321
+ usage["output_tokens"] = getattr(usage_obj, "completion_tokens", 0)
1322
+
1323
+ # D21: if the provider is marked as supporting stream usage but we
1324
+ # got zero usage, the stream was likely interrupted before the final
1325
+ # usage chunk arrived. Raise rather than silently reporting zero.
1326
+ if supports_stream_usage and usage["input_tokens"] == 0 and usage["output_tokens"] == 0:
1327
+ raise RuntimeError(
1328
+ f"Streaming call to {provider_name} completed without usage "
1329
+ f"data despite supports_stream_usage=True. The stream may "
1330
+ f"have been interrupted before the final usage chunk."
1331
+ )
1332
+
1333
+ calls = []
1334
+ for idx in sorted(tool_fragments):
1335
+ frag = tool_fragments[idx]
1336
+ name = "".join(frag["name_parts"])
1337
+ parsed, parse_error = _tool_arguments(
1338
+ "".join(frag["arguments_parts"]), name, finish_reason)
1339
+ if parse_error is not None:
1340
+ logger.warning(
1341
+ "%s: %s (finish_reason=%r)", name, parse_error, finish_reason)
1342
+ calls.append(ToolCallRequest(
1343
+ id=frag["id"], name=name, input=parsed, parse_error=parse_error,
1344
+ ))
1345
+
1346
+ # ONE block, not one per delta. There is no block structure on this
1347
+ # wire -- reasoning arrives as a flat string of deltas -- so the record
1348
+ # is the concatenation under the field name the request would use to
1349
+ # send it back. `type` names the shape for _messages_for_provider;
1350
+ # nothing about it is the provider's, which is why it is spelled after
1351
+ # the field rather than after Anthropic's "thinking".
1352
+ reasoning_blocks = ([{"type": "reasoning_content",
1353
+ "text": "".join(reasoning_parts)}]
1354
+ if reasoning_parts else [])
1355
+
1356
+ yield StreamToken(final_response=ModelResponse(
1357
+ text="".join(text_parts), tool_calls=calls, usage=usage,
1358
+ thinking=_thinking_record(provider_name, model, reasoning_blocks),
1359
+ ))
1360
+
1361
+
1362
+ # ===========================================================================
1363
+ # ---- Embeddings (ROADMAP_v2 §45, SQ2/SQ7) ---------------------------------
1364
+ # ===========================================================================
1365
+ #
1366
+ # §33's rule is that this file is where a model call lives, and an
1367
+ # embedding is a model call. It shares `api_initialization` and its client
1368
+ # cache with the chat path, so an embedder on a provider already in use
1369
+ # costs no second client.
1370
+ #
1371
+ # WHAT THIS DELIBERATELY DOES NOT SHARE. No streaming, no tool
1372
+ # translation, no `effort`, no context-window check, and no entry in
1373
+ # `ModelResponse`: none of those mean anything for a call that takes
1374
+ # strings and returns vectors. `EmbeddingResult` is its own small shape
1375
+ # for the same reason ToolCallRequest is -- widening ModelResponse with
1376
+ # three fields that are null on every chat turn is how a response object
1377
+ # stops describing anything.
1378
+
1379
+
1380
+ class EmbeddingError(RuntimeError):
1381
+ """An embedding call that could not produce usable vectors.
1382
+
1383
+ ITS OWN TYPE, so §45's scoring stage can catch exactly this and fall
1384
+ back to the model's own similarity (SQ10) without also swallowing a
1385
+ programming error from inside its own chunker. The message names the
1386
+ provider and the model, because the two most common causes -- a
1387
+ provider with no embeddings endpoint, and a chat model slug passed to
1388
+ one -- are both fixed by changing one of those two words.
1389
+ """
1390
+
1391
+
1392
+ @dataclass
1393
+ class EmbeddingResult:
1394
+ """Vectors for the texts that were sent, in the order they were sent.
1395
+
1396
+ `usage` mirrors ModelResponse's shape but carries input tokens only:
1397
+ an embedding call produces no output tokens, and reporting a zero
1398
+ under a key that means something elsewhere would put embedding spend
1399
+ into a total that is documented as billed input+output of model calls.
1400
+ §45 counts it separately and says so.
1401
+ """
1402
+
1403
+ vectors: list = field(default_factory=list)
1404
+ model: str = ""
1405
+ provider_name: str = ""
1406
+ usage: dict = field(default_factory=lambda: {"input_tokens": 0})
1407
+
1408
+ @property
1409
+ def dimension(self) -> int:
1410
+ return len(self.vectors[0]) if self.vectors else 0
1411
+
1412
+
1413
+ # Providers with no embeddings endpoint at all, where the failure is worth
1414
+ # naming rather than surfacing as a 404 from inside a research run.
1415
+ #
1416
+ # ANTHROPIC IS NOT AN OVERSIGHT. There is no Anthropic embeddings API; the
1417
+ # recommended route is a third-party embedder, which this harness reaches
1418
+ # as its own provider entry. OPENROUTER proxies chat completions only.
1419
+ #
1420
+ # INCOMPLETE ON PURPOSE, and safe when incomplete -- the same posture as
1421
+ # MODELS_REJECTING_SAMPLING_PARAMS. An unlisted provider that turns out to
1422
+ # have no endpoint fails loudly on the probe `/embedder` runs at selection
1423
+ # time, which is a measurement rather than a guess and is why there is no
1424
+ # `supports_embeddings` table to keep in step with the world.
1425
+ PROVIDERS_WITHOUT_EMBEDDINGS = frozenset({"ANTHROPIC", "OPENROUTER"})
1426
+
1427
+
1428
+ def embed_texts(provider_name: str, model: str, texts,
1429
+ *, prefix: str = "", task_type: str = "") -> EmbeddingResult:
1430
+ """Embed `texts` with `model` on `provider_name`.
1431
+
1432
+ `prefix` is prepended to every text in this call. Asymmetric embedders
1433
+ -- e5's `"query: "` / `"passage: "`, BGE's instruction prefix -- score
1434
+ materially worse without it and produce no error at all, so it is
1435
+ configuration rather than something inferred from a model slug.
1436
+ `task_type` is Google's equivalent (`RETRIEVAL_QUERY` /
1437
+ `RETRIEVAL_DOCUMENT`) and is ignored elsewhere.
1438
+
1439
+ Raises EmbeddingError, never a provider exception: the caller's whole
1440
+ contract (SQ10) is to degrade to a documented fallback, and it cannot
1441
+ do that against an exception type that differs per SDK.
1442
+ """
1443
+ items = [f"{prefix}{text}" for text in texts]
1444
+ if not items:
1445
+ return EmbeddingResult(model=model, provider_name=provider_name)
1446
+
1447
+ if provider_name in PROVIDERS_WITHOUT_EMBEDDINGS:
1448
+ raise EmbeddingError(
1449
+ f"{provider_name} has no embeddings endpoint. Configure an "
1450
+ f"embedder on a provider that does -- /embedder <PROVIDER> "
1451
+ f"<model> -- or leave it unset to score similarity with the "
1452
+ f"grounding model itself."
1453
+ )
1454
+
1455
+ try:
1456
+ client = api_initialization(provider_name)
1457
+ except ValueError as exc:
1458
+ raise EmbeddingError(str(exc)) from exc
1459
+
1460
+ try:
1461
+ if provider_name == "GOOGLE":
1462
+ vectors, tokens = _embed_google(client, model, items, task_type)
1463
+ else:
1464
+ vectors, tokens = _embed_openai_compatible(client, model, items)
1465
+ except EmbeddingError:
1466
+ raise
1467
+ except Exception as exc:
1468
+ raise EmbeddingError(
1469
+ f"{provider_name} embeddings call failed for model {model!r}: "
1470
+ f"{type(exc).__name__}: {exc}"
1471
+ ) from exc
1472
+
1473
+ _check_vectors(provider_name, model, vectors, len(items))
1474
+ return EmbeddingResult(
1475
+ vectors=vectors, model=model, provider_name=provider_name,
1476
+ usage={"input_tokens": tokens},
1477
+ )
1478
+
1479
+
1480
+ def _embed_openai_compatible(client, model, items):
1481
+ """`/v1/embeddings`, which is what every is_v1_compatible provider
1482
+ exposes if it exposes embeddings at all.
1483
+
1484
+ SORTED BY INDEX rather than trusted in arrival order. The response
1485
+ carries an explicit `index` per item precisely because the order is
1486
+ not guaranteed, and a silently permuted batch pairs every claim with
1487
+ another claim's vector -- a wrong number with no symptom, which is the
1488
+ failure this whole section exists to stop producing.
1489
+ """
1490
+ response = client.embeddings.create(model=model, input=items)
1491
+ data = sorted(response.data, key=lambda item: getattr(item, "index", 0))
1492
+ vectors = [list(item.embedding) for item in data]
1493
+ usage = getattr(response, "usage", None)
1494
+ return vectors, int(getattr(usage, "prompt_tokens", 0) or 0)
1495
+
1496
+
1497
+ def _embed_google(client, model, items, task_type):
1498
+ """google-genai's `embed_content`, which takes the batch as
1499
+ `contents` and returns `embeddings[].values`.
1500
+
1501
+ The config object is built ONLY when a task type was given, and
1502
+ through getattr rather than a direct import of the types module: a
1503
+ pinned SDK that does not carry EmbedContentConfig would otherwise turn
1504
+ an optional tuning parameter into an import error on every Google
1505
+ embedding call. D22's rule -- check the dependency's real shape, do
1506
+ not assume it.
1507
+ """
1508
+ kwargs = {"model": model, "contents": items}
1509
+ if task_type:
1510
+ from google.genai import types as genai_types
1511
+ config_cls = getattr(genai_types, "EmbedContentConfig", None)
1512
+ if config_cls is not None:
1513
+ kwargs["config"] = config_cls(task_type=task_type)
1514
+ else:
1515
+ logger.warning(
1516
+ "Ignoring embedder task_type=%r: the installed google-genai "
1517
+ "has no EmbedContentConfig.", task_type)
1518
+
1519
+ response = client.models.embed_content(**kwargs)
1520
+ vectors = [list(item.values) for item in (response.embeddings or [])]
1521
+ # google-genai reports embedding token usage inconsistently across
1522
+ # releases; absent is reported as zero rather than guessed at.
1523
+ metadata = getattr(response, "metadata", None)
1524
+ return vectors, int(getattr(metadata, "billable_character_count", 0) or 0)
1525
+
1526
+
1527
+ def _check_vectors(provider_name, model, vectors, expected) -> None:
1528
+ """Three ways a successful response is still unusable.
1529
+
1530
+ All three produce a WRONG NUMBER rather than an error downstream: a
1531
+ short batch pairs texts with the wrong vectors, a ragged batch makes
1532
+ cosine compare different spaces, and an empty vector makes every
1533
+ cosine zero -- which reads as "no source supports this claim" and is
1534
+ indistinguishable from a real finding.
1535
+ """
1536
+ if len(vectors) != expected:
1537
+ raise EmbeddingError(
1538
+ f"{provider_name} returned {len(vectors)} embedding(s) for "
1539
+ f"{expected} input(s) with model {model!r}.")
1540
+ dimensions = {len(v) for v in vectors}
1541
+ if len(dimensions) > 1:
1542
+ raise EmbeddingError(
1543
+ f"{provider_name} returned embeddings of differing dimensions "
1544
+ f"{sorted(dimensions)} for model {model!r}.")
1545
+ if dimensions == {0}:
1546
+ raise EmbeddingError(
1547
+ f"{provider_name} returned empty embeddings for model "
1548
+ f"{model!r}.")