Initial commit to hf space for hackathon

.env.example

@@ -0,0 +1,74 @@
+
+
+
+# Environment
+ENVIRONMENT=production
+
+# ------------------------------------------------
+
+# Deprecated - use provider-specific models below
+#LLM_MODEL=gpt-4o-mini  
+#####
+
+# ------------------------------------------------
+# LLM Configuration
+
+
+# Provider-Specific Models (recommended)
+DEFAULT_OPENAI_MODEL=gpt-4o-mini
+DEFAULT_HF_MODEL=Qwen/Qwen3-VL-30B-A3B-Instruct
+DEFAULT_ANTHROPIC_MODEL=claude-sonnet-4-5-20250929
+
+# Provider-Specific Temperature Settings
+OPENAI_TEMPERATURE=0.0
+HF_TEMPERATURE=0.1
+ANTHROPIC_TEMPERATURE=0.0
+
+# ------------------------------------------------
+
+################################################
+
+# ------------------------------------------------
+
+################################################
+# MODAL Bird Classifier MCP Server
+################################################
+# # Client side API key for Modal bird-classifier-api-key (set in modal as API_KEY)
+# use random string e.g., ssl rand -base64 32
+BIRD_CLASSIFIER_API_KEY=<secure-key-for-modal-bird-classifier>
+
+# https://.../mcp
+MODAL_MCP_URL=<secure-key-for-modal-mcp>
+
+# ------------------------------------------------
+
+##############################################
+# eBird MCP Server - LEGACY
+##############################################
+# Use true for HF Space (subprocess mode)
+#EBIRD_USE_STDIO=true
+
+# Cornell eBird API
+#EBIRD_API_KEY=
+# REQUIRED for eBird API calls
+#EBIRD_BASE_URL=https://api.ebird.org/v2 
+#EBIRD_MCP_AUTH_KEY=<secure_key_for_ebird_auth> # Only needed for HTTP
+#EBIRD_MCP_URL=http://localhost:8000/mcp  # Update if eBird server deployed separately
+
+# ------------------------------------------------
+
+##############################################
+# eBird MCP Server 
+##############################################
+###### NUTHATCH HAIL MARY ######
+NUTHATCH_USE_STDIO=true 
+
+NUTHATCH_API_KEY=<secure-key-for-nuthatch-api>
+#NUTHATCH_BASE_URL=https://nuthatch.lastelm.software/v2 # Optional, has default
+
+# use random string e.g., ssl rand -base64 32
+NUTHATCH_MCP_AUTH_KEY=<secure-key-for-nuthatch-mcp-auth>
+NUTHATCH_MCP_URL=http://localhost:8000/mcp # Only for HTTP mode
+DEFAULT_TIMEOUT=15
+RATE_LIMIT_DELAY=1.0
+

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+examples/another_bird.jpg filter=lfs diff=lfs merge=lfs -text
+examples/bird_example_1.jpg filter=lfs diff=lfs merge=lfs -text
+examples/bird_example_2.jpg filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,144 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Project-specific directories
+#app_drafts/
+#docs/
+#tests/
+tests_archive/
+#examples/
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.backup
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# LangGraph checkpoints and cache
+.langgraph_api/
+
+# Modal (if using local development)
+.modal/
+
+# IDE files
+.vscode/
+.idea/
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.swp
+*~
+*.bak
+
+# Logs
+*.log
+logs/

README.md

@@ -1,14 +1,86 @@
 ---
-title: BirdScopeAI
-emoji: 🏃
-colorFrom: purple
-colorTo: indigo
+title: BirdScope AI - MCP Agent
+emoji: 🦅
+colorFrom: green
+colorTo: blue
 sdk: gradio
-sdk_version: 6.0.1
+python_version: 3.11
 app_file: app.py
 pinned: false
-license: mit
-short_description: 'hackathon submission: A bird loving AI Agent with MCP tools '
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🦅 BirdScope AI - Streaming MCP Agent
+
+**Real-time bird identification powered by MCP tools!**
+
+Built for the [MCP 1st Birthday Hackathon](https://huggingface.co/MCP-First-Birthday)
+
+## Features
+
+- 🔍 **Image Classification**: Upload bird photos for instant AI identification
+- 🗺️ **Location Discovery**: Find birding hotspots near any location
+- 📊 **Sighting Data**: Get recent observations from eBird API
+- 🤖 **Multi-Provider**: Support for HuggingFace (free credits) & OpenAI
+
+## How to Use
+
+### Option 1: HuggingFace (Recommended for Hackathon)
+1. Get your HuggingFace API key from [Settings → Access Tokens](https://huggingface.co/settings/tokens)
+2. Select "HuggingFace" as your provider in the sidebar
+3. Enter your HF API key in the sidebar
+4. Start chatting! (Uses your $25 hackathon credits)
+
+### Option 2: OpenAI
+1. Select "OpenAI" as your provider in the sidebar
+2. Enter your OpenAI API key in the sidebar
+3. Start chatting!
+
+## Architecture
+
+This Space uses **MCP (Model Context Protocol)** to connect AI agents with:
+
+### Modal MCP Server
+- GPU-powered bird classification
+- ResNet50 model trained on 555 bird species
+- Real-time image processing
+
+### eBird MCP Server
+- 7 tools for bird data discovery
+- Recent sightings, hotspot locations
+- Notable/rare bird alerts
+- Powered by Cornell Lab of Ornithology
+
+## Technology Stack
+
+- **Frontend**: Gradio 6.0 with custom Blocks UI
+- **Agent Framework**: LangGraph with streaming support
+- **MCP Clients**: FastMCP for tool integration
+- **LLM Providers**:
+  - HuggingFace Inference API (Qwen/Qwen3-Coder)
+  - OpenAI (gpt-4o-mini)
+
+## Development
+
+Local testing:
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Set up environment variables
+cp .env.example .env
+# Edit .env with your API keys
+
+# Run eBird MCP server (in separate terminal)
+python ebird_tools.py --http --port 8000
+
+# Run the app
+python app.py
+```
+
+**Note**: Both HuggingFace and OpenAI providers work locally and on HF Spaces. Just provide your API key in the sidebar.
+
+## Credits
+
+- **Bird Data**: [eBird](https://ebird.org) by Cornell Lab of Ornithology
+- **MCP Protocol**: [Anthropic Model Context Protocol](https://github.com/anthropics/mcp)
+- **Bird Classifier**: Custom ResNet50 model

agent_cache.py

@@ -0,0 +1,110 @@
+"""
+Agent cache management for per-session agents.
+
+This module handles storing and retrieving agents for differnet users/sessions.
+Each agent is cached by (session_id, provider, model, api_key_hash) to avoid recreating them.
+"""
+
+from datetime import datetime, timedelta
+from typing import Dict, Tuple, Any
+import hashlib
+
+# Global cache: maps (session_id, provider, model, api_key_hash, mode) -> agent
+agent_cache: Dict[Tuple[str, str, str, str, str], Any] = {}
+
+# Track when each agent was last used
+agent_last_used: Dict[Tuple[str, str, str, str, str], datetime] = {}
+
+async def get_or_create_agent(
+    session_id: str,
+    provider: str,
+    api_key: str,
+    model: str,
+    mode: str,
+    agent_factory_method
+):
+    """
+    Get existing agent from cache or create new one.
+
+    Args:
+        session_id: Unique identifier for user session (from gr.Request)
+        provider: "huggingface" or "openai"
+        api_key: User's API key or OAuth token
+        model: Model name/repo ID
+        mode: Agent mode (e.g., "Single Agent (All Tools)", "Specialized Subagents (3 Specialists)")
+        agent_factory_method: Async function to create agent if not cached
+
+    Returns:
+        Cached or newly created agent
+
+    Example:
+        agent = await get_or_create_agent(
+            session_id="abc123",
+            provider="openai",
+            api_key="sk-...",
+            model="gpt-4o-mini",
+            mode="Single Agent (All Tools)",
+            agent_factory_method=lambda: AgentFactory.create_streaming_agent_with_openai(...)
+        )
+    """
+    # Create hash of API key to include in cache key
+    # This ensures different API keys create separate cached agents
+    api_key_hash = hashlib.sha256(api_key.encode()).hexdigest()[:16]
+
+    # Create cache key (now includes API key hash AND mode)
+    cache_key = (session_id, provider, model, api_key_hash, mode)
+
+    # Check if agent exists in cache
+    if cache_key in agent_cache:
+        print(f"[CACHE HIT] Reusing agent for session {session_id[:8]}...")
+        agent_last_used[cache_key] = datetime.now()
+        return agent_cache[cache_key]
+
+    # Cache miss - create new agent
+    print(f"[CACHE MISS] Creating new {provider} agent for session {session_id[:8]}...")
+
+    # Call the facotry method to create agent
+    agent = await agent_factory_method()
+
+    # Store in cache
+    agent_cache[cache_key] = agent
+    agent_last_used[cache_key] = datetime.now()
+
+    print(f"[CACHE] Stored agent. Total agents in cache: {len(agent_cache)}")
+
+    return agent
+
+def cleanup_old_agents(max_age_hours: int = 1):
+    """
+    Remove agents that haven't been used in max_age_hours.
+
+    Call this periodically to prevent memory leaks.
+
+    Args:
+        max_age_hours: Remove agents older than this many hours
+
+    Returns:
+        Number of agents removed
+    """
+    now = datetime.now()
+    to_remove = []
+
+    for cache_key, last_used in agent_last_used.items():
+        age = now - last_used
+        if age > timedelta(hours=max_age_hours):
+            to_remove.append(cache_key)
+
+    # Remove old agents
+    for cache_key in to_remove:
+        print(f"[CLEANUP] Removing stale agent: {cache_key}")
+        del agent_cache[cache_key]
+        del agent_last_used[cache_key]
+
+    return len(to_remove)
+
+def get_cache_stats():
+    """Get statistics about the agent cache."""
+    return {
+        "total_agents": len(agent_cache),
+        "cache_keys": list(agent_cache.keys())
+    }

app.py

@@ -0,0 +1,1780 @@
+import gradio as gr
+import base64
+import json
+import os
+from pathlib import Path
+from langgraph_agent import AgentFactory
+from langgraph_agent.config import AgentConfig
+from langgraph_agent.subagent_config import SubAgentConfig
+from langgraph_agent.prompts import BIRDSCOPE_AI_PROMPT, NUTHATCH_BIRDSCOPE_PROMPT
+from fastmcp.client import Client
+from fastmcp.client.transports import StreamableHttpTransport
+from agent_cache import get_or_create_agent
+from langgraph_agent.structured_output import parse_agent_response
+
+# Load environment variables from .env file
+from dotenv import load_dotenv
+load_dotenv()
+
+# ============================================================================
+# EXAMPLE SETS FOR DIFFERENT AGENT MODES
+# ============================================================================
+
+# Shared photo examples - always shown for both modes
+PHOTO_EXAMPLES = [
+    {"text": "What bird is this?", "files": ["examples/bird_example_1.jpg"]},
+    {"text": "Can you identify this bird?", "files": ["examples/bird_example_2.jpg"]},
+    {"text": "Identify this bird and show me similar species", "files": ["examples/bird_example_3.jpg"]}
+]
+
+# Text-only examples for Specialized Subagents mode
+MULTI_AGENT_TEXT_EXAMPLES = [
+    "Tell me about Northern Cardinals - show me images and audio",
+    "What birds are in the Cardinalidae family?",
+    "Show me species with endangered status"
+]
+
+# Text-only examples for Audio Finder Agent mode
+AUDIO_FINDER_TEXT_EXAMPLES = [
+    "Find me audio for any bird",
+    "Get audio recordings for Snow Goose",
+    "Find bird calls from North America",
+    "Show me audio recordings of Common Goldeneye"
+]
+
+# ============================================================================
+# CUSTOM CSS WITH CLOUD/SKY AESTHETIC
+# ============================================================================
+
+custom_css = """
+/* ========================================================================
+   GLOBAL STYLES - SKY/CLOUD AESTHETIC
+   ======================================================================== */
+
+/* Unified cloud/sky background across entire page */
+body, html {
+    background: linear-gradient(180deg, #E0F4FF 0%, #B0E2FF 40%, #87CEEB 100%) !important;
+    min-height: 100vh !important;
+}
+
+.gradio-container {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif !important;
+    background:
+        /* Cloud formations - concentrated at TOP, fading down */
+        radial-gradient(ellipse 1200px 400px at 20% 0%, rgba(255, 255, 255, 0.6), transparent 70%),
+        radial-gradient(ellipse 1000px 350px at 80% 3%, rgba(255, 255, 255, 0.5), transparent 70%),
+        radial-gradient(ellipse 900px 300px at 50% 5%, rgba(255, 255, 255, 0.55), transparent 70%),
+        radial-gradient(ellipse 800px 250px at 10% 8%, rgba(255, 255, 255, 0.45), transparent 70%),
+        radial-gradient(ellipse 700px 200px at 90% 10%, rgba(255, 255, 255, 0.4), transparent 70%),
+        radial-gradient(ellipse 600px 180px at 40% 12%, rgba(255, 255, 255, 0.35), transparent 70%),
+        radial-gradient(ellipse 500px 150px at 60% 15%, rgba(255, 255, 255, 0.3), transparent 70%),
+        /* Base sky gradient - REVERSED: lighter at top, deeper blue at bottom */
+        linear-gradient(180deg, #E0F4FF 0%, #B0E2FF 40%, #87CEEB 100%) !important;
+}
+
+
+/* ========================================================================
+   SIDEBAR STYLING - DARK THEME
+   ======================================================================== */
+
+.sidebar {
+    background: #1f2937 !important;
+    padding: 24px 20px !important;
+    border-radius: 12px !important;
+    border: 1px solid #374151 !important;
+}
+
+/* Hide Gradio's default loading indicator in sidebar (we use badge for loading state) */
+.sidebar .loading,
+.sidebar .wrap.pending,
+.sidebar .progress-bar,
+.sidebar [class*="loading"],
+.sidebar [class*="progress"] {
+    display: none !important;
+}
+
+/* Also hide the loading indicator that appears as a child of the sidebar */
+.gradio-container .sidebar ~ * .loading,
+.gradio-container .sidebar ~ * .progress-bar {
+    display: none !important;
+}
+
+/* Hide Gradio's global top progress bar (the blue horizontal line) */
+.app > div > div > .progress-level-inner,
+body > gradio-app > div > div > div.progress-level-inner,
+[class*="progress-level"],
+.progress-level-inner {
+    display: none !important;
+    visibility: hidden !important;
+}
+
+/* Make all sidebar text light for dark background */
+.sidebar h1,
+.sidebar h2,
+.sidebar h3,
+.sidebar h4,
+.sidebar h5,
+.sidebar h6 {
+    color: #f9fafb !important;
+}
+
+.sidebar p,
+.sidebar span,
+.sidebar label {
+    color: #d1d5db !important;
+}
+
+/* Keep links distinguishable */
+.sidebar a {
+    color: #818cf8 !important;
+    text-decoration: underline !important;
+}
+
+.sidebar a:hover {
+    color: #a5b4fc !important;
+}
+
+/* API Key sections */
+.hf-section, .openai-section, .anthropic-section {
+    margin-top: 12px !important;
+}
+
+/* Dark theme input styling */
+.sidebar input[type="password"],
+.sidebar input[type="text"],
+.sidebar textarea {
+    border: 1px solid #374151 !important;
+    border-radius: 8px !important;
+    padding: 10px 14px !important;
+    font-size: 14px !important;
+    font-family: 'SF Mono', 'Monaco', 'Inconsolata', monospace !important;
+    background: #111827 !important;
+    color: #f9fafb !important;
+    transition: all 0.2s ease !important;
+}
+
+.sidebar input[type="password"]::placeholder,
+.sidebar input[type="text"]::placeholder,
+.sidebar textarea::placeholder {
+    color: #6b7280 !important;
+}
+
+.sidebar input[type="password"]:focus,
+.sidebar input[type="text"]:focus,
+.sidebar textarea:focus {
+    border-color: #818cf8 !important;
+    box-shadow: 0 0 0 2px rgba(129, 140, 248, 0.2) !important;
+    outline: none !important;
+    background: #1f2937 !important;
+}
+
+/* ========================================================================
+   CHATBOT & TOOL LOG PANELS
+   ======================================================================== */
+
+.chatbot-container {
+    border-radius: 12px !important;
+    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.08) !important;
+    border: 1px solid #e5e7eb !important;
+}
+
+/* Force icon SVG elements to use light colors for visibility on dark background */
+.chatbot-container svg,
+.chatbot-container svg path,
+.chatbot-container svg circle,
+.chatbot-container svg rect {
+    fill: #d1d5db !important;
+    stroke: #d1d5db !important;
+}
+
+.tool-log-panel textarea {
+    background: #1f2937 !important;
+    border-radius: 12px !important;
+    padding: 20px !important;
+    border: 1px solid #374151 !important;
+    box-shadow: 0 4px 20px rgba(0, 0, 0, 0.08) !important;
+    font-family: 'SF Mono', 'Monaco', 'Inconsolata', 'Consolas', monospace !important;
+    font-size: 13px !important;
+    line-height: 1.6 !important;
+    color: #d1d5db !important;
+    resize: none !important;
+    height: 500px !important;
+    min-height: 500px !important;
+    max-height: 500px !important;
+    overflow-y: auto !important;
+}
+
+/* Ensure tool log panel container aligns perfectly */
+.tool-log-panel {
+    margin: 0 !important;
+    padding: 0 !important;
+}
+
+.tool-log-panel textarea::-webkit-scrollbar {
+    width: 8px !important;
+}
+
+.tool-log-panel textarea::-webkit-scrollbar-track {
+    background: #111827 !important;
+    border-radius: 4px !important;
+}
+
+.tool-log-panel textarea::-webkit-scrollbar-thumb {
+    background: #4b5563 !important;
+    border-radius: 4px !important;
+}
+
+.tool-log-panel textarea::-webkit-scrollbar-thumb:hover {
+    background: #6b7280 !important;
+}
+
+hr {
+    border: none !important;
+    border-top: 1px solid #374151 !important;
+    margin: 20px 0 !important;
+}
+
+.sidebar hr {
+    border-top-color: #374151 !important;
+}
+
+/* ========================================================================
+   TEXT ON LIGHT BACKGROUND - MAKE DARK FOR READABILITY
+   ======================================================================== */
+
+/* All text elements outside dark panels should be dark for readability */
+.gradio-container label:not(.sidebar label):not(.tool-log-panel label):not(.chatbot-container label),
+.gradio-container span:not(.sidebar span):not(.tool-log-panel span):not(.chatbot-container span):not(.birdscope-header span),
+.gradio-container p:not(.sidebar p):not(.tool-log-panel p):not(.chatbot-container p):not(.birdscope-header p),
+.gradio-container div:not(.sidebar div):not(.tool-log-panel div):not(.chatbot-container div):not(.birdscope-header div) {
+    color: #1a1a1a !important;
+}
+
+/* Markdown text outside dark panels */
+.gradio-container .markdown:not(.sidebar .markdown):not(.tool-log-panel .markdown) {
+    color: #1a1a1a !important;
+}
+
+/* Markdown headings - ensure all are black on light background (except sidebar) */
+.gradio-container .markdown:not(.sidebar .markdown) h1,
+.gradio-container .markdown:not(.sidebar .markdown) h2,
+.gradio-container .markdown:not(.sidebar .markdown) h3,
+.gradio-container .markdown:not(.sidebar .markdown) h4,
+.gradio-container .markdown:not(.sidebar .markdown) h5,
+.gradio-container .markdown:not(.sidebar .markdown) h6 {
+    color: #1a1a1a !important;
+}
+
+/* Regular buttons (not primary) should have dark text */
+button:not([variant="primary"]) {
+    color: #1a1a1a !important;
+}
+
+/* BUT sidebar buttons should have light text (override above) */
+.sidebar button:not([variant="primary"]),
+.sidebar button:not([variant="primary"]) span,
+.sidebar button:not([variant="primary"]) * {
+    color: #f9fafb !important;
+}
+
+/* Modal check button with logo */
+.modal-check-btn {
+    background: rgba(59, 130, 246, 0.1) !important;
+    border: 1px solid rgba(59, 130, 246, 0.3) !important;
+    border-radius: 9999px !important;
+    transition: all 0.2s ease !important;
+    cursor: pointer !important;
+}
+
+.modal-check-btn:hover {
+    background: rgba(59, 130, 246, 0.2) !important;
+    border-color: rgba(59, 130, 246, 0.5) !important;
+    transform: translateY(-1px);
+    box-shadow: 0 2px 8px rgba(59, 130, 246, 0.3) !important;
+}
+
+.modal-check-btn:active {
+    transform: translateY(0);
+}
+
+.modal-check-btn::before {
+    content: "";
+    display: inline-block;
+    width: 18px;
+    height: 18px;
+    margin-right: 8px;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100' fill='none'%3E%3C!-- Left ribbon --%3E%3Cpath d='M0 30 L25 15 L50 30 L50 70 L25 85 L0 70 Z' fill='%2335D07F'/%3E%3Cpath d='M25 15 L50 30 L25 45 L0 30 Z' fill='%2388E5A8'/%3E%3Cpath d='M25 45 L50 30 L50 70 L25 85 Z' fill='%2315B866'/%3E%3C!-- Right ribbon --%3E%3Cpath d='M50 30 L75 15 L100 30 L100 70 L75 85 L50 70 Z' fill='%2335D07F'/%3E%3Cpath d='M75 15 L100 30 L75 45 L50 30 Z' fill='%2388E5A8'/%3E%3Cpath d='M75 45 L100 30 L100 70 L75 85 Z' fill='%2315B866'/%3E%3C/svg%3E");
+    background-size: contain;
+    background-repeat: no-repeat;
+    background-position: center;
+    vertical-align: middle;
+}
+
+/* ========================================================================
+   EXAMPLES - BLACK TEXT FOR READABILITY
+   ======================================================================== */
+
+/* Examples label - force black text with very high specificity */
+label.svelte-1gfkn6j,
+.label,
+span.svelte-1gfkn6j {
+    color: #1a1a1a !important;
+}
+
+/* Target example buttons specifically, excluding footer */
+.gradio-container button:not([variant="primary"]):not(.sidebar button):not(footer button):not([class*="footer"] button) {
+    color: #1a1a1a !important;
+}
+
+/* Footer text should be black on light background */
+footer,
+footer *,
+footer a,
+[class*="footer"],
+[class*="footer"] *,
+[class*="footer"] a {
+    color: #1a1a1a !important;
+}
+
+/* ========================================================================
+   ENHANCED HEADER - BIRDSCOPE BRANDING
+   ======================================================================== */
+
+@import url('https://fonts.googleapis.com/css2?family=Quicksand:wght@500;700&display=swap');
+
+.birdscope-header {
+    position: relative;
+    overflow: hidden;
+    padding: 2rem 1.5rem;
+}
+
+/* Decorative cloud elements */
+.cloud-decor-1 {
+    position: absolute;
+    top: -2.5rem;
+    right: 2.5rem;
+    width: 10rem;
+    height: 10rem;
+    background: rgba(255, 255, 255, 0.4);
+    border-radius: 50%;
+    filter: blur(60px);
+    pointer-events: none;
+}
+
+.cloud-decor-2 {
+    position: absolute;
+    top: 0;
+    right: 33%;
+    width: 8rem;
+    height: 8rem;
+    background: rgba(224, 242, 254, 0.5);
+    border-radius: 50%;
+    filter: blur(40px);
+    pointer-events: none;
+}
+
+.cloud-decor-3 {
+    position: absolute;
+    top: -1.25rem;
+    left: 5rem;
+    width: 6rem;
+    height: 6rem;
+    background: rgba(255, 255, 255, 0.3);
+    border-radius: 50%;
+    filter: blur(40px);
+    pointer-events: none;
+}
+
+/* Flying birds animation */
+@keyframes drift {
+    0%, 100% { transform: translateX(0) translateY(0); }
+    50% { transform: translateX(10px) translateY(-5px); }
+}
+
+@keyframes fadeIn {
+    from { opacity: 0; transform: translateY(5px); }
+    to { opacity: 1; transform: translateY(0); }
+}
+
+.bird-silhouette {
+    position: absolute;
+    animation: drift 8s ease-in-out infinite;
+}
+
+.bird-1 { top: 1.5rem; right: 8rem; width: 1.25rem; height: 1.25rem; color: rgba(148, 163, 184, 0.3); }
+.bird-2 { top: 2.5rem; right: 12rem; width: 1rem; height: 1rem; color: rgba(148, 163, 184, 0.2); animation-delay: 1s; }
+.bird-3 { top: 1rem; right: 16rem; width: 0.75rem; height: 0.75rem; color: rgba(148, 163, 184, 0.15); animation-delay: 2s; }
+
+/* Logo container */
+.bird-logo-wrapper {
+    position: relative;
+    display: inline-block;
+}
+
+.bird-logo-glow {
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(135deg, #38bdf8 0%, #3b82f6 100%);
+    border-radius: 1rem;
+    filter: blur(8px);
+    opacity: 0.3;
+    transition: opacity 0.3s;
+}
+
+.bird-logo-wrapper:hover .bird-logo-glow {
+    opacity: 0.5;
+}
+
+.bird-logo {
+    position: relative;
+    background: linear-gradient(135deg, #38bdf8 0%, #3b82f6 100%);
+    padding: 0.75rem;
+    border-radius: 1rem;
+    box-shadow: 0 10px 25px rgba(56, 189, 248, 0.2);
+}
+
+/* Header content */
+.header-content {
+    position: relative;
+    z-index: 10;
+    max-width: 72rem;
+    margin: 0 auto;
+}
+
+.header-top {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+}
+
+.header-title-group h1 {
+    font-family: 'Quicksand', 'Nunito', sans-serif !important;
+    font-size: 1.875rem !important;
+    font-weight: 700 !important;
+    color: #1e293b !important;
+    letter-spacing: -0.025em !important;
+    margin: 0 !important;
+    display: inline !important;
+}
+
+.header-ai-text {
+    font-size: 1.5rem;
+    font-weight: 300;
+    color: #0ea5e9;
+    margin-left: 0.5rem;
+}
+
+.header-v2-badge {
+    display: inline-block;
+    padding: 0.125rem 0.5rem;
+    font-size: 0.75rem;
+    font-weight: 600;
+    background: linear-gradient(to right, #fbbf24, #f97316);
+    color: white;
+    border-radius: 9999px;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
+    margin-left: 0.5rem;
+}
+
+.header-subtitle {
+    color: #64748b !important;
+    font-size: 0.875rem !important;
+    margin-top: 0.125rem !important;
+}
+
+.mcp-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.375rem 0.75rem;
+    background: rgba(255, 255, 255, 0.6);
+    backdrop-filter: blur(8px);
+    border: 1px solid #e2e8f0;
+    border-radius: 6px;
+    font-size: 0.75rem;
+    color: #1a1a1a !important;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
+    margin-left: auto;
+    user-select: none;
+}
+
+.mcp-badge span {
+    color: #1a1a1a !important;
+}
+
+.mcp-badge.checking {
+    animation: badgePulse 1.5s ease-in-out infinite !important;
+    background: rgba(251, 191, 36, 0.15) !important;
+    border-color: #fbbf24 !important;
+}
+
+/* White text while checking */
+.mcp-badge.checking span {
+    color: #ffffff !important;
+}
+
+/* Disable hover effects while checking */
+.mcp-badge.checking:hover {
+    transform: none !important;
+    animation: badgePulse 1.5s ease-in-out infinite !important;
+}
+
+.mcp-badge.checking .mcp-pulse {
+    background: #fbbf24;
+    animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+.mcp-badge.offline .mcp-pulse {
+    background: #ef4444;
+    animation: none;
+}
+
+.mcp-badge.online .mcp-pulse {
+    background: #34d399;
+}
+
+.mcp-pulse {
+    width: 0.5rem;
+    height: 0.5rem;
+    background: #34d399;
+    border-radius: 50%;
+    animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+@keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.5; }
+}
+
+@keyframes badgePulse {
+    0%, 100% {
+        opacity: 1;
+        transform: scale(1);
+    }
+    50% {
+        opacity: 0.8;
+        transform: scale(1.08);
+    }
+}
+
+/* Feature tags */
+.feature-tags {
+    margin-top: 1.25rem;
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+}
+
+.feature-tag {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.375rem 0.75rem;
+    background: rgba(255, 255, 255, 0.7);
+    backdrop-filter: blur(8px);
+    border: 1px solid rgba(226, 232, 240, 0.8);
+    border-radius: 9999px;
+    font-size: 0.875rem;
+    color: #1a1a1a !important;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
+    transition: all 0.2s;
+    cursor: default;
+    animation: fadeIn 0.4s ease-out forwards;
+    opacity: 0;
+}
+
+.feature-tag span {
+    color: #1a1a1a !important;
+}
+
+.feature-tag:hover {
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+    border-color: #7dd3fc;
+}
+
+.feature-tag:nth-child(1) { animation-delay: 0ms; }
+.feature-tag:nth-child(2) { animation-delay: 80ms; }
+.feature-tag:nth-child(3) { animation-delay: 160ms; }
+.feature-tag:nth-child(4) { animation-delay: 240ms; }
+
+/* Bottom border */
+.header-border {
+    position: absolute;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    height: 1px;
+    background: linear-gradient(to right, transparent, #e2e8f0, transparent);
+}
+
+/* Mobile responsive */
+@media (max-width: 640px) {
+    .mcp-badge {
+        display: none;
+    }
+    .header-top {
+        flex-direction: column;
+        align-items: flex-start;
+    }
+}
+
+/* ========================================================================
+   ONBOARDING FLOW STYLING
+   ======================================================================== */
+
+/* Center and constrain onboarding pages */
+.onboarding-page {
+    max-width: 500px !important;
+    margin: 2rem auto !important;
+    padding: 32px !important;
+}
+
+/* Ensure welcome text is visible on dark background */
+.welcome-text h1, .api-key-text h1 {
+    color: #f9fafb !important;
+}
+
+/* Scroll animation for step transitions */
+.onboarding-page {
+    animation: fadeInStep 0.3s ease-out;
+}
+
+@keyframes fadeInStep {
+    from {
+        opacity: 0.5;
+        transform: translateY(10px);
+    }
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+"""
+
+# ============================================================================
+# CHAT FUNCTIONS - DUAL OUTPUT (CHAT + TOOL LOG)
+# ============================================================================
+
+def format_tool_output_for_chat(tool_output):
+    """
+    Parse tool output and format images/content for display in chatbot.
+    Detects image URLs and converts them to markdown image syntax.
+    """
+    import re
+
+    output_str = str(tool_output)
+
+    # Pattern to match image URLs (common image formats)
+    image_pattern = r'(https?://[^\s<>"{}|\\^\[\]`]+\.(?:jpg|jpeg|png|gif|webp|svg)(?:\?[^\s]*)?)'
+
+    # Find all image URLs
+    image_urls = re.findall(image_pattern, output_str, re.IGNORECASE)
+
+    if image_urls:
+        # Format images as markdown
+        formatted_output = ""
+        for url in image_urls[:3]:  # Limit to first 3 images to avoid clutter
+            formatted_output += f"![Image]({url})\n\n"
+        return formatted_output
+
+    # If no images, return truncated text
+    if len(output_str) > 200:
+        return output_str[:200] + "...\n\n"
+
+    return output_str + "\n\n" if output_str else ""
+
+async def chat_with_tool_visibility(
+    message,
+    history,
+    provider,
+    hf_key,
+    openai_key,
+    anthropic_key,
+    agent_mode,
+    request: gr.Request
+):
+    """
+    Dual-output streaming: chat response + tool execution log
+
+    Yields: tuple(chat_response_text, tool_log_markdown)
+    """
+    # -------------------------------------------------------------------------
+    # 1. VALIDATE CREDENTIALS & SELECT PROVIDER
+    # -------------------------------------------------------------------------
+    if provider == "HuggingFace":
+        api_key = (hf_key.strip() if hf_key and hf_key.strip()
+                   else os.getenv("HF_API_KEY", ""))
+        if not api_key:
+            yield "**API Key Required**\n\nPlease enter your HuggingFace API key in the sidebar.", "*Waiting for API key...*"
+            return
+        provider_key = "huggingface"
+        model = AgentConfig.DEFAULT_HF_MODEL
+    elif provider == "Anthropic":
+        api_key = (anthropic_key.strip() if anthropic_key and anthropic_key.strip()
+                   else os.getenv("ANTHROPIC_API_KEY", ""))
+        if not api_key:
+            yield "**API Key Required**\n\nPlease enter your Anthropic API key in the sidebar.", "*Waiting for API key...*"
+            return
+        provider_key = "anthropic"
+        model = AgentConfig.DEFAULT_ANTHROPIC_MODEL
+    else:  # OpenAI
+        api_key = (openai_key.strip() if openai_key and openai_key.strip()
+                   else os.getenv("OPENAI_API_KEY", ""))
+        if not api_key:
+            yield "**API Key Required**\n\nPlease enter your OpenAI API key in the sidebar.", "*Waiting for API key...*"
+            return
+        provider_key = "openai"
+        model = AgentConfig.DEFAULT_OPENAI_MODEL
+
+    # -------------------------------------------------------------------------
+    # 2. GET OR CREATE AGENT
+    # -------------------------------------------------------------------------
+    try:
+        session_id = request.session_hash
+
+        # Get or create agent (unified subagent architecture)
+        agent = await get_or_create_agent(
+            session_id=session_id,
+            provider=provider_key,
+            api_key=api_key,
+            model=model,
+            mode=agent_mode,  # Include mode in cache key
+            agent_factory_method=lambda: AgentFactory.create_subagent_orchestrator(
+                model=model,
+                api_key=api_key,
+                provider=provider_key,
+                mode=agent_mode  # Pass mode to determine agent composition
+            )
+        )
+    except Exception as e:
+        yield f"**Agent Creation Failed**\n\n{str(e)}", "*Agent creation failed*"
+        return
+
+    config = {"configurable": {"thread_id": session_id}}
+
+    # -------------------------------------------------------------------------
+    # 3. PARSE MESSAGE & HANDLE IMAGE UPLOADS
+    # -------------------------------------------------------------------------
+    # Separate accumulators for chat and tool log
+    chat_response = ""
+    tool_log = ""
+    tool_count = 0
+
+    user_text = ""
+    if isinstance(message, dict):
+        user_text = message.get("text", "")
+        print(f"[DEBUG MESSAGE] User query: {user_text}")  # DEBUG
+        files = message.get("files", [])
+
+        # Handle image uploads
+        if files and len(files) > 0:
+            image_path = files[0]
+
+            if image_path.startswith("http"):
+                # URL - agent will call classify_from_url
+                user_text += f"\n\nWhat bird is this? {image_path}"
+            else:
+                # Local file - call MCP tool directly (show in tool log)
+                tool_log += "🟢 Pre-Classification (Direct MODAL MCP Call)\n"
+                tool_log += "Tool: classify_from_base64\n"
+                tool_log += "Status: Calling Modal GPU classifier directly to avoid token limits...\n\n"
+                yield chat_response, tool_log
+
+                with open(image_path, "rb") as img_file:
+                    image_data = base64.b64encode(img_file.read()).decode('utf-8')
+
+                # Direct MCP call
+                transport = StreamableHttpTransport(
+                    url=AgentConfig.MODAL_MCP_URL,
+                    headers={"X-API-Key": AgentConfig.BIRD_CLASSIFIER_API_KEY}
+                )
+                async with Client(transport) as client:
+                    result = await client.call_tool(
+                        "classify_from_base64",
+                        arguments={"image_data": image_data}
+                    )
+
+                    if result and result.content:
+                        classification = json.loads(result.content[0].text)
+                        species = classification.get("species", "Unknown")
+                        confidence = classification.get("confidence", 0)
+
+                        # Update tool log
+                        tool_log += f"✅ Result: {species} ({confidence:.1%})\n"
+                        tool_log += f"{json.dumps(classification, indent=2)}\n\n"
+                        tool_log += "---\n\n"
+
+                        # Update user message
+                        user_text += f"\n\nI uploaded a bird image. The classifier identified it as: {species} (confidence: {confidence:.1%}). Can you tell me more about this bird?"
+                    else:
+                        tool_log += "❌ Failed\n\n---\n\n"
+                        user_text += "\n\n⚠️ Failed to classify the uploaded image."
+
+                yield chat_response, tool_log
+    else:
+        user_text = message
+
+    # -------------------------------------------------------------------------
+    # 4. STREAM AGENT RESPONSE WITH TOOL VISIBILITY
+    # -------------------------------------------------------------------------
+    print(f"[DEBUG AGENT INPUT] Sending to agent: {user_text}")  # DEBUG
+    async for event in agent.astream_events(
+        {"messages": [{"role": "user", "content": user_text}]},
+        config,
+        version="v2"
+    ):
+        kind = event["event"]
+
+        # Tool call started
+        if kind == "on_tool_start":
+            tool_count += 1
+            tool_name = event["name"]
+            tool_input = event.get("data", {}).get("input", {})
+
+            # Add to tool log
+            tool_log += f"\n🟢 Tool #{tool_count}: {tool_name}\n"
+            tool_log += f"Status: Running...\n"
+            tool_log += f"Input:\n{json.dumps(tool_input, indent=2)}\n\n"
+
+            # Also add visual indicator to chat (wrapped in semantic tag)
+            chat_response += f"\n\n<tool_call>🔧 Using {tool_name}...</tool_call>\n\n"
+
+            yield chat_response, tool_log
+
+        # LLM streaming tokens
+        elif kind == "on_chat_model_stream":
+            content = event["data"]["chunk"].content
+            if content:
+                # Handle both string (OpenAI) and list (Anthropic) content formats
+                if isinstance(content, list):
+                    # Anthropic returns list of content blocks - extract text
+                    for block in content:
+                        if hasattr(block, 'text'):
+                            chat_response += block.text
+                        elif isinstance(block, dict) and 'text' in block:
+                            chat_response += block['text']
+                else:
+                    # OpenAI/HF return string directly
+                    chat_response += content
+                yield chat_response, tool_log
+
+        # Tool finished
+        elif kind == "on_tool_end":
+            tool_output = event.get("data", {}).get("output", "")
+
+            # Format output for tool log (truncate if needed)
+            output_str = str(tool_output)
+            if len(output_str) > 1000:
+                output_str = output_str[:1000] + "\n...(truncated)"
+
+            # Add to tool log
+            tool_log += f"✅ Status: Completed\n"
+            tool_log += f"Output:\n{output_str}\n\n"
+            tool_log += "---\n\n"
+
+            # Format output for chat display (with image rendering)
+            formatted_output = format_tool_output_for_chat(tool_output)
+            if formatted_output.strip():
+                chat_response += formatted_output
+
+            yield chat_response, tool_log
+
+    # Final yield 
+    ## NEW: Updated with LlamaIndex OutputPraser
+    # yield chat_response, tool_log
+    try:
+        from langgraph_agent.structured_output import parse_agent_response
+        formatted_response = await parse_agent_response(
+            raw_response=chat_response,
+            provider=provider_key,
+            api_key=api_key,
+            model=model
+        )
+        yield formatted_response, tool_log
+    except ImportError:
+        # Fallback if LlamaIndex not installed
+        yield chat_response, tool_log
+    except Exception as e:
+        # Fallback if parsing fails
+        print(f"[STRUCTURED OUTPUT ERROR]: {e}")
+        yield chat_response, tool_log
+
+
+# ============================================================================
+# MODAL SERVER HEALTH CHECK
+# ============================================================================
+
+async def check_modal_server_health():
+    """
+    Check if Modal MCP server is alive and warm.
+    Returns status message for UI display.
+    """
+    import asyncio
+
+    print("[DEBUG] Health check started...")
+
+    async def do_health_check():
+        transport = StreamableHttpTransport(
+            url=AgentConfig.MODAL_MCP_URL,
+            headers={"X-API-Key": AgentConfig.BIRD_CLASSIFIER_API_KEY}
+        )
+
+        async with Client(transport) as client:
+            # Try to list tools as a health check
+            tools = await client.list_tools()
+            if tools and len(tools) > 0:
+                return f"✅ Online ({len(tools)} tools ready)"
+            else:
+                return "⚠️ Server responded but no tools found"
+
+    try:
+        # Wrap in timeout - Modal cold starts can take 30-60 seconds
+        result = await asyncio.wait_for(do_health_check(), timeout=60.0)
+        print(f"[DEBUG] Health check result: {result}")
+        return result
+
+    except asyncio.TimeoutError:
+        print("[DEBUG] Health check timeout")
+        return "⏱️ Timeout (still warming up...)"
+    except Exception as e:
+        print(f"[DEBUG] Health check error: {e}")
+        error_msg = str(e)
+        if "401" in error_msg or "Unauthorized" in error_msg:
+            return "🔐 Auth failed"
+        elif "timeout" in error_msg.lower():
+            return "⏱️ Timeout (waking up...)"
+        else:
+            return f"❌ Offline"
+
+# Wrapper to convert to Gradio 6 message format
+async def chat_wrapper(message, history, provider, hf_key, openai_key, anthropic_key, agent_mode, tool_log_state, request: gr.Request):
+    """
+    Wrapper to convert chat outputs to Gradio 6 message format.
+
+    Returns: (updated_history, updated_tool_log)
+    """
+    # Debug: print received API keys
+    print(f"[DEBUG] chat_wrapper received - provider: {provider}, hf_key: {'***' if hf_key else 'None'}, openai_key: {'***' if openai_key else 'None'}, anthropic_key: {'***' if anthropic_key else 'None'}")
+
+    # Extract user message text
+    if isinstance(message, dict):
+        user_message_text = message.get("text", "")
+    else:
+        user_message_text = message
+
+    # Add user message to history
+    history = history + [{"role": "user", "content": user_message_text}]
+
+    # Stream response
+    async for chat_text, tool_log_text in chat_with_tool_visibility(message, history, provider, hf_key, openai_key, anthropic_key, agent_mode, request):
+        # Update history with assistant response
+        updated_history = history + [{"role": "assistant", "content": chat_text}]
+        yield updated_history, tool_log_text
+
+# ============================================================================
+# UI DEFINITION - DUAL PANEL LAYOUT WITH CLOUD AESTHETIC
+# ============================================================================
+
+# Helper function to update text examples based on agent mode
+def update_text_examples_for_mode(mode):
+    """Return appropriate text example dataset based on agent mode."""
+    print(f"[DEBUG] Updating text examples for mode: {mode}")
+
+    if mode == "Audio Finder Agent":
+        # Audio text examples
+        samples = [[text] for text in AUDIO_FINDER_TEXT_EXAMPLES]
+        print(f"[DEBUG] Audio Finder text samples: {len(samples)} examples")
+    else:  # Specialized Subagents (3 Specialists)
+        # Multi-agent text examples
+        samples = [[text] for text in MULTI_AGENT_TEXT_EXAMPLES]
+        print(f"[DEBUG] Multi-agent text samples: {len(samples)} examples")
+
+    return gr.Dataset(samples=samples)
+
+# Helper function to create config HTML
+def create_config_html(provider_choice, agent_mode_choice, hf_key_input, openai_key_input, anthropic_key_input=""):
+    """Generate sky-themed config card HTML."""
+    # Determine model and API key status
+    if provider_choice == "HuggingFace":
+        model = AgentConfig.DEFAULT_HF_MODEL
+        has_key = bool((hf_key_input and hf_key_input.strip()) or os.getenv("HF_API_KEY"))
+    elif provider_choice == "Anthropic":
+        model = AgentConfig.DEFAULT_ANTHROPIC_MODEL
+        has_key = bool((anthropic_key_input and anthropic_key_input.strip()) or os.getenv("ANTHROPIC_API_KEY"))
+    else:
+        model = AgentConfig.DEFAULT_OPENAI_MODEL
+        has_key = bool((openai_key_input and openai_key_input.strip()) or os.getenv("OPENAI_API_KEY"))
+
+    # Extract mode name
+    mode_display = "3 Specialists" if "Specialized Subagents" in agent_mode_choice else "Audio Finder"
+
+    # Status styling
+    if has_key:
+        status_bg = "rgba(16, 185, 129, 0.2)"
+        status_color = "#10b981"
+        status_icon = "✓"
+    else:
+        status_bg = "rgba(239, 68, 68, 0.2)"
+        status_color = "#ef4444"
+        status_icon = "✗"
+
+    return f"""
+    <div style="
+        background: linear-gradient(135deg, rgba(31, 41, 55, 0.95) 0%, rgba(17, 24, 39, 0.98) 100%);
+        border-radius: 12px;
+        padding: 16px 20px;
+        font-family: 'Segoe UI', system-ui, sans-serif;
+        border: 1px solid #374151;
+        box-shadow: 0 4px 15px rgba(0, 0, 0, 0.3);
+        backdrop-filter: blur(10px);
+    ">
+        <!-- Provider Row -->
+        <div style="
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            padding: 6px 0;
+        ">
+            <span style="font-size: 12px; color: #9ca3af;">Provider</span>
+            <div style="display: flex; align-items: center; gap: 6px;">
+                <span style="
+                    font-size: 13px;
+                    font-weight: 500;
+                    color: #f9fafb;
+                ">{provider_choice}</span>
+                <span style="
+                    display: inline-flex;
+                    align-items: center;
+                    justify-content: center;
+                    width: 18px;
+                    height: 18px;
+                    border-radius: 50%;
+                    background: {status_bg};
+                    color: {status_color};
+                    font-size: 11px;
+                    font-weight: bold;
+                ">{status_icon}</span>
+            </div>
+        </div>
+
+        <!-- Model Row -->
+        <div style="
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            padding: 6px 0;
+        ">
+            <span style="font-size: 12px; color: #9ca3af;">Model</span>
+            <span style="
+                font-size: 12px;
+                font-weight: 500;
+                color: #60a5fa;
+                font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
+                background: rgba(59, 130, 246, 0.15);
+                padding: 2px 8px;
+                border-radius: 4px;
+            ">{model}</span>
+        </div>
+
+        <!-- Mode Row -->
+        <div style="
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            padding: 6px 0;
+        ">
+            <span style="font-size: 12px; color: #9ca3af;">Mode</span>
+            <span style="
+                font-size: 12px;
+                font-weight: 500;
+                color: #38bdf8;
+                background: rgba(56, 189, 248, 0.15);
+                padding: 3px 10px;
+                border-radius: 20px;
+                border: 1px solid rgba(56, 189, 248, 0.3);
+            ">{mode_display}</span>
+        </div>
+    </div>
+    """
+
+with gr.Blocks() as demo:
+
+    # ============================================================================
+    # STATE MANAGEMENT - ONBOARDING FLOW
+    # ============================================================================
+    stored_hf_key = gr.State("")
+    stored_openai_key = gr.State("")
+    stored_anthropic_key = gr.State("")
+
+    # Enhanced BirdScope header
+    gr.HTML("""
+    <header class="birdscope-header">
+        <!-- Decorative cloud elements -->
+        <div style="position: absolute; inset: 0; overflow: hidden; pointer-events: none;">
+            <div class="cloud-decor-1"></div>
+            <div class="cloud-decor-2"></div>
+            <div class="cloud-decor-3"></div>
+
+            <!-- Flying bird silhouettes -->
+            <svg class="bird-silhouette bird-1" viewBox="0 0 24 24" fill="currentColor">
+                <path d="M3.5 12C3.5 12 6 9 12 9C18 9 20.5 12 20.5 12C20.5 12 18 10 12 10C6 10 3.5 12 3.5 12Z"/>
+            </svg>
+            <svg class="bird-silhouette bird-2" viewBox="0 0 24 24" fill="currentColor">
+                <path d="M3.5 12C3.5 12 6 9 12 9C18 9 20.5 12 20.5 12C20.5 12 18 10 12 10C6 10 3.5 12 3.5 12Z"/>
+            </svg>
+            <svg class="bird-silhouette bird-3" viewBox="0 0 24 24" fill="currentColor">
+                <path d="M3.5 12C3.5 12 6 9 12 9C18 9 20.5 12 20.5 12C20.5 12 18 10 12 10C6 10 3.5 12 3.5 12Z"/>
+            </svg>
+        </div>
+
+        <!-- Main content -->
+        <div class="header-content">
+            <!-- Logo and title row -->
+            <div class="header-top">
+                <!-- Bird logo -->
+                <div class="bird-logo-wrapper">
+                    <div class="bird-logo-glow"></div>
+                    <div class="bird-logo">
+                        <svg style="width: 2rem; height: 2rem; color: white;" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+                            <!-- Stylized bird -->
+                            <path d="M21 8c-2 0-4 1-6 3-1.5-2-4-3-7-3-2 0-4 .5-5 1l8 4-2 6 4-3 4 3-2-6 8-4c-1-.5-1.5-1-2-1z" fill="currentColor" stroke-width="0"/>
+                            <circle cx="7" cy="9" r="1" fill="white"/>
+                        </svg>
+                    </div>
+                </div>
+
+                <!-- Title -->
+                <div class="header-title-group">
+                    <div style="display: flex; align-items: baseline; gap: 0.5rem;">
+                        <h1>BirdScope</h1>
+                        <span class="header-ai-text">AI</span>
+                        <span class="header-v2-badge">v2</span>
+                    </div>
+                    <p class="header-subtitle">AI-powered bird identification & species reference</p>
+                </div>
+
+            </div>
+
+            <!-- Feature tags with MCP status check button -->
+            <div class="feature-tags">
+                <div class="feature-tag">
+                    <span>🔍</span>
+                    <span>Image Classification</span>
+                </div>
+                <div class="feature-tag">
+                    <span>📸</span>
+                    <span>Unsplash Reference</span>
+                </div>
+                <div class="feature-tag">
+                    <span>🎵</span>
+                    <span>Audio Recordings</span>
+                </div>
+                <div class="feature-tag">
+                    <span>🌍</span>
+                    <span>Conservation Status</span>
+                </div>
+            </div>
+        </div>
+
+        <!-- Bottom border -->
+        <div class="header-border"></div>
+    </header>
+
+    <script>
+    // Auto-scroll tool log panel continuously (for Textbox component)
+    const observer = new MutationObserver(() => {
+        const toolLog = document.querySelector('#tool-log-output textarea');
+        if (toolLog) {
+            toolLog.scrollTop = toolLog.scrollHeight;
+        }
+    });
+
+    // Start observing once the page loads
+    setTimeout(() => {
+        const toolLogContainer = document.querySelector('#tool-log-output');
+        if (toolLogContainer) {
+            observer.observe(toolLogContainer, {
+                childList: true,
+                subtree: true,
+                characterData: true,
+                attributes: true
+            });
+        }
+    }, 1000);
+    </script>
+    """)
+
+    # ============================================================================
+    # ONBOARDING WALKTHROUGH - Using Native Gradio Component
+    # ============================================================================
+    with gr.Walkthrough(selected=1) as walkthrough:
+
+        # Step 1: Welcome & Provider Selection
+        with gr.Step("Welcome", id=1):
+            with gr.Column(elem_classes=["sidebar", "onboarding-page"]):
+                gr.Markdown(
+                    """
+                    # Welcome to BirdScope AI!
+
+                    Let's get you started with your AI-powered bird identification assistant.
+                    """,
+                    elem_classes=["welcome-text"]
+                )
+
+                gr.Markdown("---")
+
+                gr.Markdown("### SELECT LLM PROVIDER")
+                welcome_provider = gr.Dropdown(
+                    choices=["HuggingFace", "OpenAI", "Anthropic"],
+                    value="OpenAI",
+                    show_label=False,
+                    container=False
+                )
+
+                gr.Markdown("**Choose your AI provider**")
+                gr.Markdown("Select between HuggingFace (open models) or OpenAI (GPT models)")
+
+                gr.Markdown("---")
+
+                gr.HTML("""
+                <div style="display: flex; align-items: center; gap: 8px; margin-bottom: 8px;">
+                    <img src="https://cdn.brandfetch.io/idGqKHD5xE/theme/dark/symbol.svg?c=1bxid64Mup7aczewSAYMX&t=1668516030712"
+                         alt="HuggingFace"
+                         style="width: 20px; height: 20px;">
+                    <strong style="color: #d1d5db;">HuggingFace</strong>
+                </div>
+                """)
+                gr.Markdown("Uses open-source models like Qwen 2.5-72B")
+
+                gr.HTML("""
+                <div style="display: flex; align-items: center; gap: 8px; margin-top: 16px;">
+                    <img src="https://cdn.oaistatic.com/_next/static/media/apple-touch-icon.59f2e898.png"
+                         alt="OpenAI"
+                         style="width: 20px; height: 20px; border-radius: 4px;">
+                    <strong style="color: #d1d5db;">OpenAI</strong>
+                </div>
+                """)
+                gr.Markdown("Uses GPT-4 models for high-quality responses")
+
+                gr.HTML("""
+                <div style="display: flex; align-items: center; gap: 8px; margin-top: 16px;">
+                    <img src="https://mintlify.s3.us-west-1.amazonaws.com/anthropic/logo/dark.svg"
+                         alt="Anthropic"
+                         style="width: 20px; height: 20px;">
+                    <strong style="color: #d1d5db;">Anthropic</strong>
+                </div>
+                """)
+                gr.Markdown("Uses Claude models (Sonnet, Opus, Haiku)")
+
+                gr.Markdown("---")
+
+                welcome_next_btn = gr.Button("Next: Enter API Key →", variant="primary", size="lg")
+
+        # Step 2: API Key Input
+        with gr.Step("API Key", id=2):
+            with gr.Column(elem_classes=["sidebar", "onboarding-page"]):
+                gr.Markdown("# Step 2: Enter Your API Key 🔑")
+                gr.Markdown("To use BirdScope AI, you'll need an API key from your selected provider.")
+
+                gr.Markdown("---")
+
+                # HuggingFace API key section
+                with gr.Column(visible=False) as hf_key_section:
+                    gr.Markdown("### AUTHENTICATION")
+                    gr.HTML("""
+                    <div style="display: flex; align-items: center; gap: 8px; margin-bottom: 8px;">
+                        <img src="https://cdn.brandfetch.io/idGqKHD5xE/theme/dark/symbol.svg?c=1bxid64Mup7aczewSAYMX&t=1668516030712"
+                             alt="HuggingFace"
+                             style="width: 20px; height: 20px;">
+                        <strong style="color: #d1d5db;">HuggingFace API Key</strong>
+                    </div>
+                    """)
+                    onboarding_hf_key = gr.Textbox(
+                        placeholder="hf_...",
+                        type="password",
+                        show_label=False,
+                        container=False,
+                        elem_classes=["hf-section"]
+                    )
+                    gr.Markdown("Get your key from [HF Settings](https://huggingface.co/settings/tokens)")
+
+                # OpenAI API key section
+                with gr.Column(visible=False) as openai_key_section:
+                    gr.Markdown("### AUTHENTICATION")
+                    gr.HTML("""
+                    <div style="display: flex; align-items: center; gap: 8px; margin-bottom: 8px;">
+                        <img src="https://cdn.oaistatic.com/_next/static/media/apple-touch-icon.59f2e898.png"
+                             alt="OpenAI"
+                             style="width: 20px; height: 20px; border-radius: 4px;">
+                        <strong style="color: #d1d5db;">OpenAI API Key</strong>
+                    </div>
+                    """)
+                    onboarding_openai_key = gr.Textbox(
+                        placeholder="sk-...",
+                        type="password",
+                        show_label=False,
+                        container=False,
+                        elem_classes=["openai-section"]
+                    )
+                    gr.Markdown("Get your key from [OpenAI Platform](https://platform.openai.com/api-keys)")
+
+                # Anthropic API key section
+                with gr.Column(visible=False) as anthropic_key_section:
+                    gr.Markdown("### AUTHENTICATION")
+                    gr.HTML("""
+                    <div style="display: flex; align-items: center; gap: 8px; margin-bottom: 8px;">
+                        <img src="https://mintlify.s3.us-west-1.amazonaws.com/anthropic/logo/dark.svg"
+                             alt="Anthropic"
+                             style="width: 20px; height: 20px;">
+                        <strong style="color: #d1d5db;">Anthropic API Key</strong>
+                    </div>
+                    """)
+                    onboarding_anthropic_key = gr.Textbox(
+                        placeholder="sk-ant-...",
+                        type="password",
+                        show_label=False,
+                        container=False,
+                        elem_classes=["anthropic-section"]
+                    )
+                    gr.Markdown("Get your key from [Anthropic Console](https://console.anthropic.com/settings/keys)")
+
+                gr.Markdown("---")
+
+                with gr.Row():
+                    api_back_btn = gr.Button("← Back", variant="secondary", scale=1)
+                    api_start_btn = gr.Button("Start Using BirdScope →", variant="primary", scale=3)
+
+        # Step 3: Main App
+        with gr.Step("BirdScope AI", id=3):
+            with gr.Row():
+                # Left: Chat interface (scale=2)
+                with gr.Column(scale=2):
+                    chatbot = gr.Chatbot(
+                        show_label=False,
+                        height=500,
+                        elem_classes=["chatbot-container"]
+                    )
+
+                    msg = gr.MultimodalTextbox(
+                        placeholder="Ask about birds or upload an image...",
+                        file_count="single",
+                        file_types=["image"],
+                        interactive=True,
+                        show_label=False
+                    )
+
+                    with gr.Row():
+                        submit = gr.Button("Send", scale=3)
+                        clear = gr.Button("Clear", scale=1)
+
+                    # Photo examples - always shown (static)
+                    gr.Markdown("**Try uploading a bird photo:**")
+                    gr.Examples(
+                        examples=PHOTO_EXAMPLES,
+                        inputs=msg,
+                        cache_examples=False
+                    )
+
+                    # Text examples - change based on agent mode (dynamic)
+                    gr.Markdown("**Or try a text query:**")
+                    text_examples = gr.Examples(
+                        examples=MULTI_AGENT_TEXT_EXAMPLES,  # Default to multi-agent text examples
+                        inputs=msg,
+                        cache_examples=False
+                    )
+
+                # Middle: Tool execution log (scale=1)
+                with gr.Column(scale=1):
+                    tool_output = gr.Textbox(
+                        value="*Waiting for tool calls...*",
+                        elem_classes=["tool-log-panel"],
+                        elem_id="tool-log-output",
+                        autoscroll=True,
+                        show_label=False,
+                        interactive=False,
+                        container=False
+                    )
+
+                # Right: Sidebar (scale=1)
+                with gr.Column(scale=1, elem_classes=["sidebar"]):
+
+                    # MCP Server Status Check
+                    mcp_status_html = gr.HTML("""
+                        <div class="mcp-badge online" style="margin-bottom: 16px; justify-content: center;">
+                            <span class="mcp-pulse"></span>
+                            <span>Powered by Modal MCP</span>
+                        </div>
+                    """)
+                    check_mcp_btn = gr.Button("Check Modal MCP Server Status", size="sm", variant="secondary", elem_classes=["modal-check-btn"])
+
+                    gr.HTML("""
+                    <p style="font-size: 0.75rem; color: #9ca3af; margin-top: 8px; margin-bottom: 16px; line-height: 1.4;">
+                        Please be patient if the Modal MCP server needs to cold start
+                    </p>
+                    """)
+
+                    gr.Markdown("---")
+
+                    # Provider selection
+                    gr.Markdown("### SELECT LLM PROVIDER")
+                    provider = gr.Dropdown(
+                        choices=["HuggingFace", "OpenAI", "Anthropic"],
+                        value="OpenAI",
+                        show_label=False,
+                        container=False
+                    )
+
+                    # Agent Mode Selector
+                    gr.Markdown("**Agent Configuration**")
+                    gr.Markdown("Choose between unified agent or specialized routing")
+                    agent_mode = gr.Dropdown(
+                        choices=[
+                            "Specialized Subagents (3 Specialists)",
+                            "Audio Finder Agent"  # Changed from "Single Agent (All Tools)"
+                        ],
+                        value="Specialized Subagents (3 Specialists)",
+                        show_label=False,
+                        container=False
+                    )
+
+                    gr.Markdown("---")
+
+                    # API Keys
+                    gr.Markdown("### AUTHENTICATION")
+
+                    gr.HTML("""
+                    <div style="display: flex; align-items: center; gap: 8px; margin-bottom: 8px;">
+                        <img src="https://cdn.brandfetch.io/idGqKHD5xE/theme/dark/symbol.svg?c=1bxid64Mup7aczewSAYMX&t=1668516030712"
+                             alt="HuggingFace"
+                             style="width: 20px; height: 20px;">
+                        <strong style="color: #d1d5db;">HuggingFace API Key</strong>
+                    </div>
+                    """)
+                    hf_key = gr.Textbox(
+                        placeholder="hf_...",
+                        type="password",
+                        show_label=False,
+                        container=False,
+                        elem_classes=["hf-section"]
+                    )
+                    gr.Markdown("Get your key from [HF Settings](https://huggingface.co/settings/tokens)")
+
+                    gr.HTML("""
+                    <div style="display: flex; align-items: center; gap: 8px; margin-bottom: 8px;">
+                        <img src="https://cdn.oaistatic.com/_next/static/media/apple-touch-icon.59f2e898.png"
+                             alt="OpenAI"
+                             style="width: 20px; height: 20px; border-radius: 4px;">
+                        <strong style="color: #d1d5db;">OpenAI API Key</strong>
+                    </div>
+                    """)
+                    openai_key = gr.Textbox(
+                        placeholder="sk-...",
+                        type="password",
+                        show_label=False,
+                        container=False,
+                        elem_classes=["openai-section"]
+                    )
+                    gr.Markdown("Get your key from [OpenAI Platform](https://platform.openai.com/api-keys)")
+
+                    gr.HTML("""
+                    <div style="display: flex; align-items: center; gap: 8px; margin-bottom: 8px;">
+                        <img src="https://mintlify.s3.us-west-1.amazonaws.com/anthropic/logo/dark.svg"
+                             alt="Anthropic"
+                             style="width: 20px; height: 20px;">
+                        <strong style="color: #d1d5db;">Anthropic API Key</strong>
+                    </div>
+                    """)
+                    anthropic_key = gr.Textbox(
+                        placeholder="sk-ant-...",
+                        type="password",
+                        show_label=False,
+                        container=False,
+                        elem_classes=["anthropic-section"]
+                    )
+                    gr.Markdown("Get your key from [Anthropic Console](https://console.anthropic.com/settings/keys)")
+
+                    # Current Configuration Display
+                    gr.Markdown("---")
+                    gr.Markdown("### CURRENT CONFIG")
+
+                    # Generate initial config HTML
+                    session_status = gr.HTML(
+                        value=create_config_html(
+                            provider_choice="OpenAI",
+                            agent_mode_choice="Specialized Subagents (3 Specialists)",
+                            hf_key_input="",
+                            openai_key_input="",
+                            anthropic_key_input=""
+                        )
+                    )
+
+                    # About
+                    gr.Markdown("---")
+                    gr.Markdown("""
+                    ### ABOUT
+
+                    Built for the [Hugging Face MCP-1st-Birthday Hackathon](https://huggingface.co/MCP-1st-Birthday)
+                    """)
+
+                    gr.HTML("""
+                    <div style="text-align: center; margin: 16px 0;">
+                        <img src="https://cdn-uploads.huggingface.co/production/uploads/60d2dc1007da9c17c72708f8/s4q7RzD3S-8xQ8ecXrSwb.png"
+                             alt="Hugging Face MCP 1st Birthday"
+                             style="max-width: 100%; height: auto; border-radius: 8px;">
+                    </div>
+                    """)
+
+                    gr.Markdown("""
+                    **MCP Servers:**
+                    - Modal GPU classifier (2 tools)
+                    - Nuthatch species database (7 tools)
+
+                    **Capabilities:**
+                    - Visual bird identification
+                    - Species reference images (Unsplash)
+                    - Audio recordings (xeno-canto)
+                    - Conservation status data
+                    - Taxonomic exploration
+
+                    **v2 Features:**
+                    - Separate tool log panel
+                    - Detailed execution tracking
+                    - Tool input/output inspection
+                    - Perfect for debugging!
+                    """)
+
+    # State for tool log
+    tool_log_state = gr.State("*Waiting for tool calls...*")
+
+    # ============================================================================
+    # ONBOARDING NAVIGATION HANDLERS - Using Walkthrough
+    # ============================================================================
+
+    def handle_welcome_next(provider_choice):
+        """Navigate to API key page and show appropriate input section."""
+        show_hf = provider_choice == "HuggingFace"
+        show_openai = provider_choice == "OpenAI"
+        show_anthropic = provider_choice == "Anthropic"
+
+        return (
+            gr.Walkthrough(selected=2),          # walkthrough - go to step 2
+            gr.update(visible=show_hf),          # hf_key_section
+            gr.update(visible=show_openai),      # openai_key_section
+            gr.update(visible=show_anthropic)    # anthropic_key_section
+        )
+
+    def handle_api_back():
+        """Navigate back to welcome page."""
+        return gr.Walkthrough(selected=1)
+
+    def handle_api_start(provider_choice, hf_key_input, openai_key_input, anthropic_key_input):
+        """Save credentials and navigate to main app with pre-populated values."""
+        provider_str = str(provider_choice) if provider_choice else "OpenAI"
+
+        # Debug output
+        print(f"[DEBUG] handle_api_start - provider: {provider_str}")
+        print(f"[DEBUG] handle_api_start - hf_key: {'***' if hf_key_input else 'empty'}")
+        print(f"[DEBUG] handle_api_start - openai_key: {'***' if openai_key_input else 'empty'}")
+        print(f"[DEBUG] handle_api_start - anthropic_key: {'***' if anthropic_key_input else 'empty'}")
+
+        # Determine which API key to use
+        if provider_str == "HuggingFace":
+            hf_key_value = hf_key_input if hf_key_input else ""
+            openai_key_value = ""
+            anthropic_key_value = ""
+        elif provider_str == "Anthropic":
+            hf_key_value = ""
+            openai_key_value = ""
+            anthropic_key_value = anthropic_key_input if anthropic_key_input else ""
+        else:
+            hf_key_value = ""
+            openai_key_value = openai_key_input if openai_key_input else ""
+            anthropic_key_value = ""
+
+        # Generate config HTML
+        config_html = create_config_html(
+            provider_choice=provider_str,
+            agent_mode_choice="Specialized Subagents (3 Specialists)",
+            hf_key_input=hf_key_value,
+            openai_key_input=openai_key_value,
+            anthropic_key_input=anthropic_key_value
+        )
+
+        return (
+            gr.Walkthrough(selected=3),  # walkthrough - go to step 3 (main app)
+            provider_str,                # provider dropdown
+            hf_key_value,               # hf_key textbox
+            openai_key_value,           # openai_key textbox
+            anthropic_key_value,        # anthropic_key textbox
+            config_html,                # session_status HTML
+            hf_key_value,               # stored_hf_key state
+            openai_key_value,           # stored_openai_key state
+            anthropic_key_value         # stored_anthropic_key state
+        )
+
+    # Connect onboarding navigation
+    welcome_next_btn.click(
+        fn=handle_welcome_next,
+        inputs=[welcome_provider],
+        outputs=[walkthrough, hf_key_section, openai_key_section, anthropic_key_section]
+    )
+
+    api_back_btn.click(
+        fn=handle_api_back,
+        outputs=[walkthrough]
+    )
+
+    api_start_btn.click(
+        fn=handle_api_start,
+        inputs=[welcome_provider, onboarding_hf_key, onboarding_openai_key, onboarding_anthropic_key],
+        outputs=[
+            walkthrough,
+            provider,
+            hf_key,
+            openai_key,
+            anthropic_key,
+            session_status,
+            stored_hf_key,
+            stored_openai_key,
+            stored_anthropic_key
+        ]
+    )
+
+    # Helper function to update MCP badge HTML
+    def update_mcp_badge_html(status_text: str) -> str:
+        """Generate HTML for MCP badge based on status."""
+        # Determine badge class based on status
+        if "✅" in status_text or "Online" in status_text:
+            badge_class = "online"
+        elif "❌" in status_text or "Offline" in status_text:
+            badge_class = "offline"
+        elif "⏱️" in status_text or "Timeout" in status_text or "Checking" in status_text:
+            badge_class = "checking"
+        else:
+            badge_class = "online"
+
+        return f"""
+            <div class="mcp-badge {badge_class}" style="margin-bottom: 16px; justify-content: center;">
+                <span class="mcp-pulse"></span>
+                <span>{status_text}</span>
+            </div>
+        """
+
+    # JavaScript to scroll tool log to bottom
+    scroll_js = """
+    () => {
+        const toolLog = document.querySelector('#tool-log-output textarea');
+        if (toolLog) {
+            toolLog.scrollTop = toolLog.scrollHeight;
+        }
+    }
+    """
+
+    # Connect events
+    # Update config display when provider, agent mode, or API keys change
+    provider.change(
+        fn=create_config_html,
+        inputs=[provider, agent_mode, hf_key, openai_key, anthropic_key],
+        outputs=[session_status]
+    )
+    agent_mode.change(
+        fn=create_config_html,
+        inputs=[provider, agent_mode, hf_key, openai_key, anthropic_key],
+        outputs=[session_status]
+    )
+
+    # Update text examples when agent mode changes (photo examples stay the same)
+    agent_mode.change(
+        fn=update_text_examples_for_mode,
+        inputs=[agent_mode],
+        outputs=[text_examples.dataset]
+    )
+
+    hf_key.change(
+        fn=create_config_html,
+        inputs=[provider, agent_mode, hf_key, openai_key, anthropic_key],
+        outputs=[session_status]
+    )
+    openai_key.change(
+        fn=create_config_html,
+        inputs=[provider, agent_mode, hf_key, openai_key, anthropic_key],
+        outputs=[session_status]
+    )
+    anthropic_key.change(
+        fn=create_config_html,
+        inputs=[provider, agent_mode, hf_key, openai_key, anthropic_key],
+        outputs=[session_status]
+    )
+    
+    submit_event = msg.submit(
+        fn=chat_wrapper,
+        inputs=[msg, chatbot, provider, hf_key, openai_key, anthropic_key, agent_mode, tool_log_state],
+        outputs=[chatbot, tool_output]
+    ).then(
+        lambda: None,
+        None,
+        msg,
+        js=scroll_js
+    )
+
+    submit_click = submit.click(
+        fn=chat_wrapper,
+        inputs=[msg, chatbot, provider, hf_key, openai_key, anthropic_key, agent_mode, tool_log_state],
+        outputs=[chatbot, tool_output]
+    ).then(
+        lambda: None,
+        None,
+        msg,
+        js=scroll_js
+    )
+
+    def clear_conversation(request: gr.Request):
+        """Clear UI and agent memory by removing agent from cache."""
+        from agent_cache import agent_cache, agent_last_used
+
+        # Clear all cached agents for this session
+        session_id = request.session_hash
+        keys_to_remove = [key for key in agent_cache.keys() if key[0] == session_id]
+
+        for key in keys_to_remove:
+            del agent_cache[key]
+            if key in agent_last_used:
+                del agent_last_used[key]
+
+        print(f"[DEBUG] Clear clicked - removed {len(keys_to_remove)} cached agents for session {session_id[:8]}")
+        return [], "*Waiting for tool calls...*", None
+
+    clear.click(
+        fn=clear_conversation,
+        inputs=[],  # request will be auto-injected
+        outputs=[chatbot, tool_output, msg]
+    )
+
+    # MCP status check handler
+    async def handle_mcp_check():
+        """Check MCP status and return updated HTML."""
+        # First return "checking" state
+        yield update_mcp_badge_html("Checking...")
+        # Then check actual status
+        status = await check_modal_server_health()
+        yield update_mcp_badge_html(status)
+
+    check_mcp_btn.click(
+        fn=handle_mcp_check,
+        outputs=mcp_status_html,
+        show_progress="hidden"
+    )
+
+if __name__ == "__main__":
+    # JavaScript to force dark mode
+    force_dark_mode = """
+    function() {
+        const params = new URLSearchParams(window.location.search);
+        if (!params.has('__theme')) {
+            params.set('__theme', 'dark');
+            window.location.search = params.toString();
+        }
+    }
+    """
+
+    demo.launch(theme=gr.themes.Soft(), css=custom_css, js=force_dark_mode)

bonus_ebird_tools.py

@@ -0,0 +1,841 @@
+"""
+eBird MCP Server
+Wraps eBird API v2 as reusable MCP tools
+Runs locally with FastMCP and supports both stdio and streamable-http transport
+
+Features:
+- 7 core tools for bird data discovery
+- Configurable tool enabling/disabling
+- Support for both user input AND classifier output
+- Rate limiting and error handling
+- JSON responses for easy integration
+- Dual transport: stdio for CLI, streamable-http for web clients (via FastAPI)
+"""
+import os
+import sys
+import requests
+import json
+import time
+from typing import Optional, Dict, List, Any
+from fastmcp import FastMCP
+from dotenv import load_dotenv
+
+
+# ============================================================================
+# CONFIGURATION & SETUP
+# ============================================================================
+
+load_dotenv()
+
+EBIRD_API_KEY = os.getenv("EBIRD_API_KEY")
+BASE_URL = os.getenv("EBIRD_BASE_URL", "https://api.ebird.org/v2")
+DEFAULT_TIMEOUT = 15
+RATE_LIMIT_DELAY = 0.1  # 100ms between requests
+
+if not EBIRD_API_KEY:
+    # Print to stderr to avoid corrupting STDIO MCP protocol (stdout must be JSON-RPC only)
+    print("⚠️  [WARNING]: EBIRD_API_KEY not found in .env", file=sys.stderr)
+    print("   Get one from: https://ebird.org/api/keygen", file=sys.stderr)
+
+# Authentication configuration (production only)
+IS_PRODUCTION = os.getenv("ENVIRONMENT") == "production"
+MCP_API_KEY = os.getenv("MCP_API_KEY")
+
+# Tool configuration - enable/disable as needed
+ENABLED_TOOLS = {
+    "search_species": True,
+    "get_recent_sightings_nearby": True,
+    "find_hotspots_nearby": True,
+    "get_location_birds": True,
+    "get_species_info": True,
+    "get_notable_sightings": True,
+    "analyze_location": True,
+}
+
+# Initialize FastMCP server with optional auth
+if IS_PRODUCTION and MCP_API_KEY:
+    # Production: Enable API key authentication
+    from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+    auth = DebugTokenVerifier(
+        validate=lambda token: token == MCP_API_KEY,
+        client_id="ebird-mcp-client"
+    )
+    mcp = FastMCP("eBird Data Explorer", auth=auth)
+else:
+    # Development: No authentication
+    mcp = FastMCP("eBird Data Explorer")
+
+# Rate limiting tracker
+_last_request_time = 0
+
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+def _rate_limit():
+    """Enforce rate limiting to avoid exceeding eBird's API limits"""
+    global _last_request_time
+    elapsed = time.time() - _last_request_time
+    if elapsed < RATE_LIMIT_DELAY:
+        time.sleep(RATE_LIMIT_DELAY - elapsed)
+    _last_request_time = time.time()
+
+
+def _make_request(endpoint: str, params: Optional[Dict] = None) -> Optional[Dict]:
+    """
+    Centralized request handler with error handling and rate limiting.
+
+    Args:
+        endpoint: API endpoint path (e.g., "/data/obs/geo/recent")
+        params: Query parameters dictionary
+
+    Returns:
+        JSON response data or None on error
+    """
+    _rate_limit()
+    try:
+        headers = {"X-eBirdApiToken": EBIRD_API_KEY}
+        url = f"{BASE_URL}{endpoint}"
+        response = requests.get(
+            url,
+            headers=headers,
+            params=params or {},
+            timeout=DEFAULT_TIMEOUT
+        )
+
+        if response.status_code == 200:
+            return response.json()
+        elif response.status_code == 400:
+            print(f"❌ Bad Request ({url}): {response.text[:400]}", flush=True)
+            return None
+        elif response.status_code == 401:
+            print(f"❌ Unauthorized ({url}): Check your EBIRD_API_KEY - body={response.text[:400]}", flush=True)
+            return None
+        elif response.status_code == 404:
+            print(f"❌ Not found ({url}): Invalid endpoint or resource - body={response.text[:400]}", flush=True)
+            return None
+        else:
+            print(
+                f"❌ HTTP {response.status_code} for {url} "
+                f"params={params or {}} body={response.text[:400]}",
+                flush=True,
+            )
+            return None
+
+    except requests.Timeout:
+        print(f"❌ Request timeout after {DEFAULT_TIMEOUT}s for {endpoint}", flush=True)
+        return None
+    except requests.ConnectionError:
+        print(f"❌ Connection error calling {endpoint} - check network", flush=True)
+        return None
+    except Exception as e:
+        print(f"❌ Unexpected error calling {endpoint}: {str(e)}", flush=True)
+        return None
+
+
+def _format_success_response(data: Any, **kwargs) -> str:
+    """Format a successful response as JSON"""
+    response = {"status": "success", "data": data}
+    response.update(kwargs)
+    return json.dumps(response)
+
+
+def _format_error_response(error: str) -> str:
+    """Format an error response as JSON"""
+    return json.dumps({"status": "error", "error": error})
+
+
+# ============================================================================
+# TOOL 1: search_species
+# ============================================================================
+# Use case: User types "cardinal" or classifier returns "Northern Cardinal"
+# This tool finds the species code needed for other tools
+
+def search_species(search_term: str, max_results: int = 10) -> str:
+    """
+    Search for bird species by common or scientific name.
+
+    This tool finds species codes needed for other lookups. Accepts:
+    - Common names: "cardinal", "blue jay", "bald eagle"
+    - Partial matches: "car" -> "Northern Cardinal", "Carolina Parakeet", etc.
+    - Scientific names: "Cardinalis cardinalis"
+
+    Can accept:
+    - User input: Direct species search
+    - Classifier output: e.g., "Northern Cardinal" from image classification
+
+    Args:
+        search_term: Bird name (common or scientific)
+        max_results: Maximum matches to return (default: 10)
+
+    Returns:
+        JSON with matched species and their codes for other tools
+
+    Example:
+        search_species("cardinal")
+        -> Returns all cardinals with species codes (norcar, carcar, etc.)
+    """
+    if not search_term or len(search_term.strip()) < 2:
+        return _format_error_response("Search term must be at least 2 characters")
+
+    try:
+        endpoint = "/ref/taxonomy/ebird"
+        params = {"fmt": "json"}
+
+        data = _make_request(endpoint, params)
+
+        if not data:
+            return _format_error_response("Failed to fetch species database")
+
+        search_lower = search_term.lower()
+
+        # Filter: match in common name OR scientific name, main species only
+        matches = [
+            {
+                "common_name": s['comName'],
+                "scientific_name": s['sciName'],
+                "species_code": s['speciesCode'],
+                "family": s.get('familyComName', 'Unknown'),
+                "order": s.get('order', 'Unknown'),
+                "category": s.get('category', 'Unknown')
+            }
+            for s in data
+            if (search_lower in s['comName'].lower() or search_lower in s['sciName'].lower()) and s.get('category') == 'species'
+        ]
+
+        if not matches:
+            return _format_error_response(f"No species found matching '{search_term}'")
+
+        return _format_success_response(
+            matches[:max_results],
+            count=len(matches[:max_results]),
+            search_term=search_term
+        )
+
+    except Exception as e:
+        return _format_error_response(f"Search failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(search_species)
+
+
+# ============================================================================
+# TOOL 2: get_recent_sightings_nearby
+# ============================================================================
+# Use case: After identifying a bird, find recent sightings near user
+
+def get_recent_sightings_nearby(
+    species_code: str,
+    latitude: float,
+    longitude: float,
+    radius_km: int = 50,
+    max_results: int = 10
+) -> str:
+    """
+    Get recent sightings of a specific bird near a location.
+
+    Returns observations from other birdwatchers in the eBird network.
+
+    Can accept:
+        - User input: Coordinates from address lookup, species code from search
+        - Classifier output: Species code (after search_species lookup)
+
+    Args:
+        species_code: eBird species code (e.g., "norcar" for Northern Cardinal)
+        latitude: Location latitude
+        longitude: Location longitude
+        radius_km: Search radius in kilometers (max 50)
+        max_results: Maximum observations to return
+
+    Returns:
+        JSON with recent observations near location
+
+    Example:
+        get_recent_sightings_nearby("norcar", 40.7829, -73.9654, 25, 10)
+        -> Recent cardinal sightings in Central Park area
+    """
+    if not species_code:
+        return _format_error_response("Species code required")
+
+    if not -90 <= latitude <= 90:
+        return _format_error_response("Latitude must be between -90 and 90")
+
+    if not -180 <= longitude <= 180:
+        return _format_error_response("Longitude must be between -180 and 180")
+
+    try:
+        endpoint = f"/data/obs/geo/recent/{species_code}"
+        params = {
+            "lat": latitude,
+            "lng": longitude,
+            "dist": min(radius_km, 50),
+            "maxResults": max_results
+        }
+
+        data = _make_request(endpoint, params)
+
+        if data is None:
+            return _format_error_response("Failed to fetch sightings")
+
+        if not data:
+            return _format_success_response(
+                [],
+                count=0,
+                location={"lat": latitude, "lng": longitude},
+                radius_km=radius_km,
+                species_code=species_code
+            )
+
+        sightings = [
+            {
+                "common_name": obs['comName'],
+                "scientific_name": obs['sciName'],
+                "location": obs['locName'],
+                "location_id": obs['locId'],
+                "date": obs['obsDt'],
+                "count": obs.get('howMany'),
+                "latitude": obs.get('lat'),
+                "longitude": obs.get('lng')
+            }
+            for obs in data
+        ]
+
+        return _format_success_response(
+            sightings,
+            count=len(sightings),
+            location={"lat": latitude, "lng": longitude},
+            radius_km=radius_km
+        )
+
+    except Exception as e:
+        return _format_error_response(f"Lookup failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(get_recent_sightings_nearby)
+
+
+# ============================================================================
+# TOOL 3: find_hotspots_nearby
+# ============================================================================
+# Use case: Find popular birding locations near user
+
+def find_hotspots_nearby(
+    latitude: float,
+    longitude: float,
+    radius_km: int = 50,
+    max_results: int = 15
+) -> str:
+    """
+    Find popular birding hotspots (known locations) near a location.
+
+    Hotspots are locations frequented by birders where many species recorded.
+    Great for planning birding trips.
+
+    Can accept:
+        - User input: Coordinates from address lookup
+        - Classifier output: Not directly, but used after location analysis
+
+    Args:
+        latitude: Location latitude
+        longitude: Location longitude
+        radius_km: Search radius in kilometers
+        max_results: Maximum hotspots to return
+
+    Returns:
+        JSON with nearby hotspots and their details
+
+    Example:
+        find_hotspots_nearby(40.7829, -73.9654, 25, 10)
+        -> Popular birding locations near Central Park
+    """
+    if not -90 <= latitude <= 90:
+        return _format_error_response("Latitude must be between -90 and 90")
+
+    if not -180 <= longitude <= 180:
+        return _format_error_response("Longitude must be between -180 and 180")
+
+    try:
+        endpoint = "/ref/hotspot/geo"
+        params = {
+            "lat": latitude,
+            "lng": longitude,
+            "dist": radius_km,
+            "fmt": "json"
+        }
+
+        data = _make_request(endpoint, params)
+
+        if data is None:
+            return _format_error_response("Failed to fetch hotspots")
+
+        if not data:
+            return _format_success_response(
+                [],
+                count=0,
+                location={"lat": latitude, "lng": longitude},
+                radius_km=radius_km,
+                message="No hotspots found nearby"
+            )
+
+        hotspots = [
+            {
+                "name": hotspot['locName'],
+                "location_id": hotspot['locId'],
+                "latitude": hotspot['lat'],
+                "longitude": hotspot['lng'],
+                "species_recorded": hotspot.get('numSpeciesAllTime', 0),
+                "latest_obs_date": hotspot.get('latestObsDt', 'Unknown')
+            }
+            for hotspot in data[:max_results]
+        ]
+
+        return _format_success_response(
+            hotspots,
+            count=len(hotspots),
+            location={"lat": latitude, "lng": longitude},
+            radius_km=radius_km
+        )
+
+    except Exception as e:
+        return _format_error_response(f"Lookup failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(find_hotspots_nearby)
+
+# ============================================================================
+# TOOL 4: get_location_birds
+# ============================================================================
+# Use case: See ALL birds being seen at a location right now
+
+def get_location_birds(
+    latitude: float,
+    longitude: float,
+    radius_km: int = 50,
+    max_results: int = 50
+) -> str:
+    """
+    Get ALL recent bird sightings at a location (no species filter).
+
+    Returns comprehensive view of bird activity - what's being seen right now
+
+    Can accept:
+        - User input: Coordinates from address lookup
+        - Classifier output: Not directly, but provides context for found species
+
+    Args:
+        latitude: Location latitude
+        longitude: Location longitude
+        radius_km: Search radius in kilometers
+        max_results: Maximum sightings to return
+
+    Returns:
+        JSON with all recent sightings and summary statistics
+
+    Example:
+        get_location_birds(40.7829, -73.9654, 25, 60)
+        -> All birds being seen in Central Park area right now
+    """
+    if not -90 <= latitude <= 90:
+        return _format_error_response("Latitude must be between -90 and 90")
+
+    if not -180 <= longitude <= 180:
+        return _format_error_response("Longitude must be between -180 and 180")
+
+    try:
+        endpoint = "/data/obs/geo/recent"
+        params = {
+            "lat": latitude,
+            "lng": longitude,
+            "dist": radius_km,
+            "maxResults": max_results
+        }
+
+        data = _make_request(endpoint, params)
+
+        if data is None:
+            return _format_error_response("Failed to fetch sightings")
+
+        if not data:
+            return _format_success_response(
+                [],
+                count=0,
+                unique_species=0,
+                location={"lat": latitude, "lng": longitude},
+                radius_km=radius_km,
+                message="No sightings found at this location"
+            )
+
+        sightings = [
+            {
+                "common_name": obs['comName'],
+                "scientific_name": obs['sciName'],
+                "species_code": obs['speciesCode'],
+                "location": obs['locName'],
+                "date": obs['obsDt'],
+                "count": obs.get('howMany'),
+                "latitude": obs.get('lat'),
+                "longitude": obs.get('lng')
+            }
+            for obs in data
+        ]
+
+        # Calculate unique species count
+        unique_species = len(set(obs['common_name'] for obs in sightings))
+
+        # Find most common birds
+        bird_counts = {}
+        for obs in sightings:
+            bird_counts[obs['common_name']] = bird_counts.get(obs['common_name'], 0) + 1
+        top_birds = sorted(bird_counts.items(), key=lambda x: x[1], reverse=True)[:5]
+
+        return _format_success_response(
+            sightings,
+            count=len(sightings),
+            unique_species=unique_species,
+            location={"lat": latitude, "lng": longitude},
+            radius_km=radius_km,
+            top_birds=[{"species": name, "observations": count} for name, count in top_birds]
+        )
+
+    except Exception as e:
+        return _format_error_response(f"Lookup failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(get_location_birds)
+
+
+# ============================================================================
+# TOOL 5: get_species_info
+# ============================================================================
+# Use case: Get taxonomy and detailed info about a species
+
+def get_species_info(species_code: str) -> str:
+    """
+    Get detailed taxonomy and metadata for a bird species.
+
+    Returns scientific classification, family, order, and other details.
+
+    Can accept:
+        - User input: Species code from search_species tool
+        - Classifier output: Species code (after search_species lookup)
+
+    Args:
+        species_code: eBird species code (e.g., "norcar")
+
+    Returns:
+        JSON with complete species information
+
+    Example:
+        get_species_info("norcar")
+        -> Northern Cardinal taxonomy, family, order, etc.
+    """
+    if not species_code or len(species_code.strip()) < 2:
+        return _format_error_response("Species code required")
+
+    try:
+        endpoint = "/ref/taxonomy/ebird"
+        params = {
+            "fmt": "json",
+            "species": species_code
+        }
+
+        data = _make_request(endpoint, params)
+
+        if data is None:
+            return _format_error_response("Failed to fetch taxonomy")
+
+        # Find main species (not subspecies)
+        species = None
+        for s in data:
+            if s.get('speciesCode') == species_code and s.get('category') == 'species':
+                species = s
+                break
+
+        if not species:
+            return _format_error_response(f"Species code '{species_code}' not found")
+
+        info = {
+            "common_name": species['comName'],
+            "scientific_name": species['sciName'],
+            "species_code": species['speciesCode'],
+            "family": species.get('familyComName', 'Unknown'),
+            "family_sci_name": species.get('familySciName', 'Unknown'),
+            "order": species.get('order', 'Unknown'),
+            "category": species.get('category', 'Unknown')
+        }
+
+        return _format_success_response(info, species_code=species_code)
+
+    except Exception as e:
+        return _format_error_response(f"Lookup failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(get_species_info)
+
+
+# ============================================================================
+# TOOL 6: get_notable_sightings
+# ============================================================================
+# Use case: Find rare/unusual birds in a region
+
+def get_notable_sightings(
+    region_code: str = "US",
+    max_results: int = 10
+) -> str:
+    """
+    Get rare or notable bird sightings in a region.
+
+    Notable sightings are birds that are unusual/rare for the region.
+    Great for discovering unexpected species.
+
+    Can accept:
+        - User input: Region code (e.g., "US", "US-NY", "CA-ON")
+        - Classifier output: Not directly, but region can be derived from location
+
+    Args:
+        region_code: Region code (country, state, province)
+        max_results: Maximum notable sightings to return
+
+    Returns:
+        JSON with recent notable/rare sightings
+
+    Example:
+        get_notable_sightings("US-NY", 10)
+        -> Rare/unusual birds spotted in New York recently
+    """
+    if not region_code:
+        return _format_error_response("Region code required")
+
+    try:
+        endpoint = f"/data/obs/{region_code}/recent/notable"
+        params = {"maxResults": max_results}
+
+        data = _make_request(endpoint, params)
+
+        if data is None:
+            return _format_error_response("Failed to fetch notable sightings")
+
+        if not data:
+            return _format_success_response(
+                [],
+                count=0,
+                region_code=region_code,
+                message="No notable sightings found"
+            )
+
+        notable = [
+            {
+                "common_name": obs['comName'],
+                "scientific_name": obs['sciName'],
+                "species_code": obs['speciesCode'],
+                "location": obs['locName'],
+                "location_id": obs['locId'],
+                "date": obs['obsDt'],
+                "count": obs.get('howMany'),
+                "latitude": obs.get('lat'),
+                "longitude": obs.get('lng')
+            }
+            for obs in data
+        ]
+
+        return _format_success_response(
+            notable,
+            count=len(notable),
+            region_code=region_code
+        )
+
+    except Exception as e:
+        return _format_error_response(f"Lookup failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(get_notable_sightings)
+
+# ============================================================================
+# TOOL 7: analyze_location
+# ============================================================================
+# Use case: Comprehensive location analysis - all birds + hotspots + summary
+
+def analyze_location(
+    latitude: float,
+    longitude: float,
+    radius_km: int = 50
+) -> str:
+    """
+    Comprehensive location analysis combining all bird data.
+
+    This is a "power tool" that combines multiple API calls to give
+    complete view of birding activity: recent sightings, hotspots, stats.
+
+    Can accept:
+        - User input: Coordinates from address lookup
+        - Classifier output: Not directly, but provides full context
+
+    Args:
+        latitude: Location latitude
+        longitude: Location longitude
+        radius_km: Search radius in kilometers
+
+    Returns:
+        JSON with sightings, hotspots, and comprehensive statistics
+
+    Example:
+        analyze_location(40.7820, -73.9654, 25)
+        -> Complete birding report for Central Park area
+    """
+    if not -90 <= latitude <= 90:
+        return _format_error_response("Latitude must be between -90 and 90")
+
+    if not -180 <= longitude <= 180:
+        return _format_error_response("Longitude must be between -180 and 180")
+
+    try:
+        # Get all recent observations
+        obs_endpoint = "/data/obs/geo/recent"
+        obs_params = {
+            "lat": latitude,
+            "lng": longitude,
+            "dist": radius_km,
+            "maxResults": 100
+        }
+
+        sightings_data = _make_request(obs_endpoint, obs_params) or []
+
+        # Get hotspots (max 50)
+        hotspots_endpoint = "/ref/hotspot/geo"
+        hotspots_params = {
+            "lat": latitude,
+            "lng": longitude,
+            "dist": radius_km,
+            "fmt": "json"
+        }
+
+        hotspots_data = _make_request(hotspots_endpoint, hotspots_params) or []
+
+        # Format sightings
+        sightings = [
+            {
+                "common_name": obs['comName'],
+                "scientific_name": obs['sciName'],
+                "species_code": obs['speciesCode'],
+                "location": obs['locName'],
+                "date": obs['obsDt'],
+                "count": obs.get('howMany'),
+                "latitude": obs.get('lat'),
+                "longitude": obs.get('lng')
+            }
+            for obs in sightings_data
+        ]
+
+        # Format hotspots
+        hotspots = [
+            {
+                "name": hotspot['locName'],
+                "location_id": hotspot['locId'],
+                "latitude": hotspot['lat'],
+                "longitude": hotspot['lng'],
+                "species_recorded": hotspot.get('numSpeciesAllTime', 0),
+                "latest_obs_date": hotspot.get('latestObsDt', 'Unknown')
+            }
+            for hotspot in hotspots_data[:15]
+        ]
+
+        # Calculate statistics
+        unique_species = len(set(obs['common_name'] for obs in sightings))
+
+        # Find top species
+        bird_counts = {}
+        for obs in sightings:
+            bird_counts[obs['common_name']] = bird_counts.get(obs['common_name'], 0) + 1
+        top_birds = sorted(bird_counts.items(), key=lambda x: x[1], reverse=True)[:10]
+
+        analysis = {
+            "location": {
+                "latitude": latitude,
+                "longitude": longitude,
+                "radius_km": radius_km,
+            },
+            "sightings": sightings,
+            "hotspots": hotspots,
+            "summary": {
+                "total_sightings": len(sightings),
+                "unique_species": unique_species,
+                "total_hotspots": len(hotspots),
+                "top_species": [{"name": name, "observations": count} for name, count in top_birds]
+            }
+        }
+
+        return _format_success_response(analysis)
+
+    except Exception as e:
+        return _format_error_response(f"Analysis failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(analyze_location)
+
+# ============================================================================
+# SERVER STARTUP WITH DUAL TRANSPORT SUPPORT
+# ============================================================================
+
+def main():
+    """Start the MCP server with dual transport support."""
+    # Determine transport mode first
+    is_http_mode = "--http" in sys.argv or "--streamable-http" in sys.argv
+
+    # For STDIO mode, all informational output must go to stderr (stdout is for JSON-RPC only)
+    output = sys.stdout if is_http_mode else sys.stderr
+
+    print("\n" + "=" * 70, file=output)
+    print("🦅 [eBird MCP SERVER] - Starting...", file=output)
+    print("=" * 70, file=output)
+    print(f"[API KEY]:    {'✅ Configured' if EBIRD_API_KEY else '❌ Missing'}", file=output)
+    print("\n[AVAILABLE TOOLS]:", file=output)
+
+    tools_list = [
+        "1. search_species - Find species by name",
+        "2. get_recent_sightings_nearby - Recent sightings near location",
+        "3. find_hotspots_nearby - Find popular birding locations",
+        "4. get_location_birds - All birds at a location",
+        "5. get_species_info - Taxonomy and species details",
+        "6. get_notable_sightings - Rare/unusual birds in region",
+        "7. analyze_location - Comprehensive location analysis"
+    ]
+
+    for tool in tools_list:
+        print(f"  ✓ {tool}", file=output)
+
+    print("\n" + "=" * 70, file=output)
+
+    if is_http_mode:
+        # Extract port from command line args
+        port = 8000
+        host = "127.0.0.1"
+
+        for i, arg in enumerate(sys.argv):
+            if arg == "--port" and i + 1 < len(sys.argv):
+                port = int(sys.argv[i + 1])
+            elif arg == "--host" and i + 1 < len(sys.argv):
+                host = sys.argv[i + 1]
+
+        print("[TRANSPORT]: Starting streamable-http MCP server", file=output)
+        print(f"[HOST]:      {host}", file=output)
+        print(f"[PORT]:      {port}", file=output)
+        print(f"[URL]:       http://{host}:{port}", file=output)
+        print(f"[AUTH]:      {'🔒 Enabled (production)' if IS_PRODUCTION and MCP_API_KEY else '🔓 Disabled (development)'}", file=output)
+        print("[NOTE]:      This is proper MCP over HTTP", file=output)
+        print("=" * 70 + "\n", file=output)
+
+        # Run with streamable-http transport (built-in MCP support)
+        mcp.run(transport="streamable-http", host=host, port=port)
+    else:
+        print("[TRANSPORT]: Running as stdio MCP server", file=output)
+        print("[NOTE]:      For HTTP transport, use: python ebird_tools.py --http", file=output)
+        print("=" * 70 + "\n", file=output)
+
+        # Run as stdio MCP server (default)
+        mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

docs/bonus_ebird_docs/EBIRD_MCP_README.md

@@ -0,0 +1,972 @@
+# eBird MCP Server - BONUS Integration
+
+Complete eBird API wrapper as a Model Context Protocol (MCP) server with **dual transport support** and **full MCP protocol compliance**.
+
+## 🎯 BONUS: Integrate eBird into Your Agent Framework
+
+**Want to replace nuthatch with eBird for real-time bird sightings?** Here's how to plug this bonus eBird MCP server into your existing BirdScope AI system:
+
+---
+
+### 🚀 **Architecture Options**
+
+**Choose your approach:**
+
+#### **Option A: Replace Nuthatch (Recommended for simplicity)**
+Follow steps 1-8 below to swap nuthatch for eBird.
+
+#### **Option B: Run Both Nuthatch + eBird (Maximum capabilities)**
+
+Get the **best of both worlds** - static species data + real-time sightings:
+
+1. **Keep nuthatch running** (your existing server)
+2. **Add eBird as bonus server** on different port:
+   ```bash
+   python bonus_ebird_tools.py --http --port 8001
+   ```
+3. **Update MCPClientManager** to connect to both:
+   ```python
+   # Add to langgraph_agent/mcp_clients.py
+   async def create_multi_server_client(self):
+       clients = []
+       
+       # Keep nuthatch (stdio)
+       nuthatch_client = await self.create_stdio_client("python nuthatch_tools.py")
+       clients.append(nuthatch_client)
+       
+       # Add eBird (HTTP on port 8001)
+       ebird_client = await self.create_http_client("http://localhost:8001/mcp")
+       clients.append(ebird_client)
+       
+       # Keep Modal
+       modal_client = await self.create_http_client(AgentConfig.MODAL_MCP_URL)
+       clients.append(modal_client)
+       
+       return clients
+   ```
+
+4. **Combine toolsets** in subagent configs:
+   ```python
+   "species_explorer": {
+       "tools": [
+           # Nuthatch tools
+           "search_birds", "get_bird_info", "get_bird_images", "get_bird_audio",
+           # eBird tools  
+           "search_species", "get_recent_sightings_nearby", "find_hotspots_nearby"
+       ]
+   }
+   ```
+
+**Benefits:** Complete birding AI with species database + real-time sightings + image classification.
+
+---
+
+### Step 1: Install eBird Dependencies
+
+```bash
+pip install requests python-dotenv
+```
+
+### Step 2: Get eBird API Key
+
+1. Visit: https://ebird.org/api/keygen
+2. Create account and generate API key
+3. Add to your `.env` file:
+```bash
+EBIRD_API_KEY=your-actual-ebird-key-here
+```
+
+### Step 3: Start eBird MCP Server
+
+Choose your transport mode:
+
+**Option A: Stdio Transport (for agents)**
+```bash
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+python bonus_ebird_tools.py
+```
+
+**Option B: HTTP Transport (for web UIs)**
+```bash
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+python bonus_ebird_tools.py --http --port 8001
+```
+
+### Step 4: Update Environment Variables
+
+In your `.env` file, replace nuthatch with eBird:
+
+```bash
+# OLD (nuthatch)
+NUTHATCH_USE_STDIO=true
+NUTHATCH_API_KEY=your-nuthatch-key
+NUTHATCH_BASE_URL=https://nuthatch.lastelm.software/v2
+
+# NEW (eBird)
+EBIRD_USE_STDIO=true
+EBIRD_API_KEY=your-ebird-key
+EBIRD_BASE_URL=https://api.ebird.org/v2
+```
+
+### Step 5: Update MCP Client Manager
+
+Modify `langgraph_agent/mcp_clients.py` to connect to eBird instead of nuthatch:
+
+```python
+# In create_multi_server_client() function:
+
+# OLD: Nuthatch connection
+# nuthatch_client = await self.create_stdio_client("python nuthatch_tools.py")
+
+# NEW: eBird connection  
+ebird_client = await self.create_stdio_client("python bonus_ebird_tools.py")
+```
+
+### Step 6: Update Subagent Tool Configurations
+
+Update `langgraph_agent/subagent_config.py` to use eBird tools:
+
+```python
+# OLD: Nuthatch tools
+"search_birds": True,
+"get_bird_info": True, 
+"get_bird_images": True,
+"get_bird_audio": True,
+
+# NEW: eBird tools
+"search_species": True,
+"get_recent_sightings_nearby": True,
+"find_hotspots_nearby": True,
+"get_location_birds": True,
+"get_species_info": True,
+"get_notable_sightings": True,
+"analyze_location": True,
+```
+
+**Important:** eBird focuses on **real-time sightings** while nuthatch focuses on **species database**. Your subagents will now prioritize location-based bird data over static species information.
+
+### Step 7: Test the Integration
+
+```bash
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+python tests/test_subagents.py
+```
+
+This will test that your subagents can use the new eBird tools.
+
+### Step 8: Update Agent Prompts (Optional)
+
+Consider updating subagent prompts in `subagent_config.py` to leverage eBird's location features:
+
+```python
+"species_explorer": {
+    # ... existing config ...
+    "prompt": """You are a Species Explorer with access to real-time eBird data.
+    
+    **Your New Capabilities:**
+    - Find recent sightings of birds near locations
+    - Discover popular birding hotspots  
+    - Analyze complete location bird activity
+    - Track notable/rare bird sightings
+    
+    # ... rest of prompt ...
+    """
+}
+```
+
+### What Changes in Your Agent Behavior
+
+| **Aspect** | **Before (Nuthatch)** | **After (eBird)** |
+|------------|----------------------|-------------------|
+| **Data Focus** | Species database, images, audio | Real-time sightings, locations |
+| **Location Tools** | None | ✅ Hotspots, sightings, analysis |
+| **Freshness** | Static database | ⚡ Live bird observations |
+| **Use Cases** | Species identification | 🗺️ Birding trip planning |
+| **Coverage** | 1000+ species (NA/Europe) | 🌍 Global bird sightings |
+
+### Expected Agent Capabilities
+
+After integration, your agents can now:
+
+1. **Find Recent Sightings**: "Where have Northern Cardinals been seen recently?"
+2. **Discover Hotspots**: "What are the best birding locations near Central Park?"
+3. **Location Analysis**: "Give me a complete birding report for this area"
+4. **Rare Bird Alerts**: "What unusual birds have been spotted in New York?"
+5. **Trip Planning**: "Plan a birding trip based on current sightings"
+
+### Troubleshooting Integration
+
+**Issue: "Unknown mode" error**
+- Check that subagent configs use valid eBird tool names
+- Verify eBird server is running
+
+**Issue: No location data**
+- Ensure coordinates are passed to location-based tools
+- Check eBird API key is valid
+
+**Issue: Different data format**
+- eBird returns observation data, not static species info
+- Update any code expecting nuthatch's data structure
+
+### Rollback Instructions
+
+To switch back to nuthatch:
+
+1. Stop eBird server
+2. Revert `.env` variables to nuthatch
+3. Update `mcp_clients.py` back to nuthatch
+4. Revert `subagent_config.py` tool names
+5. Restart with `python nuthatch_tools.py`
+
+---
+
+## 📋 Overview
+
+This server provides 7 powerful tools for discovering and analyzing bird data:
+
+1. **search_species** - Find bird species by common or scientific name
+2. **get_recent_sightings_nearby** - Find recent observations of a specific species near a location
+3. **find_hotspots_nearby** - Discover popular birding locations
+4. **get_location_birds** - See all birds currently being reported at a location
+5. **get_species_info** - Get detailed taxonomy information about a species
+6. **get_notable_sightings** - Find rare or unusual birds in a region
+7. **analyze_location** - Comprehensive location analysis (combines all data)
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+```bash
+# Install dependencies
+pip install fastmcp requests python-dotenv
+
+# Set up environment variables
+echo "EBIRD_API_KEY=your-key-here" > .env
+```
+
+Get your eBird API key: https://ebird.org/api/keygen
+
+### Transport Options
+
+The server supports **two MCP-compliant transport modes**:
+
+#### Option 1: Stdio Transport (Default)
+**Best for:** LangGraph agents, subprocess communication, CLI usage
+
+```bash
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+python ebird_tools.py
+```
+
+**Features:**
+- ✅ Full MCP protocol via stdin/stdout
+- ✅ Managed by FastMCP's StdioTransport
+- ✅ Perfect for agent-to-agent communication
+- ✅ No HTTP overhead, fastest performance
+- ✅ Subprocess lifecycle managed automatically
+
+**Use when:**
+- Building LangGraph agents that need MCP tools
+- Integrating with Claude Desktop or other MCP clients
+- Running as a subprocess from Python code
+
+#### Option 2: Streamable-HTTP Transport
+**Best for:** Gradio dashboards, web clients, HuggingFace Spaces
+
+```bash
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+python ebird_tools.py --http --port 8000
+```
+
+Server will start on `http://localhost:8000`
+
+**Features:**
+- ✅ Full MCP protocol over HTTP at `/mcp` endpoint
+- ✅ Managed by FastMCP's built-in HTTP server
+- ✅ Perfect for web-based UIs like Gradio
+- ✅ Can be deployed to HuggingFace Spaces
+- ✅ Cross-platform, language-agnostic access
+
+**Use when:**
+- Building Gradio dashboards
+- Deploying to HuggingFace Spaces
+- Need HTTP-based access to MCP tools
+- Connecting from web clients
+
+#### Option 3: Direct HTTP Endpoints (Non-MCP)
+**Best for:** Quick testing, direct API access without MCP protocol
+
+```bash
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+python run_ebird_http.py
+```
+
+Server will start on `http://localhost:8000`
+
+**Available Endpoints:**
+- `GET  /health` - Health check
+- `GET  /tools` - List available tools
+- `POST /tools/{tool_name}` - Call a specific tool (bypasses MCP)
+
+**Note:** This bypasses MCP protocol and calls functions directly. Use Options 1 or 2 for hackathon compliance.
+
+## 📚 Tool Documentation
+
+### Tool 1: search_species
+
+Find bird species by name.
+
+**Input:**
+```python
+search_species(
+    search_term: str,      # "cardinal", "blue jay", etc.
+    max_results: int = 10  # How many results to return
+)
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:8000/tools/search_species \
+  -H "Content-Type: application/json" \
+  -d '{"search_term": "cardinal", "max_results": 5}'
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": [
+    {
+      "common_name": "Northern Cardinal",
+      "scientific_name": "Cardinalis cardinalis",
+      "species_code": "norcar",
+      "family": "Cardinals and Allies",
+      "order": "Passeriformes"
+    }
+  ],
+  "count": 1,
+  "search_term": "cardinal"
+}
+```
+
+**Use Cases:**
+- User enters a bird name → get species code
+- Bird classifier returns "Northern Cardinal" → get species code
+- Resolve names to codes for other tools
+
+---
+
+### Tool 2: get_recent_sightings_nearby
+
+Find recent observations of a species near a location.
+
+**Input:**
+```python
+get_recent_sightings_nearby(
+    species_code: str,       # "norcar", "blueja", etc.
+    latitude: float,         # 40.7829
+    longitude: float,        # -73.9654
+    radius_km: int = 50,     # Search radius
+    max_results: int = 10    # How many results to return
+)
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:8000/tools/get_recent_sightings_nearby \
+  -H "Content-Type: application/json" \
+  -d '{
+    "species_code": "norcar",
+    "latitude": 40.7829,
+    "longitude": -73.9654,
+    "radius_km": 25,
+    "max_results": 10
+  }'
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": [
+    {
+      "common_name": "Northern Cardinal",
+      "scientific_name": "Cardinalis cardinalis",
+      "location": "Central Park",
+      "location_id": "L12345",
+      "date": "2025-11-22 14:30",
+      "count": 2,
+      "latitude": 40.7829,
+      "longitude": -73.9654
+    }
+  ],
+  "count": 5,
+  "location": {"lat": 40.7829, "lng": -73.9654},
+  "radius_km": 25
+}
+```
+
+**Use Cases:**
+- After classifying a bird image, find where else it's been seen recently
+- Explore local species distribution
+- Plan birding trips based on recent sightings
+
+---
+
+### Tool 3: find_hotspots_nearby
+
+Discover popular birding locations near coordinates.
+
+**Input:**
+```python
+find_hotspots_nearby(
+    latitude: float,
+    longitude: float,
+    radius_km: int = 50,
+    max_results: int = 15
+)
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:8000/tools/find_hotspots_nearby \
+  -H "Content-Type: application/json" \
+  -d '{
+    "latitude": 40.7829,
+    "longitude": -73.9654,
+    "radius_km": 25,
+    "max_results": 10
+  }'
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": [
+    {
+      "name": "Central Park",
+      "location_id": "L123",
+      "latitude": 40.7829,
+      "longitude": -73.9654,
+      "species_recorded": 237,
+      "latest_obs_date": "2025-11-22 15:45"
+    }
+  ],
+  "count": 3,
+  "location": {"lat": 40.7829, "lng": -73.9654},
+  "radius_km": 25
+}
+```
+
+**Use Cases:**
+- Find popular birding locations near user
+- Discover new places to go birdwatching
+- See historical bird diversity at hotspots
+
+---
+
+### Tool 4: get_location_birds
+
+See ALL birds currently being reported at a location.
+
+**Input:**
+```python
+get_location_birds(
+    latitude: float,
+    longitude: float,
+    radius_km: int = 50,
+    max_results: int = 50
+)
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:8000/tools/get_location_birds \
+  -H "Content-Type: application/json" \
+  -d '{
+    "latitude": 40.7829,
+    "longitude": -73.9654,
+    "radius_km": 5,
+    "max_results": 50
+  }'
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": [
+    {
+      "common_name": "Canada Goose",
+      "scientific_name": "Branta canadensis",
+      "species_code": "cangoo",
+      "location": "Central Park - Reservoir",
+      "date": "2025-11-22 14:30",
+      "count": 12,
+      "latitude": 40.7829,
+      "longitude": -73.9654
+    }
+  ],
+  "count": 20,
+  "unique_species": 12,
+  "location": {"lat": 40.7829, "lng": -73.9654},
+  "top_birds": [
+    {"species": "Canada Goose", "observations": 5},
+    {"species": "American Robin", "observations": 3}
+  ]
+}
+```
+
+**Use Cases:**
+- Explore all bird activity in an area
+- See what's being seen right now
+- Get overview of biodiversity at a location
+
+---
+
+### Tool 5: get_species_info
+
+Get detailed taxonomy and metadata for a species.
+
+**Input:**
+```python
+get_species_info(
+    species_code: str  # "norcar", "blueja", etc.
+)
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:8000/tools/get_species_info \
+  -H "Content-Type: application/json" \
+  -d '{"species_code": "norcar"}'
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": {
+    "common_name": "Northern Cardinal",
+    "scientific_name": "Cardinalis cardinalis",
+    "species_code": "norcar",
+    "family": "Cardinals and Allies",
+    "family_sci_name": "Cardinalidae",
+    "order": "Passeriformes",
+    "category": "species"
+  },
+  "species_code": "norcar"
+}
+```
+
+**Use Cases:**
+- Get scientific name for a bird
+- Understand taxonomic classification
+- Enrich bird data with metadata
+
+---
+
+### Tool 6: get_notable_sightings
+
+Find rare or unusual birds recently reported in a region.
+
+**Input:**
+```python
+get_notable_sightings(
+    region_code: str = "US",  # "US", "US-NY", "CA-ON", etc.
+    max_results: int = 10
+)
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:8000/tools/get_notable_sightings \
+  -H "Content-Type: application/json" \
+  -d '{"region_code": "US-NY", "max_results": 10}'
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": [
+    {
+      "common_name": "Tufted Puffin",
+      "scientific_name": "Fratercula cirrhata",
+      "species_code": "tufpuf",
+      "location": "Jones Beach",
+      "location_id": "L456",
+      "date": "2025-11-20 10:30",
+      "count": 1,
+      "latitude": 40.5891,
+      "longitude": -72.7868
+    }
+  ],
+  "count": 3,
+  "region_code": "US-NY"
+}
+```
+
+**Use Cases:**
+- Discover rare birds in a region
+- Find exciting sighting opportunities
+- Monitor unusual bird movements
+
+---
+
+### Tool 7: analyze_location
+
+Comprehensive analysis combining all bird data for a location.
+
+**Input:**
+```python
+analyze_location(
+    latitude: float,
+    longitude: float,
+    radius_km: int = 50
+)
+```
+
+**Example:**
+```bash
+curl -X POST http://localhost:8000/tools/analyze_location \
+  -H "Content-Type: application/json" \
+  -d '{
+    "latitude": 40.7829,
+    "longitude": -73.9654,
+    "radius_km": 5
+  }'
+```
+
+**Response:**
+```json
+{
+  "status": "success",
+  "data": {
+    "location": {
+      "latitude": 40.7829,
+      "longitude": -73.9654,
+      "radius_km": 5
+    },
+    "sightings": [...],
+    "hotspots": [...],
+    "summary": {
+      "total_sightings": 42,
+      "unique_species": 18,
+      "total_hotspots": 3,
+      "top_species": [
+        {"name": "Canada Goose", "observations": 8},
+        {"name": "American Robin", "observations": 5}
+      ]
+    }
+  }
+}
+```
+
+**Use Cases:**
+- Get complete birding report for a location
+- Plan comprehensive birding trips
+- Understand area biodiversity
+
+## 🧪 Testing
+
+### Comprehensive Test Suite
+
+The test suite validates **all 7 tools** across **3 different modes**:
+
+```bash
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+python test_ebird_mcp.py
+```
+
+**What gets tested:**
+
+1. **Part 1: Direct Python Function Tests** (2 tests)
+   - Validates functions work when called directly
+   - Quick sanity check without MCP overhead
+   - Tests: `search_species`, `find_hotspots_nearby`
+
+2. **Part 2: MCP Stdio Transport Tests** (3 tests)
+   - ✅ **Proper MCP protocol via stdio**
+   - Uses FastMCP's `StdioTransport` client
+   - Validates MCP server works as subprocess
+   - Tests: List tools, call `search_species`, call `find_hotspots_nearby`
+
+3. **Part 3: MCP Streamable-HTTP Transport Tests** (3 tests)
+   - ✅ **Proper MCP protocol via HTTP**
+   - Uses FastMCP's `StreamableHttpTransport` client
+   - Validates MCP server works over HTTP
+   - Tests: List tools, call `search_species`, call `find_hotspots_nearby`
+
+**Expected Output:**
+```
+🦅 eBird MCP Server - Comprehensive Test Suite
+══════════════════════════════════════════════════════════════════════
+
+PART 1: Direct Python Function Tests (Non-MCP)
+──────────────────────────────────────────────────────────────────────
+✅ Found 3 cardinals
+✅ Found 5 hotspots
+ℹ️  Direct tests: 2/2 passed
+
+PART 2: MCP Stdio Transport Tests
+──────────────────────────────────────────────────────────────────────
+✅ Found all 7 MCP tools
+✅ MCP call successful: Found 3 species
+✅ MCP call successful: Found 3 hotspots
+ℹ️  MCP stdio tests: 3/3 passed
+
+PART 3: MCP Streamable-HTTP Transport Tests
+──────────────────────────────────────────────────────────────────────
+✅ Found all 7 MCP tools via HTTP
+✅ MCP HTTP call successful: Found 3 species
+✅ MCP HTTP call successful: Found 3 hotspots
+ℹ️  MCP HTTP tests: 3/3 passed
+
+Final Test Summary
+══════════════════════════════════════════════════════════════════════
+Total Passed: 8/8
+  Direct tests:     2/2
+  MCP stdio tests:  3/3
+  MCP HTTP tests:   3/3
+
+✅ All tests passed! ✨
+ℹ️  Your MCP server is fully functional for the hackathon! 🎉
+```
+
+**Test Options:**
+```bash
+# Run all tests (default)
+python test_ebird_mcp.py
+
+# Skip direct function tests
+python test_ebird_mcp.py --skip-direct
+
+# Skip stdio MCP tests
+python test_ebird_mcp.py --skip-stdio
+
+# Skip HTTP MCP tests
+python test_ebird_mcp.py --skip-http
+
+# Run only MCP protocol tests
+python test_ebird_mcp.py --skip-direct
+```
+
+**Why this matters for the hackathon:**
+- ✅ Validates proper MCP protocol usage (required for Track 2)
+- ✅ Tests both stdio and HTTP transports
+- ✅ Ensures compatibility with MCP clients
+- ✅ Proves tools work in real-world scenarios
+
+## 🔗 Integration Points
+
+### With LangGraph Agent (Phase 3) - RECOMMENDED
+
+**Use MCP Stdio Transport for proper protocol compliance:**
+
+```python
+from fastmcp.client import Client
+from fastmcp.client.transports import StdioTransport
+
+# Create MCP client with stdio transport
+transport = StdioTransport(
+    command="python",
+    args=["ebird_tools.py"]
+)
+client = Client(transport)
+
+# Use in async context
+async with client:
+    # List available tools
+    tools = await client.list_tools()
+    print(f"Available tools: {[t.name for t in tools]}")
+
+    # Call a tool
+    result = await client.call_tool(
+        "search_species",
+        arguments={"search_term": "cardinal", "max_results": 5}
+    )
+
+    # Parse response
+    import json
+    data = json.loads(result.content[0].text)
+    print(f"Found {data['count']} species")
+```
+
+**Why use stdio for agents:**
+- ✅ Proper MCP protocol (required for hackathon Track 2)
+- ✅ StdioTransport manages subprocess lifecycle
+- ✅ No HTTP overhead
+- ✅ Best for agent-to-agent communication
+
+### With Gradio Dashboard (Phase 4)
+
+**Option 1: Use MCP Streamable-HTTP Transport (RECOMMENDED)**
+
+```python
+from fastmcp.client import Client
+from fastmcp.client.transports import StreamableHttpTransport
+import asyncio
+import json
+
+async def call_ebird_tool(tool_name: str, params: dict):
+    """Call eBird MCP tool via proper MCP protocol."""
+    transport = StreamableHttpTransport(url="http://localhost:8000/mcp")
+    client = Client(transport)
+
+    async with client:
+        result = await client.call_tool(tool_name, arguments=params)
+        data = json.loads(result.content[0].text)
+        return data
+
+# Use in Gradio
+def gradio_search_birds(search_term: str):
+    """Gradio callback function."""
+    result = asyncio.run(call_ebird_tool(
+        "search_species",
+        {"search_term": search_term, "max_results": 10}
+    ))
+    return result
+```
+
+**Option 2: Direct HTTP calls (Non-MCP, for quick testing)**
+
+```python
+import requests
+
+# Start server with: python run_ebird_http.py
+response = requests.post(
+    "http://localhost:8000/tools/search_species",
+    json={"search_term": "cardinal", "max_results": 10}
+)
+result = response.json()
+```
+
+**Note:** Option 2 bypasses MCP protocol. Use Option 1 for hackathon compliance.
+
+### With Claude Desktop or Other MCP Clients
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ebird": {
+      "command": "python",
+      "args": ["/Users/jacobbinder/Desktop/hackathon/hackathon_draft/ebird_tools.py"]
+    }
+  }
+}
+```
+
+Claude Desktop will connect via stdio transport and have access to all 7 tools.
+
+## 📊 Performance
+
+| Tool | Time | Notes |
+|------|------|-------|
+| search_species | 1-2s | Full taxonomy lookup |
+| get_recent_sightings_nearby | 1-2s | API call |
+| find_hotspots_nearby | 1-2s | API call |
+| get_location_birds | 1-2s | API call |
+| get_species_info | 0.5-1s | Taxonomy lookup |
+| get_notable_sightings | 1-2s | API call |
+| analyze_location | 3-5s | Multiple API calls |
+
+**Target response time:** 5-10 seconds for agent queries
+
+## 🛠️ Troubleshooting
+
+### "EBIRD_API_KEY not found"
+```bash
+# Make sure .env file has your API key
+echo "EBIRD_API_KEY=your-actual-key" > /Users/jacobbinder/Desktop/hackathon/hackathon_draft/.env
+```
+
+### "Connection error"
+Check internet connection and eBird API status
+
+### "Tool not found" (HTTP)
+Ensure tool name matches exactly (lowercase with underscores)
+
+### Rate limiting
+Server automatically enforces 100ms delay between API calls
+
+## 📝 Architecture
+
+```
+┌─────────────────────────────────┐
+│   eBird MCP Server              │
+│  (ebird_tools.py)               │
+├─────────────────────────────────┤
+│ 7 Tools (all return JSON)       │
+├─────────────────────────────────┤
+│ Transport Layer (choosable)      │
+├──────────────────┬──────────────┤
+│  Stdio (CLI)     │  HTTP (Web)  │
+├──────────────────┼──────────────┤
+│  stdio transport │ FastAPI app  │
+│  (subprocess)    │ (Uvicorn)    │
+└──────────────────┴──────────────┘
+         ↓                ↓
+    LangGraph        Gradio
+    Agent           Dashboard
+```
+
+## 📦 Files
+
+- **`ebird_tools.py`** (800+ lines) - Main MCP server with dual transport support
+  - Run as stdio: `python ebird_tools.py`
+  - Run as HTTP: `python ebird_tools.py --http --port 8000`
+  - Uses FastMCP's built-in transport system
+
+- **`run_ebird_http.py`** (150 lines) - Direct HTTP wrapper (non-MCP)
+  - Bypasses MCP protocol for quick testing
+  - Exposes `/tools/{tool_name}` endpoints
+  - Use for dashboard building when MCP overhead not needed
+
+- **`test_ebird_mcp.py`** (470+ lines) - Comprehensive test suite
+  - Tests 3 modes: Direct, Stdio MCP, HTTP MCP
+  - Validates proper MCP protocol compliance
+  - 8 total tests with colored output
+
+- **`EBIRD_MCP_README.md`** - This file (complete documentation)
+- **`QUICK_START.md`** - Quick reference guide
+- **`PHASE2_SUMMARY.md`** - Implementation summary
+
+## ✨ Next Steps
+
+1. ✅ **Phase 2: eBird MCP Server (COMPLETE)**
+   - ✅ 7 tools implemented
+   - ✅ Dual transport support (stdio + streamable-http)
+   - ✅ Full MCP protocol compliance
+   - ✅ Comprehensive test suite (8/8 passing)
+   - ✅ Ready for hackathon Track 2
+
+2. ⏳ **Phase 3: LangGraph Agent**
+   - Connect both MCP servers (bird classifier + eBird data)
+   - Use stdio transport for agent-to-agent communication
+   - Build reasoning chains combining image classification + location data
+
+3. ⏳ **Phase 4: Gradio Dashboard**
+   - Use streamable-http transport for UI integration
+   - Dual interface: Chat with agent + Direct tool access
+   - Deploy to HuggingFace Spaces
+
+4. ⏳ **Phase 5: Submission**
+   - Tag with `mcp-in-action-track-consumer` or appropriate category
+   - Add demo video showing MCP protocol usage
+   - Add social media post link
+
+## 📄 License
+
+Part of BirdScope AI hackathon submission
+
+## 🤝 Support
+
+For issues, check:
+1. `.env` file has valid EBIRD_API_KEY
+2. Internet connection is working
+3. eBird API status (https://ebird.org)
+4. Test suite results: `python test_ebird_mcp.py`

examples/b64_helper.py

@@ -0,0 +1,33 @@
+import base64
+from PIL import Image
+from io import BytesIO
+
+# Load and optimize image
+image = Image.open("examples/blue_jay.jpg")
+
+# Resize if too large (max 800px on longest side)
+max_size = 800
+if max(image.size) > max_size:
+    ratio = max_size / max(image.size)
+    new_size = tuple(int(dim * ratio) for dim in image.size)
+    image = image.resize(new_size, Image.Resampling.LANCZOS)
+
+# Convert to JPEG with compression
+buffer = BytesIO()
+image.convert("RGB").save(buffer, format="JPEG", quality=85, optimize=True)
+image_bytes = buffer.getvalue()
+
+# Encode to base64
+image_base64 = base64.b64encode(image_bytes).decode()
+
+# Print full base64 for copying
+print("Full base64 string:")
+print(image_base64)
+
+# Also save to file for easy copying
+with open("examples/blue_jay_base64.txt", "w") as out:
+    out.write(image_base64)
+
+print(f"\n✅ Saved to examples/blue_jay_base64.txt")
+print(f"📏 Size: {len(image_base64)} characters")
+print(f"📦 Optimized payload: ~{len(image_base64) // 1024}KB")

langgraph.json

@@ -0,0 +1,8 @@
+{
+    "$schema": "https://langgra.ph/schema.json",
+    "dependencies": ["."],
+    "graphs": {
+        "bird_agent": "./agent/graph.py:graph"
+    },
+    "env": ".env"
+}

langgraph_agent/__init__.py

@@ -0,0 +1,21 @@
+"""
+LangGraph Bird Classification Agents
+
+Simple, modular agents for bird identification using MCP servers.
+"""
+
+from .config import AgentConfig
+from .agents import AgentFactory
+from .mcp_clients import MCPClientManager
+from .prompts import get_prompt_for_agent_type, BIRDSCOPE_AI_PROMPT, NUTHATCH_BIRDSCOPE_PROMPT
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AgentConfig",
+    "AgentFactory",
+    "MCPClientManager",
+    "get_prompt_for_agent_type",
+    "BIRDSCOPE_AI_PROMPT",
+    "NUTHATCH_BIRDSCOPE_PROMPT"
+]

langgraph_agent/__main__.py

@@ -0,0 +1,8 @@
+"""
+Entry point for running langgraph_agent as a module.
+Allows: python -m langgraph_agent [command]
+"""
+from .main import main
+
+if __name__ == "__main__":
+    main()

langgraph_agent/agents.py

@@ -0,0 +1,100 @@
+"""
+Agent creation and configuration.
+
+Unified agent factory using subagent architecture for all modes.
+"""
+from langchain_openai import ChatOpenAI
+
+from .config import AgentConfig
+from .mcp_clients import MCPClientManager
+
+
+class AgentFactory:
+    """Factory for creating agents using unified subagent architecture."""
+
+    @staticmethod
+    async def create_subagent_orchestrator(
+        model: str,
+        api_key: str,
+        provider: str,
+        mode: str = "Single Agent (All Tools)"
+    ):
+        """
+        Create agent using subagent architecture (always uses subagent system).
+
+        Args:
+            model: LLM model name
+            api_key: API key for the provider
+            provider: LLM provider ("openai" or "huggingface")
+            mode: Agent mode (e.g., "Single Agent (All Tools)", "Specialized Subagents (3 Specialists)")
+
+        Returns:
+            Configured agent (single subagent or router workflow)
+        """
+        from .subagent_config import SubAgentConfig
+        from .subagent_supervisor import create_supervisor_workflow
+        from .subagent_factory import SubAgentFactory
+        from langchain_openai import ChatOpenAI
+        from langchain_anthropic import ChatAnthropic
+
+        # Get mode configuration
+        mode_config = SubAgentConfig.get_mode_config(mode)
+        print(f"[AGENT]: Creating agent in '{mode}' mode")
+
+        # Create LLM based on provider
+        if provider == "huggingface":
+            llm = ChatOpenAI(
+                base_url="https://router.huggingface.co/v1",
+                api_key=api_key,
+                model=model,
+                temperature=AgentConfig.HF_TEMPERATURE,
+                streaming=True
+            )
+        elif provider == "anthropic": 
+            llm = ChatAnthropic(
+                model=model,
+                api_key=api_key,
+                temperature=AgentConfig.ANTHROPIC_TEMPERATURE,
+                streaming=True
+            )
+        else:  # openai
+            llm = ChatOpenAI(
+                model=model,
+                api_key=api_key,
+                temperature=AgentConfig.OPENAI_TEMPERATURE,
+                streaming=True
+            )
+
+        # Get all MCP tools
+        client = await MCPClientManager.create_multi_server_client()
+        tools = await MCPClientManager.get_tools(client)
+
+        # Create agent based on mode
+        if mode_config["use_router"]:
+            # Multi-agent mode: create router with specialists
+            print(f"[AGENT]: Creating supervisor with subagents: {mode_config['subagents']}")
+            workflow = await create_supervisor_workflow(tools, llm)
+            return workflow
+        else:
+            # Single agent mode: create one subagent directly
+            subagent_name = mode_config["subagents"][0]
+            print(f"[AGENT]: Creating single subagent: {subagent_name}")
+
+            # Create agent with memory for streaming support
+            from langchain.agents import create_agent
+            from langgraph.checkpoint.memory import InMemorySaver
+
+            # create_agent auto-compiles, so pass checkpointer and name directly
+            # Filter tools based on subagent configuration
+            subagent_tools = SubAgentConfig.get_subagent_definitions()["generalist"]["tools"]
+            filtered_tools = [tool for tool in tools if tool.name in subagent_tools]
+            print(f"[AGENT]: Filtered {len(filtered_tools)} tools for {subagent_name}: {[t.name for t in filtered_tools]}")
+
+            agent = create_agent(
+                model=llm,
+                tools=filtered_tools,
+                system_prompt=SubAgentConfig.get_subagent_definitions()["generalist"]["prompt"],
+                checkpointer=InMemorySaver(),
+                name=subagent_name
+            )
+            return agent

langgraph_agent/agents.py.legacy

@@ -0,0 +1,366 @@
+"""
+Agent creation and configuration.
+"""
+from typing import Optional
+from langchain.agents import create_agent
+from langchain_openai import ChatOpenAI
+from langgraph.checkpoint.memory import InMemorySaver
+
+from .config import AgentConfig
+from .prompts import get_prompt_for_agent_type, NUTHATCH_BIRDSCOPE_PROMPT
+from .mcp_clients import MCPClientManager
+
+
+class AgentFactory:
+    """Factory for creating different types of bird classification agents."""
+    
+    @staticmethod
+    async def create_classifier_agent(
+        model_name: Optional[str] = None,
+        temperature: Optional[float] = None,
+        with_memory: bool = False
+    ):
+        """
+        Create a basic bird classifier agent (Modal only).
+
+        Args:
+            model_name: LLM model to use (defaults to config)
+            temperature: Model temperature (defaults to config)
+            with_memory: Enable conversation memory
+
+        Returns:
+            Configured LangGraph agent
+        """
+        # Validate config
+        AgentConfig.validate()
+
+        # Create MCP client
+        client = await MCPClientManager.create_classifier_client()
+        tools = await MCPClientManager.get_tools(client)
+
+        # Create model
+        model = ChatOpenAI(
+            model=model_name or AgentConfig.DEFAULT_MODEL,
+            temperature=temperature if temperature is not None else AgentConfig.OPENAI_TEMPERATURE
+        )
+        
+        # Get system prompt
+        system_prompt = get_prompt_for_agent_type("classifier")
+        
+        # Create agent
+        agent_kwargs = {
+            "model": model,
+            "tools": tools,
+            "system_prompt": system_prompt
+        }
+        
+        # Add memory if requested
+        if with_memory:
+            agent_kwargs["checkpointer"] = InMemorySaver()
+        
+        print("[STATUS]: Creating LangGraph agent...")
+        agent = create_agent(**agent_kwargs)
+        
+        print("[SUCCESS]: Agent ready!\n")
+        return agent
+    
+    @staticmethod
+    async def create_multi_server_agent(
+        model_name: Optional[str] = None,
+        temperature: Optional[float] = None,
+        with_memory: bool = True  # Memory recommended for multi-server
+    ):
+        """
+        Create agent with both Modal classifier and eBird tools.
+
+        Args:
+            model_name: LLM model to use (defaults to config)
+            temperature: Model temperature (defaults to config)
+            with_memory: Enable conversation memory (default: True)
+
+        Returns:
+            Configured LangGraph agent with all tools
+        """
+        # Validate config
+        AgentConfig.validate()
+
+        # Create MCP client with both servers
+        client = await MCPClientManager.create_multi_server_client()
+        tools = await MCPClientManager.get_tools(client)
+
+        # Create model
+        model = ChatOpenAI(
+            model=model_name or AgentConfig.DEFAULT_MODEL,
+            temperature=temperature if temperature is not None else AgentConfig.OPENAI_TEMPERATURE
+        )
+        
+        # Get system prompt
+        system_prompt = get_prompt_for_agent_type("multi_server")
+        
+        # Create agent
+        agent_kwargs = {
+            "model": model,
+            "tools": tools,
+            "system_prompt": system_prompt
+        }
+        
+        # Add memory
+        if with_memory:
+            agent_kwargs["checkpointer"] = InMemorySaver()
+        
+        print("[STATUS]: Creating multi-server LangGraph agent...")
+        agent = create_agent(**agent_kwargs)
+
+        print("[SUCCESS]: Agent ready with all tools!\n")
+        return agent
+
+    @staticmethod
+    async def create_streaming_agent(
+        model_name: Optional[str] = None,
+        temperature: Optional[float] = None,
+        system_prompt: Optional[str] = None,
+        with_memory: bool = True
+    ):
+        """
+        Create streaming multi-server agent with custom system prompt.
+
+        Args:
+            model_name: LLM model (default: gpt-4o-mini)
+            temperature: Sampling temperature (default: 0)
+            system_prompt: Custom system message
+            with_memory: Enable conversation memory
+        """
+        print("[STATUS]: Creating streaming agent...")
+
+        # Use defaults if not provided
+        model_name = model_name or AgentConfig.DEFAULT_MODEL
+        temperature = temperature if temperature is not None else AgentConfig.OPENAI_TEMPERATURE
+
+        # Default system prompt if none provided
+        if system_prompt is None:
+            system_prompt = """You are an expert bird identification assistant with access to:
+2. **Bird Classifier** - Identify birds from images with high accuracy
+2. **eBird Database** - Find recent sightings, hotspots, and species info
+
+**Your capabilities:**
+- Classify bird images and provide confidence scores
+- Find where birds have been spotted recently
+- Recommend birding locations
+- Answer questions about bird species and habitats
+
+**Response style:**
+- Be enthusiastic and educational
+- Always cite confidence scores for identifications
+- Provide actionable location recommendations
+- Format responses clearly with markdown
+
+Let's explore the amazing world of bids together!
+
+        """
+        # Connect to both MCP servers
+        client = await MCPClientManager.create_multi_server_client()
+        tools = await MCPClientManager.get_tools(client)  
+        
+        # Create LLM with streaming enabled (this is default)
+        model = ChatOpenAI(
+            model=model_name,
+            temperature=temperature,
+            streaming=True,  # <- Key for token streaming!
+        )
+
+        # Create agent with custom prompt
+        agent_kwargs = {
+            "model": model,
+            "tools": tools,
+            "system_prompt": system_prompt
+        }
+
+        # Add memory
+        if with_memory:
+            agent_kwargs["checkpointer"] = InMemorySaver()
+
+        print("[STATUS]: Creating LangGraph agent with streaming...")
+        agent = create_agent(**agent_kwargs)
+
+        print("[SUCCESS]: Streaming agent ready!\n")
+        return agent
+
+    @staticmethod
+    async def create_streaming_agent_with_openai(
+        model: str = "gpt-4o-mini",
+        openai_key: str = None,
+        temperature: Optional[float] = None,
+        system_prompt: Optional[str] = None,
+        with_memory: bool = True
+    ):
+        """
+        Create streaming agent with OpenAI LLM using user-provided API key.
+
+        Args:
+            model: OpenAI model name (e.g., "gpt-4o-mini", "gpt-4o")
+            openai_key: User's OpenAI key (required)
+            temperature: Sampling temperature (0-2), defaults to config
+            system_prompt: Custom system prompt
+            with_memory: Enable conversation memory
+
+        Returns:
+            LangGraph agent with OpenAI LLM and MCP tools
+        """
+        # Step 1: Validate that we have a key
+        if not openai_key:
+            raise ValueError("OpenAI key is required")
+
+        print(f"[AGENT] Creating OpenAI agent with model: {model}")
+
+        # Step 2: Get MCP tools
+        client = await MCPClientManager.create_multi_server_client()
+        tools = await MCPClientManager.get_tools(client)
+
+        # Step 3: Create OpenAI LLM with USER'S key (not from .env)
+        llm = ChatOpenAI(
+            model=model,
+            api_key=openai_key, # <- KEY DIFFERENCE: explicit api_key parameter
+            temperature=temperature if temperature is not None else AgentConfig.OPENAI_TEMPERATURE,
+            streaming=True
+        )
+
+        # Step 4: Build agent
+        agent_kwargs = {
+            "model": llm,
+            "tools": tools,
+            "system_prompt": system_prompt or "You are a helpful AI assistant."
+        }
+
+        if with_memory:
+            agent_kwargs["checkpointer"] = InMemorySaver()
+
+        agent = create_agent(**agent_kwargs)
+        return agent
+
+    @staticmethod
+    async def create_streaming_agent_with_hf(
+        model: str = "meta-llama/Llama-3.1-8B-Instruct",
+        hf_token: str = None,
+        temperature: Optional[float] = None,
+        system_prompt: Optional[str] = None,
+        with_memory: bool = True
+    ):
+        """
+        Create streaming agent with HuggingFace Inference Providers.
+
+        Uses HF's OpenAI-compatible router endpoint for full tool calling support.
+
+        Args:
+            model: HF model repo ID (e.g., "meta-llama/Llama-3.1-8B-Instruct")
+            hf_token: User's HF API token (required)
+            temperature: Sampling temperature (0-1), defaults to config
+            system_prompt: Custom system prompt
+            with_memory: Enable conversation memory
+
+        Returns:
+            LangGraph agent with HF LLM and MCP tools
+        """
+        # Step 1: Validate that we have a token
+        if not hf_token:
+            raise ValueError("HuggingFace token is required")
+
+        print(f"[AGENT] Creating HuggingFace agent with model: {model}")
+
+        # Step 2: Get MCP tools (same as before)
+        client = await MCPClientManager.create_multi_server_client()
+        tools = await MCPClientManager.get_tools(client)
+
+        # Step 3: Create HuggingFace LLM using Inference Providers router
+        # This uses HF's OpenAI-compatible endpoint with full tool calling support
+        llm = ChatOpenAI(
+            base_url="https://router.huggingface.co/v1",
+            api_key=hf_token,
+            model=model,
+            temperature=temperature if temperature is not None else AgentConfig.HF_TEMPERATURE,
+            streaming=True
+        )
+
+        # Step 4: Build agent (same structure as OpenAI version)
+        agent_kwargs = {
+            "model": llm,
+            "tools": tools,
+            "system_prompt": system_prompt or "You are a helpful AI assistant."
+        }
+
+        if with_memory:
+            agent_kwargs["checkpointer"] = InMemorySaver()
+
+        agent = create_agent(**agent_kwargs)
+        return agent
+
+    @staticmethod
+    async def create_subagent_orchestrator(
+        model: str,
+        api_key: str,
+        provider: str,
+        mode: str = "Single Agent (All Tools)"
+    ):
+        """
+        Create agent using subagent architecture (always uses subagent system).
+
+        Args:
+            model: LLM model name
+            api_key: API key for the provider
+            provider: LLM provider ("openai" or "huggingface")
+            mode: Agent mode (e.g., "Single Agent (All Tools)", "Specialized Subagents (3 Specialists)")
+
+        Returns:
+            Configured agent (single subagent or router workflow)
+        """
+        from .subagent_config import SubAgentConfig
+        from .subagent_router import create_router_agent
+        from .subagent_factory import SubAgentFactory
+        from langchain_openai import ChatOpenAI
+
+        # Get mode configuration
+        mode_config = SubAgentConfig.get_mode_config(mode)
+        print(f"[AGENT]: Creating agent in '{mode}' mode")
+
+        # Create LLM based on provider
+        if provider == "huggingface":
+            llm = ChatOpenAI(
+                base_url="https://router.huggingface.co/v1",
+                api_key=api_key,
+                model=model,
+                temperature=AgentConfig.HF_TEMPERATURE,
+                streaming=True
+            )
+        else:  # openai
+            llm = ChatOpenAI(
+                model=model,
+                api_key=api_key,
+                temperature=AgentConfig.OPENAI_TEMPERATURE,
+                streaming=True
+            )
+
+        # Get all MCP tools
+        client = await MCPClientManager.create_multi_server_client()
+        tools = await MCPClientManager.get_tools(client)
+
+        # Create agent based on mode
+        if mode_config["use_router"]:
+            # Multi-agent mode: create router with specialists
+            print(f"[AGENT]: Creating router with subagents: {mode_config['subagents']}")
+            workflow = await create_router_agent(tools, llm)
+            return workflow
+        else:
+            # Single agent mode: create one subagent directly
+            subagent_name = mode_config["subagents"][0]
+            print(f"[AGENT]: Creating single subagent: {subagent_name}")
+            agent = await SubAgentFactory.create_subagent(subagent_name, tools, llm)
+            return agent
+        
+# Convenience functions (backwards compatible)
+async def create_bird_agent(**kwargs):
+    """Create basic classifier agent. Alias for backwards compatibility."""
+    return await AgentFactory.create_classifier_agent(**kwargs)
+
+
+async def create_multi_agent(**kwargs):
+    """Create multi-server agent. Alias for convenience."""
+    return await AgentFactory.create_multi_server_agent(**kwargs)

langgraph_agent/agents_README.md

@@ -0,0 +1,1195 @@
+# LangGraph Bird Classification Agent - Complete Guide
+
+**A beginner-friendly guide to setting up and using the bird classification agent system.**
+
+---
+
+## Table of Contents
+
+> **🚀 First time here?** Start with [Installation](#installation) → [Configuration](#configuration) → [CLI Commands](#cli-commands)
+> **🐦 Want interactive chat?** Jump to [eBird Server Setup](#ebird-server-setup)
+
+1. [What is This?](#what-is-this)
+2. [Prerequisites](#prerequisites)
+3. [Installation](#installation)
+4. [Configuration](#configuration)
+5. [Usage Guide](#usage-guide)
+6. [eBird Server Setup](#ebird-server-setup) ⭐ **Important for interactive mode**
+7. [CLI Commands](#cli-commands)
+8. [Programmatic Usage](#programmatic-usage)
+9. [Advanced Configuration](#advanced-configuration)
+10. [Troubleshooting](#troubleshooting)
+11. [Testing](#testing)
+12. [Examples](#examples)
+
+---
+
+## What is This?
+
+This is an intelligent AI agent that can:
+- **Identify birds** from images (via URLs or uploads)
+- **Answer questions** about bird species
+- **Find bird sightings** near locations (when connected to eBird server)
+- **Recommend birding hotspots**
+- **Hold conversations** with memory of previous messages
+
+**Technology Stack:**
+- **LangGraph:** Agent framework
+- **LangChain:** LLM integration
+- **MCP (Model Context Protocol):** Tool integration
+- **Modal:** GPU-powered bird classifier
+- **OpenAI GPT:** Agent reasoning
+
+---
+
+## Prerequisites
+
+### Required
+
+1. **Python 3.11+**
+   ```bash
+   python --version  # Should be 3.11 or higher
+   ```
+
+2. **Virtual Environment** (recommended)
+   ```bash
+   python -m venv .venv-hackathon
+   source .venv-hackathon/bin/activate  # Mac/Linux
+   # or
+   .venv-hackathon\Scripts\activate  # Windows
+   ```
+
+3. **API Keys:**
+   - **OpenAI API Key** (for GPT models) - Get from: https://platform.openai.com/api-keys
+   - **Modal Bird Classifier URL** (from Phase 1 deployment)
+   - **Bird Classifier API Key** (from Modal secrets)
+
+### Optional (for multi-server setup)
+
+4. **eBird API Key** (for bird data) - Get from: https://ebird.org/api/keygen
+5. **eBird MCP Server** running locally or deployed
+
+---
+
+## Installation
+
+### Step 1: Navigate to Directory
+
+```bash
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+```
+
+### Step 2: Activate Virtual Environment
+
+```bash
+source ../.venv-hackathon/bin/activate
+```
+
+### Step 3: Install Dependencies
+
+```bash
+# Install all required packages
+pip install -r langgraph_agent/requirements.txt
+```
+
+**What gets installed:**
+- `langchain` - LLM framework
+- `langchain-openai` - OpenAI integration
+- `langgraph` - Agent framework
+- `langchain-mcp-adapters` - MCP protocol support
+- `fastmcp` - MCP client/server
+- `python-dotenv` - Environment variable management
+
+### Step 4: Verify Installation
+
+```bash
+python -c "from langgraph_agent import AgentFactory; print('✅ Installation successful!')"
+```
+
+If you see `✅ Installation successful!`, you're ready to proceed!
+
+---
+
+## Configuration
+
+### Step 1: Understand the Configuration File
+
+The agent uses `langgraph_agent/config.py` to manage all settings. It reads from environment variables in your `.env` file.
+
+### Step 2: Create/Update .env File
+
+Navigate to the project root:
+```bash
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+```
+
+Edit `.env` file (create if it doesn't exist):
+```bash
+nano .env  # or use your favorite editor
+```
+
+### Step 3: Add Required Variables
+
+**Minimal Configuration (Classifier Only):**
+```bash
+# OpenAI API Key (Required)
+OPENAI_API_KEY=sk-proj-your-openai-api-key-here
+
+# Modal Bird Classifier (Required)
+MODAL_MCP_URL=https://yourname--bird-classifier-mcp-web.modal.run/mcp
+BIRD_CLASSIFIER_API_KEY=your-modal-api-key-here
+
+# Agent Settings (Optional - uses defaults if not set)
+LLM_MODEL=gpt-4o-mini
+LLM_TEMPERATURE=0
+```
+
+**Full Configuration (With eBird Server):**
+```bash
+# OpenAI API Key
+OPENAI_API_KEY=sk-proj-your-openai-api-key-here
+
+# Modal Bird Classifier
+MODAL_MCP_URL=https://yourname--bird-classifier-mcp-web.modal.run/mcp
+BIRD_CLASSIFIER_API_KEY=your-modal-api-key-here
+
+# eBird MCP Server
+EBIRD_MCP_URL=http://localhost:8000/mcp
+EBIRD_USE_STDIO=false
+MCP_API_KEY=your-ebird-mcp-key  # Optional, for production
+
+# eBird API (if running eBird server)
+EBIRD_API_KEY=your-ebird-api-key
+
+# Agent Settings
+LLM_MODEL=gpt-4o-mini
+LLM_TEMPERATURE=0
+AGENT_MAX_ITERATIONS=10
+AGENT_TIMEOUT=120
+```
+
+### Step 4: Save and Verify Configuration
+
+Save the file and verify it loads correctly:
+
+```bash
+python -c "from langgraph_agent import AgentConfig; AgentConfig.validate(); AgentConfig.print_config()"
+```
+
+**Expected Output:**
+```
+======================================================================
+Agent Configuration
+======================================================================
+Modal URL:        https://yourname--bird-classifier-mcp-web.modal.run/mcp
+Modal API Key:    your-modal-api-key...
+eBird URL:        http://localhost:8000/mcp
+eBird Stdio:      False
+LLM Model:        gpt-4o-mini
+Temperature:      0.0
+======================================================================
+```
+
+---
+
+## Usage Guide
+
+### Understanding Agent Types
+
+The system provides **two types of agents**:
+
+> **IMPORTANT FOR BEGINNERS:** The classifier agent (type 1) works immediately after installation. The multi-server agent (type 2) requires the eBird server to be running first. See [eBird Server Setup](#ebird-server-setup) below.
+
+#### 1. Classifier Agent (Simple)
+- **Purpose:** Identify birds from images
+- **Tools:** 2 (classify_from_url, classify_from_base64)
+- **Best for:** Quick bird identification
+- **MCP Servers:** Modal classifier only
+
+#### 2. Multi-Server Agent (Advanced)
+- **Purpose:** Full bird identification + data exploration
+- **Tools:** 9 (2 from Modal + 7 from eBird)
+- **Best for:** Conversational bird exploration
+- **MCP Servers:** Modal classifier + eBird data
+
+---
+
+### Visual Guide: Which Agent Type Do I Use?
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    CLASSIFIER AGENT (Simple)                     │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  What you need:                                                  │
+│  ✅ Modal MCP URL (from Phase 1)                                │
+│  ✅ Modal API Key                                               │
+│  ✅ OpenAI API Key                                              │
+│  ❌ eBird server (NOT needed)                                   │
+│                                                                  │
+│  What it can do:                                                 │
+│  ✅ Identify birds from image URLs                              │
+│  ✅ Identify birds from base64 images                           │
+│  ❌ Find bird sightings near locations                          │
+│  ❌ Get eBird hotspot information                               │
+│                                                                  │
+│  How to use:                                                     │
+│  python -m langgraph_agent demo                                 │
+│  python langgraph_agent/test_agent.py                           │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────┐
+│                  MULTI-SERVER AGENT (Advanced)                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  What you need:                                                  │
+│  ✅ Modal MCP URL                                               │
+│  ✅ Modal API Key                                               │
+│  ✅ OpenAI API Key                                              │
+│  ✅ eBird API Key                                               │
+│  ✅ eBird MCP server running (see setup guide below)           │
+│                                                                  │
+│  What it can do:                                                 │
+│  ✅ Everything from Classifier Agent +                          │
+│  ✅ Find recent bird sightings near any location                │
+│  ✅ Discover birding hotspots                                   │
+│  ✅ Get notable sightings                                       │
+│  ✅ Search for specific species                                 │
+│  ✅ Conversational memory                                       │
+│                                                                  │
+│  How to use:                                                     │
+│  1. Start eBird server: python ebird_tools.py --http --port 8000│
+│  2. python -m langgraph_agent interactive                        │
+│  3. python langgraph_agent/test_agent.py multi                  │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## eBird Server Setup
+
+### When Do You Need the eBird Server?
+
+**You DON'T need eBird server for:**
+- ✅ `python -m langgraph_agent demo` (classifier only)
+- ✅ `python langgraph_agent/test_agent.py` (basic classifier tests)
+- ✅ Creating classifier agents in your own code
+
+**You DO need eBird server for:**
+- ❌ `python -m langgraph_agent interactive` (multi-server chat)
+- ❌ `python langgraph_agent/test_agent.py multi` (multi-server tests)
+- ❌ Creating multi-server agents in your own code
+- ❌ Gradio app (`app.py`)
+
+---
+
+### Two Ways to Run eBird Server
+
+#### **Option 1: stdio (Recommended for Local Development)** ⭐
+
+**Advantages:**
+- ✅ No manual server management
+- ✅ Agent auto-starts/stops server
+- ✅ One terminal window only
+- ✅ Simpler for beginners
+
+**Setup:**
+1. **Add to .env:**
+   ```bash
+   EBIRD_USE_STDIO=true
+   EBIRD_API_KEY=your-ebird-api-key-here
+   ```
+
+2. **That's it!** Just run your agent:
+   ```bash
+   python -m langgraph_agent interactive
+   # eBird server starts automatically!
+   ```
+
+---
+
+#### **Option 2: HTTP (For Production/Manual Control)**
+
+**Advantages:**
+- ✅ Better for production deployment
+- ✅ One server serves multiple agents
+- ✅ More control over server lifecycle
+
+**Setup:**
+
+1. **Configure .env:**
+   ```bash
+   EBIRD_USE_STDIO=false
+   EBIRD_MCP_URL=http://localhost:8000/mcp
+   EBIRD_API_KEY=your-ebird-api-key-here
+   ```
+
+2. **Terminal 1 - Start eBird Server:**
+   ```bash
+   cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+   source ../.venv-hackathon/bin/activate
+
+   python ebird_tools.py --http --port 8000
+   ```
+
+3. **Verify server (new terminal):**
+   ```bash
+   curl http://localhost:8000/health
+   # Should return: {"status": "ok"}
+   ```
+
+4. **Terminal 2 - Run Agent:**
+   ```bash
+   cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+   source ../.venv-hackathon/bin/activate
+
+   python -m langgraph_agent interactive
+   ```
+
+---
+
+### ✅ MCP_API_KEY Authentication Verification
+
+YES, `app.py` is properly configured to use the eBird MCP API key. Here's the authentication flow:
+
+**Authentication Chain:**
+- `.env:11` - Defines `MCP_API_KEY=test-api-key`
+- `config.py:21` - Loads it as `AgentConfig.MCP_API_KEY`
+- `mcp_clients.py:63-71` - Uses it for eBird HTTP authentication:
+  ```python
+  # HTTP transport (server running separately)
+  ebird_headers = {}
+  if AgentConfig.MCP_API_KEY:
+      ebird_headers["Authorization"] = f"Bearer {AgentConfig.MCP_API_KEY}"
+
+  servers_config["ebird"] = {
+      "transport": "streamable_http",
+      "url": AgentConfig.EBIRD_MCP_URL,
+      "headers": ebird_headers if ebird_headers else None
+  }
+  ```
+- `app.py:18` - Calls `AgentFactory.create_streaming_agent()` → which calls `MCPClientManager.create_multi_server_client()` → which includes the authenticated eBird connection
+
+**Current setup (from .env):**
+- `EBIRD_USE_STDIO=false` - Using HTTP mode
+- `MCP_API_KEY=test-api-key` - Auth key for eBird server
+- Authentication header: `Authorization: Bearer test-api-key`
+
+---
+
+### Troubleshooting eBird Server
+
+#### Problem: "Connection refused" or "All connection attempts failed"
+
+**Cause:** eBird server is not running
+
+**Solution:**
+1. Check if server terminal is still running
+2. Restart the server: `python ebird_tools.py --http --port 8000`
+3. Verify with: `curl http://localhost:8000/health`
+
+#### Problem: "Address already in use" when starting server
+
+**Cause:** Port 8000 is already taken
+
+**Solution 1:** Stop the existing process
+```bash
+# Find process using port 8000
+lsof -ti:8000
+
+# Kill it
+kill -9 $(lsof -ti:8000)
+
+# Start server again
+python ebird_tools.py --http --port 8000
+```
+
+**Solution 2:** Use a different port
+```bash
+# Start on different port
+python ebird_tools.py --http --port 8001
+
+# Update .env
+EBIRD_MCP_URL=http://localhost:8001/mcp
+```
+
+#### Problem: "EBIRD_API_KEY not set"
+
+**Cause:** Missing eBird API key in .env
+
+**Solution:**
+1. Get API key from: https://ebird.org/api/keygen
+2. Add to `.env` file:
+   ```bash
+   EBIRD_API_KEY=your-key-here
+   ```
+3. Restart the eBird server
+
+---
+
+### Quick Reference: Server vs No Server
+
+| Command | Needs eBird Server? | What It Does |
+|---------|-------------------|--------------|
+| `python -m langgraph_agent demo` | ❌ No | Test classifier with single image |
+| `python -m langgraph_agent demo [url]` | ❌ No | Test classifier with custom image |
+| `python -m langgraph_agent interactive` | ✅ Yes | Chat with full agent (classifier + eBird) |
+| `python langgraph_agent/test_agent.py` | ❌ No | Run classifier tests (2 images) |
+| `python langgraph_agent/test_agent.py multi` | ✅ Yes | Run multi-server tests (requires eBird) |
+
+---
+
+## CLI Commands
+
+### Running the CLI
+
+The agent package can be run as a Python module from the project root:
+
+```bash
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+python -m langgraph_agent [command] [options]
+```
+
+---
+
+### Command 1: Demo Mode (Default)
+
+**Purpose:** Quick test with a single image classification
+
+**Usage:**
+```bash
+# Use default test image
+python -m langgraph_agent demo
+
+# Or specify your own image URL
+python -m langgraph_agent demo "https://example.com/bird.jpg"
+```
+
+**What happens:**
+1. Loads configuration from `.env`
+2. Prints config summary
+3. Creates classifier agent
+4. Classifies the bird image
+5. Prints results
+
+**Example Output:**
+```
+======================================================================
+Agent Configuration
+======================================================================
+Modal URL:        https://jakeworkoutharder-dev--bird-classifier...
+Modal API Key:    b1363a05f1ef1a8c...
+LLM Model:        gpt-4o-mini
+Temperature:      0.0
+======================================================================
+
+[STATUS]: Connecting to Modal MCP server...
+[STATUS]: Loading MCP tools...
+[LOADED]: 2 tools - ['classify_from_base64', 'classify_from_url']
+[STATUS]: Creating LangGraph agent...
+[SUCCESS]: Agent ready!
+
+======================================================================
+Testing bird classification...
+[IMAGE URL]: https://images.unsplash.com/photo-1445820200644...
+
+[AGENT RESPONSE]:
+The bird in the image is a **Grandala** with a confidence score
+of **99.9%**! What a beautiful bird!
+
+[DEMO COMPLETE!]
+```
+
+---
+
+### Command 2: Interactive Mode
+
+> **⚠️ IMPORTANT:** This command requires the eBird server to be running first! See [eBird Server Setup](#ebird-server-setup) for step-by-step instructions.
+
+**Purpose:** Chat with the agent in real-time
+
+**Usage:**
+```bash
+python -m langgraph_agent interactive
+```
+
+**What happens:**
+1. Creates multi-server agent with memory
+2. Opens interactive chat
+3. Maintains conversation history
+4. Type queries, get responses
+5. Quit with 'exit' or 'quit'
+
+**Example Session:**
+```
+======================================================================
+Bird Classification Agent - Interactive Mode
+======================================================================
+Commands:
+  - Type 'quit' or 'exit' to end session
+  - Paste image URLs to classify birds
+  - Ask about bird locations, sightings, hotspots
+======================================================================
+
+[STATUS]: Connecting to Modal and eBird MCP servers...
+[STATUS]: Loading MCP tools...
+[LOADED]: 9 tools - ['classify_from_base64', 'classify_from_url',
+                      'search_species', 'get_recent_sightings_nearby', ...]
+[STATUS]: Creating multi-server LangGraph agent...
+[SUCCESS]: Agent ready with all tools!
+
+You: What bird is this? https://example.com/cardinal.jpg
+
+Agent: This is a **Northern Cardinal** with 98.7% confidence! These
+beautiful red birds are common across North America and known for
+their bright plumage and distinctive crest.
+
+You: Where can I see them near Boston?
+
+Agent: Northern Cardinals have been spotted recently near Boston!
+Here are some locations:
+- Mount Auburn Cemetery (15 sightings this week)
+- Arnold Arboretum (12 sightings)
+- Fresh Pond Reservation (8 sightings)
+
+You: quit
+
+Goodbye! Happy birding!
+```
+
+**Key Features:**
+- 🧠 **Remembers conversation** - References previous messages
+- 🔧 **Auto-selects tools** - Agent decides which tools to use
+- 💬 **Natural language** - Talk like you would to a person
+
+---
+
+## Programmatic Usage
+
+### Import the Package
+
+From any Python file in your project:
+
+```python
+import asyncio
+from langgraph_agent import AgentFactory, AgentConfig
+```
+
+---
+
+### Example 1: Simple Bird Classification
+
+```python
+import asyncio
+from langgraph_agent import AgentFactory
+
+async def classify_bird():
+    # Create classifier agent
+    agent = await AgentFactory.create_classifier_agent()
+
+    # Classify a bird
+    result = await agent.ainvoke({
+        "messages": [{
+            "role": "user",
+            "content": "What bird is this? https://example.com/bird.jpg"
+        }]
+    })
+
+    # Print response
+    print(result["messages"][-1].content)
+
+# Run
+asyncio.run(classify_bird())
+```
+
+---
+
+### Example 2: Conversational Agent with Memory
+
+```python
+import asyncio
+from langgraph_agent import AgentFactory
+
+async def conversation():
+    # Create agent with memory
+    agent = await AgentFactory.create_classifier_agent(with_memory=True)
+
+    # Thread ID for conversation tracking
+    config = {"configurable": {"thread_id": "user_123"}}
+
+    # Turn 1: Classify bird
+    result1 = await agent.ainvoke({
+        "messages": [{
+            "role": "user",
+            "content": "Identify this: https://example.com/cardinal.jpg"
+        }]
+    }, config)
+    print("Turn 1:", result1["messages"][-1].content)
+
+    # Turn 2: Ask follow-up (agent remembers the bird!)
+    result2 = await agent.ainvoke({
+        "messages": [{
+            "role": "user",
+            "content": "What color is this bird?"
+        }]
+    }, config)
+    print("Turn 2:", result2["messages"][-1].content)
+
+asyncio.run(conversation())
+```
+
+**Output:**
+```
+Turn 1: This is a Northern Cardinal with 98.7% confidence!
+Turn 2: The Northern Cardinal is bright red, which we identified
+in the previous image. Males are vibrant red while females are
+brown with red highlights.
+```
+
+---
+
+### Example 3: Custom Configuration
+
+```python
+import asyncio
+from langgraph_agent import AgentFactory
+
+async def custom_agent():
+    # Create agent with custom settings
+    agent = await AgentFactory.create_classifier_agent(
+        model_name="gpt-4o",       # Use more powerful model
+        temperature=0.3,            # Add creativity
+        with_memory=True            # Enable conversation memory
+    )
+
+    # Use the agent...
+    result = await agent.ainvoke({
+        "messages": [{
+            "role": "user",
+            "content": "Classify and tell me a fun fact about this bird: URL"
+        }]
+    })
+
+    print(result["messages"][-1].content)
+
+asyncio.run(custom_agent())
+```
+
+---
+
+### Example 4: Multi-Server Agent (Classifier + eBird)
+
+```python
+import asyncio
+from langgraph_agent import AgentFactory
+
+async def multi_server_agent():
+    # Create agent with both MCP servers
+    agent = await AgentFactory.create_multi_server_agent(
+        with_memory=True
+    )
+
+    config = {"configurable": {"thread_id": "session_1"}}
+
+    # Agent can now use 9 tools across 2 servers!
+    result = await agent.ainvoke({
+        "messages": [{
+            "role": "user",
+            "content": "What bird is this? Where can I see it near NYC? https://example.com/bird.jpg"
+        }]
+    }, config)
+
+    print(result["messages"][-1].content)
+
+asyncio.run(multi_server_agent())
+```
+
+**What the agent does:**
+1. Uses `classify_from_url` to identify the bird
+2. Uses `search_species` to get species code
+3. Uses `get_recent_sightings_nearby` to find sightings near NYC
+4. Formats response with all information
+
+---
+
+### Example 5: Check Configuration
+
+```python
+from langgraph_agent import AgentConfig
+
+# Print current configuration
+AgentConfig.print_config()
+
+# Access specific values
+print(f"Using model: {AgentConfig.DEFAULT_MODEL}")
+print(f"Modal URL: {AgentConfig.MODAL_MCP_URL}")
+
+# Validate configuration
+try:
+    AgentConfig.validate()
+    print("✅ Configuration is valid!")
+except ValueError as e:
+    print(f"❌ Configuration error: {e}")
+```
+
+---
+
+## Advanced Configuration
+
+### Changing the LLM Model
+
+Edit `.env` file:
+```bash
+# Use GPT-4o (more powerful, slower, more expensive)
+LLM_MODEL=gpt-4o
+
+# Use GPT-4o-mini (faster, cheaper, default)
+LLM_MODEL=gpt-4o-mini
+
+# Use GPT-3.5 (cheapest, fastest, less capable)
+LLM_MODEL=gpt-3.5-turbo
+```
+
+**Or override in code:**
+```python
+agent = await AgentFactory.create_classifier_agent(
+    model_name="gpt-4o"  # Override default
+)
+```
+
+---
+
+### Adjusting Temperature
+
+**Temperature controls creativity:**
+- `0.0` = Deterministic, factual (recommended for classification)
+- `0.5` = Balanced
+- `1.0` = Creative, varied responses
+
+In `.env`:
+```bash
+LLM_TEMPERATURE=0.3
+```
+
+Or in code:
+```python
+agent = await AgentFactory.create_classifier_agent(
+    temperature=0.3
+)
+```
+
+---
+
+### Configuring eBird Server Transport
+
+**Option 1: HTTP Transport (default)**
+```bash
+EBIRD_USE_STDIO=false
+EBIRD_MCP_URL=http://localhost:8000/mcp
+```
+
+Start eBird server separately:
+```bash
+python ebird_tools.py --http --port 8000
+```
+
+**Option 2: Stdio Transport**
+```bash
+EBIRD_USE_STDIO=true
+```
+
+Agent will automatically start eBird server as subprocess.
+
+---
+
+## Troubleshooting
+
+### Issue 1: "ModuleNotFoundError: No module named 'langgraph_agent'"
+
+**Cause:** Package not in Python path
+
+**Solution:**
+```bash
+# Make sure you're in the correct directory
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+
+# Verify package exists
+ls langgraph_agent/
+
+# Try import again
+python -c "from langgraph_agent import AgentFactory"
+```
+
+---
+
+### Issue 2: "ValueError: MODAL_MCP_URL not set in .env"
+
+**Cause:** Missing or incorrect environment variables
+
+**Solution:**
+```bash
+# Check .env file exists
+ls -la .env
+
+# Verify contents
+cat .env | grep MODAL_MCP_URL
+
+# Make sure it's set correctly (no quotes, no trailing slash)
+MODAL_MCP_URL=https://your-url-here/mcp
+```
+
+---
+
+### Issue 3: "401 Unauthorized" when calling Modal
+
+**Cause:** Incorrect API key
+
+**Solution:**
+```bash
+# Verify API key in .env matches Modal secret
+cat .env | grep BIRD_CLASSIFIER_API_KEY
+
+# Get correct key from Modal
+modal secret list
+
+# Update .env with correct key
+```
+
+---
+
+### Issue 4: Agent is slow (30+ seconds per request)
+
+**Cause:** Using expensive model or large conversation history
+
+**Solution 1: Use faster model**
+```bash
+# In .env
+LLM_MODEL=gpt-4o-mini  # Instead of gpt-4o
+```
+
+**Solution 2: Limit conversation history**
+```python
+from langchain_core.messages.utils import trim_messages
+
+# Trim to last 10 messages before invoking
+messages = trim_messages(state["messages"], max_tokens=2000)
+```
+
+---
+
+### Issue 5: "Too many tools loaded" or incorrect tool count
+
+**Cause:** Wrong server configuration
+
+**Expected tool counts:**
+- Classifier only: **2 tools**
+- Multi-server: **9 tools** (2 + 7)
+
+**Solution:**
+```bash
+# Check which agent type you're creating
+# For classifier only:
+agent = await AgentFactory.create_classifier_agent()
+
+# For multi-server:
+agent = await AgentFactory.create_multi_server_agent()
+```
+
+---
+
+## Testing
+
+### Component Testing (Individual Parts)
+
+Before testing agents, verify each component works individually.
+
+#### Test Modal Classifier (Step 1)
+
+**Verify Modal deployment:**
+```bash
+modal app list
+```
+
+**Test with curl:**
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+      "protocolVersion": "2024-11-05",
+      "capabilities": {},
+      "clientInfo": {
+        "name": "test",
+        "version": "1.0"
+      }
+    }
+  }' \
+  https://yourname--bird-classifier-mcp-web.modal.run/mcp
+```
+
+✅ **Success:** Modal responds with JSON result
+
+---
+
+### Agent Testing (Combined System)
+
+#### Test 1: Basic Classifier Agent (No eBird Server Needed)
+
+This test works immediately after installation - no eBird server required!
+
+```bash
+cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+
+# Activate virtual environment
+source ../.venv-hackathon/bin/activate
+
+# Test basic classifier agent (2 bird images)
+python langgraph_agent/test_agent.py
+```
+
+**Expected Output:**
+```
+======================================================================
+Test Suite: Basic Classifier Agent
+======================================================================
+
+[STATUS]: Connecting to Modal MCP server...
+[STATUS]: Loading MCP tools...
+[LOADED]: 2 tools - ['classify_from_base64', 'classify_from_url']
+[STATUS]: Creating LangGraph agent...
+[SUCCESS]: Agent ready!
+
+[TEST 1/2]
+======================================================================
+
+[RESULT]: The bird in the image is a **Jandaya Parakeet**!
+I have a high confidence score of **99.84%** in this identification.
+
+[TEST 2/2]
+======================================================================
+
+[RESULT]: The bird in the image is identified as a **Grandala**
+with a confidence score of **99.9%**! What a beautiful bird!
+
+[ALL TESTS COMPLETE!]
+```
+
+---
+
+#### Test 2: Multi-Server Agent (Requires eBird Server)
+
+This test requires the eBird server to be running first!
+
+**Step-by-Step:**
+
+1. **Terminal 1 - Start eBird Server:**
+   ```bash
+   cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+   source ../.venv-hackathon/bin/activate
+
+   # Start eBird server (keep this running)
+   python ebird_tools.py --http --port 8000
+   ```
+
+2. **Terminal 2 - Run Multi-Server Test:**
+   ```bash
+   cd /Users/jacobbinder/Desktop/hackathon/hackathon_draft
+   source ../.venv-hackathon/bin/activate
+
+   # Run multi-server test
+   python langgraph_agent/test_agent.py multi
+   ```
+
+**Expected Output:**
+```
+======================================================================
+Test Suite: Multi-Server Agent
+======================================================================
+
+[STATUS]: Connecting to Modal and eBird servers...
+[STATUS]: Loading MCP tools...
+[LOADED]: 9 tools available
+  - classify_from_base64
+  - classify_from_url
+  - search_species
+  - get_recent_sightings_nearby
+  - get_notable_sightings_nearby
+  - get_recent_checklists_nearby
+  - get_regional_statistics
+  - list_hotspots_nearby
+  - get_checklist_details
+
+[TEST 1]: Classify bird from URL
+======================================================================
+
+[RESULT]: The bird in the image is a **Jandaya Parakeet** with
+99.84% confidence!
+
+[TEST 2]: Follow-up question (tests memory)
+======================================================================
+
+[RESULT]: You can see Jandaya Parakeets near Boston (42.36, -71.06):
+- Arnold Arboretum (3 sightings this month)
+- Mount Auburn Cemetery (2 sightings)
+Note: These are exotic birds, not native to the area.
+
+[ALL TESTS COMPLETE!]
+```
+
+**What This Tests:**
+- ✅ Multi-server connection (Modal + eBird)
+- ✅ Tool integration (9 tools from both servers)
+- ✅ Conversation memory (follow-up question)
+- ✅ Cross-server reasoning (classify → location lookup)
+
+---
+
+## Examples
+
+### Complete Example: Bird Identification App
+
+```python
+"""
+Simple bird identification CLI app
+"""
+import asyncio
+from langgraph_agent import AgentFactory
+
+async def main():
+    print("🐦 Bird Identification App")
+    print("=" * 50)
+
+    # Create agent
+    print("\n[1/3] Initializing agent...")
+    agent = await AgentFactory.create_classifier_agent()
+
+    # Get image URL from user
+    print("\n[2/3] Waiting for input...")
+    image_url = input("Enter bird image URL: ").strip()
+
+    if not image_url:
+        print("❌ No URL provided")
+        return
+
+    # Classify
+    print("\n[3/3] Classifying...")
+    result = await agent.ainvoke({
+        "messages": [{
+            "role": "user",
+            "content": f"Identify this bird: {image_url}"
+        }]
+    })
+
+    # Display result
+    print("\n" + "=" * 50)
+    print("RESULT:")
+    print("=" * 50)
+    print(result["messages"][-1].content)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+**Run it:**
+```bash
+python my_bird_app.py
+```
+
+---
+
+## Quick Reference
+
+### Import Patterns
+
+```python
+# Import everything
+from langgraph_agent import (
+    AgentFactory,
+    AgentConfig,
+    create_bird_agent,
+    create_multi_agent,
+    MCPClientManager,
+    get_prompt_for_agent_type
+)
+
+# Or import as needed
+from langgraph_agent import AgentFactory
+```
+
+### Create Agent (Simple)
+
+```python
+# Minimal
+agent = await AgentFactory.create_classifier_agent()
+
+# With memory
+agent = await AgentFactory.create_classifier_agent(with_memory=True)
+
+# Custom model
+agent = await AgentFactory.create_classifier_agent(
+    model_name="gpt-4o",
+    temperature=0.3
+)
+```
+
+### Create Agent (Multi-Server)
+
+```python
+# Default (with memory)
+agent = await AgentFactory.create_multi_server_agent()
+
+# Custom settings
+agent = await AgentFactory.create_multi_server_agent(
+    model_name="gpt-4o",
+    temperature=0.5,
+    with_memory=True
+)
+```
+
+### Invoke Agent
+
+```python
+# Single turn
+result = await agent.ainvoke({
+    "messages": [{"role": "user", "content": "Your message"}]
+})
+
+# With memory (multi-turn)
+config = {"configurable": {"thread_id": "session_1"}}
+result = await agent.ainvoke({
+    "messages": [{"role": "user", "content": "Your message"}]
+}, config)
+```
+
+---
+
+## Summary
+
+✅ **Installation:** Install dependencies, set up `.env`
+✅ **Configuration:** Edit `.env` with API keys and URLs
+✅ **Usage:** CLI commands or Python imports
+✅ **CLI:** `demo` for testing (no eBird), `interactive` for chat (needs eBird)
+✅ **Programmatic:** Import `AgentFactory`, create agents, invoke
+✅ **Testing:** Run `test_agent.py` to verify setup
+
+**Ready to build?** Start with these commands (no eBird server needed):
+```bash
+# Test the classifier
+python -m langgraph_agent demo
+
+# Run basic tests
+python langgraph_agent/test_agent.py
+```
+
+**Want multi-server features?** See [eBird Server Setup](#ebird-server-setup) above.
+
+**Questions?** Check the [HuggingFace Deployment Guide](../../project_docs/implementation/hf_deploy_planning.md) or [Phase 3 Documentation](../../project_docs/implementation/phase_3.md).
+
+Happy birding! 🐦

langgraph_agent/config.py

@@ -0,0 +1,67 @@
+"""
+Configuration for LangGraph agents.
+Loads environment variables and manages settings.
+"""
+import os
+from dotenv import load_dotenv
+from typing import Optional
+
+load_dotenv()
+
+class AgentConfig:
+    """Configuration for bird classification agents."""
+
+    # Modal Bird classifier (Phase 1)
+    MODAL_MCP_URL: str = os.getenv("MODAL_MCP_URL", "")
+    BIRD_CLASSIFIER_API_KEY: str = os.getenv("BIRD_CLASSIFIER_API_KEY", "")
+
+    # eBird Server (Phase 2 - deprecated, replaced by Nuthatch)
+    EBIRD_API_KEY: str = os.getenv("EBIRD_API_KEY", "")  # For Cornell eBird API calls
+    EBIRD_BASE_URL: str = os.getenv("EBIRD_BASE_URL", "https://api.ebird.org/v2")  # Cornell eBird API endpoint
+    EBIRD_MCP_URL: str = os.getenv("EBIRD_MCP_URL", "http://localhost:8000/mcp")  # MCP server endpoint
+    EBIRD_USE_STDIO: bool = os.getenv("EBIRD_USE_STDIO", "false").lower() == "true"
+    EBIRD_MCP_AUTH_KEY: Optional[str] = os.getenv("EBIRD_MCP_AUTH_KEY")  # For HTTP transport auth (legacy: MCP_API_KEY)
+
+    # Nuthatch Server (Phase 2.5 - species reference database)
+    NUTHATCH_API_KEY: str = os.getenv("NUTHATCH_API_KEY", "")  # For Nuthatch API calls
+    NUTHATCH_BASE_URL: str = os.getenv("NUTHATCH_BASE_URL", "https://nuthatch.lastelm.software/v2")  # Nuthatch API endpoint
+    NUTHATCH_MCP_URL: str = os.getenv("NUTHATCH_MCP_URL", "http://localhost:8001/mcp")  # MCP server endpoint
+    NUTHATCH_USE_STDIO: bool = os.getenv("NUTHATCH_USE_STDIO", "true").lower() == "true"
+    NUTHATCH_MCP_AUTH_KEY: Optional[str] = os.getenv("NUTHATCH_MCP_AUTH_KEY")  # For HTTP transport
+
+    # LLM Settings
+    OPENAI_API_KEY: str = os.getenv("OPENAI_API_KEY", "")  # For dev/testing with backend-provided key
+    DEFAULT_OPENAI_MODEL: str = os.getenv("DEFAULT_OPENAI_MODEL", "gpt-4o-mini")
+    DEFAULT_HF_MODEL: str = os.getenv("DEFAULT_HF_MODEL", "Qwen/Qwen2.5-Coder-32B-Instruct")
+
+    # Anthropic Settings
+    ANTHROPIC_API_KEY: str = os.getenv("ANTHROPIC_API_KEY", "")
+    DEFAULT_ANTHROPIC_MODEL: str = os.getenv("DEFAULT_ANTHROPIC_MODEL", "claude-sonnet-4-5-20250929")
+    ANTHROPIC_TEMPERATURE: float = float(os.getenv("ANTHROPIC_TEMPERATURE", "0.0"))
+
+    # Provider-specific temperature settings
+    OPENAI_TEMPERATURE: float = float(os.getenv("OPENAI_TEMPERATURE", "0.0"))
+    HF_TEMPERATURE: float = float(os.getenv("HF_TEMPERATURE", "0.1"))
+
+    # Agent Settings
+    MAX_ITERATIONS: int = int(os.getenv("AGENT_MAX_ITERATIONS", "10"))
+    TIMEOUT: int = int(os.getenv("AGENT_TIMEOUT", "120"))
+
+    @classmethod
+    def print_config(cls) -> None:
+        """Print current configuration (hiding sensitive data)."""
+        print("\n" + "="*70)
+        print("Agent Configuration")
+        print("="*70)
+        print(f"[MODAL URL]:        {cls.MODAL_MCP_URL}")
+        print(f"[MODAL API KEY]:    {cls.BIRD_CLASSIFIER_API_KEY[:20]}..." if cls.BIRD_CLASSIFIER_API_KEY else "[MODAL API KEY]:  Not set")
+        print(f"[NUTHATCH STDIO]:   {cls.NUTHATCH_USE_STDIO}")
+        print(f"[NUTHATCH URL]:     {cls.NUTHATCH_MCP_URL}")
+        print(f"[NUTHATCH API KEY]: {'✅ Set' if cls.NUTHATCH_API_KEY else '❌ Not set'}")
+        print(f"[OPENAI MODEL]:     {cls.DEFAULT_OPENAI_MODEL}")
+        print(f"[OPENAI TEMP]:      {cls.OPENAI_TEMPERATURE}")
+        print(f"[HF MODEL]:         {cls.DEFAULT_HF_MODEL}")
+        print(f"[HF TEMP]:          {cls.HF_TEMPERATURE}")
+        print(f"[ANTHROPIC_MODEL]:  {cls.DEFAULT_ANTHROPIC_MODEL}")
+        print(f"[ANTHROPIC_TEMP]:  {cls.ANTHROPIC_TEMPERATURE}")
+        print("="*70 + "\n")

langgraph_agent/main.py

@@ -0,0 +1,105 @@
+"""
+Main entry point for LangGraph bird classification agents.
+"""
+import asyncio
+import sys
+from typing import Optional
+
+from .config import AgentConfig
+from .agents import AgentFactory
+
+async def run_classifier_demo(image_url: Optional[str] = None):
+    """Run basic classifier demo"""
+
+    AgentConfig.print_config()
+
+    # Create agent
+    agent = await AgentFactory.create_classifier_agent()
+
+    # Default test URL if none provided
+    if not image_url:
+        image_url = "https://images.unsplash.com/photo-1445820200644-69f87d946277?w=400"
+    
+    print("="*70)
+    print("Testing bird classification...")
+    print(f"[IMAGE URL]: {image_url}\n")
+
+    # Invoke agent
+    result = await agent.ainvoke({
+        "messages": [{
+            "role": "user",
+            "content": f"What bird species is this? {image_url}"
+        }]
+    })
+
+    # Print result
+    print("\n[AGENT RESPONSE]:")
+    print(result["messages"][-1].content)
+    print("\n[DEMO COMPLETE!]\n")
+
+async def run_interactive_chat():
+    """Run interactive chat with agent."""
+
+    print("\n"+"="*70)
+    print("Bird Classification Agent - Interactive Mode")
+    print("="*70)
+    print("Commands:")
+    print(". - Type 'quit' or 'exit' to end session")
+    print("  - Paste image URLs to classify birds")
+    print(". - Ask about bird locations, sightings, hotspots")
+    print("="*70+"\n")
+
+    # Create multi-server agent with memory
+    agent = await AgentFactory.create_multi_server_agent(with_memory=True)
+
+    # Thread ID for conversation memory
+    config = {"configurable": {"thread_id": "interactive_session"}}
+
+    while True:
+        try:
+            user_input = input("\nYou: ").strip()
+
+            if user_input.lower() in ['quit', 'exit', 'q']:
+                print("\nGoodbye! Happy birding!\n")
+                break
+
+            if not user_input:
+                continue
+
+            # Invoke agent
+            result = await agent.ainvoke(
+                {"messages": [{"role": "user", "content": user_input}]},
+                config
+            )
+
+            # Print response
+            print(f"\nAgent: {result['messages'][-1].content}")
+
+        except KeyboardInterrupt:
+            print("\nGoodbye! Happy birding!\n")
+            break
+        except Exception as e:
+            print(f"\n[ERROR]: {e}")
+
+def main():
+    """Main entry point"""
+
+    if len(sys.argv) > 1:
+        command = sys.argv[1]
+
+        if command == "interactive":
+            asyncio.run(run_interactive_chat())
+        elif command == "demo":
+            url = sys.argv[2] if len(sys.argv) > 2 else None
+            asyncio.run(run_classifier_demo(url))
+        else:
+            print(f"Unknown command: {command}")
+            print("Usage:")
+            print("  python -m langgraph_agent demo [url]")
+            print("  python -m langgraph_agent interactive")
+    else:
+        # Default: run demo
+        asyncio.run(run_classifier_demo())
+
+if __name__ == "__main__":
+    main()

langgraph_agent/mcp_clients.py

@@ -0,0 +1,103 @@
+"""
+MCP client configuration and setup for bird classification agents.
+"""
+import os
+from typing import List, Dict, Any
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from .config import AgentConfig
+
+class MCPClientManager:
+    """Manages MCP client connections to various servers"""
+
+    @staticmethod
+    async def create_classifier_client() -> MultiServerMCPClient:
+        """
+        Create MCP client for Modal bird classifier only.
+
+        Returns:
+            MultiServerMCPClient configured for Modal server
+        """
+        print("[STATUS]: Connecting to Modal MCP server...")
+
+        client = MultiServerMCPClient({
+            "bird_classifier": {
+                "transport": "streamable_http",
+                "url": AgentConfig.MODAL_MCP_URL,
+                "headers": {
+                    "X-API-Key": AgentConfig.BIRD_CLASSIFIER_API_KEY
+                }
+            }
+        })
+
+        return client
+
+    @staticmethod
+    async def create_multi_server_client() -> MultiServerMCPClient:
+        """
+        Create MCP client for both Modal classifier and Nuthatch species database.
+
+        Returns:
+            MultiServerMCPClient configured for both servers
+        """
+        print("[STATUS]: Connecting to Modal and Nuthatch servers...")
+
+        servers_config = {
+            "bird_classifier": {
+                "transport": "streamable_http",
+                "url": AgentConfig.MODAL_MCP_URL,
+                "headers": {
+                    "X-API-Key": AgentConfig.BIRD_CLASSIFIER_API_KEY
+                }
+            }
+        }
+
+        # Add Nuthatch server (Phase 2.5 - species reference database)
+        # Supports both STDIO (default) and HTTP transport
+        if AgentConfig.NUTHATCH_USE_STDIO:
+            # STDIO mode - subprocess for integrated agent use
+            servers_config["nuthatch"] = {
+                "transport": "stdio",
+                "command": "python",
+                "args": ["nuthatch_tools.py"],  # Same directory as where app runs
+                "env": {
+                    # Pass through critical env vars from parent process
+                    # HuggingFace Spaces Secrets don't auto-inherit to subprocesses
+                    "NUTHATCH_API_KEY": AgentConfig.NUTHATCH_API_KEY,
+                    "NUTHATCH_BASE_URL": AgentConfig.NUTHATCH_BASE_URL
+                }
+            }
+        else:
+            # HTTP mode - external server (requires nuthatch_tools.py running separately)
+            nuthatch_config = {
+                "transport": "streamable_http",
+                "url": AgentConfig.NUTHATCH_MCP_URL
+            }
+            # Add auth header if configured (DebugTokenVerifier expects Bearer token)
+            if AgentConfig.NUTHATCH_MCP_AUTH_KEY:
+                nuthatch_config["headers"] = {
+                    "Authorization": f"Bearer {AgentConfig.NUTHATCH_MCP_AUTH_KEY}"
+                }
+            servers_config["nuthatch"] = nuthatch_config
+
+        client = MultiServerMCPClient(servers_config)
+        return client
+
+    @staticmethod
+    async def get_tools(client: MultiServerMCPClient) -> List[Any]:
+        """
+        Get tools from MCP client and print summary.
+
+        Args:
+            client: MultiServerMCPClient instance
+
+        Returns:
+            List of tools
+        """
+        print("[STATUS]: Loading MCP tools...")
+        tools = await client.get_tools()
+
+        print(f"[LOADED]: {len(tools)} tools available")
+        for tool in tools:
+            print(f"  - {tool.name}")
+
+        return tools

langgraph_agent/mcp_clients.py.ebird

@@ -0,0 +1,106 @@
+"""
+MCP client configuration and setup for bird classification agents.
+"""
+import os
+from typing import List, Dict, Any
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from .config import AgentConfig
+
+class MCPClientManager:
+    """Manages MCP client connections to various servers"""
+
+    @staticmethod
+    async def create_classifier_client() -> MultiServerMCPClient:
+        """
+        Create MCP client for Modal bird classifier only.
+
+        Returns:
+            MultiServerMCPClient configured for Modal server
+        """
+        print("[STATUS]: Connecting to Modal MCP server...")
+
+        client = MultiServerMCPClient({
+            "bird_classifier": {
+                "transport": "streamable_http",
+                "url": AgentConfig.MODAL_MCP_URL,
+                "headers": {
+                    "X-API-Key": AgentConfig.BIRD_CLASSIFIER_API_KEY
+                }
+            }
+        })
+
+        return client
+
+    @staticmethod
+    async def create_multi_server_client() -> MultiServerMCPClient:
+        """
+        Create MCP client for both Modal classifier and eBird server.
+
+        Returns:
+            MultiServerMCPClient configured for both servers
+        """
+        print("[STATUS]: Connecting to Modal and eBird servers...")
+
+        servers_config = {
+            "bird_classifier": {
+                "transport": "streamable_http",
+                "url": AgentConfig.MODAL_MCP_URL,
+                "headers": {
+                    "X-API-Key": AgentConfig.BIRD_CLASSIFIER_API_KEY
+                }
+            }
+        }
+
+        # Add eBird server (Phase 2)
+        if AgentConfig.EBIRD_USE_STDIO:
+            # Stdio transport (run server as subprocess)
+            # IMPORTANT: Explicitly pass environment variables to subprocess
+            # HuggingFace Spaces Secrets don't auto-inherit to subprocesses
+            servers_config["ebird"] = {
+                "transport": "stdio",
+                "command": "python",
+                "args": ["ebird_tools.py"],  # Same directory as where app runs
+                "env": {
+                    # Pass through critical env vars from parent process
+                    # HuggingFace Spaces Secrets don't auto-inherit to subprocesses
+                    "EBIRD_API_KEY": AgentConfig.EBIRD_API_KEY,
+                    "EBIRD_BASE_URL": AgentConfig.EBIRD_BASE_URL,
+                    "ENVIRONMENT": os.getenv("ENVIRONMENT", "development"),
+                    "MCP_API_KEY": AgentConfig.EBIRD_MCP_AUTH_KEY or "",
+                }
+            }
+        else:
+            # HTTP transport (server running separately)
+            ebird_config = {
+                "transport": "streamable_http",
+                "url": AgentConfig.EBIRD_MCP_URL
+            }
+            # Add auth header if configured (DebugTokenVerifier expects Bearer token)
+            if AgentConfig.EBIRD_MCP_AUTH_KEY:
+                ebird_config["headers"] = {
+                    "Authorization": f"Bearer {AgentConfig.EBIRD_MCP_AUTH_KEY}"
+                }
+            servers_config["ebird"] = ebird_config
+
+        client = MultiServerMCPClient(servers_config)
+        return client
+
+    @staticmethod
+    async def get_tools(client: MultiServerMCPClient) -> List[Any]:
+        """
+        Get tools from MCP client and print summary.
+
+        Args:
+            client: MultiServerMCPClient instance
+
+        Returns:
+            List of tools
+        """
+        print("[STATUS]: Loading MCP tools...")
+        tools = await client.get_tools()
+
+        print(f"[LOADED]: {len(tools)} tools available")
+        for tool in tools:
+            print(f"  - {tool.name}")
+
+        return tools

langgraph_agent/prompts.py

@@ -0,0 +1,213 @@
+"""
+System prompts and templates for bird classification agents.
+"""
+
+# Basic classifier agent prompt
+CLASSIFIER_AGENT_PROMPT = """
+You are a helpful bird identification assistant.
+
+When a user provides an image URL, use the classify_from_url tool to identify the bird species.
+When a user provides a base64 image, use the classify_from_base64 tool.
+
+Always report:
+    - Species name
+    - Confidence score (as percentage)
+    - Any interesting facts about the bird (if you know them)
+
+If information is unavailable or you are not sure do not make it up but instead just state that you don't know.
+
+If a user's query is not related to birds or bird identification then politely explain our role and abiltiies and that you can only answer bird-related queries.
+"""
+
+# Multi-server agent prompt (classifier + eBird)
+MULTI_SERVER_AGENT_PROMPT = """
+You are an expert bird identification and exploration assistant with access to two powerful systems:
+    
+1. **Bird Classifier** (Modal GPU)
+    - classify_from_url: Identify birds from image URLs
+    - classify_from_base64: Identify birds from base64 images
+
+2. **eBird Database** (Global bird sighting data)
+    - search_species: Find species codes and info
+    - get_recent_sightings_nearby: Find recent sightings near a location
+    - find_hotspots_nearby: Discover popular birding locations
+    - get_location_birds: See all birds at a location
+    - get_notable_sightings: Find rare birds in a region
+    - analyze_location: Comprehensive location analysis
+
+**Your workflow:**
+1. When given an image: Classify it first, then optionally provide context using eBird tools
+2. When asked about locations: Use eBird tools to find sightings and hotspots
+3. When asked about species: Use search_species to get the species code, then other tools for details
+    
+Always be:
+    - Friendly and enthusiastic about birds
+    - Accurate with species identification
+    - Helpful with location recommendations
+    - Clear about confidence levels
+
+If you're unsure, say so. Birding is about learning and discovery!
+"""
+
+NUTHATCH_BIRDSCOPE_PROMPT = """You are BirdScope AI - an enthusiastic bird identification and education assistant!
+
+**Your Mission:**
+Help users identify birds from photos and provide rich educational content about bird species,
+including reference images, audio recordings, conservation status, and taxonomic information.
+
+**Available Tools (9 total):**
+
+🔍 **Bird Classifier (Modal GPU):**
+- classify_from_url: Identify birds from image URLs
+- classify_from_base64: Identify birds from base64-encoded images
+
+📚 **Species Database (Nuthatch API - 1000+ species):**
+- search_birds: Multi-filter search (name, family, region, conservation status)
+- get_bird_info: Complete species profile (taxonomy, size, status, images, audio count)
+- get_bird_images: High-quality reference photos from Unsplash
+- get_bird_audio: Sound recordings from xeno-canto.org
+- search_by_family: Find all species in a taxonomic family
+- filter_by_status: Search by conservation status (Endangered, Low Concern, etc.)
+- get_all_families: List all bird families in the database
+
+**Your Workflow:**
+1. **Image Identification**: When users upload a bird photo, the classifier will identify it automatically
+2. **Rich Context**: After identification, use Nuthatch tools to provide:
+   - Reference images (show users what the species looks like from different angles)
+   - Audio recordings (let them hear the bird's call/song)
+   - Conservation status and interesting facts
+   - Related species in the same family
+3. **Educational Queries**: When users ask about specific birds or families, use search and info tools
+4. **Visual Learning**: Always offer to show images and audio when discussing a species
+
+**Response Style:**
+- Be enthusiastic and educational
+- Cite confidence scores for image classifications
+- Describe what makes each species unique (visual features, sounds, behavior)
+- Format image and audio URLs as clickable markdown links
+- Mention conservation status to raise awareness
+- Suggest related species they might be interested in
+
+**Important Notes:**
+- This is a SPECIES REFERENCE system, not a location finder (no real-time sightings or hotspots)
+- Focus on "What is this bird?" rather than "Where can I see it?"
+- Images are from Unsplash and curator collections (always high quality)
+- Audio is from xeno-canto.org (community-contributed bird recordings)
+- Database covers 1000+ species (primarily North America and Western Europe)
+
+Let's explore the amazing world of birds together! 🦅
+"""
+
+# Conversational agent with memory
+CONVERSATIONAL_AGENT_PROMPT = """
+You are a knowledgeable and friendly bird expert assistant. You have access to:
+- Bird image classification tools
+- eBird global bird sightings database
+- Birding hotspot information
+
+You remember our conversation history, so:
+- Reference birds we've discussed previously
+- Build on location context from earlier in the conversation
+- Suggest related species or locations based on user interests
+
+Keep responses concise but informative. Don't overwhelm the user with data, but if a user shows interest in a particular species or location, offer to provide more details.
+"""
+
+# BirdScope AI Web Interface Prompt (used in Gradio app)
+BIRDSCOPE_AI_PROMPT = """You are BirdScope AI - an enthusiastic bird expert!
+
+Help users identify birds and find amazing bird locations.
+Always be educational and cite your sources.
+
+**Your capabilities:**
+- Identify birds from uploaded images using state-of-the-art classification
+- Find recent bird sightings in any location using eBird data
+- Recommend birding hotspots and popular locations
+- Provide species information and interesting facts
+
+**Response style:**
+- Be friendly and encouraging
+- Cite confidence scores for identifications
+- Provide actionable location recommendations when asked
+- Format responses clearly
+
+Let's explore the amazing world of birds together!"""
+
+AUDIO_FINDER_PROMPT = """You are BirdScope Audio Finder, a specialized agent for finding and retrieving bird audio recordings.
+
+**Your Mission:**
+Help us discover bird songs and calls by finding species with available audio recordings.
+
+**Your Tools:**
+1. **search_birds(name, family, region, status, page_size)**
+    - Multi-filter search for bird species
+    - IMPORTANT: At least ONE filter is required (name, family, region, or status)
+    - ⚠️ CRITICAL: DO NOT use `has_audio` as a parameter - it will cause an error!
+    - The API returns a `has_audio` field in RESULTS that you check after the call
+    - Available parameters ONLY: name, family, region, status, page_size
+
+2. **get_bird_info(name)**
+    - Get complete species information
+    - Check `audio_count` field to verify recordings exist
+
+3. **get_bird_audio(name, max_recordings)**
+    - Fetch actual audio recordings from xeno-canto.org
+    - Returns recording metadata and download URLs
+    - Only call this for birds that have `has_audio=true` in their search results
+
+**CRITICAL WORKFLOW for "find audio for any bird":**
+The API has NO `has_audio` filter parameter. You MUST use this two-step process:
+
+    1. **First**: Call `search_birds()` with ONE of these parameters:
+        - For "any bird": `region="North America"` (most coverage)
+        - For specific bird: `name="Bird Name"`
+        - For family search: `family="Family Name"`
+        - ⚠️ DO NOT include `has_audio` in the function call - it's not a valid parameter!
+
+    2. **Then**: Look at the RESULTS and find birds where `has_audio=true`
+
+    3. **Finally**: Call `get_bird_audio(name)` on a bird that has audio
+
+    **Known Birds With Audio:**
+    - Snow Goose, Common Goldeneye, Gadwall, Tundra Swan, Ross's Goose
+    - Use these as fallbacks if search yields no audio
+
+    **Response Style:**
+    - Always confirm which bird you're fetching audio for
+    - Mention the number of recordings available
+    - Provide recording details (location, date, type, recordist)
+    - **CRITICAL**: Include the FULL file_url from the API response in your text
+      Example: "Recording: https://xeno-canto.org/143610/download"
+      This ensures URLs are formatted as clickable links for the user
+
+    **Example Interaction:**
+    User: "Find audio recordings for any bird"
+    You:
+    1. Call search_birds(region="North America", page_size=20)
+    2. Filter results for has_audio=true
+    3. Pick first bird with audio (e.g., "Black-bellied Whistling-Duck")
+    4. Call get_bird_audio("Black-bellied Whistling-Duck", max_recordings=1)
+    5. Present: "Found 10 recordings for Black-bellied Whistling-Duck. Here's a sample:
+
+       Recording from Orlando Wetlands, Florida (July 18, 2013)
+       Recordist: Paul Marvin
+       Quality: A
+       https://xeno-canto.org/143610/download"
+
+    **Error Handling:**
+    - If search returns no birds: suggest broadening filters
+    - If no birds have audio: inform user and suggest known birds with audio
+    - If get_bird_audio fails: the bird may not have recordings despite database indicating otherwise
+    """
+
+def get_prompt_for_agent_type(agent_type: str) -> str:
+    """Get the appropriate prompt for the agent type."""
+    prompts = {
+        "classifier": CLASSIFIER_AGENT_PROMPT,
+        "multi_server": MULTI_SERVER_AGENT_PROMPT,
+        "conversational": CONVERSATIONAL_AGENT_PROMPT,
+        "birdscope_ai": BIRDSCOPE_AI_PROMPT,
+        "nuthatch_birdscope": NUTHATCH_BIRDSCOPE_PROMPT
+    }
+    return prompts.get(agent_type, CLASSIFIER_AGENT_PROMPT)
+

langgraph_agent/simple_demo.py

@@ -0,0 +1,78 @@
+"""
+Simple LangGraph agent demo connecting to Modal bird classifier MCP
+"""
+
+import asyncio
+import os
+from dotenv import load_dotenv
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain.agents import create_agent
+from langchain_openai import ChatOpenAI 
+
+load_dotenv()
+
+async def create_bird_agent():
+    """Create and return a bird classification agent."""
+
+    # 1. Configure MCP client for Modal bird classifier
+    print("[STATUS]: Connecting to Modal MCP server...")
+
+    client = MultiServerMCPClient({
+        "bird_classifier": {
+            "transport": "streamable_http",
+            "url": os.getenv("MODAL_MCP_URL"),
+            "headers": {
+                "X-API-Key": os.getenv("BIRD_CLASSIFIER_API_KEY")
+            }
+        }
+    })
+
+    # 2. Get tools from MCP server
+    print("[STATUS]: Loading MCP tools...")
+    tools = await client.get_tools()
+    print(f"[LOADED]: {len(tools)} tools - {[t.name for t in tools]}")
+
+    # 3. Create agent with model and tools
+    print("[STATUS]: Creating LangGraph agent...")
+    agent = create_agent(
+        model=ChatOpenAI(
+            model="gpt-4o-mini",
+            temperature=0
+        ),
+        tools=tools,
+        system_prompt="""
+        You are a helpful bird identification assistant.
+        When a user provides an image URL, use the classify_from_url tool to identify the bird species.
+        Always report the species name and confidence score in a friendly manner."""
+    )
+
+    return agent
+
+async def main():
+    """Run simple bird classification agent demo"""
+
+    # Create agent
+    agent = await create_bird_agent()
+
+    # 4. Test with a bird image URL
+    print("\n"+"="*70)
+    print("[STATUS]: Testing bird classification...")
+    print("="*70+"\n")
+
+    test_url = "https://images.unsplash.com/photo-1445820200644-69f87d946277?w=400&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8MTV8fGJpcmR8ZW58MHx8MHx8fDA%3D"
+
+    result = await agent.ainvoke({
+        "messages": [{
+            "role": "user",
+            "content": f"What bird species is this? {test_url}"
+        }]
+    })
+
+    # 5. Print results
+    print("\n[AGENT RESPONSE]:")
+    print(result["messages"][-1].content)
+
+    print("\n[DEMO COMPLETE!]")
+
+if __name__ == "__main__":
+    asyncio.run(main())

langgraph_agent/structured_output.py

@@ -0,0 +1,167 @@
+"""
+Structured output parsing using LlamaIndex Pydantic Programs.
+Ensures consistent image formatting in agent responses.
+
+HACKATHON OPTIMIZED: Uses regex extraction instead of LLM calls for speed.
+"""
+from typing import List, Optional
+import re
+from pydantic import BaseModel, Field
+
+
+class BirdIdentificationResponse(BaseModel):
+    """Structured response for bird identification using LlamaIndex Pydantic."""
+
+    summary: str = Field(
+        description="Main response text with bird identification, facts, or information"
+    )
+    species_name: Optional[str] = Field(
+        default=None,
+        description="Common name of the bird species (e.g., 'Northern Cardinal')"
+    )
+    image_urls: List[str] = Field(
+        default_factory=list,
+        description="List of image URLs to display for this bird"
+    )
+    audio_urls: List[str] = Field(
+        default_factory=list,
+        description="List of audio URLs (bird calls/songs)"
+    )
+    confidence_score: Optional[float] = Field(
+        default=None,
+        description="Confidence score from classifier (0.0-1.0)"
+    )
+
+
+def extract_urls_from_text(text: str) -> tuple[List[str], List[str]]:
+    """
+    Extract image and audio URLs from text using regex.
+
+    Returns:
+        tuple: (image_urls, audio_urls)
+    """
+    # Pattern for image URLs (jpg, jpeg, png, gif, webp, svg)
+    image_pattern = r'https?://[^\s<>"{}|\\^`\[\]]+\.(?:jpg|jpeg|png|gif|webp|svg)(?:\?[^\s]*)?'
+
+    # Pattern for audio URLs - handles both direct audio files AND xeno-canto links
+    # Matches: .mp3, .wav, .ogg, .m4a files OR xeno-canto.org URLs with /download
+    audio_pattern_files = r'https?://[^\s<>"{}|\\^`\[\]]+\.(?:mp3|wav|ogg|m4a)(?:\?[^\s]*)?'
+    audio_pattern_xenocanto = r'https?://xeno-canto\.org/\d+/download'
+
+    # Extract all URLs
+    image_urls = list(set(re.findall(image_pattern, text, re.IGNORECASE)))
+    audio_urls_files = list(set(re.findall(audio_pattern_files, text, re.IGNORECASE)))
+    audio_urls_xenocanto = list(set(re.findall(audio_pattern_xenocanto, text, re.IGNORECASE)))
+
+    # Combine both types of audio URLs
+    audio_urls = audio_urls_files + audio_urls_xenocanto
+
+    return image_urls, audio_urls
+
+
+def extract_species_name(text: str) -> Optional[str]:
+    """
+    Try to extract species name from common patterns in response.
+    """
+    # Pattern: "identified as SPECIES NAME" or "species: SPECIES NAME"
+    patterns = [
+        r'identified as[:\s]+([A-Z][a-z]+(?:\s+[A-Z][a-z]+){0,3})',
+        r'species[:\s]+([A-Z][a-z]+(?:\s+[A-Z][a-z]+){0,3})',
+        r'This is (?:a |an )?([A-Z][a-z]+(?:\s+[A-Z][a-z]+){0,3})',
+    ]
+
+    for pattern in patterns:
+        match = re.search(pattern, text)
+        if match:
+            return match.group(1)
+
+    return None
+
+
+async def parse_agent_response(
+    raw_response: str,
+    provider: str,
+    api_key: str,
+    model: str
+) -> str:
+    """
+    Parse agent response into structured format and reformat with guaranteed markdown.
+
+    OPTIMIZED FOR HACKATHON: Uses regex extraction instead of LLM call.
+    Still uses LlamaIndex Pydantic models for structured data.
+
+    Args:
+        raw_response: The agent's raw text response
+        provider: LLM provider ("openai", "anthropic", "huggingface")
+        api_key: API key (unused in optimized version)
+        model: Model name (unused in optimized version)
+
+    Returns:
+        Formatted markdown response with guaranteed image syntax
+    """
+    try:
+        print("[STRUCTURED OUTPUT] Starting parsing...")
+
+        # Extract URLs using regex (fast, no API call)
+        image_urls, audio_urls = extract_urls_from_text(raw_response)
+
+        print(f"[STRUCTURED OUTPUT] Found {len(image_urls)} images, {len(audio_urls)} audio files")
+
+        # Extract species name if possible
+        species_name = extract_species_name(raw_response)
+
+        # Create structured response using LlamaIndex Pydantic model
+        structured = BirdIdentificationResponse(
+            summary=raw_response,  # Keep full response as summary
+            species_name=species_name,
+            image_urls=image_urls,
+            audio_urls=audio_urls,
+            confidence_score=None  # Could extract with regex if needed
+        )
+
+        # Check if we found any media to format
+        if not structured.image_urls and not structured.audio_urls:
+            print("[STRUCTURED OUTPUT] No images or audio found, returning original")
+            return raw_response
+
+        # Reformat into markdown with guaranteed images
+        formatted_parts = []
+
+        # Main summary (but remove already-formatted images/audio to avoid duplication)
+        clean_summary = raw_response
+        for url in image_urls:
+            # Remove existing markdown images
+            clean_summary = re.sub(rf'!\[([^\]]*)\]\({re.escape(url)}\)', '', clean_summary)
+            # Remove plain URLs
+            clean_summary = clean_summary.replace(url, '')
+
+        for url in audio_urls:
+            # Remove audio URLs from summary
+            clean_summary = clean_summary.replace(url, '')
+
+        formatted_parts.append(clean_summary.strip())
+
+        # Add images with markdown syntax
+        if structured.image_urls:
+            formatted_parts.append("\n### Images\n")
+            for idx, url in enumerate(structured.image_urls, 1):
+                # Use species name if available, otherwise generic
+                alt_text = structured.species_name or f"Bird {idx}"
+                formatted_parts.append(f"![{alt_text}]({url})")
+
+        # Add audio links if present
+        if structured.audio_urls:
+            formatted_parts.append("\n### Audio Recordings\n")
+            for idx, url in enumerate(structured.audio_urls, 1):
+                # Strip /download from xeno-canto URLs for browser-friendly links
+                display_url = url.replace("/download", "") if "xeno-canto.org" in url else url
+                formatted_parts.append(f"🔊 [Listen to recording {idx}]({display_url})")
+
+        result = "\n\n".join(formatted_parts)
+        print(f"[STRUCTURED OUTPUT] ✅ Successfully formatted response")
+        return result
+
+    except Exception as e:
+        # Fallback: return original response if parsing fails
+        print(f"[STRUCTURED OUTPUT] ❌ Parsing failed: {e}")
+        return raw_response

langgraph_agent/subagent_config.py

@@ -0,0 +1,221 @@
+"""
+Specialized Subagent Configuration
+
+Defines specialized agents with focused tool subsets for better performance.
+Uses SubAgentMiddleware pattern from LangGraph deep agents.
+"""
+from typing import Dict, List
+from .config import AgentConfig
+from .prompts import NUTHATCH_BIRDSCOPE_PROMPT, AUDIO_FINDER_PROMPT
+
+
+class SubAgentConfig:
+    """Configuration for specialized subagents."""
+
+    @staticmethod
+    def get_mode_definitions() -> Dict[str, Dict]:
+        """
+        Define agent modes (how subagents are composed).
+
+        Returns:
+            Dict mapping mode names to their configurations
+        """
+        return {
+            "Specialized Subagents (3 Specialists)": {
+                "description": "Router orchestrates 3 specialized agents",
+                "subagents": ["image_identifier", "species_explorer", "taxonomy_specialist"],
+                "use_router": True
+            },
+            "Audio Finder Agent": {
+                "description": "Specialized agent for finding birds with audio recordings",
+                "subagents": ["generalist"],
+                "use_router": False
+            }
+        }
+
+    @staticmethod
+    def get_subagent_definitions() -> Dict[str, Dict]:
+        """
+        Define specialized subagents with their tool subsets and prompts.
+
+        Returns:
+            Dict mapping subagent names to their configurations
+        """
+        return {
+            "generalist": {
+                "name": "BirdScope AI Generalist",
+                "description": "All-in-one bird identification expert with access to all tools",
+                "tools": [
+                    "search_birds",  # Required to find any birds
+                    "get_bird_info", # Get details including audio count 
+                    "get_bird_audio" # Fetch actual audio recordings 
+                ],  
+                "prompt": AUDIO_FINDER_PROMPT, # We'll create this next
+                "temperature": AgentConfig.OPENAI_TEMPERATURE,
+            },
+            "image_identifier": {
+                "name": "Image Identification Specialist",
+                "description": "Expert at identifying birds from images and providing initial species information",
+                "tools": [
+                    "classify_from_url",
+                    "classify_from_base64",
+                    "get_bird_info",
+                    "get_bird_images"
+                ],
+                "prompt": """You are an Image Identification Specialist focused on bird recognition.
+**Your Role:**
+1. Use classification tools to identify birds from uploaded images
+2. Provide accurate species identification with confidence scores
+3. Fetch basic species information (taxonomy, size, status)
+4. Show reference images to help users verify identification
+
+**Response Style:**
+- Lead with the bird's common name and scientific name
+- Always cite confidence scores from classifier
+- Describe key identifying features visible in the image
+- Show reference images using markdown image syntax: ![Bird Name](image_url)
+- Mention if confidence is low and suggest why
+- Keep responses focused and concise
+
+**When to defer:**
+- For audio recordings -> species_explorer
+- For family/taxonomy queries -> taxonomy_specialist
+- For conservation status searches -> taxonomy_specialist
+""",
+                "temperature": AgentConfig.OPENAI_TEMPERATURE,
+            },
+            "species_explorer": {
+                "name": "Species Exploration Specialist",
+                "description": "Expert at finding birds by name, exploring families, and providing multimedia content",
+                "tools": [
+                    "search_birds",
+                    "get_bird_info",
+                    "get_bird_images",
+                    "get_bird_audio",
+                    "search_by_family"
+                ],
+                "prompt": """You are a Species Exploration specialist who helps users learn about birds.
+
+**Your Role:**
+1. Search for birds by common name or partial matches
+2. Provide comprehensive species profiles with images and audio
+3. Show related species in the same family
+4. Help users discover new birds based on their interests
+
+**Search Strategy (IMPORTANT):**
+- If a search returns no results, try progressively simpler queries:
+  * "Rock Dove" → try "Dove"
+  * "Northern Cardinal" → try "Cardinal"
+  * "Red-tailed Hawk" → try "Hawk"
+- Return the closest relevant match and explain what you found
+- If still no results, suggest similar species the user might be interested in
+
+**Response Style:**
+- Be enthusiastic and educational
+- Always provide images when available using markdown image syntax: ![Bird Name](image_url)
+- Offer audio recordings to help users learn bird calls (if available)
+- Suggest related species users might enjoy
+- Describe what makes each bird unique
+- If you had to search multiple times, mention it briefly: "I found information on Dove (the database uses this simplified name)"
+
+**When to defer:**
+- For image identification -> image_identifier
+- For conservation status filtering -> taxonomy_specialist
+- For broad taxonomy questions -> taxonomy_specialist
+""",
+                "temperature": 0.1,  # slightly creative for educational content
+            },
+            "taxonomy_specialist": {
+                "name": "Taxonomy & Conservation Specialist",
+                "description": "Expert at bird families, taxonomic classification, and conservation status",
+                "tools": [
+                    "filter_by_status",
+                    "search_by_family",
+                    "get_all_families",
+                    "get_bird_info"
+                ],
+                "prompt": """You are a Taxonomy & Conservation Specialist with deep knowledge of bird classification.
+
+**Your Role:**
+1. Explain bird family relationships and taxonomic structure
+2. Find birds by conservation status
+3. Provide comprehensive family overviews
+4. Educate users about bird conservation
+
+**Search Strategy (IMPORTANT):**
+- When searching by family name, if no results:
+  * Try variations: "Cardinalidae" → "Cardinal"
+  * Try broader terms: specific family → general group
+- Return the closest match and explain any differences
+- If user asks about a species but you only have family tools, get basic info with get_bird_info
+
+**Response Style:**
+- Use proper taxonomic terminology but explain it clearly
+- Emphasize conservation status and threats
+- Show how species relate within families
+- Provide context about family characteristics
+- Be educational but accessible
+- If you had to adjust the search, explain briefly: "The database lists this family as..."
+
+**When to defer:**
+- For image identification -> image_identifier
+- For audio or species discovery -> species_explorer
+- For specific species details -> species_explorer
+""",
+                "temperature": AgentConfig.OPENAI_TEMPERATURE,
+            }
+        }
+
+    @staticmethod
+    def get_router_prompt() -> str:
+        """
+        Prompt for the supervisor agent that routes to subagents.
+
+        Returns:
+            Supervisor agent system prompt
+        """
+        return """You are BirdScope AI Supervisor - an intelligent orchestrator for bird identification.
+
+**Your Team:**
+- **image_identifier**: Identifies birds from photos using ML classification
+- **species_explorer**: Searches species by name, provides multimedia (images/audio)
+- **taxonomy_specialist**: Conservation status, taxonomic families, classification
+
+**Your Role:**
+Analyze each user request and route it to the MOST appropriate specialist.
+
+**Routing Guidelines:**
+1. **Image uploads/URLs** → image_identifier (has classification tools)
+2. **"Show me"/"Find"/"Search" + species name** → species_explorer (has search tools)
+3. **"Audio"/"sound"/"call"/"song"** → species_explorer (has audio tools)
+4. **"Family"/"families" + broad questions** → taxonomy_specialist (has family tools)
+5. **"Conservation"/"endangered"/"threatened"** → taxonomy_specialist (has status filters)
+6. **"Related species"/"similar birds"** → species_explorer (explores connections)
+
+**Decision-making:**
+- Consider the user's INTENT, not just keywords
+- Route to ONE specialist at a time
+- Trust your specialists' expertise
+- After specialist responds, you can route follow-ups to different specialists
+
+**Important:**
+- Be decisive - route quickly
+- Don't duplicate specialist work - let them handle their domain
+- Synthesize multi-turn conversations if needed
+"""
+
+    @staticmethod
+    def get_mode_config(mode_name: str) -> Dict:
+        """
+        Get configuration for a specific mode.
+
+        Args:
+            mode_name: Name of the mode (e.g., "Single Agent (All Tools)")
+
+        Returns:
+            Mode configuration dict
+        """
+        modes = SubAgentConfig.get_mode_definitions()
+        if mode_name not in modes:
+            raise ValueError(f"Unknown mode: {mode_name}. Available: {list(modes.keys())}")
+        return modes[mode_name]

langgraph_agent/subagent_factory.py

@@ -0,0 +1,85 @@
+"""
+Subagent Factory
+
+Creates specialized agents with filtered tool subsets.
+"""
+from typing import List, Dict, Any
+from langchain_core.language_models import BaseChatModel
+from langchain.agents import create_agent
+from langgraph.checkpoint.memory import InMemorySaver
+from .subagent_config import SubAgentConfig
+from .config import AgentConfig
+
+class SubAgentFactory:
+    """Factory for creating specialized subagents."""
+
+    @staticmethod
+    async def create_subagent(
+        subagent_name: str,
+        all_tools: List[Any],
+        llm: BaseChatModel
+    ):
+        """
+        Create a specialized subagent with filtered tools.
+
+        Args:
+            subagent_name: Name of the subagent (e.g., "image_identifier")
+            all_tools: Full list of available tools
+            llm: Language model instance
+
+        Returns:
+            LangGraph agent configured for the subagent
+        """
+        # Get subagent configuration
+        definitions = SubAgentConfig.get_subagent_definitions()
+
+        if subagent_name not in definitions:
+            raise ValueError(f"Unknown subagent: {subagent_name}")
+
+        config = definitions[subagent_name]
+
+        # Filter tools for this subagent
+        allowed_tool_names = set(config["tools"])
+        subagent_tools = [
+            tool for tool in all_tools
+            if tool.name in allowed_tool_names
+        ]
+
+        print(f"[SUBAGENT]: Creating {config['name']}")
+        print(f"  • Tools: {', '.join([t.name for t in subagent_tools])}")
+
+        # Create specialized agent with filtered tools and name
+        # Note: create_agent auto-compiles, so we pass name directly
+        agent = create_agent(
+            model=llm,
+            tools=subagent_tools,
+            system_prompt=config["prompt"],
+            name=subagent_name
+        )
+
+        return agent
+
+    @staticmethod
+    async def create_all_subagents(
+        all_tools: List[Any],
+        llm: BaseChatModel
+    ) -> Dict[str, Any]:
+        """
+        Create all specialized subagents.
+
+        Args:
+            all_tools: Full list of available tools
+            llm: Language model instance
+
+        Returns:
+            Dict mapping subagent names to agent instances
+        """
+        definitions = SubAgentConfig.get_subagent_definitions()
+        subagents = {}
+
+        for name in definitions.keys():
+            subagents[name] = await SubAgentFactory.create_subagent(
+                name, all_tools, llm
+            )
+
+        return subagents

langgraph_agent/subagent_router.py.legacy

@@ -0,0 +1,91 @@
+"""
+Subagent Router
+
+Orchestrates routing between specialized subagents using LangGraph's
+delegation pattern.
+"""
+from typing import Dict, Any, List, Literal
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import HumanMessage, AIMessage, SystemMessage
+from langgraph.graph import StateGraph, MessagesState, START, END
+from langgraph.prebuilt import ToolNode
+from langgraph.checkpoint.memory import InMemorySaver
+from .subagent_config import SubAgentConfig
+from .subagent_factory import SubAgentFactory
+
+async def create_router_agent(all_tools: List[Any], llm: BaseChatModel):
+    """
+    Create a router agent that orchestrates specialized subagents.
+
+    Args:
+        all_tools: Full list of available MCP tools
+        llm: Language model for the router
+
+    Returns:
+        Compiled LangGraph workflow
+    """
+
+    async def router_node(state: MessagesState):
+        """Main router that delegates to subagents."""
+        # Get routing instructions
+        router_prompt = SubAgentConfig.get_router_prompt()
+
+        # Add system message with routing instructions
+        messages = [SystemMessage(content=router_prompt)] + state["messages"]
+
+        # Router decides which subagent to use
+        response = await llm.ainvoke(messages)
+
+        # Extract subagent name from response (you could make this more sophisticated)
+        # For now, the router will use tools to delegate
+        return {"messages": [response]}
+
+    async def create_subagent_node(subagent_name: str):
+        """Create a node for a specific subagent."""
+        async def subagent_node(state: MessagesState):
+            # Create the specialized subagent
+            subagent = await SubAgentFactory.create_subagent(
+                subagent_name, all_tools, llm
+            )
+
+            # Run the subagent
+            result = await subagent.ainvoke(state)
+            return result
+
+        return subagent_node
+
+    # Build the graph
+    workflow = StateGraph(MessagesState)
+
+    # Add nodes
+    workflow.add_node("router", router_node)
+    workflow.add_node("image_identifier", await create_subagent_node("image_identifier"))
+    workflow.add_node("species_explorer", await create_subagent_node("species_explorer"))
+    workflow.add_node("taxonomy_specialist", await create_subagent_node("taxonomy_specialist"))
+
+    # Define routing logic
+    def route_to_specialist(state: MessagesState) -> Literal["image_identifier", "species_explorer", "taxonomy_specialist", END]:
+        """Route based on last message content."""
+        last_message = state["messages"][-1]
+        content = last_message.content.lower()
+
+        # Simple keyword-based routing (could be improved with LLM classification)
+        if any(word in content for word in ["identify", "what bird", "classify", "image", "photo"]):
+            return "image_identifier"
+        elif any(word in content for word in ["audio", "sound", "call", "song", "find", "search"]):
+            return "species_explorer"
+        elif any(word in content for word in ["family", "families", "conservation", "endangered", "taxonomy"]):
+            return "taxonomy_specialist"
+        else:
+            # Default to species explorer for general queries
+            return "species_explorer"
+
+    # Connect nodes
+    workflow.add_edge(START, "router")
+    workflow.add_conditional_edges("router", route_to_specialist)
+    workflow.add_edge("image_identifier", END)
+    workflow.add_edge("species_explorer", END)
+    workflow.add_edge("taxonomy_specialist", END)
+
+    # Compile with memory for conversation context
+    return workflow.compile(checkpointer=InMemorySaver())

langgraph_agent/subagent_supervisor.py

@@ -0,0 +1,55 @@
+"""
+Subagent Supervisor
+
+Uses LangGraph's create_supervisor() for LLM-based routing between specialists.
+"""
+from typing import List, Any
+from langchain_core.language_models import BaseChatModel
+from langchain.agents import create_agent
+from langgraph.graph import StateGraph, MessagesState, START, END
+from langgraph.checkpoint.memory import InMemorySaver
+from .subagent_config import SubAgentConfig
+from .subagent_factory import SubAgentFactory
+
+async def create_supervisor_workflow(all_tools: List[Any], llm: BaseChatModel):
+    """
+    Create a supervisor workflow that orchestrates specialized subagents.
+
+    The supervisor uses LLM-based routing to delegate tasks to the most
+    appropriate specialist agent.
+
+    Args:
+        all_tools: Full list of available MCP tools
+        llm: Language model for both supervisor and subagents
+
+    Returns:
+        Compiled LangGraph workflow with supervisor
+    """
+    from langgraph_supervisor import create_supervisor
+
+    # Create the three specialist agents
+    print("[SUPERVISOR]: Creating specialist agents...")
+
+    image_agent = await SubAgentFactory.create_subagent(
+        "image_identifier", all_tools, llm
+    )
+    species_agent = await SubAgentFactory.create_subagent(
+        "species_explorer", all_tools, llm
+    )
+    taxonomy_agent = await SubAgentFactory.create_subagent(
+        "taxonomy_specialist", all_tools, llm
+    )
+
+    # Create supervisor with LLM-based routing
+    print("[SUPERVISOR]: Creating supervisor orchestrator...")
+
+    # create_supervisor takes a list of agents as first positional argument
+    workflow = create_supervisor(
+        [image_agent, species_agent, taxonomy_agent],
+        model=llm,
+        prompt=SubAgentConfig.get_router_prompt()
+    )
+
+    # Compile with shared memory for conversation context
+    print("[SUPERVISOR]: Compiling workflow with memory...")
+    return workflow.compile(checkpointer=InMemorySaver())

langgraph_agent/test_agent.py

@@ -0,0 +1,89 @@
+"""
+Test suite for bird classifier agents.
+"""
+import asyncio
+import sys
+from pathlib import Path
+
+# Add parent directory to path so imports work from any location
+parent_dir = Path(__file__).parent.parent
+if str(parent_dir) not in sys.path:
+    sys.path.insert(0, str(parent_dir))
+
+from langgraph_agent import AgentFactory
+
+
+async def test_classifier_agent():
+    """Test basic classifier agent with multiple images."""
+    
+    print("\n" + "="*70)
+    print("Test Suite: Basic Classifier Agent")
+    print("="*70 + "\n")
+    
+    # Create agent
+    agent = await AgentFactory.create_classifier_agent()
+    
+    test_urls = [
+        "https://images.unsplash.com/photo-1555169062-013468b47731?w=400",
+        "https://images.unsplash.com/photo-1445820200644-69f87d946277?w=400",
+    ]
+    
+    for i, url in enumerate(test_urls, 1):
+        print(f"\n[TEST {i}/{len(test_urls)}]")
+        print("="*70)
+        
+        result = await agent.ainvoke({
+            "messages": [{
+                "role": "user",
+                "content": f"Classify the bird in this image: {url}"
+            }]
+        })
+        
+        print(f"\n[RESULT]: {result['messages'][-1].content}\n")
+    
+    print("\n[ALL TESTS COMPLETE!]\n")
+
+
+async def test_multi_server_agent():
+    """Test multi-server agent with classifier + eBird."""
+    
+    print("\n" + "="*70)
+    print("Test Suite: Multi-Server Agent")
+    print("="*70 + "\n")
+    
+    # Create agent with memory
+    agent = await AgentFactory.create_multi_server_agent(with_memory=True)
+    config = {"configurable": {"thread_id": "test_session"}}
+    
+    # Test 1: Classify bird
+    print("\n[TEST 1]: Classify bird from URL")
+    print("="*70)
+    result1 = await agent.ainvoke({
+        "messages": [{
+            "role": "user",
+            "content": "What bird is this? https://images.unsplash.com/photo-1555169062-013468b47731?w=400"
+        }]
+    }, config)
+    print(f"\n[RESULT]: {result1['messages'][-1].content}\n")
+    
+    # Test 2: Ask follow-up (tests memory)
+    print("\n[TEST 2]: Follow-up question (tests memory)")
+    print("="*70)
+    result2 = await agent.ainvoke({
+        "messages": [{
+            "role": "user",
+            "content": "Where can I see this bird near Boston (42.36, -71.06)?"
+        }]
+    }, config)
+    print(f"\n[RESULT]: {result2['messages'][-1].content}\n")
+    
+    print("\n[ALL TESTS COMPLETE!]\n")
+
+
+if __name__ == "__main__":
+    import sys
+    
+    if len(sys.argv) > 1 and sys.argv[1] == "multi":
+        asyncio.run(test_multi_server_agent())
+    else:
+        asyncio.run(test_classifier_agent())

langgraph_agent/test_agent.py.v1

@@ -0,0 +1,36 @@
+"""
+Test script for bird classifier agent with multiple scenarios
+"""
+import asyncio
+from simple_demo import create_bird_agent
+
+async def test_agent():
+    """Test agent with multiple bird images."""
+
+    # Create agent once
+    agent = await create_bird_agent()
+
+    test_urls = [
+        "https://images.unsplash.com/photo-1555169062-013468b47731?w=400",
+        "https://images.unsplash.com/photo-1445820200644-69f87d946277?w=400&auto=format&fit=crop&q=60&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxzZWFyY2h8MTV8fGJpcmR8ZW58MHx8MHx8fDA%3D"
+    ]
+
+    for i, url in enumerate(test_urls, 1):
+        print("\n"+"="*70)
+        print(f"[TEST {i}/{len(test_urls)}]: Testing bird classification...")
+        print("="*70+"\n")
+        
+        result = await agent.ainvoke({
+            "messages": [{
+                "role": "user",
+                "content": f"Classify the bird in this image: {url}"
+            }]
+        })
+        
+        print("\n[AGENT RESPONSE]:")
+        print(result["messages"][-1].content)
+        
+    print("\n[DEMO COMPLETE!]")
+
+if __name__ == "__main__":
+    asyncio.run(test_agent())

modal_bird_classifier.py

@@ -0,0 +1,262 @@
+"""
+Bird Species Classifier MCP Server on Modal
+Updated to support:
+1. classify_from_base64() - for IDE/Cursor clients and Gradio
+2. classify_from_url() - for fallback/public images
+"""
+
+import modal
+from fastmcp import FastMCP
+import base64
+import json
+import httpx
+from io import BytesIO
+from PIL import Image
+import torch
+import os
+
+# ============================================================================
+# MODAL APP CONFIGURATION
+# ============================================================================
+
+app = modal.App("bird-classifier-mcp")
+
+image = modal.Image.debian_slim(python_version="3.12").pip_install(
+    "transformers==4.46.0",
+    "torch==2.5.1",
+    "pillow==10.4.0",
+    "fastmcp>=2.13.0",
+    "pydantic>=2.10.0,<3.0.0",
+    "fastapi==0.115.14",
+    "httpx>=0.28.0",
+)
+
+API_KEY_SECRET = modal.Secret.from_name("bird-classifier-api-key")
+
+# ============================================================================
+# MCP SERVER DEFINITION
+# ============================================================================
+
+def make_mcp_server():
+    """Create FastMCP server with bird classification tools."""
+    from transformers import pipeline
+
+    mcp = FastMCP("Bird Species Classifier")
+
+    print("🔄 Loading bird classifier model...")
+    classifier = pipeline(
+        "image-classification",
+        model="prithivMLmods/Bird-Species-Classifier-526",
+        device=0
+    )
+    print("✅ Model loaded!")
+
+    def preprocess_image(image: Image.Image, max_size: int = 800) -> Image.Image:
+        """Resize and convert to RGB."""
+        if image.mode != 'RGB':
+            image = image.convert('RGB')
+
+        if max(image.size) > max_size:
+            ratio = max_size / max(image.size)
+            new_size = (int(image.size[0] * ratio), int(image.size[1] * ratio))
+            image = image.resize(new_size, Image.Resampling.LANCZOS)
+
+        return image
+
+    # ========================================================================
+    # TOOL 1: classify_from_base64 (PRIMARY - for IDE/Gradio)
+    # ========================================================================
+
+    @mcp.tool()
+    async def classify_from_base64(image_data: str) -> str:
+        """
+        Classify a bird species from base64-encoded image data.
+
+        This is the primary tool for IDE clients and Gradio apps.
+        Accepts raw base64 or data URL format.
+
+        Args:
+            image_data: Base64-encoded image string (PNG/JPG)
+                       Can be raw base64 or "data:image/png;base64,..."
+
+        Returns:
+            JSON string with species name and confidence score
+            Format: {"species": "Common Name", "confidence": 0.95}
+        """
+        try:
+            # Handle data URL format
+            if image_data.startswith("data:"):
+                image_data = image_data.split(",")[1]
+
+            # Decode base64
+            print(f"[STATUS]: Decoding base64 image ({len(image_data)} chars)...")
+            image_bytes = base64.b64decode(image_data)
+            image = Image.open(BytesIO(image_bytes))
+            image = preprocess_image(image)
+
+            # Classify
+            print(f"[STATUS]: Classifying image...")
+            results = classifier(image, top_k=1)
+            top_result = results[0]
+
+            return json.dumps({
+                "species": top_result['label'],
+                "confidence": round(top_result['score'], 4),
+                "source": "base64"
+            })
+
+        except Exception as e:
+            return json.dumps({
+                "error": str(e),
+                "species": None,
+                "confidence": 0.0
+            })
+
+    # ========================================================================
+    # TOOL 2: classify_from_url (FALLBACK)
+    # ========================================================================
+
+    @mcp.tool()
+    async def classify_from_url(image_url: str) -> str:
+        """
+        Download image from URL and classify bird species.
+
+        Fallback tool for clients that have URL access.
+
+        Args:
+            image_url: URL to the image (https://example.com/bird.jpg)
+
+        Returns:
+            JSON string with species name and confidence score
+        """
+        try:
+            print(f"[STATUS]: Downloading from URL...")
+            response = httpx.get(image_url, follow_redirects=True, timeout=15)
+            response.raise_for_status()
+
+            image = Image.open(BytesIO(response.content))
+            image = preprocess_image(image)
+
+            results = classifier(image, top_k=1)
+            top_result = results[0]
+
+            return json.dumps({
+                "species": top_result['label'],
+                "confidence": round(top_result['score'], 4),
+                "source": "url"
+            })
+
+        except Exception as e:
+            return json.dumps({
+                "error": str(e),
+                "species": None,
+                "confidence": 0.0
+            })
+
+    return mcp
+
+# ============================================================================
+# WEB ENDPOINT WITH AUTHENTICATION
+# ============================================================================
+
+@app.function(
+    image=image,
+    #gpu="L40S",
+    gpu="T4",
+    secrets=[API_KEY_SECRET],
+    timeout=300,
+    min_containers=0,
+    max_containers=5,
+    scaledown_window=60,
+)
+@modal.asgi_app()
+def web():
+    """ASGI web endpoint for MCP server with API key auth."""
+    from fastapi import FastAPI, Request, HTTPException
+    from fastapi.responses import JSONResponse
+
+    print("[STATUS]: Starting MCP server...")
+
+    mcp = make_mcp_server()
+    mcp_app = mcp.http_app(transport="streamable-http", stateless_http=True)
+
+    from fastapi.middleware.cors import CORSMiddleware
+
+    fastapi_app = FastAPI(
+        title="Bird Classifier MCP Server",
+        description="MCP server for bird species classification",
+        lifespan=mcp_app.lifespan
+    )
+
+    @fastapi_app.middleware("http")
+    async def verify_api_key(request: Request, call_next):
+        """Verify API key on every request"""
+        api_key = request.headers.get("X-API-Key")
+        expected_key = os.environ.get("API_KEY")
+
+        if not api_key or api_key != expected_key:
+            return JSONResponse(
+                status_code=401,
+                content={"error": "Invalid or missing API key"}
+            )
+
+        return await call_next(request)
+
+    fastapi_app.mount("/", mcp_app)
+    
+    print("[STATUS]: MCP server is ready!")
+    return fastapi_app
+
+# ============================================================================
+# TEST FUNCTION
+# ============================================================================
+
+@app.function(image=image, secrets=[API_KEY_SECRET])
+async def test_classifier():
+    """Test MCP server"""
+    from fastmcp import Client
+    from fastmcp.client.transports import StreamableHttpTransport   
+
+    print("\n"+"="*70)
+    print("[STATUS]: Testing Bird Classifier MCP server...")    
+    print("="*70+"\n")
+
+    server_url = f"{web.get_web_url()}/mcp/"
+    
+    transport = StreamableHttpTransport(
+        url=server_url,
+        headers={"X-API-Key": os.environ.get("API_KEY")}
+    )
+
+    client = Client(transport)
+
+    try:
+        async with client:
+            # List tools
+            print("\nAvailable Tools:")
+            tools = await client.list_tools()
+            for tool in tools:
+                print(f"  - {tool.name}")
+
+            # Test classify_from_url
+            print("\n"+"="*70)
+            print("[TEST 1]: classify_from_url")
+            print("="*70)
+
+            test_url = "https://images.unsplash.com/photo-1444464666168-49d633b86797?w=400"
+            result = await client.call_tool(
+                "classify_from_url",
+                arguments={"image_url": test_url}
+            )
+
+            if result.content:
+                result_text = result.content[0].text
+                data = json.loads(result_text)
+                print(f"[RESULT]: {data.get('species')} ({data.get('confidence'):.1%})")
+
+    except Exception as e:
+        print(f"[ERROR]: {e}")
+
+    print("\n"+"="*70)
+    print("[STATUS]: Test complete!")
+    print("="*70+"\n")

nuthatch_tools.py

@@ -0,0 +1,737 @@
+"""
+Nuthatch MCP Server
+Wraps Nuthatch API v2.3.1 as reusable MCP tools
+Runs locally with FastMCP and supports STDIO transport
+
+Features:
+ - 7 core tools for bird species reference data
+ - Rich media: images (Unsplash) + audio (xeno-canto.org)
+ - Taxonomic search and conservation status filtering
+ - JSON responses for easy integration
+ - Rate limiting and error handling
+
+ Difference from eBird:
+     - eBird: Real-time sightings, location-based hotspots
+     - Nuthatch: Species reference, images, audio, taxonomy
+     - Focus: "what is this bird?" vs. "Where can I see it?"
+"""
+import os
+import sys
+import requests
+import json
+import time
+from typing import Optional, Dict, List, Any
+from fastmcp import FastMCP
+from dotenv import load_dotenv
+
+# ============================================================================
+# CONFIGURATION & SETUP
+# ============================================================================
+
+load_dotenv()
+
+NUTHATCH_API_KEY = os.getenv("NUTHATCH_API_KEY")
+NUTHATCH_BASE_URL = os.getenv("NUTHATCH_BASE_URL", "https://nuthatch.lastelm.software/v2")
+DEFAULT_TIMEOUT = 15
+# Rate limiting: 500 requests/hour = 7.2s safe, but 1s acceptable for demos
+# Demo sessions are bursty (5-10 requests in 30 seconds, then idle)
+# 1 second = 60 requests/minute max = 360/hour in worst case (still under 500)
+RATE_LIMIT_DELAY = 1.0  # Balance between responsiveness and API limits
+
+if not NUTHATCH_API_KEY:
+    # Print to stderr to avoid corrupting STDIO MCP protocol (stdout must be JSON-RPC only)
+    print("[WARNING]: NUTHATCH_API_KEY not found in .env", file=sys.stderr)
+    print("   Get one from: https://nuthatch.lastelm.software/", file=sys.stderr)
+
+# Tool configuration - enable/disable as needed
+ENABLED_TOOLS = {
+    "search_birds": True,
+    "get_bird_info": True,
+    "get_bird_images": True,
+    "get_bird_audio": True,
+    "search_by_family": True,
+    "filter_by_status": True,
+    "get_all_families": True,
+}
+
+# Authentication configuration for HTTP mode
+NUTHATCH_MCP_AUTH_KEY = os.getenv("NUTHATCH_MCP_AUTH_KEY")
+
+# Initialize FastMCP server with optional auth
+if NUTHATCH_MCP_AUTH_KEY:
+    # HTTP mode with authentication
+    from fastmcp.server.auth.providers.debug import DebugTokenVerifier
+
+    auth = DebugTokenVerifier(
+        validate=lambda token: token == NUTHATCH_MCP_AUTH_KEY,
+        client_id="nuthatch-mcp-client"
+    )
+    mcp = FastMCP("Nuthatch Bird Reference", auth=auth)
+else:
+    # Development: No authentication
+    mcp = FastMCP("Nuthatch Bird Reference")
+
+# Rate limiting tracker
+_last_request_time = 0
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ============================================================================
+
+def _rate_limit():
+    """Enforce rate limiting to avoid exceeding Nuthatch's API limits (500/hour)"""
+    global _last_request_time
+    elapsed = time.time() - _last_request_time
+    if elapsed < RATE_LIMIT_DELAY:
+        time.sleep(RATE_LIMIT_DELAY - elapsed)
+    _last_request_time = time.time()
+
+
+def _make_request(endpoint: str, params: Optional[Dict] = None) -> Optional[Dict]:
+    """
+    Centralized request handler with error handling and rate limiting.
+
+    IMPORTANT: Header name is case-sensitive! "API-Key"
+
+    Args:
+        endpoint: API endpoint path (e.g., "/birds")
+        params: Query parameters dictionary
+
+    Returns:
+        JSON response data or None on error
+    """
+    _rate_limit()
+    try:
+        headers = {"API-Key": NUTHATCH_API_KEY}  # Case-sensitive!
+        url = f"{NUTHATCH_BASE_URL}{endpoint}"
+        response = requests.get(
+            url,
+            headers=headers,
+            params=params or {},
+            timeout=DEFAULT_TIMEOUT,
+        )
+
+        if response.status_code == 200:
+            return response.json()
+        elif response.status_code == 400:
+            print(f" Bad Request ({url}): {response.text[:400]}", flush=True)
+            return None
+        elif response.status_code == 401:
+            print(f" Unauthorized ({url}): Check your NUTHATCH_API_KEY - body={response.text[:400]}", flush=True)
+            return None
+        elif response.status_code == 404:
+            print(f" Not found ({url}): Invalid endpoint or resource - body={response.text[:400]}", flush=True)
+            return None
+        else:
+            print(
+                f" HTTP {response.status_code} for {url} "
+                f"params={params or {}} body={response.text[:400]}",
+                flush=True,
+            )
+            return None
+
+    except requests.Timeout:
+        print(f" Request timeout after {DEFAULT_TIMEOUT}s for {endpoint}", flush=True)
+        return None
+    except requests.ConnectionError:
+        print(f" Connection error calling {endpoint} - check network", flush=True)
+        return None
+    except Exception as e:
+        print(f" Unexpected error calling {endpoint}: {str(e)}", flush=True)
+        return None
+
+
+def _format_success_response(data: Any, **kwargs) -> str:
+    """Format a successful response as JSON"""
+    response = {"status": "success", "data": data}
+    response.update(kwargs)
+    return json.dumps(response)
+
+
+def _format_error_response(error: str) -> str:
+    """Format an error response as JSON"""
+    return json.dumps({"status": "error", "error": error})
+
+
+# ============================================================================
+# TOOL 1: search_birds
+# ============================================================================
+# Use case: User asks "What cardinals exist?" or classifier returns "Northern Cardinal"
+# This tool provides multi-filter search across the species database
+
+def search_birds(
+    name: str = "",
+    family: str = "",
+    region: str = "",
+    status: str = "",
+    has_images: bool = True,
+    page_size: int = 10
+) -> str:
+    """
+    Search for bird species using multiple filters.
+
+    Comprehensive search tool that combines name, taxonomy, geography, and media filters.
+    Great for exploratory queries like "show me all cardinals" or "endangered birds".
+
+    Can accept:
+    - User input: "cardinals", "eagles", "finches"
+    - Classifier output: "Northern Cardinal" -> search for similar species
+    - Taxonomic queries: family="Cardinalidae"
+
+    Args:
+        name: Common or scientific name (partial match)
+        family: Scientific family name (e.g., "Cardinalidae", "Anatidae")
+        region: Geographic region ("North America", "Western Europe")
+        status: Conservation status ("Low Concern", "Endangered", etc.)
+        has_images: Only returns birds with images (default: True)
+        page_size: Maximum results to return (max: 100)
+
+    Returns:
+        JSON with matching birds and their basic info
+
+    Example:
+        search_birds(name="cardinal", has_images=True)
+        -> Returns all cardinal species with images
+    """
+    if not name and not family and not region and not status:
+        return _format_error_response("At least one search filter required")
+
+    if page_size > 100:
+        page_size = 100
+
+    try:
+        params = {"pageSize": page_size}
+        # Nuthatch API expects "true"/"false" strings, not Python booleans
+        if has_images is not None:
+            params["hasImg"] = "true" if has_images else "false"
+        if name:
+            # API is case-sensitive - convert to lowercase for reliable matching
+            params["name"] = name.lower()
+        if family:
+            # API is case-sensitive - convert to lowercase for reliable matching
+            params["family"] = family.lower()
+        if region:
+            params["region"] = region
+        if status:
+            params["status"] = status
+
+        data = _make_request("/birds", params)
+
+        if data is None:
+            return _format_error_response("Failed to fetch birds")
+
+        if not data.get('entities'):
+            return _format_success_response(
+                [],
+                count=0,
+                total_count=0,
+                filters={"name": name, "family": family, "region": region, "status": status}
+            )
+
+        # Format results with essential info
+        birds = [
+            {
+                "name": bird['name'],
+                "scientific_name": bird['sciName'],
+                "family": bird.get('family', 'Unknown'),
+                "order": bird.get('order', 'Unknown'),
+                "status": bird.get('status', 'Unknown'),
+                "region": bird.get('region', []),
+                "image_count": len(bird.get('images', [])),
+                "has_audio": len(bird.get('recordings', [])) > 0
+            }
+            for bird in data['entities']
+        ]
+
+        return _format_success_response(
+            birds,
+            count=len(birds),
+            total_count=data.get('totalCount', 0),
+            filters={"name": name, "family": family, "region": region, "status": status}
+        )
+
+    except Exception as e:
+        return _format_error_response(f"Search failed: {str(e)}")
+
+
+# Register as MCP tool
+mcp.tool()(search_birds)
+
+
+# ============================================================================
+# TOOL 2: get_bird_info
+# ============================================================================
+# Use case: After classifier identifies a bird, get complete species details
+
+def get_bird_info(name: str) -> str:
+    """
+    Get comprehensive information about a specific bird species.
+
+    Returns all available data: taxonomy, size, conservation status, 
+    image/audio counts, and geographic range.
+
+    Can accept:
+    - User input: "Northern Cardinal"
+    - Classifier output: Species name from image classification
+
+    Args:
+        name: Common or scientific name of the bird
+
+    Returns:
+        JSON with complete species information
+
+    Example:
+        get_bird_info("Northern Cardinal")
+        -> Returns full details: family, size, status, media counts, etc.
+    """
+    if not name or len(name.strip()) < 2:
+        return _format_error_response("Bird name required (minimum 2 characters)")
+
+    try:
+        # Search for exact or closest match
+        # API is case-sensitive - convert to lowercase for reliable matching
+        params = {"name": name.lower(), "pageSize": 1}
+        data = _make_request("/birds", params)
+
+        if data is None or not data.get('entities'):
+            return _format_error_response(f"Bird '{name}' not found in database")
+
+        bird = data['entities'][0]
+
+        # Compile comprehensive info
+        info = {
+            "name": bird['name'],
+            "scientific_name": bird['sciName'],
+            "family": bird.get('family', 'Unknown'),
+            "order": bird.get('order', 'Unknown'),
+            "status": bird.get('status', 'Unknown'),
+            "region": bird.get('region', []),
+            "length_cm": {
+                "min": bird.get('lengthMin'),
+                "max": bird.get('lengthMax')
+            } if bird.get('lengthMin') else None,
+            "wingspan_cm": {
+                "min": bird.get('wingspanMin'),
+                "max": bird.get('wingspanMax')
+            } if bird.get('wingspanMin') else None,
+            "image_count": len(bird.get('images', [])),
+            "audio_count": len(bird.get('recordings', [])),
+            "has_images": len(bird.get('images', [])) > 0,
+            "has_audio": len(bird.get('recordings', [])) > 0
+        }
+
+        return _format_success_response(info, bird_name=name)
+
+    except Exception as e:
+        return _format_error_response(f"Lookup failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(get_bird_info)
+    
+
+# ============================================================================
+# TOOL 3: get_bird_images
+# ============================================================================
+# Use case: Show reference images to compare with user's uploaded photo
+
+def get_bird_images(name: str, max_images: int = 5) -> str:
+    """
+    Get image URLs for a bird species.
+
+    Returns high-quality reference images from Unsplash and curator photos.
+    Perfect for visual comparison with user's uploaded photo.
+
+    Can accept:
+    - User input: "Show me pictures of a cardinal"
+    - Classifier output: Species name -> fetch reference images
+
+    Args:
+        name: Common or scientific name of the bird
+        max_images: Maximum number of image URLs to return (default: 5)
+
+    Returns:
+        JSON with image URLs and bird identification
+
+    Example:
+        get_bird_images("Northern Cardinal", max_images=3)
+        -> Returns 3 image URLs for visual comparison
+    """
+    if not name or len(name.strip()) < 2:
+        return _format_error_response("Bird name required (minimum 2 characters)")
+
+    try:
+        # API is case-sensitive - convert to lowercase for reliable matching
+        params = {"name": name.lower(), "pageSize": 1, "hasImg": "true"}
+        data = _make_request("/birds", params)
+
+        if data is None or not data.get('entities'):
+            return _format_error_response(f"Bird '{name}' not found or has no images")
+
+        bird = data['entities'][0]
+        images = bird.get('images', [])
+
+        if not images:
+            return _format_error_response(f"No images available for '{bird['name']}'")
+
+        return _format_success_response(
+            images[:max_images],
+            bird_name=bird['name'],
+            scientific_name=bird['sciName'],
+            total_images=len(images),
+            returned_count=min(len(images), max_images)
+        )
+
+    except Exception as e:
+        return _format_error_response(f"Image lookup failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(get_bird_images)
+
+# ============================================================================
+# TOOL 4: get_bird_audio
+# ============================================================================
+# Use case: Provide audio recordings so user can learn bird's call/song
+
+def get_bird_audio(name: str, max_recordings: int = 5) -> str:
+    """
+    Get audio recordings for a bird species.
+
+    Returns recordings from xeno-canto.org with location, date, and type info.
+    Great for learning bird calls and songs.
+
+    Can accept:
+    - User input: "What does a cardinal sound like?"
+    - Classifier output: Species name -> fetch audio examples
+
+    Args:
+        name: Common or scientific name of the bird
+        max_recordings: Maximum number of recordings to return (default: 5)
+
+    Returns:
+        JSON with recording metadata and download URLs
+
+    Example:
+        get_bird_audio("Northern Cardinal", max_recordings=3)
+        -> Returns 3 audio recordings with metadata
+    """
+    if not name or len(name.strip()) < 2:
+        return _format_error_response("Bird name required (minimum 2 characters)")
+
+    try:
+        # API is case-sensitive - convert to lowercase for reliable matching
+        params = {"name": name.lower(), "pageSize": 1}
+        data = _make_request("/birds", params)
+
+        if data is None or not data.get('entities'):
+            return _format_error_response(f"Bird '{name}' not found")
+
+        bird = data['entities'][0]
+        recordings = bird.get('recordings', [])
+
+        if not recordings:
+            return _format_error_response(f"No audio recordings available for '{bird['name']}'")
+
+        # Format recording info (keep essential fields only)
+        formatted_recordings = [
+            {
+                "type": rec.get('type', 'Unknown'),
+                "location": rec.get('loc', 'Unknown'),
+                "country": rec.get('cnt', 'Unknown'),
+                "date": rec.get('date', 'Unknown'),
+                "recordist": rec.get('rec', 'Unknown'),
+                "file_url": rec.get('file', ''),
+                "xeno_canto_url": rec.get('url', ''),
+                "quality": rec.get('q', ''),
+                "length": rec.get('length', 'Unknown')
+            }
+            for rec in recordings[:max_recordings]
+        ]
+
+        return _format_success_response(
+            formatted_recordings,
+            bird_name=bird['name'],
+            scientific_name=bird['sciName'],
+            total_recordings=len(recordings),
+            returned_count=min(len(recordings), max_recordings)
+        )
+
+    except Exception as e:
+        return _format_error_response(f"Audio lookup failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(get_bird_audio)
+    
+# ============================================================================
+# TOOL 5: search_by_family
+# ============================================================================
+# Use case: "Show me all birds in the same family as this cardinal"
+
+def search_by_family(family_name: str, max_results: int = 20) -> str:
+    """
+    Get all bird species in a taxonomic family.
+
+    Great for exploring related species after identifying a bird.
+    Example: "This is a cardinal. What other cardinals exist?"
+
+    Can accept:
+    - User input: "Show me all finches"
+    - Derived from classification: After identifying a Cardinalidae member
+
+    Args:
+        family_name: Scientific family name (e.g., "Cardinalidae", "Fringillidae")
+        max_results: Maximum species to return (default: 20)
+
+    Returns:
+        JSON with all species in that family
+
+    Example:
+        search_by_family("Cardinalidae")
+        -> Returns Northern Cardinal, Pyrrhuloxia, Rose-breasted Grosbeak, etc.
+    """
+    if not family_name or len(family_name.strip()) < 2:
+        return _format_error_response("Family name required (minimum 2 characters)")
+
+    try:
+        # API is case-sensitive - convert to lowercase for reliable matching
+        params = {"family": family_name.lower(), "pageSize": min(max_results, 100)}
+        data = _make_request("/birds", params)
+
+        if data is None:
+            return _format_error_response("Failed to fetch family data")
+
+        if not data.get('entities'):
+            return _format_error_response(f"No birds found in family '{family_name}'")
+
+        # Format family members
+        birds = [
+            {
+                "name": bird['name'],
+                "scientific_name": bird['sciName'],
+                "status": bird.get('status', 'Unknown'),
+                "region": bird.get('region', []),
+                "has_images": len(bird.get('images', [])) > 0,
+                "has_audio": len(bird.get('recordings', [])) > 0
+            }
+            for bird in data['entities']
+        ]
+
+        return _format_success_response(
+            birds,
+            family=family_name,
+            count=len(birds),
+            total_count=data.get('totalCount', 0)
+        )
+
+    except Exception as e:
+        return _format_error_response(f"Family search failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(search_by_family)
+
+# ============================================================================
+# TOOL 6: filter_by_status
+# ============================================================================
+# Use case: "Show me endangered birds" or conservation awareness
+
+def filter_by_status(status: str, region: str = "", max_results: int = 20) -> str:
+    """
+    Find birds by conservation status.
+
+    Great for conservation awareness and educational purposes.
+    Common statuses: "Low Concern", "Endangered", "Threatened", "Vulnerable"
+
+    Can accept:
+    - User input: "Show me endangered birds"
+    - Educational queries: "What birds are threatened?"
+
+    Args:
+        status: Conservation status to filter by
+        region: Optional geographic filter ("North America", "Western Europe")
+        max_results: Maximum birds to return (default: 20)
+
+    Returns:
+        JSON with birds matching the conservation status
+
+    Example:
+        filter_by_status("Endangered", region="North America")
+        -> Returns endangered birds in North America
+    """
+    if not status or len(status.strip()) < 2:
+        return _format_error_response("Conservation status required")
+
+    try:
+        params = {"status": status, "pageSize": min(max_results, 100)}
+        if region:
+            params["region"] = region
+
+        data = _make_request("/birds", params)
+
+        if data is None:
+            return _format_error_response("Failed to fetch status data")
+
+        if not data.get('entities'):
+            return _format_error_response(
+                f"No birds found with status '{status}'"
+                + (f" in region '{region}'" if region else "")
+            )
+        # Format results
+        birds = [
+            {
+                "name": bird['name'],
+                "scientific_name": bird['sciName'],
+                "family": bird.get('family', 'Unknown'),
+                "status": bird.get('status', 'Unknown'),
+                "region": bird.get('region', []),
+                "has_images": len(bird.get('images', [])) > 0
+            }
+            for bird in data['entities']
+        ]
+
+        return _format_success_response(
+            birds,
+            status=status,
+            region=region or "All regions",
+            count=len(birds),
+            total_count=data.get('totalCount', 0)
+        )
+
+    except Exception as e:
+        return _format_error_response(f"Status filter failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(filter_by_status)
+
+# ============================================================================
+# TOOL 7: get_all_families
+# ============================================================================
+# Use case: "What bird families are in the database?"
+
+def get_all_families(region: str = "") -> str:
+    """
+    Get list of all unique bird families in the database.
+
+    Useful for taxonomic exploration and understanding database coverage.
+
+    Can accept:
+    - User input: "What families are covered?"
+    - Educational queries: "Show me all bird families"
+
+    Args:
+        region: Optional geographic filter ("North America", "Western Europe")
+
+    Returns:
+        JSON with unique family names
+
+    Example:
+        get_all_families(region="North America")
+        -> Returns ["Anatidae", "Cardinalidae", "Fringillidae", ...]
+    """
+    try:
+        # Fetch large sample to get comprehensive family list
+        params = {"pageSize": 100}
+        if region:
+            params["region"] = region
+
+        data = _make_request("/birds", params)
+
+        if data is None:
+            return _format_error_response("Failed to fetch family data")
+
+        if not data.get('entities'):
+            return _format_error_response("No birds found")
+
+        # Extract unique families
+        families = list(set(
+            bird.get('family', 'Unknown')
+            for bird in data['entities']
+            if bird.get('family')
+        ))
+        families.sort()
+
+        return _format_success_response(
+            families,
+            region=region or "All regions",
+            count=len(families),
+            note="This is a sample - database may contain more families"
+        )
+
+    except Exception as e:
+        return _format_error_response(f"Family listing failed: {str(e)}")
+
+# Register as MCP tool
+mcp.tool()(get_all_families)
+
+# ============================================================================
+# SERVER STARTUP WITH STDIO TRANSPORT
+# ============================================================================
+
+def main():
+    """Start the MCP server with dual transport support (STDIO or HTTP)."""
+    # Determine transport mode from command line args
+    is_http_mode = "--http" in sys.argv or "--streamable-http" in sys.argv
+
+    # For STDIO mode, all informational output must go to stderr (stdout is for JSON-RPC only)
+    # For HTTP mode, can use stdout
+    output = sys.stdout if is_http_mode else sys.stderr
+
+    print("\n"+"="*70, file=output)
+    print("🐦 [NUTHATCH MCP SERVER] - Starting...", file=output)
+    print("="*70, file=output)
+    print(f"[API KEY]:    {'✅ Configured' if NUTHATCH_API_KEY else '❌ Missing'}", file=output)
+    print("\n[AVAILABLE TOOLS]:", file=output)
+
+    tools_list = [
+        "1. search_birds - Multi-filter bird search",
+        "2. get_bird_info - Complete species information",
+        "3. get_bird_images - Reference image URLs",
+        "4. get_bird_audio - Audio recordings from xeno-canto",
+        "5. search_by_family - All species in taxonomic family",
+        "6. filter_by_status - Birds by conservation status",
+        "7. get_all_families - List all bird families"
+    ]
+
+    for tool in tools_list:
+        print(f"  ✓ {tool}", file=output)
+
+    print("\n[DATA SOURCE]:", file=output)
+    print("  • Images: Unsplash + curator photos", file=output)
+    print("  • Audio: xeno-canto.org recordings", file=output)
+    print("  • Coverage: 1000+ species (North America, Western Europe)", file=output)
+
+    print("\n"+"="*70, file=output)
+
+    if is_http_mode:
+        # Extract port and host from command line args
+        port = 8001  # Default to 8001 to avoid conflict with other MCP servers
+        host = "127.0.0.1"
+
+        for i, arg in enumerate(sys.argv):
+            if arg == "--port" and i + 1 < len(sys.argv):
+                port = int(sys.argv[i + 1])
+            elif arg == "--host" and i + 1 < len(sys.argv):
+                host = sys.argv[i + 1]
+
+        # Auth status based on initialization
+        auth_status = "🔒 Protected (auth required)" if NUTHATCH_MCP_AUTH_KEY else "🔓 No authentication (development mode)"
+
+        print("[TRANSPORT]: Starting streamable-http MCP server", file=output)
+        print(f"[HOST]:      {host}", file=output)
+        print(f"[PORT]:      {port}", file=output)
+        print(f"[URL]:       http://{host}:{port}", file=output)
+        print(f"[AUTH]:      {auth_status}", file=output)
+        print("[NOTE]:      This is MCP over HTTP for web clients", file=output)
+        print("="*70+"\n", file=output)
+
+        # Run with streamable-http transport (auth configured at FastMCP init)
+        mcp.run(transport="streamable-http", host=host, port=port)
+    else:
+        print("[TRANSPORT]: Running as stdio MCP server", file=output)
+        print("[NOTE]:      For HTTP transport, use: python nuthatch_tools.py --http", file=output)
+        print("="*70+"\n", file=output)
+
+        # Run as stdio MCP server (default for agent integration)
+        mcp.run(transport="stdio")
+
+if __name__ == "__main__":
+    main()
+

requirements.txt

@@ -0,0 +1,24 @@
+gradio[mcp]==6.0.1
+huggingface_hub>=0.30.0
+transformers==4.45.0
+torch==2.2.2
+accelerate==0.34.0
+numpy<2.0.0
+spaces>=0.30.0
+langgraph>=0.0.1
+fastmcp==2.13.1
+mcp==1.21.2
+pydantic>=2.0.0
+langchain-mcp-adapters==0.1.13
+langchain-openai==1.0.3
+langchain-huggingface==1.1.0
+langchain==1.0.8
+langgraph-supervisor==0.0.31
+langchain-anthropic==1.2.0
+llama-index==0.14.8
+llama-index-llms-openai==0.6.10
+llama-index-llms-anthropic==0.10.3
+
+python-dotenv>=1.0.0
+Pillow>=10.0.0
+modal>=1.2.0

test_file.py

@@ -0,0 +1 @@
+Hello World !

tests/test_agent_cache.py

@@ -0,0 +1,90 @@
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# Add parent directory to sys.path so we can import ebird_tools
+parent_dir = Path(__file__).parent.parent
+sys.path.insert(0, str(parent_dir))
+
+from langgraph_agent import AgentFactory
+from agent_cache import get_or_create_agent, get_cache_stats
+
+async def test_cache():
+    # Test data
+    session_id = "test_session_123"
+    openai_key = os.environ.get("OPENAI_API_KEY")
+
+    # Check for API key (similar to main app)
+    if not openai_key:
+        print("❌ OPENAI_API_KEY environment variable not set!")
+        print("Please set your OpenAI API key to run this test.")
+        print("Example: export OPENAI_API_KEY='sk-your-key-here'")
+        return
+
+    print("="*50)
+    print("[TEST 1]: Create agent (cache miss)")
+    print("="*50)
+
+    agent1 = await get_or_create_agent(
+        session_id=session_id,
+        provider="openai",
+        api_key=openai_key,
+        model="gpt-4o-mini",
+        mode="Specialized Subagents (3 Specialists)",
+        agent_factory_method=lambda: AgentFactory.create_subagent_orchestrator(
+            model="gpt-4o-mini",
+            api_key=openai_key,
+            provider="openai",
+            mode="Specialized Subagents (3 Specialists)"
+        )
+    )
+
+    print(f"\nCache stats: {get_cache_stats()}")
+
+    print("\n"+"="*50)
+    print("[TEST 2: Get same agent (cache hit)")
+    print("="*50)
+
+    agent2 = await get_or_create_agent(
+        session_id=session_id,
+        provider="openai",
+        api_key=openai_key,
+        model="gpt-4o-mini",
+        mode="Specialized Subagents (3 Specialists)",
+        agent_factory_method=lambda: AgentFactory.create_subagent_orchestrator(
+            model="gpt-4o-mini",
+            api_key=openai_key,
+            provider="openai",
+            mode="Specialized Subagents (3 Specialists)"
+        )
+    )
+
+    print(f"\nCache stats: {get_cache_stats()}")
+
+    # Verify they're the same object
+    print(f"\nSame agent object? {agent1 is agent2}")
+
+    print("\n"+"="*50)
+    print("[TEST 3]: Different session (cache miss)")
+    print("=" * 50)
+
+    agent3 = await get_or_create_agent(
+        session_id="different_session_456",
+        provider="openai",
+        api_key=openai_key,
+        model="gpt-4o-mini",
+        mode="Specialized Subagents (3 Specialists)",
+        agent_factory_method=lambda: AgentFactory.create_subagent_orchestrator(
+            model="gpt-4o-mini",
+            api_key=openai_key,
+            provider="openai",
+            mode="Specialized Subagents (3 Specialists)"
+        )
+    )
+
+    print(f"\nCache stats: {get_cache_stats()}")
+
+asyncio.run(test_cache())

tests/test_modal_direct.py

@@ -0,0 +1,283 @@
+"""
+Simple test script for Modal Bird Classifier MCP Server
+Tests the deployed Modal server directly with both tools
+"""
+import asyncio
+import base64
+import json
+import os
+from io import BytesIO
+from pathlib import Path
+from PIL import Image
+from dotenv import load_dotenv
+
+from fastmcp import Client
+from fastmcp.client.transports import StreamableHttpTransport
+
+load_dotenv()
+
+# ============================================================================
+# CONFIGURATION
+# ============================================================================
+
+MODAL_MCP_URL = os.getenv("MODAL_MCP_URL")
+BIRD_API_KEY = os.getenv("BIRD_CLASSIFIER_API_KEY")
+
+print("="*70)
+print("[STATUS]: Testing Classifier Modal MCP Server...")
+print("="*70)
+print(f"[MODAL URL]: {MODAL_MCP_URL}")
+print(f"[API KEY]: {'Set' if BIRD_API_KEY else 'Missing'}")
+print("="*70)
+
+if not MODAL_MCP_URL or not BIRD_API_KEY:
+    print("\n[ERROR]: Missing MODAL_MCP_URL or BIRD_CLASSIFIER_API_KEY in .env")
+    print(" Set these in your .env file:")
+    print(" MODAL_MCP_URL=https://your-username--bird-classifier-mcp-web.modal.run/mcp/")
+    print(" BIRD_CLASSIFIER_API_KEY=your-api-key")
+    exit(1)
+
+# ============================================================================
+# HELPER FUNCTIONS
+# ===========================================================================
+
+def image_to_base64(image_path: str) -> str:
+    """Convert image file to base64 string."""
+    image = Image.open(image_path)
+
+    # Resize if too large
+    if max(image.size) > 800:
+        ratio = 800 / max(image.size)
+        new_size = (int(image.size[0] * ratio), int(image.size[1] * ratio))
+        image = image.resize(new_size, Image.Resampling.LANCZOS)
+
+    # Convert to RGB
+    if image.mode != 'RGB':
+        image = image.convert('RGB')
+
+    # Compress as JPEG
+    buffered = BytesIO()
+    image.save(buffered, format="JPEG", quality=85, optimize=True)
+    img_base64 = base64.b64encode(buffered.getvalue()).decode()
+
+    return img_base64
+
+# ============================================================================
+# TEST FUNCTIONS
+# ============================================================================
+
+async def test_list_tools():
+    """Test: List available tools on Modal server"""
+    print("\n"+"="*70)
+    print("[TEST 1]: List Available Tools")
+    print("="*70)
+
+    try:
+        transport = StreamableHttpTransport(
+            url=MODAL_MCP_URL,
+            headers={"X-API-Key": BIRD_API_KEY}
+        )
+
+        client = Client(transport)
+
+        async with client:
+            tools = await client.list_tools()
+            print(f"\n[✅ FOUND]: {len(tools)} tools:")
+            for tool in tools:
+                print(f"  - {tool.name}")
+                print(f".   {tool.description[:60]}...")
+
+        print("\n[✅ TEST 1 PASSED]")
+        return True
+
+    except Exception as e:
+        print(f"\n[❌TEST 1 FAILED]: {e}")
+        return False
+
+async def test_classify_from_url():
+    """Test: Classify bird from URL"""
+    print("\n"+"="*70)
+    print("[TEST 2]: Classify Bird from URL")
+    print("="*70)
+
+    try:
+        #test_url = "https://images.unsplash.com/photo-1444464666168-49d633b86797?w=400"
+        test_url = "https://images.unsplash.com/photo-1551085254-e96b210db58a?q=80&w=680&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D"
+        print(f"\nURL: {test_url[:60]}...")
+
+        transport = StreamableHttpTransport(
+            url=MODAL_MCP_URL,
+            headers={"X-API-Key": BIRD_API_KEY}
+        )
+
+        client = Client(transport)
+
+        async with client:
+            result = await client.call_tool(
+                "classify_from_url",
+                arguments={"image_url": test_url}
+            )
+
+            if not result.content:
+                print("❌ No response from server")
+                return False
+
+            result_text = result.content[0].text if hasattr(result.content[0], 'text') else str(result.content[0])
+            data = json.loads(result_text)
+
+            if "error" in data:
+                print("❌ [ERROR]: Server error: {data['error']}")
+                return False
+
+            print(f"\n✅ [CLASSIFICATION RESULT]:")
+            print(f"  Species: {data.get('species')}")
+            print(f"  Confidence: {data.get('confidence'):.1%}")
+            print(f"  Source: {data.get('source')}")
+
+        print("\n✅ TEST 2 PASSED")
+        return True
+
+    except Exception as e:
+        print(f"\n❌ TEST 2 FAILED: {e}")
+        import traceback
+        return False
+
+async def test_classify_from_base64_with_local_file():
+    """Test: Classify bird from local file (converted to base64)."""
+    print("\n"+"="*70)
+    print("[TEST 3]: Classify Bird from Local File (base64)")
+    print("="*70)
+
+    try:
+        # Find a test image
+        test_image = Path("/Users/jacobbinder/Desktop/hackathon/hackathon_draft/examples/another_bird.jpg")
+
+        if not test_image.exists():
+            print(f"\n[ERROR]: Test image not found: {test_image}")
+            print("  Skipping test 3...")
+            print("\n[TEST 3 SKIPPED]")
+            return True
+
+        print(f"\nFile: {test_image.name}")
+
+        # Convert to base64
+        print("[STATUS]: Converting image to base64...")
+        img_base64 = image_to_base64(str(test_image))
+        print(f"Base64 size: {len(img_base64) / 1024:.1f} KB")
+
+        transport = StreamableHttpTransport(
+            url=MODAL_MCP_URL,
+            headers={"X-API-Key": BIRD_API_KEY}
+        )
+
+        client = Client(transport)
+
+        async with client:
+            print("[STATUS]:Sending to Modal server...")
+            result = await client.call_tool(
+                "classify_from_base64",
+                arguments={"image_data": img_base64}
+            )
+
+            if not result.content:
+                print("❌ [ERROR]: No response from server")
+                return False
+
+            result_text = result.content[0].text if hasattr(result.content[0], 'text') else str(result.content[0])
+            data = json.loads(result_text)
+
+            if "error" in data:
+                print(f"[SERVER ERROR]: {data['error']}")
+                return False
+
+            print(f"\n[CLASSIFICATION RESULT]:")
+            print(f"  Species: {data.get('species')}")
+            print(f"  Confidence: {data.get('confidence'):.1%}")
+            print(f"  Source: {data.get('source')}")
+
+        print("\n✅ [TEST 3 PASSED]")
+        return True
+
+    except Exception as e:
+        print(f"\n❌ [TEST 3 FAILED]")
+        import traceback
+        traceback.print_exc()
+        return False
+
+async def test_auth_failure():
+    """Test: Verify API key authentication work."""
+    print("\n"+"="*70)
+    print("[TEST 4]: API Key Authentication")
+    print("="*70)
+
+    try:
+        print("\nTesting with INVALID API key...")
+
+        transport = StreamableHttpTransport(
+            url=MODAL_MCP_URL,
+            headers={"X-API-Key": "invalid-key-123"}
+        )
+
+        client = Client(transport)
+
+        async with client:
+            # Try to list tool - should fail with 401
+            tools = await client.list_tools()
+            print("❌ Should have failed with 401")
+            return False
+
+    except Exception as e:
+        if "401" in str(e) or "Unauthorized" in str(e) or "Invalid" in str(e):
+            print(f"✅ Correctly rejected invalid API key: {str(e)[:60]}...")
+            print("\n✅ [TEST 4 PASSED]")
+            return True
+        else:
+            print(f"❌ [ERROR]: {e}")
+            return False
+
+
+# ============================================================================
+# MAIN
+# ============================================================================
+
+async def main():
+    """Run all tests"""
+    print("\n")
+
+    results = []
+
+    # Test 1: List tools
+    results.append(("[TEST 1]: List Tools", await test_list_tools()))
+
+    # Test 2: Classify from URL
+    results.append(("[TEST 2]: Classify from URL", await test_classify_from_url()))
+
+    # Test 3: Classify from base64
+    results.append(("[TEST 3]: Classify from Base64", await test_classify_from_base64_with_local_file()))
+
+    # Test 4: Auth
+    results.append(("[TEST 4]: API Key Auth", await test_auth_failure()))
+
+    # Summary
+    print("\n"+"="*70)
+    print("[TEST SUMMARY]")
+    print("="*70)
+
+    passed = sum(1 for _, result in results if result)
+    total = len(results)
+
+    for test_name, result in results:
+        status = "✅ [PASS]" if result else "❌ [FAIL]"
+        print(f"{status}: {test_name}")
+
+    print(f"\n[TOTAL]: {passed}/{total} tests passed")
+
+    if passed == total:
+        print("\n🎉 All tests passed! Modal server is working correctly!")
+    else:
+        print(f"\n⚠️ {total - passed} test(s) failed. Check configuration and server status.")
+
+    print("="*70+"\n")
+
+if __name__ == "__main__":
+    asyncio.run(main())

tests/test_nuthatch.py

@@ -0,0 +1,205 @@
+"""
+Nuthatch MCP Integration Test
+
+Tests the Nuthatch species database MCP server with both STDIO and HTTP transports.
+
+Usage:
+    # Test with current .env configuration (STDIO or HTTP)
+    python tests/test_nuthatch.py
+
+    # Test both STDIO and HTTP modes sequentially
+    python tests/test_nuthatch.py --both
+
+Configuration (.env):
+    # For STDIO mode (default - subprocess integration)
+    NUTHATCH_USE_STDIO=true
+    NUTHATCH_API_KEY=<your-key>
+    NUTHATCH_BASE_URL=https://nuthatch.lastelm.software/v2
+
+    # For HTTP mode (external server)
+    NUTHATCH_USE_STDIO=false
+    NUTHATCH_MCP_URL=http://localhost:8001/mcp
+    NUTHATCH_MCP_AUTH_KEY=<optional-auth-key>
+
+    # Also required (Modal classifier)
+    MODAL_MCP_URL=<your-modal-url>
+    BIRD_CLASSIFIER_API_KEY=<your-modal-key>
+
+HTTP Mode Setup:
+    # Start Nuthatch HTTP server in separate terminal:
+    NUTHATCH_API_KEY=<your-key> python nuthatch_tools.py --http --port 8001
+
+    # With auth protection:
+    NUTHATCH_API_KEY=<your-key> NUTHATCH_MCP_AUTH_KEY=<auth-key> python nuthatch_tools.py --http --port 8001
+"""
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# Add parent directory to sys.path so we can import modules
+parent_dir = Path(__file__).parent.parent
+sys.path.insert(0, str(parent_dir))
+
+from langgraph_agent import AgentFactory
+from agent_cache import get_or_create_agent, cleanup_old_agents, get_cache_stats
+from langgraph_agent.mcp_clients import MCPClientManager
+from langgraph_agent.config import AgentConfig
+
+load_dotenv()
+
+def validate_config():
+    """Validate required configuration is present."""
+    errors = []
+
+    # Critical checks
+    if not AgentConfig.MODAL_MCP_URL:
+        errors.append("MODAL_MCP_URL not set")
+    if not AgentConfig.BIRD_CLASSIFIER_API_KEY:
+        errors.append("BIRD_CLASSIFIER_API_KEY not set")
+    if not AgentConfig.NUTHATCH_API_KEY:
+        errors.append("NUTHATCH_API_KEY not set")
+
+    # HTTP mode specific checks
+    if not AgentConfig.NUTHATCH_USE_STDIO:
+        if not AgentConfig.NUTHATCH_MCP_URL:
+            errors.append("NUTHATCH_MCP_URL required for HTTP mode")
+        if AgentConfig.NUTHATCH_MCP_URL == "http://localhost:8001/mcp":
+            print("\n⚠️  WARNING: Using default NUTHATCH_MCP_URL (localhost:8001)")
+            print("   Make sure nuthatch_tools.py is running with: python nuthatch_tools.py --http --port 8001")
+
+    if errors:
+        print("\n❌ Configuration Errors:")
+        for error in errors:
+            print(f"  • {error}")
+        print("\n💡 Check your .env file or environment variables")
+        return False
+
+    return True
+
+async def test_nuthatch():
+    print("="*70)
+    print("Testing Nuthatch MCP Integration")
+    print("="*70)
+
+    # Validate configuration
+    if not validate_config():
+        print("\n❌ Test aborted due to configuration errors")
+        return
+
+    # Show configuration
+    print("\n[CONFIG] Transport Configuration:")
+    print(f"  • NUTHATCH_USE_STDIO: {AgentConfig.NUTHATCH_USE_STDIO}")
+    print(f"  • NUTHATCH_API_KEY: {'✅ Set' if AgentConfig.NUTHATCH_API_KEY else '❌ Not set'}")
+    print(f"  • NUTHATCH_BASE_URL: {AgentConfig.NUTHATCH_BASE_URL}")
+
+    if AgentConfig.NUTHATCH_USE_STDIO:
+        print(f"  • Transport Mode: STDIO (subprocess)")
+        print(f"  • Command: python nuthatch_tools.py")
+    else:
+        print(f"  • Transport Mode: HTTP (external server)")
+        print(f"  • MCP URL: {AgentConfig.NUTHATCH_MCP_URL}")
+        print(f"  • Auth: {'🔒 Protected' if AgentConfig.NUTHATCH_MCP_AUTH_KEY else '🔓 No auth'}")
+
+    # Create multi-server client (Modal + Nuthatch)
+    print("\n[1] Creating MCP client...")
+    client = await MCPClientManager.create_multi_server_client()
+
+    # Get tools
+    print("\n[2] Loading tools...")
+    tools = await MCPClientManager.get_tools(client)
+
+    print(f"\n[3] Total tools available: {len(tools)}")
+
+    # Separate tools by source
+    classifier_tools = [t for t in tools if 'classify' in t.name.lower()]
+    # Nuthatch tools = everything except classifier tools
+    nuthatch_tools = [t for t in tools if 'classify' not in t.name.lower()]
+
+    print(f"\n📊 Classifier tools ({len(classifier_tools)}):")
+    for tool in classifier_tools:
+        print(f"  - {tool.name}")
+
+    print(f"\n🐦 Nuthatch tools ({len(nuthatch_tools)}):")
+    for tool in nuthatch_tools:
+        print(f"  - {tool.name}")
+
+    # Test a Nuthatch tool
+    print(f"\n[4] Testing search_birds tool...")
+
+    try:
+        # Find the search_birds tool (it's a LangChain Tool object)
+        search_tool = None
+        for tool in tools:
+            if tool.name == "search_birds":
+                search_tool = tool
+                break
+
+        if not search_tool:
+            print(f"\n❌ search_birds tool not found!")
+        else:
+            # Invoke the tool directly with arguments
+            result = await search_tool.ainvoke({"name": "Blue Jay", "page_size": 3})
+            print(f"\n✅ Tool call successful!")
+            print(f"Result preview:\n{result[:400]}...")
+    except Exception as e:
+        print(f"\n❌ Tool call failed: {e}")
+        import traceback
+        traceback.print_exc()
+
+    print("\n"+"="*70)
+    print("Integration test complete!")
+    print("="*70)
+
+async def test_both_transports():
+    """Test both STDIO and HTTP transports sequentially."""
+    print("\n" + "="*70)
+    print("Testing BOTH Transport Modes (STDIO + HTTP)")
+    print("="*70)
+
+    original_stdio_mode = AgentConfig.NUTHATCH_USE_STDIO
+
+    # Test 1: STDIO mode
+    print("\n\n### TEST 1: STDIO Transport ###")
+    AgentConfig.NUTHATCH_USE_STDIO = True
+    try:
+        await test_nuthatch()
+    except Exception as e:
+        print(f"\n❌ STDIO test failed: {e}")
+        import traceback
+        traceback.print_exc()
+
+    # Test 2: HTTP mode (only if server is configured)
+    if AgentConfig.NUTHATCH_MCP_URL and AgentConfig.NUTHATCH_MCP_URL != "http://localhost:8001/mcp":
+        print("\n\n### TEST 2: HTTP Transport ###")
+        AgentConfig.NUTHATCH_USE_STDIO = False
+        try:
+            await test_nuthatch()
+        except Exception as e:
+            print(f"\n❌ HTTP test failed: {e}")
+            import traceback
+            traceback.print_exc()
+    else:
+        print("\n\n### TEST 2: HTTP Transport (SKIPPED) ###")
+        print("  Reason: NUTHATCH_MCP_URL not configured or using default")
+        print("  Tip: To test HTTP mode, set NUTHATCH_MCP_URL and start nuthatch_tools.py with --http")
+
+    # Restore original mode
+    AgentConfig.NUTHATCH_USE_STDIO = original_stdio_mode
+
+    print("\n" + "="*70)
+    print("Both transport tests complete!")
+    print("="*70)
+
+if __name__ == "__main__":
+    import sys
+
+    # Check if user wants to test both transports
+    if "--both" in sys.argv:
+        asyncio.run(test_both_transports())
+    else:
+        asyncio.run(test_nuthatch())
+        print("\n💡 Tip: Run with '--both' to test both STDIO and HTTP transports")
+    

tests/test_structured_output.py

@@ -0,0 +1,136 @@
+"""
+Test structured output parsing for agent responses.
+Tests the parse_agent_response function to ensure it correctly formats
+images, audio, and species information from raw agent text.
+"""
+
+import asyncio
+import sys
+from pathlib import Path
+
+# Add parent directory to sys.path
+parent_dir = Path(__file__).parent.parent
+sys.path.insert(0, str(parent_dir))
+
+from langgraph_agent.structured_output import parse_agent_response
+
+
+async def test_structured_output():
+    """Test structured output parsing with various response formats."""
+
+    print("=" * 60)
+    print("TESTING STRUCTURED OUTPUT PARSING")
+    print("=" * 60)
+
+    # Test Case 1: Response with images and species identification
+    print("\n[TEST 1]: Response with images and species")
+    print("-" * 40)
+
+    test_response_1 = """
+    Based on the image, I can identify this as a Northern Cardinal. The bright red plumage and distinctive crest are characteristic of this species.
+
+    Here are some reference images:
+    ![Northern Cardinal](https://images.unsplash.com/photo-1578662996442-48f60103fc96?w=400)
+    ![Cardinal in snow](https://images.unsplash.com/photo-1551085254-e96b210db58a?w=400)
+
+    The Northern Cardinal is a beautiful songbird commonly found in North America.
+    """
+
+    result_1 = await parse_agent_response(
+        raw_response=test_response_1,
+        provider="openai",
+        api_key="test-key",
+        model="gpt-4o-mini"
+    )
+
+    print("Input length:", len(test_response_1))
+    print("Output length:", len(result_1))
+    print("Contains markdown images:", "![Northern Cardinal]" in result_1)
+    print("Contains species name:", "Northern Cardinal" in result_1)
+    print("✅ Test 1 completed")
+
+    # Test Case 2: Response with audio recordings
+    print("\n[TEST 2]: Response with audio recordings")
+    print("-" * 40)
+
+    test_response_2 = """
+    This appears to be an American Robin. You can listen to its distinctive song here:
+
+    Listen to the robin: https://xeno-canto.org/12345/download
+
+    Another recording: https://xeno-canto.org/67890/download
+
+    The American Robin is known for its cheerful song that signals the arrival of spring.
+    """
+
+    result_2 = await parse_agent_response(
+        raw_response=test_response_2,
+        provider="openai",
+        api_key="test-key",
+        model="gpt-4o-mini"
+    )
+
+    print("Input length:", len(test_response_2))
+    print("Output length:", len(result_2))
+    print("Contains audio links:", "[Listen to recording" in result_2)
+    print("Contains xeno-canto links:", "xeno-canto.org" in result_2)
+    print("✅ Test 2 completed")
+
+    # Test Case 3: Response with no media (should return original)
+    print("\n[TEST 3]: Response with no media")
+    print("-" * 40)
+
+    test_response_3 = """
+    This appears to be a Blue Jay. Blue Jays are intelligent birds known for their problem-solving abilities and distinctive calls.
+
+    They are commonly found in North American forests and suburban areas.
+    """
+
+    result_3 = await parse_agent_response(
+        raw_response=test_response_3,
+        provider="openai",
+        api_key="test-key",
+        model="gpt-4o-mini"
+    )
+
+    print("Input length:", len(test_response_3))
+    print("Output length:", len(result_3))
+    print("Output matches input:", result_3.strip() == test_response_3.strip())
+    print("✅ Test 3 completed")
+
+    # Test Case 4: Response with mixed URLs (images and audio)
+    print("\n[TEST 4]: Response with mixed media")
+    print("-" * 40)
+
+    test_response_4 = """
+    This is definitely a Scarlet Tanager. Here are some photos and recordings:
+
+    Photo: https://example.com/tanager.jpg
+    Another photo: https://example.com/tanager2.png
+
+    Song recording: https://xeno-canto.org/11111/download
+    Call recording: https://example.com/tanager.mp3
+
+    Scarlet Tanagers are known for their striking red plumage.
+    """
+
+    result_4 = await parse_agent_response(
+        raw_response=test_response_4,
+        provider="openai",
+        api_key="test-key",
+        model="gpt-4o-mini"
+    )
+
+    print("Input length:", len(test_response_4))
+    print("Output length:", len(result_4))
+    print("Contains image section:", "### Images" in result_4)
+    print("Contains audio section:", "### Audio Recordings" in result_4)
+    print("✅ Test 4 completed")
+
+    print("\n" + "=" * 60)
+    print("✅ ALL STRUCTURED OUTPUT TESTS PASSED")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(test_structured_output())

tests/test_subagents.py

@@ -0,0 +1,301 @@
+"""
+Subagent System Test
+
+Tests the specialized subagent orchestration system with tool filtering and routing.
+
+Usage:
+    # Test subagent system (uses .env NUTHATCH_USE_STDIO setting)
+    python tests/test_subagents.py
+
+    # Test individual specialists
+    python tests/test_subagents.py --specialist image_identifier
+    python tests/test_subagents.py --specialist species_explorer
+    python tests/test_subagents.py --specialist taxonomy_specialist
+
+Configuration (.env):
+    # Ensure STDIO mode for testing
+    NUTHATCH_USE_STDIO=true
+    NUTHATCH_API_KEY=<your-key>
+
+    # Required for Modal classifier
+    MODAL_MCP_URL=<your-modal-url>
+    BIRD_CLASSIFIER_API_KEY=<your-modal-key>
+
+    # Required for LLM
+    OPENAI_API_KEY=<your-key>
+"""
+import asyncio
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# Add parent directory to sys.path
+parent_dir = Path(__file__).parent.parent
+sys.path.insert(0, str(parent_dir))
+
+from langgraph_agent import AgentFactory
+from langgraph_agent.config import AgentConfig
+from langgraph_agent.subagent_config import SubAgentConfig
+from langgraph_agent.subagent_factory import SubAgentFactory
+from langgraph_agent.mcp_clients import MCPClientManager
+from langchain_openai import ChatOpenAI
+
+load_dotenv()
+
+
+def validate_config():
+    """Validate required configuration."""
+    errors = []
+
+    if not AgentConfig.MODAL_MCP_URL:
+        errors.append("MODAL_MCP_URL not set")
+    if not AgentConfig.BIRD_CLASSIFIER_API_KEY:
+        errors.append("BIRD_CLASSIFIER_API_KEY not set")
+    if not AgentConfig.NUTHATCH_API_KEY:
+        errors.append("NUTHATCH_API_KEY not set")
+    if not AgentConfig.OPENAI_API_KEY:
+        errors.append("OPENAI_API_KEY not set")
+
+    if not AgentConfig.NUTHATCH_USE_STDIO:
+        print("\n⚠️  WARNING: NUTHATCH_USE_STDIO is False")
+        print("   For this test, STDIO mode is recommended")
+        print("   Set NUTHATCH_USE_STDIO=true in .env\n")
+
+    if errors:
+        print("\n❌ Configuration Errors:")
+        for error in errors:
+            print(f"  • {error}")
+        print("\n💡 Check your .env file")
+        return False
+
+    return True
+
+
+async def test_tool_filtering():
+    """Test that each subagent gets the correct filtered tool set."""
+    print("\n" + "="*70)
+    print("TEST 1: Tool Filtering")
+    print("="*70)
+
+    # Get all tools
+    client = await MCPClientManager.create_multi_server_client()
+    all_tools = await MCPClientManager.get_tools(client)
+
+    print(f"\n[ALL TOOLS]: {len(all_tools)} total tools available")
+    for tool in all_tools:
+        print(f"  • {tool.name}")
+
+    # Test each subagent's tool filtering
+    definitions = SubAgentConfig.get_subagent_definitions()
+
+    for subagent_name, config in definitions.items():
+        print(f"\n[{subagent_name.upper()}]:")
+        print(f"  Name: {config['name']}")
+        print(f"  Expected tools: {len(config['tools'])}")
+        print(f"  Tools: {', '.join(config['tools'])}")
+
+        # Filter tools
+        allowed_tool_names = set(config['tools'])
+        filtered_tools = [t for t in all_tools if t.name in allowed_tool_names]
+
+        print(f"  ✅ Filtered to: {len(filtered_tools)} tools")
+
+        if len(filtered_tools) != len(config['tools']):
+            print(f"  ⚠️  Warning: Expected {len(config['tools'])} but got {len(filtered_tools)}")
+
+
+async def test_individual_subagent(subagent_name: str):
+    """Test a specific subagent with a sample query."""
+    print("\n" + "="*70)
+    print(f"TEST 2: Individual Subagent - {subagent_name}")
+    print("="*70)
+
+    # Get configuration
+    definitions = SubAgentConfig.get_subagent_definitions()
+
+    if subagent_name not in definitions:
+        print(f"\n❌ Unknown subagent: {subagent_name}")
+        print(f"Available: {', '.join(definitions.keys())}")
+        return
+
+    config = definitions[subagent_name]
+    print(f"\n[CONFIG]:")
+    print(f"  Name: {config['name']}")
+    print(f"  Description: {config['description']}")
+    print(f"  Tools: {', '.join(config['tools'])}")
+
+    # Create LLM
+    llm = ChatOpenAI(
+        model=AgentConfig.DEFAULT_OPENAI_MODEL,
+        temperature=config['temperature'],
+        streaming=True
+    )
+
+    # Get tools and create subagent
+    client = await MCPClientManager.create_multi_server_client()
+    all_tools = await MCPClientManager.get_tools(client)
+
+    print(f"\n[CREATING SUBAGENT]...")
+    subagent = await SubAgentFactory.create_subagent(
+        subagent_name, all_tools, llm
+    )
+    print(f"✅ Subagent created successfully")
+
+    # Test queries for each specialist
+    test_queries = {
+        "image_identifier": "What bird is in this image?",
+        "species_explorer": "Tell me about Northern Cardinals",
+        "taxonomy_specialist": "What birds are in the Cardinalidae family?"
+    }
+
+    query = test_queries.get(subagent_name, "Help me identify birds")
+
+    print(f"\n[TEST QUERY]: {query}")
+    print(f"[RESPONSE]:")
+    print("-" * 70)
+
+    try:
+        # Note: This will fail without an actual image for image_identifier
+        # but shows the subagent is working
+        result = await subagent.ainvoke({
+            "messages": [{"role": "user", "content": query}]
+        })
+
+        if result and "messages" in result:
+            for msg in result["messages"]:
+                if hasattr(msg, 'content'):
+                    print(msg.content)
+        else:
+            print(result)
+
+    except Exception as e:
+        print(f"⚠️  Test query failed (expected for image_identifier without image): {e}")
+
+
+async def test_router():
+    """Test the routing logic."""
+    print("\n" + "="*70)
+    print("TEST 3: Router Logic")
+    print("="*70)
+
+    test_cases = [
+        ("What bird is this?", "image_identifier"),
+        ("Identify this photo", "image_identifier"),
+        ("Tell me about cardinals", "species_explorer"),
+        ("Find birds with red feathers", "species_explorer"),
+        ("Show me audio of a robin", "species_explorer"),
+        ("What families exist?", "taxonomy_specialist"),
+        ("Show me endangered birds", "taxonomy_specialist"),
+    ]
+
+    print("\n[ROUTING TESTS]:")
+    print(f"Testing {len(test_cases)} queries...")
+
+    for query, expected_route in test_cases:
+        # Simulate routing logic from subagent_router.py
+        content = query.lower()
+
+        if any(word in content for word in ["identify", "what bird", "classify", "image", "photo"]):
+            route = "image_identifier"
+        elif any(word in content for word in ["audio", "sound", "call", "song", "find", "search"]):
+            route = "species_explorer"
+        elif any(word in content for word in ["family", "families", "conservation", "endangered", "taxonomy"]):
+            route = "taxonomy_specialist"
+        else:
+            route = "species_explorer"
+
+        status = "✅" if route == expected_route else "❌"
+        print(f"\n  {status} Query: '{query}'")
+        print(f"     Expected: {expected_route}")
+        print(f"     Got: {route}")
+
+
+async def test_full_orchestrator():
+    """Test the full subagent orchestrator."""
+    print("\n" + "="*70)
+    print("TEST 4: Full Orchestrator")
+    print("="*70)
+
+    # Enable subagents
+    SubAgentConfig.USE_SUBAGENTS = True
+
+    print(f"\n[CONFIG]:")
+    print(f"  Subagents enabled: {SubAgentConfig.USE_SUBAGENTS}")
+    print(f"  OpenAI model: {AgentConfig.DEFAULT_OPENAI_MODEL}")
+    print(f"  Temperature: {AgentConfig.OPENAI_TEMPERATURE}")
+
+    print(f"\n[CREATING ORCHESTRATOR]...")
+    try:
+        orchestrator = await AgentFactory.create_subagent_orchestrator(
+            model=AgentConfig.DEFAULT_OPENAI_MODEL,
+            api_key=AgentConfig.OPENAI_API_KEY,
+            provider="openai",
+            mode="Specialized Subagents (3 Specialists)"
+        )
+        print(f"✅ Orchestrator created successfully")
+        print(f"   Type: {type(orchestrator)}")
+
+    except Exception as e:
+        print(f"❌ Orchestrator creation failed: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+async def run_all_tests():
+    """Run all subagent tests."""
+    print("\n" + "="*70)
+    print("SUBAGENT SYSTEM TEST SUITE")
+    print("="*70)
+
+    if not validate_config():
+        print("\n❌ Test suite aborted due to configuration errors")
+        return
+
+    try:
+        # Test 1: Tool filtering
+        await test_tool_filtering()
+
+        # Test 2: Individual subagents
+        for subagent_name in ["image_identifier", "species_explorer", "taxonomy_specialist"]:
+            await test_individual_subagent(subagent_name)
+
+        # Test 3: Router logic
+        await test_router()
+
+        # Test 4: Full orchestrator
+        await test_full_orchestrator()
+
+        print("\n" + "="*70)
+        print("✅ ALL TESTS COMPLETED")
+        print("="*70)
+
+    except Exception as e:
+        print(f"\n❌ Test suite failed: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "--specialist" and len(sys.argv) > 2:
+            # Test individual specialist
+            specialist_name = sys.argv[2]
+            asyncio.run(test_individual_subagent(specialist_name))
+        elif sys.argv[1] == "--router":
+            # Test router only
+            asyncio.run(test_router())
+        elif sys.argv[1] == "--tools":
+            # Test tool filtering only
+            asyncio.run(test_tool_filtering())
+        else:
+            print("Usage:")
+            print("  python tests/test_subagents.py                          # Run all tests")
+            print("  python tests/test_subagents.py --specialist <name>      # Test one specialist")
+            print("  python tests/test_subagents.py --router                 # Test routing only")
+            print("  python tests/test_subagents.py --tools                  # Test tool filtering")
+    else:
+        # Run all tests
+        asyncio.run(run_all_tests())

tests/theme_builder.py

@@ -0,0 +1,3 @@
+import gradio as gr
+
+gr.themes.builder()