backend/database/samples/README.md

AgentGraph Sample Data System

这是重构后的 sample data 系统，使用 JSON 文件而不是硬编码的 Python 数据，更容易维护和扩展。

📁 文件结构

samples/
├── README.md                          # 本文档
├── samples_config.json                # 样本配置文件
├── traces/                           # Trace数据目录
│   └── python_documentation_inquiry.json
└── knowledge_graphs/                  # Knowledge Graph数据目录
    └── kg_python_documentation_enhanced.json

🔧 配置系统

samples_config.json

主配置文件，定义所有可用的样本：

{
  "samples": [
    {
      "id": "python_documentation_demo",
      "name": "Python Documentation Assistant Demo",
      "description": "...",
      "trace_file": "traces/python_documentation_inquiry.json",
      "knowledge_graph_file": "knowledge_graphs/kg_python_documentation_enhanced.json",
      "tags": ["programming", "rag_assistant", "documentation"],
      "complexity": "enhanced",
      "trace_type": "documentation_search",
      "trace_source": "sample_data",
      "features": [
        "rag_search",
        "failure_detection",
        "optimization_recommendations"
      ]
    }
  ],
  "metadata": {
    "version": "1.0.0",
    "created": "2025-01-27",
    "description": "..."
  }
}

📄 数据文件格式

Trace 文件

• 位置：traces/目录
• 格式：标准 JSON，包含 filename, title, description, content 等字段
• Content 字段包含完整的 trace 数据（observations, metadata 等）

Knowledge Graph 文件

• 位置：knowledge_graphs/目录
• 格式：标准 JSON，包含 filename, trace_index, graph_data 等字段
• Graph_data 包含 entities, relations, failures, optimizations, metadata

🔄 向后兼容性

新的sample_data.py保持了与旧 API 的完全兼容性：

# 这些调用仍然正常工作
from backend.database.sample_data import SAMPLE_TRACES, SAMPLE_KNOWLEDGE_GRAPHS
from backend.database.sample_data import insert_sample_data, get_sample_data_info

✨ 新增功能

动态加载

• 支持运行时添加新样本（修改 JSON 文件即可）
• 自动验证 JSON 格式
• 更好的错误处理和日志

配置管理

from backend.database.sample_data import list_available_samples, get_sample_data_info

# 列出所有可用样本
samples = list_available_samples()

# 获取详细信息
info = get_sample_data_info()

🚀 添加新样本

1. 准备数据文件

创建 trace 和 knowledge graph 的 JSON 文件，放在相应目录下。

2. 更新配置

在samples_config.json中添加新条目：

{
  "id": "new_sample_id",
  "name": "New Sample Name",
  "description": "Description of the sample",
  "trace_file": "traces/new_trace.json",
  "knowledge_graph_file": "knowledge_graphs/new_kg.json",
  "tags": ["tag1", "tag2"],
  "complexity": "standard",
  "trace_type": "custom",
  "trace_source": "sample_data",
  "features": ["feature1", "feature2"]
}

3. 自动加载

系统会自动检测并加载新样本，无需重启。

🎯 优势

1. 易于维护：数据与代码分离，修改样本不需要改 Python 代码
2. 版本控制友好：JSON diff 更清晰，方便 code review
3. 扩展性强：添加新样本只需添加 JSON 文件
4. 类型安全：JSON schema 验证（可扩展）
5. 向后兼容：现有代码无需修改

🛠️ 开发工具

测试新系统

cd backend/database
python sample_data_new.py

验证 JSON 格式

python -m json.tool samples/traces/new_trace.json
python -m json.tool samples/knowledge_graphs/new_kg.json

📊 从 algorithm-generated.jsonl 迁移

当我们准备好从 algorithm-generated.jsonl 中选择样本时：

1. 运行multi_agent_knowledge_extractor.py生成 KG
2. 将 trace 和 KG 分别保存为 JSON 文件
3. 在samples_config.json中添加配置条目
4. 自动集成到系统中

这个结构使得批量添加真实样本变得非常简单！