parsefood 0.1.0

A Python tool that extracts and analyzes food logs from Telegram exports using LLMs

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

Quick Start · Features · Documentation

---

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

# 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

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

🔧 Installation

Prerequisites

• Python 3.12+
• uv package manager
• OpenRouter API key

Setup

# 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:

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:

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

# 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/:

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 and copy the token
2. Get your chat ID from @userinfobot
3. Add to .env:

   TELEGRAM_BOT_TOKEN=your_bot_token
   TELEGRAM_CHAT_ID=your_chat_id
   

Usage:

# 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:

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

From supermarket URLs:

# 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

# 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