# wbr-data-interpreter-project

**Repository Path**: work_project_item/wbr-data-interpreter-project

## Basic Information

- **Project Name**: wbr-data-interpreter-project
- **Description**: 数据解读即服务
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-21
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Data Interpreter - 数据解读智能体

一个面向开发者的"数据解读即服务"API。客户传图表数据进来，返回结构化的分析结果和自然语言解读。

## 核心设计理念

**对外极简,对内极强**。

- API 只有 5 个字段：`chart_type` + `data` + `fields` + `prompt` + `language`
- 必填字段只有 2 个（`chart_type` 和 `data`）
- 所有复杂度藏在内部：数据语义识别、分析策略选择、确定性计算、LLM 解读

## 架构分层

```
[API 层 (FastAPI)]
       ↓
[请求校验层]
       ↓
[数据语义识别] ← 识别每列的角色（time/category/measure/...）
       ↓
[分析策略选择] ← 根据"数据角色组合"决定调用哪些分析（不按图表类型）
       ↓
[确定性计算层] ← 纯 Python 函数，无 LLM，可单测
       ↓
[LLM 解读生成] ← 阿里云百炼,把数字翻译成自然语言
       ↓
[响应组装层]
```

**关键纪律**:计算层绝对不用 LLM,LLM 层绝对不做数学。

## v0.2 增强方向

这版把系统从"能分析"增强到"能解释为什么这样分析"。

### 1. 分析模板层

新增 `app/core/templates.py` 和 `app/core/strategy_store.py`,把字段角色组合映射成可解释、可配置的分析策略。策略配置会存入 SQLite,默认路径是 `data/analysis_config.sqlite3`,可通过环境变量 `ANALYSIS_CONFIG_DB` 覆盖。

| 数据形态 | 触发条件 | 核心分析 |
|---|---|---|
| `time_series` | time + measure | 趋势、环比、同比、波动、异常、峰谷 |
| `categorical_comparison` | category + measure | 排名、Top/Bottom、差距、占比、集中度、长尾 |
| `time_series_with_segments` | time + category + measure | 整体趋势 + 分组贡献/结构 |
| `multi_measure_relation` | 2 个以上 measure 或 scatter | 相关方向、强度、简单线性拟合 |
| `single_measure_profile` | 单指标或弱结构数据 | 基础统计、极值、质量风险 |

响应的 `meta.analysis_template` 会返回本次选中的分析、可做但未优先执行的分析、跳过原因和推荐叙事框架。

### 1.1 策略运营 API

策略模板可以通过 API 管理:

- `GET /v1/strategy/templates` 列出模板
- `GET /v1/strategy/templates?include_config=true` 列出完整配置
- `GET /v1/strategy/templates/{template_id}` 查看单个模板
- `PUT /v1/strategy/templates/{template_id}` 创建或更新模板
- `PATCH /v1/strategy/templates/{template_id}/status` 启用或暂停模板
- `POST /v1/strategy/templates/reset` 恢复内置默认模板

一个模板包含:

- `enabled_analyzers`: 启用哪些已有分析器
- `enabled_methods`: 启用哪些细粒度分析元素,如 `pareto`、`gap_analysis`、`pearson_relation`
- `guardrails`: 启用哪些分析防腐规则,如禁止因果推断、小样本谨慎、相关不等于因果
- `thresholds`: 趋势、环比、异常、质量风险等阈值
- `insight_policy`: 洞察排序、最大返回条数
- `narrative_frame`: Agent 解读结构
- `style`: 业务表达风格和风险提示

可通过 `GET /v1/strategy/catalog` 查看所有可选分析元素和防腐规则。

### 2. 确定性分析能力

- `quality`: 缺失率、重复行、字段稀疏风险
- `relation`: 多指标两两皮尔逊相关、最强关系、拟合斜率和 R²
- `comparison.aggregate_by_category`: 支持 time + category 长表先聚合再做分组贡献

### 3. Agent 叙事增强

LLM 输入现在包含"分析模板",Agent 会按模板组织报告:

1. 先讲该数据类型最重要的主线
2. 再讲异常、分组贡献、关系或结构
3. 最后提示数据质量和相关性不等于因果

### 4. 产品体验

Playground 新增 `Plan` 标签页,展示本次分析策略；新增散点关系和分组趋势示例。

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置百炼 API Key

复制 `.env.example` 为 `.env`,填入你的 DashScope API Key:

```bash
cp .env.example .env
# 编辑 .env,填入 DASHSCOPE_API_KEY
```

获取 API Key: https://bailian.console.aliyun.com/

### 3. 启动服务

```bash
python -m app.main
```

服务启动在 http://localhost:8000

- API 文档: http://localhost:8000/docs
- 测试页面: http://localhost:8000/

### 4. 调用 API

```python
import requests

response = requests.post("http://localhost:8000/v1/interpret", json={
    "chart_type": "line",
    "data": [
        {"month": "2025-01", "sales": 1200},
        {"month": "2025-02", "sales": 1350},
        {"month": "2025-03", "sales": 1180},
        {"month": "2025-04", "sales": 1420},
    ],
    "fields": {
        "month": {"role": "time", "granularity": "month"},
        "sales": {"role": "measure", "name": "销售额", "unit": "元"}
    },
    "prompt": "关注趋势和异常"
})

print(response.json())
```

## 项目结构

```
app/
├── main.py              # FastAPI 入口
├── config.py            # 配置
├── core/                # 核心
│   ├── schemas.py       # Pydantic 数据模型(输入输出契约)
│   ├── semantics.py     # 数据语义识别
│   └── orchestrator.py  # 编排器
├── analyzers/           # 确定性分析函数库
│   ├── base.py          # 基础统计
│   ├── timeseries.py    # 时间序列分析
│   ├── comparison.py    # 对比分析
│   ├── composition.py   # 结构分析
│   └── anomaly.py       # 异常检测
├── llm/                 # LLM 层
│   ├── client.py        # 百炼客户端
│   └── narrator.py      # 解读生成
└── api/                 # API 路由
    └── interpret.py
web/
└── index.html           # 测试页面
tests/
└── test_analyzers.py    # 单测
```

## API 规范

详见 `API.md`。