Metadata-Version: 2.4
Name: smartplate
Version: 1.2.0
Summary: Knowledge-constrained LLM framework for intelligent meal planning
Author-email: Wu Duo <wuduo@buaa.edu.cn>
License: MIT
Keywords: meal-planning,nutrition,large-language-models,knowledge-constrained-generation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: requests>=2.25.0
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: pillow>=9.0.0
Provides-Extra: vision
Requires-Dist: ultralytics>=8.0.0; extra == "vision"
Requires-Dist: opencv-python>=4.5.0; extra == "vision"
Requires-Dist: transformers>=4.30.0; extra == "vision"
Requires-Dist: torch>=2.0.0; extra == "vision"
Provides-Extra: web
Requires-Dist: streamlit>=1.28.0; extra == "web"
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"

# SmartPlate - 智能配餐助手

## 简介
SmartPlate 是一个智能配餐系统，根据用户画像（日常健康 / 控糖 / 减脂 / 增肌）和营养学规则，
结合大语言模型（LLM）知识约束，生成个性化一日食谱和饮食建议。

## 核心技术架构

```
用户画像 → DRIs 每日营养目标计算
         → LLM + 结构化知识注入（营养数据库 + 份量规则 + 画像约束 + 校验层）
         → 规则引擎兜底（基于本地营养数据库 + 视觉份量系统）
         → 个性化饮食建议输出
```

- **LLM + 知识约束**：将营养数据库、DRIs、份量指南、画像约束注入 prompt，LLM 在领域知识约束下生成食谱，经校验层验证（食物名称、营养偏差、画像违规）后输出
- **规则引擎**：基于本地 79 种食物的营养数据库，按画像评分选取食物，结合手部视觉份量系统生成食谱
- **三级回退**：LLM+知识 → LLM 基线 → 规则引擎，确保离线可用

## 核心功能

- 多画像支持：日常健康 / 糖尿病血糖控制 / 减脂体重控制 / 增肌力量训练
- 个性化 DRIs 计算（基于《中国居民膳食营养素参考摄入量 2023 版》）
- 三种食谱生成模式：LLM+知识约束 / LLM 纯基线 / 规则引擎
- 食物摄入记录与营养累计
- 今日剩余饮食建议与下一餐推荐
- 血糖负荷（GL）分析与控糖提醒
- 个性化膳食建议（基于《中国居民膳食指南 2022》）
- LLM 营养解释（可选，需配置 API Key）

## 安装与运行

```bash
pip install -r requirements.txt

# 交互式菜单（推荐）
python -m src.smartplate.main

# 快速生成一日食谱（规则引擎，无需 API）
python -m src.smartplate.main --mode recipe --no-llm

# 使用 LLM 生成食谱（需配置 .env 中的 API Key）
python -m src.smartplate.main --mode recipe --user diabetes

# 记录食物摄入
python -m src.smartplate.main --mode log --foods "米饭,鸡胸肉,西兰花"

# 运行对比实验（论文第 4 章数据采集）
python scripts/run_thesis_experiment.py --trials 10
```

## 模块说明
```
src/smartplate/
├── main.py              # 主程序入口，命令行参数解析与模式分发
├── cli.py               # 交互式命令行菜单界面
├── meal_planner.py      # 核心配餐引擎（LLM 调度 + 规则引擎兜底 + 食物记录 + 总结）
├── llm_planner.py       # 知识约束型 LLM 配餐引擎（prompt 构建 + 校验 + 纠错）
├── advice_engine.py     # 个性化建议引擎（DRIs 计算 + 营养分析 + GL 计算 + 搭配建议）
├── nutrition_db.py      # 本地营养数据库（79 种食物，含 GI 与微量元素）
├── visual_portion.py    # 视觉份量推荐系统（手掌分量法：拳头/掌心/拇指）
├── reason_engine.py     # 解释引擎（规则 + LLM 文本 + 多模态）
├── experiment.py        # 对比实验框架（论文第 4 章）
├── logging_config.py    # 统一日志系统
└── __init__.py
```

## 用户画像

| 画像 | 说明 | 关键约束 |
|------|------|----------|
| general | 日常健康饮食 | 均衡营养 |
| diabetes | 糖尿病/血糖控制 | 每餐碳水≤60g，GI≤55，GL≤40 |
| weight_loss | 减脂/体重控制 | 热量系数 75%，每餐蛋白≥25g |
| muscle_gain | 增肌/力量训练 | 热量系数 110%，每餐蛋白≥30g，碳水≥60g |

## 环境配置

在项目根目录创建 `.env` 文件：

```
LLM_API_KEY=your-api-key
LLM_API_URL=https://open.bigmodel.cn/api/paas/v4/chat/completions
LLM_MODEL=glm-4-flash
```

不配置 API Key 时，系统自动使用规则引擎，所有核心功能均可正常使用。
