🐍 Python SDK Documentation

import avocavo as av

# One-time OAuth login (opens browser)
av.login()  # Google OAuth (default)
av.auto_setup_api_key()  # One-time API key setup

# 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 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 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
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") # Typically 300-400ms
print(f"Method Used: {result.method_used}")             # "sql_exact" | "fuzzy_match_90%"

# Parsing details
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 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"     Powered by USDA: {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 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}")               # "gpt_normalized"
print(f"Parsing tier: {result.portion_source}")           # "gpt_processing"
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:

# Direct SQL Match (fastest)
result = av.analyze_ingredient("1 cup rice")
print(f"Method: {result.method_used}")          # "sql_exact"
print(f"Cached: {result.cached}")               # True/False

# Fuzzy Match (spelling variations)
result = av.analyze_ingredient("1 cup ryce")
print(f"Method: {result.method_used}")          # "fuzzy_match_90%"
print(f"Cached: {result.cached}")               # True/False

# GPT-Powered Ingredient Normalization
result = av.analyze_ingredient("1 large apple")
print(f"Method: {result.method_used}")          # "gpt_normalized"
print(f"Cached: {result.cached}")               # True/False

# Complex Ingredient Processing
result = av.analyze_ingredient("1 very small pinch of salt")
print(f"Method: {result.method_used}")          # "gpt_normalized"
print(f"Cached: {result.cached}")               # True/False

# Generic Portion Fallback
result = av.analyze_ingredient("a splash of vanilla extract")
print(f"Method: {result.method_used}")          # "redis_cache"
print(f"Cached: {result.cached}")               # True/False

# Small Measurement Handling
result = av.analyze_ingredient("a dash of cinnamon")
print(f"Method: {result.method_used}")          # "supabase_cache"
print(f"Cached: {result.cached}")               # True/False

import avocavo 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
    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
    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 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}")

import avocavo as av

# Search for a product by UPC
result = av.search_upc("034000052004")

if result.found:
    print(f"Product: {result.product.product_name}")
    print(f"Brand: {result.product.brand}")
    print(f"Sources: {result.product.sources}")
    print(f"Categories: {len(result.product.categories)} categories")
    
    # Access nutrition data if available
    if result.product.has_nutrition:
        nutrition = result.product.nutrition['merged']
        calories = nutrition.get('energy-kcal', 'N/A')
        protein = nutrition.get('proteins', 'N/A')
        print(f"Calories: {calories}")
        print(f"Protein: {protein}g")
    
    # Show data sources
    print(f"Data from: {', '.join(result.product.sources)}")
    print(f"Processing time: {result.processing_time_ms}ms")
else:
    print(f"Product not found: {result.error}")

# Search multiple UPCs efficiently
upcs = [
    "034000052004",  # Known UPC (Hershey's Cocoa)
    "123456789012",  # Test UPC
    "999999999999",  # Invalid UPC
]

batch_result = av.search_upc_batch(upcs)

print(f"Batch Results: {batch_result.found_count}/{batch_result.total_count} found")
print(f"Success Rate: {batch_result.success_rate:.1f}%")
print(f"Processing Time: {batch_result.processing_time_ms}ms")

# Process individual results
for upc_result in batch_result.results:
    if upc_result.found:
        product = upc_result.product
        print(f"✅ {upc_result.upc}: {product.product_name}")
        print(f"   Brand: {product.brand}")
        print(f"   Sources: {product.sources}")
    else:
        print(f"❌ {upc_result.upc}: {upc_result.error}")

from avocavo import NutritionAPI

# Initialize client with API key
client = NutritionAPI(api_key="your_api_key")

# Search UPC with client instance
result = client.search_upc("034000052004")

if result.found:
    product = result.product
    print(f"Product: {product.product_name}")
    print(f"Brand: {product.brand}")
    
    # Check data quality indicators
    if product.quality_score:
        print(f"Quality Score: {product.quality_score}")
    
    # Show serving information
    if hasattr(product, 'serving_info'):
        serving = product.serving_info
        if 'serving_size' in serving:
            print(f"Serving Size: {serving['serving_size']}")
    
    # Multi-source data advantages
    if product.is_multi_source:
        print("✨ Enhanced data from multiple sources!")

# Check UPC service health
health = client.upc_health_check()
print(f"UPC Service Status: {health['status']}")

from avocavo import (
    ApiError, 
    RateLimitError, 
    AuthenticationError,
    ValidationError,
    NetworkError
)
import avocavo 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 as av
from avocavo 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 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
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
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
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