Initial commit

2025-11-30 08:30:10 +08:00
commit f0bd18fb4e
824 changed files with 331919 additions and 0 deletions
--- a/skills/fda-database/references/foods.md
+++ b/skills/fda-database/references/foods.md
@@ -0,0 +1,374 @@
+# FDA Food Databases
+
+This reference covers FDA food-related API endpoints accessible through openFDA.
+
+## Overview
+
+The FDA food databases provide access to information about food products, including adverse events and enforcement actions. These databases help track food safety issues, recalls, and consumer complaints.
+
+## Available Endpoints
+
+### 1. Food Adverse Events
+
+**Endpoint**: `https://api.fda.gov/food/event.json`
+
+**Purpose**: Access adverse event reports for food products, dietary supplements, and cosmetics.
+
+**Data Source**: CAERS (CFSAN Adverse Event Reporting System)
+
+**Key Fields**:
+- `date_started` - When adverse event began
+- `date_created` - When report was created
+- `report_number` - Unique report identifier
+- `outcomes` - Event outcomes (e.g., hospitalization, death)
+- `reactions` - Adverse reactions/symptoms reported
+- `consumer.age` - Consumer age
+- `consumer.age_unit` - Age unit (years, months, etc.)
+- `consumer.gender` - Consumer gender
+- `products` - Array of products involved
+- `products.name_brand` - Product brand name
+- `products.industry_code` - Product category code
+- `products.industry_name` - Product category name
+- `products.role` - Product role (Suspect, Concomitant)
+
+**Product Categories (industry_name)**:
+- Bakery Products/Dough/Mixes/Icing
+- Beverages (coffee, tea, soft drinks, etc.)
+- Dietary Supplements
+- Ice Cream Products
+- Cosmetics
+- Vitamins and nutritional supplements
+- Many others
+
+**Common Use Cases**:
+- Food safety surveillance
+- Dietary supplement monitoring
+- Adverse event trend analysis
+- Product safety assessment
+- Consumer complaint tracking
+
+**Example Queries**:
+```python
+import requests
+
+api_key = "YOUR_API_KEY"
+url = "https://api.fda.gov/food/event.json"
+
+# Find adverse events for dietary supplements
+params = {
+    "api_key": api_key,
+    "search": "products.industry_name:Dietary+Supplements",
+    "limit": 10
+}
+
+response = requests.get(url, params=params)
+data = response.json()
+```
+
+```python
+# Count most common reactions
+params = {
+    "api_key": api_key,
+    "search": "products.industry_name:*Beverages*",
+    "count": "reactions.exact"
+}
+```
+
+```python
+# Find serious outcomes (hospitalizations, deaths)
+params = {
+    "api_key": api_key,
+    "search": "outcomes:Hospitalization",
+    "limit": 50,
+    "sort": "date_created:desc"
+}
+```
+
+```python
+# Search by product brand name
+params = {
+    "api_key": api_key,
+    "search": "products.name_brand:*protein+powder*",
+    "limit": 20
+}
+```
+
+### 2. Food Enforcement Reports
+
+**Endpoint**: `https://api.fda.gov/food/enforcement.json`
+
+**Purpose**: Access food product recall enforcement reports issued by the FDA.
+
+**Data Source**: FDA Enforcement Reports
+
+**Key Fields**:
+- `status` - Current status (Ongoing, Completed, Terminated)
+- `recall_number` - Unique recall identifier
+- `classification` - Class I, II, or III
+- `product_description` - Description of recalled food product
+- `reason_for_recall` - Why product was recalled
+- `product_quantity` - Amount of product recalled
+- `code_info` - Lot numbers, batch codes, UPCs
+- `distribution_pattern` - Geographic distribution
+- `recalling_firm` - Company conducting recall
+- `recall_initiation_date` - When recall began
+- `report_date` - When FDA received notice
+- `voluntary_mandated` - Voluntary or FDA-mandated recall
+- `city` - Recalling firm city
+- `state` - Recalling firm state
+- `country` - Recalling firm country
+- `initial_firm_notification` - How firm was notified
+
+**Classification Levels**:
+- **Class I**: Dangerous or defective products that could cause serious health problems or death (e.g., undeclared allergens with severe risk, botulism contamination)
+- **Class II**: Products that might cause temporary health problems or pose slight threat (e.g., minor allergen issues, quality defects)
+- **Class III**: Products unlikely to cause adverse health reactions but violate FDA regulations (e.g., labeling errors, quality issues)
+
+**Common Recall Reasons**:
+- Undeclared allergens (milk, eggs, peanuts, tree nuts, soy, wheat, fish, shellfish, sesame)
+- Microbial contamination (Listeria, Salmonella, E. coli, etc.)
+- Foreign material contamination (metal, plastic, glass)
+- Labeling errors
+- Improper processing/packaging
+- Chemical contamination
+
+**Common Use Cases**:
+- Food safety monitoring
+- Supply chain risk management
+- Allergen tracking
+- Retailer recall coordination
+- Consumer safety alerts
+
+**Example Queries**:
+```python
+# Find all Class I food recalls (most serious)
+params = {
+    "api_key": api_key,
+    "search": "classification:Class+I",
+    "limit": 20,
+    "sort": "report_date:desc"
+}
+
+response = requests.get("https://api.fda.gov/food/enforcement.json", params=params)
+```
+
+```python
+# Search for allergen-related recalls
+params = {
+    "api_key": api_key,
+    "search": "reason_for_recall:*undeclared+allergen*",
+    "limit": 50
+}
+```
+
+```python
+# Find Listeria contamination recalls
+params = {
+    "api_key": api_key,
+    "search": "reason_for_recall:*listeria*",
+    "limit": 30,
+    "sort": "recall_initiation_date:desc"
+}
+```
+
+```python
+# Get recalls by specific company
+params = {
+    "api_key": api_key,
+    "search": "recalling_firm:*General+Mills*",
+    "limit": 20
+}
+```
+
+```python
+# Find ongoing recalls
+params = {
+    "api_key": api_key,
+    "search": "status:Ongoing",
+    "limit": 100
+}
+```
+
+```python
+# Search by product type
+params = {
+    "api_key": api_key,
+    "search": "product_description:*ice+cream*",
+    "limit": 25
+}
+```
+
+## Integration Tips
+
+### Allergen Monitoring System
+
+```python
+def monitor_allergen_recalls(allergens, api_key, days_back=30):
+    """
+    Monitor food recalls for specific allergens.
+
+    Args:
+        allergens: List of allergens to monitor (e.g., ["peanut", "milk", "soy"])
+        api_key: FDA API key
+        days_back: Number of days to look back
+
+    Returns:
+        List of matching recalls
+    """
+    import requests
+    from datetime import datetime, timedelta
+
+    # Calculate date range
+    end_date = datetime.now()
+    start_date = end_date - timedelta(days=days_back)
+    date_range = f"[{start_date.strftime('%Y%m%d')}+TO+{end_date.strftime('%Y%m%d')}]"
+
+    url = "https://api.fda.gov/food/enforcement.json"
+    all_recalls = []
+
+    for allergen in allergens:
+        params = {
+            "api_key": api_key,
+            "search": f"reason_for_recall:*{allergen}*+AND+report_date:{date_range}",
+            "limit": 100
+        }
+
+        response = requests.get(url, params=params)
+        if response.status_code == 200:
+            data = response.json()
+            if "results" in data:
+                for result in data["results"]:
+                    result["detected_allergen"] = allergen
+                    all_recalls.append(result)
+
+    return all_recalls
+```
+
+### Adverse Event Analysis
+
+```python
+def analyze_product_adverse_events(product_name, api_key):
+    """
+    Analyze adverse events for a specific food product.
+
+    Args:
+        product_name: Product name or partial name
+        api_key: FDA API key
+
+    Returns:
+        Dictionary with analysis results
+    """
+    import requests
+    from collections import Counter
+
+    url = "https://api.fda.gov/food/event.json"
+    params = {
+        "api_key": api_key,
+        "search": f"products.name_brand:*{product_name}*",
+        "limit": 1000
+    }
+
+    response = requests.get(url, params=params)
+    data = response.json()
+
+    if "results" not in data:
+        return {"error": "No results found"}
+
+    results = data["results"]
+
+    # Extract all reactions
+    all_reactions = []
+    all_outcomes = []
+
+    for event in results:
+        if "reactions" in event:
+            all_reactions.extend(event["reactions"])
+        if "outcomes" in event:
+            all_outcomes.extend(event["outcomes"])
+
+    # Count frequencies
+    reaction_counts = Counter(all_reactions)
+    outcome_counts = Counter(all_outcomes)
+
+    return {
+        "total_events": len(results),
+        "most_common_reactions": reaction_counts.most_common(10),
+        "outcome_distribution": dict(outcome_counts),
+        "serious_outcomes": sum(1 for o in all_outcomes if o in ["Hospitalization", "Death", "Disability"])
+    }
+```
+
+### Recall Alert System
+
+```python
+def get_recent_recalls_by_state(state_code, api_key, days=7):
+    """
+    Get recent food recalls for products distributed in a specific state.
+
+    Args:
+        state_code: Two-letter state code (e.g., "CA", "NY")
+        api_key: FDA API key
+        days: Number of days to look back
+
+    Returns:
+        List of recent recalls affecting the state
+    """
+    import requests
+    from datetime import datetime, timedelta
+
+    url = "https://api.fda.gov/food/enforcement.json"
+
+    # Calculate date range
+    end_date = datetime.now()
+    start_date = end_date - timedelta(days=days)
+    date_range = f"[{start_date.strftime('%Y%m%d')}+TO+{end_date.strftime('%Y%m%d')}]"
+
+    params = {
+        "api_key": api_key,
+        "search": f"distribution_pattern:*{state_code}*+AND+report_date:{date_range}",
+        "limit": 100,
+        "sort": "report_date:desc"
+    }
+
+    response = requests.get(url, params=params)
+    if response.status_code == 200:
+        data = response.json()
+        return data.get("results", [])
+    return []
+```
+
+## Best Practices
+
+1. **Monitor allergen recalls** - Critical for food service and retail
+2. **Check distribution patterns** - Recalls may be regional or national
+3. **Track recall status** - Status changes from "Ongoing" to "Completed"
+4. **Filter by classification** - Prioritize Class I recalls for immediate action
+5. **Use date ranges** - Focus on recent events for operational relevance
+6. **Cross-reference products** - Same product may appear in both adverse events and enforcement
+7. **Parse code_info carefully** - Lot numbers and UPCs vary in format
+8. **Consider product categories** - Industry codes help categorize products
+9. **Track serious outcomes** - Hospitalization and death require immediate attention
+10. **Implement alert systems** - Automate monitoring for critical products/allergens
+
+## Common Allergens to Monitor
+
+The FDA recognizes 9 major food allergens that must be declared:
+1. Milk
+2. Eggs
+3. Fish
+4. Crustacean shellfish
+5. Tree nuts
+6. Peanuts
+7. Wheat
+8. Soybeans
+9. Sesame
+
+These account for over 90% of food allergies and are the most common reasons for Class I recalls.
+
+## Additional Resources
+
+- OpenFDA Food API Documentation: https://open.fda.gov/apis/food/
+- CFSAN Adverse Event Reporting: https://www.fda.gov/food/compliance-enforcement-food/cfsan-adverse-event-reporting-system-caers
+- Food Recalls: https://www.fda.gov/safety/recalls-market-withdrawals-safety-alerts
+- API Basics: See `api_basics.md` in this references directory
+- Python examples: See `scripts/fda_food_query.py`