# 🥑 Avocavo Nutrition API Python SDK
[](https://badge.fury.io/py/avocavo-nutrition)
[](https://pypi.org/project/avocavo-nutrition/)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/projects/avocavo-nutrition)
**Bulletproof nutrition data with anti-hallucination protection + enterprise-grade secure credential storage.**
Get 100% reliable USDA nutrition data powered by our bulletproof system. Multi-tier caching, intelligent parsing, and mathematical calculations ensure accuracy. Real FDC IDs, sub-second responses, and accepts any ingredient description format. **Built-in secure keyring storage** keeps your API credentials safe. Perfect for recipe apps, fitness trackers, meal planners, and food tech products.
### ✨ Key Features
- ✅ **Secure credential storage** - System keyring integration (macOS/Windows/Linux)
- ✅ **100% USDA verified** - Real FDC IDs with every response
- ✅ **Anti-hallucination** - GPT never provides nutrition data
- ✅ **Sub-second responses** - Multi-tier caching system
- ✅ **Any input format** - Natural language processing
- ✅ **Production ready** - OAuth, server-side key management, batch processing
## 🚀 Quick Start
### Installation
```bash
pip install avocavo-nutrition
```
### 🔐 Two-Step Authentication (Recommended)
Modern OAuth + API key system for maximum security:
```python
import avocavo_nutrition as av
# Step 1: OAuth login (stores JWT token securely)
av.login() # Google OAuth by default
# av.login(provider="github") # Or GitHub OAuth
# Step 2: Create/manage API keys with JWT authentication
result = av.create_api_key(
name="My App Key",
description="Production API key for my recipe app",
environment="production"
)
print(f"Created key: {result['key']['api_key']}")
# Step 3: Use nutrition API (automatically uses stored API key)
nutrition = av.analyze_ingredient("2 cups chocolate chips")
print(f"Calories: {nutrition.nutrition.calories_total}")
print(f"Protein: {nutrition.nutrition.protein_total}g")
print(f"USDA: {nutrition.usda_match.description}")
```
### 🔑 API Key Management
```python
# List all your API keys
keys = av.list_api_keys()
for key in keys['keys']:
print(f"{key['key_name']}: {key['monthly_usage']}/{key['monthly_limit']}")
# Switch to different API key
av.switch_to_api_key("sk_prod_abc123...")
# Delete old keys
av.delete_api_key(key_id=123)
```
### 🚀 Alternative Methods
```python
# Method 1: Direct API key (if you already have one)
client = av.NutritionAPI(api_key="sk_starter_your_api_key_here")
# Method 2: Environment variable (for CI/CD)
# export AVOCAVO_API_KEY=sk_starter_your_api_key_here
result = av.analyze_ingredient("2 cups flour")
```
### 🔐 Secure Credential Management
The Python SDK uses a modern two-step authentication system:
1. **JWT Tokens**: For identity verification and API key management
2. **API Keys**: For actual nutrition API requests
All credentials are stored securely using your system's keyring:
- **macOS**: Stored in Keychain (same as Safari, Chrome)
- **Windows**: Stored in Credential Manager
- **Linux**: Stored in Secret Service (gnome-keyring, kwallet)
```python
# One-time OAuth login - JWT token stored securely
av.login() # Opens browser for Google OAuth
# Create API keys using JWT authentication
new_key = av.create_api_key(
name="Production Key",
environment="production"
)
# Use anywhere in your projects - API key automatically used
result = av.analyze_ingredient("1 cup quinoa")
print(f"✅ {result.nutrition.calories_total} calories")
# Check login status
user = av.get_current_user()
if user:
print(f"Logged in as: {user['email']}")
# Logout and clear credentials
av.logout()
```
### 🔑 Direct API Key (Legacy)
If you already have an API key, you can use it directly:
```python
from avocavo_nutrition import NutritionAPI
# Use existing API key directly
client = NutritionAPI(api_key="sk_starter_your_api_key_here")
result = client.analyze_ingredient("1 cup rice")
print(f"Calories: {result.nutrition.calories_total}")
# Or via environment variable
import os
os.environ['AVOCAVO_API_KEY'] = 'sk_starter_your_api_key_here'
result = av.analyze_ingredient("1 cup rice") # Uses env var automatically
```
## 🎯 100% USDA Data
**All nutrition data comes from USDA FoodData Central** - the official U.S. government nutrition database. AI is used only for intelligent matching to find the best USDA food entry for your ingredient. No hallucination, no made-up data.
## ⚡ Any Input Format
**No rigid formatting required - describe ingredients any way you want:**
```python
# Descriptive ingredients
result = av.analyze_ingredient("2 tablespoons of extra virgin olive oil")
# Any style works
result = av.analyze_ingredient("I'm using about 1 cup of chicken breast, grilled")
# Precise or approximate
result = av.analyze_ingredient("100g brown rice, cooked")
# Include preparation details
result = av.analyze_ingredient("2 cups flour (all-purpose, for baking)")
```
**Bulletproof USDA matching with 94%+ cache hit rate and anti-hallucination protection.**
## 🎯 What You Can Do
### 🥘 Analyze Ingredients
```python
# Any ingredient with quantity - flexible input formats
result = av.analyze_ingredient("2 tbsp olive oil")
if result.success:
print(f"Calories: {result.nutrition.calories}")
print(f"Fat: {result.nutrition.fat}g")
print(f"Verify: {result.verification_url}")
```
### 🍳 Analyze Complete Recipes
```python
# Full recipe with per-serving calculations
recipe = av.analyze_recipe([
"2 cups all-purpose flour",
"1 cup whole milk",
"2 large eggs",
"1/4 cup sugar"
], servings=8)
print(f"Per serving: {recipe.nutrition.per_serving.calories} calories")
print(f"Total recipe: {recipe.nutrition.total.calories} calories")
```
### ⚡ Batch Processing
```python
# Analyze multiple ingredients efficiently
# Batch limits: Free (5), Starter (10), Professional (20), Enterprise (50+) ingredients
batch = av.analyze_batch([
"1 cup quinoa",
"2 tbsp olive oil",
"4 oz salmon",
"1 cup spinach"
])
for item in batch.results:
if item.success:
print(f"{item.ingredient}: {item.nutrition.calories} cal")
```
### 📊 Account Management
```python
# Check your usage and limits
account = av.get_account_usage()
print(f"Plan: {account.plan_name}")
print(f"Usage: {account.usage.current_month}/{account.usage.monthly_limit}")
print(f"Remaining: {account.usage.remaining}")
```
## ✨ Bulletproof Features
### 🛡️ **Anti-Hallucination Protection**
- **Smart USDA Matching**: AI used only for intelligent matching to USDA database
- **Verified Database Search**: All matches verified against real USDA FoodData Central
- **Mathematical Calculation Only**: Nutrition = (USDA_per_100g × grams) ÷ 100
- **Zero AI Nutrition Data**: 100% database-sourced nutrition facts
- **Transparent Tier System**: Shows exactly how each ingredient was matched
### 🔄 **10-Layer Bulletproof Flow**
1. 🚀 **Redis Cache**: Instant exact match (sub-1ms)
2. 💾 **Supabase Cache**: Persistent exact match (1-5ms)
3. 🧠 **Intelligent Parsing**: Extract ingredient + quantity + unit
4. 📏 **Deterministic Conversion**: Unit → grams using conversion tables
5. 🎯 **SQL Exact Search**: Direct USDA database lookup
6. 🔍 **Fuzzy Match**: High-confidence fuzzy matching (90%+)
7. 🤖 **Smart USDA Matching**: Intelligent matching to USDA database
8. 🛡️ **Validated Search**: Verify all matches against USDA data
9. 🧮 **Mathematical Calculation**: Scale nutrition to actual quantity
10. 💾 **Multi-Tier Caching**: Store for future instant access
### 🎯 **Bulletproof USDA Accuracy**
- **Anti-hallucination protection**: AI never provides nutrition data
- Real FDC IDs from USDA FoodData Central
- **Mathematical calculations**: Handles missing calories (Protein×4 + Carbs×4 + Fat×9)
- **Smart zero-calorie detection** for ingredients like salt and water
- Verification URLs for manual checking
- **7-tier parsing system** shows exactly how each ingredient was matched
- **10-layer bulletproof flow** ensures 100% reliability
### ⚡ **Bulletproof Performance**
- **94%+ cache hit rate** = sub-second responses
- **8,000+ requests/hour** throughput
- **Multi-tier caching**: Redis → Supabase → Local USDA
- **Anti-hallucination protection** with verified calculations
- **Mathematical calorie calculation** for missing nutrients
### 🔧 **Any Input Format**
- Handles "2 cups flour" or "1 lb chicken breast"
- Any ingredient description style
- Automatic quantity and measurement parsing
- No rigid formatting requirements
### 🛠️ **Developer Friendly**
- Secure credential storage with `keyring`
- Type hints and comprehensive error handling
- Works with environment variables
- Detailed documentation and examples
## 📊 Complete Nutrition Data
```python
result = av.analyze_ingredient("1 cup cooked rice")
nutrition = result.nutrition
# All available nutrients
print(f"Calories: {nutrition.calories}")
print(f"Protein: {nutrition.protein}g")
print(f"Carbs: {nutrition.carbs}g")
print(f"Fat: {nutrition.fat}g")
print(f"Fiber: {nutrition.fiber}g")
print(f"Sugar: {nutrition.sugar}g")
print(f"Sodium: {nutrition.sodium}mg")
print(f"Calcium: {nutrition.calcium}mg")
print(f"Iron: {nutrition.iron}mg")
```
## 💰 Pricing Plans
| Plan | Monthly Calls | Price | Batch Limit | Features |
|------|---------------|-------|-------------|----------|
| **Free** | 1,000 | **Free** | 5 ingredients | Basic nutrition analysis |
| **Starter** | 5,000 | $4.99/month | 10 ingredients | Full API access, priority support |
| **Professional** | 10,000 | $8.99/month | 20 ingredients | Advanced features, production use |
| **Business** | 50,000 | $39.99/month | 50+ ingredients | High volume, custom limits available |
### Pay-As-You-Go Credits
Need more calls? Purchase credits anytime:
- **$1** = 1,000 additional calls
- **$5** = 5,000 additional calls
- **$10** = 10,000 additional calls
- **$25** = 25,000 additional calls
- **$50** = 50,000 additional calls
- **$100** = 100,000 additional calls
Credits never expire and work with any plan!
[**Get your API key →**](https://nutrition.avocavo.app)
## 🔐 Authentication Options
### Option 1: Login (Recommended)
```python
import avocavo_nutrition as av
# Login once, use everywhere
av.login("user@example.com", "password")
# Credentials stored securely with keyring
result = av.analyze_ingredient("1 cup rice")
```
### Option 2: API Key
```python
from avocavo_nutrition import NutritionAPI
# Direct API key usage
client = NutritionAPI(api_key="your_api_key")
result = client.analyze_ingredient("1 cup rice")
```
### Option 3: Environment Variable
```bash
export AVOCAVO_API_KEY="your_api_key_here"
```
```python
import avocavo_nutrition as av
# API key automatically detected from environment
result = av.analyze_ingredient("1 cup rice")
```
## 🏗️ Real-World Examples
### Recipe App Integration
```python
import avocavo_nutrition as av
def calculate_recipe_nutrition(ingredients, servings=1):
"""Calculate nutrition for any recipe"""
recipe = av.analyze_recipe(ingredients, servings)
if recipe.success:
return {
'calories_per_serving': recipe.nutrition.per_serving.calories,
'protein_per_serving': recipe.nutrition.per_serving.protein,
'total_calories': recipe.nutrition.total.calories,
'usda_verified_ingredients': recipe.usda_matches
}
else:
return {'error': recipe.error}
# Usage
recipe_nutrition = calculate_recipe_nutrition([
"2 cups flour",
"1 cup milk",
"2 eggs"
], servings=6)
```
### Fitness Tracker Integration
```python
def track_daily_nutrition(food_entries):
"""Track daily nutrition from food entries"""
total_nutrition = {
'calories': 0,
'protein': 0,
'carbs': 0,
'fat': 0
}
for food in food_entries:
result = av.analyze_ingredient(food)
if result.success:
total_nutrition['calories'] += result.nutrition.calories
total_nutrition['protein'] += result.nutrition.protein
total_nutrition['carbs'] += result.nutrition.carbs
total_nutrition['fat'] += result.nutrition.fat
return total_nutrition
# Usage
daily_foods = [
"1 cup oatmeal",
"1 medium banana",
"6 oz grilled chicken",
"2 cups steamed broccoli"
]
daily_totals = track_daily_nutrition(daily_foods)
```
### Restaurant Menu Analysis
```python
def analyze_menu_item(ingredients):
"""Analyze nutrition for restaurant menu items"""
# Use batch processing for efficiency
# Batch limits: Free (5), Starter (10), Professional (20), Enterprise (50+) ingredients
batch = av.analyze_batch(ingredients)
total_calories = sum(
item.nutrition.calories
for item in batch.results
if item.success
)
return {
'total_calories': total_calories,
'success_rate': batch.success_rate,
'ingredients_analyzed': batch.successful_matches
}
```
## 🛠️ Advanced Usage
### Error Handling
```python
from avocavo_nutrition import ApiError, RateLimitError, AuthenticationError
try:
result = av.analyze_ingredient("mystery ingredient")
if result.success:
print(f"Found: {result.usda_match.description}")
else:
print(f"No match: {result.error}")
except RateLimitError as e:
print(f"Rate limit exceeded. Limit: {e.limit}, Usage: {e.usage}")
except AuthenticationError as e:
print(f"Auth error: {e.message}")
except ApiError as e:
print(f"API Error: {e.message}")
```
### Configuration
```python
# Use development environment
client = NutritionAPI(
api_key="your_key",
base_url="https://devapp.avocavo.app", # Dev environment
timeout=60 # Custom timeout
)
# Check API health
health = client.health_check()
print(f"API Status: {health['status']}")
print(f"Cache Hit Rate: {health['cache']['hit_rate']}")
```
### User Management
```python
# Check login status
if av.is_logged_in():
user = av.get_current_user()
print(f"Logged in as: {user['email']}")
else:
print("Please login: av.login()") # OAuth browser login
# Login with different provider
av.login(provider="github") # GitHub OAuth instead of Google
# Logout
result = av.logout()
print(result['message']) # "Successfully logged out"
```
## 🔍 What Information You Get
The Avocavo Nutrition API provides comprehensive nutrition data with USDA verification:
### Core Nutrition Facts
- **Calories** - Energy content
- **Macronutrients** - Protein, carbohydrates, total fat
- **Fiber & Sugar** - Detailed carbohydrate breakdown
- **Minerals** - Sodium, calcium, iron
- **Fats** - Saturated fat, cholesterol
### USDA Verification
- **Real FDC IDs** from USDA FoodData Central
- **Verification URLs** for manual checking
- **Data source types** (Foundation, SR Legacy, Survey, Branded)
- **Confidence scores** for match quality
### Bulletproof System Metrics
- **Cache layer hit** - Which cache tier provided the data
- **Processing method** - Exact path through bulletproof flow
- **Anti-hallucination status** - Verification that no AI nutrition data was used
- **Mathematical verification** - Confirmation of calculated vs database nutrition
- **Response times** - Sub-second bulletproof performance tracking
### Complete API Response Fields
```python
result = av.analyze_ingredient("1 cup cooked brown rice")
# Core nutrition data (100% mathematical calculation)
print(f"Calories: {result.nutrition.calories}") # 216.0
print(f"Protein: {result.nutrition.protein}g") # 5.0
print(f"Carbs: {result.nutrition.carbs}g") # 45.0
print(f"Fiber: {result.nutrition.fiber}g") # 3.5
print(f"Calcium: {result.nutrition.calcium_total}mg") # 23.0
print(f"Iron: {result.nutrition.iron_total}mg") # 0.8
# USDA verification (bulletproof source)
print(f"FDC ID: {result.usda_match.fdc_id}") # 168880
print(f"Description: {result.usda_match.description}") # "Rice, brown, long-grain, cooked"
print(f"Data Type: {result.usda_match.data_type}") # "foundation_food"
print(f"Verify: {result.verification_url}") # USDA verification link
# System performance & caching
print(f"From Cache: {result.from_cache}") # True/False
print(f"Cache Type: {result.cache_type}") # "redis" | "supabase" | None
print(f"Processing Time: {result.processing_time_ms}ms") # 15.2 (bulletproof speed)
print(f"Method Used: {result.method_used}") # "llm_driven_search" | "sql_exact" | "fuzzy_match"
# Parsing details
print(f"Estimated Grams: {result.estimated_grams}") # 195.0
print(f"Parsed Name: {result.ingredient_name}") # "1 cup cooked brown rice"
```
## Recipe Results with Individual Ingredient Details
```python
recipe = av.analyze_recipe([
"2 cups all-purpose flour",
"1 cup whole milk"
], servings=4)
# Recipe-level data
print(f"Total Calories: {recipe.nutrition.total.calories}") # 1862.21
print(f"Per Serving: {recipe.nutrition.per_serving.calories}") # 465.55
print(f"USDA Matches: {recipe.usda_matches}") # 2
print(f"Processing Time: {recipe.processing_time_ms}ms") # 5.3
# Note: All nutrition data is USDA-verifiable via included FDC IDs and verification URLs
# Individual ingredient details
for ingredient in recipe.nutrition.ingredients:
print(f"Ingredient: {ingredient.ingredient}")
print(f" Calories: {ingredient.nutrition.calories}")
print(f" USDA: {ingredient.usda_match.description}")
print(f" Verify: {ingredient.verification_url}")
```
## 📚 Documentation
- **[Complete API Documentation](https://nutrition.avocavo.app/docs/python)** - Full reference
- **[Get API Key](https://nutrition.avocavo.app)** - Sign up for free
- **[GitHub Repository](https://github.com/avocavo/nutrition-api-python)** - Source code
- **[Support](mailto:api-support@avocavo.com)** - Get help
## 🤝 Support
- **Email**: [api-support@avocavo.com](mailto:api-support@avocavo.com)
- **Documentation**: [nutrition.avocavo.app/docs/python](https://nutrition.avocavo.app/docs/python)
- **Status Page**: [status.avocavo.app](https://status.avocavo.app)
- **Feature Requests**: [GitHub Issues](https://github.com/avocavo/nutrition-api-python/issues)
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
**Made with ❤️ by the Avocavo team**
*Get started in 30 seconds: `pip install avocavo-nutrition`*
Raw data
{
"_id": null,
"home_page": "https://github.com/avocavo/nutrition-api-python",
"name": "avocavo-nutrition",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "nutrition, api, usda, food, recipe, health, fitness, calories, macros, nutrients, fooddata, fdc, cooking, meal-planning, diet, wellness, restaurant, food-tech",
"author": "Avocavo",
"author_email": "Avocavo <support@avocavo.com>",
"download_url": "https://files.pythonhosted.org/packages/d7/e0/d90acae75f260058b6d3dbe5b5f20a912b7fced9cb0b85bd0b59ccd3530b/avocavo_nutrition-1.8.4.tar.gz",
"platform": "any",
"description": "# \ud83e\udd51 Avocavo Nutrition API Python SDK\n\n[](https://badge.fury.io/py/avocavo-nutrition)\n[](https://pypi.org/project/avocavo-nutrition/)\n[](https://opensource.org/licenses/MIT)\n[](https://pepy.tech/projects/avocavo-nutrition)\n\n**Bulletproof nutrition data with anti-hallucination protection + enterprise-grade secure credential storage.**\n\nGet 100% reliable USDA nutrition data powered by our bulletproof system. Multi-tier caching, intelligent parsing, and mathematical calculations ensure accuracy. Real FDC IDs, sub-second responses, and accepts any ingredient description format. **Built-in secure keyring storage** keeps your API credentials safe. Perfect for recipe apps, fitness trackers, meal planners, and food tech products.\n\n### \u2728 Key Features\n- \u2705 **Secure credential storage** - System keyring integration (macOS/Windows/Linux)\n- \u2705 **100% USDA verified** - Real FDC IDs with every response\n- \u2705 **Anti-hallucination** - GPT never provides nutrition data\n- \u2705 **Sub-second responses** - Multi-tier caching system\n- \u2705 **Any input format** - Natural language processing\n- \u2705 **Production ready** - OAuth, server-side key management, batch processing\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install avocavo-nutrition\n```\n\n### \ud83d\udd10 Two-Step Authentication (Recommended)\n\nModern OAuth + API key system for maximum security:\n\n```python\nimport avocavo_nutrition as av\n\n# Step 1: OAuth login (stores JWT token securely)\nav.login() # Google OAuth by default\n# av.login(provider=\"github\") # Or GitHub OAuth\n\n# Step 2: Create/manage API keys with JWT authentication\nresult = av.create_api_key(\n name=\"My App Key\",\n description=\"Production API key for my recipe app\",\n environment=\"production\"\n)\nprint(f\"Created key: {result['key']['api_key']}\")\n\n# Step 3: Use nutrition API (automatically uses stored API key)\nnutrition = av.analyze_ingredient(\"2 cups chocolate chips\")\nprint(f\"Calories: {nutrition.nutrition.calories_total}\")\nprint(f\"Protein: {nutrition.nutrition.protein_total}g\")\nprint(f\"USDA: {nutrition.usda_match.description}\")\n```\n\n### \ud83d\udd11 API Key Management\n\n```python\n# List all your API keys\nkeys = av.list_api_keys()\nfor key in keys['keys']:\n print(f\"{key['key_name']}: {key['monthly_usage']}/{key['monthly_limit']}\")\n\n# Switch to different API key\nav.switch_to_api_key(\"sk_prod_abc123...\")\n\n# Delete old keys\nav.delete_api_key(key_id=123)\n```\n\n### \ud83d\ude80 Alternative Methods\n\n```python\n# Method 1: Direct API key (if you already have one)\nclient = av.NutritionAPI(api_key=\"sk_starter_your_api_key_here\")\n\n# Method 2: Environment variable (for CI/CD)\n# export AVOCAVO_API_KEY=sk_starter_your_api_key_here\nresult = av.analyze_ingredient(\"2 cups flour\")\n```\n\n### \ud83d\udd10 Secure Credential Management\n\nThe Python SDK uses a modern two-step authentication system:\n\n1. **JWT Tokens**: For identity verification and API key management\n2. **API Keys**: For actual nutrition API requests\n\nAll credentials are stored securely using your system's keyring:\n\n- **macOS**: Stored in Keychain (same as Safari, Chrome)\n- **Windows**: Stored in Credential Manager \n- **Linux**: Stored in Secret Service (gnome-keyring, kwallet)\n\n```python\n# One-time OAuth login - JWT token stored securely\nav.login() # Opens browser for Google OAuth\n\n# Create API keys using JWT authentication\nnew_key = av.create_api_key(\n name=\"Production Key\",\n environment=\"production\"\n)\n\n# Use anywhere in your projects - API key automatically used\nresult = av.analyze_ingredient(\"1 cup quinoa\")\nprint(f\"\u2705 {result.nutrition.calories_total} calories\")\n\n# Check login status\nuser = av.get_current_user()\nif user:\n print(f\"Logged in as: {user['email']}\")\n \n# Logout and clear credentials \nav.logout()\n```\n\n### \ud83d\udd11 Direct API Key (Legacy)\n\nIf you already have an API key, you can use it directly:\n\n```python\nfrom avocavo_nutrition import NutritionAPI\n\n# Use existing API key directly\nclient = NutritionAPI(api_key=\"sk_starter_your_api_key_here\")\nresult = client.analyze_ingredient(\"1 cup rice\")\nprint(f\"Calories: {result.nutrition.calories_total}\")\n\n# Or via environment variable\nimport os\nos.environ['AVOCAVO_API_KEY'] = 'sk_starter_your_api_key_here'\nresult = av.analyze_ingredient(\"1 cup rice\") # Uses env var automatically\n```\n\n## \ud83c\udfaf 100% USDA Data\n\n**All nutrition data comes from USDA FoodData Central** - the official U.S. government nutrition database. AI is used only for intelligent matching to find the best USDA food entry for your ingredient. No hallucination, no made-up data.\n\n## \u26a1 Any Input Format\n\n**No rigid formatting required - describe ingredients any way you want:**\n\n```python\n# Descriptive ingredients\nresult = av.analyze_ingredient(\"2 tablespoons of extra virgin olive oil\")\n\n# Any style works\nresult = av.analyze_ingredient(\"I'm using about 1 cup of chicken breast, grilled\")\n\n# Precise or approximate\nresult = av.analyze_ingredient(\"100g brown rice, cooked\")\n\n# Include preparation details\nresult = av.analyze_ingredient(\"2 cups flour (all-purpose, for baking)\")\n```\n\n**Bulletproof USDA matching with 94%+ cache hit rate and anti-hallucination protection.**\n\n## \ud83c\udfaf What You Can Do\n\n### \ud83e\udd58 Analyze Ingredients\n```python\n# Any ingredient with quantity - flexible input formats\nresult = av.analyze_ingredient(\"2 tbsp olive oil\")\nif result.success:\n print(f\"Calories: {result.nutrition.calories}\")\n print(f\"Fat: {result.nutrition.fat}g\")\n print(f\"Verify: {result.verification_url}\")\n```\n\n### \ud83c\udf73 Analyze Complete Recipes\n```python\n# Full recipe with per-serving calculations\nrecipe = av.analyze_recipe([\n \"2 cups all-purpose flour\",\n \"1 cup whole milk\",\n \"2 large eggs\", \n \"1/4 cup sugar\"\n], servings=8)\n\nprint(f\"Per serving: {recipe.nutrition.per_serving.calories} calories\")\nprint(f\"Total recipe: {recipe.nutrition.total.calories} calories\")\n```\n\n### \u26a1 Batch Processing\n```python\n# Analyze multiple ingredients efficiently\n# Batch limits: Free (5), Starter (10), Professional (20), Enterprise (50+) ingredients\nbatch = av.analyze_batch([\n \"1 cup quinoa\",\n \"2 tbsp olive oil\", \n \"4 oz salmon\",\n \"1 cup spinach\"\n])\n\nfor item in batch.results:\n if item.success:\n print(f\"{item.ingredient}: {item.nutrition.calories} cal\")\n```\n\n### \ud83d\udcca Account Management\n```python\n# Check your usage and limits\naccount = av.get_account_usage()\nprint(f\"Plan: {account.plan_name}\")\nprint(f\"Usage: {account.usage.current_month}/{account.usage.monthly_limit}\")\nprint(f\"Remaining: {account.usage.remaining}\")\n```\n\n## \u2728 Bulletproof Features\n\n### \ud83d\udee1\ufe0f **Anti-Hallucination Protection**\n- **Smart USDA Matching**: AI used only for intelligent matching to USDA database\n- **Verified Database Search**: All matches verified against real USDA FoodData Central\n- **Mathematical Calculation Only**: Nutrition = (USDA_per_100g \u00d7 grams) \u00f7 100\n- **Zero AI Nutrition Data**: 100% database-sourced nutrition facts\n- **Transparent Tier System**: Shows exactly how each ingredient was matched\n\n### \ud83d\udd04 **10-Layer Bulletproof Flow**\n1. \ud83d\ude80 **Redis Cache**: Instant exact match (sub-1ms)\n2. \ud83d\udcbe **Supabase Cache**: Persistent exact match (1-5ms)\n3. \ud83e\udde0 **Intelligent Parsing**: Extract ingredient + quantity + unit\n4. \ud83d\udccf **Deterministic Conversion**: Unit \u2192 grams using conversion tables\n5. \ud83c\udfaf **SQL Exact Search**: Direct USDA database lookup\n6. \ud83d\udd0d **Fuzzy Match**: High-confidence fuzzy matching (90%+)\n7. \ud83e\udd16 **Smart USDA Matching**: Intelligent matching to USDA database\n8. \ud83d\udee1\ufe0f **Validated Search**: Verify all matches against USDA data\n9. \ud83e\uddee **Mathematical Calculation**: Scale nutrition to actual quantity\n10. \ud83d\udcbe **Multi-Tier Caching**: Store for future instant access\n\n### \ud83c\udfaf **Bulletproof USDA Accuracy**\n- **Anti-hallucination protection**: AI never provides nutrition data\n- Real FDC IDs from USDA FoodData Central\n- **Mathematical calculations**: Handles missing calories (Protein\u00d74 + Carbs\u00d74 + Fat\u00d79)\n- **Smart zero-calorie detection** for ingredients like salt and water\n- Verification URLs for manual checking\n- **7-tier parsing system** shows exactly how each ingredient was matched\n- **10-layer bulletproof flow** ensures 100% reliability\n\n### \u26a1 **Bulletproof Performance**\n- **94%+ cache hit rate** = sub-second responses \n- **8,000+ requests/hour** throughput\n- **Multi-tier caching**: Redis \u2192 Supabase \u2192 Local USDA\n- **Anti-hallucination protection** with verified calculations\n- **Mathematical calorie calculation** for missing nutrients\n\n### \ud83d\udd27 **Any Input Format**\n- Handles \"2 cups flour\" or \"1 lb chicken breast\"\n- Any ingredient description style\n- Automatic quantity and measurement parsing\n- No rigid formatting requirements\n\n### \ud83d\udee0\ufe0f **Developer Friendly**\n- Secure credential storage with `keyring`\n- Type hints and comprehensive error handling\n- Works with environment variables\n- Detailed documentation and examples\n\n## \ud83d\udcca Complete Nutrition Data\n\n```python\nresult = av.analyze_ingredient(\"1 cup cooked rice\")\nnutrition = result.nutrition\n\n# All available nutrients\nprint(f\"Calories: {nutrition.calories}\")\nprint(f\"Protein: {nutrition.protein}g\")\nprint(f\"Carbs: {nutrition.carbs}g\") \nprint(f\"Fat: {nutrition.fat}g\")\nprint(f\"Fiber: {nutrition.fiber}g\")\nprint(f\"Sugar: {nutrition.sugar}g\")\nprint(f\"Sodium: {nutrition.sodium}mg\")\nprint(f\"Calcium: {nutrition.calcium}mg\")\nprint(f\"Iron: {nutrition.iron}mg\")\n```\n\n## \ud83d\udcb0 Pricing Plans\n\n| Plan | Monthly Calls | Price | Batch Limit | Features |\n|------|---------------|-------|-------------|----------|\n| **Free** | 1,000 | **Free** | 5 ingredients | Basic nutrition analysis |\n| **Starter** | 5,000 | $4.99/month | 10 ingredients | Full API access, priority support |\n| **Professional** | 10,000 | $8.99/month | 20 ingredients | Advanced features, production use |\n| **Business** | 50,000 | $39.99/month | 50+ ingredients | High volume, custom limits available |\n\n### Pay-As-You-Go Credits\nNeed more calls? Purchase credits anytime:\n- **$1** = 1,000 additional calls\n- **$5** = 5,000 additional calls \n- **$10** = 10,000 additional calls\n- **$25** = 25,000 additional calls\n- **$50** = 50,000 additional calls\n- **$100** = 100,000 additional calls\n\nCredits never expire and work with any plan!\n\n[**Get your API key \u2192**](https://nutrition.avocavo.app)\n\n## \ud83d\udd10 Authentication Options\n\n### Option 1: Login (Recommended)\n```python\nimport avocavo_nutrition as av\n\n# Login once, use everywhere\nav.login(\"user@example.com\", \"password\")\n\n# Credentials stored securely with keyring\nresult = av.analyze_ingredient(\"1 cup rice\")\n```\n\n### Option 2: API Key\n```python\nfrom avocavo_nutrition import NutritionAPI\n\n# Direct API key usage\nclient = NutritionAPI(api_key=\"your_api_key\")\nresult = client.analyze_ingredient(\"1 cup rice\")\n```\n\n### Option 3: Environment Variable\n```bash\nexport AVOCAVO_API_KEY=\"your_api_key_here\"\n```\n\n```python\nimport avocavo_nutrition as av\n# API key automatically detected from environment\nresult = av.analyze_ingredient(\"1 cup rice\")\n```\n\n## \ud83c\udfd7\ufe0f Real-World Examples\n\n### Recipe App Integration\n```python\nimport avocavo_nutrition as av\n\ndef calculate_recipe_nutrition(ingredients, servings=1):\n \"\"\"Calculate nutrition for any recipe\"\"\"\n recipe = av.analyze_recipe(ingredients, servings)\n \n if recipe.success:\n return {\n 'calories_per_serving': recipe.nutrition.per_serving.calories,\n 'protein_per_serving': recipe.nutrition.per_serving.protein,\n 'total_calories': recipe.nutrition.total.calories,\n 'usda_verified_ingredients': recipe.usda_matches\n }\n else:\n return {'error': recipe.error}\n\n# Usage\nrecipe_nutrition = calculate_recipe_nutrition([\n \"2 cups flour\",\n \"1 cup milk\", \n \"2 eggs\"\n], servings=6)\n```\n\n### Fitness Tracker Integration \n```python\ndef track_daily_nutrition(food_entries):\n \"\"\"Track daily nutrition from food entries\"\"\"\n total_nutrition = {\n 'calories': 0,\n 'protein': 0,\n 'carbs': 0,\n 'fat': 0\n }\n \n for food in food_entries:\n result = av.analyze_ingredient(food)\n if result.success:\n total_nutrition['calories'] += result.nutrition.calories\n total_nutrition['protein'] += result.nutrition.protein\n total_nutrition['carbs'] += result.nutrition.carbs\n total_nutrition['fat'] += result.nutrition.fat\n \n return total_nutrition\n\n# Usage\ndaily_foods = [\n \"1 cup oatmeal\",\n \"1 medium banana\", \n \"6 oz grilled chicken\",\n \"2 cups steamed broccoli\"\n]\ndaily_totals = track_daily_nutrition(daily_foods)\n```\n\n### Restaurant Menu Analysis\n```python\ndef analyze_menu_item(ingredients):\n \"\"\"Analyze nutrition for restaurant menu items\"\"\"\n # Use batch processing for efficiency\n # Batch limits: Free (5), Starter (10), Professional (20), Enterprise (50+) ingredients \n batch = av.analyze_batch(ingredients)\n \n total_calories = sum(\n item.nutrition.calories \n for item in batch.results \n if item.success\n )\n \n return {\n 'total_calories': total_calories,\n 'success_rate': batch.success_rate,\n 'ingredients_analyzed': batch.successful_matches\n }\n```\n\n## \ud83d\udee0\ufe0f Advanced Usage\n\n### Error Handling\n```python\nfrom avocavo_nutrition import ApiError, RateLimitError, AuthenticationError\n\ntry:\n result = av.analyze_ingredient(\"mystery ingredient\")\n if result.success:\n print(f\"Found: {result.usda_match.description}\")\n else:\n print(f\"No match: {result.error}\")\n \nexcept RateLimitError as e:\n print(f\"Rate limit exceeded. Limit: {e.limit}, Usage: {e.usage}\")\nexcept AuthenticationError as e:\n print(f\"Auth error: {e.message}\")\nexcept ApiError as e:\n print(f\"API Error: {e.message}\")\n```\n\n### Configuration\n```python\n# Use development environment\nclient = NutritionAPI(\n api_key=\"your_key\",\n base_url=\"https://devapp.avocavo.app\", # Dev environment\n timeout=60 # Custom timeout\n)\n\n# Check API health\nhealth = client.health_check()\nprint(f\"API Status: {health['status']}\")\nprint(f\"Cache Hit Rate: {health['cache']['hit_rate']}\")\n```\n\n### User Management\n```python\n# Check login status\nif av.is_logged_in():\n user = av.get_current_user()\n print(f\"Logged in as: {user['email']}\")\nelse:\n print(\"Please login: av.login()\") # OAuth browser login\n\n# Login with different provider\nav.login(provider=\"github\") # GitHub OAuth instead of Google\n\n# Logout\nresult = av.logout()\nprint(result['message']) # \"Successfully logged out\"\n```\n\n## \ud83d\udd0d What Information You Get\n\nThe Avocavo Nutrition API provides comprehensive nutrition data with USDA verification:\n\n### Core Nutrition Facts\n- **Calories** - Energy content\n- **Macronutrients** - Protein, carbohydrates, total fat\n- **Fiber & Sugar** - Detailed carbohydrate breakdown \n- **Minerals** - Sodium, calcium, iron\n- **Fats** - Saturated fat, cholesterol\n\n### USDA Verification\n- **Real FDC IDs** from USDA FoodData Central\n- **Verification URLs** for manual checking\n- **Data source types** (Foundation, SR Legacy, Survey, Branded)\n- **Confidence scores** for match quality\n\n### Bulletproof System Metrics\n- **Cache layer hit** - Which cache tier provided the data\n- **Processing method** - Exact path through bulletproof flow\n- **Anti-hallucination status** - Verification that no AI nutrition data was used\n- **Mathematical verification** - Confirmation of calculated vs database nutrition\n- **Response times** - Sub-second bulletproof performance tracking\n\n### Complete API Response Fields\n```python\nresult = av.analyze_ingredient(\"1 cup cooked brown rice\")\n\n# Core nutrition data (100% mathematical calculation)\nprint(f\"Calories: {result.nutrition.calories}\") # 216.0\nprint(f\"Protein: {result.nutrition.protein}g\") # 5.0\nprint(f\"Carbs: {result.nutrition.carbs}g\") # 45.0\nprint(f\"Fiber: {result.nutrition.fiber}g\") # 3.5\nprint(f\"Calcium: {result.nutrition.calcium_total}mg\") # 23.0\nprint(f\"Iron: {result.nutrition.iron_total}mg\") # 0.8\n\n# USDA verification (bulletproof source)\nprint(f\"FDC ID: {result.usda_match.fdc_id}\") # 168880\nprint(f\"Description: {result.usda_match.description}\") # \"Rice, brown, long-grain, cooked\"\nprint(f\"Data Type: {result.usda_match.data_type}\") # \"foundation_food\"\nprint(f\"Verify: {result.verification_url}\") # USDA verification link\n\n# System performance & caching\nprint(f\"From Cache: {result.from_cache}\") # True/False\nprint(f\"Cache Type: {result.cache_type}\") # \"redis\" | \"supabase\" | None\nprint(f\"Processing Time: {result.processing_time_ms}ms\") # 15.2 (bulletproof speed)\nprint(f\"Method Used: {result.method_used}\") # \"llm_driven_search\" | \"sql_exact\" | \"fuzzy_match\"\n\n# Parsing details\nprint(f\"Estimated Grams: {result.estimated_grams}\") # 195.0\nprint(f\"Parsed Name: {result.ingredient_name}\") # \"1 cup cooked brown rice\"\n```\n\n## Recipe Results with Individual Ingredient Details\n```python\nrecipe = av.analyze_recipe([\n \"2 cups all-purpose flour\", \n \"1 cup whole milk\"\n], servings=4)\n\n# Recipe-level data\nprint(f\"Total Calories: {recipe.nutrition.total.calories}\") # 1862.21\nprint(f\"Per Serving: {recipe.nutrition.per_serving.calories}\") # 465.55\nprint(f\"USDA Matches: {recipe.usda_matches}\") # 2\nprint(f\"Processing Time: {recipe.processing_time_ms}ms\") # 5.3\n# Note: All nutrition data is USDA-verifiable via included FDC IDs and verification URLs\n\n# Individual ingredient details\nfor ingredient in recipe.nutrition.ingredients:\n print(f\"Ingredient: {ingredient.ingredient}\")\n print(f\" Calories: {ingredient.nutrition.calories}\")\n print(f\" USDA: {ingredient.usda_match.description}\")\n print(f\" Verify: {ingredient.verification_url}\")\n```\n\n## \ud83d\udcda Documentation\n\n- **[Complete API Documentation](https://nutrition.avocavo.app/docs/python)** - Full reference\n- **[Get API Key](https://nutrition.avocavo.app)** - Sign up for free\n- **[GitHub Repository](https://github.com/avocavo/nutrition-api-python)** - Source code\n- **[Support](mailto:api-support@avocavo.com)** - Get help\n\n## \ud83e\udd1d Support\n\n- **Email**: [api-support@avocavo.com](mailto:api-support@avocavo.com)\n- **Documentation**: [nutrition.avocavo.app/docs/python](https://nutrition.avocavo.app/docs/python)\n- **Status Page**: [status.avocavo.app](https://status.avocavo.app)\n- **Feature Requests**: [GitHub Issues](https://github.com/avocavo/nutrition-api-python/issues)\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Made with \u2764\ufe0f by the Avocavo team**\n\n*Get started in 30 seconds: `pip install avocavo-nutrition`*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for the Avocavo Nutrition API - Fast, accurate nutrition data with USDA verification",
"version": "1.8.4",
"project_urls": {
"API Dashboard": "https://nutrition.avocavo.app",
"Bug Tracker": "https://github.com/avocavo/nutrition-api-python/issues",
"Changelog": "https://github.com/avocavo/nutrition-api-python/blob/main/CHANGELOG.md",
"Documentation": "https://nutrition.avocavo.app/docs/python",
"Download": "https://pypi.org/project/avocavo-nutrition/",
"Homepage": "https://github.com/avocavo/nutrition-api-python"
},
"split_keywords": [
"nutrition",
" api",
" usda",
" food",
" recipe",
" health",
" fitness",
" calories",
" macros",
" nutrients",
" fooddata",
" fdc",
" cooking",
" meal-planning",
" diet",
" wellness",
" restaurant",
" food-tech"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2d49bf85bfd83fbe6551bb5be6732fefa178102576e7c32029ae719de1c43206",
"md5": "e9dab4732c96f09ea66d60144174e23e",
"sha256": "f0d2b227101a7f5f20bcdbbdaaf5feed875339f43063e6fd10fe65749f9e1c33"
},
"downloads": -1,
"filename": "avocavo_nutrition-1.8.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9dab4732c96f09ea66d60144174e23e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 26072,
"upload_time": "2025-07-17T15:41:53",
"upload_time_iso_8601": "2025-07-17T15:41:53.663165Z",
"url": "https://files.pythonhosted.org/packages/2d/49/bf85bfd83fbe6551bb5be6732fefa178102576e7c32029ae719de1c43206/avocavo_nutrition-1.8.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d7e0d90acae75f260058b6d3dbe5b5f20a912b7fced9cb0b85bd0b59ccd3530b",
"md5": "bda322f187e9019e32989af603544e9c",
"sha256": "0e71ed33b3b020ed6ea5dfa0096f8597bb18bb17d1feeaaed5d66d447653c25b"
},
"downloads": -1,
"filename": "avocavo_nutrition-1.8.4.tar.gz",
"has_sig": false,
"md5_digest": "bda322f187e9019e32989af603544e9c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 32188,
"upload_time": "2025-07-17T15:41:54",
"upload_time_iso_8601": "2025-07-17T15:41:54.804289Z",
"url": "https://files.pythonhosted.org/packages/d7/e0/d90acae75f260058b6d3dbe5b5f20a912b7fced9cb0b85bd0b59ccd3530b/avocavo_nutrition-1.8.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 15:41:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "avocavo",
"github_project": "nutrition-api-python",
"github_not_found": true,
"lcname": "avocavo-nutrition"
}
JSON
