proteus-evolve 0.2.0__tar.gz → 1.0.0__tar.gz

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 (429) hide show
  1. proteus_evolve-1.0.0/MANIFEST.in +4 -0
  2. proteus_evolve-1.0.0/PKG-INFO +399 -0
  3. proteus_evolve-1.0.0/README.md +364 -0
  4. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/__init__.py +1 -1
  5. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/adapters/aki.py +6 -5
  6. proteus_evolve-1.0.0/proteus/adapters/codex.py +678 -0
  7. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/adapters/dsh.py +188 -57
  8. proteus_evolve-1.0.0/proteus/adapters/dsh_resume.py +133 -0
  9. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/adapters/llm.py +65 -31
  10. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/adapters/minimal.py +42 -27
  11. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/adapters/pi.py +86 -37
  12. proteus_evolve-1.0.0/proteus/api/__init__.py +1 -0
  13. proteus_evolve-1.0.0/proteus/api/v1.py +51 -0
  14. proteus_evolve-1.0.0/proteus/artifacts/__init__.py +5 -0
  15. proteus_evolve-1.0.0/proteus/artifacts/codecs.py +199 -0
  16. proteus_evolve-1.0.0/proteus/artifacts/store.py +325 -0
  17. proteus_evolve-1.0.0/proteus/bench/_datasets.py +39 -0
  18. proteus_evolve-1.0.0/proteus/bench/_isolation.py +303 -0
  19. proteus_evolve-1.0.0/proteus/bench/humaneval.py +189 -0
  20. proteus_evolve-1.0.0/proteus/bench/mbpp.py +225 -0
  21. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/bench/sandbox.py +8 -3
  22. proteus_evolve-1.0.0/proteus/benchmarks/__init__.py +1 -0
  23. proteus_evolve-1.0.0/proteus/benchmarks/ace_formula.py +37 -0
  24. proteus_evolve-1.0.0/proteus/benchmarks/ace_formula_data.py +101 -0
  25. proteus_evolve-1.0.0/proteus/benchmarks/ace_formula_reference.py +39 -0
  26. proteus_evolve-1.0.0/proteus/benchmarks/aime.py +103 -0
  27. proteus_evolve-1.0.0/proteus/benchmarks/aime_data.py +115 -0
  28. proteus_evolve-1.0.0/proteus/benchmarks/aime_format.py +101 -0
  29. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/LICENSE-CORAL.txt +202 -0
  30. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/NOTICE.md +23 -0
  31. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/__init__.py +19 -0
  32. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/candidate.py +28 -0
  33. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/grader.reference.py +152 -0
  34. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/recipe.py +209 -0
  35. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/reference.json +38 -0
  36. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/report.py +220 -0
  37. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/research.py +101 -0
  38. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/seed.reference.py +95 -0
  39. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/task.reference.yaml +52 -0
  40. proteus_evolve-1.0.0/proteus/benchmarks/coral_circle_packing/verify.py +60 -0
  41. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/cli.py +154 -14
  42. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/core/__init__.py +8 -0
  43. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/core/adapter.py +40 -3
  44. proteus_evolve-1.0.0/proteus/core/budget.py +240 -0
  45. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/core/continuity.py +131 -14
  46. proteus_evolve-1.0.0/proteus/core/contracts.py +414 -0
  47. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/core/episode.py +335 -120
  48. proteus_evolve-1.0.0/proteus/core/episode_protocol.py +77 -0
  49. proteus_evolve-1.0.0/proteus/core/feedback.py +60 -0
  50. proteus_evolve-1.0.0/proteus/core/goal.py +335 -0
  51. proteus_evolve-1.0.0/proteus/core/ledger.py +307 -0
  52. proteus_evolve-1.0.0/proteus/core/methods.py +684 -0
  53. proteus_evolve-1.0.0/proteus/core/native_activation.py +87 -0
  54. proteus_evolve-1.0.0/proteus/core/native_budget.py +188 -0
  55. proteus_evolve-1.0.0/proteus/core/native_codex_usage.py +64 -0
  56. proteus_evolve-1.0.0/proteus/core/native_dsh_storage.py +122 -0
  57. proteus_evolve-1.0.0/proteus/core/native_dsh_usage.py +222 -0
  58. proteus_evolve-1.0.0/proteus/core/native_evaluators.py +57 -0
  59. proteus_evolve-1.0.0/proteus/core/native_inputs.py +151 -0
  60. proteus_evolve-1.0.0/proteus/core/native_pi_usage.py +176 -0
  61. proteus_evolve-1.0.0/proteus/core/native_usage.py +174 -0
  62. proteus_evolve-1.0.0/proteus/core/parallel.py +481 -0
  63. proteus_evolve-1.0.0/proteus/core/plugins.py +332 -0
  64. proteus_evolve-1.0.0/proteus/core/recovery.py +222 -0
  65. proteus_evolve-1.0.0/proteus/core/run_lock.py +36 -0
  66. proteus_evolve-1.0.0/proteus/core/search.py +314 -0
  67. proteus_evolve-1.0.0/proteus/core/serialization.py +255 -0
  68. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/core/snapshot.py +16 -0
  69. proteus_evolve-1.0.0/proteus/core/snapshot_store.py +105 -0
  70. proteus_evolve-1.0.0/proteus/core/timing.py +65 -0
  71. proteus_evolve-1.0.0/proteus/core/workflows.py +926 -0
  72. proteus_evolve-1.0.0/proteus/evaluation/__init__.py +1 -0
  73. proteus_evolve-1.0.0/proteus/evaluation/audit.py +146 -0
  74. proteus_evolve-1.0.0/proteus/evaluation/graders.py +157 -0
  75. proteus_evolve-1.0.0/proteus/evaluation/parallel.py +521 -0
  76. proteus_evolve-1.0.0/proteus/evaluation/records.py +128 -0
  77. proteus_evolve-1.0.0/proteus/evaluation/runners.py +241 -0
  78. proteus_evolve-1.0.0/proteus/evaluation/service.py +788 -0
  79. proteus_evolve-1.0.0/proteus/evaluation/study_timing.py +65 -0
  80. proteus_evolve-1.0.0/proteus/evaluation/tasks.py +117 -0
  81. proteus_evolve-1.0.0/proteus/events/__init__.py +5 -0
  82. proteus_evolve-1.0.0/proteus/events/policies.py +119 -0
  83. proteus_evolve-1.0.0/proteus/events/records.py +98 -0
  84. proteus_evolve-1.0.0/proteus/events/service.py +258 -0
  85. proteus_evolve-1.0.0/proteus/evidence/__init__.py +1 -0
  86. proteus_evolve-1.0.0/proteus/evidence/records.py +73 -0
  87. proteus_evolve-1.0.0/proteus/evidence/service.py +113 -0
  88. proteus_evolve-1.0.0/proteus/evidence/store.py +102 -0
  89. proteus_evolve-1.0.0/proteus/examples/_coral_worker_fixture.py +131 -0
  90. proteus_evolve-1.0.0/proteus/examples/_event_worker_fixture.py +78 -0
  91. proteus_evolve-1.0.0/proteus/examples/_gateway_worker_fixture.py +62 -0
  92. proteus_evolve-1.0.0/proteus/examples/_knowledge_worker_fixture.py +95 -0
  93. proteus_evolve-1.0.0/proteus/examples/_worker_protocol_fixture.py +39 -0
  94. proteus_evolve-1.0.0/proteus/examples/ace_formula.py +280 -0
  95. proteus_evolve-1.0.0/proteus/examples/ace_formula_audit.py +132 -0
  96. proteus_evolve-1.0.0/proteus/examples/ace_playbook.py +144 -0
  97. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/examples/adapter_template.py +20 -15
  98. proteus_evolve-1.0.0/proteus/examples/adaptive_workflows.py +232 -0
  99. proteus_evolve-1.0.0/proteus/examples/candidate_evaluation.py +74 -0
  100. proteus_evolve-1.0.0/proteus/examples/code_memory.py +83 -0
  101. proteus_evolve-1.0.0/proteus/examples/coding_workspace.py +141 -0
  102. proteus_evolve-1.0.0/proteus/examples/combee_ace.py +97 -0
  103. proteus_evolve-1.0.0/proteus/examples/combee_aggregation.py +261 -0
  104. proteus_evolve-1.0.0/proteus/examples/combee_formula.py +266 -0
  105. proteus_evolve-1.0.0/proteus/examples/combee_formula_audit.py +215 -0
  106. proteus_evolve-1.0.0/proteus/examples/combee_gepa.py +122 -0
  107. proteus_evolve-1.0.0/proteus/examples/coral_search.py +70 -0
  108. proteus_evolve-1.0.0/proteus/examples/evaluation_gateway.py +74 -0
  109. proteus_evolve-1.0.0/proteus/examples/event_interventions.py +77 -0
  110. proteus_evolve-1.0.0/proteus/examples/evidence_history.py +90 -0
  111. proteus_evolve-1.0.0/proteus/examples/gepa_aime.py +269 -0
  112. proteus_evolve-1.0.0/proteus/examples/gepa_prompt.py +110 -0
  113. proteus_evolve-1.0.0/proteus/examples/harbor_code_memory.py +37 -0
  114. proteus_evolve-1.0.0/proteus/examples/harbor_evaluation.py +118 -0
  115. proteus_evolve-1.0.0/proteus/examples/harbor_source_build.py +82 -0
  116. proteus_evolve-1.0.0/proteus/examples/harness_roles.py +101 -0
  117. proteus_evolve-1.0.0/proteus/examples/meta_harness.py +277 -0
  118. proteus_evolve-1.0.0/proteus/examples/meta_harness_fixture.py +202 -0
  119. proteus_evolve-1.0.0/proteus/examples/parallel_stages.py +128 -0
  120. proteus_evolve-1.0.0/proteus/examples/parent_selection.py +161 -0
  121. proteus_evolve-1.0.0/proteus/examples/search_policy.py +170 -0
  122. proteus_evolve-1.0.0/proteus/examples/search_policy_study.py +57 -0
  123. proteus_evolve-1.0.0/proteus/examples/self_evaluator_plugin.py +29 -0
  124. proteus_evolve-1.0.0/proteus/examples/shared_knowledge.py +92 -0
  125. proteus_evolve-1.0.0/proteus/examples/worker_knowledge.py +36 -0
  126. proteus_evolve-1.0.0/proteus/examples/worker_lifecycle.py +77 -0
  127. proteus_evolve-1.0.0/proteus/execution/__init__.py +1 -0
  128. proteus_evolve-1.0.0/proteus/execution/actors.py +301 -0
  129. proteus_evolve-1.0.0/proteus/execution/builds.py +247 -0
  130. proteus_evolve-1.0.0/proteus/execution/code_records.py +76 -0
  131. proteus_evolve-1.0.0/proteus/execution/code_rpc.py +186 -0
  132. proteus_evolve-1.0.0/proteus/execution/code_service.py +118 -0
  133. proteus_evolve-1.0.0/proteus/execution/code_subject.py +62 -0
  134. proteus_evolve-1.0.0/proteus/execution/code_worker.py +131 -0
  135. proteus_evolve-1.0.0/proteus/execution/filesystem_policy.py +117 -0
  136. proteus_evolve-1.0.0/proteus/execution/harbor.py +415 -0
  137. proteus_evolve-1.0.0/proteus/execution/harbor_code.py +117 -0
  138. proteus_evolve-1.0.0/proteus/execution/harbor_code_worker.py +315 -0
  139. proteus_evolve-1.0.0/proteus/execution/harbor_worker.py +333 -0
  140. proteus_evolve-1.0.0/proteus/execution/harness_candidate.py +189 -0
  141. proteus_evolve-1.0.0/proteus/execution/harness_evolution.py +109 -0
  142. proteus_evolve-1.0.0/proteus/execution/harness_usage.py +53 -0
  143. proteus_evolve-1.0.0/proteus/execution/harnesses.py +157 -0
  144. proteus_evolve-1.0.0/proteus/execution/workspace.py +92 -0
  145. proteus_evolve-1.0.0/proteus/execution/workspace_records.py +59 -0
  146. proteus_evolve-1.0.0/proteus/gateway/__init__.py +1 -0
  147. proteus_evolve-1.0.0/proteus/gateway/client.py +97 -0
  148. proteus_evolve-1.0.0/proteus/gateway/knowledge.py +107 -0
  149. proteus_evolve-1.0.0/proteus/gateway/records.py +95 -0
  150. proteus_evolve-1.0.0/proteus/gateway/service.py +188 -0
  151. proteus_evolve-1.0.0/proteus/gateway/store.py +235 -0
  152. proteus_evolve-1.0.0/proteus/gateway/transport.py +131 -0
  153. proteus_evolve-1.0.0/proteus/knowledge/__init__.py +6 -0
  154. proteus_evolve-1.0.0/proteus/knowledge/client.py +56 -0
  155. proteus_evolve-1.0.0/proteus/knowledge/records.py +91 -0
  156. proteus_evolve-1.0.0/proteus/knowledge/service.py +120 -0
  157. proteus_evolve-1.0.0/proteus/knowledge/store.py +276 -0
  158. proteus_evolve-1.0.0/proteus/measure/artifacts.py +200 -0
  159. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/measure/distance.py +0 -9
  160. proteus_evolve-1.0.0/proteus/methods/__init__.py +1 -0
  161. proteus_evolve-1.0.0/proteus/methods/ace/LICENSE-ACE.txt +201 -0
  162. proteus_evolve-1.0.0/proteus/methods/ace/NOTICE.md +42 -0
  163. proteus_evolve-1.0.0/proteus/methods/ace/__init__.py +1 -0
  164. proteus_evolve-1.0.0/proteus/methods/ace/batch.py +678 -0
  165. proteus_evolve-1.0.0/proteus/methods/ace/method.py +319 -0
  166. proteus_evolve-1.0.0/proteus/methods/ace/parsing.py +326 -0
  167. proteus_evolve-1.0.0/proteus/methods/ace/playbook.py +165 -0
  168. proteus_evolve-1.0.0/proteus/methods/ace/prompts.py +15 -0
  169. proteus_evolve-1.0.0/proteus/methods/ace/roles.py +172 -0
  170. proteus_evolve-1.0.0/proteus/methods/ace/upstream.py +319 -0
  171. proteus_evolve-1.0.0/proteus/methods/combee_gepa.py +143 -0
  172. proteus_evolve-1.0.0/proteus/methods/compare.py +74 -0
  173. proteus_evolve-1.0.0/proteus/methods/coral/LICENSE-CORAL.txt +202 -0
  174. proteus_evolve-1.0.0/proteus/methods/coral/NOTICE.md +26 -0
  175. proteus_evolve-1.0.0/proteus/methods/coral/__init__.py +1 -0
  176. proteus_evolve-1.0.0/proteus/methods/coral/_reference_heartbeat.py +205 -0
  177. proteus_evolve-1.0.0/proteus/methods/coral/consolidate.reference.md +47 -0
  178. proteus_evolve-1.0.0/proteus/methods/coral/method.py +193 -0
  179. proteus_evolve-1.0.0/proteus/methods/coral/pivot.reference.md +68 -0
  180. proteus_evolve-1.0.0/proteus/methods/coral/policy.py +58 -0
  181. proteus_evolve-1.0.0/proteus/methods/coral/records.py +62 -0
  182. proteus_evolve-1.0.0/proteus/methods/coral/reflect.reference.md +45 -0
  183. proteus_evolve-1.0.0/proteus/methods/coral/report.py +497 -0
  184. proteus_evolve-1.0.0/proteus/methods/gepa/__init__.py +5 -0
  185. proteus_evolve-1.0.0/proteus/methods/gepa/dynamic_sampling.py +111 -0
  186. proteus_evolve-1.0.0/proteus/methods/gepa/method.py +491 -0
  187. proteus_evolve-1.0.0/proteus/methods/gepa/reference.py +33 -0
  188. proteus_evolve-1.0.0/proteus/methods/gepa/sampling.py +105 -0
  189. proteus_evolve-1.0.0/proteus/methods/gepa/search.py +93 -0
  190. proteus_evolve-1.0.0/proteus/methods/gepa/state.py +178 -0
  191. proteus_evolve-1.0.0/proteus/methods/meta_harness/LICENSE-META-HARNESS.txt +21 -0
  192. proteus_evolve-1.0.0/proteus/methods/meta_harness/NOTICE.md +5 -0
  193. proteus_evolve-1.0.0/proteus/methods/meta_harness/PROPOSER.md +139 -0
  194. proteus_evolve-1.0.0/proteus/methods/meta_harness/__init__.py +0 -0
  195. proteus_evolve-1.0.0/proteus/methods/meta_harness/benchmark.py +181 -0
  196. proteus_evolve-1.0.0/proteus/methods/meta_harness/data.py +84 -0
  197. proteus_evolve-1.0.0/proteus/methods/meta_harness/entry.py +38 -0
  198. proteus_evolve-1.0.0/proteus/methods/meta_harness/grading.py +58 -0
  199. proteus_evolve-1.0.0/proteus/methods/meta_harness/method.py +478 -0
  200. proteus_evolve-1.0.0/proteus/methods/meta_harness/records.py +171 -0
  201. proteus_evolve-1.0.0/proteus/methods/meta_harness/reference/__init__.py +0 -0
  202. proteus_evolve-1.0.0/proteus/methods/meta_harness/reference/agents/__init__.py +0 -0
  203. proteus_evolve-1.0.0/proteus/methods/meta_harness/reference/agents/fewshot_all.py +11 -0
  204. proteus_evolve-1.0.0/proteus/methods/meta_harness/reference/agents/fewshot_memory.py +125 -0
  205. proteus_evolve-1.0.0/proteus/methods/meta_harness/reference/agents/no_memory.py +40 -0
  206. proteus_evolve-1.0.0/proteus/methods/meta_harness/reference/data/__init__.py +0 -0
  207. proteus_evolve-1.0.0/proteus/methods/meta_harness/reference/data/constants.py +236 -0
  208. proteus_evolve-1.0.0/proteus/methods/meta_harness/reference/data/evaluators.py +189 -0
  209. proteus_evolve-1.0.0/proteus/methods/meta_harness/reference/data/loaders.py +206 -0
  210. proteus_evolve-1.0.0/proteus/methods/meta_harness/reference/llm.py +8 -0
  211. proteus_evolve-1.0.0/proteus/methods/meta_harness/reference/memory_system.py +127 -0
  212. proteus_evolve-1.0.0/proteus/methods/meta_harness/report.py +369 -0
  213. proteus_evolve-1.0.0/proteus/methods/native.py +136 -0
  214. proteus_evolve-1.0.0/proteus/methods/native_evolution.py +205 -0
  215. proteus_evolve-1.0.0/proteus/methods/sequence.py +112 -0
  216. proteus_evolve-1.0.0/proteus/operators/__init__.py +1 -0
  217. proteus_evolve-1.0.0/proteus/operators/combee/LICENSE-GEPA.txt +7 -0
  218. proteus_evolve-1.0.0/proteus/operators/combee/NOTICE.md +34 -0
  219. proteus_evolve-1.0.0/proteus/operators/combee/__init__.py +19 -0
  220. proteus_evolve-1.0.0/proteus/operators/combee/_gepa/__init__.py +1 -0
  221. proteus_evolve-1.0.0/proteus/operators/combee/_gepa/base.py +113 -0
  222. proteus_evolve-1.0.0/proteus/operators/combee/_gepa/combee.py +762 -0
  223. proteus_evolve-1.0.0/proteus/operators/combee/_gepa/instruction.py +245 -0
  224. proteus_evolve-1.0.0/proteus/operators/combee/ace.py +176 -0
  225. proteus_evolve-1.0.0/proteus/operators/combee/batching.py +164 -0
  226. proteus_evolve-1.0.0/proteus/operators/combee/gepa.py +146 -0
  227. proteus_evolve-1.0.0/proteus/operators/combee/grouping.py +104 -0
  228. proteus_evolve-1.0.0/proteus/operators/combee/managed.py +104 -0
  229. proteus_evolve-1.0.0/proteus/operators/combee/reference.json +25 -0
  230. proteus_evolve-1.0.0/proteus/recipes/__init__.py +10 -0
  231. proteus_evolve-1.0.0/proteus/recipes/builtins.py +251 -0
  232. proteus_evolve-1.0.0/proteus/recipes/catalog.py +133 -0
  233. proteus_evolve-1.0.0/proteus/recipes/cli.py +173 -0
  234. proteus_evolve-1.0.0/proteus/recipes/config.py +434 -0
  235. proteus_evolve-1.0.0/proteus/recipes/controller_timing.py +140 -0
  236. proteus_evolve-1.0.0/proteus/recipes/export.py +472 -0
  237. proteus_evolve-1.0.0/proteus/recipes/manifest.py +119 -0
  238. proteus_evolve-1.0.0/proteus/recipes/runner.py +142 -0
  239. proteus_evolve-1.0.0/proteus/recipes/scaffolding.py +34 -0
  240. proteus_evolve-1.0.0/proteus/recipes/study.py +233 -0
  241. proteus_evolve-1.0.0/proteus/recipes/templates/README.md.tmpl +58 -0
  242. proteus_evolve-1.0.0/proteus/recipes/templates/__init__.py +1 -0
  243. proteus_evolve-1.0.0/proteus/recipes/templates/check.py.tmpl +143 -0
  244. proteus_evolve-1.0.0/proteus/recipes/templates/evaluator.py.tmpl +53 -0
  245. proteus_evolve-1.0.0/proteus/recipes/templates/method.py.tmpl +74 -0
  246. proteus_evolve-1.0.0/proteus/recipes/templates/policy.py.tmpl +25 -0
  247. proteus_evolve-1.0.0/proteus/recipes/templates/policy_check.py.tmpl +53 -0
  248. proteus_evolve-1.0.0/proteus/recipes/templates/policy_prepare.py.tmpl +22 -0
  249. proteus_evolve-1.0.0/proteus/recipes/templates/prepare.py.tmpl +104 -0
  250. proteus_evolve-1.0.0/proteus/recipes/templates/stage.py.tmpl +51 -0
  251. proteus_evolve-1.0.0/proteus/recipes/templates/subject.py.tmpl +77 -0
  252. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/report.py +1 -1
  253. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/sandbox/docker.py +82 -38
  254. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/sweep.py +73 -3
  255. proteus_evolve-1.0.0/proteus/visualize/__init__.py +5 -0
  256. proteus_evolve-1.0.0/proteus/visualize/config.py +174 -0
  257. proteus_evolve-1.0.0/proteus/visualize/data.py +632 -0
  258. proteus_evolve-1.0.0/proteus/visualize/server.py +204 -0
  259. proteus_evolve-1.0.0/proteus/visualize/static/__init__.py +1 -0
  260. proteus_evolve-1.0.0/proteus/visualize/static/app.js +315 -0
  261. proteus_evolve-1.0.0/proteus/visualize/static/index.html +126 -0
  262. proteus_evolve-1.0.0/proteus/visualize/static/model.js +41 -0
  263. proteus_evolve-1.0.0/proteus/visualize/static/package.json +1 -0
  264. proteus_evolve-1.0.0/proteus/visualize/static/styles.css +45 -0
  265. proteus_evolve-1.0.0/proteus/workers/__init__.py +6 -0
  266. proteus_evolve-1.0.0/proteus/workers/codex.py +44 -0
  267. proteus_evolve-1.0.0/proteus/workers/codex_bridge.py +194 -0
  268. proteus_evolve-1.0.0/proteus/workers/container_worker.py +35 -0
  269. proteus_evolve-1.0.0/proteus/workers/controller.py +143 -0
  270. proteus_evolve-1.0.0/proteus/workers/harbor.py +98 -0
  271. proteus_evolve-1.0.0/proteus/workers/harbor_bridge.py +307 -0
  272. proteus_evolve-1.0.0/proteus/workers/records.py +126 -0
  273. proteus_evolve-1.0.0/proteus/workers/runtime.py +135 -0
  274. proteus_evolve-1.0.0/proteus/workers/seeding.py +76 -0
  275. proteus_evolve-1.0.0/proteus/workers/service.py +111 -0
  276. proteus_evolve-1.0.0/proteus/workers/supervisor.py +212 -0
  277. proteus_evolve-1.0.0/proteus_evolve.egg-info/PKG-INFO +399 -0
  278. proteus_evolve-1.0.0/proteus_evolve.egg-info/SOURCES.txt +422 -0
  279. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus_evolve.egg-info/requires.txt +1 -0
  280. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/pyproject.toml +13 -1
  281. proteus_evolve-1.0.0/recipes/examples/p01-contract.toml +59 -0
  282. proteus_evolve-1.0.0/recipes/examples/self-evaluation.toml +43 -0
  283. proteus_evolve-1.0.0/recipes/examples/stages.toml +29 -0
  284. proteus_evolve-1.0.0/recipes/native/minimal.toml +17 -0
  285. proteus_evolve-1.0.0/recipes/native/shared-evaluation/README.md +51 -0
  286. proteus_evolve-1.0.0/recipes/native/shared-evaluation/prepare.py +70 -0
  287. proteus_evolve-1.0.0/tests/test_benchmark_isolation.py +243 -0
  288. proteus_evolve-1.0.0/tests/test_canary_diagnostics.py +53 -0
  289. proteus_evolve-1.0.0/tests/test_codex_adapter.py +573 -0
  290. proteus_evolve-1.0.0/tests/test_codex_pilot_reuse.py +73 -0
  291. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/tests/test_continuity.py +35 -0
  292. proteus_evolve-1.0.0/tests/test_custom_phases.py +83 -0
  293. proteus_evolve-1.0.0/tests/test_datasets.py +99 -0
  294. proteus_evolve-1.0.0/tests/test_dsh_controller_resume.py +123 -0
  295. proteus_evolve-1.0.0/tests/test_dsh_phase_resume.py +189 -0
  296. proteus_evolve-1.0.0/tests/test_envs.py +112 -0
  297. proteus_evolve-1.0.0/tests/test_episode_protocol.py +101 -0
  298. proteus_evolve-1.0.0/tests/test_evaluator_controls.py +179 -0
  299. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/tests/test_goals.py +32 -0
  300. proteus_evolve-1.0.0/tests/test_harness_full_response.py +104 -0
  301. proteus_evolve-1.0.0/tests/test_humaneval.py +149 -0
  302. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/tests/test_instrument.py +52 -0
  303. proteus_evolve-1.0.0/tests/test_live_harness_pilot.py +113 -0
  304. proteus_evolve-1.0.0/tests/test_mbpp.py +209 -0
  305. proteus_evolve-1.0.0/tests/test_native_activation.py +186 -0
  306. proteus_evolve-1.0.0/tests/test_native_budget.py +291 -0
  307. proteus_evolve-1.0.0/tests/test_native_codex_usage.py +197 -0
  308. proteus_evolve-1.0.0/tests/test_native_dsh_storage.py +94 -0
  309. proteus_evolve-1.0.0/tests/test_native_dsh_usage.py +293 -0
  310. proteus_evolve-1.0.0/tests/test_native_evaluator_usage.py +171 -0
  311. proteus_evolve-1.0.0/tests/test_native_inputs.py +195 -0
  312. proteus_evolve-1.0.0/tests/test_native_pi_usage.py +182 -0
  313. proteus_evolve-1.0.0/tests/test_native_source_gate.py +82 -0
  314. proteus_evolve-1.0.0/tests/test_native_source_repair.py +161 -0
  315. proteus_evolve-1.0.0/tests/test_native_usage.py +243 -0
  316. proteus_evolve-1.0.0/tests/test_publish_gate.py +149 -0
  317. proteus_evolve-1.0.0/tests/test_release_smoke.py +187 -0
  318. proteus_evolve-1.0.0/tests/test_release_smoke_diagnostics.py +303 -0
  319. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/tests/test_selfcode.py +240 -17
  320. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/tests/test_smoke.py +4 -2
  321. proteus_evolve-1.0.0/tests/test_v1_ace_formula.py +281 -0
  322. proteus_evolve-1.0.0/tests/test_v1_ace_method.py +268 -0
  323. proteus_evolve-1.0.0/tests/test_v1_ace_playbook.py +259 -0
  324. proteus_evolve-1.0.0/tests/test_v1_artifact_measurements.py +149 -0
  325. proteus_evolve-1.0.0/tests/test_v1_artifacts.py +363 -0
  326. proteus_evolve-1.0.0/tests/test_v1_backend_evaluation.py +116 -0
  327. proteus_evolve-1.0.0/tests/test_v1_chat_accounting.py +154 -0
  328. proteus_evolve-1.0.0/tests/test_v1_code_protocol.py +399 -0
  329. proteus_evolve-1.0.0/tests/test_v1_codex_worker.py +218 -0
  330. proteus_evolve-1.0.0/tests/test_v1_combee_ace_method.py +723 -0
  331. proteus_evolve-1.0.0/tests/test_v1_combee_aggregation.py +395 -0
  332. proteus_evolve-1.0.0/tests/test_v1_combee_baselines.py +79 -0
  333. proteus_evolve-1.0.0/tests/test_v1_combee_formula.py +211 -0
  334. proteus_evolve-1.0.0/tests/test_v1_combee_gepa.py +464 -0
  335. proteus_evolve-1.0.0/tests/test_v1_combee_shared_trace.py +105 -0
  336. proteus_evolve-1.0.0/tests/test_v1_contracts.py +354 -0
  337. proteus_evolve-1.0.0/tests/test_v1_controller_timing.py +152 -0
  338. proteus_evolve-1.0.0/tests/test_v1_coral_circle_packing.py +208 -0
  339. proteus_evolve-1.0.0/tests/test_v1_coral_directed_qualification.py +255 -0
  340. proteus_evolve-1.0.0/tests/test_v1_coral_harbor_study.py +209 -0
  341. proteus_evolve-1.0.0/tests/test_v1_coral_method.py +281 -0
  342. proteus_evolve-1.0.0/tests/test_v1_coral_reference.py +75 -0
  343. proteus_evolve-1.0.0/tests/test_v1_coral_report.py +183 -0
  344. proteus_evolve-1.0.0/tests/test_v1_dynamic_batching.py +376 -0
  345. proteus_evolve-1.0.0/tests/test_v1_evaluation.py +552 -0
  346. proteus_evolve-1.0.0/tests/test_v1_events.py +372 -0
  347. proteus_evolve-1.0.0/tests/test_v1_evidence.py +307 -0
  348. proteus_evolve-1.0.0/tests/test_v1_filesystem_policy.py +139 -0
  349. proteus_evolve-1.0.0/tests/test_v1_gateway.py +178 -0
  350. proteus_evolve-1.0.0/tests/test_v1_gateway_closure.py +80 -0
  351. proteus_evolve-1.0.0/tests/test_v1_gateway_harbor.py +125 -0
  352. proteus_evolve-1.0.0/tests/test_v1_gateway_recovery.py +206 -0
  353. proteus_evolve-1.0.0/tests/test_v1_gepa_aime.py +276 -0
  354. proteus_evolve-1.0.0/tests/test_v1_gepa_method.py +403 -0
  355. proteus_evolve-1.0.0/tests/test_v1_gepa_search.py +299 -0
  356. proteus_evolve-1.0.0/tests/test_v1_harbor.py +188 -0
  357. proteus_evolve-1.0.0/tests/test_v1_harbor_code.py +400 -0
  358. proteus_evolve-1.0.0/tests/test_v1_harbor_workers.py +321 -0
  359. proteus_evolve-1.0.0/tests/test_v1_harness_accounting.py +256 -0
  360. proteus_evolve-1.0.0/tests/test_v1_harness_candidates.py +182 -0
  361. proteus_evolve-1.0.0/tests/test_v1_harness_compatibility.py +38 -0
  362. proteus_evolve-1.0.0/tests/test_v1_harness_integrations.py +175 -0
  363. proteus_evolve-1.0.0/tests/test_v1_harness_methods.py +386 -0
  364. proteus_evolve-1.0.0/tests/test_v1_knowledge.py +281 -0
  365. proteus_evolve-1.0.0/tests/test_v1_knowledge_service.py +191 -0
  366. proteus_evolve-1.0.0/tests/test_v1_ledger.py +402 -0
  367. proteus_evolve-1.0.0/tests/test_v1_meta_harness.py +375 -0
  368. proteus_evolve-1.0.0/tests/test_v1_meta_reference.py +223 -0
  369. proteus_evolve-1.0.0/tests/test_v1_model_evaluators.py +220 -0
  370. proteus_evolve-1.0.0/tests/test_v1_packing_report.py +86 -0
  371. proteus_evolve-1.0.0/tests/test_v1_parallel.py +476 -0
  372. proteus_evolve-1.0.0/tests/test_v1_parallel_evaluation.py +670 -0
  373. proteus_evolve-1.0.0/tests/test_v1_parallel_model_evaluators.py +187 -0
  374. proteus_evolve-1.0.0/tests/test_v1_plugin_scaffolds.py +79 -0
  375. proteus_evolve-1.0.0/tests/test_v1_plugins.py +537 -0
  376. proteus_evolve-1.0.0/tests/test_v1_public_api.py +107 -0
  377. proteus_evolve-1.0.0/tests/test_v1_recipe_catalog.py +135 -0
  378. proteus_evolve-1.0.0/tests/test_v1_reconciliation.py +311 -0
  379. proteus_evolve-1.0.0/tests/test_v1_recovery.py +403 -0
  380. proteus_evolve-1.0.0/tests/test_v1_release_contracts.py +150 -0
  381. proteus_evolve-1.0.0/tests/test_v1_release_recovery.py +313 -0
  382. proteus_evolve-1.0.0/tests/test_v1_result_export.py +197 -0
  383. proteus_evolve-1.0.0/tests/test_v1_search.py +345 -0
  384. proteus_evolve-1.0.0/tests/test_v1_snapshot_store.py +77 -0
  385. proteus_evolve-1.0.0/tests/test_v1_source_build.py +263 -0
  386. proteus_evolve-1.0.0/tests/test_v1_study_comparison.py +128 -0
  387. proteus_evolve-1.0.0/tests/test_v1_subject_inputs.py +96 -0
  388. proteus_evolve-1.0.0/tests/test_v1_timing.py +100 -0
  389. proteus_evolve-1.0.0/tests/test_v1_worker_knowledge.py +210 -0
  390. proteus_evolve-1.0.0/tests/test_v1_worker_seed.py +119 -0
  391. proteus_evolve-1.0.0/tests/test_v1_worker_service.py +146 -0
  392. proteus_evolve-1.0.0/tests/test_v1_workers.py +311 -0
  393. proteus_evolve-1.0.0/tests/test_v1_workflows.py +1149 -0
  394. proteus_evolve-1.0.0/tests/test_v1_workspace.py +411 -0
  395. proteus_evolve-1.0.0/tests/test_visualize.py +318 -0
  396. proteus_evolve-0.2.0/PKG-INFO +0 -356
  397. proteus_evolve-0.2.0/README.md +0 -322
  398. proteus_evolve-0.2.0/proteus/core/goal.py +0 -221
  399. proteus_evolve-0.2.0/proteus_evolve.egg-info/PKG-INFO +0 -356
  400. proteus_evolve-0.2.0/proteus_evolve.egg-info/SOURCES.txt +0 -57
  401. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/LICENSE +0 -0
  402. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/adapters/__init__.py +0 -0
  403. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/adapters/instructions.py +0 -0
  404. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/bench/__init__.py +0 -0
  405. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/bench/local.py +0 -0
  406. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/bench/polyglot.py +0 -0
  407. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/bench/swe.py +0 -0
  408. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/bench/task.py +0 -0
  409. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/core/disposition.py +0 -0
  410. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/core/evaluators.py +0 -0
  411. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/envs.py +0 -0
  412. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/examples/__init__.py +0 -0
  413. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/examples/benchmark_template.py +0 -0
  414. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/examples/no_goal_vs_review.py +0 -0
  415. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/measure/__init__.py +0 -0
  416. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/measure/audit.py +0 -0
  417. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/measure/crystallize.py +0 -0
  418. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/measure/stream.py +0 -0
  419. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/sandbox/__init__.py +0 -0
  420. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/scaffold.py +0 -0
  421. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus/testing.py +0 -0
  422. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus_evolve.egg-info/dependency_links.txt +0 -0
  423. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus_evolve.egg-info/entry_points.txt +0 -0
  424. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/proteus_evolve.egg-info/top_level.txt +0 -0
  425. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/setup.cfg +0 -0
  426. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/tests/test_aki_adapter.py +0 -0
  427. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/tests/test_bench.py +0 -0
  428. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/tests/test_conformance.py +0 -0
  429. {proteus_evolve-0.2.0 → proteus_evolve-1.0.0}/tests/test_polyglot.py +0 -0
@@ -0,0 +1,4 @@
1
+ include recipes/examples/p01-contract.toml
2
+ recursive-include recipes *.toml
3
+ include recipes/native/shared-evaluation/prepare.py
4
+ include recipes/native/shared-evaluation/README.md
@@ -0,0 +1,399 @@
1
+ Metadata-Version: 2.4
2
+ Name: proteus-evolve
3
+ Version: 1.0.0
4
+ Summary: A harness-agnostic driver for measuring agent self-evolution: plug in any harness × model, evolve it under goal or no-goal conditions, and measure how the harness changes.
5
+ Author: Proteus Authors
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://proteus-evolve.github.io/
8
+ Project-URL: Repository, https://github.com/proteus-evolve/Proteus
9
+ Project-URL: Documentation, https://github.com/proteus-evolve/Proteus/tree/main/docs
10
+ Project-URL: Issues, https://github.com/proteus-evolve/Proteus/issues
11
+ Keywords: agents,self-evolution,harness,llm,self-improving
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: tomli>=2.0; python_version < "3.11"
25
+ Provides-Extra: llm
26
+ Provides-Extra: sandbox
27
+ Provides-Extra: dsh
28
+ Requires-Dist: zstandard>=0.21; python_version < "3.14" and extra == "dsh"
29
+ Provides-Extra: pi
30
+ Provides-Extra: dev
31
+ Requires-Dist: pytest>=7.0; extra == "dev"
32
+ Requires-Dist: ruff==0.14.14; extra == "dev"
33
+ Requires-Dist: jsonschema>=4.18; extra == "dev"
34
+ Dynamic: license-file
35
+
36
+ <p align="center">
37
+ <img src="docs/assets/proteus-logo.png" alt="Proteus logo" width="340">
38
+ </p>
39
+
40
+ <h3 align="center">Harness-agnostic agent self-improvement.</h3>
41
+
42
+ <p align="center">
43
+ <b>Bring your harness. Compose the method. Evaluate and visualize the evolution.</b>
44
+ </p>
45
+
46
+ <p align="center">
47
+ <a href="https://github.com/proteus-evolve/Proteus/actions/workflows/ci.yml"><img src="https://github.com/proteus-evolve/Proteus/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
48
+ <a href="https://github.com/proteus-evolve/Proteus/actions/workflows/release-smoke.yml"><img src="https://github.com/proteus-evolve/Proteus/actions/workflows/release-smoke.yml/badge.svg" alt="release smoke"></a>
49
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License"></a>
50
+ <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+">
51
+ <img src="https://img.shields.io/badge/version-1.0.0-informational.svg" alt="Source version 1.0.0">
52
+ </p>
53
+
54
+ <p align="center">
55
+ <a href="#use-proteus-with-your-agent">Agent Skills</a> •
56
+ <a href="#recipe-quick-start">Quick Start</a> •
57
+ <a href="#harness-agnostic-by-design">Harnesses</a> •
58
+ <a href="#method-families">Methods & Composition</a> •
59
+ <a href="#evaluation-as-part-of-the-experiment">Evaluators</a> •
60
+ <a href="#visualize-the-evolution">Visualization</a> •
61
+ <a href="recipes/README.md">Experiments</a> •
62
+ <a href="docs/technical-report/proteus-tech-report.pdf">Technical Report</a> •
63
+ <a href="#documentation">Docs</a>
64
+ </p>
65
+
66
+ ---
67
+
68
+ **Proteus is a modular framework for building and studying self-improving agents.**
69
+ Optimize prompts, memory, skills or harness source code while keeping the optimization
70
+ method, agent runtime and evaluation protocol independently configurable.
71
+
72
+ **Technical report (PDF):** [Proteus: A Modular Framework for Agent Self-Improvement](docs/technical-report/proteus-tech-report.pdf).
73
+
74
+ - **Harness-agnostic:** use Pi, DeepSeek Harness, Codex, an HTTP model adapter, or
75
+ your own integration in supported roles. The agent proposing changes and the
76
+ agent executing the candidate can use different harnesses and models.
77
+ - **Composable methods:** reuse stages, search policies, parallel aggregation and
78
+ worker infrastructure. Included combinations span Combee + ACE, Combee + GEPA,
79
+ and explicit self-evaluation stages.
80
+ - **Flexible evaluation:** combine task verifiers, model judges, visible feedback,
81
+ hidden tests and agent self-assessment, with explicit control over which evidence
82
+ can guide the next update.
83
+ - **Visual evolution:** replay Native sweeps, compare trajectories, inspect candidate
84
+ changes and evaluator scores, and export recipe results for further analysis.
85
+
86
+ > The quick start installs Proteus 1.0 from `main`. See the
87
+ > [release notes](docs/releases/v1.0.0.md) for the version scope and
88
+ > [GitHub releases](https://github.com/proteus-evolve/Proteus/releases) for published versions.
89
+
90
+ <p align="center">
91
+ <b>Watch a Native evolution replay.</b><br>
92
+ <a href="https://proteus-evolve.github.io/">Explore the interactive demo →</a>
93
+ </p>
94
+
95
+ https://github.com/user-attachments/assets/63311c1e-1ad9-4821-81b4-044cf5bf4650
96
+
97
+ ## Use Proteus with your agent
98
+
99
+ Give your coding agent the goal; let it configure the harnesses, method and evaluators,
100
+ run the experiment, then explain the evidence. Proteus includes two companion
101
+ **Agent Skills** in this repository:
102
+
103
+ | Skill | Use it to |
104
+ | --- | --- |
105
+ | [`proteus-use`](skills/proteus-use/SKILL.md) | Choose or compose a method, bind harness roles, configure evaluation, run/resume experiments, export results and visualize Native sweeps |
106
+ | [`proteus-contribute`](skills/proteus-contribute/SKILL.md) | Extend methods, stages, harnesses, evaluators and other framework components through the public contracts; validate and prepare a contribution |
107
+
108
+ The contribution skill is **optional guidance**, not a requirement for submitting
109
+ a PR. Both skills use `SKILL.md` instructions, with optional Codex display metadata;
110
+ the workflows are not tied to Codex as the experiment's harness.
111
+
112
+ ### Install and invoke a skill
113
+
114
+ In Codex, ask the built-in skill installer to install the usage skill from `main`:
115
+
116
+ ```text
117
+ $skill-installer install the skill at skills/proteus-use from
118
+ proteus-evolve/Proteus, ref main.
119
+ ```
120
+
121
+ For framework development, install `skills/proteus-contribute` the same way.
122
+ After installation, select the skill or invoke it by name. See the
123
+ [Codex skill documentation](https://learn.chatgpt.com/docs/build-skills) for local
124
+ discovery and installation behavior.
125
+
126
+ With another agent, copy the selected skill folder into that agent's supported
127
+ skills directory. An agent that can read files and run shell commands can also
128
+ read `skills/proteus-use/SKILL.md` directly from a Proteus checkout. The skills
129
+ are distributed through Git, separately from the Python wheel; use the same
130
+ tag or commit as your Proteus checkout. Install the Python package using the
131
+ [quick start](#recipe-quick-start) below, or ask your agent to do so.
132
+
133
+ Try this first:
134
+
135
+ ```text
136
+ Use $proteus-use to set up Proteus and run its offline candidate-comparison
137
+ example. Check recovery, export the results, then create a small Native demo
138
+ and open the visualization. Use no API calls or Docker.
139
+ ```
140
+
141
+ For an experiment with your own agent:
142
+
143
+ ```text
144
+ Use $proteus-use to improve my harness on the attached tasks. Compare Native
145
+ self-evolution with a compatible method using a separate coding proposer.
146
+ Keep the same visible/hidden split and external evaluator, explain which
147
+ combinations are supported, and prepare a minimal pilot for each. Show me
148
+ the exact recipes and resource estimates before starting paid runs.
149
+ ```
150
+
151
+ For a contribution:
152
+
153
+ ```text
154
+ Use $proteus-contribute to add a typed self-evaluation stage as an external
155
+ plugin. Demonstrate that a later stage consumes its output, keep the external
156
+ task score separate, and run the scaffold's offline checks.
157
+ ```
158
+
159
+ ## Recipe quick start
160
+
161
+ Install Proteus 1.0 from `main` with Python 3.10 or newer:
162
+
163
+ ```bash
164
+ git clone --branch main https://github.com/proteus-evolve/Proteus.git
165
+ cd Proteus
166
+ python3 -m venv .venv
167
+ source .venv/bin/activate
168
+ python -m pip install -e .
169
+ proteus recipe catalog
170
+ ```
171
+
172
+ Run an offline candidate-comparison recipe. It needs **no API key or Docker**:
173
+
174
+ ```bash
175
+ PROTEUS_EXAMPLE="$(mktemp -d)/comparison"
176
+ proteus recipe example candidate-comparison --out "$PROTEUS_EXAMPLE"
177
+ proteus recipe check "$PROTEUS_EXAMPLE/recipe.json"
178
+ proteus recipe lock "$PROTEUS_EXAMPLE/recipe.json" \
179
+ --source "proteus=$PWD" --out "$PROTEUS_EXAMPLE/lock.json"
180
+ proteus recipe run "$PROTEUS_EXAMPLE/recipe.json" \
181
+ --lock "$PROTEUS_EXAMPLE/lock.json" \
182
+ --artifact-store "$PROTEUS_EXAMPLE/artifact-store" --out "$PROTEUS_EXAMPLE/run"
183
+ proteus recipe resume "$PROTEUS_EXAMPLE/recipe.json" \
184
+ --lock "$PROTEUS_EXAMPLE/lock.json" --out "$PROTEUS_EXAMPLE/run"
185
+ proteus recipe export "$PROTEUS_EXAMPLE/run" --out "$PROTEUS_EXAMPLE/export"
186
+ ```
187
+
188
+ This creates two immutable, fixed candidates, evaluates each and exports
189
+ `report.json` plus eight CSV tables. The completed resume reuses settled
190
+ work. Private test scores require an owner-side export with `--include-private`.
191
+ This offline fixture demonstrates the pipeline; it is not a model improvement
192
+ result. The separate [search-policy example](docs/V1_RECIPE_CATALOG.md#replace-a-final-selector-without-changing-the-engine)
193
+ demonstrates candidate selection. See the [catalog](docs/V1_RECIPE_CATALOG.md) for
194
+ method examples and benchmark preparation instructions.
195
+
196
+ To try the interactive viewer, generate a small **Native sweep** in the same environment:
197
+
198
+ ```bash
199
+ PROTEUS_NATIVE="$(mktemp -d)/native-demo"
200
+ proteus run --harness minimal --arm neutral --arm review:notes \
201
+ --episodes 8 --seeds 2 --evaluator tool-calls@observe \
202
+ --eval-initial tool-calls --out "$PROTEUS_NATIVE"
203
+ proteus visualize --out "$PROTEUS_NATIVE"
204
+ # Open http://127.0.0.1:8301
205
+ ```
206
+
207
+ The `minimal` harness is a deterministic offline policy. Its snapshots, evaluator
208
+ records and visualized trajectories are real outputs of that fixture.
209
+
210
+ ## Harness-agnostic by design
211
+
212
+ A method defines **how to improve**. A harness supplies **how an agent runs**.
213
+ A candidate is **what changes**: text components, a playbook, memory or source files.
214
+ The subject runner executes that candidate on a task; the evaluator grades its output.
215
+
216
+ ```mermaid
217
+ flowchart LR
218
+ M["Method + reusable stages"] --> O["Optimizer / coding harness"]
219
+ O --> C["Candidate<br/>prompts · memory · code"]
220
+ C --> S["Subject harness<br/>runs the task"]
221
+ S --> E["External evaluation"]
222
+ E -->|Permitted feedback| M
223
+ C --> R["Evidence + reports"]
224
+ E -->|Recorded outcomes| R
225
+ ```
226
+
227
+ Bind optimizer, subject and model-grader roles separately in a recipe. Native
228
+ self-evolution can use the same harness integration to propose changes and run the
229
+ evolving candidate. Another setup can use a coding harness to modify a candidate
230
+ that a different subject executes.
231
+
232
+ | Integration | Available use | Setup |
233
+ | --- | --- | --- |
234
+ | [Pi](https://github.com/badlogic/pi-mono) | Agent/coding roles and staged source evolution | Prepared Docker image + model credentials |
235
+ | [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) | Agent/coding roles and staged source evolution | Prepared Docker image + model credentials |
236
+ | [Codex](https://github.com/openai/codex) | Agent/coding roles and staged source evolution | Pinned Rust Docker image + Codex authentication |
237
+ | `llm` | HTTP model actor, candidate execution and file evolution | Compatible model endpoint + credentials |
238
+ | `minimal` | Offline Native demo and fixture actor | No API key or Docker |
239
+ | Your harness | Roles advertised by your adapter and integration | [Register an integration](docs/V1_HARNESS_ROLES.md#integration-and-configuration) |
240
+
241
+ Registration declares roles and capabilities once; methods use those contracts
242
+ rather than a separate implementation for every harness pair. Candidate formats and
243
+ method protocols still have to match. The [role and evidence matrix](docs/V1_HARNESS_ROLES.md#capability-and-evidence-matrix)
244
+ documents supported combinations and 16 bounded live pilot cells; it is not a claim
245
+ that every method × harness × role combination has been tested.
246
+
247
+ For source evolution, all phases execute the last-valid harness while editing a
248
+ separate candidate. Proteus validates the candidate before activating it in the
249
+ next episode, retaining a failed candidate for repair. See the
250
+ [Native evolution profile](docs/V1_HARNESS_ROLES.md#native-evolution-with-external-evaluation)
251
+ and [adapter guide](docs/ADAPTERS.md). The existing Native CLI, including the Aki
252
+ research adapter, remains available through its [compatibility path](docs/V1_COMPATIBILITY.md).
253
+
254
+ ## Method families
255
+
256
+ Proteus includes the following method profiles and their original-domain recipes.
257
+ Each profile records the upstream source and its supported options.
258
+
259
+ | Method | What it provides | Recipe / implementation | Original work |
260
+ | --- | --- | --- | --- |
261
+ | **GEPA** | Reflective evolution of text components and candidate selection | [AIME](recipes/gepa/aime/README.md) · [method](docs/V1_GEPA_METHOD.md) | [Paper](https://arxiv.org/abs/2507.19457v2) · [Code](https://github.com/gepa-ai/gepa) |
262
+ | **ACE** | Playbook updates through generator, reflector and curator roles; offline and online learning | [Formula](recipes/ace/formula/README.md) · [method](docs/V1_ACE_METHOD.md) | [Paper](https://arxiv.org/abs/2510.04618v3) · [Code](https://github.com/ace-agent/ace) |
263
+ | **Meta-Harness** | Candidate-code proposals, historical evidence retrieval and memory learning | [MCE](recipes/meta-harness/mce/README.md) · [method](docs/V1_META_HARNESS.md) | [Paper](https://arxiv.org/abs/2603.28052v1) · [Code](https://github.com/stanford-iris-lab/meta-harness) |
264
+ | **Combee** | Parallel learning and aggregation for ACE and GEPA, with fixed or dynamic batches | [Formula](recipes/combee/formula/README.md) · [ACE](docs/V1_COMBEE_ACE.md) / [GEPA](docs/V1_COMBEE_GEPA.md) | [Paper](https://arxiv.org/abs/2604.04247v2) · [Code](https://github.com/gepa-ai/gepa) |
265
+ | **CORAL** | Persistent research workers, shared knowledge, formal submissions and event-driven interventions | [Circle packing](recipes/coral/circle-packing/README.md) · [method](docs/V1_CORAL_METHOD.md) | [Paper](https://arxiv.org/abs/2604.01658v3) · [Code](https://github.com/Human-Agent-Society/CORAL) |
266
+ | **Native** | Harness self-evolution with candidate validation and next-episode activation | [Shared external evaluation](recipes/native/shared-evaluation/README.md) · [episode protocol](docs/EPISODE.md) | [Native Pi experiment and software credit](recipes/native/pi/README.md) |
267
+
268
+ ### Compose the experiment
269
+
270
+ Composition is about reusing mechanisms as well as choosing a named method:
271
+
272
+ - **ACE + Combee:** learn from samples in parallel, then aggregate their updates
273
+ into a shared playbook. Compare sequential, naive parallel, fixed-batch and
274
+ dynamic-batch settings in the [Formula recipes](recipes/combee/formula/README.md).
275
+ - **GEPA + Combee:** reuse parallel proposal aggregation within the GEPA profile;
276
+ configure its batch policy and evaluation through the
277
+ [Combee–GEPA integration](docs/V1_COMBEE_GEPA.md).
278
+ - **Proposal + self-evaluation:** connect a typed proposal stage to a self-evaluator
279
+ and specify how later stages consume its assessment. The
280
+ [offline stage example](recipes/examples/self-evaluation.toml) demonstrates the
281
+ wiring; [plugin templates](docs/V1_PLUGIN_SCAFFOLDS.md) show how to implement it.
282
+ - **Search-policy ablations:** swap a supported parent, archive or final-selection
283
+ policy while keeping candidates and evaluation fixed. The
284
+ [runnable selector example](docs/V1_RECIPE_CATALOG.md#replace-a-final-selector-without-changing-the-engine)
285
+ changes the selected candidate through configuration alone.
286
+
287
+ Methods retain their own control flow. Adding a stage does not silently change
288
+ every algorithm: a composing method must invoke it. New update rules and loops
289
+ use the [versioned plugin API](docs/V1_PUBLIC_API.md), with shared artifact,
290
+ evaluation, budget and recovery services.
291
+
292
+ ## Evaluation as part of the experiment
293
+
294
+ Choose the evaluator independently of the optimization method and subject harness.
295
+ Proteus supports deterministic task scoring, benchmark verifiers, private
296
+ Harbor/Docker graders, managed model judges and custom evaluator plugins.
297
+
298
+ | Evaluation role | Purpose | How the evidence is used |
299
+ | --- | --- | --- |
300
+ | **Visible external evaluation** | Measure the candidate against declared tasks | Release permitted scores, feedback or traces to guide later updates |
301
+ | **Hidden external evaluation** | Audit generalization on held-out tasks | Keep private grades outside optimizer/subject feedback; owner-side reporting is explicit |
302
+ | **Self-evaluation stage** | Let the agent assess its own proposal or candidate | Produce separate stage evidence that the method can consume |
303
+ | **Structural and behavioral measurements** | Track what changed in the candidate or action trajectory | Describe evolution alongside task scores |
304
+
305
+ An agent's self-assessment does not become the external benchmark score. Recipes
306
+ bind task splits, evaluator identities and evidence permissions; model grading
307
+ can use its own harness/model role and usage accounting. Native episodes also
308
+ support H0 evaluation, cadence and explicit checkpoints, with visibility,
309
+ selection eligibility and scheduling configured independently.
310
+
311
+ Start with [benchmark and evaluator controls](docs/BENCHMARKS.md),
312
+ [independent model grading](docs/V1_HARNESS_ROLES.md#external-evaluators-and-private-model-grading),
313
+ or the [custom evaluator template](docs/V1_PLUGIN_SCAFFOLDS.md).
314
+ Native additionally supports goal-free, single-goal and multi-goal conditions through
315
+ [`GoalConfig`](docs/EPISODE.md).
316
+
317
+ ## Visualize the evolution
318
+
319
+ **Proteus Visualize** is a local workspace for inspecting Native sweeps as they run
320
+ or replaying completed experiments. It ships with the Python package and opens
321
+ without a frontend build or model call:
322
+
323
+ ```bash
324
+ proteus visualize --out /path/to/native-sweep
325
+ ```
326
+
327
+ - **Evolution:** replay trajectories, compare recorded runs, and switch between
328
+ evaluator scores, structural displacement and tool-frequency divergence.
329
+ - **Measurements:** inspect surface changes, path length and behavioral distances;
330
+ compare matched seeds when the measurement requirements are satisfied.
331
+ - **Configuration:** inspect recorded goals, harness/model settings, budgets,
332
+ phases and evaluator visibility; compose a new Native run configuration.
333
+ - **Snapshots:** inspect valid checkpoints and proposed candidates, including
334
+ rejected edits, without confusing a proposed change with an activated one.
335
+
336
+ The viewer is read-only by default. Run launching is an explicit opt-in, and hidden
337
+ scores are available to the local owner without feeding them back to the agent.
338
+ See the [viewer guide](docs/VISUALIZE.md) for configuration and export controls.
339
+
340
+ For **general method recipes**, use [JSON/CSV export](docs/V1_RESULT_EXPORT.md) and
341
+ [study comparisons](docs/V1_STUDY_COMPARISON.md) to analyze task scores, candidate
342
+ lineage, role/stage usage, failures and measured timing. Supported candidate formats
343
+ also provide [artifact and lineage measurements](docs/V1_ARTIFACT_MEASUREMENTS.md).
344
+ The interactive sweep viewer and recipe exports are distinct interfaces today.
345
+
346
+ ## Reproducible runs and inspectable evidence
347
+
348
+ Recipes bind method options, actors, tasks, evaluators, budgets and source/dependency
349
+ locks. Candidates and evidence retain immutable identities; completed managed work
350
+ can be recovered without repeating it. Uncertain external calls require reconciliation.
351
+ Local and Harbor/Docker backends have explicitly declared execution boundaries.
352
+
353
+ Saved records distinguish **baseline, selected and last candidates**, retain failures,
354
+ and leave unavailable scores, costs or timing unknown. Native source histories can
355
+ also be exported as Git repositories with `proteus repo export`. These records let
356
+ you inspect both the task result and the changes that produced it.
357
+
358
+ The [frozen experiment recipes](recipes/README.md) contain launchers, reproduction
359
+ instructions and results for **15 historical profiles: 14 adapted method studies
360
+ and one Native mechanism study**, across 16 recipes. They are separate from current
361
+ integration pilots and generic benchmark builders. Adapted results do not imply
362
+ matched paper reproduction, multi-seed significance or gains for every combination.
363
+ Exact upstream pins and deviations are in [method references](docs/METHOD_REFERENCES.md).
364
+
365
+ ## Documentation
366
+
367
+ | Start here | Extend or investigate |
368
+ | --- | --- |
369
+ | [Agent usage skill](skills/proteus-use/SKILL.md) | [Optional contribution skill](skills/proteus-contribute/SKILL.md) |
370
+ | [Architecture and method coverage](docs/V1_OVERVIEW.md) | [Public API and plugin templates](docs/V1_PLUGIN_SCAFFOLDS.md) |
371
+ | [Recipe catalog](docs/V1_RECIPE_CATALOG.md) | [Harness roles and adapters](docs/V1_HARNESS_ROLES.md) |
372
+ | [Evaluators and benchmarks](docs/BENCHMARKS.md) | [Search policies](docs/V1_SEARCH.md) |
373
+ | [Visualize runs](docs/VISUALIZE.md) | [Artifact measurements](docs/V1_ARTIFACT_MEASUREMENTS.md) |
374
+ | [Result export and study comparison](docs/V1_RESULT_EXPORT.md) | [Recovery and accounting](docs/V1_RECOVERY.md) |
375
+ | [Native episodes](docs/EPISODE.md) | [Prepared environments](environments/README.md) |
376
+ | [Experiment recipes and results](recipes/README.md) | [Acceptance evidence](docs/V1_FINAL_ACCEPTANCE.md) |
377
+
378
+ CI covers Python 3.10–3.14, installed wheel/sdist examples and pinned reference
379
+ contracts. Harbor runs real Docker integration checks; the complete live smoke
380
+ covers minimal, HTTP LLM, Pi, DSH and Codex. The
381
+ [release procedure](docs/RELEASING.md) keeps preparation, integration and final tag
382
+ checks separate.
383
+
384
+ ## Contributing and citation
385
+
386
+ Add a method, stage, evaluator, subject, policy or harness integration through the
387
+ [extension templates](docs/V1_PLUGIN_SCAFFOLDS.md). See
388
+ [CONTRIBUTING.md](CONTRIBUTING.md) for setup and contribution guidelines.
389
+ An agent can follow the optional [`proteus-contribute`](skills/proteus-contribute/SKILL.md)
390
+ skill to choose an extension point, preserve framework contracts and validate the change.
391
+
392
+ Cite Proteus using [CITATION.cff](CITATION.cff), and cite the original papers and
393
+ software for the methods you use. [Method references](docs/METHOD_REFERENCES.md)
394
+ include official repositories, source pins and licenses;
395
+ [references.bib](references.bib) provides BibTeX entries.
396
+
397
+ ## License
398
+
399
+ MIT. Upstream software and datasets retain their own licenses and attribution.