examples: add eval-attribution-optimize-gate loop example

[tianyouyiwang]

Add a self-contained example under examples/optimization that demonstrates a six-stage closed loop: baseline evaluation, failure attribution, candidate optimization, gate decision and audit reporting. It ships a deterministic fake backend that needs no API key, plus an optional real backend backed by an OpenAI-compatible model.

Updates #214

RELEASE NOTES: Add an evaluation-optimization loop example under examples/optimization.

[github-actions]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

[tianyouyiwang]

I have read the CLA Document and I hereby sign the CLA

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@f2a34ff). Learn more about missing BASE report.

Additional details and impacted files

@@            Coverage Diff             @@
##             main        #217   +/-   ##
==========================================
  Coverage        ?   87.90237%           
==========================================
  Files           ?         479           
  Lines           ?       44984           
  Branches        ?           0           
==========================================
  Hits            ?       39542           
  Misses          ?        5442           
  Partials        ?           0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tianyouyiwang]

recheck

[helloopenworld]

AI Code Review

我现在已经有了完整且经过验证的图景。让我完成审查。

发现的问题

🚨 Critical

• examples/optimization/eval_optimize_loop/run_pipeline.py:73-85：真实模式凭据泄露入仓风险
  • _resolve_config_for_real 把 ${TRPC_AGENT_API_KEY} 等占位符用 os.path.expandvars 展开成真实明文凭据，写入 delete=False 的临时文件，随后在 run_pipeline.py:184 shutil.copy(config_path, OUTPUT / "optimizer.snapshot.json") 把该临时文件原样拷贝到仓库内的 artifacts 目录。fake 模式提交的 snapshot 无密钥，但真实模式一旦运行，artifacts/optimizer.snapshot.json 会含明文 API Key；artifacts 目录已被 git 跟踪（见 git ls-files 已包含 optimizer.snapshot.json），开发者很可能 git add 后误提交。应在拷贝前脱敏（移除/占位 apiKey），或真实模式下不拷贝配置快照。

  ...
  expanded = os.path.expandvars(raw)   # ${TRPC_AGENT_API_KEY} -> 明文
  tmp.write(expanded)
  ...
  shutil.copy(config_path, OUTPUT / "optimizer.snapshot.json")  # 明文落盘到入库目录

⚠️ Warning

• examples/optimization/eval_optimize_loop/run_pipeline.py:82-85：临时文件未清理且异常路径下凭据残留

  • NamedTemporaryFile(delete=False) 创建的临时文件从未 os.unlink，真实模式下每次运行都在系统临时目录残留一份含明文凭据的 JSON。应写入后用完即删，或改用 mkstemp + finally 清理。

• examples/optimization/eval_optimize_loop/pipeline.py:101-102、gate.py:118：配置的预算/超时/种子完全未生效

  • seed 与 budget（max_metric_calls/timeout_seconds）被读取并写进报告，但 run() 既未用 seed 做任何随机化控制，也未对评测调用做 timeout_seconds/max_metric_calls 上限保护；真实模式下若 hy3 长时间限流或挂起，pipeline 会无上限等待。gate.py:118 的 max_cost_usd 也因 evaluate_gate 调用处（pipeline.py:179）未传入 cost_usd 永远为 0、永不触发。建议至少对真实模式整体 asyncio.wait_for(..., timeout_seconds) 兜底，并去掉或真正实现 budget 校验。

• examples/optimization/eval_optimize_loop/real_call_agent.py:86-94：每次调用新建 Runner/Session 且从不关闭，真实模式下资源泄漏

  • call_agent 每次都 InMemorySessionService() + Runner(...) + create_session，循环结束后未 await session_service.close()。InMemorySessionService 在 TTL 未禁用时会启动后台 cleanup task（见框架 _start_cleanup_task）；真实模式每次评测调用都泄漏一个 service+task，artifacts/optimization_report.json 显示单轮真实闭环约 60 次调用，会累积大量未关闭资源与悬挂 task。应复用单例 service/runner，或每次 finally 中 close。

• examples/optimization/eval_optimize_loop/pipeline.py:179：gate 决策未传入成本/耗时，max_cost_usd 形同虚设

  • evaluate_gate(base_va_pass, va_pass, self.gate_cfg) 未传 cost_usd/duration_seconds，gate 第 4 条预算规则永远不触发；而 README/配置将其宣称为"成本/耗时作为硬上限兜底"。要么传入真实成本，要么在文档中明确该规则当前不启用，避免误导。

• examples/optimization/eval_optimize_loop/attribution.py:97：classify 参数错误判定硬编码城市，与训练/验证集语义不符

  • if has_tool and "weather" in actual_text and "北京" in actual_text and "上海" in query: 仅当 query 含"上海"且回复含"北京"时归 param_error；但 train_weather(query="北京天气") 调对工具时回复也含"北京"，val_weather(query="上海天气") 在 candidate_1 下返回"北京今天晴…"却被判 passed=true（见 report 433-440 行）。即验证集期望文本本身写的就是"北京今天晴"（val.evalset.json 第 1666 行），用 contains 匹配会让"问上海答北京"通过——这与 classify 标注的"参数(城市)错误"自相矛盾，示例存在正确性矛盾。建议统一 expected 文本或改用更严格匹配，并在注释中说明。

💡 Suggestion

• examples/optimization/eval_optimize_loop/optimizer.py:49-56 与 pipeline.py:167：RuleBasedOptimizer.commit 定义但从未被调用，target_prompt 注册后从不写回，"接受后回写源文件"能力实际未接入主流程。若不打算启用，建议删除以减少误导；若打算启用，应在 accepted_label 非空时调用 commit。

总结

示例整体闭环设计清晰，fake 模式可复现运行；但真实模式存在明文凭据写入入库目录的 Critical 风险，必须修复。此外预算/超时/成本兜底均未真正生效、真实模式存在资源泄漏，建议一并处理。

测试建议

• 补充真实模式运行后 artifacts/optimizer.snapshot.json 与系统临时文件中不含明文 apiKey 的断言测试。
• 补充一个真实/ fake 模式下 timeout_seconds 超限与 max_metric_calls 超限的回归测试，验证 pipeline 能按预算中断而非无限等待。

[helloopenworld]

真实模式凭据泄露入仓风险

_resolve_config_for_real 用 os.path.expandvars 把 ${TRPC_AGENT_API_KEY} 等占位符展开为明文凭据写入临时文件，随后 shutil.copy 将该临时文件原样拷贝到已纳入 git 跟踪的 artifacts 目录，存在明文 API Key 误提交风险。应在拷贝前对 apiKey 脱敏，或真实模式下不拷贝配置快照。