Inital commit for agent

README.md

@@ -0,0 +1,105 @@
+# 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.