Enahanced prompts for supervisor and subagents

app.py

@@ -24,14 +24,14 @@ load_dotenv()
 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_5.jpg"]}
+    {"text": "Identify this bird and show me similar species", "files": ["examples/bird_example_5.jpg"]},
+    {"text": "", "files": ["examples/bird_example_6.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",
     "Find me audio recordings for Snow Goose",
     "Get me bird call samples for any two species"
 ]
@@ -1034,7 +1034,7 @@ def update_text_examples_for_mode(mode):
     #     print(f"[DEBUG] Future mode text samples: {len(samples)} examples")
     # else:
 
-    # Default: Specialized Subagents (3 Specialists) - includes image ID, taxonomy, and audio finder
+    # Default: Supervisor (Multi-Agent) - includes image ID, taxonomy, and audio finder
     samples = [[text] for text in MULTI_AGENT_TEXT_EXAMPLES]
     print(f"[DEBUG] Multi-agent text samples: {len(samples)} examples")
 
@@ -1488,9 +1488,9 @@ with gr.Blocks() as demo:
                     gr.Markdown("Choose between unified agent or specialized routing")
                     agent_mode = gr.Dropdown(
                         choices=[
-                            "Specialized Subagents (3 Specialists)"
+                            "Supervisor (Multi-Agent)"
                         ],
-                        value="Specialized Subagents (3 Specialists)",
+                        value="Supervisor (Multi-Agent)",
                         show_label=False,
                         container=False
                     )
@@ -1559,7 +1559,7 @@ with gr.Blocks() as demo:
                     session_status = gr.HTML(
                         value=create_config_html(
                             provider_choice="OpenAI",
-                            agent_mode_choice="Specialized Subagents (3 Specialists)",
+                            agent_mode_choice="Supervisor (Multi-Agent)",
                             hf_key_input="",
                             openai_key_input="",
                             anthropic_key_input=""
@@ -1653,7 +1653,7 @@ with gr.Blocks() as demo:
         # Generate config HTML
         config_html = create_config_html(
             provider_choice=provider_str,
-            agent_mode_choice="Specialized Subagents (3 Specialists)",
+            agent_mode_choice="Supervisor (Multi-Agent)",
             hf_key_input=hf_key_value,
             openai_key_input=openai_key_value,
             anthropic_key_input=anthropic_key_value

docs/dev/agents_config-README.md

@@ -33,7 +33,7 @@ Supervisor (Router)
 **Key Concepts:**
 - **Supervisor**: LLM-based router that delegates tasks to specialists
 - **Subagents**: Specialized agents with filtered tool access and focused prompts
-- **Modes**: Different agent configurations (e.g., "Specialized Subagents (2 Specialists)", "Audio Finder Agent")
+- **Modes**: Different agent configurations (e.g., "Supervisor (Multi-Agent)")
 - **Tool Filtering**: Each subagent only has access to relevant tools
 
 ---
@@ -190,7 +190,7 @@ Update `get_mode_definitions()`:
 
 ```python
 return {
-    "Specialized Subagents (3 Specialists)": {  # Update count
+    "Supervisor (Multi-Agent)": {  # Current mode name
         "description": "Router orchestrates 3 specialized agents",
         "subagents": ["image_identifier", "taxonomy_specialist", "my_new_agent"],  # Add here
         "use_router": True
@@ -231,7 +231,7 @@ async def create_supervisor_workflow(all_tools, llm, provider="openai"):
 
 ```python
 return {
-    "Specialized Subagents (2 Specialists)": {  # Update count
+    "Supervisor (Multi-Agent)": {  # Update count if needed
         "description": "Router orchestrates 2 specialized agents",
         "subagents": ["image_identifier", "taxonomy_specialist"],  # Remove agent
         "use_router": True
@@ -348,10 +348,9 @@ IMAGE_IDENTIFIER_PROMPT = """Updated comprehensive prompt..."""
 ```python
 agent_mode = gr.Dropdown(
     choices=[
-        "Specialized Subagents (2 Specialists)",  # Update mode name here
-        "Audio Finder Agent"
+        "Supervisor (Multi-Agent)"  # Update mode name here
     ],
-    value="Specialized Subagents (2 Specialists)",  # Update default here
+    value="Supervisor (Multi-Agent)",  # Update default here
     show_label=False,
     container=False
 )
@@ -365,7 +364,7 @@ agent_mode = gr.Dropdown(
 session_status = gr.HTML(
     value=create_config_html(
         provider_choice="OpenAI",
-        agent_mode_choice="Specialized Subagents (2 Specialists)",  # Update here
+        agent_mode_choice="Supervisor (Multi-Agent)",  # Update here
         hf_key_input="",
         openai_key_input="",
         anthropic_key_input=""
@@ -380,7 +379,7 @@ session_status = gr.HTML(
 ```python
 config_html = create_config_html(
     provider_choice=provider_str,
-    agent_mode_choice="Specialized Subagents (2 Specialists)",  # Update here
+    agent_mode_choice="Supervisor (Multi-Agent)",  # Update here
     hf_key_input=hf_key_value,
     openai_key_input=openai_key_input,
     anthropic_key_input=anthropic_key_input
@@ -392,7 +391,7 @@ config_html = create_config_html(
 **Location:** `app.py` ~line 1033
 
 ```python
-else:  # Specialized Subagents (2 Specialists)  # Update comment
+else:  # Supervisor (Multi-Agent)  # Update comment
     samples = [[text] for text in MULTI_AGENT_TEXT_EXAMPLES]
 ```
 
@@ -435,7 +434,7 @@ def update_text_examples_for_mode(mode):
     #     samples = [[text] for text in ANOTHER_MODE_EXAMPLES]
     else:  # Default: Specialized Subagents
 
-    # Default: Specialized Subagents (3 Specialists)
+    # Default: Supervisor (Multi-Agent)
     samples = [[text] for text in MULTI_AGENT_TEXT_EXAMPLES]
     print(f"[DEBUG] Multi-agent text samples: {len(samples)} examples")
 
@@ -462,7 +461,7 @@ gradio app.py
 **Common errors to watch for:**
 
 ```
-Unknown mode: Specialized Subagents (3 Specialists). Available: ['Specialized Subagents (2 Specialists)', 'Audio Finder Agent']
+Unknown mode: Old Mode Name. Available: ['Supervisor (Multi-Agent)']
 ```
 → **Fix:** Update app.py mode references
 
@@ -544,7 +543,7 @@ Test with different LLM providers:
 
 **Fix:** Search for all occurrences in app.py and update:
 ```bash
-grep -n "Specialized Subagents (3 Specialists)" app.py
+grep -n "Old Mode Name" app.py
 ```
 
 ### Error: "Unknown subagent"
@@ -576,19 +575,22 @@ print([tool.name for tool in all_tools])
 
 ---
 
-## Example: Recent Change
+## Example: Recent Changes
 
-**We removed `species_explorer` from the Specialized Subagents mode:**
+**Evolution of the supervisor mode:**
+
+1. **Removed `species_explorer`** - Streamlined from 3 to 2 specialists
+2. **Added `generalist` (audio finder)** - Back to 3 specialists with audio capabilities
+3. **Renamed mode** - "Specialized Subagents (3 Specialists)" → "Supervisor (Multi-Agent)"
 
 **Files changed:**
-1. `subagent_supervisor.py` - Removed species_agent creation and reference
-2. `subagent_config.py` - Updated mode from (3 Specialists) → (2 Specialists)
-3. `subagent_config.py` - Updated router prompts (default)
-4. `prompts.py` - Updated ROUTER_PROMPT_HF
-5. `subagent_config.py` - Removed species_explorer from "When to defer" sections
-6. `app.py` - Updated all 5 mode references from (3 Specialists) → (2 Specialists)
-
-**Reason:** Simplified architecture before adding audio finder as new subagent
+1. `subagent_supervisor.py` - Added/removed agents from supervisor list
+2. `subagent_config.py` - Updated mode definition and router prompts
+3. `prompts.py` - Updated HuggingFace router prompt, removed pirate personality
+4. `subagent_config.py` - Updated "When to defer" sections
+5. `app.py` - Updated all 5 mode references throughout
+
+**Current architecture:** Single unified "Supervisor (Multi-Agent)" mode with 3 specialists (image_identifier, taxonomy_specialist, generalist)
 
 ---
 

langgraph_agent/prompts.py

@@ -133,10 +133,10 @@ Always be educational and cite your sources.
 
 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.
+AUDIO_FINDER_PROMPT = """You are BirdScope AI Generalist, an expert at searching the bird database and retrieving audio recordings.
 
 **Your Mission:**
-Help us discover bird songs and calls by finding species with available audio recordings.
+Help users find birds in the database and discover bird songs and calls.
 
 **Your Tools:**
 1. **search_birds(name, family, region, status, page_size)**
@@ -155,6 +155,15 @@ Help us discover bird songs and calls by finding species with available audio re
     - Returns recording metadata and download URLs
     - Only call this for birds that have `has_audio=true` in their search results
 
+**WORKFLOW for general bird searches (find/list/examples):**
+When users ask to "find birds", "show examples", "list birds":
+1. Call `search_birds()` with a broad filter:
+   - `region="North America"` (most coverage) OR
+   - `family="[Family Name]"` if they mention a family OR
+   - `status="[Status]"` if they mention conservation status
+2. Set `page_size` parameter to control results (default to 5-10 unless they specify)
+3. Present the birds you found with their names and basic info
+
 **CRITICAL WORKFLOW for "find audio for any bird":**
 The API has NO `has_audio` filter parameter. You MUST use this two-step process:
 
@@ -194,6 +203,13 @@ The API has NO `has_audio` filter parameter. You MUST use this two-step process:
        Quality: A
        https://xeno-canto.org/143610/download"
 
+    **CRITICAL - No Hallucination:**
+    - If get_bird_audio returns empty/no recordings: Tell user "No audio recordings available for this species"
+    - If search_birds returns no results: Tell user "No birds found matching that criteria"
+    - NEVER fabricate audio URLs, bird names, or recording metadata
+    - Only show audio recordings and data that are actually returned by the API tools
+    - If a tool fails or returns empty results, honestly report it to the user
+
     **Error Handling:**
     - If search returns no birds: suggest broadening filters
     - If no birds have audio: inform user and suggest known birds with audio
@@ -204,7 +220,7 @@ The API has NO `has_audio` filter parameter. You MUST use this two-step process:
 # HuggingFace-Optimized Prompts (More Explicit, Step-by-Step)
 # =============================================================================
 
-AUDIO_FINDER_PROMPT_HF = """You are BirdScope Audio Finder. Find bird audio recordings.
+AUDIO_FINDER_PROMPT_HF = """You are BirdScope AI Generalist. Find birds in database and retrieve audio recordings.
 
 **Tools Available:**
 1. search_birds(name, family, region, status, page_size) - Search for birds
@@ -213,13 +229,22 @@ AUDIO_FINDER_PROMPT_HF = """You are BirdScope Audio Finder. Find bird audio reco
 
 **Step-by-Step Process:**
 
+When user asks to find/list/search birds:
+1. Call search_birds with region="North America" and page_size=5-10
+2. Present birds found
+
 When user asks for audio:
 1. Call search_birds with ONE filter (name, region, family, or status)
 2. Look at results for birds with has_audio=true
 3. Call get_bird_audio(name="Bird Name") for a bird that has audio
 4. Return the full URL from file_url field
 
-**Example:**
+**Example - General Search:**
+User: "Find five birds"
+1. Call: search_birds(region="North America", page_size=5)
+2. List the birds found
+
+**Example - Audio Search:**
 User: "Find audio for any bird"
 1. Call: search_birds(region="North America", page_size=20)
 2. Find bird with has_audio=true (example: "Snow Goose")
@@ -230,6 +255,12 @@ User: "Find audio for any bird"
 - NEVER use has_audio as a parameter in search_birds
 - ALWAYS include full file_url in your response
 - Known birds with audio: Snow Goose, Common Goldeneye, Gadwall
+
+**CRITICAL - No Hallucination:**
+- If get_bird_audio returns empty: Tell user "No audio recordings available"
+- If search_birds returns no results: Tell user "No birds found"
+- NEVER make up audio URLs or bird names
+- Only return actual data from API tools
 """
 
 IMAGE_IDENTIFIER_PROMPT_HF = """You are an Image Identification Specialist.
@@ -252,6 +283,12 @@ IMAGE_IDENTIFIER_PROMPT_HF = """You are an Image Identification Specialist.
 3. Key features
 4. Reference images as: ![Bird](url)
 
+**CRITICAL - No Hallucination:**
+- If get_bird_images returns empty: Tell user "No reference images available"
+- If get_bird_info returns no data: Tell user "Species information not available"
+- NEVER make up image URLs or species data
+- Only show actual data from API tools
+
 Keep responses short and factual.
 """
 
@@ -275,6 +312,13 @@ SPECIES_EXPLORER_PROMPT_HF = """You are a Species Explorer. Help users learn abo
 - Be educational
 - Show images and audio when available
 - Explain what makes the bird special
+
+**CRITICAL - No Hallucination:**
+- If get_bird_images returns empty: Tell user "No images available"
+- If get_bird_audio returns empty: Tell user "No audio available"
+- If search_birds returns no results: Tell user "No birds found"
+- NEVER make up URLs, bird names, or data
+- Only show actual data from API tools
 """
 
 TAXONOMY_SPECIALIST_PROMPT_HF = """You are a Taxonomy & Conservation Specialist.
@@ -290,8 +334,16 @@ TAXONOMY_SPECIALIST_PROMPT_HF = """You are a Taxonomy & Conservation Specialist.
 - Bird families
 - Taxonomic relationships
 
-**Process:**
-1. Use filter or search tools
+**Process for conservation status:**
+1. Call filter_by_status with user's requested status (use proper capitalization)
+2. Check EVERY returned bird's "status" field
+3. If status doesn't match what user requested: Tell user honestly what you found
+4. Explain: "Database returned '{actual_status}' birds instead of '{requested_status}'"
+5. Suggest: "Database has mostly 'Low Concern' species. Want to see those?"
+6. NEVER show birds with wrong status as if they match user's request
+
+**Process for families:**
+1. Use search or filter tools
 2. Explain conservation importance
 3. Show family relationships
 4. Use proper scientific terms but explain them
@@ -304,16 +356,21 @@ ROUTER_PROMPT_HF = """You are BirdScope AI Supervisor. Route user requests to sp
 **Specialists:**
 - image_identifier: Identify birds from photos and get species info
 - taxonomy_specialist: Conservation and families
-- generalist: Find birds with audio recordings
+- generalist: Search bird database (has search_birds tool) and retrieve audio recordings
 
 **Routing Rules:**
 1. Image uploads → image_identifier
-2. Species info requests → image_identifier
+2. "Search" or "find" or "examples" or "list birds" → generalist
 3. "Audio" or "sound" or "song" → generalist
-4. "Conservation" or "endangered" → taxonomy_specialist
-5. "Family" or "families" → taxonomy_specialist
+4. Species info by name → image_identifier
+5. "Conservation" or "endangered" → taxonomy_specialist
+6. "Family" or "families" → taxonomy_specialist
 
 Route to ONE specialist per request.
+
+**Important:**
+- If specialist reports no data found, relay this to user honestly
+- Never add information not provided by specialist
 """
 
 # =============================================================================

langgraph_agent/subagent_config.py

@@ -21,7 +21,7 @@ class SubAgentConfig:
             Dict mapping mode names to their configurations
         """
         return {
-            "Specialized Subagents (3 Specialists)": {
+            "Supervisor (Multi-Agent)": {
                 "description": "Router orchestrates 3 specialized agents",
                 "subagents": ["image_identifier", "taxonomy_specialist", "generalist"],
                 "use_router": True
@@ -79,6 +79,13 @@ class SubAgentConfig:
 - Mention if confidence is low and suggest why
 - Keep responses focused and concise
 
+**CRITICAL - No Hallucination:**
+- If get_bird_images returns empty/no images: Tell user "No reference images available for this species"
+- If get_bird_info returns no data: Tell user "Species information not available in database"
+- NEVER fabricate image URLs, species data, or make up placeholder links
+- Only show images and data that are actually returned by the API tools
+- If a tool fails or returns empty results, honestly report it to the user
+
 **When to defer:**
 - For audio/sound/call queries -> generalist
 - For family/taxonomy queries -> taxonomy_specialist
@@ -120,6 +127,14 @@ class SubAgentConfig:
 - 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)"
 
+**CRITICAL - No Hallucination:**
+- If get_bird_images returns empty/no images: Tell user "No reference images available for this species"
+- If get_bird_audio returns empty/no audio: Tell user "No audio recordings available for this species"
+- If search_birds returns no results: Tell user "No birds found matching that criteria"
+- NEVER fabricate URLs, bird names, species data, or make up placeholder content
+- Only show images, audio, and data that are actually returned by the API tools
+- If a tool fails or returns empty results, honestly report it to the user
+
 **When to defer:**
 - For image identification -> image_identifier
 - For conservation status filtering -> taxonomy_specialist
@@ -145,11 +160,21 @@ class SubAgentConfig:
 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
+
+**For conservation status queries:**
+1. Use filter_by_status with the user's requested status (use proper capitalization: "Endangered", "Low Concern", etc.)
+2. CRITICAL: Check the "status" field in EVERY returned bird result
+3. If results have DIFFERENT status than what user requested:
+   - Inform user honestly: "The database has no birds with '{requested_status}' status"
+   - Explain what you found: "The results returned birds with '{actual_status}' status instead"
+   - Suggest: "The database primarily contains 'Low Concern' species. Would you like to see those instead?"
+4. NEVER present birds with wrong status as if they match the user's request
+5. Only show birds whose status field exactly matches what the user asked for
+
+**For family name searches:**
+- If no results, try variations: "Cardinalidae" → "Cardinal"
+- Try broader terms: specific family → general group
+- Return closest match and explain differences
 
 **Response Style:**
 - Use proper taxonomic terminology but explain it clearly
@@ -157,7 +182,7 @@ class SubAgentConfig:
 - 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..."
+- If you had to adjust the search, explain briefly
 
 **When to defer:**
 - For image identification -> image_identifier
@@ -190,18 +215,19 @@ class SubAgentConfig:
 **Your Team:**
 - **image_identifier**: Identifies birds from photos using ML classification and fetches species info
 - **taxonomy_specialist**: Conservation status, taxonomic families, classification queries
-- **generalist**: Audio finder specialist - finds birds with audio recordings and retrieves bird calls/songs
+- **generalist**: Database search specialist - finds birds using search_birds tool, can filter by name/region/family/status, and retrieves audio recordings
 
 **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. **Species information requests** → image_identifier (has get_bird_info and get_bird_images)
+2. **"Search"/"find"/"examples"/"list birds"** → generalist (has search_birds tool for database queries)
 3. **"Audio"/"sound"/"song"/"call"/"recording"** → generalist (has audio search and retrieval)
-4. **"Family"/"families" + broad questions** → taxonomy_specialist (has family tools)
-5. **"Conservation"/"endangered"/"threatened"** → taxonomy_specialist (has status filters)
-6. **Taxonomic relationships** → taxonomy_specialist (specializes in classification)
+4. **Species info by name** → image_identifier (has get_bird_info and get_bird_images)
+5. **"Family"/"families" + broad questions** → taxonomy_specialist (has family tools)
+6. **"Conservation"/"endangered"/"threatened"** → taxonomy_specialist (has status filters)
+7. **Taxonomic relationships** → taxonomy_specialist (specializes in classification)
 
 **Decision-making:**
 - Consider the user's INTENT, not just keywords
@@ -213,6 +239,8 @@ Analyze each user request and route it to the MOST appropriate specialist.
 - Be decisive - route quickly
 - Don't duplicate specialist work - let them handle their domain
 - Synthesize multi-turn conversations if needed
+- If a specialist reports no data found, accept and relay this to the user honestly
+- Never add or fabricate information that wasn't provided by the specialist
 """
 
     @staticmethod