🐍 Python SDK Documentation

import avocavo_nutrition as av

# One-time OAuth login (opens browser)
av.login()  # Google OAuth (default)

# Now use the nutrition API without API keys!
result = av.analyze_ingredient("2 cups chocolate chips")
print(f"Calories: {result.nutrition.calories}")
print(f"Protein: {result.nutrition.protein}g")
print(f"USDA: {result.usda_match.description}")

from avocavo_nutrition import NutritionAPI

client = NutritionAPI(api_key="your_api_key_here")
result = client.analyze_ingredient("1 cup rice")
print(f"Calories: {result.nutrition.calories}")

import avocavo_nutrition as av

# Any ingredient with quantity
result = av.analyze_ingredient("2 tbsp olive oil")

if result.success:
    nutrition = result.nutrition
    print(f"Calories: {nutrition.calories}")
    print(f"Fat: {nutrition.fat}g")
    print(f"Protein: {nutrition.protein}g")
    print(f"Carbs: {nutrition.carbs}g")
    print(f"Fiber: {nutrition.fiber}g")
    print(f"Sodium: {nutrition.sodium}mg")
    
    # USDA verification
    usda = result.usda_match
    print(f"\nUSDA FDC ID: {usda.fdc_id}")
    print(f"Description: {usda.description}")
    print(f"Data Type: {usda.data_type}")
    print(f"Verify: {result.verification_url}")
else:
    print(f"Error: {result.error}")

result = av.analyze_ingredient("1 cup cooked brown rice")
nutrition = result.nutrition

# Core nutrients
print(f"Calories: {nutrition.calories}")
print(f"Protein: {nutrition.protein}g")
print(f"Carbohydrates: {nutrition.carbs}g") 
print(f"Total Fat: {nutrition.fat}g")

# Detailed breakdown
print(f"Dietary Fiber: {nutrition.fiber}g")
print(f"Sugars: {nutrition.sugar}g")
print(f"Saturated Fat: {nutrition.saturated_fat}g")

# Minerals
print(f"Sodium: {nutrition.sodium}mg")
print(f"Calcium: {nutrition.calcium}mg")
print(f"Iron: {nutrition.iron}mg")
print(f"Potassium: {nutrition.potassium}mg")

# Vitamins (when available)
print(f"Vitamin A: {nutrition.vitamin_a}mcg")
print(f"Vitamin C: {nutrition.vitamin_c}mg")

# System performance & caching (NEW in v1.7.3+)
print(f"\nFrom 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") # Sub-second response
print(f"Method Used: {result.method_used}")             # "llm_driven_search" | "sql_exact"

# Parsing details (NEW in v1.7.3+)
print(f"\nParsing Info:")
print(f"Estimated Grams: {result.estimated_grams}")     # 195.0
print(f"Parsed Name: {result.ingredient_name}")         # "1 cup cooked brown rice"

# Complex natural language ingredients that work perfectly
import avocavo_nutrition as av

# Natural language portions that other APIs can't handle
ingredients = [
    "1 handful of baby spinach",
    "a splash of vanilla extract", 
    "1 very small pinch of salt",
    "2 medium bananas, ripe",
    "a drizzle of extra virgin olive oil",
    "1 generous dollop of Greek yogurt",
    "a few sprigs of fresh thyme",
    "1 small bunch of fresh cilantro",
    "a squeeze of fresh lemon juice"
]

print("Advanced Parsing Demonstration:")
print("=" * 50)

for ingredient in ingredients:
    result = av.analyze_ingredient(ingredient)
    
    if result.success:
        print(f"✅ {ingredient}")
        print(f"   Calories: {result.nutrition.calories}")
        print(f"   Method: {result.method_used}")
        print(f"   Parsing: {result.parsing.quantity} {result.parsing.unit} {result.parsing.ingredient_name}")
        print(f"   Estimated grams: {result.estimated_grams}g")
        print()
    else:
        print(f"❌ {ingredient}: {result.error}")

# Advanced Recipe with Mixed Ingredient Types
print("\n" + "=" * 50)
print("Advanced Recipe Analysis:")
print("=" * 50)

recipe = av.analyze_recipe([
    "2 cups all-purpose flour",        # Traditional measurement
    "1 handful of baby spinach",       # Natural language portion
    "a splash of vanilla extract",     # Vague quantity description
    "1 very small pinch of salt",      # Size modifier + traditional
    "2 medium bananas, ripe",          # Size + ripeness descriptor
    "a drizzle of olive oil",          # Cooking-style portion
    "1 generous dollop of yogurt"      # Informal + size modifier
], servings=4)

if recipe.success:
    print(f"Recipe Analysis Success! ({recipe.processing_time_ms}ms)")
    print(f"Per serving: {recipe.nutrition.per_serving.calories} calories")
    print(f"USDA matches: {recipe.usda_matches}/{len(recipe.nutrition.ingredients)}")
    print("\nIngredient breakdown:")
    
    for ingredient in recipe.nutrition.ingredients:
        if ingredient.success:
            print(f"  ✅ {ingredient.ingredient}: {ingredient.nutrition.calories} cal")
            print(f"     Parsing method: {ingredient.method_used}")
            print(f"     USDA verified: {ingredient.usda_match.description if ingredient.usda_match else 'N/A'}")
        else:
            print(f"  ❌ {ingredient.ingredient}: Failed")
else:
    print(f"Recipe failed: {recipe.error}")

print("\n🎯 Key Features Demonstrated:")
print("• Size modifiers: 'very small', 'medium', 'generous'")
print("• Natural portions: 'handful', 'splash', 'drizzle', 'dollop'")
print("• Complex descriptors: 'extra virgin', 'fresh', 'ripe'")
print("• Traditional + modern mixing in same recipe")
print("• 100% USDA-verifiable results with parsing transparency")

import avocavo_nutrition as av

# Get detailed response with full parsing breakdown
result = av.analyze_ingredient("1 handful of baby spinach")

print("🔍 PARSING TRANSPARENCY:")
print("=" * 50)
print(f"Original input: {result.original_ingredient}")    # "1 handful of baby spinach"
print(f"Extracted quantity: {result.parsing.quantity}")   # 1
print(f"Recognized unit: {result.parsing.unit}")          # "handful"
print(f"Clean ingredient: {result.parsing.ingredient_name}")  # "baby spinach"
print(f"Estimated grams: {result.estimated_grams}")       # 30

print("\n🎯 HOW WE FOUND THE ANSWER:")
print("=" * 50)
print(f"Method used: {result.method_used}")               # "tiered_portion_conversion"
print(f"Parsing tier: {result.portion_source}")           # "tier_3_adjusted"
print(f"Processing time: {result.processing_time_ms}ms")   # 23.4
print(f"From cache: {result.cached}")                     # False

print("\n✅ USDA VERIFICATION:")
print("=" * 50)
print(f"USDA FDC ID: {result.usda_match.fdc_id}")        # 168462
print(f"Description: {result.usda_match.description}")    # "Spinach, baby, raw"
print(f"Data type: {result.usda_match.data_type}")        # "sr_legacy_food"
print(f"Verify at: {result.verification_url}")

print("\n🥗 NUTRITION RESULTS:")
print("=" * 50)
print(f"Calories: {result.nutrition.calories}")           # 7
print(f"Protein: {result.nutrition.protein}g")            # 0.9
print(f"Total fat: {result.nutrition.total_fat}g")        # 0.1
print(f"Carbs: {result.nutrition.carbohydrates}g")        # 1.1
print(f"Fiber: {result.nutrition.fiber}g")                # 0.7
print(f"Sodium: {result.nutrition.sodium}mg")             # 24

# See exactly how different ingredients are parsed:

# TIER 1: Direct SQL Match (fastest)
result = av.analyze_ingredient("1 cup rice")
print(f"Method: {result.method_used}")          # "sql_exact"
print(f"Tier: {result.portion_source}")         # "tier_1_exact"

# TIER 2: Fuzzy Match (spelling variations)
result = av.analyze_ingredient("1 cup ryce")
print(f"Method: {result.method_used}")          # "fuzzy_match"
print(f"Tier: {result.portion_source}")         # "tier_2_fuzzy"

# TIER 3: Size Modifier Applied
result = av.analyze_ingredient("1 large apple")
print(f"Method: {result.method_used}")          # "portion_adjusted"
print(f"Tier: {result.portion_source}")         # "tier_3_adjusted"

# TIER 4: Complex Modifier Processing
result = av.analyze_ingredient("1 very small pinch of salt")
print(f"Method: {result.method_used}")          # "modifier_adjusted_conversion"
print(f"Tier: {result.portion_source}")         # "tier_4_with_modifier"

# TIER 5: Generic Portion Fallback
result = av.analyze_ingredient("a splash of vanilla extract")
print(f"Method: {result.method_used}")          # "small_measurement_fallback"
print(f"Tier: {result.portion_source}")         # "tier_5_generic"

# TIER 6: Small Measurement Handling
result = av.analyze_ingredient("a dash of cinnamon")
print(f"Method: {result.method_used}")          # "small_measurement"
print(f"Tier: {result.portion_source}")         # "tier_6_small_measurement"

# TIER 7: Smart USDA Matching
result = av.analyze_ingredient("about 2 heaping tablespoons of chunky peanut butter")
print(f"Method: {result.method_used}")          # "llm_driven_search"
print(f"Tier: {result.portion_source}")         # "tier_7_semantic_match"

import avocavo_nutrition as av

# 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",
    "2 tsp baking powder",
    "1/2 tsp salt"
], servings=8)

if recipe.success:
    # Per serving nutrition
    per_serving = recipe.nutrition.per_serving
    print(f"Per serving ({recipe.servings} servings):")
    print(f"  Calories: {per_serving.calories}")
    print(f"  Protein: {per_serving.protein}g")
    print(f"  Carbs: {per_serving.carbs}g")
    print(f"  Fat: {per_serving.fat}g")
    
    # Total recipe nutrition
    total = recipe.nutrition.total
    print(f"\nTotal recipe:")
    print(f"  Calories: {total.calories}")
    print(f"  Protein: {total.protein}g")
    
    # Recipe-level performance (NEW in v1.7.3+)
    print(f"\nRecipe Performance:")
    print(f"  USDA Matches: {recipe.usda_matches}")           # Number of USDA-verifiable ingredients
    print(f"  Processing Time: {recipe.processing_time_ms}ms") # Total processing time
    # Note: All nutrition data is USDA-verifiable via included FDC IDs and verification URLs
    
    # Individual ingredient details (NEW in v1.7.3+)
    print(f"\nIngredient Details:")
    for ingredient in recipe.nutrition.ingredients:
        if ingredient.success:
            print(f"  ✅ {ingredient.ingredient}: {ingredient.nutrition.calories} cal")
            if ingredient.usda_match:
                print(f"     USDA: {ingredient.usda_match.description}")
                print(f"     Verify: {ingredient.verification_url}")
        else:
            print(f"  ❌ {ingredient.ingredient}: Failed to analyze")
else:
    print(f"Recipe analysis failed: {recipe.error}")

# Analyze recipe with metadata
recipe_data = {
    "name": "Healthy Green Smoothie",
    "description": "A nutritious smoothie packed with vitamins",
    "ingredients": [
        "1 banana",
        "100g spinach", 
        "1 cup almond milk",
        "1 tbsp honey",
        "1/2 cup frozen mango"
    ],
    "servings": 2,
    "prep_time": 5,  # minutes
    "cook_time": 0
}

recipe = av.analyze_recipe(
    ingredients=recipe_data["ingredients"],
    servings=recipe_data["servings"],
    name=recipe_data["name"]
)

# Calculate nutrition density
if recipe.success:
    per_serving = recipe.nutrition.per_serving
    
    # Macronutrient percentages
    total_cals = per_serving.calories
    protein_cals = per_serving.protein * 4
    carb_cals = per_serving.carbs * 4  
    fat_cals = per_serving.fat * 9
    
    print(f"Macronutrient breakdown per serving:")
    print(f"  Protein: {protein_cals/total_cals*100:.1f}%")
    print(f"  Carbs: {carb_cals/total_cals*100:.1f}%") 
    print(f"  Fat: {fat_cals/total_cals*100:.1f}%")
    
    # Nutrition density score
    fiber_score = min(per_serving.fiber / 25 * 100, 100)  # 25g daily target
    protein_score = min(per_serving.protein / 50 * 100, 100)  # 50g daily target
    
    print(f"\nNutrition Quality:")
    print(f"  Fiber Score: {fiber_score:.1f}/100")
    print(f"  Protein Score: {protein_score:.1f}/100")

import avocavo_nutrition as av

# Analyze multiple ingredients efficiently
ingredients_list = [
    "1 cup quinoa",
    "2 tbsp olive oil", 
    "4 oz salmon",
    "1 cup spinach",
    "1/4 cup almonds"
]

batch_result = av.analyze_batch(ingredients_list)

print(f"Batch Analysis Results:")
print(f"Success rate: {batch_result.success_rate}%")
print(f"Processed: {len(batch_result.results)} ingredients")
print(f"Processing time: {batch_result.total_processing_time_ms}ms")

# Iterate through results
for item in batch_result.results:
    if item.success:
        print(f"✅ {item.ingredient}: {item.nutrition.calories} cal, {item.nutrition.protein}g protein")
    else:
        print(f"❌ {item.ingredient}: {item.error}")

# Calculate totals
total_calories = sum(item.nutrition.calories for item in batch_result.results if item.success)
total_protein = sum(item.nutrition.protein for item in batch_result.results if item.success)

print(f"\nTotal: {total_calories} calories, {total_protein}g protein")

# Batch processing with error handling and progress
import time

def analyze_shopping_list(ingredients, chunk_size=5):
    """Analyze a large shopping list in chunks"""
    results = []
    
    # Process in chunks to respect rate limits
    for i in range(0, len(ingredients), chunk_size):
        chunk = ingredients[i:i + chunk_size]
        print(f"Processing chunk {i//chunk_size + 1}/{(len(ingredients)-1)//chunk_size + 1}...")
        
        try:
            batch_result = av.analyze_batch(chunk)
            results.extend(batch_result.results)
            
            # Show progress
            successful = sum(1 for r in batch_result.results if r.success)
            print(f"  ✅ {successful}/{len(chunk)} successful")
            
        except Exception as e:
            print(f"  ❌ Chunk failed: {e}")
            # Continue with next chunk
            
        # Brief pause between chunks
        time.sleep(0.1)
    
    return results

# Usage
shopping_list = [
    "2 lbs ground beef", "1 dozen eggs", "1 gallon milk",
    "2 lbs chicken breast", "1 bag brown rice", "2 lbs bananas",
    "1 lb spinach", "1 lb carrots", "1 jar peanut butter",
    "1 loaf whole wheat bread", "1 lb oats", "1 lb almonds"
]

results = analyze_shopping_list(shopping_list)

# Summarize results
successful_results = [r for r in results if r.success]
total_calories = sum(r.nutrition.calories for r in successful_results)
total_cost_estimate = len(successful_results) * 0.02  # Rough API cost estimate

print(f"\nShopping List Summary:")
print(f"Analyzed: {len(successful_results)}/{len(shopping_list)} items")
print(f"Total calories: {total_calories:,.0f}")
print("Estimated API cost: $" + f"{total_cost_estimate:.2f}")

from avocavo_nutrition import (
    ApiError, 
    RateLimitError, 
    AuthenticationError,
    ValidationError,
    NetworkError
)
import avocavo_nutrition as av

def robust_nutrition_analysis(ingredient: str):
    """Nutrition analysis with comprehensive error handling"""
    
    try:
        result = av.analyze_ingredient(ingredient)
        
        if result.success:
            print(f"✅ {ingredient}")
            print(f"   Calories: {result.nutrition.calories}")
            print(f"   USDA: {result.usda_match.description}")
            print(f"   Verify: {result.verification_url}")
            return result
        else:
            print(f"❌ {ingredient}: {result.error}")
            return None
            
    except AuthenticationError as e:
        print(f"🔐 Authentication failed: {e.message}")
        print("💡 Try: av.login() or check your API key")
        return None
        
    except RateLimitError as e:
        print(f"⏱️  Rate limit exceeded: {e.message}")
        print(f"   Current usage: {e.usage}/{e.limit}")
        print(f"   Resets at: {e.reset_time}")
        print("💡 Consider upgrading your plan or waiting")
        return None
        
    except ValidationError as e:
        print(f"📝 Invalid input: {e.message}")
        print("💡 Check ingredient format: '1 cup rice' not just 'rice'")
        return None
        
    except NetworkError as e:
        print(f"🌐 Network error: {e.message}")
        print("💡 Check internet connection and try again")
        return None
        
    except ApiError as e:
        print(f"🚨 API error: {e.message}")
        print(f"   Status code: {e.status_code}")
        print("💡 Contact support if this persists")
        return None
        
    except Exception as e:
        print(f"❗ Unexpected error: {str(e)}")
        print("💡 Please report this issue")
        return None

# Usage
ingredients = [
    "1 cup brown rice",
    "invalid ingredient format",
    "2 tbsp olive oil",
    "",  # Empty string
    "1 cup imaginary food that doesn't exist"
]

successful_analyses = []
for ingredient in ingredients:
    if ingredient.strip():  # Skip empty strings
        result = robust_nutrition_analysis(ingredient)
        if result:
            successful_analyses.append(result)

print(f"\nSuccessfully analyzed: {len(successful_analyses)}/{len([i for i in ingredients if i.strip()])} ingredients")

import time
import avocavo_nutrition as av
from avocavo_nutrition import NetworkError, RateLimitError

def analyze_with_retry(ingredient: str, max_retries: int = 3, backoff_factor: float = 1.0):
    """Analyze ingredient with exponential backoff retry logic"""
    
    for attempt in range(max_retries):
        try:
            result = av.analyze_ingredient(ingredient)
            return result
            
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise  # Re-raise on final attempt
            
            # Wait for rate limit reset or exponential backoff
            wait_time = min(e.retry_after or (backoff_factor * (2 ** attempt)), 60)
            print(f"Rate limited. Waiting {wait_time:.1f}s before retry {attempt + 1}/{max_retries}")
            time.sleep(wait_time)
            
        except NetworkError as e:
            if attempt == max_retries - 1:
                raise
            
            wait_time = backoff_factor * (2 ** attempt)
            print(f"Network error. Retrying in {wait_time:.1f}s... ({attempt + 1}/{max_retries})")
            time.sleep(wait_time)
    
    raise Exception(f"Failed after {max_retries} attempts")

# Usage with timeout configuration
from avocavo_nutrition import NutritionAPI

# Configure client with custom timeout
client = NutritionAPI(
    api_key="your_api_key",
    timeout=30,  # 30 second timeout
    max_retries=3
)

# Analyze with retry logic
try:
    result = analyze_with_retry("1 cup quinoa", max_retries=3)
    if result.success:
        print(f"Success: {result.nutrition.calories} calories")
except Exception as e:
    print(f"Final failure: {e}")

result = av.analyze_ingredient("1 cup cooked brown rice")

# Core Properties
result.success                    # bool: True if analysis succeeded
result.ingredient                 # str: Original ingredient text
result.nutrition                  # Nutrition: Complete nutrition data
result.usda_match                 # USDAMatch: USDA verification info
result.verification_url           # str: Direct USDA verification link

# Performance & System Data (NEW in v1.7.3+)
result.from_cache                 # bool: True if served from cache
result.cache_type                 # str: "redis" | "supabase" | None
result.processing_time_ms         # float: Processing time in milliseconds
result.method_used                # str: "llm_driven_search" | "sql_exact" | "fuzzy_match"

# Parsing Details (NEW in v1.7.3+)
result.estimated_grams            # float: Estimated grams for ingredient
result.ingredient_name            # str: Parsed ingredient name
result.error                      # str: Error message if success=False

recipe = av.analyze_recipe(ingredients, servings=4)

# Core Properties
recipe.success                    # bool: True if analysis succeeded
recipe.recipe                     # dict: Original recipe info
recipe.nutrition                  # RecipeNutrition: Complete nutrition breakdown

# Recipe Performance (NEW in v1.7.3+)
recipe.usda_matches               # int: Number of USDA-verifiable ingredients  
recipe.processing_time_ms         # float: Total processing time (sum of ingredients)
# Note: All data is USDA-verifiable via included FDC IDs and verification URLs

# Nutrition Breakdown
recipe.nutrition.total            # Nutrition: Total recipe nutrition
recipe.nutrition.per_serving      # Nutrition: Per-serving nutrition
recipe.nutrition.ingredients      # List[RecipeIngredient]: Individual ingredients

# Individual Ingredient Details
for ingredient in recipe.nutrition.ingredients:
    ingredient.ingredient         # str: Ingredient text
    ingredient.nutrition          # Nutrition: Individual nutrition data
    ingredient.usda_match         # USDAMatch: USDA verification
    ingredient.verification_url   # str: USDA verification link (NEW)
    ingredient.success            # bool: Analysis success for this ingredient