# ai-recommendation

**Repository Path**: agingai-open/ai-recommendation

## Basic Information

- **Project Name**: ai-recommendation
- **Description**: AI 方案推荐系统 — 评估→护理方案映射（规则优先 + LLM 兜底 + DL 预留）
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 方案推荐系统 (ai-recommendation)

> AgingAI 平台的**评估→护理方案推荐**层 — 消费底座评估记录，输出针对性治疗/护理方案建议。独立第七模块（ADR-002），端口 `:8006`。

## 定位

评估系统（ai-evaluation）职责到 `EvaluationResult` 落底座为止；本模块是其**下游消费者**：读底座评估记录 → 规则/LLM/DL → 护理方案。评估（给分，算法稳定）与方案推荐（给护理方案，业务高频变动）职责分离（ADR-002）。

## 核心能力

- **规则优先**：YAML 配置驱动的规则引擎，按 `evaluation_type` / `risk_level` / `component_scores` 匹配，聚合命中规则
- **LLM 兜底**：规则未命中时，评估记录喂 LLM 生成结构化方案（标注 `source=llm`）；LLM 失败/未配置降级为默认方案（`source=default`）
- **多源融合**：`FusionEngine` 支持多评估来源（容器算分 + 案例匹配）融合，配置驱动三种策略（weighted_average / max_risk / llm_adjudication），权重和策略在 `fusion_config.yaml` 调整（ADR-004）
- **DL 预留**：`RecommenderStrategy` 接口定型，DL 策略空实现，数据足够时接入（不强依赖）
- **生成并写回**：`POST /api/v1/recommendations/generate-and-save` 会话级幂等地生成并落库 foundation `care_plan_ai`（T-AA 评估→护理计划自动链环节 2，ADR-002 §九）
- **数据来源**：消费底座 `GET /api/v1/records?record_type=evaluation`，底座不可达时降级

## 快速开始

```bash
python3.11 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --port 8006 --reload
```

健康检查：`GET http://localhost:8006/health`

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查 |
| POST | `/api/v1/recommendations` | 生成方案推荐（`elderly_id` 查底座 / inline 单评估 / inline 多源融合），只读不落库 |
| POST | `/api/v1/recommendations/generate-and-save` | 生成护理计划并写回底座 care_plan_ai（会话级幂等，T-AA 环节 2） |
| POST | `/api/v1/services/generate` | 入住基础服务生成 |
| GET | `/api/v1/care-measures` | 查询照顾措施目录 |
| GET | `/api/v1/care-measures/{code}` | 查单条措施详情 |

**请求示例 — 多源融合**：

```bash
curl -X POST http://localhost:8006/api/v1/recommendations \
  -H "Content-Type: application/json" \
  -d '{
    "evaluations": [
      {"evaluation_type":"frailty","risk_level":"high","total_score":5.0,"component_scores":{"grip":0.8}},
      {"evaluation_type":"case_match","risk_level":"moderate","total_score":3.0,"component_scores":{"fall":0.9}}
    ]
  }'
```

也支持 inline 单评估（不查底座）：

```bash
curl -X POST http://localhost:8006/api/v1/recommendations \
  -H "Content-Type: application/json" \
  -d '{"evaluation":{"evaluation_type":"frailty","risk_level":"moderate","total_score":4.2,"component_scores":{}}}'
```

### 生成并写回（generate-and-save）

`POST /api/v1/recommendations/generate-and-save` — 评估会话完成点触发（ADR-002 §九）：inline 传递本会话全部评估 → 生成（rule → llm → default 链）→ 幂等落库 foundation `care_plan_ai` 记录（status=pending，护士端可见）。

- **幂等（会话级）**：`session_id` 非空时，同会话已有计划 → 返回 `status=existing`（不重复生成不重复落库）；手动重推（`session_id` 空）不做幂等拦截
- **生成路径**：`evaluations` 非空走 FusionEngine 多源融合（零落库竞态）；空则查底座最新评估
- **失败语义**：LLM 兜底超时（默认 60s，`LLM_TIMEOUT_SECONDS`）降级仅规则/default 结果落库（保证一定有计划）；底座写入失败返回 502（4xx 不重试 / 5xx 退避重试 3 次）
- **时效**：规则命中秒级，LLM 兜底 ≤60s，评估完成→护士端可见 P95 ≤1 分钟

```bash
curl -X POST http://localhost:8006/api/v1/recommendations/generate-and-save \
  -H "Content-Type: application/json" \
  -d '{
    "elderly_id": "E008",
    "session_id": "sess-20260824-001",
    "trigger_source": "voice_session",
    "evaluations": [
      {"evaluation_id":"eval-1","evaluation_type":"frailty","risk_level":"high","total_score":5.0},
      {"evaluation_id":"eval-2","evaluation_type":"cognitive","risk_level":"moderate","total_score":20.0}
    ]
  }'
```

响应：

```json
{
  "code": 0, "message": "success",
  "data": {
    "plan_id": "plan-4bbed9892aa3",
    "status": "created",
    "source": "rule",
    "recommendation_count": 7,
    "job_id": "job-b8f90e88b976"
  }
}
```

落库 payload 含溯源字段：`generated_by`（rule_engine/llm/fusion/default）、`rules_version`（规则内容指纹 `care_rules@<hash8>`）、`trigger`（session_id + trigger_source）、`based_on_evaluation_ids`（inline 评估记录 ID 透传）。

## 融合引擎配置

`app/rules/fusion_config.yaml` 配置多源融合策略：

```yaml
strategy: weighted_average          # 融合策略
default_strategy: weighted_average  # LLM 裁决降级策略
risk_mapping:                       # 风险等级→数值映射
  normal: 0; mild: 1; moderate: 2; high: 3; critical: 4
sources:                            # 各来源权重
  scale_container: {weight: 0.6}
  case_match:      {weight: 0.4}
```

## 技术栈

Python 3.11 · FastAPI · Pydantic v2 · httpx · PyYAML · OpenAI SDK（兜底）

## 相关文档

- 架构决策：父仓库 `docs/decisions/ADR-002-方案推荐模块独立.md`
- 多源融合决策：父仓库 `docs/decisions/ADR-004-案例匹配评估与多源融合.md`
- 治理规范：父仓库 `docs/standards/03-需求与任务管理规范.md`


---

## 医疗免责声明

本项目为研究用途的老年人健康评估技术探索，**不是医疗器械，未取得任何医疗资质**，输出结果**不得用于临床诊断、治疗决策或任何医疗场景**。所有示例数据均为合成数据。使用者自行承担使用风险。完整声明见[父仓 DISCLAIMER.zh.md](../DISCLAIMER.zh.md)。

### 内容资产许可

`app/rules/` 目录下的规则内容为内容资产，采用 CC BY-NC 4.0 许可（见 [app/rules/CONTENT-LICENSE.md](app/rules/CONTENT-LICENSE.md)）；其余代码为 Apache-2.0。

---

## 许可

本项目代码采用 [Apache License 2.0](LICENSE)；许可边界说明见[父仓 NOTICE](../NOTICE.md)。