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`

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

```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 的完全兼容性：

```python
# 这些调用仍然正常工作
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 格式
- 更好的错误处理和日志

### 配置管理

```python
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`中添加新条目：

```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. **向后兼容**：现有代码无需修改

## 🛠️ 开发工具

### 测试新系统

```bash
cd backend/database
python sample_data_new.py
```

### 验证 JSON 格式

```bash
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. 自动集成到系统中

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