# 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 即可注册一个评测集
- **内置 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.1"}
  ]
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` 透传。

## 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