Metadata-Version: 2.5
Name: ai-eval-scope
Version: 0.1.5
Summary: Agent 能力评估系统 — 基于 Agent-Driven 架构的评测框架
Author: Agent Eval Team
License-Expression: MIT
License-File: LICENSE
Keywords: agent,benchmark,code-generation,courseware,evaluation,llm,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: diskcache>=5.6
Requires-Dist: html5lib>=1.1
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: jsonschema>=4.21
Requires-Dist: markdown>=3.5
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: structlog>=24.0
Requires-Dist: typer>=0.12.0
Provides-Extra: agent
Requires-Dist: deepagents>=0.2; extra == 'agent'
Requires-Dist: langchain-anthropic>=0.3; extra == 'agent'
Requires-Dist: langchain-openai>=0.3; extra == 'agent'
Requires-Dist: langgraph>=0.4; extra == 'agent'
Provides-Extra: datasets
Requires-Dist: huggingface-hub>=0.24; extra == 'datasets'
Requires-Dist: modelscope>=1.18; extra == 'datasets'
Requires-Dist: pyarrow>=24.0.0; extra == 'datasets'
Provides-Extra: llm
Requires-Dist: anthropic>=0.30; extra == 'llm'
Requires-Dist: langfuse>=2.0; extra == 'llm'
Requires-Dist: openai>=1.30; extra == 'llm'
Provides-Extra: vision
Requires-Dist: anthropic>=0.30; extra == 'vision'
Requires-Dist: langfuse>=2.0; extra == 'vision'
Requires-Dist: openai>=1.30; extra == 'vision'
Requires-Dist: playwright==1.60.0; extra == 'vision'
Description-Content-Type: text/markdown

# Agent Eval 评估器

[![PyPI](https://img.shields.io/pypi/v/ai-eval-scope.svg)](https://pypi.org/project/ai-eval-scope/)
[![Python](https://img.shields.io/pypi/pyversions/ai-eval-scope.svg)](https://pypi.org/project/ai-eval-scope/)
[![License: MIT](https://img.shields.io/pypi/l/ai-eval-scope.svg)](https://pypi.org/project/ai-eval-scope/)

Agent 能力评估框架（`agent-eval` CLI）——基于 Agent-Driven 架构，支持课件生成、
代码生成、RAG、对话等多类 Agent 评估。

## 安装（发布后）

```bash
pip install ai-eval-scope                 # 基础：规则评估（无 LLM 依赖）
pip install "ai-eval-scope[llm]"          # + LLM Judge（OpenAI/Anthropic 兼容）
pip install "ai-eval-scope[agent]"        # + ExecutionAgent 执行引擎（DeepAgents 底座）
pip install "ai-eval-scope[vision]"       # + 视觉评估（playwright 截图渲染）
pip install "ai-eval-scope[datasets]"     # + 数据集下载（HuggingFace/ModelScope）

uv tool install "ai-eval-scope[agent]"    # uv：全局 CLI 工具安装
uvx --from "ai-eval-scope[agent]" agent-eval --help   # 一次性运行，不落盘
```

> 包名 `ai-eval-scope`，import 名 `agent_eval`，CLI 命令 `agent-eval`（命令名≠包名）。
> Python ≥ 3.11。LLM 与凭证配置见 [CLI 使用教程](../docs/guide/CLI使用教程.md)。

## 开发

```bash
cd evaluator
uv sync --group dev                # 开发依赖组（PEP 735，含 llm/vision 测试依赖）
uv run playwright install chromium  # 下载 Chromium 浏览器二进制（~150MB，装到用户缓存）
uv run agent-eval --help
```

## 配置

### 交互式向导（推荐）

```bash
uv run agent-eval models login
```

向导流程：

1. **选择提供商**：`anthropic` / `openai` / `deepseek` / `custom`（自定义 OpenAI 兼容端点）
2. **API Base URL**：按提供商给默认值（anthropic 缺省 `https://api.moonshot.cn/anthropic`，即 Kimi 的 Anthropic 协议端点；openai 缺省 `https://api.openai.com/v1`；deepseek 缺省 `https://api.deepseek.com/v1`）
3. **API Key**：隐藏输入
4. **逐角色确认模型**：
   - `text` — 文本 LLM Judge（默认必配）
   - `vision` — 视觉评估模型（用视觉规则集时需要）
   - `agent` — 执行侧模型（`run`/`pipeline` 驱动被测 Agent 用；未配置时自动回退 `text`）

### 查看与验证

```bash
uv run agent-eval models list    # 查看（API Key 脱敏显示 前4…后4）
uv run agent-eval models test    # 对每个已配角色真实调用一次，打印时延
uv run agent-eval models logout  # 删除配置（含 key）
```

详见 [CLI 使用教程](../docs/guide/CLI使用教程.md) 与 [CLAUDE.md](./CLAUDE.md)。

## 运行

```bash
uv run agent-eval eval \
  --package-dir workspace/packages/<包目录>/ \
  --package courseware
```

验证是否真正执行：产物中出现 `*.png` 截图、评估耗时显著增加（视觉渲染 + 视觉 LLM 调用），
且日志无「视觉跳过」「Chromium 启动失败」字样。缓存命中时会跳过视觉重算，调试时加
`--no-cache` 强制重评。
