agentic-rubric-runner

agentic-rubric-runner

可审计的文档约束型 Agent 流水线：读取任务说明与 PDF 附件，生成结构化中文报告，按 Rubric 自动评分，并输出完整工具调用轨迹。

适用于「给定参考文档 + 明确任务要求 + 结构化评分标准」的文档生成与质量评估场景，例如增长指标方案、研究报告摘要、合规性检查等。

产品入口

CLI 是本项目的核心入口；Streamlit Web 控制台与 CLI 共用同一套 pipeline / agent / grader 后端，但不属于默认安装依赖。

---

功能概览

• Phase 1 — 报告生成：Agent 通过 Function Calling 依次读取 query.txt、PDF 附件，生成 Markdown 报告；程序解析固定章节后套入管理层 HTML/CSS 模板，导出 PDF（WeasyPrint，失败回退 ReportLab），同时保留 .md / .html 供审计与预览。
• Phase 2 — Rubric 评分：根据 rubrics.json 对 Phase 1 产物逐条打分，输出结构化 grading_result.json。
• 可审计轨迹：每一步 LLM 请求与工具调用写入 agent_trace.jsonl，支持事后回放与排错。
• 程序重算分数：final_score 由程序按权重公式计算，不直接信任模型给出的总分。
• 双入口：Typer CLI（核心）与 Streamlit Web 控制台（可选）共用同一套 pipeline / agent / grader 后端。
• 分步执行：支持只跑 Phase 1、只跑 Phase 2，或在 Web 上分步触发。

---

架构

CLI、Web 与 solution.py 共用同一套 pipeline / agent / grader 后端，不通过子进程调脚本。

flowchart TB
    subgraph entry [入口层]
        CLI["agentic-rubric CLI<br/>run · phase1 · grade · validate · ui"]
        WEB["Streamlit Console<br/>aarrr_agent/web_app.py"]
        SOL[solution.py]
    end

    subgraph core [核心层 aarrr_agent]
        PL["pipeline.py<br/>路径解析 · run_meta · 双阶段编排"]

        subgraph phase1 [Phase 1 — agent.py + 状态机]
            direction LR
            T1[read_text] --> T2[read_pdf] --> T3[extract_evidence_pack]
            T3 --> T4[self_check_report]
            T4 --> T5[write_structured_report]
        end

        subgraph phase2 [Phase 2 — grader.py]
            direction LR
            G0[检索式选页] --> G1[证据化评分] --> G2[附件门控/校准] --> G3[程序重算 final_score]
        end

        PL --> phase1
        PL --> phase2
    end

    subgraph inputs [输入]
        Q[query.txt]
        P[attachment.pdf]
        R[rubrics.json]
    end

    subgraph outputs [输出]
        MD[phase1_output.md]
        HTML[phase1_output.html]
        PDF[phase1_output.pdf]
        GR[grading_result.json]
        GRPT[grading_report.md/html]
        EV[evidence_pack.json]
        TR[agent_trace.jsonl]
        META[run_meta.json]
    end

    CLI --> PL
    WEB --> PL
    SOL --> CLI

    Q --> T1
    P --> T2
    T3 --> EV
    R --> G0
    T5 --> MD
    T5 --> HTML
    T5 --> PDF
    MD --> G1
    PDF --> G1
    G3 --> GR
    G3 --> GRPT
    phase1 --> TR
    PL --> META
    phase2 --> META

Phase 1 约束

• Agent 只能访问 query.txt 与附件 PDF，不读取 rubrics.json（避免评分标准泄露到生成阶段）。
• 状态机强制工具顺序；write 之后禁止再调工具；须输出 PHASE1_DONE。
• 报告关键事实须引用证据编号 [E01]，证据来自 evidence_pack.json。

Phase 2 流程

• 读取 Phase 1 产物（Markdown / PDF）与 rubrics.json。
• 检索式选取附件相关页（非简单截断）；每项输出 evidence / missing。
• 附件领域不匹配时程序门控压低分数；final_score 由程序重算。

---

安装

默认安装仅包含 CLI 核心依赖（run / phase1 / grade / validate / inspect-trace 等完整可用）。如需 Streamlit Web UI，请额外安装 [web] extra。

从 GitHub 安装（推荐）

pip install "git+https://github.com/bosprimigenious/agentic-rubric-runner.git"

固定版本：

pip install "agentic-rubric-runner @ git+https://github.com/bosprimigenious/agentic-rubric-runner.git@v0.4.0"

可选：Web UI

pip install "agentic-rubric-runner[web] @ git+https://github.com/bosprimigenious/agentic-rubric-runner.git"

安装后可运行 agentic-rubric ui 或 streamlit run app.py。

全局 CLI（pipx）

pipx install "git+https://github.com/bosprimigenious/agentic-rubric-runner.git"

需要 Web 时：

pipx install "agentic-rubric-runner[web] @ git+https://github.com/bosprimigenious/agentic-rubric-runner.git"

本地开发

git clone https://github.com/bosprimigenious/agentic-rubric-runner.git
cd agentic-rubric-runner
pip install -e ".[dev]"          # CLI + 测试工具
pip install -e ".[dev,web]"      # 含 Streamlit Web UI

依赖清单文件说明

安装 CLI 请使用 pip install . 或 pip install -e .，不要直接 pip install -r requirements.txt 后再误以为已包含 Web。

---

快速开始

1. 配置 API Key

cp .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY

PowerShell 临时设置：

$env:DEEPSEEK_API_KEY = "sk-..."

可选环境变量：

2. 运行完整流水线

仓库自带 fixtures/ 样例数据，可直接验证：

agentic-rubric run \
  --query fixtures/query.txt \
  --pdf fixtures/attachment.pdf \
  --rubrics fixtures/rubrics.json

输出写入 outputs/<run_id>/，包含 PDF、评分 JSON、审计轨迹等。

3. 校验评分结果

agentic-rubric validate outputs/<run_id>/grading_result.json

4. 查看 Agent 轨迹

agentic-rubric inspect-trace outputs/<run_id>/agent_trace.jsonl

5. 生成 Agent 运行评分（可选）

agentic-rubric eval-run \
  --out outputs/<run_id> \
  --rubrics fixtures/rubrics.json

该命令读取一次已完成运行的产物，生成 agent_eval.json，从 Phase 1 执行、Phase 2 评分、任务成功率、事实可追溯、鲁棒性、效率与安全边界七个维度给出 run-level 分数。

6. 运行 Benchmark（可选）

cp fixtures/benchmarks/agent_cases.example.json fixtures/benchmarks/agent_cases.json
# 编辑 agent_cases.json，把 .example 占位文件替换为真实存在的 query/pdf/rubrics

agentic-rubric bench \
  --manifest fixtures/benchmarks/agent_cases.json \
  --out outputs/bench

Benchmark 会逐个执行 manifest 中的 case，每个 case 写入独立目录，并在 outputs/bench/ 下生成 agent_benchmark_result.json 和 agent_benchmark_report.md。

7. 启动 Web 控制台（可选，需 [web]）

pip install -e ".[web]"   # 若尚未安装 Web 依赖
agentic-rubric ui
# 或
streamlit run app.py

---

CLI 命令参考

常用选项

# 指定输出目录
agentic-rubric run --query q.txt --pdf doc.pdf --rubrics rubrics.json --out outputs/demo

# 分步执行
agentic-rubric phase1 --query q.txt --pdf doc.pdf --out outputs/demo
agentic-rubric grade --rubrics rubrics.json --phase1-md outputs/demo/phase1_output.md --out outputs/demo

# 切换模型
agentic-rubric run ... --model deepseek-chat

# 对单次运行做 Agent 级评分
agentic-rubric eval-run --out outputs/demo --rubrics rubrics.json

# 运行 benchmark case suite
agentic-rubric bench --manifest fixtures/benchmarks/agent_cases.json --out outputs/bench

solution.py 为兼容入口，等价于 agentic-rubric run。

---

Web 控制台

Deploy Console： agentic-rubric-runner.streamlit.app

文档评审控制台 提供与 CLI 相同的后端能力：

1. 上传 query.txt、PDF 附件、rubrics.json
2. 在页面输入 DeepSeek API Key（密钥仅存于当前会话）
3. 运行 Phase 1（报告生成）与 Phase 2（Rubric 评分）
4. 查看评分摘要，下载 PDF / JSON / 审计轨迹（下载不触发重新运行）

本地启动：agentic-rubric ui 或 streamlit run app.py

Streamlit Cloud 部署

云端部署推荐配置：Main file 为 app.py，Requirements file 为 requirements-streamlit.txt，Python 版本为 3.11，Visibility 设为 Public。

如果页面空白、只有灰色背景、控制台出现 Unable to preload CSS，通常是 Streamlit Cloud 权限或配置问题。完整部署步骤与排障手册见 docs/streamlit_deploy.md。

---

输入格式

query.txt

纯文本任务描述，说明期望 Agent 产出的文档类型、结构与覆盖范围。示例见 fixtures/query.txt。

attachment.pdf

参考文档。Agent 在 Phase 1 中通过 read_pdf 提取文本；评分阶段也会读取 PDF 以核对事实引用。

rubrics.json

结构化评分标准，顶层字段：

{
  "rubric_summary": "评分标准总体说明",
  "rubric": {
    "hard_constraints": [ ... ],
    "soft_constraints": [ ... ],
    "optional_constraints": [ ... ]
  }
}

每条约束包含：

评分项 ID 规则：硬约束 H01…、软约束 S01…、可选约束 O01…

---

输出格式

默认输出目录：outputs/<run_id>/（run_id 格式 YYYYMMDD_HHMMSS）

Benchmark 汇总目录额外包含：

grading_result.json 主要字段：

{
  "final_score": 93.5,
  "score_breakdown": {
    "hard_score": 10, "hard_max": 10,
    "soft_score": 8, "soft_max": 9,
    "optional_score": 2, "optional_max": 3
  },
  "hard_constraints": [{ "id": "H01", "score": 1, "reason": "..." }],
  "soft_constraints": [...],
  "optional_constraints": [...]
}

---

日志与审计

本项目的排障核心是三个文件：

常见排障路径：

1. grading_result.json 分数异常：先看 grading_report.md 的主要缺口，再看 agent_eval.json 的 failure_types。
2. Agent 没生成报告：看 agent_trace.jsonl 最后一条工具调用和 phase1_state。
3. 附件离题或事实不可追溯：看 grading_result.json 中是否出现“程序门控”，再看 agent_eval.json 的 groundedness 详情。
4. Benchmark 阻断发布：看 agent_benchmark_result.json 的 release.failures 和 failure_taxonomy。
5. 需要复现：用 run_meta.json 的输入哈希、模型名、输出文件名和 trace 定位对应 run。

---

Agent Benchmark 规划

当前 Benchmark 已具备最小闭环：

• bench 命令读取 manifest 并逐 case 运行。
• 每个 case 独立输出，避免互相覆盖。
• 每次运行生成 agent_eval.json。
• Benchmark 汇总生成 JSON 与 Markdown 报告。
• 支持 release gate、case severity、owner、business impact 等生产字段。

后续规划：

详细标准见 docs/agent_scoring_upgrade.md。

---

评分公式

三类约束按权重折算为 0–100 分，分母从 rubrics.json 动态计算：

final_score =
  (hard_score / hard_max) × 50
+ (soft_score / soft_max) × 30
+ (optional_score / optional_max) × 20

• 硬约束（hard）：必须满足的核心要求，权重 50%
• 软约束（soft）：质量区分项，权重 30%
• 可选约束（optional）：加分项，权重 20%

若某一类约束在 rubrics 中为空，对应项不参与计算（动态调整有效分母）。程序在写入前强制重算 final_score，与模型原始输出不一致时以程序结果为准。

如需将当前“文档评分”升级为更完整的 Agent Benchmark，请参考 docs/agent_scoring_upgrade.md 与 fixtures/benchmarks/agent_cases.example.json。该标准覆盖 Phase 1 执行、Phase 2 评分、任务成功率、事实可追溯、鲁棒性、效率成本与安全边界。

---

错误码

---

项目结构

agentic-rubric-runner/
├── aarrr_agent/              # 核心 Python 包
│   ├── agent.py              # Phase 1 Agent 工具循环
│   ├── benchmark.py          # Agent eval-run / bench 评测与汇总
│   ├── grader.py             # Phase 2 Rubric 评分
│   ├── grading_report.py     # 评审报告、总评清洗、管理层摘要
│   ├── pipeline.py           # 双阶段编排与输出路径
│   ├── tools.py              # read_text / read_pdf / write_pdf_report
│   ├── html_report.py        # Jinja2 管理层 HTML 模板
│   ├── html_pdf.py           # WeasyPrint PDF + ReportLab fallback
│   ├── md_report_parser.py   # Markdown → 结构化报告
│   ├── pdf_gen.py            # ReportLab PDF 渲染（fallback）
│   ├── templates/            # executive_report.html
│   ├── assets/               # executive_report.css
│   ├── cli.py                # Typer CLI
│   ├── web_app.py            # Streamlit UI
│   ├── schemas.py            # Pydantic 数据模型
│   ├── validation.py         # 评分结果校验
│   └── ...
├── app.py                    # Streamlit Cloud 入口
├── solution.py               # run 兼容入口
├── fixtures/                 # 样例 query / PDF / rubrics
│   └── benchmarks/           # Agent Benchmark manifest 示例
├── docs/                     # GitHub Pages 静态站
├── tests/                    # pytest 测试套件
├── .github/workflows/        # CI、Pages、PyPI 发布
├── requirements.txt            # CLI / 核心依赖
├── requirements-web.txt        # 核心 + Streamlit
├── requirements-streamlit.txt  # Streamlit Cloud 部署
├── packages.txt                # 云端系统字体包
└── pyproject.toml

---

开发与测试

# 运行测试（当前 18 项）
pytest -q

# 打包 wheel
python -m build

# 代码格式化（dev 依赖）
ruff check aarrr_agent tests
black aarrr_agent tests

CI/CD（GitHub Actions）

---

安全说明

• 勿将 .env 或真实 API Key 提交到版本库。
• Web 控制台由用户在浏览器输入 Key，不在 Streamlit Secrets 中存储。
• fixtures/ 为演示材料；生产环境请替换为自有文档与评分标准。
• Agent 工具层对文件路径有白名单校验，限制可读文件范围。

---

License

MIT — 详见 LICENSE。