# Nutritional Recipe Parser

A Python application that parses recipes and looks up nutritional information for ingredients using the OpenFoodFacts API.

## Python Version

- **Required:** Python 3.8 or higher
- **Tested on:** Python 3.12.13

## Dependencies

### Python Libraries

The following Python packages are required:

| Package | Purpose | Install Method |
|---------|---------|----------------|
| `requests` | HTTP client for OpenFoodFacts API | `pip install requests` |
| `json` | Built-in | Python 3.x (no install needed) |
| `tkinter` | GUI toolkit (optional) | Usually bundled with Python |

### System Packages (apt)

For a fresh TrueNAS/Ubuntu/Debian environment, install the following:

```bash
sudo apt update
sudo apt install -y python3 python3-pip python3-tk
```

**Explanation:**
- `python3` - The Python interpreter (version 3.12.13 is available on this system)
- `python3-pip` - Pip package manager to install `requests` and other PyPI packages
- `python3-tk` - Tkinter support for the optional GUI mode

### Verifying Installation

After installing, verify the core dependency:

```bash
pip3 install --upgrade requests
```

Test the installation:

```bash
python3 --version
python3 -c "import requests; print('requests version:', requests.__version__)"
```

## Usage

### Command-Line Interface

```bash
# Parse a recipe file and show summary
python3 main.py recipe.md

# Parse and output JSON to a file
python3 main.py recipe.md -o output.json

# Parse with verbose nutrition output
python3 main.py recipe.md -v

# List cached ingredients
python3 main.py --list-foods
```

### GUI Mode

Launch without arguments for a graphical interface:

```bash
python3 main.py
```

## Project Structure

```
nutri_parser/
├── nutri_parser.py    # Core parsing and API logic
├── recipe_parser.py   # Recipe parsing utilities
├── main.py           # Entry point (CLI + GUI)
├── README.md         # This file
└── LICENSE          # Project license
```

## API Integration

This project uses the [OpenFoodFacts](https://world.openfoodfacts.org/) open database API to look up nutritional values for ingredients. The API:

- **Does not require** an API key for basic use
- **Requires** a descriptive `User-Agent` header (set to `"RecipeParser/1.0"` in this project)
- **Recommends** rate limiting (1 request/second minimum) to avoid being blocked
- **Includes** automatic retry with exponential backoff (5 attempts with delays [2, 5, 10, 20, 30] seconds)

## Rate Limiting & Caching

- **Rate limiter:** Enforces 1 request per second minimum between API calls
- **SQLite cache:** Ingredient nutrition data is cached locally to avoid redundant API calls
- **Cache management:** Use `--list-foods` to view cached ingredients, or clear the cache file to refresh

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.