# cmdc_eval

> CMDC Agent benchmark harness —— 接公开基准 + 自定义 suite，输出 JSONL 报告，
> 与 LangSmith / Langfuse / Datadog 同源消费。

`cmdc_eval` 是 [cmdc](https://hex.pm/packages/cmdc) 的独立子库，提供：

- 标准 **Suite behaviour**（`CMDCEval.Suite`），实现 3 callback 即可注册一个评测集
- **断言上下文**（`CMDCEval.Context`），Suite 可用 `assert/3` 读取 reply / tool outputs / plugin events / metadata
- **RAG 通用断言**（`CMDCEval.Assertions.RAG`），覆盖 recall / citation / grounding / ACL / faithfulness / correctness
- **Workflow Eval 接缝**（`CMDCEval.Workflow` + `CMDCEval.Assertions.Workflow`），从 orchestrator event ledger 计算完成率、分支覆盖、human_task SLA 等门禁指标
- **内置 Internal Suite** —— 验证 cmdc kernel 内部特性（DAG / Steering / Checkpoint）的回归基准
- **BFCL v3 Suite 接入框架** —— Berkeley Function Calling Leaderboard，公开数据
- **`Mix.Tasks.Cmdc.Eval` CLI** —— 一行命令跑 evals + 输出 JSONL
- **稳定 JSONL 报告 schema** —— `suite / case_id / model / pass / latency_ms / tokens_in / tokens_out / cost_usd / events_digest`

## 安装

```elixir
def deps do
  [
    {:cmdc, "~> 0.5"},
    {:cmdc_eval, "~> 0.2"}
  ]
end
```

## Quick Start

### 1. 跑 Internal Suite（cmdc kernel 自验证）

```bash
$ mix cmdc.eval --suite=internal --model="anthropic:claude-sonnet-4-5" --report=internal.jsonl
```

输出：

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Suite:   internal
Model:   anthropic:claude-sonnet-4-5
Cases:   5
Pass:    5  (rate=1.0)
Fail:    0
Latency: avg=1234.0ms total=6170ms
Tokens:  in=234 out=567
Cost:    $0.0123
Report:  internal.jsonl
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 2. 跑 BFCL v3（公开基准）

```bash
# 1. 先 fetch fixtures（v0.1 写占位，真实数据见 cmdc.eval.fetch_bfcl moduledoc）
$ mix cmdc.eval.fetch_bfcl

# 2. 跑 evals
$ mix cmdc.eval --suite=bfcl --model="openai:gpt-4o" --report=bfcl.jsonl
```

### 3. 程序化调用

```elixir
{:ok, report} = CMDCEval.run(
  suite: CMDCEval.Suites.Internal,
  model: "anthropic:claude-sonnet-4-5",
  concurrency: 4,
  timeout_ms: 60_000
)

report.summary
# => %{total: 5, pass: 5, fail: 0, pass_rate: 1.0, ...}

report.runs
# => [%CMDCEval.Run{case_id: "basic_text", pass: true, ...}, ...]
```

### 4. 自定义 Suite

```elixir
defmodule MyApp.MySuite do
  @behaviour CMDCEval.Suite

  alias CMDCEval.Case

  @impl true
  def name, do: "my_app_evals"

  @impl true
  def cases do
    [
      Case.new(id: "task_a", input: "Solve task A", expected: ~r/done/),
      Case.new(id: "task_b", input: "Solve task B", expected: ~r/completed/)
    ]
  end

  @impl true
  def assert(%Case{expected: %Regex{} = re}, reply), do: Regex.match?(re, reply)
end

# 跑
{:ok, report} = CMDCEval.run(
  suite: MyApp.MySuite,
  model: "anthropic:claude-sonnet-4-5"
)
```

## 报告 JSONL Schema

每行一个 Run 的 JSON。下游可被 LangSmith / Langfuse / Datadog 直接消费:

```json
{
  "suite": "internal",
  "case_id": "basic_text",
  "model": "anthropic:claude-sonnet-4-5",
  "pass": true,
  "latency_ms": 1234,
  "tokens_in": 234,
  "tokens_out": 567,
  "cost_usd": 0.0123,
  "events_digest": null,
  "error": null,
  "timestamp": "2026-05-18T12:34:56Z",
  "metadata": {"category": "smoke"}
}
```

字段稳定 —— 不会在 minor 版本删/改字段，新字段会通过 `metadata` 透传。

## RAG Suite 示例

```elixir
defmodule MyApp.RAGEvalSuite do
  @behaviour CMDCEval.Suite

  alias CMDCEval.{Assertions.RAG, Case}

  def name, do: "rag_regression"

  def cases do
    [
      Case.new(
        id: "policy-approval",
        input: "高风险操作需要审批吗？",
        expected: %{rag: %{expected_chunk_ids: ["approval-policy-c1"]}},
        metadata: %{allowed_collections: ["policies"]}
      )
    ]
  end

  def assert(_case, _reply, context) do
    RAG.recall_at_k(context, 5, 1.0) and
      RAG.contains_citation(context) and
      RAG.no_unauthorized_source(context) and
      RAG.faithfulness_min(context, 0.8)
  end
end
```

## Workflow Eval 示例

```elixir
alias CMDCEval.Assertions.Workflow

{:ok, snapshot} = CMDCOrchestrator.status(run_id)

context =
  CMDCEval.Workflow.from_status(snapshot,
    expected_branches: ["approved", "default"]
  )

Workflow.gate(context,
  completion_rate_min: 1.0,
  node_failure_rate_lte: 0.0,
  branch_coverage_min: 1.0,
  human_task_sla_ms_lte: 86_400_000,
  retry_count_lte: 2,
  cost_usd_lte: 1.0,
  latency_ms_lte: 300_000,
  require_fork_join_satisfied: true
)
# => true / false

CMDCEval.Assertions.Workflow.gate_failures(context, human_task_sla_ms_lte: 1_000)
# => [%{metric: :human_task_sla_ms, expected: {:<=, 1000}, actual: 4200}]
```

Workflow Eval 只消费 Run / NodeRun / RunEvent 的稳定 ledger shape,不依赖 Phoenix
schema、Trace Viewer 或 Eval Dashboard。企业平台可以在 AgentSpec / Workflow 发布
审批前运行这组门禁,失败时把 `gate_failures/2` 展示给发布人。

## v0.2 范围

✅ **新增**：
- `CMDCEval.Context` —— `assert/3` 可读取 Agent 回复、工具输出、Plugin 事件和 metadata
- `CMDCEval.Runner` —— 自动订阅当前 eval session 的 CMDC EventBus 事件,并写入 `Run.metadata.eval_context`
- `CMDCEval.Assertions.RAG` —— `recall_at_k` / `contains_citation` / `grounded_answer` /
  `no_unauthorized_source` / `faithfulness_min` / `correctness_min`
- 离线 fixture 支持 —— RAG assertions 可直接对 map fixture 运行,不依赖 Arcana 或真实 LLM
- `CMDCEval.Workflow` + `CMDCEval.Assertions.Workflow` —— 基于 orchestrator event
  ledger 的 WorkflowEval 最小接缝,不做完整 Eval Dashboard / 数据飞轮

## v0.1 范围

✅ **已实现**：
- Suite behaviour + 4 struct（Case / Run / Report / Suite）
- `Mix.Tasks.Cmdc.Eval` + `Mix.Tasks.Cmdc.Eval.FetchBfcl`
- `CMDCEval.Suites.Internal` —— 5 个 cmdc kernel 自验证 case
- `CMDCEval.Suites.BFCL` —— 框架 + fetch_bfcl 占位
- JSONL 报告 schema + summary 聚合
- 11+ 单元测试覆盖 struct + Suite + Runner（mock provider 端到端）

🔁 **推后到 v0.2**：
- BFCL v3 fixtures 自动 fetch（v0.1 写占位，需手动 git clone 上游）
- tau2-bench airline suite
- MemoryAgentBench 子集（依赖 cmdc_memory_pg PG 集成）
- LangSmith 直接同步（OTLP）
- 完整 BFCL 5 子类（multiple / parallel / parallel_multiple / multi_turn）

## CLI 退出码

- `0` —— 所有 case pass
- `1` —— 有 case 失败
- `2` —— Suite 无 case（如 BFCL fixtures 未 fetch）
- `3` —— Suite 模块不存在或非法

## License

Apache-2.0