Add LlamaIndex agent with guardrails and on-demand image

.gitignore

@@ -6,9 +6,7 @@
 venv/
 env/
 
-# Cached data
-data/raw/
-data/processed/
+# Cached data (moved to end of file)
 
 # Python
 __pycache__/
@@ -56,7 +54,22 @@ spice_bae/
 # Others
 .claude/
 DEPLOYMENT.md
-data/
 data_ingest/
 neo4j_setup/
-thoughts/
+thoughts/
+
+# Logs directory
+logs/
+
+# Static images (downloaded on-demand instead)
+static/
+
+# Data directory (keep spice_images.json for URLs)
+data/raw/
+data/processed/
+data/manual/
+data/spice_list.json
+data/spice_name_mapping.json
+data/spice_images_local.json
+data/health_benefits.json
+data/nccih_herb_mapping.json

MCP_INTEGRATION.md

@@ -0,0 +1,145 @@
+# MCP Integration Guide
+
+This guide explains how to connect the Medicinal Cuisine MCP server to various AI clients.
+
+## Overview
+
+The Medicinal Cuisine AI Advisor exposes its tools via the Model Context Protocol (MCP), allowing AI assistants like Cline and Claude Desktop to query spice information, nutritional data, and health benefits directly.
+
+**MCP Endpoint**: `https://mcp-1st-birthday-spice-bae.hf.space/gradio_api/mcp/sse`
+
+## Prerequisites
+
+- Node.js 18+ installed
+- `npx` available in your PATH
+- The Medicinal Cuisine Space deployed on Hugging Face
+
+## Connecting with Cline (VS Code)
+
+### Step 1: Locate the Settings File
+
+Cline stores MCP server configurations in `cline_mcp_settings.json`. The location varies by OS:
+
+- **Windows**: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
+- **macOS**: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+- **Linux**: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
+
+### Step 2: Add the Server Configuration
+
+Edit `cline_mcp_settings.json` and add:
+
+```json
+{
+  "mcpServers": {
+    "medicinal-cuisine": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "https://mcp-1st-birthday-spice-bae.hf.space/gradio_api/mcp/sse"
+      ]
+    }
+  }
+}
+```
+
+Note: The `-y` flag auto-confirms npx prompts.
+
+### Step 3: Restart Cline
+
+Restart VS Code or reload the Cline extension for changes to take effect.
+
+## Connecting with Claude Desktop
+
+### Step 1: Locate the Settings File
+
+Claude Desktop stores configurations in:
+
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+### Step 2: Add the Server Configuration
+
+Edit `claude_desktop_config.json` and add:
+
+```json
+{
+  "mcpServers": {
+    "medicinal-cuisine": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "https://mcp-1st-birthday-spice-bae.hf.space/gradio_api/mcp/sse"
+      ]
+    }
+  }
+}
+```
+
+Note: The `-y` flag auto-confirms npx prompts.
+
+### Step 3: Restart Claude Desktop
+
+**Important**: You must completely quit Claude Desktop and reopen it (not just close the window). On macOS, use Cmd+Q or right-click the dock icon and select Quit. On Windows, ensure Claude is fully closed from the system tray.
+
+## Available Tools
+
+Once connected, the following tools are available:
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `get_spice_information` | `spice_name: str` | Get comprehensive spice data with nutrients |
+| `get_nutrient_content` | `spice_name: str, nutrient_name: str` | Get specific nutrient content |
+| `compare_spices` | `spice1: str, spice2: str` | Side-by-side nutritional comparison |
+| `list_available_spices` | None | List all 88+ spices in the database |
+| `get_health_benefits` | `spice_name: str` | Get health benefits from NCCIH |
+| `get_safety_info` | `spice_name: str` | Get side effects and cautions |
+| `find_substitute_spices` | `spice_name: str` | Find nutritionally similar alternatives |
+| `find_spices_for_condition` | `condition: str` | Find spices for a health condition |
+
+## Example Queries
+
+After connecting, you can ask your AI assistant questions like:
+
+- "What are the health benefits of turmeric?"
+- "Compare the nutritional content of cinnamon and ginger"
+- "Find spices that may help with inflammation"
+- "What are the side effects of taking too much garlic?"
+- "List all available spices in the database"
+- "What can I substitute for cumin in a recipe?"
+
+## Troubleshooting
+
+### Connection Errors
+
+1. **Verify the Space is running**: Visit your Hugging Face Space URL directly
+2. **Check the endpoint**: Ensure you're using `/gradio_api/mcp/sse` (not `/gradio_api/mcp/`)
+3. **Install mcp-remote**: Run `npm install -g mcp-remote` if npx fails
+
+### Tool Not Found
+
+1. Restart your AI client after adding the configuration
+2. Check JSON syntax in the settings file
+3. Verify the Space has finished building
+
+### Rate Limiting
+
+The server includes guardrails:
+- 10 requests per minute per session
+- 100 requests per day per session
+
+If you hit rate limits, wait a moment before retrying.
+
+## Security Notes
+
+- The MCP server is read-only and cannot modify any data
+- All responses include medical disclaimers
+- No personal data is collected or stored
+- API usage is tracked for cost control only
+
+## References
+
+- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
+- [Gradio MCP Server Guide](https://www.gradio.app/guides/mcp-server)
+- [mcp-remote Package](https://www.npmjs.com/package/mcp-remote)

README.md

@@ -8,63 +8,108 @@ sdk_version: 5.50.0
 app_file: app.py
 pinned: false
 license: mit
+tags:
+  - mcp-server
+  - mcp-in-action
+  - building-mcp-track-consumer
+  - mcp-in-action-track-consumer
 ---
 
-# 🌿 Medicinal Cuisine AI Advisor
+# Medicinal Cuisine AI Advisor
 
-An AI-powered advisor for spice information, nutritional content, and medicinal properties. Built with Gradio, Neo4j, and the USDA FoodData Central API.
+An AI-powered advisor for spice information, nutritional content, and medicinal properties. Built with Gradio, Neo4j, LlamaIndex, and Claude AI.
+
+> **Hackathon Submission**: This project is submitted to [MCP's 1st Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday) (November 14-30, 2025).
+>
+> **Tracks:**
+> - **Track 1: Building MCP** - Consumer MCP Servers (`building-mcp-track-consumer`)
+> - **Track 2: MCP in Action** - Consumer Applications (`mcp-in-action-track-consumer`)
 
 ## Features
 
-- 🔍 **Spice Information Lookup** - Detailed nutritional data for 25 common spices
-- 🧪 **Nutrient Content Search** - Find specific vitamins, minerals, and compounds
-- ⚖️ **Spice Comparison** - Side-by-side nutritional analysis
-- 📊 **MCP Server Integration** - Model Context Protocol tools at `/gradio_api/mcp/`
-- 📚 **Data Provenance** - All data sourced from USDA FoodData Central with full attribution
+- **AI Chat Assistant** - Conversational interface powered by Claude via LlamaIndex AgentWorkflow
+- **Spice Database** - Comprehensive data for 88+ spices with nutritional information
+- **Health Benefits** - Medicinal properties from NCCIH (National Center for Complementary and Integrative Health)
+- **Safety Information** - Side effects, cautions, and drug interactions
+- **Spice Substitutes** - Find alternatives based on nutritional or medicinal similarity
+- **MCP Server Integration** - Model Context Protocol tools at `/gradio_api/mcp/sse`
+- **Guardrails** - Rate limiting, cost controls ($1/day limit), and medical disclaimer enforcement
+- **Data Provenance** - All data sourced from USDA FoodData Central and NCCIH with full attribution
 
 ## Live Demo
 
-- **Web UI**: [Your Hugging Face Space URL]
-- **MCP Server**: [Your Space URL]/gradio_api/mcp/
+- **Web UI**: https://mcp-1st-birthday-spice-bae.hf.space
+- **MCP Server**: https://mcp-1st-birthday-spice-bae.hf.space/gradio_api/mcp/sse
 
 ## Architecture
 
 ```
-┌─────────────────────────────────┐
-│   Gradio Web UI + MCP Server    │
-│  (app.py - Port 7860)           │
-└─────────────────────────────────┘
-              ↓
-┌─────────────────────────────────┐
-│   MCP Tools (tools/mcp_tools.py)│
-│  - get_spice_information()      │
-│  - get_nutrient_content()       │
-│  - compare_spices()             │
-│  - list_available_spices()      │
-└─────────────────────────────────┘
-              ↓
-┌─────────────────────────────────┐
-│ Neo4j Aura (Spice-Bae Database) │
-│  - 25 Spice nodes               │
-│  - 2,098 Nutrient relationships │
-└─────────────────────────────────┘
-              ↑
-┌─────────────────────────────────┐
-│  USDA FoodData Central API      │
-│  (Cached in data/raw/usda/)     │
-└─────────────────────────────────┘
+┌─────────────────────────────────────────────────────────┐
+│              Gradio Web UI + MCP Server                 │
+│                   (app.py - Port 7860)                  │
+│  Tabs: AI Chat | Spice Database | Health & Safety       │
+└─────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────┐
+│              LlamaIndex AgentWorkflow                   │
+│          (tools/llama_agent.py - SpiceAgent)            │
+│   - Claude AI for natural language understanding        │
+│   - 8 function tools for database queries               │
+└─────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────��───────────────────────────────┐
+│                    Guardrails                           │
+│              (tools/guardrails.py)                      │
+│   - Rate limiting (10 req/min, 100 req/day)             │
+│   - Cost control ($1/day limit)                         │
+│   - Medical disclaimer enforcement                      │
+│   - Topic filtering (spice-related only)                │
+└─────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────┐
+│           MCP Tools (tools/mcp_tools.py)                │
+│   - get_spice_information()   - get_health_benefits()   │
+│   - get_nutrient_content()    - get_safety_info()       │
+│   - compare_spices()          - find_substitutes()      │
+│   - list_available_spices()   - find_by_condition()     │
+└─────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────┐
+│          Neo4j Aura (Spice-Bae Database)                │
+│   - 88+ Spice nodes with nutritional data               │
+│   - Health benefit relationships (NCCIH)                │
+│   - Safety information and cautions                     │
+└─────────────────────────────────────────────────────────┘
+                            ↑
+┌─────────────────────────────────────────────────────────┐
+│                   Data Sources                          │
+│   - USDA FoodData Central (nutritional data)            │
+│   - NCCIH (health benefits, safety info)                │
+│   - Wikipedia (spice images with attribution)           │
+└─────────────────────────────────────────────────────────┘
 ```
 
 ## Data Sources
 
-All spice and nutritional data is sourced from:
+All data is sourced from authoritative sources:
+
 - **USDA FoodData Central** - Public domain nutritional database
-- **License**: Public Domain
-- **Attribution**: USDA FoodData Central (https://fdc.nal.usda.gov/)
+  - License: Public Domain
+  - URL: https://fdc.nal.usda.gov/
+
+- **NCCIH (National Center for Complementary and Integrative Health)** - Health benefits and safety information
+  - License: Public Domain (U.S. Government)
+  - URL: https://www.nccih.nih.gov/
+
+- **Wikipedia** - Spice images with proper attribution
+  - License: Various (CC BY-SA, Public Domain)
+  - Images stored locally with source attribution
 
 ## Available Spices
 
-Black Pepper, Cayenne Pepper, Cinnamon, Coriander, Cumin, Fennel, Fenugreek, Garlic, Mustard Seed, Nutmeg, Oregano, Paprika, Saffron, Sage, Allspice, Anise, Basil, Cloves, Ginger, Rosemary, Thyme, Turmeric, Vanilla
+The database contains 88+ spices including:
+
+Allspice, Anise, Asafoetida, Basil, Bay Leaf, Black Cardamom, Black Cumin, Black Pepper, Caraway, Cardamom, Cayenne Pepper, Celery Seed, Chervil, Chili Powder, Chives, Cilantro, Cinnamon, Cloves, Coriander, Cumin, Curry Powder, Dill, Fennel, Fenugreek, Galangal, Garlic, Ginger, Grains of Paradise, Green Cardamom, Horseradish, Juniper Berries, Kaffir Lime, Lavender, Lemon Balm, Lemongrass, Licorice, Lovage, Mace, Marjoram, Mint, Mustard Seed, Nutmeg, Onion Powder, Oregano, Paprika, Parsley, Peppermint, Pink Pepper, Poppy Seed, Rosemary, Saffron, Sage, Savory, Sesame, Shallot, Spearmint, Star Anise, Sumac, Szechuan Pepper, Tamarind, Tarragon, Thyme, Turmeric, Vanilla, Wasabi, White Pepper, and more...
 
 ## Local Development
 
@@ -156,34 +201,44 @@ medicinal-cuisine/
 
 ## MCP Server Usage
 
-The application exposes 4 tools via the Model Context Protocol:
-
-### Available Tools
-
-1. **get_spice_information(spice_name: str)**
-   - Returns comprehensive spice data with nutrients
-
-2. **get_nutrient_content(spice_name: str, nutrient_name: str)**
-   - Returns specific nutrient content
-
-3. **compare_spices(spice1: str, spice2: str)**
-   - Returns side-by-side nutritional comparison
-
-4. **list_available_spices()**
-   - Returns list of all 25 spices
-
-### Connecting to MCP Server
+The application exposes tools via the Model Context Protocol at `/gradio_api/mcp/sse`:
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_spice_information(spice_name)` | Comprehensive spice data with nutrients and image |
+| `get_nutrient_content(spice_name, nutrient_name)` | Specific nutrient content |
+| `compare_spices(spice1, spice2)` | Side-by-side nutritional comparison |
+| `list_available_spices()` | List all 88+ spices |
+| `get_health_benefits(spice_name)` | Health benefits from NCCIH |
+| `get_safety_info(spice_name)` | Side effects, cautions, interactions |
+| `find_substitute_spices(spice_name)` | Nutritionally similar alternatives |
+| `find_spices_for_condition(condition)` | Spices that may help with a condition |
+
+### Connecting with Cline or Claude Desktop
+
+Add to your MCP settings configuration:
+
+```json
+{
+  "mcpServers": {
+    "medicinal-cuisine": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote",
+        "https://mcp-1st-birthday-spice-bae.hf.space/gradio_api/mcp/sse"
+      ]
+    }
+  }
+}
+```
 
-```python
-import requests
+- **Cline**: Edit `cline_mcp_settings.json`, then restart VS Code
+- **Claude Desktop**: Edit `claude_desktop_config.json`, then **completely quit and reopen** Claude Desktop
 
-# MCP endpoint
-mcp_url = "https://your-space.hf.space/gradio_api/mcp/"
-
-# Example: List available tools
-response = requests.get(f"{mcp_url}tools")
-print(response.json())
-```
+See [MCP_INTEGRATION.md](MCP_INTEGRATION.md) for detailed setup instructions.
 
 ## Project Structure
 
@@ -191,31 +246,35 @@ print(response.json())
 medicinal-cuisine/
 ├── app.py                      # Main Gradio application
 ├── requirements.txt            # Python dependencies
-├── .env                        # Environment variables (not in git)
-├── .env.example               # Environment template
 ├── README.md                   # This file
+├── MCP_INTEGRATION.md          # MCP setup guide for Cline/Claude Desktop
+│
+├── tools/                      # Core application logic (deployed)
+│   ├── __init__.py            # Module exports
+│   ├── neo4j_queries.py       # Database queries
+│   ├── mcp_tools.py           # MCP tool definitions
+│   ├── llama_agent.py         # LlamaIndex agent with Claude
+│   ├── guardrails.py          # Safety guardrails
+│   └── image_utils.py         # Local image serving
+│
+├── static/                     # Static assets (deployed)
+│   └── images/spices/         # Local spice images from Wikipedia
 │
 ├── data/                       # Data storage (not deployed to HF)
 │   ├── spice_list.json        # Seed spice names
-│   ├── spice_name_mapping.json # USDA search term mappings
-│   └── raw/
-│       ├── usda/              # Cached API responses
-│       └── metadata.json      # API call tracking
-│
-├── data_ingest/               # Data collection scripts (not deployed)
-│   ├── usda_client.py         # USDA API client
-│   ├── fetch_all_spices.py   # Batch data fetcher
-│   └── ...
+│   ├── spice_images_local.json # Local image mappings
+│   └── raw/                   # Cached API responses
 │
 ├── neo4j_setup/               # Database setup scripts (not deployed)
-│   ├── test_connection.py    # Connection tester
-│   ├── create_schema.py      # Schema creation
-│   └── load_data.py          # Data loader
+│   ├── test_connection.py     # Connection tester
+│   ├── create_schema.py       # Schema creation
+│   ├── load_data.py           # Data loader
+│   ├── fetch_wikipedia_images.py  # Image fetcher
+│   └── download_spice_images.py   # Image downloader
 │
-└── tools/                     # Core application logic
-    ├── __init__.py           # Module exports
-    ├── neo4j_queries.py      # Database queries
-    └── mcp_tools.py          # MCP tool definitions
+└── data_ingest/               # Data collection scripts (not deployed)
+    ├── usda_client.py         # USDA API client
+    └── fetch_all_spices.py    # Batch data fetcher
 ```
 
 ## Disclaimer
@@ -239,10 +298,20 @@ For issues or questions:
 ## Acknowledgments
 
 - **USDA FoodData Central** for comprehensive nutritional data
+- **NCCIH** for health benefits and safety information
 - **Neo4j Aura** for graph database hosting
 - **Gradio** for the web UI framework and MCP server capabilities
-- **Anthropic** for the Model Context Protocol specification
+- **LlamaIndex** for the agent orchestration framework
+- **Anthropic** for Claude AI and the Model Context Protocol specification
+- **Wikipedia** for spice images with proper attribution
+
+## References
+
+- [MCP's 1st Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday)
+- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
+- [Gradio MCP Server Documentation](https://www.gradio.app/guides/mcp-server)
+- [LlamaIndex Documentation](https://docs.llamaindex.ai/)
 
 ---
 
-Built with ❤️ for medicinal cuisine enthusiasts
+Built for medicinal cuisine enthusiasts

app.py

@@ -3,335 +3,599 @@
 This application provides:
 1. Web UI for querying spice information
 2. MCP server at /gradio_api/mcp/ for AI agent integration
+3. Conversational AI chat interface (LlamaIndex + Claude)
 
 All data is sourced from USDA FoodData Central with full attribution.
 """
 
 import os
+import traceback
+from functools import wraps
+from typing import List, Tuple, Callable, Any
 from dotenv import load_dotenv
 import gradio as gr
+
+
+def handle_errors(func: Callable) -> Callable:
+    """Decorator to handle errors gracefully in UI functions.
+
+    Args:
+        func: Function to wrap with error handling.
+
+    Returns:
+        Wrapped function that catches exceptions.
+    """
+    @wraps(func)
+    def wrapper(*args, **kwargs) -> Any:
+        try:
+            return func(*args, **kwargs)
+        except ConnectionError:
+            return None, "Connection error. Please check your internet connection and try again."
+        except TimeoutError:
+            return None, "Request timed out. The server may be busy. Please try again."
+        except Exception as e:
+            error_msg = f"An error occurred: {str(e)}"
+            print(f"[ERROR] {func.__name__}: {traceback.format_exc()}")
+            if hasattr(func, '__annotations__'):
+                return_type = func.__annotations__.get('return', None)
+                if return_type and 'Tuple' in str(return_type):
+                    return None, error_msg
+            return error_msg
+    return wrapper
+
+
 from tools.mcp_tools import (
-    get_spice_information,
-    list_available_spices,
-    get_nutrient_content,
-    compare_spices,
-    find_spice_substitutes,
-    get_health_benefits_info,
-    find_spices_for_health_benefit,
-    get_spice_safety_information,
-    find_medicinal_substitutes
+    get_spice_information as _get_spice_information,
+    get_spice_info_with_image as _get_spice_info_with_image,
+    get_health_benefits_with_image as _get_health_benefits_with_image,
+    get_safety_info_with_image as _get_safety_info_with_image,
+    list_available_spices as _list_available_spices,
+    get_nutrient_content as _get_nutrient_content,
+    compare_spices as _compare_spices,
+    find_spice_substitutes as _find_spice_substitutes,
+    get_health_benefits_info as _get_health_benefits_info,
+    find_spices_for_health_benefit as _find_spices_for_health_benefit,
+    get_spice_safety_information as _get_spice_safety_information,
+    find_medicinal_substitutes as _find_medicinal_substitutes
 )
+from tools.llama_agent import SpiceAgent
+
+
+# Wrap all functions with error handling
+@handle_errors
+def get_spice_information(spice_name: str) -> str:
+    return _get_spice_information(spice_name)
+
+
+@handle_errors
+def get_spice_info_with_image(spice_name: str) -> Tuple[str, str]:
+    return _get_spice_info_with_image(spice_name)
+
+
+@handle_errors
+def get_health_benefits_with_image(spice_name: str) -> Tuple[str, str]:
+    return _get_health_benefits_with_image(spice_name)
+
+
+@handle_errors
+def get_safety_info_with_image(spice_name: str) -> Tuple[str, str]:
+    return _get_safety_info_with_image(spice_name)
+
+
+@handle_errors
+def list_available_spices() -> str:
+    return _list_available_spices()
+
+
+@handle_errors
+def get_nutrient_content(spice_name: str, nutrient_name: str) -> str:
+    return _get_nutrient_content(spice_name, nutrient_name)
+
+
+@handle_errors
+def compare_spices(spice1: str, spice2: str) -> str:
+    return _compare_spices(spice1, spice2)
+
+
+@handle_errors
+def find_spice_substitutes(spice_name: str, limit: int = 5) -> str:
+    return _find_spice_substitutes(spice_name, limit)
+
+
+@handle_errors
+def get_health_benefits_info(spice_name: str) -> str:
+    return _get_health_benefits_info(spice_name)
+
+
+@handle_errors
+def find_spices_for_health_benefit(benefit: str) -> str:
+    return _find_spices_for_health_benefit(benefit)
+
+
+@handle_errors
+def get_spice_safety_information(spice_name: str) -> str:
+    return _get_spice_safety_information(spice_name)
+
 
 if not os.getenv("SPACE_ID"):
     load_dotenv()
-    
-def create_spice_info_tab():
-    """Create the spice information lookup tab."""
-    with gr.Tab("Spice Information"):
-        gr.Markdown("### Look up detailed information about a spice")
 
-        with gr.Row():
-            spice_input = gr.Textbox(
-                label="Spice Name",
-                placeholder="e.g., turmeric, ginger, cinnamon",
-                scale=3
-            )
-            search_btn = gr.Button("Search", variant="primary", scale=1)
+# Initialize LlamaIndex agent (lazy initialization)
+spice_agent = None
 
-        output = gr.Textbox(
-            label="Spice Information",
-            lines=15,
-            interactive=False
-        )
 
-        gr.Examples(
-            examples=[["turmeric"], ["ginger root"], ["cinnamon"], ["garlic"]],
-            inputs=spice_input
-        )
+def get_agent() -> SpiceAgent:
+    """Get or create the spice agent instance."""
+    global spice_agent
+    if spice_agent is None:
+        spice_agent = SpiceAgent()
+    return spice_agent
 
-        search_btn.click(
-            fn=get_spice_information,
-            inputs=spice_input,
-            outputs=output
-        )
 
+def get_usage_stats() -> str:
+    """Get usage statistics from the guardrails.
 
-def create_nutrient_lookup_tab():
-    """Create the nutrient content lookup tab."""
-    with gr.Tab("Nutrient Content"):
-        gr.Markdown("### Find specific nutrient content in a spice")
+    Returns:
+        Formatted usage statistics string.
+    """
+    agent = get_agent()
 
-        with gr.Row():
-            spice_input = gr.Textbox(
-                label="Spice Name",
-                placeholder="e.g., turmeric",
-                scale=2
-            )
-            nutrient_input = gr.Textbox(
-                label="Nutrient Name",
-                placeholder="e.g., iron, vitamin C, calcium",
-                scale=2
-            )
-            search_btn = gr.Button("Search", variant="primary", scale=1)
+    if not agent.guardrails:
+        return "Guardrails are disabled. No usage tracking available."
 
-        output = gr.Textbox(
-            label="Nutrient Information",
-            lines=8,
-            interactive=False
-        )
+    usage_guardrail = agent.guardrails.get_guardrail("usage_tracking")
 
-        gr.Examples(
-            examples=[
-                ["turmeric", "iron"],
-                ["ginger root", "vitamin C"],
-                ["cinnamon", "calcium"]
-            ],
-            inputs=[spice_input, nutrient_input]
-        )
+    if not usage_guardrail:
+        return "Usage tracking guardrail not found."
 
-        search_btn.click(
-            fn=get_nutrient_content,
-            inputs=[spice_input, nutrient_input],
-            outputs=output
-        )
+    summary = usage_guardrail.get_daily_summary()
 
+    output = []
+    output.append("=== USAGE DASHBOARD ===\n")
+    output.append(f"Date: {summary['date']}")
+    output.append(f"Total Requests: {summary['total_requests']}")
+    output.append(f"\n--- Token Usage ---")
+    output.append(f"Input Tokens: {summary['total_input_tokens']:,}")
+    output.append(f"Output Tokens: {summary['total_output_tokens']:,}")
+    output.append(f"Total Tokens: {summary['total_input_tokens'] + summary['total_output_tokens']:,}")
+    output.append(f"\n--- Cost ---")
+    output.append(f"Today's Cost: ${summary['total_cost_usd']:.4f}")
+    output.append(f"Daily Limit: ${summary['daily_limit_usd']:.2f}")
+    output.append(f"Remaining Budget: ${summary['remaining_budget_usd']:.4f}")
 
-def create_comparison_tab():
-    """Create the spice comparison tab."""
-    with gr.Tab("Compare Spices"):
-        gr.Markdown("### Compare nutritional content of two spices")
+    pct_used = (summary['total_cost_usd'] / summary['daily_limit_usd']) * 100 if summary['daily_limit_usd'] > 0 else 0
+    output.append(f"Budget Used: {pct_used:.1f}%")
 
-        with gr.Row():
-            spice1_input = gr.Textbox(
-                label="Spice 1",
-                placeholder="e.g., turmeric",
-                scale=2
-            )
-            spice2_input = gr.Textbox(
-                label="Spice 2",
-                placeholder="e.g., ginger root",
-                scale=2
-            )
-            compare_btn = gr.Button("Compare", variant="primary", scale=1)
+    return "\n".join(output)
 
-        output = gr.Textbox(
-            label="Comparison Results",
-            lines=20,
-            interactive=False
-        )
 
-        gr.Examples(
-            examples=[
-                ["turmeric", "ginger root"],
-                ["cinnamon", "nutmeg"],
-                ["garlic", "ginger root"]
-            ],
-            inputs=[spice1_input, spice2_input]
-        )
+def chat_response(
+    message: str,
+    history: List[Tuple[str, str]]
+) -> Tuple[str, List[Tuple[str, str]]]:
+    """Process chat message and return response.
 
-        compare_btn.click(
-            fn=compare_spices,
-            inputs=[spice1_input, spice2_input],
-            outputs=output
+    Args:
+        message: User's input message.
+        history: List of (user, assistant) message tuples.
+
+    Returns:
+        Tuple of (empty string for input, updated history).
+    """
+    agent = get_agent()
+
+    if not agent.is_ready():
+        response = (
+            "The AI chat feature requires an Anthropic API key (ANTHROPIC_API_KEY). "
+            "Please use the individual tabs above for spice queries, or set "
+            "the ANTHROPIC_API_KEY environment variable to enable conversational AI."
         )
+    else:
+        response = agent.chat(message)
 
+    history.append((message, response))
+    return "", history
 
-def create_substitute_finder_tab():
-    """Create the spice substitute finder tab."""
-    with gr.Tab("Find Substitutes"):
+
+def create_chat_tab():
+    """Create the conversational AI chat tab."""
+    with gr.Tab("AI Chat"):
         gr.Markdown(
             """
-            ### Find substitute spices based on nutritional similarity
+            ### Ask me anything about spices!
+
+            I can help you with:
+            - Spice information and nutritional data
+            - Health benefits and traditional uses
+            - Finding substitutes for spices
+            - Safety information and cautions
 
-            Uses dynamic cosine similarity on nutrient profiles from USDA data.
-            Perfect for when you're missing a spice in your recipe!
+            **Note:** Requires ANTHROPIC_API_KEY for AI responses. Use other tabs if unavailable.
             """
         )
 
+        chatbot = gr.Chatbot(
+            label="Conversation",
+            height=400,
+            type="tuples",
+            show_copy_button=True
+        )
+
         with gr.Row():
-            spice_input = gr.Textbox(
-                label="Spice Name",
-                placeholder="e.g., turmeric, cinnamon, cumin",
-                value="cinnamon",
-                scale=3
-            )
-            limit_slider = gr.Slider(
-                minimum=3,
-                maximum=10,
-                value=5,
-                step=1,
-                label="Number of Substitutes",
-                scale=1
+            msg_input = gr.Textbox(
+                label="Your Question",
+                placeholder="e.g., What spices help with inflammation?",
+                scale=4,
+                show_label=False
             )
+            send_btn = gr.Button("Send", variant="primary", scale=1)
 
-        find_btn = gr.Button("Find Substitutes", variant="primary")
-
-        output = gr.Textbox(
-            label="Substitute Suggestions",
-            lines=20,
-            interactive=False
-        )
+        status = gr.Markdown("", elem_classes=["status-ready"])
 
         gr.Examples(
             examples=[
-                ["cinnamon", 5],
-                ["turmeric", 5],
-                ["Black Pepper", 3],
-                ["basil, dried", 5]
+                ["What are the health benefits of turmeric?"],
+                ["Which spices help lower cholesterol?"],
+                ["What's a good substitute for cinnamon?"],
+                ["Is garlic safe to take with blood thinners?"],
+                ["What spices are high in iron?"],
             ],
-            inputs=[spice_input, limit_slider]
+            inputs=msg_input
         )
 
-        find_btn.click(
-            fn=find_spice_substitutes,
-            inputs=[spice_input, limit_slider],
-            outputs=output
+        def chat_with_status(message, history):
+            """Chat response with status updates."""
+            result = chat_response(message, history)
+            return result[0], result[1], ""
+
+        msg_input.submit(
+            fn=lambda: "Thinking...",
+            outputs=status
+        ).then(
+            fn=chat_with_status,
+            inputs=[msg_input, chatbot],
+            outputs=[msg_input, chatbot, status],
+            show_progress="minimal"
+        )
+        send_btn.click(
+            fn=lambda: "Thinking...",
+            outputs=status
+        ).then(
+            fn=chat_with_status,
+            inputs=[msg_input, chatbot],
+            outputs=[msg_input, chatbot, status],
+            show_progress="minimal"
         )
 
 
-def create_spice_list_tab():
-    """Create the available spices list tab."""
-    with gr.Tab("Available Spices"):
-        gr.Markdown("### View all spices in the database")
-
-        list_btn = gr.Button("Show All Spices", variant="primary")
+def create_spice_database_tab():
+    """Create the consolidated spice database tab."""
+    with gr.Tab("Spice Database"):
+        gr.Markdown("### Explore spice information, nutrients, and comparisons")
+
+        with gr.Accordion("Spice Lookup", open=True):
+            with gr.Row():
+                spice_input = gr.Textbox(
+                    label="Spice Name",
+                    placeholder="e.g., turmeric, ginger, cinnamon",
+                    scale=3
+                )
+                search_btn = gr.Button("Search", variant="primary", scale=1)
+
+            with gr.Row():
+                spice_image = gr.Image(
+                    label="Spice Image",
+                    height=200,
+                    width=200,
+                    show_label=False,
+                    scale=1
+                )
+                info_output = gr.Textbox(
+                    label="Spice Information",
+                    lines=10,
+                    interactive=False,
+                    scale=3
+                )
+
+            gr.Examples(
+                examples=[["turmeric"], ["ginger root"], ["cinnamon"], ["garlic"]],
+                inputs=spice_input
+            )
 
-        output = gr.Textbox(
-            label="Spice List",
-            lines=15,
-            interactive=False
-        )
+            search_btn.click(
+                fn=get_spice_info_with_image,
+                inputs=spice_input,
+                outputs=[spice_image, info_output],
+                show_progress="minimal"
+            )
+            spice_input.submit(
+                fn=get_spice_info_with_image,
+                inputs=spice_input,
+                outputs=[spice_image, info_output],
+                show_progress="minimal"
+            )
 
-        list_btn.click(
-            fn=list_available_spices,
-            outputs=output
-        )
+        with gr.Accordion("Find Substitutes", open=False):
+            with gr.Row():
+                sub_spice_input = gr.Textbox(
+                    label="Spice Name",
+                    placeholder="e.g., cinnamon",
+                    scale=3
+                )
+                limit_slider = gr.Slider(
+                    minimum=3, maximum=10, value=5, step=1,
+                    label="Results", scale=1
+                )
+                find_btn = gr.Button("Find", variant="primary", scale=1)
+
+            sub_output = gr.Textbox(
+                label="Substitute Suggestions",
+                lines=12,
+                interactive=False
+            )
 
+            find_btn.click(
+                fn=find_spice_substitutes,
+                inputs=[sub_spice_input, limit_slider],
+                outputs=sub_output,
+                show_progress="minimal"
+            )
 
-def create_health_benefits_tab():
-    """Create the health benefits information tab."""
-    with gr.Tab("Health Benefits"):
-        gr.Markdown(
-            """
-            ### Learn about health benefits and medicinal properties
+        with gr.Accordion("Compare Spices", open=False):
+            with gr.Row():
+                spice1_input = gr.Textbox(label="Spice 1", placeholder="e.g., turmeric", scale=2)
+                spice2_input = gr.Textbox(label="Spice 2", placeholder="e.g., ginger", scale=2)
+                compare_btn = gr.Button("Compare", variant="primary", scale=1)
 
-            Data sourced from **NCCIH (National Center for Complementary and Integrative Health)**
-            """
-        )
+            compare_output = gr.Textbox(
+                label="Comparison Results",
+                lines=15,
+                interactive=False
+            )
 
-        with gr.Row():
-            spice_input = gr.Textbox(
-                label="Spice Name",
-                placeholder="e.g., Garlic, Cinnamon, Sage",
-                scale=3
+            compare_btn.click(
+                fn=compare_spices,
+                inputs=[spice1_input, spice2_input],
+                outputs=compare_output,
+                show_progress="minimal"
             )
-            search_btn = gr.Button("Get Health Info", variant="primary", scale=1)
 
-        output = gr.Textbox(
-            label="Health Information",
-            lines=20,
-            interactive=False
-        )
+        with gr.Accordion("Nutrient Lookup", open=False):
+            with gr.Row():
+                nut_spice = gr.Textbox(label="Spice", placeholder="e.g., turmeric", scale=2)
+                nut_name = gr.Textbox(label="Nutrient", placeholder="e.g., iron", scale=2)
+                nut_btn = gr.Button("Search", variant="primary", scale=1)
 
-        gr.Examples(
-            examples=[["Garlic"], ["Cinnamon"], ["Fenugreek"], ["Sage"]],
-            inputs=spice_input
-        )
+            nut_output = gr.Textbox(label="Nutrient Information", lines=6, interactive=False)
 
-        search_btn.click(
-            fn=get_health_benefits_info,
-            inputs=spice_input,
-            outputs=output
-        )
+            nut_btn.click(
+                fn=get_nutrient_content,
+                inputs=[nut_spice, nut_name],
+                outputs=nut_output,
+                show_progress="minimal"
+            )
+
+        with gr.Accordion("All Available Spices", open=False):
+            list_btn = gr.Button("Show All Spices", variant="secondary")
+            list_output = gr.Textbox(label="Spice List", lines=12, interactive=False)
+
+            list_btn.click(
+                fn=list_available_spices,
+                outputs=list_output,
+                show_progress="minimal"
+            )
 
 
-def create_health_search_tab():
-    """Create the health benefit search tab."""
-    with gr.Tab("Search by Health Benefit"):
+def create_health_safety_tab():
+    """Create the consolidated health and safety tab."""
+    with gr.Tab("Health & Safety"):
         gr.Markdown(
             """
-            ### Find spices for specific health conditions
-
-            Search traditional uses and scientific research
+            ### Health benefits and safety information
+            Data sourced from **NCCIH** (National Center for Complementary and Integrative Health)
             """
         )
 
-        with gr.Row():
-            benefit_input = gr.Textbox(
-                label="Health Benefit or Condition",
-                placeholder="e.g., diabetes, cholesterol, inflammation",
-                scale=3
+        with gr.Accordion("Health Benefits Lookup", open=True):
+            with gr.Row():
+                health_spice = gr.Textbox(
+                    label="Spice Name",
+                    placeholder="e.g., Garlic, Cinnamon",
+                    scale=3
+                )
+                health_btn = gr.Button("Get Health Info", variant="primary", scale=1)
+
+            with gr.Row():
+                health_image = gr.Image(
+                    label="Spice Image",
+                    height=200,
+                    width=200,
+                    show_label=False,
+                    scale=1
+                )
+                health_output = gr.Textbox(
+                    label="Health Information",
+                    lines=12,
+                    interactive=False,
+                    scale=3
+                )
+
+            gr.Examples(
+                examples=[["Garlic"], ["Cinnamon"], ["Fenugreek"], ["Turmeric"]],
+                inputs=health_spice
             )
-            search_btn = gr.Button("Search", variant="primary", scale=1)
-
-        output = gr.Textbox(
-            label="Matching Spices",
-            lines=15,
-            interactive=False
-        )
 
-        gr.Examples(
-            examples=[["diabetes"], ["cholesterol"], ["blood pressure"], ["inflammation"]],
-            inputs=benefit_input
-        )
+            health_btn.click(
+                fn=get_health_benefits_with_image,
+                inputs=health_spice,
+                outputs=[health_image, health_output],
+                show_progress="minimal"
+            )
+            health_spice.submit(
+                fn=get_health_benefits_with_image,
+                inputs=health_spice,
+                outputs=[health_image, health_output],
+                show_progress="minimal"
+            )
 
-        search_btn.click(
-            fn=find_spices_for_health_benefit,
-            inputs=benefit_input,
-            outputs=output
-        )
+        with gr.Accordion("Search by Health Condition", open=False):
+            with gr.Row():
+                condition_input = gr.Textbox(
+                    label="Health Condition",
+                    placeholder="e.g., diabetes, cholesterol, inflammation",
+                    scale=3
+                )
+                condition_btn = gr.Button("Search", variant="primary", scale=1)
+
+            condition_output = gr.Textbox(
+                label="Matching Spices",
+                lines=12,
+                interactive=False
+            )
 
+            gr.Examples(
+                examples=[["diabetes"], ["cholesterol"], ["inflammation"]],
+                inputs=condition_input
+            )
 
-def create_safety_info_tab():
-    """Create the safety information tab."""
-    with gr.Tab("Safety Information"):
-        gr.Markdown(
-            """
-            ### Check side effects and safety cautions
+            condition_btn.click(
+                fn=find_spices_for_health_benefit,
+                inputs=condition_input,
+                outputs=condition_output,
+                show_progress="minimal"
+            )
 
-            Important safety information for medicinal use
-            """
-        )
+        with gr.Accordion("Safety Information", open=False):
+            with gr.Row():
+                safety_spice = gr.Textbox(
+                    label="Spice Name",
+                    placeholder="e.g., Garlic, Cinnamon",
+                    scale=3
+                )
+                safety_btn = gr.Button("Get Safety Info", variant="primary", scale=1)
+
+            with gr.Row():
+                safety_image = gr.Image(
+                    label="Spice Image",
+                    height=200,
+                    width=200,
+                    show_label=False,
+                    scale=1
+                )
+                safety_output = gr.Textbox(
+                    label="Safety Information",
+                    lines=12,
+                    interactive=False,
+                    scale=3
+                )
+
+            gr.Markdown(
+                "**IMPORTANT:** Always consult healthcare providers before using herbs medicinally."
+            )
 
-        with gr.Row():
-            spice_input = gr.Textbox(
-                label="Spice Name",
-                placeholder="e.g., Garlic, Cinnamon",
-                scale=3
+            safety_btn.click(
+                fn=get_safety_info_with_image,
+                inputs=safety_spice,
+                outputs=[safety_image, safety_output],
+                show_progress="minimal"
+            )
+            safety_spice.submit(
+                fn=get_safety_info_with_image,
+                inputs=safety_spice,
+                outputs=[safety_image, safety_output],
+                show_progress="minimal"
             )
-            search_btn = gr.Button("Get Safety Info", variant="primary", scale=1)
 
-        output = gr.Textbox(
-            label="Safety Information",
-            lines=18,
-            interactive=False
-        )
 
-        gr.Examples(
-            examples=[["Garlic"], ["Cinnamon"], ["Fenugreek"]],
-            inputs=spice_input
-        )
+def create_usage_dashboard_tab():
+    """Create the usage dashboard tab."""
+    with gr.Tab("Usage"):
+        gr.Markdown("### API Usage Dashboard")
 
-        gr.Markdown(
-            """
-            **IMPORTANT:** This information is for educational purposes only.
-            Always consult healthcare providers before using herbs medicinally.
-            """
+        refresh_btn = gr.Button("Refresh Stats", variant="primary")
+
+        stats_output = gr.Textbox(
+            label="Usage Statistics",
+            lines=12,
+            interactive=False,
+            value="Click 'Refresh Stats' to view current usage."
         )
 
-        search_btn.click(
-            fn=get_spice_safety_information,
-            inputs=spice_input,
-            outputs=output
+        gr.Markdown("*Usage tracked for AI Chat. Stats reset daily.*")
+
+        refresh_btn.click(
+            fn=get_usage_stats,
+            outputs=stats_output,
+            show_progress="minimal"
         )
 
 
+# Custom CSS for better loading indicators and styling (supports dark mode)
+CUSTOM_CSS = """
+/* Light mode styles */
+.loading-indicator {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 8px 12px;
+    background: linear-gradient(90deg, #f0f7ff 0%, #e8f4fd 100%);
+    border-radius: 6px;
+    margin: 8px 0;
+}
+.loading-spinner {
+    width: 16px;
+    height: 16px;
+    border: 2px solid #3b82f6;
+    border-top-color: transparent;
+    border-radius: 50%;
+    animation: spin 0.8s linear infinite;
+}
+@keyframes spin {
+    to { transform: rotate(360deg); }
+}
+.status-ready { color: #059669; }
+.status-loading { color: #3b82f6; }
+.status-error { color: #dc2626; }
+footer { display: none !important; }
+
+/* Dark mode styles */
+@media (prefers-color-scheme: dark) {
+    .loading-indicator {
+        background: linear-gradient(90deg, #1e3a5f 0%, #1a365d 100%);
+    }
+    .status-ready { color: #34d399; }
+    .status-loading { color: #60a5fa; }
+    .status-error { color: #f87171; }
+}
+
+/* Gradio dark mode class overrides */
+.dark .loading-indicator {
+    background: linear-gradient(90deg, #1e3a5f 0%, #1a365d 100%);
+}
+.dark .status-ready { color: #34d399; }
+.dark .status-loading { color: #60a5fa; }
+.dark .status-error { color: #f87171; }
+
+/* Improved image styling */
+.image-container img {
+    border-radius: 8px;
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+.dark .image-container img {
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.3);
+}
+"""
+
 # Create main application
-with gr.Blocks(title="Medicinal Cuisine AI Advisor") as demo:
+with gr.Blocks(
+    title="Medicinal Cuisine AI Advisor",
+    theme=gr.themes.Soft(),
+    css=CUSTOM_CSS
+) as demo:
 
     gr.Markdown(
         """
-        # 🌿 Medicinal Cuisine AI Advisor
+        # Medicinal Cuisine AI Advisor
 
         Explore spices, their nutritional content, and health properties.
         All data sourced from **USDA FoodData Central** with full attribution.
@@ -340,24 +604,20 @@ with gr.Blocks(title="Medicinal Cuisine AI Advisor") as demo:
         """
     )
 
-    # Create tabs
-    create_spice_info_tab()
-    create_nutrient_lookup_tab()
-    create_health_benefits_tab()
-    create_health_search_tab()
-    create_safety_info_tab()
-    create_comparison_tab()
-    create_substitute_finder_tab()
-    create_spice_list_tab()
+    # Create consolidated tabs (4 tabs instead of 10)
+    create_chat_tab()
+    create_spice_database_tab()
+    create_health_safety_tab()
+    create_usage_dashboard_tab()
 
     gr.Markdown(
         """
         ---
         **Data Sources:** USDA FoodData Central | NCCIH (Public Domain)
 
-        **MCP Server:** Available at `/gradio_api/mcp/`
+        **Images:** Wikipedia/Wikimedia Commons (CC/Public Domain)
 
-        **25 spices** | **2,098 nutrient relationships** | **NEW: Health Benefits & Safety Info!**
+        **MCP Server:** Available at `/gradio_api/mcp/`
         """
     )
 

data/spice_images.json

@@ -0,0 +1,294 @@
+{
+  "default_image": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/45/A_small_cup_of_coffee.JPG/640px-A_small_cup_of_coffee.JPG",
+  "source_attribution": "Images sourced from Wikipedia/Wikimedia Commons. See individual spice entries for specific licenses.",
+  "spice_images": {
+    "turmeric": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/a/ab/Turmeric_inflorescence.jpg/500px-Turmeric_inflorescence.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/a/ab/Turmeric_inflorescence.jpg",
+      "source": "https://en.wikipedia.org/wiki/Turmeric",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "ginger root": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/18/Koeh-146-no_text.jpg/500px-Koeh-146-no_text.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/1/18/Koeh-146-no_text.jpg",
+      "source": "https://en.wikipedia.org/wiki/Ginger",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "ginger": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/18/Koeh-146-no_text.jpg/500px-Koeh-146-no_text.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/1/18/Koeh-146-no_text.jpg",
+      "source": "https://en.wikipedia.org/wiki/Ginger",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "cinnamon": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/de/Cinnamomum_verum_spices.jpg/500px-Cinnamomum_verum_spices.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/d/de/Cinnamomum_verum_spices.jpg",
+      "source": "https://en.wikipedia.org/wiki/Cinnamon",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "garlic": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/3/39/Allium_sativum_Woodwill_1793.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/3/39/Allium_sativum_Woodwill_1793.jpg",
+      "source": "https://en.wikipedia.org/wiki/Garlic",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "black pepper": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/f/fd/Piper_nigrum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-107.jpg/400px-Piper_nigrum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-107.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/f/fd/Piper_nigrum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-107.jpg",
+      "source": "https://en.wikipedia.org/wiki/Black_pepper",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "cumin": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/5/58/Cuminum_cyminum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-198.jpg/400px-Cuminum_cyminum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-198.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/5/58/Cuminum_cyminum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-198.jpg",
+      "source": "https://en.wikipedia.org/wiki/Cumin",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "paprika": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/8/81/Piment%C3%B3n_Tap_de_Cort%C3%AD_%28cropped%29.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/8/81/Piment%C3%B3n_Tap_de_Cort%C3%AD_%28cropped%29.jpg",
+      "source": "https://en.wikipedia.org/wiki/Paprika",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "cayenne pepper": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/d2/Capsicum_annuum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-027.jpg/500px-Capsicum_annuum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-027.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/d/d2/Capsicum_annuum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-027.jpg",
+      "source": "https://en.wikipedia.org/wiki/Cayenne_pepper",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "chili powder": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/0/00/BolivianChilePowder2.JPG/500px-BolivianChilePowder2.JPG",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/0/00/BolivianChilePowder2.JPG",
+      "source": "https://en.wikipedia.org/wiki/Chili_powder",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "oregano": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/14/Origanum_vulgare_-_harilik_pune.jpg/500px-Origanum_vulgare_-_harilik_pune.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/1/14/Origanum_vulgare_-_harilik_pune.jpg",
+      "source": "https://en.wikipedia.org/wiki/Oregano",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "basil": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/97/Ocimum_basilicum_8zz.jpg/500px-Ocimum_basilicum_8zz.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/9/97/Ocimum_basilicum_8zz.jpg",
+      "source": "https://en.wikipedia.org/wiki/Basil",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "basil, dried": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/97/Ocimum_basilicum_8zz.jpg/500px-Ocimum_basilicum_8zz.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/9/97/Ocimum_basilicum_8zz.jpg",
+      "source": "https://en.wikipedia.org/wiki/Basil",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "thyme": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/e/ea/Thyme-Bundle.jpg/500px-Thyme-Bundle.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/e/ea/Thyme-Bundle.jpg",
+      "source": "https://en.wikipedia.org/wiki/Thyme",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "rosemary": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a3/Rosemary_in_bloom.JPG/500px-Rosemary_in_bloom.JPG",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/a/a3/Rosemary_in_bloom.JPG",
+      "source": "https://en.wikipedia.org/wiki/Rosemary",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "sage": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/5/5a/Salvia_officinalis0.jpg/500px-Salvia_officinalis0.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/5/5a/Salvia_officinalis0.jpg",
+      "source": "https://en.wikipedia.org/wiki/Salvia_officinalis",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "mint": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/4d/Mentha_spicata-IMG_6186.jpg/500px-Mentha_spicata-IMG_6186.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/4/4d/Mentha_spicata-IMG_6186.jpg",
+      "source": "https://en.wikipedia.org/wiki/Mentha",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "parsley": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e4/Petroselinum.jpg/500px-Petroselinum.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/e/e4/Petroselinum.jpg",
+      "source": "https://en.wikipedia.org/wiki/Parsley",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "cilantro": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/13/Coriandrum_sativum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-193.jpg/400px-Coriandrum_sativum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-193.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/1/13/Coriandrum_sativum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-193.jpg",
+      "source": "https://en.wikipedia.org/wiki/Coriander",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "coriander": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/13/Coriandrum_sativum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-193.jpg/400px-Coriandrum_sativum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-193.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/1/13/Coriandrum_sativum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-193.jpg",
+      "source": "https://en.wikipedia.org/wiki/Coriander",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "nutmeg": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c8/Biji_Pala_Bubuk.jpg/500px-Biji_Pala_Bubuk.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/c/c8/Biji_Pala_Bubuk.jpg",
+      "source": "https://en.wikipedia.org/wiki/Nutmeg",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "clove": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/4b/Syzygium_aromaticum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-030.jpg/400px-Syzygium_aromaticum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-030.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/4/4b/Syzygium_aromaticum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-030.jpg",
+      "source": "https://en.wikipedia.org/wiki/Clove",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "cardamom": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/66/02017_0119_Kardamom%2C_Winter_in_den_Beskiden.jpg/500px-02017_0119_Kardamom%2C_Winter_in_den_Beskiden.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/6/66/02017_0119_Kardamom%2C_Winter_in_den_Beskiden.jpg",
+      "source": "https://en.wikipedia.org/wiki/Cardamom",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "fennel": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c0/Foeniculum_July_2011-1a.jpg/500px-Foeniculum_July_2011-1a.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/c/c0/Foeniculum_July_2011-1a.jpg",
+      "source": "https://en.wikipedia.org/wiki/Fennel",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "mustard": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/3/35/Mustard.png/500px-Mustard.png",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/3/35/Mustard.png",
+      "source": "https://en.wikipedia.org/wiki/Mustard_seed",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "saffron": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/68/Saffron_-_premium_spice.jpg/500px-Saffron_-_premium_spice.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/6/68/Saffron_-_premium_spice.jpg",
+      "source": "https://en.wikipedia.org/wiki/Saffron",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "vanilla": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0f/Vanilla_planifolia_%286998639597%29.jpg/500px-Vanilla_planifolia_%286998639597%29.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/0/0f/Vanilla_planifolia_%286998639597%29.jpg",
+      "source": "https://en.wikipedia.org/wiki/Vanilla",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "bay leaf": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a8/Bay_Leaves.JPG/500px-Bay_Leaves.JPG",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/a/a8/Bay_Leaves.JPG",
+      "source": "https://en.wikipedia.org/wiki/Bay_leaf",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "dill": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/4b/Illustration_Anethum_graveolens_clean.jpg/500px-Illustration_Anethum_graveolens_clean.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/4/4b/Illustration_Anethum_graveolens_clean.jpg",
+      "source": "https://en.wikipedia.org/wiki/Dill",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "tarragon": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/6/6c/Estragon_1511.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/6/6c/Estragon_1511.jpg",
+      "source": "https://en.wikipedia.org/wiki/Tarragon",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "marjoram": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/5/5c/Origanum_majorana_002.JPG/500px-Origanum_majorana_002.JPG",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/5/5c/Origanum_majorana_002.JPG",
+      "source": "https://en.wikipedia.org/wiki/Marjoram",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "allspice": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/a/a5/Pimenta_dioica_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-239.jpg/400px-Pimenta_dioica_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-239.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/a/a5/Pimenta_dioica_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-239.jpg",
+      "source": "https://en.wikipedia.org/wiki/Allspice",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "anise": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/3/3b/Koehler1887-PimpinellaAnisum.jpg/400px-Koehler1887-PimpinellaAnisum.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/3/3b/Koehler1887-PimpinellaAnisum.jpg",
+      "source": "https://en.wikipedia.org/wiki/Anise",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "star anise": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/7c/Illicium_verum_1zz.jpg/500px-Illicium_verum_1zz.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/7/7c/Illicium_verum_1zz.jpg",
+      "source": "https://en.wikipedia.org/wiki/Illicium_verum",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "fenugreek": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/ce/Illustration_Trigonella_foenum-graecum0_clean.jpg/500px-Illustration_Trigonella_foenum-graecum0_clean.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/c/ce/Illustration_Trigonella_foenum-graecum0_clean.jpg",
+      "source": "https://en.wikipedia.org/wiki/Fenugreek",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "curry powder": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Curry_powder_in_the_spice-bazaar_in_Istanbul.jpg/500px-Curry_powder_in_the_spice-bazaar_in_Istanbul.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/6/60/Curry_powder_in_the_spice-bazaar_in_Istanbul.jpg",
+      "source": "https://en.wikipedia.org/wiki/Curry_powder",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "garam masala": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/5/58/Garammasalaphoto.jpg/500px-Garammasalaphoto.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/5/58/Garammasalaphoto.jpg",
+      "source": "https://en.wikipedia.org/wiki/Garam_masala",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "onion powder": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/3/36/Onion_Powder%2C_Penzeys_Spices%2C_Arlington_Heights_MA.jpg/500px-Onion_Powder%2C_Penzeys_Spices%2C_Arlington_Heights_MA.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/3/36/Onion_Powder%2C_Penzeys_Spices%2C_Arlington_Heights_MA.jpg",
+      "source": "https://en.wikipedia.org/wiki/Onion_powder",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "garlic powder": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c3/Masterfoods_Garlic_Powder.jpg/500px-Masterfoods_Garlic_Powder.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/c/c3/Masterfoods_Garlic_Powder.jpg",
+      "source": "https://en.wikipedia.org/wiki/Garlic_powder",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "celery seed": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/0/0d/Celery_1.jpg/500px-Celery_1.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/0/0d/Celery_1.jpg",
+      "source": "https://en.wikipedia.org/wiki/Celery_seed",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "caraway": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/42/Carum_carvi_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-172.jpg/400px-Carum_carvi_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-172.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/4/42/Carum_carvi_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-172.jpg",
+      "source": "https://en.wikipedia.org/wiki/Caraway",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "poppy seed": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/69/Poppy_seeds.jpg/500px-Poppy_seeds.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/6/69/Poppy_seeds.jpg",
+      "source": "https://en.wikipedia.org/wiki/Poppy_seed",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "sesame": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/70/Sesamum_indicum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-129.jpg/400px-Sesamum_indicum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-129.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/7/70/Sesamum_indicum_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-129.jpg",
+      "source": "https://en.wikipedia.org/wiki/Sesame",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "juniper": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1e/Juniperus_communis_fruits_-_Keila.jpg/500px-Juniperus_communis_fruits_-_Keila.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/1/1e/Juniperus_communis_fruits_-_Keila.jpg",
+      "source": "https://en.wikipedia.org/wiki/Juniper_berry",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "lavender": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/7e/Single_lavender_flower02.jpg/500px-Single_lavender_flower02.jpg",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/7/7e/Single_lavender_flower02.jpg",
+      "source": "https://en.wikipedia.org/wiki/Lavandula",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "chamomile": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/2/26/Kamomillasaunio_%28Matricaria_recutita%29.JPG/500px-Kamomillasaunio_%28Matricaria_recutita%29.JPG",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/2/26/Kamomillasaunio_%28Matricaria_recutita%29.JPG",
+      "source": "https://en.wikipedia.org/wiki/Chamomile",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "lemongrass": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/b/bd/YosriNov04Pokok_Serai.JPG/500px-YosriNov04Pokok_Serai.JPG",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/b/bd/YosriNov04Pokok_Serai.JPG",
+      "source": "https://en.wikipedia.org/wiki/Cymbopogon",
+      "license": "Wikimedia Commons (see source for specific license)"
+    },
+    "sumac": {
+      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/a/aa/SumacFruit.JPG/500px-SumacFruit.JPG",
+      "full_url": "https://upload.wikimedia.org/wikipedia/commons/a/aa/SumacFruit.JPG",
+      "source": "https://en.wikipedia.org/wiki/Sumac",
+      "license": "Wikimedia Commons (see source for specific license)"
+    }
+  }
+}

requirements.txt

@@ -1,3 +1,8 @@
 gradio[mcp]==5.50.0
 requests>=2.31.0
 python-dotenv>=1.0.0
+beautifulsoup4>=4.12.0
+
+# LlamaIndex for conversational AI
+llama-index>=0.11.0
+llama-index-llms-anthropic>=0.6.0

tools/guardrails.py

@@ -0,0 +1,788 @@
+"""Guardrails module for Medicinal Cuisine AI Agent.
+
+This module provides safety guardrails for the conversational AI interface,
+ensuring safe, responsible, and cost-effective usage across different LLM providers.
+
+Guardrails implemented:
+1. Input validation (length limits, sanitization)
+2. Rate limiting (per-session request limits)
+3. Medical disclaimer (automatic disclaimer injection)
+4. Topic filtering (block off-topic queries)
+5. Token/cost limits (cap max tokens per request)
+6. Usage tracking (monitor API spend)
+7. Audit logging (log queries for review)
+"""
+
+import json
+import os
+import re
+import time
+from abc import ABC, abstractmethod
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+class GuardrailResult(Enum):
+    """Result of a guardrail check."""
+    PASS = "pass"
+    BLOCK = "block"
+    WARN = "warn"
+    MODIFY = "modify"
+
+
+@dataclass
+class GuardrailResponse:
+    """Response from a guardrail check.
+
+    Attributes:
+        result: The result of the check (pass, block, warn, modify).
+        message: Optional message explaining the result.
+        modified_input: If result is MODIFY, the modified input to use.
+        metadata: Additional metadata about the check.
+    """
+    result: GuardrailResult
+    message: Optional[str] = None
+    modified_input: Optional[str] = None
+    metadata: Dict = field(default_factory=dict)
+
+
+class Guardrail(ABC):
+    """Abstract base class for all guardrails."""
+
+    def __init__(self, name: str, enabled: bool = True):
+        """Initialize the guardrail.
+
+        Args:
+            name: Name of the guardrail for logging.
+            enabled: Whether the guardrail is active.
+        """
+        self.name = name
+        self.enabled = enabled
+
+    @abstractmethod
+    def check_input(self, user_input: str, context: Dict) -> GuardrailResponse:
+        """Check user input before processing.
+
+        Args:
+            user_input: The user's message.
+            context: Additional context (session_id, user_id, etc.).
+
+        Returns:
+            GuardrailResponse indicating the result.
+        """
+        pass
+
+    def check_output(self, output: str, context: Dict) -> GuardrailResponse:
+        """Check agent output before returning to user.
+
+        Args:
+            output: The agent's response.
+            context: Additional context.
+
+        Returns:
+            GuardrailResponse indicating the result.
+        """
+        return GuardrailResponse(result=GuardrailResult.PASS)
+
+
+class InputLengthGuardrail(Guardrail):
+    """Guardrail to limit input length and prevent abuse."""
+
+    def __init__(
+        self,
+        max_length: int = 2000,
+        min_length: int = 1,
+        enabled: bool = True
+    ):
+        """Initialize input length guardrail.
+
+        Args:
+            max_length: Maximum allowed input length in characters.
+            min_length: Minimum required input length.
+            enabled: Whether the guardrail is active.
+        """
+        super().__init__(name="input_length", enabled=enabled)
+        self.max_length = max_length
+        self.min_length = min_length
+
+    def check_input(self, user_input: str, context: Dict) -> GuardrailResponse:
+        """Check if input length is within acceptable bounds."""
+        if not self.enabled:
+            return GuardrailResponse(result=GuardrailResult.PASS)
+
+        input_length = len(user_input.strip())
+
+        if input_length < self.min_length:
+            return GuardrailResponse(
+                result=GuardrailResult.BLOCK,
+                message="Please enter a question or message.",
+                metadata={"length": input_length, "min": self.min_length}
+            )
+
+        if input_length > self.max_length:
+            return GuardrailResponse(
+                result=GuardrailResult.BLOCK,
+                message=f"Input too long ({input_length} chars). Please limit to {self.max_length} characters.",
+                metadata={"length": input_length, "max": self.max_length}
+            )
+
+        return GuardrailResponse(
+            result=GuardrailResult.PASS,
+            metadata={"length": input_length}
+        )
+
+
+class RateLimitGuardrail(Guardrail):
+    """Guardrail to limit request rate per session."""
+
+    def __init__(
+        self,
+        max_requests_per_minute: int = 10,
+        max_requests_per_hour: int = 100,
+        enabled: bool = True
+    ):
+        """Initialize rate limit guardrail.
+
+        Args:
+            max_requests_per_minute: Max requests allowed per minute.
+            max_requests_per_hour: Max requests allowed per hour.
+            enabled: Whether the guardrail is active.
+        """
+        super().__init__(name="rate_limit", enabled=enabled)
+        self.max_requests_per_minute = max_requests_per_minute
+        self.max_requests_per_hour = max_requests_per_hour
+        self._request_times: Dict[str, List[float]] = defaultdict(list)
+
+    def _clean_old_requests(self, session_id: str, current_time: float) -> None:
+        """Remove request timestamps older than 1 hour."""
+        one_hour_ago = current_time - 3600
+        self._request_times[session_id] = [
+            t for t in self._request_times[session_id]
+            if t > one_hour_ago
+        ]
+
+    def check_input(self, user_input: str, context: Dict) -> GuardrailResponse:
+        """Check if request rate is within limits."""
+        if not self.enabled:
+            return GuardrailResponse(result=GuardrailResult.PASS)
+
+        session_id = context.get("session_id", "default")
+        current_time = time.time()
+
+        self._clean_old_requests(session_id, current_time)
+
+        one_minute_ago = current_time - 60
+        requests_last_minute = sum(
+            1 for t in self._request_times[session_id]
+            if t > one_minute_ago
+        )
+        requests_last_hour = len(self._request_times[session_id])
+
+        if requests_last_minute >= self.max_requests_per_minute:
+            return GuardrailResponse(
+                result=GuardrailResult.BLOCK,
+                message="Rate limit exceeded. Please wait a moment before sending another message.",
+                metadata={
+                    "requests_last_minute": requests_last_minute,
+                    "limit_per_minute": self.max_requests_per_minute
+                }
+            )
+
+        if requests_last_hour >= self.max_requests_per_hour:
+            return GuardrailResponse(
+                result=GuardrailResult.BLOCK,
+                message="Hourly rate limit exceeded. Please try again later.",
+                metadata={
+                    "requests_last_hour": requests_last_hour,
+                    "limit_per_hour": self.max_requests_per_hour
+                }
+            )
+
+        self._request_times[session_id].append(current_time)
+
+        return GuardrailResponse(
+            result=GuardrailResult.PASS,
+            metadata={
+                "requests_last_minute": requests_last_minute + 1,
+                "requests_last_hour": requests_last_hour + 1
+            }
+        )
+
+
+class MedicalDisclaimerGuardrail(Guardrail):
+    """Guardrail to ensure medical disclaimers are included in health-related responses."""
+
+    HEALTH_KEYWORDS = [
+        "health", "benefit", "cure", "treat", "disease", "condition",
+        "symptom", "medicine", "medicinal", "therapeutic", "healing",
+        "diabetes", "cholesterol", "blood pressure", "inflammation",
+        "pain", "infection", "illness", "disorder", "cancer", "heart",
+        "liver", "kidney", "stomach", "digestive", "immune", "anxiety",
+        "depression", "sleep", "weight", "diet", "pregnant", "pregnancy"
+    ]
+
+    DISCLAIMER = (
+        "\n\n---\n"
+        "**Disclaimer:** This information is for educational purposes only and "
+        "should not be considered medical advice. Always consult a qualified "
+        "healthcare provider before using herbs or spices for medicinal purposes."
+    )
+
+    def __init__(self, enabled: bool = True):
+        """Initialize medical disclaimer guardrail."""
+        super().__init__(name="medical_disclaimer", enabled=enabled)
+        self._health_pattern = re.compile(
+            r'\b(' + '|'.join(self.HEALTH_KEYWORDS) + r')\b',
+            re.IGNORECASE
+        )
+
+    def _is_health_related(self, text: str) -> bool:
+        """Check if text contains health-related keywords."""
+        return bool(self._health_pattern.search(text))
+
+    def check_input(self, user_input: str, context: Dict) -> GuardrailResponse:
+        """Mark context if input is health-related."""
+        is_health_query = self._is_health_related(user_input)
+        return GuardrailResponse(
+            result=GuardrailResult.PASS,
+            metadata={"is_health_query": is_health_query}
+        )
+
+    def check_output(self, output: str, context: Dict) -> GuardrailResponse:
+        """Add disclaimer to health-related responses."""
+        if not self.enabled:
+            return GuardrailResponse(result=GuardrailResult.PASS)
+
+        is_health_query = context.get("is_health_query", False)
+        is_health_response = self._is_health_related(output)
+
+        if (is_health_query or is_health_response) and self.DISCLAIMER not in output:
+            return GuardrailResponse(
+                result=GuardrailResult.MODIFY,
+                modified_input=output + self.DISCLAIMER,
+                metadata={"disclaimer_added": True}
+            )
+
+        return GuardrailResponse(
+            result=GuardrailResult.PASS,
+            metadata={"disclaimer_added": False}
+        )
+
+
+class TopicFilterGuardrail(Guardrail):
+    """Guardrail to filter off-topic queries."""
+
+    ALLOWED_TOPICS = [
+        "spice", "herb", "seasoning", "flavor", "ingredient",
+        "nutrient", "vitamin", "mineral", "nutrition", "food",
+        "cooking", "recipe", "cuisine", "health", "benefit",
+        "substitute", "alternative", "replacement", "similar",
+        "side effect", "caution", "safety", "interaction", "dosage"
+    ]
+
+    OFF_TOPIC_RESPONSE = (
+        "I'm a medicinal cuisine advisor specialized in spices, herbs, and their "
+        "health benefits. I can help you with:\n"
+        "- Spice and herb information\n"
+        "- Nutritional content\n"
+        "- Health benefits and traditional uses\n"
+        "- Finding substitutes\n"
+        "- Safety information\n\n"
+        "Please ask a question related to these topics."
+    )
+
+    def __init__(self, strict_mode: bool = False, enabled: bool = True):
+        """Initialize topic filter guardrail.
+
+        Args:
+            strict_mode: If True, block all off-topic queries. If False, just warn.
+            enabled: Whether the guardrail is active.
+        """
+        super().__init__(name="topic_filter", enabled=enabled)
+        self.strict_mode = strict_mode
+        self._topic_pattern = re.compile(
+            r'\b(' + '|'.join(self.ALLOWED_TOPICS) + r')\b',
+            re.IGNORECASE
+        )
+
+    def _is_on_topic(self, text: str) -> bool:
+        """Check if text is related to allowed topics."""
+        return bool(self._topic_pattern.search(text))
+
+    def check_input(self, user_input: str, context: Dict) -> GuardrailResponse:
+        """Check if input is on-topic."""
+        if not self.enabled:
+            return GuardrailResponse(result=GuardrailResult.PASS)
+
+        if self._is_on_topic(user_input):
+            return GuardrailResponse(
+                result=GuardrailResult.PASS,
+                metadata={"on_topic": True}
+            )
+
+        if self.strict_mode:
+            return GuardrailResponse(
+                result=GuardrailResult.BLOCK,
+                message=self.OFF_TOPIC_RESPONSE,
+                metadata={"on_topic": False}
+            )
+
+        return GuardrailResponse(
+            result=GuardrailResult.WARN,
+            message="This query may be off-topic. I specialize in spices and herbs.",
+            metadata={"on_topic": False}
+        )
+
+
+class TokenLimitGuardrail(Guardrail):
+    """Guardrail to limit token usage and control costs."""
+
+    def __init__(
+        self,
+        max_input_tokens: int = 500,
+        max_output_tokens: int = 1000,
+        daily_token_budget: int = 100000,
+        enabled: bool = True
+    ):
+        """Initialize token limit guardrail.
+
+        Args:
+            max_input_tokens: Max tokens allowed in input.
+            max_output_tokens: Max tokens allowed in output.
+            daily_token_budget: Total tokens allowed per day.
+            enabled: Whether the guardrail is active.
+        """
+        super().__init__(name="token_limit", enabled=enabled)
+        self.max_input_tokens = max_input_tokens
+        self.max_output_tokens = max_output_tokens
+        self.daily_token_budget = daily_token_budget
+        self._daily_usage: Dict[str, int] = {}
+        self._last_reset: Optional[str] = None
+
+    def _estimate_tokens(self, text: str) -> int:
+        """Estimate token count (rough approximation: ~4 chars per token)."""
+        return len(text) // 4
+
+    def _get_today(self) -> str:
+        """Get today's date string."""
+        return datetime.now().strftime("%Y-%m-%d")
+
+    def _reset_daily_if_needed(self) -> None:
+        """Reset daily usage if it's a new day."""
+        today = self._get_today()
+        if self._last_reset != today:
+            self._daily_usage.clear()
+            self._last_reset = today
+
+    def check_input(self, user_input: str, context: Dict) -> GuardrailResponse:
+        """Check if input is within token limits."""
+        if not self.enabled:
+            return GuardrailResponse(result=GuardrailResult.PASS)
+
+        self._reset_daily_if_needed()
+
+        estimated_tokens = self._estimate_tokens(user_input)
+        session_id = context.get("session_id", "default")
+        today = self._get_today()
+
+        if estimated_tokens > self.max_input_tokens:
+            return GuardrailResponse(
+                result=GuardrailResult.BLOCK,
+                message=f"Input too long. Please shorten your message.",
+                metadata={
+                    "estimated_tokens": estimated_tokens,
+                    "max_tokens": self.max_input_tokens
+                }
+            )
+
+        current_daily_usage = self._daily_usage.get(today, 0)
+        if current_daily_usage >= self.daily_token_budget:
+            return GuardrailResponse(
+                result=GuardrailResult.BLOCK,
+                message="Daily usage limit reached. Please try again tomorrow.",
+                metadata={
+                    "daily_usage": current_daily_usage,
+                    "daily_budget": self.daily_token_budget
+                }
+            )
+
+        return GuardrailResponse(
+            result=GuardrailResult.PASS,
+            metadata={
+                "estimated_input_tokens": estimated_tokens,
+                "daily_usage": current_daily_usage
+            }
+        )
+
+    def record_usage(self, input_tokens: int, output_tokens: int) -> None:
+        """Record token usage for tracking.
+
+        Args:
+            input_tokens: Tokens used in input.
+            output_tokens: Tokens used in output.
+        """
+        self._reset_daily_if_needed()
+        today = self._get_today()
+        total_tokens = input_tokens + output_tokens
+        self._daily_usage[today] = self._daily_usage.get(today, 0) + total_tokens
+
+    def get_max_output_tokens(self) -> int:
+        """Get the configured max output tokens."""
+        return self.max_output_tokens
+
+
+class UsageTrackingGuardrail(Guardrail):
+    """Guardrail to track API usage and costs."""
+
+    COST_PER_1K_INPUT_TOKENS = {
+        "claude-sonnet-4-20250514": 0.003,
+        "claude-3-5-haiku-20241022": 0.001,
+        "gpt-4": 0.03,
+        "gpt-3.5-turbo": 0.0015,
+        "default": 0.002
+    }
+
+    COST_PER_1K_OUTPUT_TOKENS = {
+        "claude-sonnet-4-20250514": 0.015,
+        "claude-3-5-haiku-20241022": 0.005,
+        "gpt-4": 0.06,
+        "gpt-3.5-turbo": 0.002,
+        "default": 0.01
+    }
+
+    def __init__(
+        self,
+        model_name: str = "default",
+        daily_cost_limit: float = 10.0,
+        enabled: bool = True
+    ):
+        """Initialize usage tracking guardrail.
+
+        Args:
+            model_name: Name of the model for cost calculation.
+            daily_cost_limit: Maximum daily spend in USD.
+            enabled: Whether the guardrail is active.
+        """
+        super().__init__(name="usage_tracking", enabled=enabled)
+        self.model_name = model_name
+        self.daily_cost_limit = daily_cost_limit
+        self._usage_log: List[Dict] = []
+        self._daily_cost: Dict[str, float] = {}
+
+    def _get_today(self) -> str:
+        """Get today's date string."""
+        return datetime.now().strftime("%Y-%m-%d")
+
+    def _calculate_cost(self, input_tokens: int, output_tokens: int) -> float:
+        """Calculate cost for token usage."""
+        input_rate = self.COST_PER_1K_INPUT_TOKENS.get(
+            self.model_name,
+            self.COST_PER_1K_INPUT_TOKENS["default"]
+        )
+        output_rate = self.COST_PER_1K_OUTPUT_TOKENS.get(
+            self.model_name,
+            self.COST_PER_1K_OUTPUT_TOKENS["default"]
+        )
+
+        input_cost = (input_tokens / 1000) * input_rate
+        output_cost = (output_tokens / 1000) * output_rate
+
+        return input_cost + output_cost
+
+    def check_input(self, user_input: str, context: Dict) -> GuardrailResponse:
+        """Check if daily cost limit is reached."""
+        if not self.enabled:
+            return GuardrailResponse(result=GuardrailResult.PASS)
+
+        today = self._get_today()
+        current_cost = self._daily_cost.get(today, 0.0)
+
+        if current_cost >= self.daily_cost_limit:
+            return GuardrailResponse(
+                result=GuardrailResult.BLOCK,
+                message="Daily cost limit reached. Please try again tomorrow.",
+                metadata={
+                    "daily_cost": current_cost,
+                    "daily_limit": self.daily_cost_limit
+                }
+            )
+
+        return GuardrailResponse(
+            result=GuardrailResult.PASS,
+            metadata={"daily_cost": current_cost}
+        )
+
+    def record_usage(
+        self,
+        input_tokens: int,
+        output_tokens: int,
+        session_id: str = "default"
+    ) -> Dict:
+        """Record API usage and calculate cost.
+
+        Args:
+            input_tokens: Number of input tokens.
+            output_tokens: Number of output tokens.
+            session_id: Session identifier.
+
+        Returns:
+            Dict with usage details.
+        """
+        today = self._get_today()
+        cost = self._calculate_cost(input_tokens, output_tokens)
+
+        usage_entry = {
+            "timestamp": datetime.now().isoformat(),
+            "session_id": session_id,
+            "model": self.model_name,
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "cost_usd": cost
+        }
+
+        self._usage_log.append(usage_entry)
+        self._daily_cost[today] = self._daily_cost.get(today, 0.0) + cost
+
+        return usage_entry
+
+    def get_daily_summary(self) -> Dict:
+        """Get usage summary for today."""
+        today = self._get_today()
+        today_entries = [
+            e for e in self._usage_log
+            if e["timestamp"].startswith(today)
+        ]
+
+        return {
+            "date": today,
+            "total_requests": len(today_entries),
+            "total_input_tokens": sum(e["input_tokens"] for e in today_entries),
+            "total_output_tokens": sum(e["output_tokens"] for e in today_entries),
+            "total_cost_usd": self._daily_cost.get(today, 0.0),
+            "daily_limit_usd": self.daily_cost_limit,
+            "remaining_budget_usd": max(0, self.daily_cost_limit - self._daily_cost.get(today, 0.0))
+        }
+
+
+class AuditLogGuardrail(Guardrail):
+    """Guardrail to log all queries for audit and review."""
+
+    def __init__(
+        self,
+        log_dir: str = "logs/audit",
+        log_to_file: bool = True,
+        log_to_console: bool = True,
+        enabled: bool = True
+    ):
+        """Initialize audit log guardrail.
+
+        Args:
+            log_dir: Directory to store log files.
+            log_to_file: Whether to write logs to file.
+            log_to_console: Whether to print logs to console.
+            enabled: Whether the guardrail is active.
+        """
+        super().__init__(name="audit_log", enabled=enabled)
+        self.log_dir = Path(log_dir)
+        self.log_to_file = log_to_file
+        self.log_to_console = log_to_console
+        self._session_logs: Dict[str, List[Dict]] = defaultdict(list)
+
+        if log_to_file:
+            self.log_dir.mkdir(parents=True, exist_ok=True)
+
+    def _get_log_filename(self) -> Path:
+        """Get today's log filename."""
+        today = datetime.now().strftime("%Y-%m-%d")
+        return self.log_dir / f"audit_{today}.jsonl"
+
+    def check_input(self, user_input: str, context: Dict) -> GuardrailResponse:
+        """Log incoming query."""
+        if not self.enabled:
+            return GuardrailResponse(result=GuardrailResult.PASS)
+
+        session_id = context.get("session_id", "default")
+
+        log_entry = {
+            "timestamp": datetime.now().isoformat(),
+            "type": "input",
+            "session_id": session_id,
+            "content": user_input,
+            "metadata": {k: v for k, v in context.items() if k != "session_id"}
+        }
+
+        self._write_log(log_entry)
+
+        return GuardrailResponse(
+            result=GuardrailResult.PASS,
+            metadata={"logged": True}
+        )
+
+    def check_output(self, output: str, context: Dict) -> GuardrailResponse:
+        """Log outgoing response."""
+        if not self.enabled:
+            return GuardrailResponse(result=GuardrailResult.PASS)
+
+        session_id = context.get("session_id", "default")
+
+        log_entry = {
+            "timestamp": datetime.now().isoformat(),
+            "type": "output",
+            "session_id": session_id,
+            "content": output[:500] + "..." if len(output) > 500 else output,
+            "content_length": len(output),
+            "metadata": {k: v for k, v in context.items() if k != "session_id"}
+        }
+
+        self._write_log(log_entry)
+
+        return GuardrailResponse(
+            result=GuardrailResult.PASS,
+            metadata={"logged": True}
+        )
+
+    def _write_log(self, entry: Dict) -> None:
+        """Write log entry to file and/or console."""
+        if self.log_to_console:
+            print(f"[AUDIT] {entry['type'].upper()}: {entry.get('content', '')[:100]}...")
+
+        if self.log_to_file:
+            try:
+                with open(self._get_log_filename(), "a", encoding="utf-8") as f:
+                    f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+            except Exception as e:
+                print(f"[AUDIT] Failed to write log: {e}")
+
+
+class GuardrailManager:
+    """Manager class to orchestrate multiple guardrails."""
+
+    def __init__(self):
+        """Initialize the guardrail manager."""
+        self.guardrails: List[Guardrail] = []
+        self._context: Dict = {}
+
+    def add_guardrail(self, guardrail: Guardrail) -> "GuardrailManager":
+        """Add a guardrail to the manager.
+
+        Args:
+            guardrail: The guardrail to add.
+
+        Returns:
+            Self for method chaining.
+        """
+        self.guardrails.append(guardrail)
+        return self
+
+    def check_input(
+        self,
+        user_input: str,
+        session_id: str = "default"
+    ) -> Tuple[bool, str, Dict]:
+        """Run all input guardrails.
+
+        Args:
+            user_input: The user's message.
+            session_id: Session identifier.
+
+        Returns:
+            Tuple of (should_proceed, message, context).
+        """
+        context = {"session_id": session_id}
+
+        for guardrail in self.guardrails:
+            if not guardrail.enabled:
+                continue
+
+            response = guardrail.check_input(user_input, context)
+
+            context.update(response.metadata)
+
+            if response.result == GuardrailResult.BLOCK:
+                print(f"[GUARDRAIL] {guardrail.name} BLOCKED: {response.message}")
+                return False, response.message, context
+
+            if response.result == GuardrailResult.WARN:
+                print(f"[GUARDRAIL] {guardrail.name} WARNING: {response.message}")
+
+        self._context = context
+        return True, "", context
+
+    def check_output(self, output: str) -> str:
+        """Run all output guardrails.
+
+        Args:
+            output: The agent's response.
+
+        Returns:
+            The (possibly modified) output.
+        """
+        modified_output = output
+
+        for guardrail in self.guardrails:
+            if not guardrail.enabled:
+                continue
+
+            response = guardrail.check_output(modified_output, self._context)
+
+            if response.result == GuardrailResult.MODIFY and response.modified_input:
+                modified_output = response.modified_input
+                print(f"[GUARDRAIL] {guardrail.name} modified output")
+
+        return modified_output
+
+    def get_guardrail(self, name: str) -> Optional[Guardrail]:
+        """Get a guardrail by name.
+
+        Args:
+            name: Name of the guardrail.
+
+        Returns:
+            The guardrail or None if not found.
+        """
+        for guardrail in self.guardrails:
+            if guardrail.name == name:
+                return guardrail
+        return None
+
+
+def create_default_guardrails(
+    model_name: str = "claude-sonnet-4-20250514",
+    strict_topic_filter: bool = False,
+    daily_cost_limit: float = 1.0
+) -> GuardrailManager:
+    """Create a GuardrailManager with default configuration.
+
+    Args:
+        model_name: Name of the LLM model for cost tracking.
+        strict_topic_filter: Whether to strictly block off-topic queries.
+        daily_cost_limit: Maximum daily spend in USD (default: $1/day).
+
+    Returns:
+        Configured GuardrailManager instance.
+    """
+    manager = GuardrailManager()
+
+    manager.add_guardrail(InputLengthGuardrail(max_length=2000, min_length=1))
+    manager.add_guardrail(RateLimitGuardrail(
+        max_requests_per_minute=10,
+        max_requests_per_hour=100
+    ))
+    manager.add_guardrail(TopicFilterGuardrail(strict_mode=strict_topic_filter))
+    manager.add_guardrail(TokenLimitGuardrail(
+        max_input_tokens=500,
+        max_output_tokens=1000,
+        daily_token_budget=100000
+    ))
+    manager.add_guardrail(UsageTrackingGuardrail(
+        model_name=model_name,
+        daily_cost_limit=daily_cost_limit
+    ))
+    manager.add_guardrail(MedicalDisclaimerGuardrail())
+    manager.add_guardrail(AuditLogGuardrail(log_to_file=True, log_to_console=True))
+
+    return manager

tools/image_utils.py

@@ -0,0 +1,160 @@
+"""Image utility functions for fetching spice images from Wikipedia.
+
+Images are fetched on-demand from Wikimedia Commons with proper User-Agent
+headers to comply with their API requirements. Downloaded images are cached
+in a temp directory.
+"""
+
+import json
+import hashlib
+import tempfile
+import requests
+from pathlib import Path
+from typing import Optional, Tuple
+
+DATA_DIR = Path(__file__).parent.parent / "data"
+MAPPINGS_FILE = DATA_DIR / "spice_images.json"
+CACHE_DIR = Path(tempfile.gettempdir()) / "spice_images_cache"
+
+HEADERS = {
+    "User-Agent": "MedicinalCuisineBot/1.0 (https://huggingface.co/spaces/MCP-1st-Birthday/Spice_Bae; educational project)"
+}
+
+_url_cache: dict = {}
+
+
+def _load_mappings() -> dict:
+    """Load image URL mappings from JSON file.
+
+    Returns:
+        Dict with spice image URLs and metadata.
+    """
+    global _url_cache
+
+    if _url_cache:
+        return _url_cache
+
+    if not MAPPINGS_FILE.exists():
+        return {}
+
+    with open(MAPPINGS_FILE, 'r', encoding='utf-8') as f:
+        _url_cache = json.load(f)
+
+    return _url_cache
+
+
+def _get_cache_path(url: str) -> Path:
+    """Generate a cache file path for a URL.
+
+    Args:
+        url: Image URL.
+
+    Returns:
+        Path to cached file.
+    """
+    url_hash = hashlib.md5(url.encode()).hexdigest()
+    ext = url.split('.')[-1].split('?')[0][:4]
+    if ext not in ['jpg', 'jpeg', 'png', 'gif', 'webp']:
+        ext = 'jpg'
+    return CACHE_DIR / f"{url_hash}.{ext}"
+
+
+def _download_image(url: str) -> Optional[str]:
+    """Download image from URL with proper headers.
+
+    Args:
+        url: Wikimedia image URL.
+
+    Returns:
+        Path to downloaded file, or None on failure.
+    """
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    cache_path = _get_cache_path(url)
+
+    if cache_path.exists():
+        return str(cache_path)
+
+    try:
+        response = requests.get(url, headers=HEADERS, timeout=10)
+        response.raise_for_status()
+
+        with open(cache_path, 'wb') as f:
+            f.write(response.content)
+
+        return str(cache_path)
+    except Exception:
+        return None
+
+
+def get_local_image_path(spice_name: str) -> Optional[str]:
+    """Get image path for a spice (downloads if needed).
+
+    Args:
+        spice_name: Name of the spice.
+
+    Returns:
+        Path to the image file, or None if not found.
+    """
+    mappings = _load_mappings()
+    spice_images = mappings.get("spice_images", {})
+
+    name_lower = spice_name.lower().strip()
+
+    if name_lower in spice_images:
+        url = spice_images[name_lower].get("url")
+        if url:
+            return _download_image(url)
+
+    for key, data in spice_images.items():
+        if key in name_lower or name_lower in key:
+            url = data.get("url")
+            if url:
+                return _download_image(url)
+
+    return None
+
+
+def get_image_source(spice_name: str) -> Optional[str]:
+    """Get Wikipedia source URL for a spice image.
+
+    Args:
+        spice_name: Name of the spice.
+
+    Returns:
+        Wikipedia source URL or None.
+    """
+    mappings = _load_mappings()
+    spice_images = mappings.get("spice_images", {})
+
+    name_lower = spice_name.lower().strip()
+
+    if name_lower in spice_images:
+        return spice_images[name_lower].get("source")
+
+    for key, data in spice_images.items():
+        if key in name_lower or name_lower in key:
+            return data.get("source")
+
+    return None
+
+
+def get_spice_image_and_info(
+    spice_name: str,
+    info_text: str
+) -> Tuple[Optional[str], str]:
+    """Get image path and info text with source attribution.
+
+    Args:
+        spice_name: Name of the spice.
+        info_text: Original information text.
+
+    Returns:
+        Tuple of (image_path, info_text_with_attribution).
+    """
+    image_path = get_local_image_path(spice_name)
+    source = get_image_source(spice_name)
+
+    if source:
+        info_text += f"\n\n---\nImage source: {source}"
+
+    return image_path, info_text

tools/llama_agent.py

@@ -0,0 +1,293 @@
+"""LlamaIndex Agent for Medicinal Cuisine conversational interface.
+
+This module wraps the existing spice database tools as LlamaIndex FunctionTools,
+enabling a conversational AI interface powered by Claude.
+
+Architecture:
+    User Question -> Guardrails -> LlamaIndex AgentWorkflow -> Tool Selection -> Neo4j Query -> Guardrails -> Response
+"""
+
+import asyncio
+import os
+from typing import Optional
+from llama_index.core.tools import FunctionTool
+from llama_index.core.agent.workflow import AgentWorkflow
+from llama_index.llms.anthropic import Anthropic
+
+from tools.neo4j_queries import SpiceDatabase
+from tools.guardrails import (
+    GuardrailManager,
+    create_default_guardrails,
+    UsageTrackingGuardrail,
+    TokenLimitGuardrail,
+)
+
+
+class SpiceAgent:
+    """Conversational agent for medicinal spice queries.
+
+    Wraps the SpiceDatabase functions as LlamaIndex tools and uses
+    Claude for natural language understanding. Includes comprehensive
+    guardrails for safety, cost control, and compliance.
+
+    Attributes:
+        db: SpiceDatabase instance for Neo4j queries
+        llm: Anthropic Claude LLM for processing queries
+        workflow: LlamaIndex AgentWorkflow for tool orchestration
+        guardrails: GuardrailManager for safety checks
+    """
+
+    DEFAULT_MODEL = "claude-sonnet-4-20250514"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        model: Optional[str] = None,
+        enable_guardrails: bool = True,
+        daily_cost_limit: float = 1.0,
+        strict_topic_filter: bool = False,
+    ):
+        """Initialize the spice agent.
+
+        Args:
+            api_key: Anthropic API key. If None, reads from ANTHROPIC_API_KEY env var.
+            model: Model name to use. Defaults to claude-sonnet-4-20250514.
+            enable_guardrails: Whether to enable safety guardrails.
+            daily_cost_limit: Maximum daily spend in USD (default: $1/day).
+            strict_topic_filter: Whether to strictly block off-topic queries.
+        """
+        self.db = SpiceDatabase()
+        self.api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
+        self.model = model or self.DEFAULT_MODEL
+        self.llm = None
+        self.workflow = None
+
+        if enable_guardrails:
+            self.guardrails = create_default_guardrails(
+                model_name=self.model,
+                strict_topic_filter=strict_topic_filter,
+                daily_cost_limit=daily_cost_limit,
+            )
+            print("[GUARDRAILS] Initialized with default configuration")
+        else:
+            self.guardrails = None
+            print("[GUARDRAILS] Disabled")
+
+        if self.api_key:
+            self._initialize_agent()
+
+    def _initialize_agent(self) -> None:
+        """Initialize LLM and agent workflow with tools."""
+        self.llm = Anthropic(
+            model=self.model,
+            api_key=self.api_key,
+        )
+
+        tools = self._create_tools()
+
+        self.workflow = AgentWorkflow.from_tools_or_functions(
+            tools_or_functions=tools,
+            llm=self.llm,
+            system_prompt="""You are a helpful medicinal cuisine advisor that helps users learn about spices, their nutritional content, and health benefits.
+
+You have access to a database of 88+ spices with:
+- Nutritional data from USDA FoodData Central
+- Health benefits from NCCIH (National Center for Complementary and Integrative Health)
+- Safety information including side effects and cautions
+
+IMPORTANT: Always remind users that this information is for educational purposes only and not medical advice.
+
+When answering questions:
+1. Use the appropriate tool to query the database
+2. Provide clear, helpful responses
+3. Include source attribution (USDA or NCCIH)
+4. Mention relevant safety information when discussing health benefits
+""",
+        )
+
+    def _create_tools(self) -> list:
+        """Create LlamaIndex FunctionTools from database methods.
+
+        Returns:
+            List of FunctionTool objects for the agent.
+        """
+        tools = [
+            FunctionTool.from_defaults(
+                fn=self._get_spice_info,
+                name="get_spice_information",
+                description="Get comprehensive information about a spice including nutritional data."
+            ),
+            FunctionTool.from_defaults(
+                fn=self._list_spices,
+                name="list_available_spices",
+                description="List all spices available in the database."
+            ),
+            FunctionTool.from_defaults(
+                fn=self._get_nutrient,
+                name="get_nutrient_content",
+                description="Get specific nutrient content for a spice."
+            ),
+            FunctionTool.from_defaults(
+                fn=self._find_substitutes,
+                name="find_spice_substitutes",
+                description="Find substitute spices based on nutritional similarity."
+            ),
+            FunctionTool.from_defaults(
+                fn=self._get_health_benefits,
+                name="get_health_benefits",
+                description="Get health benefits and medicinal properties of a spice."
+            ),
+            FunctionTool.from_defaults(
+                fn=self._find_by_benefit,
+                name="find_spices_for_benefit",
+                description="Find spices that help with a specific health condition."
+            ),
+            FunctionTool.from_defaults(
+                fn=self._get_safety_info,
+                name="get_safety_information",
+                description="Get safety information including side effects and cautions."
+            ),
+            FunctionTool.from_defaults(
+                fn=self._find_medicinal_substitutes,
+                name="find_medicinal_substitutes",
+                description="Find substitute spices based on shared health benefits."
+            ),
+        ]
+        return tools
+
+    def _get_spice_info(self, spice_name: str) -> str:
+        """Get comprehensive spice information."""
+        print(f"[TOOL] get_spice_information called with: {spice_name}")
+        return self.db.get_spice_info(spice_name)
+
+    def _list_spices(self) -> str:
+        """List all available spices."""
+        print("[TOOL] list_available_spices called")
+        return self.db.list_all_spices()
+
+    def _get_nutrient(self, spice_name: str, nutrient_name: str) -> str:
+        """Get specific nutrient content."""
+        print(f"[TOOL] get_nutrient_content called with: {spice_name}, {nutrient_name}")
+        return self.db.get_nutrient_content(spice_name, nutrient_name)
+
+    def _find_substitutes(self, spice_name: str, limit: int = 5) -> str:
+        """Find nutritional substitutes."""
+        print(f"[TOOL] find_spice_substitutes called with: {spice_name}, limit={limit}")
+        return self.db.find_substitutes(spice_name, limit=limit)
+
+    def _get_health_benefits(self, spice_name: str) -> str:
+        """Get health benefits information."""
+        print(f"[TOOL] get_health_benefits called with: {spice_name}")
+        return self.db.get_health_benefits(spice_name)
+
+    def _find_by_benefit(self, benefit_keyword: str, limit: int = 10) -> str:
+        """Find spices by health benefit."""
+        print(f"[TOOL] find_spices_for_benefit called with: {benefit_keyword}, limit={limit}")
+        return self.db.find_spices_by_benefit(benefit_keyword, limit=limit)
+
+    def _get_safety_info(self, spice_name: str) -> str:
+        """Get safety information."""
+        print(f"[TOOL] get_safety_information called with: {spice_name}")
+        return self.db.get_safety_info(spice_name)
+
+    def _find_medicinal_substitutes(self, spice_name: str, limit: int = 5) -> str:
+        """Find medicinal substitutes."""
+        print(f"[TOOL] find_medicinal_substitutes called with: {spice_name}, limit={limit}")
+        return self.db.find_substitutes_by_benefits(spice_name, limit=limit)
+
+    def chat(self, message: str, session_id: str = "default") -> str:
+        """Process a chat message and return response.
+
+        Args:
+            message: User's question or message.
+            session_id: Session identifier for rate limiting and tracking.
+
+        Returns:
+            Agent's response string.
+        """
+        if not self.workflow:
+            return "Error: Agent not initialized. Please ensure ANTHROPIC_API_KEY is set."
+
+        if self.guardrails:
+            should_proceed, block_message, context = self.guardrails.check_input(
+                message, session_id
+            )
+            if not should_proceed:
+                return block_message
+
+        try:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            try:
+                result = loop.run_until_complete(self._async_chat(message))
+
+                if self.guardrails:
+                    result = self.guardrails.check_output(result)
+
+                    usage_tracker = self.guardrails.get_guardrail("usage_tracking")
+                    if usage_tracker and isinstance(usage_tracker, UsageTrackingGuardrail):
+                        input_tokens = len(message) // 4
+                        output_tokens = len(result) // 4
+                        usage_tracker.record_usage(input_tokens, output_tokens, session_id)
+
+                return result
+            finally:
+                loop.close()
+        except Exception as e:
+            return f"Error processing request: {str(e)}"
+
+    async def _async_chat(self, message: str) -> str:
+        """Async chat handler for the workflow.
+
+        Args:
+            message: User's question or message.
+
+        Returns:
+            Agent's response string.
+        """
+        print(f"[AGENT] Processing message: {message}")
+        try:
+            response = await self.workflow.run(user_msg=message)
+            print(f"[AGENT] Raw response type: {type(response)}")
+            if response is None:
+                return "No response generated. Please try rephrasing your question."
+            return str(response)
+        except Exception as e:
+            print(f"[AGENT] Error in workflow: {type(e).__name__}: {e}")
+            import traceback
+            traceback.print_exc()
+            raise
+
+    def get_usage_summary(self) -> dict:
+        """Get usage summary for today.
+
+        Returns:
+            Dict with usage statistics or empty dict if guardrails disabled.
+        """
+        if not self.guardrails:
+            return {}
+
+        usage_tracker = self.guardrails.get_guardrail("usage_tracking")
+        if usage_tracker and isinstance(usage_tracker, UsageTrackingGuardrail):
+            return usage_tracker.get_daily_summary()
+        return {}
+
+    def is_ready(self) -> bool:
+        """Check if agent is ready to process queries.
+
+        Returns:
+            True if workflow is initialized, False otherwise.
+        """
+        return self.workflow is not None
+
+
+def create_agent(api_key: Optional[str] = None) -> SpiceAgent:
+    """Factory function to create a SpiceAgent.
+
+    Args:
+        api_key: Optional Anthropic API key.
+
+    Returns:
+        Configured SpiceAgent instance.
+    """
+    return SpiceAgent(api_key=api_key)

tools/mcp_tools.py

@@ -7,13 +7,54 @@ Spice-Bae Neo4j database.
 All data is sourced from USDA FoodData Central with full attribution.
 """
 
+from typing import Optional, Tuple
 import gradio as gr
 from tools.neo4j_queries import SpiceDatabase
+from tools.image_utils import get_spice_image_and_info, get_local_image_path
 
 # Initialize database connection
 db = SpiceDatabase()
 
 
+def get_spice_info_with_image(spice_name: str) -> Tuple[Optional[str], str]:
+    """Get spice information along with local image path.
+
+    Args:
+        spice_name: Name of the spice to look up.
+
+    Returns:
+        Tuple of (local_image_path, info_text with attribution).
+    """
+    info_text = db.get_spice_info(spice_name)
+    return get_spice_image_and_info(spice_name, info_text)
+
+
+def get_health_benefits_with_image(spice_name: str) -> Tuple[Optional[str], str]:
+    """Get health benefits information along with local image path.
+
+    Args:
+        spice_name: Name of the spice to look up.
+
+    Returns:
+        Tuple of (local_image_path, health_info_text with attribution).
+    """
+    health_text = db.get_health_benefits(spice_name)
+    return get_spice_image_and_info(spice_name, health_text)
+
+
+def get_safety_info_with_image(spice_name: str) -> Tuple[Optional[str], str]:
+    """Get safety information along with local image path.
+
+    Args:
+        spice_name: Name of the spice to look up.
+
+    Returns:
+        Tuple of (local_image_path, safety_info_text with attribution).
+    """
+    safety_text = db.get_safety_info(spice_name)
+    return get_spice_image_and_info(spice_name, safety_text)
+
+
 @gr.mcp.tool()
 def get_spice_information(spice_name: str) -> str:
     """Get comprehensive information about a spice including nutrients and sourcing.

tools/neo4j_queries.py

@@ -85,14 +85,16 @@ class SpiceDatabase:
             return f"Spice '{spice_name}' not found in database."
 
         data = result["data"]["values"][0]
-        # Extract properties from Neo4j node object
         spice_node = data[0] if data else {}
         spice = spice_node.get('properties', {}) if isinstance(spice_node, dict) else {}
         nutrients = data[1] if len(data) > 1 else []
 
-        # Format output
         output = []
         output.append(f"=== {spice.get('name', 'Unknown').upper()} ===\n")
+
+        if spice.get('image_url'):
+            output.append(f"Image: {spice['image_url']}")
+
         output.append(f"Description: {spice.get('description', 'N/A')}")
 
         if spice.get('scientific_name'):
@@ -101,7 +103,6 @@ class SpiceDatabase:
         output.append(f"Category: {spice.get('food_category', 'N/A')}")
         output.append(f"\nKey Nutrients (top 10):")
 
-        # Show top 10 nutrients by value
         nutrient_list = [n for n in nutrients if n.get('value') is not None]
         nutrient_list.sort(key=lambda x: float(x.get('value', 0) or 0), reverse=True)
 
@@ -113,6 +114,40 @@ class SpiceDatabase:
 
         return "\n".join(output)
 
+    def get_spice_with_image(self, spice_name: str) -> Optional[Dict]:
+        """Get spice information including image URL as a dictionary.
+
+        Args:
+            spice_name: Name of the spice to look up
+
+        Returns:
+            Dict with spice data including image_url and source, or None if not found
+        """
+        query = """
+        MATCH (s:Spice)
+        WHERE toLower(s.name) = toLower($spice_name)
+        RETURN s.name as name,
+               s.description as description,
+               s.image_url as image_url,
+               s.image_source as image_source,
+               s.food_category as category
+        LIMIT 1
+        """
+
+        result = self.run_query(query, {"spice_name": spice_name})
+
+        if not result or not result.get("data", {}).get("values"):
+            return None
+
+        data = result["data"]["values"][0]
+        return {
+            "name": data[0],
+            "description": data[1],
+            "image_url": data[2],
+            "image_source": data[3],
+            "category": data[4]
+        }
+
     def list_all_spices(self) -> str:
         """List all available spices in the database.