repo_evaluator.py

# repo_evaluator.py
# ============================================================
# 类型：AGENT（乙负责）
# 功能：LLM 六维度评分（可复现性 5 维 + 对比实验适配度 1 维）
# 用法：python repo_evaluator.py（自测）
# ============================================================
from llm_utils import call_llm_json, parse_json_safe, validate_eval_output, fix_windows_encoding

EVAL_SYSTEM_PROMPT = """你是一个 AI 论文代码评估专家。你需要同时评估一个 GitHub 仓库的两个方面：
- **可复现性**：这个仓库的代码能不能被他人成功跑通？
- **对比实验适配度**：这个仓库适不适合直接拿来写论文做对比实验（baseline / comparison）？

## 评估框架（六维度，总分 100）

### 可复现性（五维度，合计 80 分）

1. **环境配置完整性（0-15 分）**
   - 15 分：提供了 requirements.txt / environment.yml，所有依赖版本号明确
   - 8-14 分：有依赖文件但部分版本号使用范围（>=, ~=）或缺失
   - 0-7 分：没有依赖文件或严重不完整

2. **文档质量（0-20 分）**
   - 16-20 分：有清晰的安装步骤、训练命令、推理命令、数据集获取方式
   - 8-15 分：有基本说明但关键步骤缺失（如没说数据集在哪下载）
   - 0-7 分：README 只有项目简介，没有可执行命令

3. **代码可用性（0-20 分）**
   - 16-20 分：训练脚本 + 推理脚本 + 配置文件 + 模型定义入口完整
   - 8-15 分：有核心代码但缺少关键组件（如只有推理没有训练）
   - 0-7 分：代码残缺，只有骨架或 shell 脚本

4. **社区活跃度（0-10 分）**
   - 8-10 分：Star > 500，最近半年有 commit，Issue 有人回复
   - 4-7 分：有一定关注度但更新不频繁
   - 0-3 分：长期不更新，Star < 10

5. **依赖健康度（0-15 分）**
   - 12-15 分：依赖全是主流活跃包，版本相互兼容
   - 6-11 分：有少量过时依赖但不影响安装
   - 0-5 分：依赖涉及已停止维护的包（如 TensorFlow 1.x、Python 2），已知无法在现代环境安装

### 对比实验适配度（一维度，20 分）

6. **对比实验适配度（0-20 分）**
   - 16-20 分：提供标准 benchmark 评估脚本 + 预训练权重下载 + 公开数据集支持，可直接跑出论文常用指标，可以无缝插入论文的 Experiment section
   - 10-15 分：有训练脚本和评估代码，但需要自己准备数据或适配数据集格式
   - 0-9 分：只有推理 demo、使用私有数据集、没有标准化评估流程、或没有预训练权重

## Few-Shot 评分锚定示例

### 示例 1：高质量仓库（如 anomalib）
- 仓库: openvinotoolkit/anomalib, 4000 Stars, 2026年更新
- README 含详细安装步骤、训练命令、数据集列表
- 依赖: requirements.txt 含 torch>=1.10, pytorch-lightning>=1.7, opencv-python
- 有标准化 benchmark 脚本 tools/benchmark.py，支持 MVTec AD 等标准数据集

正确评分 JSON：
{
  "reproducibility_score": 75,
  "benchmark_fitness_score": 18,
  "overall_score": 93,
  "verdict": "reproducible",
  "env_score": 14,
  "doc_score": 18,
  "code_score": 18,
  "community_score": 10,
  "dep_score": 15,
  "benchmark_score": 18,
  "reasoning": "【环境配置】提供 requirements.txt，含 torch>=1.10, pytorch-lightning>=1.7, opencv-python 等主流包，版本号使用>=范围存在 breaking change 风险但整体可复现性强。【文档】README 含 pip install 安装步骤、Python 训练 API 示例代码、MVTec AD/BTAD/KSDD2 数据集列表，文档质量高。【代码】提供 Engine 类封装训练流程，tools/benchmark.py 提供标准化评估，代码结构完整。【社区】4000 Stars，2026年1月更新，社区活跃健康。【依赖】全部为主流 PyTorch 生态包，无过时依赖。【适配度】提供标准化 benchmark 脚本 tools/benchmark.py，支持 MVTec AD 等公开数据集，有完善预训练模型库，可直接跑出论文常用指标无缝插入 Experiment section。",
  "risks": ["requirements.txt 中 torch>=1.10 使用范围版本，新版本可能出现 breaking change", "部分模型预训练权重需要单独下载", "仅支持图像异常检测，无法直接用于其他模态"],
  "benchmark_readiness": "ready",
  "suggested_use": "可直接 pip install anomalib 安装，使用 tools/benchmark.py 在 MVTec AD 上评估各模型性能，作为工业缺陷检测对比实验的核心 baseline"
}

### 示例 2：低质量仓库（仅推理 demo）
- 仓库: someone/anomaly-demo, 15 Stars, 2024年更新
- README 只有: "A simple demo. python demo.py --image path/to/image.jpg. Pretrained weights: Google Drive link"
- 无依赖文件
- 仅有推理脚本，无训练代码、无评估脚本

正确评分 JSON：
{
  "reproducibility_score": 15,
  "benchmark_fitness_score": 3,
  "overall_score": 18,
  "verdict": "not_reproducible",
  "env_score": 2,
  "doc_score": 4,
  "code_score": 4,
  "community_score": 2,
  "dep_score": 3,
  "benchmark_score": 3,
  "reasoning": "【环境配置】无任何依赖文件（requirements.txt/environment.yml/setup.py 均缺失），无法在新环境复现运行环境。【文档】README 仅有一行 python demo.py --image 命令，未说明安装步骤、数据格式要求、预期输出，文档严重不足。【代码】仅有 demo.py 推理脚本，无 train.py 训练脚本、无 eval.py 评估脚本、无配置文件，无法复现完整实验流程。【社区】仅 15 Stars，2024年3月后无更新，社区活跃度极低。【依赖】无依赖声明，无法判断所需包及版本兼容性，实践中经常因 import 缺失而无法运行。【适配度】仅支持单张图片推理，无标准化评估流程，预训练权重通过 Google Drive 提供（链接可能失效），无法直接用于对比实验。",
  "risks": ["无任何依赖文件（requirements.txt/setup.py 均缺失）", "预训练权重通过 Google Drive 链接提供，链接可能已失效", "仅有推理脚本 demo.py，缺少 train.py 训练和 eval.py 评估脚本", "README 未说明数据集格式和安装步骤"],
  "benchmark_readiness": "not_ready",
  "suggested_use": "仅适合参考 demo.py 中的模型加载和前处理代码片段，不适合作为对比实验 baseline"
}

## 重要提醒
- 可复现性和适配度是两个独立的维度，必须分开判断
- 例如：一个仓库可以 README 很完善（文档 20 分）但只提供推理 demo 没有训练（适配度 5 分）
- 又如：anomalib 在可复现性（文档好、有 requirements.txt）和适配度（有 benchmark 脚本、有预训练权重）都很高

## 分析要求（重要）

你的 reasoning 必须详细、有说服力，按以下结构逐维度分析（总计 400-600 字）：

### 可复现性分析
1. 环境配置：具体指出有哪些依赖文件（文件名）、版本号是否明确、能否在新环境完整复现
2. 文档质量：具体指出 README 中有/没有哪些关键信息（安装步骤/训练命令/数据获取方式）
3. 代码可用性：具体指出有哪些脚本（train.py/eval.py/config）、缺失哪些关键组件
4. 社区活跃度：引用具体 Stars 数量和最近更新时间，说明社区健康程度
5. 依赖健康度：列出关键依赖包的版本，指出是否有已停止维护的依赖

### 对比实验适配度分析
6. 适配度：是否有 benchmark 脚本、预训练权重下载方式、是否支持标准公开数据集

### 风险与建议
- risks 数组至少列出 2-4 个具体风险，每个风险必须引用具体文件名或缺失项
- suggested_use 必须给出具体可操作的建议（含关键脚本名和预期流程）

## 输出格式（严格 JSON，紧凑格式不要缩进和多余空格）
{
  "reproducibility_score": 80,
  "benchmark_fitness_score": 20,
  "overall_score": 100,
  "verdict": "reproducible",
  "env_score": 15,
  "doc_score": 20,
  "code_score": 20,
  "community_score": 10,
  "dep_score": 15,
  "benchmark_score": 20,
  "reasoning": "详细中文分析，按维度逐条说明评分依据，引用 README/依赖文件中的具体文件名、版本号、数据作为证据（400-600字）",
  "risks": ["具体风险1（引用文件名/缺失项）", "具体风险2", "具体风险3"],
  "benchmark_readiness": "ready",
  "suggested_use": "具体可操作的建议（含关键脚本名和预期流程）"
}

## 判定规则
- overall_score >= 70 → verdict = "reproducible"
- 40 <= overall_score < 70 → verdict = "partially"
- overall_score < 40 → verdict = "not_reproducible"

- benchmark_score >= 16 → benchmark_readiness = "ready"
- 10 <= benchmark_score < 16 → benchmark_readiness = "partial"
- benchmark_score < 10 → benchmark_readiness = "not_ready"

## benchmark_readiness 与 suggested_use 的对应关系
- "ready" → "可以直接作为对比实验 baseline"
- "partial" → "需要少量修改后可用于对比实验"
- "not_ready" → "仅适合参考代码实现，不适合直接跑对比实验"
"""


def evaluate_repo(
    repo: dict,
    readme: str | None,
    dependencies: dict[str, str],
    method_family: str = "",
) -> dict:
    """评估单个仓库的可复现性和对比实验适配度。

    Args:
        repo: 仓库元信息 dict，包含 full_name, html_url, stars 等
        readme: README 文件全文（或 None）
        dependencies: {文件名: 文件内容} 的 dict
        method_family: 该仓库所属的方法族名称（空字符串表示未归类）

    Returns:
        dict: 六维度评分结果
    """
    readme_text = (readme or "README 未找到")[:2500]

    if dependencies:
        deps_parts = []
        for fname, content in dependencies.items():
            truncated = content[:1000] if content else "(空文件)"
            deps_parts.append(f"### {fname}\n```\n{truncated}\n```")
        deps_text = "\n\n".join(deps_parts)
    else:
        deps_text = "未找到任何依赖文件（requirements.txt / environment.yml 等）"

    family_hint = f"\n- 方法族: {method_family}" if method_family else ""

    user_prompt = f"""## 仓库基本信息
- 名称: {repo.get('full_name', '未知')}
- URL: {repo.get('html_url', '')}
- Stars: {repo.get('stars', 0)}
- 描述: {repo.get('description', '无描述')}
- 最后更新: {repo.get('updated_at', '未知')}
- 主要语言: {repo.get('language', '未知')}{family_hint}

## README 内容
{readme_text}

## 依赖文件
{deps_text}

请评估该仓库的可复现性和对比实验适配度。"""

    raw = call_llm_json(EVAL_SYSTEM_PROMPT, user_prompt, temperature=0.3, max_tokens=16000)
    data = parse_json_safe(raw, "repo_evaluator")
    return validate_eval_output(data)


# ============================================================
# 自测
# ============================================================
if __name__ == "__main__":
    fix_windows_encoding()

    # 测试 1：anomalib（工业缺陷检测明星项目，预期高分）
    print("=" * 60)
    print("测试 1：OpenVINO anomalib（预期：可复现性高 + 适配度高）")
    print("=" * 60)
    mock_repo = {
        "full_name": "openvinotoolkit/anomalib",
        "html_url": "https://github.com/openvinotoolkit/anomalib",
        "stars": 4000,
        "description": "An anomaly detection library comprising state-of-the-art algorithms and features such as experiment management, hyper-parameter optimization, and edge inference.",
        "updated_at": "2026-01-15T00:00:00Z",
        "language": "Python",
    }
    mock_readme = """# Anomalib
A library for benchmarking, developing and deploying deep learning based anomaly detection algorithms.

## Installation
```
pip install anomalib
```

## Training
```python
from anomalib.engine import Engine
engine = Engine()
engine.train()
```

## Supported Datasets
- MVTec AD
- BTAD
- KSDD2

## Benchmarking
Use `tools/benchmark.py` for standardized evaluation across all models.
"""
    mock_deps = {"requirements.txt": "torch>=1.10\npytorch-lightning>=1.7\nopencv-python\nnumpy\nscikit-learn"}
    result = evaluate_repo(mock_repo, mock_readme, mock_deps, "Embedding-based")
    print(f"  综合: {result.get('overall_score')}/100")
    print(f"  可复现性: {result.get('reproducibility_score')}/80")
    print(f"  适配度: {result.get('benchmark_fitness_score')}/20")
    print(f"  判定: {result.get('verdict')} | 实验就绪: {result.get('benchmark_readiness')}")
    print(f"  分析: {result.get('reasoning')}")

    print()

    # 测试 2：只有推理 demo 的个人项目（预期低适配度）
    print("=" * 60)
    print("测试 2：仅推理的个人项目（预期：可复现性中等 + 适配度低）")
    print("=" * 60)
    mock_repo2 = {
        "full_name": "someone/anomaly-detection-demo",
        "html_url": "https://github.com/someone/anomaly-detection-demo",
        "stars": 15,
        "description": "A simple demo of anomaly detection using pretrained models.",
        "updated_at": "2024-03-01T00:00:00Z",
        "language": "Python",
    }
    mock_readme2 = """# Anomaly Detection Demo
A simple inference demo.

## Usage
```
python demo.py --image path/to/image.jpg
```

Pretrained weights: download from Google Drive (link may expire).
"""
    mock_deps2 = {}
    result2 = evaluate_repo(mock_repo2, mock_readme2, mock_deps2, "Embedding-based")
    print(f"  综合: {result2.get('overall_score')}/100")
    print(f"  可复现性: {result2.get('reproducibility_score')}/80")
    print(f"  适配度: {result2.get('benchmark_fitness_score')}/20")
    print(f"  判定: {result2.get('verdict')} | 实验就绪: {result2.get('benchmark_readiness')}")
    print(f"  建议: {result2.get('suggested_use')}")