Metadata-Version: 2.4
Name: parsefood
Version: 0.1.0
Summary: A Python tool that extracts and analyzes food logs from Telegram exports using LLMs
Project-URL: Homepage, https://github.com/tsilva/parsefood
Project-URL: Repository, https://github.com/tsilva/parsefood
Project-URL: Issues, https://github.com/tsilva/parsefood/issues
Author: Tiago Silva
License-Expression: MIT
License-File: LICENSE
Keywords: calorie-tracking,food,llm,nutrition,telegram
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.12
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: boto3>=1.42.5
Requires-Dist: botocore[crt]>=1.42.5
Requires-Dist: gradio>=4.0.0
Requires-Dist: matplotlib
Requires-Dist: openai
Requires-Dist: pandas
Requires-Dist: pillow>=12.0.0
Requires-Dist: playwright>=1.57.0
Requires-Dist: pydantic
Requires-Dist: python-dotenv
Requires-Dist: python-telegram-bot>=22.5
Requires-Dist: pyyaml>=6.0
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: telethon>=1.42.0
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <img src="logo.png" alt="parsefood" width="512"/>

  [![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/downloads/)
  [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
  [![OpenRouter](https://img.shields.io/badge/LLM-OpenRouter-purple.svg)](https://openrouter.ai/)

  **🍽️ Parse food logs from Telegram and track calories with AI 📊**

  [Quick Start](#-quick-start) · [Features](#-features) · [Documentation](#-documentation)
</div>

---

## Overview

**The Pain:** Manually tracking calories from natural-language food notes is tedious, error-prone, and never gets done consistently.

**The Solution:** parsefood connects to your Telegram, reads your food log messages in Portuguese, and uses LLMs to extract ingredients, match them against a structured nutrition database, and calculate calories automatically.

**The Result:** Daily calorie trend visualizations and Telegram bot progress reports — with zero manual data entry.

## Features

- **AI-Powered Extraction** — Uses OpenRouter LLMs (Gemini, GPT, Claude) to parse natural language food entries in Portuguese
- **Structured Food Database** — JSON-based nutrition database with per-100g values and unit conversions
- **Calorie Trend Visualization** — Polynomial regression plots showing intake patterns over time
- **Telegram Bot Integration** — Get daily progress reports with colorful progress bars
- **Multiple Input Methods** — Add foods via product label images (vision AI) or web scraping from supermarket URLs
- **Multi-User Profiles** — YAML-based profile system for tracking multiple users
- **Automatic Backups** — Timestamped backups before any processing

## 🚀 Quick Start

```bash
# Clone and install
git clone https://github.com/tsilva/parsefood.git
cd parsefood
uv sync

# Configure
cp .env.example .env
# Edit .env with your OPENROUTER_API_KEY

# Run
uv run python main.py
```

View your calorie trend at `data/plot.png`.

### Daily Status

```bash
# Quick read-only view of today's progress
uv run python main.py --today
```

## 🔧 Installation

### Prerequisites

- Python 3.12+
- [uv](https://github.com/astral-sh/uv) package manager
- [OpenRouter API key](https://openrouter.ai/keys)

### Setup

```bash
# Install uv (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone repository
git clone https://github.com/tsilva/parsefood.git
cd parsefood

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
```

Edit `.env` with your settings:

```env
MODEL_ID=google/gemini-2.5-flash
OPENROUTER_API_KEY=your_api_key_here
TARGET_CALORIES=2000
BED_TIME=22:00
```

## 📖 Usage

### Processing Food Logs

1. Export your Telegram chat as JSON (or use the built-in Telegram sync)
2. Place the export at `data/result.json`
3. Run the parser:

```bash
uv run python main.py
```

The tool will:
- Back up existing data with timestamps
- Sync latest messages from Telegram
- Parse food log messages using the LLM
- Extract ingredients and calculate calories using the food database
- Generate a calorie trend visualization at `data/plot.png`

### Multi-User Profiles

```bash
# List available profiles
uv run python main.py --list-profiles

# Process with a specific profile
uv run python main.py --profile cristina

# Quick daily status for a profile
uv run python main.py --profile cristina --today
```

Profiles are YAML files in `profiles/`:

```yaml
name: "Cristina"
sender_name: "Cristina"
data_path: "/path/to/data"
target_calories: 2000
```

### Telegram Bot

Get daily calorie progress reports via Telegram.

**Setup:**

1. Create a bot via [@BotFather](https://t.me/botfather) and copy the token
2. Get your chat ID from [@userinfobot](https://t.me/userinfobot)
3. Add to `.env`:
   ```env
   TELEGRAM_BOT_TOKEN=your_bot_token
   TELEGRAM_CHAT_ID=your_chat_id
   ```

**Usage:**

```bash
# Interactive bot mode
uv run python telegram_bot.py --bot

# One-time report (for cron jobs)
uv run python telegram_bot.py
```

Commands: `/start`, `/report`

### Adding Foods to Database

**From product label images:**

```bash
# Place images in labels/ directory (productname_1.jpg, etc.)
uv run python process_labels.py
```

**From supermarket URLs:**

```bash
# Dry-run (display only)
uv run python scrape_food.py URL

# Add to database
uv run python scrape_food.py --add URL

# With custom name
uv run python scrape_food.py --add --name "food name" URL
```

Supported sites: Continente.pt

### Validation

```bash
# Validate all processed data
uv run python main.py validate data/date_messages_map.json

# Inspect specific date
uv run python main.py validate data/date_messages_map.json 2024-03-27

# Quick calorie recalculation check (no LLM)
uv run python scripts/compare_migration.py --quick -n 50
```

## 📁 Data Files

| File | Description |
|------|-------------|
| `data/result.json` | Telegram export (input) |
| `data/date_messages_map.json` | Processed food log data |
| `data/plot.png` | Calorie trend visualization |
| `food_database.json` | Nutrition database |
| `data/backups/` | Timestamped backups |

## 📚 Documentation

- **CLAUDE.md** — Comprehensive architecture guide, data structures, and development workflows
- **docs/pipeline.md** — Detailed data processing pipeline documentation

## License

[MIT License](LICENSE)
