agentinputlab 0.1.0a1__py3-none-any.whl

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 (469) hide show
  1. agentinputlab/__init__.py +28 -0
  2. agentinputlab/algorithms/__init__.py +6 -0
  3. agentinputlab/algorithms/acquire/__init__.py +145 -0
  4. agentinputlab/algorithms/acquire/adaptive_rag/__init__.py +43 -0
  5. agentinputlab/algorithms/acquire/adaptive_rag/replay.py +367 -0
  6. agentinputlab/algorithms/acquire/adaptive_rag/runtime.py +1202 -0
  7. agentinputlab/algorithms/acquire/adaptive_rag_common_support.py +542 -0
  8. agentinputlab/algorithms/acquire/hyde.py +296 -0
  9. agentinputlab/algorithms/acquire/hyde_controlled.py +200 -0
  10. agentinputlab/algorithms/acquire/hyde_external.py +148 -0
  11. agentinputlab/algorithms/acquire/ircot.py +28 -0
  12. agentinputlab/algorithms/acquire/ircot_common_support.py +478 -0
  13. agentinputlab/algorithms/acquire/ircot_native.py +355 -0
  14. agentinputlab/algorithms/acquire/ircot_replay.py +327 -0
  15. agentinputlab/algorithms/acquire/qrag/__init__.py +79 -0
  16. agentinputlab/algorithms/acquire/qrag/bridge.py +828 -0
  17. agentinputlab/algorithms/acquire/qrag/common_support.py +891 -0
  18. agentinputlab/algorithms/acquire/qrag/native_axis.py +71 -0
  19. agentinputlab/algorithms/acquire/qrag/reader_adapter.py +139 -0
  20. agentinputlab/algorithms/acquire/r2ag/__init__.py +57 -0
  21. agentinputlab/algorithms/acquire/r2ag/bridge.py +1312 -0
  22. agentinputlab/algorithms/acquire/r2ag/common_support.py +1029 -0
  23. agentinputlab/algorithms/acquire/r2ag/socket_runtime.py +255 -0
  24. agentinputlab/algorithms/clarify/__init__.py +61 -0
  25. agentinputlab/algorithms/clarify/_structured.py +64 -0
  26. agentinputlab/algorithms/clarify/active_task_disambiguation.py +371 -0
  27. agentinputlab/algorithms/clarify/ask_or_assume/__init__.py +17 -0
  28. agentinputlab/algorithms/clarify/ask_or_assume/monitor.py +410 -0
  29. agentinputlab/algorithms/clarify/future_turns.py +379 -0
  30. agentinputlab/algorithms/clarify/udcs.py +255 -0
  31. agentinputlab/algorithms/clarify/udcs_deterministic.py +196 -0
  32. agentinputlab/algorithms/curate/__init__.py +65 -0
  33. agentinputlab/algorithms/curate/acon/__init__.py +27 -0
  34. agentinputlab/algorithms/curate/acon/common.py +284 -0
  35. agentinputlab/algorithms/curate/acon/common_support.py +136 -0
  36. agentinputlab/algorithms/curate/acon/history_bridge.py +309 -0
  37. agentinputlab/algorithms/curate/acon/observation_bridge.py +290 -0
  38. agentinputlab/algorithms/curate/llmlingua/__init__.py +30 -0
  39. agentinputlab/algorithms/curate/llmlingua/adapters.py +537 -0
  40. agentinputlab/algorithms/curate/llmlingua/budget.py +48 -0
  41. agentinputlab/algorithms/curate/llmlingua/controlled.py +175 -0
  42. agentinputlab/algorithms/curate/llmlingua/multilingual.py +105 -0
  43. agentinputlab/algorithms/curate/llmlingua/span_map.py +167 -0
  44. agentinputlab/algorithms/curate/recomp/__init__.py +47 -0
  45. agentinputlab/algorithms/curate/recomp/external.py +1129 -0
  46. agentinputlab/algorithms/curate/recomp/selective.py +304 -0
  47. agentinputlab/algorithms/decompose/__init__.py +107 -0
  48. agentinputlab/algorithms/decompose/decomp/__init__.py +53 -0
  49. agentinputlab/algorithms/decompose/decomp/common_support.py +478 -0
  50. agentinputlab/algorithms/decompose/decomp/planner_component.py +199 -0
  51. agentinputlab/algorithms/decompose/decomp/worker_bridge.py +416 -0
  52. agentinputlab/algorithms/decompose/llm_compiler/__init__.py +35 -0
  53. agentinputlab/algorithms/decompose/llm_compiler/bridge.py +520 -0
  54. agentinputlab/algorithms/decompose/llm_compiler/common_support.py +504 -0
  55. agentinputlab/algorithms/decompose/plan_and_budget/__init__.py +43 -0
  56. agentinputlab/algorithms/decompose/plan_and_budget/cached_soft_budget.py +362 -0
  57. agentinputlab/algorithms/decompose/plan_and_budget/decomposer_component.py +107 -0
  58. agentinputlab/algorithms/decompose/plan_and_budget/full.py +205 -0
  59. agentinputlab/algorithms/decompose/plan_and_budget/hard_cap.py +246 -0
  60. agentinputlab/algorithms/decompose/plan_and_budget/regenerated_soft_budget.py +448 -0
  61. agentinputlab/algorithms/decompose/plan_and_solve/__init__.py +33 -0
  62. agentinputlab/algorithms/decompose/plan_and_solve/plan_component.py +192 -0
  63. agentinputlab/algorithms/decompose/plan_and_solve/ps_prompt.py +127 -0
  64. agentinputlab/algorithms/decompose/self_ask/__init__.py +27 -0
  65. agentinputlab/algorithms/decompose/self_ask/loop.py +362 -0
  66. agentinputlab/algorithms/decompose/self_ask/planner_component.py +117 -0
  67. agentinputlab/algorithms/reformulate/__init__.py +85 -0
  68. agentinputlab/algorithms/reformulate/infocqr/__init__.py +40 -0
  69. agentinputlab/algorithms/reformulate/infocqr/cache_replay.py +362 -0
  70. agentinputlab/algorithms/reformulate/infocqr/external.py +675 -0
  71. agentinputlab/algorithms/reformulate/infocqr/student.py +189 -0
  72. agentinputlab/algorithms/reformulate/query2doc/__init__.py +42 -0
  73. agentinputlab/algorithms/reformulate/query2doc/controlled_live.py +190 -0
  74. agentinputlab/algorithms/reformulate/query2doc/models.py +95 -0
  75. agentinputlab/algorithms/reformulate/query2doc/official_cached.py +335 -0
  76. agentinputlab/algorithms/reformulate/query2doc/querygym_bridge.py +223 -0
  77. agentinputlab/algorithms/reformulate/query2doc/querygym_runtime.py +326 -0
  78. agentinputlab/algorithms/reformulate/reformer/__init__.py +23 -0
  79. agentinputlab/algorithms/reformulate/reformer/external.py +417 -0
  80. agentinputlab/algorithms/reformulate/rrr.py +696 -0
  81. agentinputlab/annotation/__init__.py +5 -0
  82. agentinputlab/annotation/independent.py +428 -0
  83. agentinputlab/annotation/server.py +233 -0
  84. agentinputlab/annotation/static/app.js +121 -0
  85. agentinputlab/annotation/static/index.html +60 -0
  86. agentinputlab/annotation/static/review.css +2 -0
  87. agentinputlab/annotation/static/review.html +10 -0
  88. agentinputlab/annotation/static/review.js +11 -0
  89. agentinputlab/annotation/static/styles.css +55 -0
  90. agentinputlab/annotation/store.py +444 -0
  91. agentinputlab/api.py +368 -0
  92. agentinputlab/artifacts/__init__.py +15 -0
  93. agentinputlab/artifacts/json_file.py +104 -0
  94. agentinputlab/artifacts/manifest.py +98 -0
  95. agentinputlab/artifacts/store.py +157 -0
  96. agentinputlab/backends/__init__.py +98 -0
  97. agentinputlab/backends/embedding/__init__.py +25 -0
  98. agentinputlab/backends/embedding/base.py +145 -0
  99. agentinputlab/backends/embedding/callable.py +75 -0
  100. agentinputlab/backends/embedding/replay.py +129 -0
  101. agentinputlab/backends/llm/__init__.py +31 -0
  102. agentinputlab/backends/llm/base.py +149 -0
  103. agentinputlab/backends/llm/callable.py +108 -0
  104. agentinputlab/backends/llm/decomp_completion.py +88 -0
  105. agentinputlab/backends/llm/final_content_stop.py +72 -0
  106. agentinputlab/backends/llm/gpt_oss_final_channel.py +84 -0
  107. agentinputlab/backends/llm/openai_compatible.py +332 -0
  108. agentinputlab/backends/llm/transformers.py +171 -0
  109. agentinputlab/backends/retrieval/__init__.py +35 -0
  110. agentinputlab/backends/retrieval/base.py +50 -0
  111. agentinputlab/backends/retrieval/dense.py +777 -0
  112. agentinputlab/backends/retrieval/memory.py +119 -0
  113. agentinputlab/backends/retrieval/sqlite_fts.py +155 -0
  114. agentinputlab/backends/user/__init__.py +15 -0
  115. agentinputlab/backends/user/base.py +66 -0
  116. agentinputlab/backends/user/callable.py +54 -0
  117. agentinputlab/backends/user/replay.py +89 -0
  118. agentinputlab/backends/vector.py +38 -0
  119. agentinputlab/benchmarks/__init__.py +246 -0
  120. agentinputlab/benchmarks/acquisition.py +106 -0
  121. agentinputlab/benchmarks/ale.py +540 -0
  122. agentinputlab/benchmarks/appworld_ul.py +669 -0
  123. agentinputlab/benchmarks/assets.py +226 -0
  124. agentinputlab/benchmarks/base.py +68 -0
  125. agentinputlab/benchmarks/beir_archive.py +235 -0
  126. agentinputlab/benchmarks/beir_sample.py +269 -0
  127. agentinputlab/benchmarks/bfcl_native.py +245 -0
  128. agentinputlab/benchmarks/bfcl_v3.py +607 -0
  129. agentinputlab/benchmarks/cache.py +218 -0
  130. agentinputlab/benchmarks/clariq.py +203 -0
  131. agentinputlab/benchmarks/data/registry.json +321 -0
  132. agentinputlab/benchmarks/data/smoke_assets.json +511 -0
  133. agentinputlab/benchmarks/data/statebench_v0_8_1_task_ids.json +475 -0
  134. agentinputlab/benchmarks/data/toolsandbox_165848b_scenario_names.json +1 -0
  135. agentinputlab/benchmarks/execution.py +1111 -0
  136. agentinputlab/benchmarks/interactive.py +257 -0
  137. agentinputlab/benchmarks/ir_query.py +204 -0
  138. agentinputlab/benchmarks/longbench.py +203 -0
  139. agentinputlab/benchmarks/paired_replay.py +479 -0
  140. agentinputlab/benchmarks/preprocess.py +2313 -0
  141. agentinputlab/benchmarks/production.py +236 -0
  142. agentinputlab/benchmarks/qa.py +963 -0
  143. agentinputlab/benchmarks/registry.py +110 -0
  144. agentinputlab/benchmarks/retrieval.py +459 -0
  145. agentinputlab/benchmarks/runtime.py +509 -0
  146. agentinputlab/benchmarks/statebench.py +938 -0
  147. agentinputlab/benchmarks/tau3.py +725 -0
  148. agentinputlab/benchmarks/toolsandbox.py +626 -0
  149. agentinputlab/benchmarks/trec_dl_sample.py +263 -0
  150. agentinputlab/campaign.py +654 -0
  151. agentinputlab/campaign_runner.py +953 -0
  152. agentinputlab/cli/__init__.py +6 -0
  153. agentinputlab/cli/main.py +933 -0
  154. agentinputlab/connectors/__init__.py +46 -0
  155. agentinputlab/connectors/knowledge/__init__.py +4 -0
  156. agentinputlab/connectors/tools/__init__.py +30 -0
  157. agentinputlab/connectors/tools/base.py +57 -0
  158. agentinputlab/connectors/tools/mcp.py +222 -0
  159. agentinputlab/connectors/tools/memory.py +41 -0
  160. agentinputlab/connectors/tools/openapi.py +695 -0
  161. agentinputlab/connectors/tools/schema.py +102 -0
  162. agentinputlab/contracts/__init__.py +91 -0
  163. agentinputlab/contracts/availability.py +24 -0
  164. agentinputlab/contracts/dependency.py +58 -0
  165. agentinputlab/contracts/enums.py +82 -0
  166. agentinputlab/contracts/errors.py +63 -0
  167. agentinputlab/contracts/evidence.py +43 -0
  168. agentinputlab/contracts/intent.py +110 -0
  169. agentinputlab/contracts/lifecycle.py +164 -0
  170. agentinputlab/contracts/patch.py +167 -0
  171. agentinputlab/contracts/serialization.py +93 -0
  172. agentinputlab/contracts/state.py +127 -0
  173. agentinputlab/contracts/trace.py +59 -0
  174. agentinputlab/contracts/worker.py +42 -0
  175. agentinputlab/core/__init__.py +7 -0
  176. agentinputlab/data/__init__.py +32 -0
  177. agentinputlab/data/checksums.py +9 -0
  178. agentinputlab/data/downloader.py +235 -0
  179. agentinputlab/data/http.py +171 -0
  180. agentinputlab/data/index.py +21 -0
  181. agentinputlab/data/overlap.py +28 -0
  182. agentinputlab/data/preprocess.py +32 -0
  183. agentinputlab/data/storage.py +57 -0
  184. agentinputlab/data/trec_sample.py +427 -0
  185. agentinputlab/evaluation/__init__.py +5 -0
  186. agentinputlab/evaluation/outcomes.py +32 -0
  187. agentinputlab/experiments/__init__.py +278 -0
  188. agentinputlab/experiments/analysis.py +981 -0
  189. agentinputlab/experiments/artifacts.py +687 -0
  190. agentinputlab/experiments/automatic_measurement.py +678 -0
  191. agentinputlab/experiments/auxiliary_matrix.py +203 -0
  192. agentinputlab/experiments/bindings.py +430 -0
  193. agentinputlab/experiments/blueprints.py +147 -0
  194. agentinputlab/experiments/builders/__init__.py +45 -0
  195. agentinputlab/experiments/builders/executable_external_payload.py +423 -0
  196. agentinputlab/experiments/builders/external_process_arena.py +1018 -0
  197. agentinputlab/experiments/builders/registry_intervention.py +463 -0
  198. agentinputlab/experiments/cli.py +158 -0
  199. agentinputlab/experiments/controls.py +340 -0
  200. agentinputlab/experiments/driver_guard.py +205 -0
  201. agentinputlab/experiments/drivers/__init__.py +89 -0
  202. agentinputlab/experiments/drivers/external_arena.py +2908 -0
  203. agentinputlab/experiments/drivers/method_process.py +662 -0
  204. agentinputlab/experiments/drivers/parity_process.py +1484 -0
  205. agentinputlab/experiments/drivers/static_production.py +1574 -0
  206. agentinputlab/experiments/executor.py +448 -0
  207. agentinputlab/experiments/loader.py +605 -0
  208. agentinputlab/experiments/measurement.py +675 -0
  209. agentinputlab/experiments/paper_analysis.py +1818 -0
  210. agentinputlab/experiments/parity_identity.py +605 -0
  211. agentinputlab/experiments/plan.py +277 -0
  212. agentinputlab/experiments/production_builders.py +3739 -0
  213. agentinputlab/experiments/readiness.py +432 -0
  214. agentinputlab/experiments/schema.py +514 -0
  215. agentinputlab/experiments/secrets.py +177 -0
  216. agentinputlab/experiments/stateful_analysis.py +1738 -0
  217. agentinputlab/experiments/transfer_analysis.py +1316 -0
  218. agentinputlab/experiments/unseen_analysis.py +1025 -0
  219. agentinputlab/integrations/__init__.py +1 -0
  220. agentinputlab/integrations/action_space/__init__.py +1 -0
  221. agentinputlab/integrations/external_workers/__init__.py +76 -0
  222. agentinputlab/integrations/external_workers/ace.py +431 -0
  223. agentinputlab/integrations/external_workers/base.py +181 -0
  224. agentinputlab/integrations/external_workers/decomp_live.py +249 -0
  225. agentinputlab/integrations/external_workers/decomp_planner.py +30 -0
  226. agentinputlab/integrations/external_workers/infocqr_student.py +280 -0
  227. agentinputlab/integrations/external_workers/ircot.py +576 -0
  228. agentinputlab/integrations/external_workers/llmcompiler_live.py +360 -0
  229. agentinputlab/integrations/external_workers/longllmlingua.py +162 -0
  230. agentinputlab/integrations/external_workers/method.py +314 -0
  231. agentinputlab/integrations/external_workers/process.py +678 -0
  232. agentinputlab/integrations/external_workers/supervisor.py +1071 -0
  233. agentinputlab/integrations/full_architecture/__init__.py +1 -0
  234. agentinputlab/integrations/full_architecture/hyde.py +212 -0
  235. agentinputlab/integrations/full_architecture/plan_and_budget.py +188 -0
  236. agentinputlab/integrations/live_history.py +222 -0
  237. agentinputlab/integrations/prompt_optimization/__init__.py +1 -0
  238. agentinputlab/integrations/training/__init__.py +1 -0
  239. agentinputlab/metrics/__init__.py +50 -0
  240. agentinputlab/metrics/catalog.py +313 -0
  241. agentinputlab/metrics/harm.py +95 -0
  242. agentinputlab/metrics/paired.py +40 -0
  243. agentinputlab/metrics/qa.py +76 -0
  244. agentinputlab/metrics/text.py +33 -0
  245. agentinputlab/metrics/third_party.py +161 -0
  246. agentinputlab/models/__init__.py +4 -0
  247. agentinputlab/observability/__init__.py +56 -0
  248. agentinputlab/observability/budget.py +316 -0
  249. agentinputlab/observability/instrumentation.py +754 -0
  250. agentinputlab/observability/models.py +403 -0
  251. agentinputlab/observability/monitor.py +380 -0
  252. agentinputlab/optimizers/__init__.py +1 -0
  253. agentinputlab/optimizers/clarify/__init__.py +12 -0
  254. agentinputlab/optimizers/context/__init__.py +22 -0
  255. agentinputlab/optimizers/decompose/__init__.py +64 -0
  256. agentinputlab/optimizers/evidence/__init__.py +22 -0
  257. agentinputlab/optimizers/rewrite/__init__.py +30 -0
  258. agentinputlab/parity/__init__.py +5 -0
  259. agentinputlab/parity/base.py +206 -0
  260. agentinputlab/production_campaign.py +763 -0
  261. agentinputlab/py.typed +1 -0
  262. agentinputlab/recipes/__init__.py +333 -0
  263. agentinputlab/recipes/ace.py +418 -0
  264. agentinputlab/recipes/ace_bfcl.py +273 -0
  265. agentinputlab/recipes/ace_common_support.py +169 -0
  266. agentinputlab/recipes/ace_native_plan.py +322 -0
  267. agentinputlab/recipes/ace_online.py +711 -0
  268. agentinputlab/recipes/ace_retrieval.py +330 -0
  269. agentinputlab/recipes/ace_statebench.py +382 -0
  270. agentinputlab/recipes/ace_tau.py +463 -0
  271. agentinputlab/recipes/ace_toolsandbox.py +432 -0
  272. agentinputlab/recipes/acon_guideline.py +22 -0
  273. agentinputlab/recipes/adaptive_rag.py +822 -0
  274. agentinputlab/recipes/llmlingua2_inference.py +146 -0
  275. agentinputlab/recipes/llmlingua2_training.py +796 -0
  276. agentinputlab/recipes/mce.py +1486 -0
  277. agentinputlab/recipes/mce_final.py +335 -0
  278. agentinputlab/recipes/mce_text_fit.py +499 -0
  279. agentinputlab/recipes/mce_text_only.py +298 -0
  280. agentinputlab/recipes/qrag.py +729 -0
  281. agentinputlab/recipes/qrag_inference.py +364 -0
  282. agentinputlab/recipes/r2ag_features.py +236 -0
  283. agentinputlab/recipes/r2ag_inference.py +503 -0
  284. agentinputlab/recipes/r2ag_training.py +948 -0
  285. agentinputlab/recipes/recomp_abstractive.py +592 -0
  286. agentinputlab/recipes/recomp_extractive.py +525 -0
  287. agentinputlab/recipes/reformer.py +17 -0
  288. agentinputlab/recipes/rqrag.py +1516 -0
  289. agentinputlab/recipes/rqrag_common_support.py +193 -0
  290. agentinputlab/recipes/rqrag_completion.py +147 -0
  291. agentinputlab/recipes/skillopt.py +462 -0
  292. agentinputlab/recipes/skillopt_common_support.py +154 -0
  293. agentinputlab/recipes/skillopt_environment.py +165 -0
  294. agentinputlab/recipes/skillopt_environment_cli.py +5 -0
  295. agentinputlab/recipes/skillopt_retrieval.py +188 -0
  296. agentinputlab/recipes/smartsearch.py +897 -0
  297. agentinputlab/recipes/smartsearch_curriculum.py +283 -0
  298. agentinputlab/recipes/smartsearch_grpo_contracts.py +58 -0
  299. agentinputlab/recipes/smartsearch_grpo_data.py +314 -0
  300. agentinputlab/recipes/smartsearch_grpo_meter.py +324 -0
  301. agentinputlab/recipes/smartsearch_grpo_prefix.py +144 -0
  302. agentinputlab/recipes/smartsearch_grpo_rollout.py +119 -0
  303. agentinputlab/recipes/smartsearch_grpo_tools.py +364 -0
  304. agentinputlab/recipes/smartsearch_grpo_training.py +305 -0
  305. agentinputlab/recipes/smartsearch_grpo_transport.py +248 -0
  306. agentinputlab/recipes/smartsearch_grpo_worker.py +364 -0
  307. agentinputlab/recipes/smartsearch_inference.py +524 -0
  308. agentinputlab/recipes/smartsearch_native_data.py +172 -0
  309. agentinputlab/recipes/smartsearch_policy.py +616 -0
  310. agentinputlab/recipes/smartsearch_policy_worker.py +9 -0
  311. agentinputlab/recipes/smartsearch_sampling.py +232 -0
  312. agentinputlab/recipes/smartsearch_teacher.py +203 -0
  313. agentinputlab/recipes/smartsearch_training.py +265 -0
  314. agentinputlab/registry/__init__.py +46 -0
  315. agentinputlab/registry/beta.py +727 -0
  316. agentinputlab/registry/data/algorithms.json +1959 -0
  317. agentinputlab/registry/data/auxiliary_method_profiles.json +34 -0
  318. agentinputlab/registry/loader.py +100 -0
  319. agentinputlab/registry/result_manifest.py +184 -0
  320. agentinputlab/registry/runtime.py +195 -0
  321. agentinputlab/registry/schema.py +449 -0
  322. agentinputlab/runner/__init__.py +30 -0
  323. agentinputlab/runner/balance.py +248 -0
  324. agentinputlab/runner/cache.py +135 -0
  325. agentinputlab/runner/composite.py +130 -0
  326. agentinputlab/runner/engine.py +285 -0
  327. agentinputlab/runner/runtime_guard.py +268 -0
  328. agentinputlab/runner/worker.py +80 -0
  329. agentinputlab/runtime_bootstrap.py +288 -0
  330. agentinputlab/selectors/__init__.py +196 -0
  331. agentinputlab/selectors/advanced.py +1514 -0
  332. agentinputlab/selectors/artifacts.py +1087 -0
  333. agentinputlab/selectors/base.py +112 -0
  334. agentinputlab/selectors/campaigns.py +1893 -0
  335. agentinputlab/selectors/catalog.py +86 -0
  336. agentinputlab/selectors/discovery.py +1860 -0
  337. agentinputlab/selectors/evaluation.py +1348 -0
  338. agentinputlab/selectors/features.py +383 -0
  339. agentinputlab/selectors/learned.py +502 -0
  340. agentinputlab/selectors/no_op.py +28 -0
  341. agentinputlab/selectors/outcome_table.py +475 -0
  342. agentinputlab/selectors/producer.py +853 -0
  343. agentinputlab/selectors/rules.py +109 -0
  344. agentinputlab/selectors/runtime.py +420 -0
  345. agentinputlab/studies/__init__.py +16 -0
  346. agentinputlab/studies/design.py +165 -0
  347. agentinputlab/studies/paired.py +322 -0
  348. agentinputlab/studio/__init__.py +6 -0
  349. agentinputlab/studio/campaigns.py +819 -0
  350. agentinputlab/studio/engine.py +1408 -0
  351. agentinputlab/studio/model_backends.py +425 -0
  352. agentinputlab/studio/prepared.py +410 -0
  353. agentinputlab/studio/server.py +613 -0
  354. agentinputlab/studio/static/app.js +397 -0
  355. agentinputlab/studio/static/campaigns.html +175 -0
  356. agentinputlab/studio/static/campaigns.js +426 -0
  357. agentinputlab/studio/static/index.html +192 -0
  358. agentinputlab/studio/static/result.html +103 -0
  359. agentinputlab/studio/static/result.js +273 -0
  360. agentinputlab/studio/static/styles.css +467 -0
  361. agentinputlab-0.1.0a1.data/data/share/agentinputlab/CITATION.cff +22 -0
  362. agentinputlab-0.1.0a1.dist-info/METADATA +392 -0
  363. agentinputlab-0.1.0a1.dist-info/RECORD +469 -0
  364. agentinputlab-0.1.0a1.dist-info/WHEEL +5 -0
  365. agentinputlab-0.1.0a1.dist-info/entry_points.txt +6 -0
  366. agentinputlab-0.1.0a1.dist-info/licenses/LICENSE +21 -0
  367. agentinputlab-0.1.0a1.dist-info/licenses/NOTICE +31 -0
  368. agentinputlab-0.1.0a1.dist-info/licenses/THIRD_PARTY_NOTICES.md +94 -0
  369. agentinputlab-0.1.0a1.dist-info/top_level.txt +2 -0
  370. workers/README.md +94 -0
  371. workers/ace/README.md +261 -0
  372. workers/ace/__init__.py +1 -0
  373. workers/ace/compatibility_manifest.json +39 -0
  374. workers/ace/driver.py +1682 -0
  375. workers/acon/README.md +215 -0
  376. workers/acon/__init__.py +5 -0
  377. workers/acon/compatibility_manifest.json +93 -0
  378. workers/acon/driver.py +1859 -0
  379. workers/acon/fitted.py +395 -0
  380. workers/acon/guideline.py +470 -0
  381. workers/acon/guideline_source_manifest.json +20 -0
  382. workers/adaptive_rag/README.md +96 -0
  383. workers/adaptive_rag/__init__.py +15 -0
  384. workers/adaptive_rag/compatibility_manifest.json +61 -0
  385. workers/adaptive_rag/driver.py +1470 -0
  386. workers/adaptive_rag/fixture_runtime.py +163 -0
  387. workers/adaptive_rag/runtime.py +252 -0
  388. workers/ask_or_assume/README.md +124 -0
  389. workers/ask_or_assume/__init__.py +1 -0
  390. workers/ask_or_assume/compatibility_manifest.json +36 -0
  391. workers/ask_or_assume/driver.py +1227 -0
  392. workers/decomp/README.md +133 -0
  393. workers/decomp/UPSTREAM_LICENSE.Apache-2.0.txt +201 -0
  394. workers/decomp/__init__.py +5 -0
  395. workers/decomp/compatibility_manifest.json +205 -0
  396. workers/decomp/driver.py +1015 -0
  397. workers/decomp/live.py +137 -0
  398. workers/decomp/runtime.py +231 -0
  399. workers/infocqr/README.md +106 -0
  400. workers/infocqr/__init__.py +1 -0
  401. workers/infocqr/compatibility_manifest.json +84 -0
  402. workers/infocqr/driver.py +1766 -0
  403. workers/ircot/README.md +167 -0
  404. workers/ircot/__init__.py +7 -0
  405. workers/ircot/compatibility_manifest.json +121 -0
  406. workers/ircot/controlled.py +457 -0
  407. workers/ircot/driver.py +1373 -0
  408. workers/ircot/fixture_bindings.json +39 -0
  409. workers/ircot/fixture_config.json +48 -0
  410. workers/ircot/fixture_prompt.txt +2 -0
  411. workers/ircot/native_qa.py +398 -0
  412. workers/ircot/qa_compatibility_manifest.json +57 -0
  413. workers/ircot/runtime.py +97 -0
  414. workers/llmcompiler/README.md +160 -0
  415. workers/llmcompiler/__init__.py +1 -0
  416. workers/llmcompiler/compatibility_manifest.json +45 -0
  417. workers/llmcompiler/driver.py +1514 -0
  418. workers/llmcompiler/export_prompts.py +74 -0
  419. workers/llmcompiler/live.py +174 -0
  420. workers/llmcompiler/patch_manifest.json +147 -0
  421. workers/mce/README.md +198 -0
  422. workers/mce/__init__.py +29 -0
  423. workers/mce/compatibility_manifest.json +115 -0
  424. workers/mce/driver.py +2585 -0
  425. workers/mce/final_eval.py +173 -0
  426. workers/official_arenas/README.md +25 -0
  427. workers/official_arenas/__init__.py +1 -0
  428. workers/official_arenas/capture_records.py +110 -0
  429. workers/official_arenas/driver.py +619 -0
  430. workers/official_arenas/protocol.py +334 -0
  431. workers/official_arenas/providers/__init__.py +1 -0
  432. workers/official_arenas/providers/_live_history.py +228 -0
  433. workers/official_arenas/providers/_message_compat.py +77 -0
  434. workers/official_arenas/providers/appworld_ul.py +196 -0
  435. workers/official_arenas/providers/fixture.py +112 -0
  436. workers/official_arenas/providers/statebench.py +960 -0
  437. workers/official_arenas/providers/tau3.py +1672 -0
  438. workers/official_arenas/providers/tau_retail.py +586 -0
  439. workers/official_arenas/providers/toolsandbox.py +1321 -0
  440. workers/official_arenas/providers/tooltalk.py +699 -0
  441. workers/official_arenas/retail_capture.py +188 -0
  442. workers/official_arenas/retail_driver.py +275 -0
  443. workers/qrag/README.md +172 -0
  444. workers/qrag/__init__.py +1 -0
  445. workers/qrag/compatibility_manifest.json +64 -0
  446. workers/qrag/driver.py +673 -0
  447. workers/r2ag/README.md +154 -0
  448. workers/r2ag/__init__.py +5 -0
  449. workers/r2ag/compatibility_manifest.json +55 -0
  450. workers/r2ag/driver.py +1287 -0
  451. workers/r2ag/feature_schema.json +8 -0
  452. workers/r2ag/runtime.py +589 -0
  453. workers/recomp/README.md +120 -0
  454. workers/recomp/__init__.py +1 -0
  455. workers/recomp/compatibility_manifest.json +43 -0
  456. workers/recomp/driver.py +1653 -0
  457. workers/reformer/README.md +125 -0
  458. workers/reformer/__init__.py +1 -0
  459. workers/reformer/compatibility_manifest.json +68 -0
  460. workers/reformer/driver.py +1459 -0
  461. workers/reformer/induction.py +457 -0
  462. workers/rrr/README.md +126 -0
  463. workers/rrr/__init__.py +1 -0
  464. workers/rrr/compatibility_manifest.json +57 -0
  465. workers/rrr/driver.py +1133 -0
  466. workers/smartsearch/README.md +331 -0
  467. workers/smartsearch/__init__.py +1 -0
  468. workers/smartsearch/compatibility_manifest.json +41 -0
  469. workers/smartsearch/driver.py +1643 -0
@@ -0,0 +1,1470 @@
1
+ #!/usr/bin/env python3
2
+ """Source-verified, budget-supervised Adaptive-RAG worker.
3
+
4
+ The driver owns routing, arm dispatch, usage accounting, and the event log.
5
+ Injected model/retrieval components return only typed inference results; they
6
+ cannot supply attestations or caller-controlled trace records.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import hashlib
12
+ import json
13
+ import math
14
+ import re
15
+ import subprocess
16
+ import sys
17
+ from collections.abc import Callable, Mapping, Sequence
18
+ from dataclasses import dataclass, field
19
+ from pathlib import Path, PurePosixPath
20
+ from types import MappingProxyType
21
+ from typing import Any, Protocol, TextIO
22
+
23
+ UPSTREAM_COMMIT = "0c88670af8707667eb5c1163151bb5ce61b14acb"
24
+ UPSTREAM_TREE = "8dadc754562d61d5d6e6e3ee2fc3aa4481763320"
25
+ METHOD_ID = "adaptive_rag"
26
+ RELEASE_ID = "acquire.adaptive_rag.controlled_reimplementation"
27
+ PROTOCOL_VERSION = "agentinputlab.adaptive-rag.v1"
28
+ MANIFEST_SCHEMA = "agentinputlab.adaptive-rag.compatibility.v1"
29
+ EVENT_SCHEMA = "agentinputlab.adaptive-rag.supervisor-event.v1"
30
+ EVIDENCE_SCHEMA = "agentinputlab.adaptive-rag.execution-evidence.v1"
31
+ DEFAULT_MANIFEST = Path(__file__).with_name("compatibility_manifest.json")
32
+ _ZERO_HASH = "0" * 64
33
+ _HEX40 = re.compile(r"[0-9a-f]{40}")
34
+ _HEX64 = re.compile(r"[0-9a-f]{64}")
35
+ _ROUTES = ("A", "B", "C")
36
+ _STRATEGIES = {"A": "no_retrieval", "B": "single_retrieval", "C": "ircot"}
37
+ _ROOT_FIELDS = frozenset(
38
+ {
39
+ "method_id",
40
+ "release_id",
41
+ "upstream_commit",
42
+ "state_hash",
43
+ "payload",
44
+ "dependency_fingerprints",
45
+ "minimum_reservation",
46
+ "protocol_version",
47
+ "request_id",
48
+ }
49
+ )
50
+ _PAYLOAD_FIELDS = frozenset(
51
+ {
52
+ "task_id",
53
+ "question",
54
+ "artifacts",
55
+ "artifact_identity_sha256",
56
+ "controls",
57
+ "remaining_budget",
58
+ "seed",
59
+ "execution_contract",
60
+ }
61
+ )
62
+ _FORBIDDEN_KEYS = frozenset(
63
+ {
64
+ "answer",
65
+ "answers",
66
+ "attestation",
67
+ "gold",
68
+ "gold_answer",
69
+ "ground_truth",
70
+ "label",
71
+ "labels",
72
+ "oracle",
73
+ "reward",
74
+ "silver",
75
+ "target",
76
+ }
77
+ )
78
+ _ALLOWED_DOCUMENT_METADATA = frozenset({"source_uri", "chunk_index", "language", "content_sha256"})
79
+
80
+
81
+ class DriverError(RuntimeError):
82
+ """Expected fail-closed worker error."""
83
+
84
+ def __init__(
85
+ self,
86
+ code: str,
87
+ message: str,
88
+ *,
89
+ consumed: bool = False,
90
+ partial_usage: Mapping[str, Any] | None = None,
91
+ partial_events: Sequence[Mapping[str, Any]] = (),
92
+ ) -> None:
93
+ super().__init__(message)
94
+ self.code = code
95
+ self.public_message = message
96
+ self.consumed = consumed
97
+ self.partial_usage = dict(partial_usage) if partial_usage is not None else _zero_usage()
98
+ self.partial_events = tuple(dict(event) for event in partial_events)
99
+
100
+
101
+ @dataclass(frozen=True, slots=True)
102
+ class RouterResult:
103
+ """Raw first decoder-step label logits and observed usage."""
104
+
105
+ logits: Mapping[str, float]
106
+ input_tokens: int
107
+ output_tokens: int = 1
108
+ accelerator_seconds: float = 0.0
109
+ cost_usd: float | None = None
110
+
111
+
112
+ @dataclass(frozen=True, slots=True)
113
+ class GenerationResult:
114
+ text: str
115
+ input_tokens: int
116
+ output_tokens: int
117
+ accelerator_seconds: float = 0.0
118
+ cost_usd: float | None = None
119
+ reset_retrieval: bool = False
120
+
121
+
122
+ @dataclass(frozen=True, slots=True)
123
+ class RetrievedDocument:
124
+ document_id: str
125
+ text: str
126
+ title: str = ""
127
+ score: float | None = None
128
+ metadata: Mapping[str, Any] = field(default_factory=dict)
129
+
130
+ def __post_init__(self) -> None:
131
+ # Detach valid mappings immediately so a caller-owned retriever object
132
+ # cannot drift between retrieval and supervisor validation. Semantic
133
+ # allowlisting intentionally remains in _validate_document so leakage
134
+ # is still reported at the supervised retriever boundary.
135
+ if isinstance(self.metadata, Mapping):
136
+ object.__setattr__(self, "metadata", _freeze_metadata_value(self.metadata))
137
+
138
+ def as_mapping(self, *, corpus_revision: str) -> Mapping[str, Any]:
139
+ return {
140
+ "document_id": self.document_id,
141
+ "text": self.text,
142
+ "title": self.title,
143
+ "corpus_revision": corpus_revision,
144
+ "score": self.score,
145
+ "metadata": dict(self.metadata),
146
+ }
147
+
148
+
149
+ @dataclass(frozen=True, slots=True)
150
+ class RuntimeIdentity:
151
+ router_revision: str
152
+ router_snapshot_sha256: str
153
+ router_weights_sha256: str
154
+ router_tokenizer_sha256: str
155
+ base_model_revision: str
156
+ generator_artifact_sha256: str
157
+ generator_config_sha256: str
158
+ retriever_revision: str
159
+ retriever_implementation_sha256: str
160
+ retriever_config_sha256: str
161
+ corpus_revision: str
162
+ corpus_manifest_sha256: str
163
+ index_revision: str
164
+ index_manifest_sha256: str
165
+ fixture_runtime: bool = False
166
+
167
+ def __post_init__(self) -> None:
168
+ for name in (
169
+ "router_revision",
170
+ "base_model_revision",
171
+ "retriever_revision",
172
+ "corpus_revision",
173
+ "index_revision",
174
+ ):
175
+ value = getattr(self, name)
176
+ if not isinstance(value, str) or not value.strip():
177
+ raise DriverError("RUNTIME_IDENTITY_INVALID", f"{name} must be non-empty")
178
+ if value.strip().lower() in {"default", "head", "latest", "main", "master"}:
179
+ raise DriverError("RUNTIME_IDENTITY_INVALID", f"{name} must be immutable")
180
+ for name in (
181
+ "router_snapshot_sha256",
182
+ "router_weights_sha256",
183
+ "router_tokenizer_sha256",
184
+ "generator_artifact_sha256",
185
+ "generator_config_sha256",
186
+ "retriever_implementation_sha256",
187
+ "retriever_config_sha256",
188
+ "corpus_manifest_sha256",
189
+ "index_manifest_sha256",
190
+ ):
191
+ _sha256(getattr(self, name), name)
192
+ if not isinstance(self.fixture_runtime, bool):
193
+ raise DriverError("RUNTIME_IDENTITY_INVALID", "fixture_runtime must be boolean")
194
+
195
+
196
+ class RouterBackend(Protocol):
197
+ def component_manifest(self) -> Mapping[str, Any]: ...
198
+
199
+ def estimate_input_tokens(self, question: str) -> int: ...
200
+
201
+ def first_decoder_step(self, question: str, *, seed: int) -> RouterResult: ...
202
+
203
+
204
+ class GeneratorBackend(Protocol):
205
+ def component_manifest(self) -> Mapping[str, Any]: ...
206
+
207
+ def estimate_input_tokens(
208
+ self,
209
+ *,
210
+ operation: str,
211
+ question: str,
212
+ documents: Sequence[RetrievedDocument],
213
+ reasoning: Sequence[str],
214
+ prompt: str,
215
+ ) -> int: ...
216
+
217
+ def generate(
218
+ self,
219
+ *,
220
+ operation: str,
221
+ question: str,
222
+ documents: Sequence[RetrievedDocument],
223
+ reasoning: Sequence[str],
224
+ prompt: str,
225
+ max_output_tokens: int,
226
+ seed: int,
227
+ ) -> GenerationResult: ...
228
+
229
+
230
+ class RetrieverBackend(Protocol):
231
+ def component_manifest(self) -> Mapping[str, Any]: ...
232
+
233
+ def retrieve(self, query: str, *, top_k: int) -> Sequence[RetrievedDocument]: ...
234
+
235
+
236
+ @dataclass(frozen=True, slots=True)
237
+ class RuntimeBundle:
238
+ identity: RuntimeIdentity
239
+ router: RouterBackend
240
+ generator: GeneratorBackend
241
+ retriever: RetrieverBackend
242
+
243
+
244
+ @dataclass(frozen=True, slots=True)
245
+ class CompatibilityPolicy:
246
+ commit: str
247
+ tree: str
248
+ license_path: str
249
+ license_sha256: str
250
+ require_clean_checkout: bool
251
+ source_hashes: Mapping[str, str]
252
+ prompt_files: Mapping[str, str]
253
+
254
+ @classmethod
255
+ def from_mapping(cls, value: Mapping[str, Any]) -> CompatibilityPolicy:
256
+ if value.get("schema_version") != MANIFEST_SCHEMA:
257
+ raise DriverError("INVALID_MANIFEST", "Adaptive-RAG manifest schema mismatch")
258
+ upstream = _mapping(value.get("upstream"), "manifest upstream")
259
+ execution = _mapping(value.get("execution"), "manifest execution")
260
+ security = _mapping(value.get("security"), "manifest security")
261
+ if upstream.get("commit") != UPSTREAM_COMMIT:
262
+ raise DriverError("INVALID_MANIFEST", "Adaptive-RAG manifest commit mismatch")
263
+ tree = _git_hash(upstream.get("tree"), "manifest tree")
264
+ if upstream.get("license_spdx") != "Apache-2.0":
265
+ raise DriverError("INVALID_MANIFEST", "Adaptive-RAG root license must be Apache-2.0")
266
+ if execution.get("method_id") != METHOD_ID or execution.get("release_id") != RELEASE_ID:
267
+ raise DriverError("INVALID_MANIFEST", "Adaptive-RAG manifest release mismatch")
268
+ if execution.get("protocol_version") != PROTOCOL_VERSION:
269
+ raise DriverError("INVALID_MANIFEST", "Adaptive-RAG manifest protocol mismatch")
270
+ if execution.get("route_labels") != list(_ROUTES):
271
+ raise DriverError("INVALID_MANIFEST", "Adaptive-RAG route order must be A, B, C")
272
+ if execution.get("strategy_map") != _STRATEGIES:
273
+ raise DriverError("INVALID_MANIFEST", "Adaptive-RAG strategy map mismatch")
274
+ if (
275
+ execution.get("supervisor_event_schema") != EVENT_SCHEMA
276
+ or execution.get("execution_evidence_schema") != EVIDENCE_SCHEMA
277
+ ):
278
+ raise DriverError("INVALID_MANIFEST", "Adaptive-RAG evidence schema mismatch")
279
+ required_security = {
280
+ "request_supplied_paths_allowed": False,
281
+ "request_supplied_endpoints_allowed": False,
282
+ "request_supplied_attestations_allowed": False,
283
+ "evaluation_gold_fields_allowed": False,
284
+ "evaluation_silver_fields_allowed": False,
285
+ "evaluation_oracle_fields_allowed": False,
286
+ "production_fixture_runtime_allowed": False,
287
+ "budget_checked_before_every_external_call": True,
288
+ "selected_arm_only": True,
289
+ "official_parity_claimed": False,
290
+ }
291
+ if any(security.get(key) != expected for key, expected in required_security.items()):
292
+ raise DriverError("INVALID_MANIFEST", "Adaptive-RAG security policy drifted")
293
+ raw_sources = _mapping(value.get("source_files"), "manifest source_files")
294
+ source_hashes = {
295
+ _relative_path(path, "manifest source path"): _sha256(digest, "source hash")
296
+ for path, digest in raw_sources.items()
297
+ }
298
+ prompts = {
299
+ strategy: _relative_path(path, f"{strategy} prompt path")
300
+ for strategy, path in _mapping(
301
+ execution.get("prompt_files"), "manifest prompt_files"
302
+ ).items()
303
+ }
304
+ if set(prompts) != set(_STRATEGIES.values()):
305
+ raise DriverError("INVALID_MANIFEST", "Adaptive-RAG manifest must bind three prompts")
306
+ return cls(
307
+ commit=UPSTREAM_COMMIT,
308
+ tree=tree,
309
+ license_path=_relative_path(upstream.get("license_path"), "license path"),
310
+ license_sha256=_sha256(upstream.get("license_sha256"), "license hash"),
311
+ require_clean_checkout=upstream.get("require_clean_checkout") is True,
312
+ source_hashes=source_hashes,
313
+ prompt_files=prompts,
314
+ )
315
+
316
+
317
+ class _Supervisor:
318
+ """Only object allowed to dispatch external calls and write call evidence."""
319
+
320
+ def __init__(
321
+ self,
322
+ *,
323
+ runtime: RuntimeBundle,
324
+ remaining: Mapping[str, Any],
325
+ ) -> None:
326
+ self.runtime = runtime
327
+ self.remaining: dict[str, int | None] = {
328
+ "model_calls": _nonnegative_int(remaining.get("model_calls"), "model budget"),
329
+ "retrieval_calls": _nonnegative_int(
330
+ remaining.get("retrieval_calls"), "retrieval budget"
331
+ ),
332
+ "input_tokens": _optional_nonnegative_int(
333
+ remaining.get("context_tokens"), "context budget"
334
+ ),
335
+ "output_tokens": _nonnegative_int(remaining.get("output_tokens"), "output budget"),
336
+ }
337
+ self.events: list[Mapping[str, Any]] = []
338
+ self._last_hash = _ZERO_HASH
339
+ self._usage = _zero_usage()
340
+
341
+ def can_model(self, count: int = 1) -> bool:
342
+ return int(self.remaining["model_calls"] or 0) >= count
343
+
344
+ def can_retrieve(self, count: int = 1) -> bool:
345
+ return int(self.remaining["retrieval_calls"] or 0) >= count
346
+
347
+ def classify(self, question: str, *, seed: int) -> Mapping[str, float]:
348
+ estimate = self.runtime.router.estimate_input_tokens(question)
349
+ result = self._model_call(
350
+ operation="router.first_decoder_step",
351
+ estimated_input_tokens=estimate,
352
+ requested_output_tokens=1,
353
+ invoke=lambda cap: self.runtime.router.first_decoder_step(question, seed=seed),
354
+ result_builder=lambda value: {
355
+ "question_sha256": _content_hash(question),
356
+ "route_logits": dict(value.logits),
357
+ },
358
+ )
359
+ if not isinstance(result, RouterResult):
360
+ raise self.error("ROUTER_FAILED", "router returned the wrong result type")
361
+ if set(result.logits) != set(_ROUTES):
362
+ raise self.error("ROUTER_FAILED", "router must return exactly A/B/C logits")
363
+ try:
364
+ logits = {
365
+ label: _finite_number(result.logits[label], f"router logit {label}")
366
+ for label in _ROUTES
367
+ }
368
+ except DriverError as exc:
369
+ raise self.error(exc.code, exc.public_message) from exc
370
+ # Replace the event's raw mapping only after strict finite validation.
371
+ event = dict(self.events[-1])
372
+ result_payload = dict(_mapping(event["result"], "router event result"))
373
+ result_payload["route_logits"] = logits
374
+ event["result"] = result_payload
375
+ self._replace_last_event(event)
376
+ return logits
377
+
378
+ def retrieve(
379
+ self,
380
+ *,
381
+ operation: str,
382
+ query: str,
383
+ top_k: int,
384
+ ) -> tuple[RetrievedDocument, ...]:
385
+ before = self._reserve(
386
+ operation=operation,
387
+ call_kind="retrieval",
388
+ model_calls=0,
389
+ retrieval_calls=1,
390
+ input_tokens=0,
391
+ output_tokens=0,
392
+ )
393
+ try:
394
+ raw = self.runtime.retriever.retrieve(query, top_k=top_k)
395
+ except Exception as exc:
396
+ raise self.error("RETRIEVER_FAILED", "retriever call failed") from exc
397
+ if isinstance(raw, (str, bytes)) or not isinstance(raw, Sequence):
398
+ raise self.error("RETRIEVER_FAILED", "retriever returned a non-sequence")
399
+ try:
400
+ documents = tuple(_validate_document(item) for item in raw)
401
+ except DriverError as exc:
402
+ raise self.error(exc.code, exc.public_message) from exc
403
+ if len(documents) > top_k:
404
+ raise self.error("RETRIEVER_FAILED", "retriever exceeded top_k")
405
+ ids = tuple(item.document_id for item in documents)
406
+ if len(ids) != len(set(ids)):
407
+ raise self.error("RETRIEVER_FAILED", "retriever returned duplicate IDs")
408
+ self._record(
409
+ operation=operation,
410
+ call_kind="retrieval",
411
+ before=before,
412
+ reservation={
413
+ "model_calls": 0,
414
+ "retrieval_calls": 1,
415
+ "estimated_input_tokens": 0,
416
+ "max_output_tokens": 0,
417
+ },
418
+ usage=_zero_usage(retrieval_calls=1),
419
+ result={
420
+ "query": query,
421
+ "query_sha256": _content_hash(query),
422
+ "top_k": top_k,
423
+ "document_ids": ids,
424
+ "documents_sha256": _content_hash(
425
+ tuple(_document_event_mapping(item) for item in documents)
426
+ ),
427
+ },
428
+ )
429
+ return documents
430
+
431
+ def generate(
432
+ self,
433
+ *,
434
+ operation: str,
435
+ question: str,
436
+ documents: Sequence[RetrievedDocument],
437
+ reasoning: Sequence[str],
438
+ prompt: str,
439
+ output_cap: int,
440
+ seed: int,
441
+ ) -> GenerationResult:
442
+ estimate = self.runtime.generator.estimate_input_tokens(
443
+ operation=operation,
444
+ question=question,
445
+ documents=documents,
446
+ reasoning=reasoning,
447
+ prompt=prompt,
448
+ )
449
+ result = self._model_call(
450
+ operation=operation,
451
+ estimated_input_tokens=estimate,
452
+ requested_output_tokens=output_cap,
453
+ invoke=lambda cap: self.runtime.generator.generate(
454
+ operation=operation,
455
+ question=question,
456
+ documents=documents,
457
+ reasoning=reasoning,
458
+ prompt=prompt,
459
+ max_output_tokens=cap,
460
+ seed=seed,
461
+ ),
462
+ result_builder=lambda value: {
463
+ "text_sha256": _content_hash(value.text),
464
+ "document_ids": tuple(item.document_id for item in documents),
465
+ "reset_retrieval": value.reset_retrieval,
466
+ },
467
+ )
468
+ if not isinstance(result, GenerationResult) or not result.text.strip():
469
+ raise self.error("GENERATOR_FAILED", "generator returned invalid text")
470
+ return result
471
+
472
+ def _model_call(
473
+ self,
474
+ *,
475
+ operation: str,
476
+ estimated_input_tokens: int,
477
+ requested_output_tokens: int,
478
+ invoke: Callable[[int], RouterResult | GenerationResult],
479
+ result_builder: Callable[[RouterResult | GenerationResult], Mapping[str, Any]],
480
+ ) -> RouterResult | GenerationResult:
481
+ estimate = _nonnegative_int(estimated_input_tokens, "estimated input tokens")
482
+ requested = _positive_int(requested_output_tokens, "requested output tokens")
483
+ available_output = int(self.remaining["output_tokens"] or 0)
484
+ cap = min(requested, available_output)
485
+ if cap < 1:
486
+ raise self.error("OUTPUT_BUDGET_EXHAUSTED", "model output budget exhausted")
487
+ before = self._reserve(
488
+ operation=operation,
489
+ call_kind="model",
490
+ model_calls=1,
491
+ retrieval_calls=0,
492
+ input_tokens=estimate,
493
+ output_tokens=cap,
494
+ )
495
+ try:
496
+ result = invoke(cap)
497
+ except Exception as exc:
498
+ raise self.error("MODEL_FAILED", f"{operation} failed") from exc
499
+ if not isinstance(result, (RouterResult, GenerationResult)):
500
+ raise self.error("MODEL_FAILED", f"{operation} returned invalid result")
501
+ try:
502
+ actual_input = _nonnegative_int(result.input_tokens, "observed input tokens")
503
+ actual_output = _nonnegative_int(result.output_tokens, "observed output tokens")
504
+ accelerator_seconds = _nonnegative_number(
505
+ result.accelerator_seconds, "accelerator_seconds"
506
+ )
507
+ cost_usd = (
508
+ None
509
+ if result.cost_usd is None
510
+ else _nonnegative_number(result.cost_usd, "cost_usd")
511
+ )
512
+ except DriverError as exc:
513
+ raise self.error(exc.code, exc.public_message) from exc
514
+ self._usage["input_tokens"] += actual_input
515
+ self._usage["output_tokens"] += actual_output
516
+ self._usage["accelerator_seconds"] += accelerator_seconds
517
+ if cost_usd is not None:
518
+ self._usage["cost_usd"] += cost_usd
519
+ self._usage["unpriced_model_calls"] -= 1
520
+ if actual_input > estimate:
521
+ raise self.error(
522
+ "INPUT_BUDGET_ESTIMATE_BREACH",
523
+ f"{operation} exceeded its pre-call input reservation",
524
+ )
525
+ if actual_output > cap:
526
+ raise self.error(
527
+ "OUTPUT_BUDGET_EXCEEDED",
528
+ f"{operation} exceeded its pre-call output cap",
529
+ )
530
+ self._consume_tokens(actual_input=actual_input, actual_output=actual_output)
531
+ usage = _zero_usage(
532
+ model_calls=1,
533
+ unpriced_model_calls=1 if result.cost_usd is None else 0,
534
+ input_tokens=actual_input,
535
+ output_tokens=actual_output,
536
+ accelerator_seconds=accelerator_seconds,
537
+ cost_usd=0.0 if cost_usd is None else cost_usd,
538
+ )
539
+ self._record(
540
+ operation=operation,
541
+ call_kind="model",
542
+ before=before,
543
+ reservation={
544
+ "model_calls": 1,
545
+ "retrieval_calls": 0,
546
+ "estimated_input_tokens": estimate,
547
+ "max_output_tokens": cap,
548
+ },
549
+ usage=usage,
550
+ result=result_builder(result),
551
+ )
552
+ return result
553
+
554
+ def _reserve(
555
+ self,
556
+ *,
557
+ operation: str,
558
+ call_kind: str,
559
+ model_calls: int,
560
+ retrieval_calls: int,
561
+ input_tokens: int,
562
+ output_tokens: int,
563
+ ) -> Mapping[str, int | None]:
564
+ before = dict(self.remaining)
565
+ if int(self.remaining["model_calls"] or 0) < model_calls:
566
+ raise self.error(
567
+ "MODEL_BUDGET_EXHAUSTED",
568
+ f"{operation} model budget exhausted",
569
+ )
570
+ if int(self.remaining["retrieval_calls"] or 0) < retrieval_calls:
571
+ raise self.error(
572
+ "RETRIEVAL_BUDGET_EXHAUSTED", f"{operation} retrieval budget exhausted"
573
+ )
574
+ context = self.remaining["input_tokens"]
575
+ if context is not None and context < input_tokens:
576
+ raise self.error(
577
+ "CONTEXT_BUDGET_EXHAUSTED",
578
+ f"{operation} context budget exhausted",
579
+ )
580
+ if int(self.remaining["output_tokens"] or 0) < output_tokens:
581
+ raise self.error(
582
+ "OUTPUT_BUDGET_EXHAUSTED",
583
+ f"{operation} output budget exhausted",
584
+ )
585
+ if call_kind not in {"model", "retrieval"}:
586
+ raise self.error("INTERNAL_ERROR", "unknown supervisor call kind")
587
+ self.remaining["model_calls"] = int(self.remaining["model_calls"] or 0) - model_calls
588
+ self.remaining["retrieval_calls"] = (
589
+ int(self.remaining["retrieval_calls"] or 0) - retrieval_calls
590
+ )
591
+ self._usage["model_calls"] += model_calls
592
+ self._usage["retrieval_calls"] += retrieval_calls
593
+ self._usage["unpriced_model_calls"] += model_calls
594
+ # Tokens are consumed after the call, but the upper bounds are checked here.
595
+ return before
596
+
597
+ def _consume_tokens(self, *, actual_input: int, actual_output: int) -> None:
598
+ context = self.remaining["input_tokens"]
599
+ if context is not None:
600
+ self.remaining["input_tokens"] = context - actual_input
601
+ self.remaining["output_tokens"] = int(self.remaining["output_tokens"] or 0) - actual_output
602
+
603
+ def _record(
604
+ self,
605
+ *,
606
+ operation: str,
607
+ call_kind: str,
608
+ before: Mapping[str, int | None],
609
+ reservation: Mapping[str, Any],
610
+ usage: Mapping[str, Any],
611
+ result: Mapping[str, Any],
612
+ ) -> None:
613
+ event = {
614
+ "schema": EVENT_SCHEMA,
615
+ "sequence": len(self.events),
616
+ "previous_event_sha256": self._last_hash,
617
+ "call_kind": call_kind,
618
+ "operation": operation,
619
+ "pre_call_remaining": dict(before),
620
+ "reservation": dict(reservation),
621
+ "usage": dict(usage),
622
+ "result": dict(result),
623
+ }
624
+ event["event_sha256"] = _content_hash(event)
625
+ self.events.append(event)
626
+ self._last_hash = str(event["event_sha256"])
627
+
628
+ def _replace_last_event(self, event: Mapping[str, Any]) -> None:
629
+ unsigned = {key: value for key, value in event.items() if key != "event_sha256"}
630
+ updated = {**unsigned, "event_sha256": _content_hash(unsigned)}
631
+ self.events[-1] = updated
632
+ self._last_hash = str(updated["event_sha256"])
633
+
634
+ def usage(self) -> Mapping[str, Any]:
635
+ return dict(self._usage)
636
+
637
+ def error(self, code: str, message: str) -> DriverError:
638
+ consumed = bool(self._usage["model_calls"] or self._usage["retrieval_calls"])
639
+ return DriverError(
640
+ code,
641
+ message,
642
+ consumed=consumed,
643
+ partial_usage=self._usage,
644
+ partial_events=self.events,
645
+ )
646
+
647
+
648
+ class AdaptiveRAGWorkerDriver:
649
+ """Verify immutable deployment inputs and execute one selected strategy."""
650
+
651
+ def __init__(
652
+ self,
653
+ *,
654
+ source_root: Path,
655
+ router_weights_path: Path,
656
+ prompt_root: Path,
657
+ runtime: RuntimeBundle,
658
+ router_snapshot_path: Path | None = None,
659
+ router_tokenizer_path: Path | None = None,
660
+ generator_artifact_manifest_path: Path | None = None,
661
+ generator_config_path: Path | None = None,
662
+ retriever_implementation_path: Path | None = None,
663
+ retriever_config_path: Path | None = None,
664
+ corpus_manifest_path: Path | None = None,
665
+ index_manifest_path: Path | None = None,
666
+ manifest_path: Path = DEFAULT_MANIFEST,
667
+ fixture_mode: bool = False,
668
+ ) -> None:
669
+ supplied_paths = {
670
+ "source root": source_root,
671
+ "router weights": router_weights_path,
672
+ "prompt root": prompt_root,
673
+ "router snapshot": router_snapshot_path,
674
+ "router tokenizer": router_tokenizer_path,
675
+ "generator artifact manifest": generator_artifact_manifest_path,
676
+ "generator config": generator_config_path,
677
+ "retriever implementation": retriever_implementation_path,
678
+ "retriever config": retriever_config_path,
679
+ "corpus manifest": corpus_manifest_path,
680
+ "index manifest": index_manifest_path,
681
+ }
682
+ for label, path in supplied_paths.items():
683
+ if path is not None and path.is_symlink():
684
+ raise DriverError(
685
+ "PATH_INVALID",
686
+ f"Adaptive-RAG {label} must not be a symlink",
687
+ )
688
+ self.source_root = source_root.resolve()
689
+ self.router_weights_path = router_weights_path.resolve()
690
+ self.prompt_root = prompt_root.resolve()
691
+ self.runtime = runtime
692
+ self.component_paths = {
693
+ "router_snapshot_sha256": router_snapshot_path,
694
+ "router_tokenizer_sha256": router_tokenizer_path,
695
+ "generator_artifact_sha256": generator_artifact_manifest_path,
696
+ "generator_config_sha256": generator_config_path,
697
+ "retriever_implementation_sha256": retriever_implementation_path,
698
+ "retriever_config_sha256": retriever_config_path,
699
+ "corpus_manifest_sha256": corpus_manifest_path,
700
+ "index_manifest_sha256": index_manifest_path,
701
+ }
702
+ self.manifest_path = manifest_path.resolve()
703
+ self.manifest = _load_json(self.manifest_path)
704
+ self.manifest_sha256 = _content_hash(self.manifest)
705
+ self.policy = CompatibilityPolicy.from_mapping(self.manifest)
706
+ self.fixture_mode = fixture_mode
707
+ if runtime.identity.fixture_runtime is not fixture_mode:
708
+ raise DriverError("FIXTURE_MODE_MISMATCH", "runtime and driver fixture modes disagree")
709
+
710
+ def handle(self, request: Mapping[str, Any]) -> Mapping[str, Any]:
711
+ try:
712
+ return self._handle(request)
713
+ except DriverError as exc:
714
+ return {
715
+ "status": "error",
716
+ "failure_code": exc.code,
717
+ "message": exc.public_message,
718
+ "consumed": exc.consumed,
719
+ "usage": dict(exc.partial_usage),
720
+ "partial_events": tuple(exc.partial_events),
721
+ }
722
+
723
+ def source_fingerprint(self) -> Mapping[str, Any]:
724
+ return self._verify_source()
725
+
726
+ def _handle(self, request: Mapping[str, Any]) -> Mapping[str, Any]:
727
+ _reject_forbidden_keys(request, "request")
728
+ payload = _validate_envelope(request)
729
+ artifacts = _mapping(payload.get("artifacts"), "artifacts")
730
+ if payload.get("artifact_identity_sha256") != _content_hash(artifacts):
731
+ raise DriverError("IDENTITY_MISMATCH", "artifact identity hash mismatch")
732
+ controls = _controls(payload.get("controls"))
733
+ _execution_contract(payload.get("execution_contract"))
734
+ source = self._verify_source()
735
+ prompts = self._verify_runtime_assets(artifacts)
736
+ question = _text(payload.get("question"), "question")
737
+ seed = _nonnegative_int(payload.get("seed"), "seed")
738
+ supervisor = _Supervisor(
739
+ runtime=self.runtime,
740
+ remaining=_mapping(payload.get("remaining_budget"), "remaining_budget"),
741
+ )
742
+ logits = supervisor.classify(question, seed=seed)
743
+ route = max(_ROUTES, key=lambda label: logits[label])
744
+ strategy = _STRATEGIES[route]
745
+ documents: list[RetrievedDocument] = []
746
+ initial: Mapping[str, Any] | None = None
747
+ steps: list[Mapping[str, Any]] = []
748
+ active_ids: tuple[str, ...] = ()
749
+
750
+ if strategy == "no_retrieval":
751
+ if not supervisor.can_model():
752
+ raise supervisor.error(
753
+ "MODEL_BUDGET_EXHAUSTED",
754
+ "selected arm cannot answer",
755
+ )
756
+ generated = supervisor.generate(
757
+ operation="answer.no_retrieval",
758
+ question=question,
759
+ documents=(),
760
+ reasoning=(),
761
+ prompt=prompts[strategy],
762
+ output_cap=controls["max_output_tokens"],
763
+ seed=seed + 1,
764
+ )
765
+ elif strategy == "single_retrieval":
766
+ if not supervisor.can_retrieve() or not supervisor.can_model():
767
+ raise supervisor.error(
768
+ "ARM_BUDGET_EXHAUSTED",
769
+ "single-retrieval arm lacks budget",
770
+ )
771
+ retrieved = supervisor.retrieve(
772
+ operation="retrieve.single.initial",
773
+ query=question,
774
+ top_k=controls["single_retrieval_top_k"],
775
+ )
776
+ if not retrieved:
777
+ raise supervisor.error(
778
+ "EMPTY_RETRIEVAL",
779
+ "single-retrieval arm returned no documents",
780
+ )
781
+ documents.extend(retrieved)
782
+ active_ids = tuple(item.document_id for item in retrieved)
783
+ initial = {"query": question, "document_ids": active_ids}
784
+ generated = supervisor.generate(
785
+ operation="answer.single_retrieval",
786
+ question=question,
787
+ documents=retrieved,
788
+ reasoning=(),
789
+ prompt=prompts[strategy],
790
+ output_cap=controls["max_output_tokens"],
791
+ seed=seed + 1,
792
+ )
793
+ else:
794
+ if not supervisor.can_retrieve() or not supervisor.can_model():
795
+ raise supervisor.error(
796
+ "ARM_BUDGET_EXHAUSTED",
797
+ "IRCoT arm lacks minimum budget",
798
+ )
799
+ initial_docs = supervisor.retrieve(
800
+ operation="retrieve.ircot.initial",
801
+ query=question,
802
+ top_k=controls["ircot_per_step_top_k"],
803
+ )
804
+ if not initial_docs:
805
+ raise supervisor.error(
806
+ "EMPTY_RETRIEVAL",
807
+ "IRCoT initial retrieval returned no documents",
808
+ )
809
+ documents.extend(initial_docs)
810
+ active = list(initial_docs)
811
+ active_ids = tuple(item.document_id for item in active)
812
+ initial = {"query": question, "document_ids": active_ids}
813
+ reasoning: list[str] = []
814
+ seen = set(active_ids)
815
+ for index in range(controls["ircot_max_steps"]):
816
+ # Preserve one final model call; a reasoning step also requires its retrieval.
817
+ if not supervisor.can_model(2) or not supervisor.can_retrieve():
818
+ break
819
+ reason = supervisor.generate(
820
+ operation=f"ircot.reason.{index}",
821
+ question=question,
822
+ documents=active,
823
+ reasoning=reasoning,
824
+ prompt=prompts[strategy],
825
+ output_cap=controls["max_output_tokens"],
826
+ seed=seed + 1 + index,
827
+ )
828
+ reasoning.append(reason.text)
829
+ try:
830
+ retrieval_query = _latest_nonempty_line(reason.text)
831
+ except DriverError as exc:
832
+ raise supervisor.error(exc.code, exc.public_message) from exc
833
+ retrieved = supervisor.retrieve(
834
+ operation=f"retrieve.ircot.step.{index}",
835
+ query=retrieval_query,
836
+ top_k=controls["ircot_per_step_top_k"],
837
+ )
838
+ new_docs = tuple(item for item in retrieved if item.document_id not in seen)
839
+ for item in new_docs:
840
+ seen.add(item.document_id)
841
+ documents.append(item)
842
+ if len(seen) > controls["max_total_documents"]:
843
+ raise supervisor.error(
844
+ "DOCUMENT_BUDGET_EXCEEDED",
845
+ "IRCoT document budget exceeded",
846
+ )
847
+ reset = controls["ircot_reset_policy"] == "replace_each_step" or (
848
+ controls["ircot_reset_policy"] == "upstream_native" and reason.reset_retrieval
849
+ )
850
+ if reset:
851
+ active = list(retrieved)
852
+ else:
853
+ active.extend(new_docs)
854
+ active_ids = tuple(item.document_id for item in active)
855
+ steps.append(
856
+ {
857
+ "index": index,
858
+ "cot_step": reason.text,
859
+ "latest_cot_sentence": retrieval_query,
860
+ "retrieval_query": retrieval_query,
861
+ "retrieved_document_ids": tuple(item.document_id for item in retrieved),
862
+ "new_document_ids": tuple(item.document_id for item in new_docs),
863
+ "active_document_ids": active_ids,
864
+ "reset_applied": reset,
865
+ }
866
+ )
867
+ generated = supervisor.generate(
868
+ operation="answer.ircot",
869
+ question=question,
870
+ documents=active,
871
+ reasoning=reasoning,
872
+ prompt=prompts[strategy],
873
+ output_cap=controls["max_output_tokens"],
874
+ seed=seed + 1 + len(steps),
875
+ )
876
+
877
+ event_log = tuple(supervisor.events)
878
+ usage = supervisor.usage()
879
+ evidence_kind = "hermetic_fixture" if self.fixture_mode else "controlled_component_closure"
880
+ evidence = {
881
+ "schema": EVIDENCE_SCHEMA,
882
+ "evidence_kind": evidence_kind,
883
+ "fixture_runtime": self.fixture_mode,
884
+ "controlled_method_execution": True,
885
+ "controlled_upstream_router_parity": True,
886
+ "upstream_arm_parity_claimed": False,
887
+ "official_parity_claimed": False,
888
+ "source_commit": source["commit"],
889
+ "source_tree": source["tree"],
890
+ "source_state": source["state"],
891
+ "source_closure_sha256": source["closure_sha256"],
892
+ "compatibility_manifest_sha256": self.manifest_sha256,
893
+ "router_revision": artifacts["router_revision"],
894
+ "router_snapshot_sha256": artifacts["router_snapshot_sha256"],
895
+ "router_weights_sha256": artifacts["router_weights_sha256"],
896
+ "router_tokenizer_sha256": artifacts["router_tokenizer_sha256"],
897
+ "base_model_revision": artifacts["base_model_revision"],
898
+ "generator_artifact_sha256": artifacts["generator_artifact_sha256"],
899
+ "generator_config_sha256": artifacts["generator_config_sha256"],
900
+ "retriever_revision": artifacts["retriever_revision"],
901
+ "retriever_implementation_sha256": artifacts["retriever_implementation_sha256"],
902
+ "retriever_config_sha256": artifacts["retriever_config_sha256"],
903
+ "corpus_revision": artifacts["corpus_revision"],
904
+ "corpus_manifest_sha256": artifacts["corpus_manifest_sha256"],
905
+ "index_revision": artifacts["index_revision"],
906
+ "index_manifest_sha256": artifacts["index_manifest_sha256"],
907
+ "prompt_sha256": {
908
+ "no_retrieval": artifacts["no_retrieval_prompt_sha256"],
909
+ "single_retrieval": artifacts["single_retrieval_prompt_sha256"],
910
+ "ircot": artifacts["ircot_prompt_sha256"],
911
+ },
912
+ "selected_strategy": strategy,
913
+ "event_log_sha256": _content_hash(event_log),
914
+ "final_event_sha256": event_log[-1]["event_sha256"],
915
+ "events": event_log,
916
+ }
917
+ return {
918
+ "status": "ok",
919
+ "request_id": request["request_id"],
920
+ "upstream_commit": UPSTREAM_COMMIT,
921
+ "protocol_version": PROTOCOL_VERSION,
922
+ "payload": {
923
+ "question": question,
924
+ "artifacts": dict(artifacts),
925
+ "artifact_identity_sha256": payload["artifact_identity_sha256"],
926
+ "route_logits": logits,
927
+ "route_label": route,
928
+ "selected_strategy": strategy,
929
+ "answer": generated.text,
930
+ "documents": tuple(
931
+ item.as_mapping(corpus_revision=self.runtime.identity.corpus_revision)
932
+ for item in documents
933
+ ),
934
+ "initial_retrieval": initial,
935
+ "ircot_steps": tuple(steps),
936
+ "active_document_ids": active_ids,
937
+ "execution_evidence": evidence,
938
+ },
939
+ "usage": usage,
940
+ }
941
+
942
+ def _verify_source(self) -> Mapping[str, Any]:
943
+ for relative, expected in self.policy.source_hashes.items():
944
+ if _file_sha256(_safe_file(self.source_root, relative)) != expected:
945
+ raise DriverError("SOURCE_MISMATCH", f"source hash mismatch: {relative}")
946
+ if _file_sha256(_safe_file(self.source_root, self.policy.license_path)) != (
947
+ self.policy.license_sha256
948
+ ):
949
+ raise DriverError("SOURCE_MISMATCH", "Adaptive-RAG license hash mismatch")
950
+ if self.fixture_mode:
951
+ state = "verified_fixture_snapshot"
952
+ tree = self.policy.tree
953
+ else:
954
+ if not (self.source_root / ".git").exists():
955
+ raise DriverError("SOURCE_MISMATCH", "production source must be a Git checkout")
956
+ commit = _git(self.source_root, "rev-parse", "HEAD")
957
+ tree = _git(self.source_root, "rev-parse", "HEAD^{tree}")
958
+ status = _git(self.source_root, "status", "--porcelain=v1", "--untracked-files=all")
959
+ if commit != self.policy.commit or tree != self.policy.tree or status:
960
+ raise DriverError("SOURCE_MISMATCH", "source checkout is not exact and clean")
961
+ state = "clean_git_checkout"
962
+ closure = _content_hash(
963
+ {
964
+ "commit": self.policy.commit,
965
+ "tree": tree,
966
+ "source_files": dict(self.policy.source_hashes),
967
+ "license_sha256": self.policy.license_sha256,
968
+ }
969
+ )
970
+ return {
971
+ "commit": self.policy.commit,
972
+ "tree": tree,
973
+ "state": state,
974
+ "closure_sha256": closure,
975
+ }
976
+
977
+ def _verify_runtime_assets(self, artifacts: Mapping[str, Any]) -> Mapping[str, str]:
978
+ identity = self.runtime.identity
979
+ expected = {
980
+ "upstream_commit": UPSTREAM_COMMIT,
981
+ "router_revision": identity.router_revision,
982
+ "router_snapshot_sha256": identity.router_snapshot_sha256,
983
+ "router_weights_sha256": identity.router_weights_sha256,
984
+ "router_tokenizer_sha256": identity.router_tokenizer_sha256,
985
+ "base_model_revision": identity.base_model_revision,
986
+ "generator_artifact_sha256": identity.generator_artifact_sha256,
987
+ "generator_config_sha256": identity.generator_config_sha256,
988
+ "retriever_revision": identity.retriever_revision,
989
+ "retriever_implementation_sha256": identity.retriever_implementation_sha256,
990
+ "retriever_config_sha256": identity.retriever_config_sha256,
991
+ "corpus_revision": identity.corpus_revision,
992
+ "corpus_manifest_sha256": identity.corpus_manifest_sha256,
993
+ "index_revision": identity.index_revision,
994
+ "index_manifest_sha256": identity.index_manifest_sha256,
995
+ }
996
+ for key, value in expected.items():
997
+ if artifacts.get(key) != value:
998
+ raise DriverError("PROFILE_DRIFT", f"runtime identity mismatch: {key}")
999
+ weights_hash = _path_closure_sha256(self.router_weights_path)
1000
+ if identity.router_weights_sha256 != weights_hash:
1001
+ raise DriverError("ROUTER_MISMATCH", "router weights hash mismatch")
1002
+ if not self.fixture_mode:
1003
+ missing = [name for name, path in self.component_paths.items() if path is None]
1004
+ if missing:
1005
+ raise DriverError(
1006
+ "COMPONENT_CLOSURE_MISSING",
1007
+ "production runtime lacks component closure paths: "
1008
+ + ", ".join(sorted(missing)),
1009
+ )
1010
+ for name, path in self.component_paths.items():
1011
+ assert path is not None
1012
+ if _path_closure_sha256(path.resolve()) != getattr(identity, name):
1013
+ raise DriverError(
1014
+ "COMPONENT_CLOSURE_MISMATCH",
1015
+ f"production component closure mismatch: {name}",
1016
+ )
1017
+ verify_component_manifests(self.runtime, fixture_mode=self.fixture_mode)
1018
+ hash_fields = {
1019
+ "no_retrieval": "no_retrieval_prompt_sha256",
1020
+ "single_retrieval": "single_retrieval_prompt_sha256",
1021
+ "ircot": "ircot_prompt_sha256",
1022
+ }
1023
+ prompts: dict[str, str] = {}
1024
+ for strategy, relative in self.policy.prompt_files.items():
1025
+ path = _safe_file(self.prompt_root, relative)
1026
+ if _file_sha256(path) != artifacts.get(hash_fields[strategy]):
1027
+ raise DriverError("PROMPT_MISMATCH", f"{strategy} prompt hash mismatch")
1028
+ prompts[strategy] = path.read_text(encoding="utf-8")
1029
+ return prompts
1030
+
1031
+
1032
+ def verify_component_manifests(runtime: RuntimeBundle, *, fixture_mode: bool) -> None:
1033
+ identity = runtime.identity
1034
+ expected = {
1035
+ "router": {
1036
+ "component_type": "router",
1037
+ "fixture_runtime": fixture_mode,
1038
+ "revision": identity.router_revision,
1039
+ "snapshot_sha256": identity.router_snapshot_sha256,
1040
+ "weights_sha256": identity.router_weights_sha256,
1041
+ "tokenizer_sha256": identity.router_tokenizer_sha256,
1042
+ },
1043
+ "generator": {
1044
+ "component_type": "generator",
1045
+ "fixture_runtime": fixture_mode,
1046
+ "revision": identity.base_model_revision,
1047
+ "artifact_sha256": identity.generator_artifact_sha256,
1048
+ "config_sha256": identity.generator_config_sha256,
1049
+ },
1050
+ "retriever": {
1051
+ "component_type": "retriever",
1052
+ "fixture_runtime": fixture_mode,
1053
+ "revision": identity.retriever_revision,
1054
+ "implementation_sha256": identity.retriever_implementation_sha256,
1055
+ "config_sha256": identity.retriever_config_sha256,
1056
+ "corpus_revision": identity.corpus_revision,
1057
+ "corpus_manifest_sha256": identity.corpus_manifest_sha256,
1058
+ "index_revision": identity.index_revision,
1059
+ "index_manifest_sha256": identity.index_manifest_sha256,
1060
+ },
1061
+ }
1062
+ for name, component in (
1063
+ ("router", runtime.router),
1064
+ ("generator", runtime.generator),
1065
+ ("retriever", runtime.retriever),
1066
+ ):
1067
+ implementation_class = f"{type(component).__module__}.{type(component).__qualname__}"
1068
+ if (
1069
+ not fixture_mode
1070
+ and type(component).__module__ == "workers.adaptive_rag.fixture_runtime"
1071
+ ):
1072
+ raise DriverError(
1073
+ "FIXTURE_COMPONENT_REJECTED",
1074
+ f"production runtime cannot use the hermetic {name}",
1075
+ )
1076
+ provider = getattr(component, "component_manifest", None)
1077
+ if not callable(provider):
1078
+ raise DriverError(
1079
+ "COMPONENT_MANIFEST_MISSING",
1080
+ f"{name} must expose component_manifest()",
1081
+ )
1082
+ manifest = provider()
1083
+ if not isinstance(manifest, Mapping):
1084
+ raise DriverError(
1085
+ "COMPONENT_MANIFEST_INVALID",
1086
+ f"{name} component manifest must be a mapping",
1087
+ )
1088
+ required = {**expected[name], "implementation_class": implementation_class}
1089
+ if dict(manifest) != required:
1090
+ raise DriverError(
1091
+ "COMPONENT_MANIFEST_MISMATCH",
1092
+ f"{name} component manifest does not match the locked runtime identity",
1093
+ )
1094
+
1095
+
1096
+ def _validate_envelope(request: Mapping[str, Any]) -> Mapping[str, Any]:
1097
+ if not isinstance(request, Mapping) or set(request) != _ROOT_FIELDS:
1098
+ raise DriverError("REQUEST_INVALID", "worker request envelope fields are invalid")
1099
+ if (
1100
+ request.get("method_id") != METHOD_ID
1101
+ or request.get("release_id") != RELEASE_ID
1102
+ or request.get("upstream_commit") != UPSTREAM_COMMIT
1103
+ or request.get("protocol_version") != PROTOCOL_VERSION
1104
+ ):
1105
+ raise DriverError("IDENTITY_MISMATCH", "Adaptive-RAG envelope identity mismatch")
1106
+ identity = {key: request[key] for key in _ROOT_FIELDS if key != "request_id"}
1107
+ if request.get("request_id") != _content_hash(identity):
1108
+ raise DriverError("IDENTITY_MISMATCH", "Adaptive-RAG request_id mismatch")
1109
+ payload = _mapping(request.get("payload"), "payload")
1110
+ if set(payload) != _PAYLOAD_FIELDS:
1111
+ raise DriverError("REQUEST_INVALID", "Adaptive-RAG payload fields are invalid")
1112
+ return payload
1113
+
1114
+
1115
+ def _execution_contract(value: Any) -> None:
1116
+ expected = {
1117
+ "input_view": "question_only",
1118
+ "route_labels": list(_ROUTES),
1119
+ "route_rule": "first_decoder_step_logit_argmax_A_first",
1120
+ "strategy_map": _STRATEGIES,
1121
+ "evaluation_label_access": "none",
1122
+ "selected_arm_only": True,
1123
+ "fallback_allowed": False,
1124
+ "arm_execution_semantics": "controlled_reimplementation",
1125
+ "upstream_router_parity": True,
1126
+ "supervisor_event_schema": EVENT_SCHEMA,
1127
+ }
1128
+ if value != expected:
1129
+ raise DriverError("EXECUTION_CONTRACT_REJECTED", "execution contract drifted")
1130
+
1131
+
1132
+ def _controls(value: Any) -> Mapping[str, Any]:
1133
+ raw = _mapping(value, "controls")
1134
+ expected = {
1135
+ "single_retrieval_top_k",
1136
+ "ircot_per_step_top_k",
1137
+ "ircot_max_steps",
1138
+ "max_total_documents",
1139
+ "max_output_tokens",
1140
+ "ircot_reset_policy",
1141
+ "deduplicate_documents",
1142
+ }
1143
+ if set(raw) != expected:
1144
+ raise DriverError("REQUEST_INVALID", "Adaptive-RAG controls fields are invalid")
1145
+ result = {
1146
+ key: _positive_int(raw[key], key)
1147
+ for key in (
1148
+ "single_retrieval_top_k",
1149
+ "ircot_per_step_top_k",
1150
+ "ircot_max_steps",
1151
+ "max_total_documents",
1152
+ "max_output_tokens",
1153
+ )
1154
+ }
1155
+ if raw["ircot_reset_policy"] not in {"upstream_native", "never", "replace_each_step"}:
1156
+ raise DriverError("REQUEST_INVALID", "unsupported IRCoT reset policy")
1157
+ if raw["deduplicate_documents"] is not True:
1158
+ raise DriverError("REQUEST_INVALID", "controlled runtime requires document deduplication")
1159
+ return {
1160
+ **result,
1161
+ "ircot_reset_policy": raw["ircot_reset_policy"],
1162
+ "deduplicate_documents": True,
1163
+ }
1164
+
1165
+
1166
+ def _validate_document(value: Any) -> RetrievedDocument:
1167
+ if not isinstance(value, RetrievedDocument):
1168
+ raise DriverError("RETRIEVER_FAILED", "retriever must return RetrievedDocument")
1169
+ if not value.document_id.strip() or not value.text:
1170
+ raise DriverError("RETRIEVER_FAILED", "retrieved document requires ID and text")
1171
+ if value.score is not None:
1172
+ _finite_number(value.score, "document score")
1173
+ if not isinstance(value.metadata, Mapping):
1174
+ raise DriverError("RETRIEVER_FAILED", "document metadata must be a mapping")
1175
+ metadata = _validated_document_metadata(value.metadata)
1176
+ return RetrievedDocument(
1177
+ document_id=value.document_id,
1178
+ text=value.text,
1179
+ title=value.title,
1180
+ score=value.score,
1181
+ metadata=MappingProxyType(metadata),
1182
+ )
1183
+
1184
+
1185
+ def _validated_document_metadata(value: Mapping[str, Any]) -> dict[str, Any]:
1186
+ unknown = set(value) - _ALLOWED_DOCUMENT_METADATA
1187
+ if unknown:
1188
+ raise DriverError(
1189
+ "EVALUATION_LEAKAGE",
1190
+ "document metadata contains non-allowlisted fields: "
1191
+ + ", ".join(sorted(str(item) for item in unknown)),
1192
+ )
1193
+ normalized: dict[str, Any] = {}
1194
+ for key, item in value.items():
1195
+ if key in {"source_uri", "language"}:
1196
+ if not isinstance(item, str) or not item.strip():
1197
+ raise DriverError(
1198
+ "RETRIEVER_FAILED",
1199
+ f"document metadata {key} must be non-empty text",
1200
+ )
1201
+ normalized[key] = item.strip()
1202
+ elif key == "chunk_index":
1203
+ if isinstance(item, bool) or not isinstance(item, int) or item < 0:
1204
+ raise DriverError(
1205
+ "RETRIEVER_FAILED",
1206
+ "document metadata chunk_index must be non-negative",
1207
+ )
1208
+ normalized[key] = item
1209
+ else:
1210
+ normalized[key] = _sha256(item, "document metadata content_sha256")
1211
+ return normalized
1212
+
1213
+
1214
+ def _freeze_metadata_value(value: Any) -> Any:
1215
+ """Detach and recursively freeze caller-owned metadata containers."""
1216
+
1217
+ if isinstance(value, Mapping):
1218
+ return MappingProxyType({key: _freeze_metadata_value(item) for key, item in value.items()})
1219
+ if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
1220
+ return tuple(_freeze_metadata_value(item) for item in value)
1221
+ if isinstance(value, (set, frozenset)):
1222
+ return frozenset(_freeze_metadata_value(item) for item in value)
1223
+ return value
1224
+
1225
+
1226
+ def _document_event_mapping(value: RetrievedDocument) -> Mapping[str, Any]:
1227
+ return {
1228
+ "document_id": value.document_id,
1229
+ "text_sha256": _content_hash(value.text),
1230
+ "title_sha256": _content_hash(value.title),
1231
+ "score": value.score,
1232
+ "metadata": dict(value.metadata),
1233
+ }
1234
+
1235
+
1236
+ def _reject_forbidden_keys(value: Any, path: str = "payload") -> None:
1237
+ if isinstance(value, Mapping):
1238
+ for key, item in value.items():
1239
+ normalized = str(key).strip().lower()
1240
+ if normalized in _FORBIDDEN_KEYS or any(
1241
+ token in normalized for token in ("gold_", "silver_", "oracle_")
1242
+ ):
1243
+ raise DriverError("EVALUATION_LEAKAGE", f"forbidden evaluation field at {path}")
1244
+ _reject_forbidden_keys(item, f"{path}.{key}")
1245
+ elif isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
1246
+ for index, item in enumerate(value):
1247
+ _reject_forbidden_keys(item, f"{path}[{index}]")
1248
+
1249
+
1250
+ def _zero_usage(**updates: int | float) -> dict[str, int | float]:
1251
+ result: dict[str, int | float] = {
1252
+ "model_calls": 0,
1253
+ "retrieval_calls": 0,
1254
+ "tool_calls": 0,
1255
+ "embedding_calls": 0,
1256
+ "unpriced_model_calls": 0,
1257
+ "input_tokens": 0,
1258
+ "output_tokens": 0,
1259
+ "cpu_seconds": 0.0,
1260
+ "accelerator_seconds": 0.0,
1261
+ "cost_usd": 0.0,
1262
+ "compute_cost_usd": 0.0,
1263
+ }
1264
+ result.update(updates)
1265
+ return result
1266
+
1267
+
1268
+ def _latest_nonempty_line(text: str) -> str:
1269
+ lines = tuple(line.strip() for line in text.splitlines() if line.strip())
1270
+ if not lines:
1271
+ raise DriverError("GENERATOR_FAILED", "IRCoT reasoning step is empty", consumed=True)
1272
+ return lines[-1]
1273
+
1274
+
1275
+ def _mapping(value: Any, label: str) -> Mapping[str, Any]:
1276
+ if not isinstance(value, Mapping):
1277
+ raise DriverError("REQUEST_INVALID", f"{label} must be a mapping")
1278
+ return value
1279
+
1280
+
1281
+ def _text(value: Any, label: str) -> str:
1282
+ if not isinstance(value, str) or not value.strip():
1283
+ raise DriverError("REQUEST_INVALID", f"{label} must be non-empty text")
1284
+ return value
1285
+
1286
+
1287
+ def _positive_int(value: Any, label: str) -> int:
1288
+ result = _nonnegative_int(value, label)
1289
+ if result < 1:
1290
+ raise DriverError("REQUEST_INVALID", f"{label} must be positive")
1291
+ return result
1292
+
1293
+
1294
+ def _nonnegative_int(value: Any, label: str) -> int:
1295
+ if isinstance(value, bool) or not isinstance(value, int) or value < 0:
1296
+ raise DriverError("REQUEST_INVALID", f"{label} must be a non-negative integer")
1297
+ return value
1298
+
1299
+
1300
+ def _optional_nonnegative_int(value: Any, label: str) -> int | None:
1301
+ return None if value is None else _nonnegative_int(value, label)
1302
+
1303
+
1304
+ def _finite_number(value: Any, label: str) -> float:
1305
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
1306
+ raise DriverError("RUNTIME_INVALID", f"{label} must be numeric", consumed=True)
1307
+ result = float(value)
1308
+ if not math.isfinite(result):
1309
+ raise DriverError("RUNTIME_INVALID", f"{label} must be finite", consumed=True)
1310
+ return result
1311
+
1312
+
1313
+ def _nonnegative_number(value: Any, label: str) -> float:
1314
+ result = _finite_number(value, label)
1315
+ if result < 0:
1316
+ raise DriverError("RUNTIME_INVALID", f"{label} must be non-negative", consumed=True)
1317
+ return result
1318
+
1319
+
1320
+ def _sha256(value: Any, label: str) -> str:
1321
+ if not isinstance(value, str) or _HEX64.fullmatch(value) is None:
1322
+ raise DriverError("INVALID_MANIFEST", f"{label} must be SHA-256")
1323
+ return value
1324
+
1325
+
1326
+ def _git_hash(value: Any, label: str) -> str:
1327
+ if not isinstance(value, str) or _HEX40.fullmatch(value) is None:
1328
+ raise DriverError("INVALID_MANIFEST", f"{label} must be a Git object ID")
1329
+ return value
1330
+
1331
+
1332
+ def _relative_path(value: Any, label: str) -> str:
1333
+ if not isinstance(value, str) or not value:
1334
+ raise DriverError("INVALID_MANIFEST", f"{label} must be a path")
1335
+ pure = PurePosixPath(value)
1336
+ if pure.is_absolute() or ".." in pure.parts or "." in pure.parts:
1337
+ raise DriverError("INVALID_MANIFEST", f"{label} is unsafe")
1338
+ return pure.as_posix()
1339
+
1340
+
1341
+ def _safe_file(root: Path, relative: str) -> Path:
1342
+ path = root.joinpath(*PurePosixPath(relative).parts)
1343
+ if path.is_symlink():
1344
+ raise DriverError("PATH_INVALID", f"symlink is forbidden: {relative}")
1345
+ resolved = path.resolve()
1346
+ try:
1347
+ resolved.relative_to(root.resolve())
1348
+ except ValueError as exc:
1349
+ raise DriverError("PATH_INVALID", f"path escapes root: {relative}") from exc
1350
+ if not resolved.is_file():
1351
+ raise DriverError("PATH_INVALID", f"required file is absent: {relative}")
1352
+ return resolved
1353
+
1354
+
1355
+ def _safe_absolute_file(path: Path) -> Path:
1356
+ if path.is_symlink() or not path.is_file():
1357
+ raise DriverError("PATH_INVALID", "router weights must be a regular file")
1358
+ return path
1359
+
1360
+
1361
+ def _load_json(path: Path) -> Mapping[str, Any]:
1362
+ try:
1363
+ value = json.loads(path.read_text(encoding="utf-8"))
1364
+ except (OSError, json.JSONDecodeError) as exc:
1365
+ raise DriverError("INVALID_MANIFEST", "manifest cannot be loaded") from exc
1366
+ if not isinstance(value, Mapping):
1367
+ raise DriverError("INVALID_MANIFEST", "manifest must be an object")
1368
+ return value
1369
+
1370
+
1371
+ def _file_sha256(path: Path) -> str:
1372
+ digest = hashlib.sha256()
1373
+ with path.open("rb") as stream:
1374
+ for chunk in iter(lambda: stream.read(1024 * 1024), b""):
1375
+ digest.update(chunk)
1376
+ return digest.hexdigest()
1377
+
1378
+
1379
+ def _path_closure_sha256(path: Path) -> str:
1380
+ """Hash one file or a symlink-free directory closure deterministically."""
1381
+
1382
+ resolved = path.resolve()
1383
+ if not resolved.exists() or path.is_symlink():
1384
+ raise DriverError("COMPONENT_CLOSURE_MISSING", "component closure path is unavailable")
1385
+ if resolved.is_file():
1386
+ return _file_sha256(resolved)
1387
+ if not resolved.is_dir():
1388
+ raise DriverError("COMPONENT_CLOSURE_MISSING", "component closure path is not file/dir")
1389
+ files: dict[str, str] = {}
1390
+ for candidate in sorted(resolved.rglob("*")):
1391
+ if candidate.is_symlink():
1392
+ raise DriverError(
1393
+ "COMPONENT_CLOSURE_INVALID",
1394
+ "component closure directories may not contain symlinks",
1395
+ )
1396
+ if candidate.is_file():
1397
+ files[candidate.relative_to(resolved).as_posix()] = _file_sha256(candidate)
1398
+ if not files:
1399
+ raise DriverError("COMPONENT_CLOSURE_MISSING", "component closure directory is empty")
1400
+ return _content_hash(files)
1401
+
1402
+
1403
+ def _content_hash(value: Any) -> str:
1404
+ payload = json.dumps(
1405
+ value,
1406
+ ensure_ascii=False,
1407
+ sort_keys=True,
1408
+ separators=(",", ":"),
1409
+ allow_nan=False,
1410
+ ).encode("utf-8")
1411
+ return hashlib.sha256(payload).hexdigest()
1412
+
1413
+
1414
+ def _git(root: Path, *args: str) -> str:
1415
+ completed = subprocess.run(
1416
+ ["git", "-C", str(root), *args],
1417
+ check=False,
1418
+ capture_output=True,
1419
+ text=True,
1420
+ timeout=15,
1421
+ )
1422
+ if completed.returncode != 0:
1423
+ raise DriverError("SOURCE_MISMATCH", "Git source verification failed")
1424
+ return completed.stdout.strip()
1425
+
1426
+
1427
+ def serve_jsonl(
1428
+ driver: AdaptiveRAGWorkerDriver,
1429
+ input_stream: TextIO = sys.stdin,
1430
+ output_stream: TextIO = sys.stdout,
1431
+ ) -> int:
1432
+ """Serve exactly one bounded JSON request per input line."""
1433
+
1434
+ for line in input_stream:
1435
+ if not line.strip():
1436
+ continue
1437
+ try:
1438
+ request = json.loads(line)
1439
+ response = driver.handle(request)
1440
+ except (json.JSONDecodeError, TypeError, ValueError):
1441
+ response = {
1442
+ "status": "error",
1443
+ "failure_code": "REQUEST_INVALID",
1444
+ "message": "request is not valid JSON",
1445
+ "consumed": False,
1446
+ }
1447
+ output_stream.write(
1448
+ json.dumps(response, sort_keys=True, separators=(",", ":"), allow_nan=False) + "\n"
1449
+ )
1450
+ output_stream.flush()
1451
+ return 0
1452
+
1453
+
1454
+ __all__ = [
1455
+ "EVENT_SCHEMA",
1456
+ "EVIDENCE_SCHEMA",
1457
+ "PROTOCOL_VERSION",
1458
+ "RELEASE_ID",
1459
+ "UPSTREAM_COMMIT",
1460
+ "UPSTREAM_TREE",
1461
+ "AdaptiveRAGWorkerDriver",
1462
+ "CompatibilityPolicy",
1463
+ "DriverError",
1464
+ "GenerationResult",
1465
+ "RetrievedDocument",
1466
+ "RouterResult",
1467
+ "RuntimeBundle",
1468
+ "RuntimeIdentity",
1469
+ "serve_jsonl",
1470
+ ]