Deploy COMPLETE ID Agents - Medical AI system (clean, no cache files)

.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Temporary files
+*.tmp
+*.temp
+
+# HF Spaces specific
+.git/

__init__.py

@@ -0,0 +1 @@
+# This file marks the tools directory as a Python package.

config.py

@@ -0,0 +1,102 @@
+"""
+config.py
+---------
+Global configuration, shared state, and constants for the modular AI agent system.
+"""
+
+# Global configuration, shared state, and constants for the modular AI agent system.
+import os
+
+agents_config = {}
+rag_retriever = None
+
+skills_library = {
+    "🛡️ Antimicrobial Stewardship": [
+        "recommend_deescalation",
+        "recommend_empiric_therapy",
+        "alert_prolonged_antibiotic_use"
+    ],
+    "🦠 Infection Prevention and Control": [
+        "IPC_reporting",
+        "NHSN_criteria_evaluator",
+        "recommend_isolation_precautions"
+    ],
+    "🔬 Research Assistant": [
+        "search_pubmed",
+        "suggest_journals_for_submission",
+        "format_references"
+    ],
+    "🏥 Clinical Assistant": [
+        "retrieve_guidelines",
+        "explain_in_layman_language",
+        "history_taking"
+    ],
+    "📚 Education Assistant": [
+        "generate_board_exam_question",
+        "generate_flash_cards",
+        "create_educational_presentation"
+    ],
+    "🎼 Orchestrator": [
+        # Note: Orchestrator capabilities are built-in and don't require skill selection
+    ]
+}
+
+prefilled_agents = {
+    "Example Stewardship Agent": {
+        "agent_name": "SmartSteward",
+        "agent_type": "🛡️ Antimicrobial Stewardship",
+        "agent_mission": "Assist stewardship team in optimizing antibiotic use.",
+        "skills": [
+            "recommend_deescalation",
+            "alert_prolonged_antibiotic_use",
+            "recommend_empiric_therapy"
+        ]
+    },
+    "Example Infection Control Agent": {
+        "agent_name": "InfectoGuard",
+        "agent_type": "🦠 Infection Prevention and Control",
+        "agent_mission": "Support IPC team in monitoring outbreaks and adherence to precautions. When users ask about reportable diseases or reporting requirements, offer to help with the specific reporting process using available tools.",
+        "skills": [
+            "IPC_reporting",
+            "NHSN_criteria_evaluator",
+            "recommend_isolation_precautions"
+        ]
+    },
+    "Example Research Assistant Agent": {
+        "agent_name": "ResearchRanger",
+        "agent_type": "🔬 Research Assistant",
+        "agent_mission": "Assist in literature search, article summarization, and citation formatting.",
+        "skills": [
+            "search_pubmed",
+            "suggest_journals_for_submission",
+            "format_references"
+        ]
+    },
+    "Example Clinical Assistant Agent": {
+        "agent_name": "ClinicoPilot",
+        "agent_type": "🏥 Clinical Assistant",
+        "agent_mission": "Assist clinicians in diagnostic workflows and patient education by translating complex medical information into layman terms.",
+        "skills": [
+            "retrieve_guidelines",
+            "explain_in_layman_language"
+        ]
+    },
+    "Example Education Assistant Agent": {
+        "agent_name": "EduMedCoach",
+        "agent_type": "📚 Education Assistant",
+        "agent_mission": "Generate educational materials like board exam questions, flash cards, and comprehensive presentations.",
+        "skills": [
+            "generate_board_exam_question",
+            "generate_flash_cards",
+            "create_educational_presentation"
+        ]
+    },
+    "Example Orchestrator Agent": {
+        "agent_name": "ID Maestro",
+        "agent_type": "🎼 Orchestrator",
+        "agent_mission": "Intelligently coordinate multiple ID agents to provide comprehensive analysis and recommendations.",
+        "skills": [
+            # Orchestrator uses built-in coordination capabilities
+        ]
+    }
+}

core/__init__.py

@@ -0,0 +1 @@
+# Core module for ID Agents application

core/agents/__init__.py

@@ -0,0 +1 @@
+# Agent orchestration and management components

core/agents/agent_utils.py

@@ -0,0 +1,84 @@
+import json
+import re
+import gradio as gr
+
+def linkify_citations(answer_text: str, titles: dict) -> str:
+    """
+    Replace every literal [n] in the answer with:
+        <a href="#srcn" title="snippet...">[n]</a>
+    where titles[n] holds the hover text.
+    """
+    def _sub(match):
+        n = match.group(1)          # the number between brackets
+        title = titles.get(int(n), "")
+        return f'<a href="#src{n}" title="{title}">[{n}]</a>'
+
+    return re.sub(r"\[(\d+)\]", _sub, answer_text)
+
+def build_agent(agent_type, agent_name, agent_mission, selected_skills, web_access, allow_fallback, uploaded_files, link1, link2, link3, link4):
+    trusted_links = [link for link in [link1, link2, link3, link4] if link]
+    agent = {
+        "agent_name": agent_name,
+        "agent_type": agent_type,
+        "agent_mission": agent_mission,
+        "skills": selected_skills,
+        "web_access": web_access,
+        "allow_fallback": allow_fallback,
+        "grounded_files": [file.name for file in uploaded_files] if uploaded_files else [],
+        "trusted_links": trusted_links
+    }
+    return json.dumps(agent, indent=2)
+
+def load_prefilled(prefilled_name, prefilled_agents):
+    if prefilled_name in prefilled_agents:
+        data = prefilled_agents[prefilled_name]
+        return (data["agent_type"], data["agent_name"], data["agent_mission"], data["skills"])
+    else:
+        return (None, "", "", [])
+
+def prepare_download(agent_json):
+    return ("agent_config.json", agent_json.encode())
+
+def preload_demo_chat(agent_json):
+    """Show instruction message instead of agent greeting to avoid confusion"""
+    return [{"role": "assistant", "content": "� **Agent generated successfully!**\n\nTo start chatting:\n1. Select an agent from the dropdown menu above\n2. Click '💬 Chat with Selected Agent'\n3. Then you can type your questions here\n\n*Please select an agent to begin testing.*"}]
+
+def _safe_title(text, limit=140):
+    txt = text.replace('"', "'").replace("\n", " ")
+    return (txt[:limit] + "…") if len(txt) > limit else txt
+
+def extract_clinical_variables_from_history(history, variable_names):
+    """
+    Extract the most recent value for each variable from the chat history (list of dicts).
+    Returns a dict of variable_name: value.
+    """
+    import re
+    result = {var: None for var in variable_names}
+    # Search from most recent to oldest
+    for message in reversed(history):
+        if message["role"] != "user" and message["role"] != "assistant":
+            continue
+        content = message.get("content", "")
+        for var in variable_names:
+            # Simple regex: look for 'var: value' or '- var: value' or 'var = value'
+            pattern = rf"(?:^|\n|\-)\s*{re.escape(var.replace('_', ' '))}\s*[:=]\s*(.+)"
+            match = re.search(pattern, content, re.IGNORECASE)
+            if match and not result[var]:
+                value = match.group(1).strip()
+                # Remove trailing punctuation
+                value = re.sub(r"[\.,;\n\r]+$", "", value)
+                result[var] = value
+    return result
+
+def validate_and_reference_recommendation(reply_text: str) -> str:
+    """
+    Checks the reply for common clinical errors and attaches references/guidelines.
+    Returns the possibly modified reply with references appended.
+    """
+    # No hardcoded clinical rules or references here. If clinical validation is needed, use a knowledge base or guideline-driven system.
+    return reply_text
+"""
+agent_utils.py
+-------------
+Utility functions for agent configuration, citation linking, and other helpers.
+"""

core/agents/chat_orchestrator.py

@@ -0,0 +1,352 @@
+"""
+chat_orchestrator.py
+-------------------
+Agent orchestration, chat streaming, and related logic.
+"""
+
+import json
+from typing import Dict, cast
+from core.utils.llm_connector import AgentLLMConnector
+from core.utils.skills_registry import get_tool_by_name
+from core.agents.agent_utils import validate_and_reference_recommendation
+
+# --- Orchestrator state ---
+orchestrators: Dict[str, object] = {}
+
+# --- Constants ---
+MAX_HISTORY = 20
+
+# --- Build log utility ---
+def build_log(conn):
+    """Return a formatted log of tool invocations if available."""
+    if hasattr(conn, 'invocations'):
+        invocations = getattr(conn, 'invocations', [])
+        if not invocations:
+            return ''
+        log = '--- Tool Invocation Log ---\n'
+        for i, inv in enumerate(invocations, 1):
+            log += f"{i}. {inv}\n"
+        return log
+    return ''
+
+# --- Streaming to agent (for child agents) ---
+def _stream_to_agent(cfg, history, user_input, debug_flag, active_children):
+    """Yield streaming responses for a child agent (sync generator)."""
+    skill_objs = []
+    if cfg.get("web_access", False):
+        web_tool = get_tool_by_name("search_internet", {"user_query": user_input})
+        if web_tool:
+            skill_objs.append(web_tool)
+    for skill_name in cfg.get("skills", []):
+        tool = get_tool_by_name(skill_name, {"user_query": user_input})
+        if tool:
+            skill_objs.append(tool)
+    # Pass allow_fallback, trusted_links, grounded_files to AgentLLMConnector
+    allow_fallback = cfg.get("allow_fallback", True)
+    trusted_links = cfg.get("trusted_links", [])
+    grounded_files = cfg.get("grounded_files", [])
+    
+    # Get global RAG retriever if available
+    rag_retriever = None
+    try:
+        import sys
+        if 'app' in sys.modules:
+            app_module = sys.modules['app']
+            rag_retriever = getattr(app_module, 'rag_retriever', None)
+    except:
+        pass  # No RAG retriever available
+    
+    conn = AgentLLMConnector(
+        api_key=cast(str, cfg.get("api_key")),
+        skills=skill_objs,
+        allow_fallback=allow_fallback,
+        trusted_links=trusted_links,
+        grounded_files=grounded_files,
+        rag_retriever=rag_retriever
+    )
+    model = conn.agent_model_mapping.get(cfg.get("agent_type", ""), "gpt-5-mini")
+    
+    # Build enhanced system message with tool-specific guidance
+    system_content = f"You are {cfg.get('agent_name', 'Agent')}. {cfg.get('agent_mission', '')}"
+    
+    # Add general concise response guidelines for child agents
+    system_content += (
+        "\n\nRESPONSE GUIDELINES:\n"
+        "- Be concise and clinically focused\n"
+        "- Provide clear, actionable recommendations\n"
+        "- Avoid excessive reasoning or explanation unless specifically requested\n"
+        "- Structure responses with clear sections when appropriate\n"
+        "- Use bullet points or numbered lists for multiple recommendations"
+    )
+    
+    # Add specific guidance for IPC reporting
+    has_ipc_reporting = any(skill.name == "IPC_reporting" for skill in skill_objs)
+    if has_ipc_reporting:
+        system_content += (
+            "\n\nWhen users ask about reportable diseases, reporting requirements, or infection control reporting, "
+            "always offer to help with the specific reporting process. Use the IPC_reporting tool to provide "
+            "jurisdiction-specific requirements and generate formatted reports. "
+            "IMPORTANT: When calling IPC_reporting, include ALL conversation context in the case_summary parameter, "
+            "especially the specific organism/pathogen mentioned by the user (e.g., 'User asked about typhus fever reporting')."
+        )
+    
+    system_msg = {"role": "system", "content": system_content}
+    from collections import deque
+    recent = deque(history, maxlen=MAX_HISTORY)
+    history_msgs = [ {"role": m["role"], "content": m["content"]} for m in recent if m["role"] in ("user", "assistant")]
+    messages = [system_msg] + history_msgs
+    history.append({"role": "assistant", "content": ""})
+    buf = ""
+    # This is a sync generator for child agents; in real use, adapt to async if needed
+    # Fix: call the async generator and iterate with asyncio
+    import asyncio
+    async def run_stream():
+        async for token in conn.chat_with_agent_stream(model_name=model, messages=messages):
+            yield token
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    gen = run_stream()
+    try:
+        while True:
+            token = loop.run_until_complete(gen.__anext__())
+            buf += token
+            history[-1]["content"] = buf
+            invocation_log = build_log(conn)
+            yield history, "", invocation_log, active_children, None
+    except StopAsyncIteration:
+        pass
+    history[-1]["content"] = buf.strip()
+    invocation_log = build_log(conn)
+    yield history, "", invocation_log, active_children, None
+
+# --- Main async chat orchestrator ---
+async def simulate_agent_response_stream(agent_json, history, user_input, debug_flag, active_children):
+    """
+    Streams agent replies with sliding window, multi-agent routing,
+    and invocation logging under orchestrator flows.
+    Yields: history, cleared input, invocation log, active_children, challenger_info.
+    """
+    if not agent_json or not agent_json.strip():
+        history.append({"role": "assistant", "content": "⚠️ No agent configuration found. Please Generate or Load an agent first."})
+        yield history, "", "", active_children, None
+        return
+
+    try:
+        cfg = json.loads(agent_json)
+    except json.JSONDecodeError:
+        history.append({"role": "assistant", "content": "⚠️ Invalid agent configuration. Please regenerate or reload the agent."})
+        yield history, "", "", active_children, None
+        return
+
+    name = cfg.get("agent_name", "Agent")
+    mission = cfg.get("agent_mission", "")
+    agent_type = cfg.get("agent_type", "")
+
+    if not history:
+        history.append({"role": "assistant", "content": f"👋 Hello! I'm {name}. How can I assist today?"})
+        yield history, "", "", active_children, None
+
+    # Add user message to history and display it immediately
+    history.append({"role": "user", "content": user_input})
+    yield history, "", "", active_children, None
+
+    if agent_type == "🎼 Orchestrator":
+        try:
+            from core.agents.orchestrator import OrchestratorAgent
+            global orchestrators
+            name = cfg.get("agent_name", "orchestrator")
+            
+            # Create a fresh orchestrator instance for new conversations, 
+            # but reuse existing instance to maintain state for execution
+            orch = orchestrators.get(name)
+            if orch is None:
+                # Import the runtime agents_config from app.py where it's dynamically updated
+                import sys
+                if 'app' in sys.modules:
+                    # Get the runtime agents_config that contains all deployed agents
+                    app_module = sys.modules['app']
+                    runtime_agents_config = getattr(app_module, 'agents_config', {})
+                else:
+                    # Fallback to config if app module not available
+                    from config import agents_config as runtime_agents_config
+                
+                # Create new orchestrator instance only if none exists
+                orch = OrchestratorAgent(runtime_agents_config, cast(str, cfg.get("api_key", "")))
+                orchestrators[name] = orch
+            
+            history.append({"role": "assistant", "content": ""})
+            orch_agent = cast(OrchestratorAgent, orch)
+            answer_gen = orch_agent.answer(history, user_input, debug=debug_flag)
+            async for msg in answer_gen:
+                if isinstance(msg, dict):
+                    chunk = msg.get("content", "")
+                    if chunk:
+                        history[-1]["content"] += chunk
+                else:
+                    history[-1]["content"] += str(msg)
+                invocation_log = build_log(orch) if hasattr(orch, 'invocations') and isinstance(orch, OrchestratorAgent) else ""
+                yield history, "", invocation_log, active_children, None
+        except ImportError:
+            history.append({"role": "assistant", "content": "Orchestrator not available."})
+            yield history, "", "", active_children, None
+        return
+
+    if active_children:
+        for child_json in active_children:
+            child_cfg = json.loads(child_json)
+            for output in _stream_to_agent(child_cfg, history, user_input, debug_flag, active_children):
+                yield output
+        return
+
+    skill_objs = []
+    if cfg.get("web_access", False):
+        web_tool = get_tool_by_name("search_internet", {"user_query": user_input})
+        if web_tool:
+            skill_objs.append(web_tool)
+    for skill_name in cfg.get("skills", []):
+        tool = get_tool_by_name(skill_name, {"user_query": user_input})
+        if tool:
+            skill_objs.append(tool)
+
+    # Pass allow_fallback, trusted_links, grounded_files to AgentLLMConnector
+    allow_fallback = cfg.get("allow_fallback", True)
+    trusted_links = cfg.get("trusted_links", [])
+    grounded_files = cfg.get("grounded_files", [])
+    
+    # Get global RAG retriever if available
+    rag_retriever = None
+    try:
+        import sys
+        if 'app' in sys.modules:
+            app_module = sys.modules['app']
+            rag_retriever = getattr(app_module, 'rag_retriever', None)
+    except:
+        pass  # No RAG retriever available
+    
+    conn = AgentLLMConnector(
+        api_key=cast(str, cfg.get("api_key", "")),
+        skills=skill_objs,
+        allow_fallback=allow_fallback,
+        trusted_links=trusted_links,
+        grounded_files=grounded_files,
+        rag_retriever=rag_retriever
+    )
+    model = conn.agent_model_mapping.get(agent_type, "gpt-5-mini")
+    has_history_tool = any(t.name == "history_taking" for t in skill_objs)
+    has_ipc_reporting = any(t.name == "IPC_reporting" for t in skill_objs)
+    
+    if agent_type == "🏥 Clinical Assistant" and has_history_tool:
+        system_content = (
+            f"You are {name}. {mission}\n\n"
+            "Before giving any advice, gather all necessary patient history by calling the "
+            "`history_taking` function. A JSON-schema has been provided with each question as a "
+            "parameter description. Ask wauestions, wait for the user's answer, and only "
+            "once every required field is filled will you then provide your final recommendation.\n\n"
+            "RESPONSE FORMAT: Keep responses concise and clinical. Avoid lengthy explanations unless specifically asked. "
+            "Focus on actionable recommendations and key clinical points."
+        )
+    else:
+        system_content = f"You are {name}." + (f" {mission}" if mission else "")
+        
+    # Add general instruction to keep responses focused and concise
+    system_content += (
+        "\n\nRESPONSE GUIDELINES:\n"
+        "- Be concise and clinically focused\n"
+        "- Provide clear, actionable recommendations\n"
+        "- Avoid excessive reasoning or explanation unless specifically requested\n"
+        "- Structure responses with clear sections when appropriate\n"
+        "- Use bullet points or numbered lists for multiple recommendations"
+    )
+        
+    # Add specific guidance for IPC reporting
+    if has_ipc_reporting:
+        system_content += (
+            "\n\nWhen users ask about reportable diseases, reporting requirements, or infection control reporting, "
+            "always offer to help with the specific reporting process. Use the IPC_reporting tool to provide "
+            "jurisdiction-specific requirements and generate formatted reports. "
+            "IMPORTANT: When calling IPC_reporting, include ALL conversation context in the case_summary parameter, "
+            "especially the specific organism/pathogen mentioned by the user (e.g., 'User asked about typhus fever reporting')."
+        )
+        
+    system_msg = {"role": "system", "content": system_content}
+    from collections import deque
+    recent = deque(history, maxlen=MAX_HISTORY)
+    history_msgs = [ {"role": m["role"], "content": m["content"]} for m in recent if m["role"] in ("user", "assistant")]
+    messages = [system_msg] + history_msgs
+    history.append({"role": "assistant", "content": ""})
+    buf = ""
+    tool_invoked = False
+    
+    async for token in conn.chat_with_agent_stream(model_name=model, messages=messages):
+        buf += token
+        history[-1]["content"] = buf
+        invocation_log = build_log(conn)
+        # Detect if a tool was invoked (by tool name in the reply)
+        for tool in skill_objs:
+            if tool.name in buf:
+                tool_invoked = True
+        yield history, "", invocation_log, active_children, None
+    
+    # Apply clinical validation and references to the final reply
+    original_reply = validate_and_reference_recommendation(buf.strip())
+
+    # --- Challenger step: adversarial critique if enabled ---
+
+    challenger_enabled = cfg.get("challenger_enabled", False)
+    critique = None
+    final_reply = original_reply
+
+    # --- Only run challenger if the required fields for the tool actually invoked are present, or if FORCE_CHALLENGE is present ---
+    def required_fields_present_for_invoked_tool():
+        # Try to infer which tool was actually invoked (last tool in skill_objs with a matching name in the reply)
+        from core.utils.skills_registry import get_tool_by_name
+        invoked_tool = None
+        for skill_name in cfg.get("skills", []):
+            if skill_name in original_reply:
+                invoked_tool = get_tool_by_name(skill_name, {"user_query": user_input})
+                break
+        if not invoked_tool and skill_objs:
+            invoked_tool = skill_objs[-1]  # fallback: last tool
+        if not invoked_tool:
+            return True  # fallback: allow
+        required_fields = invoked_tool.args_schema.get("required", [])
+        if not required_fields:
+            return True
+        for field in required_fields:
+            found = False
+            for m in history[::-1]:
+                if m["role"] == "user" and (field.replace("_", " ") in m["content"].lower() or field in m["content"].lower()):
+                    found = True
+                    break
+            if not found:
+                return False
+        return True
+
+    force_challenge = "FORCE_CHALLENGE" in user_input or "FORCE_CHALLENGE" in original_reply
+
+    # Always run challenger if enabled (or forced)
+    if challenger_enabled or force_challenge:
+        try:
+            from core.utils.llm_connector import challenge_agent_response, refine_final_answer
+            user_message = user_input
+            agent_reply = original_reply
+            # Pass conversation history to challenger for better context awareness
+            critique = await challenge_agent_response(user_message, agent_reply, history)
+            # If critique is None or empty, treat as OK
+            if not critique or critique.strip().upper() == "OK":
+                critique = "OK"
+                final_reply = original_reply
+            else:
+                # Use a refiner LLM to produce a clean, user-facing answer
+                final_reply = await refine_final_answer(user_message, original_reply, critique)
+        except Exception as e:
+            critique = f"[Challenger error: {e}]"
+            final_reply = original_reply
+
+    history[-1]["content"] = final_reply
+    invocation_log = build_log(conn)
+    yield history, "", invocation_log, active_children, {
+        "original_reply": original_reply,
+        "challenger_critique": critique,
+        "final_reply": final_reply
+    }

core/agents/orchestrator.py

@@ -0,0 +1,670 @@
+"""
+orchestrator.py
+---------------
+
+Coordinates multi-agent planning, tool invocation,        if context_results:
+            # Replanning m        system = (
+            "You are an orchestration assistant. A clinician's request may contain multiple distinct tasks "
+            "(e.g. antibiotic choice, duration, isolation, orders, literature search, quiz). "
+            "Here are your available agents:\n\n"
+            f"{json.dumps(avail, indent=2)}\n\n"
+            "Return *only* a JSON array of objects, each with exactly three keys:\n"
+            "  • action: always \"invoke\"\n"
+            "  • agent: one of the agent names above\n"
+            "  • prompt: the exact question to send to that agent\n"
+            "Do not include any extra text.\n\n"
+            "RESPONSE GUIDELINES:\n"
+            "- Be concise and clinically focused\n"
+            "- Provide clear, actionable recommendations\n"
+            "- Avoid excessive reasoning or explanation unless specifically requested"
+        )     system = (
+                "You are an expert replanning agent. Based on intermediate results, create an updated "
+                "execution plan that adapts to new information while maintaining original objectives.\n\n"
+                "Focus on:\n"
+                "1. Incorporating lessons from completed phases\n"
+                "2. Adjusting remaining phases based on i            summary = await call_llm(
+                [{"role": "user", "content": synthesis_prompt}],
+                model=SUMMARY_MODEL
+            )ediate findings\n"
+                "3. Optimizing parallel execution for efficiency\n"
+                "4. Setting new replanning conditions\n\n"
+                f"Available agents:\n{json.dumps(avail, indent=2)}\n\n"
+                f"Context from previous phases:\n{json.dumps(context_results, indent=2)}\n\n"
+                "Return updated plan in enhanced format (JSON):\n"
+                "{\n"
+                '  "execution_strategy": "description",\n'
+                '  "phases": [{"phase_id": "id", "description": "desc", "parallel_tasks": [{"task_id": "id", "agent": "name", "prompt": "task", "priority": "high", "dependencies": []}]}],\n'
+                '  "replanning_conditions": [{"condition": "desc", "trigger_phase": "id", "evaluation_prompt": "prompt"}]\n'
+                '}'
+            )
+        else:
+            # Initial planning mode
+            system = (
+                "You are an expert planning agent for an Infectious Disease consultation system. "
+                "Create sophisticated execution plans with parallel agent coordination and dynamic replanning.\n\n"
+                f"Available agents:\n{json.dumps(avail, indent=2)}\n\n"
+                "Output format (JSON):\n"
+                "{\n"
+                '  "execution_strategy": "description of approach",\n'
+                '  "phases": [\n'
+                '    {\n'
+                '      "phase_id": "phase_1",\n'
+                '      "description": "phase description",\n'
+                '      "parallel_tasks": [\n'
+                '        {\n'
+                '          "task_id": "task_1",\n'
+                '          "agent": "agent_name",\n'
+                '          "prompt": "specific task",\n'
+                '          "priority": "high|medium|low",\n'
+                '          "dependencies": ["task_id"]\n'
+                '        }\n'
+                '      ]\n'
+                '    }\n'
+                '  ],\n'
+                '  "replanning_conditions": [\n'
+                '    {\n'
+                '      "condition": "description",\n'
+                '      "trigger_phase": "phase_id",\n'
+                '      "evaluation_prompt": "LLM prompt for evaluation"\n'
+                '    }\n'
+                '  ]\n'
+                '}'
+            )se synthesis for the AI agent system.
+
+- Defines the OrchestratorAgent class, which manages agent selection, planning, and execution.
+- Handles user input decomposition, tool invocation, and error handling.
+- Integrates with OpenAI and the tool registry for dynamic agent workflows.
+- Provides robust logging, request tracking, and user-friendly error messages.
+- Designed for future compatibility with Model Context Protocol (MCP) and Agent-to-Agent (A2A) standards.
+
+"""
+
+# orchestrator.py
+
+import os
+import json
+import re
+import asyncio
+from typing import Any, Dict, List, Optional
+from openai import OpenAI
+from core.utils.llm_connector import AgentLLMConnector, call_llm
+from core.utils.skills_registry import get_tool_by_name
+
+GREETING_RE = re.compile(r"^(hi|hello|hey|good\s(morning|afternoon|evening))\b", re.I)
+PLANNER_MODEL = "gpt-5"      # Use GPT-5 for planning
+SUMMARY_MODEL = "gpt-5"      # Use GPT-5 for summaries
+
+import uuid
+import datetime
+
+class OrchestratorAgent:
+    """
+    The OrchestratorAgent coordinates multiple AI agent tools to fulfill complex user requests.
+
+    Attributes:
+        cfg (Dict[str, str]): Configuration for available agents.
+        client (OpenAI): OpenAI client for LLM calls.
+        state (dict): Tracks the current plan, subtask progress, and results.
+        invocations (List[Dict[str, Any]]): Audit log of tool invocations and results.
+    """
+    def __init__(self, agents_cfg: Dict[str, str], api_key: str):
+        """
+        Initialize the OrchestratorAgent.
+
+        Args:
+            agents_cfg (Dict[str, str]): Configuration for available agents.
+            api_key (str): API key for OpenAI.
+        """
+        self.cfg    = agents_cfg
+        self.client = OpenAI(api_key=api_key)
+        self.state = {
+            "plan": [],              # list of {"action","agent","prompt","priority","dependencies"}
+            "current_phase": 0,      # which execution phase we're on
+            "subtask_convos": {},    # maps step index -> convo so far
+            "results": {},           # agent_key -> [final outputs]
+            "intermediate_results": {},  # step_id -> intermediate results for replanning
+            "execution_phases": [],  # list of phases with parallel execution groups
+            "replanning_triggers": []  # conditions that trigger replanning
+        }
+        self.invocations: List[Dict[str,Any]] = []
+
+    async def planning_agent(self, user_input: str, context_results: Optional[Dict] = None) -> Dict:
+        """
+        Enhanced planning agent that creates parallel execution plans with replanning conditions.
+
+        Args:
+            user_input (str): The user's request or question.
+            context_results (Optional[Dict]): Context from previous phases for replanning.
+
+        Returns:
+            Dict: Enhanced plan with phases, parallel tasks, and replanning conditions.
+        """
+        agent_keys = list(self.cfg.keys())
+        avail = []
+        history_agent = None
+        for name in agent_keys:
+            cfg = json.loads(self.cfg[name])
+            avail.append({
+                "name":    name,
+                "mission": cfg.get("agent_mission",""),
+                "skills":  cfg.get("skills",[])
+            })
+            if history_agent is None and "history_taking" in cfg.get("skills", []):
+                history_agent = name
+
+        system = (
+            "You are an orchestration assistant. A clinician’s request may contain multiple distinct tasks "
+            "(e.g. antibiotic choice, duration, isolation, orders, literature search, quiz). "
+            "Here are your available agents:\n\n"
+            f"{json.dumps(avail, indent=2)}\n\n"
+            "Return *only* a JSON array of objects, each with exactly three keys:\n"
+            "  • action: always \"invoke\"\n"
+            "  • agent: one of the agent names above\n"
+            "  • prompt: the exact question to send to that agent\n"
+            "Do not include any extra text."
+        )
+        # **critical fix**: pass the model name
+        plan_str = await call_llm(
+            [{"role":"system","content":system},
+             {"role":"user","content":user_input}],
+            model=PLANNER_MODEL
+        )
+        self.invocations.append({
+            "tool":"enhanced_planning_agent",
+            "args":{"user_input":user_input, "context_results": context_results},
+            "result":plan_str
+        })
+
+        try:
+            plan = json.loads(plan_str)
+            
+            # Validate and convert plan format if needed
+            if isinstance(plan, list):
+                # Old format: convert list to enhanced dictionary format
+                enhanced_plan = {
+                    "execution_strategy": "sequential_legacy",
+                    "phases": [{
+                        "phase_id": "phase_1",
+                        "description": "Legacy sequential execution",
+                        "parallel_tasks": []
+                    }],
+                    "replanning_conditions": []
+                }
+                
+                # Convert each list item to a parallel task
+                for i, task in enumerate(plan):
+                    if isinstance(task, dict) and "agent" in task:
+                        enhanced_plan["phases"][0]["parallel_tasks"].append({
+                            "task_id": f"task_{i+1}",
+                            "agent": task.get("agent", "stewardship_agent"),
+                            "prompt": task.get("prompt", user_input),
+                            "priority": "medium",
+                            "dependencies": []
+                        })
+                
+                return enhanced_plan
+            
+            elif isinstance(plan, dict):
+                # Enhanced format: validate required keys
+                if "phases" not in plan:
+                    plan["phases"] = [self._create_default_phase(user_input, avail, history_agent)]
+                if "execution_strategy" not in plan:
+                    plan["execution_strategy"] = "enhanced_parallel"
+                if "replanning_conditions" not in plan:
+                    plan["replanning_conditions"] = []
+                
+                return plan
+            
+            else:
+                # Invalid format: use fallback
+                return self._create_fallback_plan(user_input, avail, history_agent)
+                
+        except json.JSONDecodeError:
+            # Fallback to simple plan
+            return self._create_fallback_plan(user_input, avail, history_agent)
+
+    def _create_fallback_plan(self, user_input: str, avail: List[Dict], history_agent: Optional[str] = None) -> Dict[str, Any]:
+        """Create a simple fallback plan when advanced planning fails."""
+        fallback_plan = {
+            "execution_strategy": "sequential",
+            "phases": [{
+                "phase_id": 1,
+                "description": "Fallback sequential execution",
+                "parallel_tasks": []
+            }],
+            "replanning_conditions": [],
+            "success_criteria": "Complete all agent responses"
+        }
+        
+        # Add history agent first if available
+        if history_agent:
+            fallback_plan["phases"][0]["parallel_tasks"].append({
+                "task_id": "history_task",
+                "action": "invoke",
+                "agent": history_agent,
+                "prompt": "Gather necessary patient history before proceeding",
+                "priority": "high",
+                "estimated_duration": "medium",
+                "dependencies": [],
+                "replanning_triggers": []
+            })
+        
+        # Add a general agent task
+        if avail:
+            default_agent = avail[0]["name"]
+            fallback_plan["phases"][0]["parallel_tasks"].append({
+                "task_id": "main_task",
+                "action": "invoke", 
+                "agent": default_agent,
+                "prompt": user_input,
+                "priority": "high",
+                "estimated_duration": "medium",
+                "dependencies": ["history_task"] if history_agent else [],
+                "replanning_triggers": []
+            })
+            
+        return fallback_plan
+    
+    def _validate_and_organize_plan(self, plan: Dict[str, Any], agent_keys: List[str], history_agent: Optional[str] = None) -> Dict[str, Any]:
+        """Validate and organize the enhanced plan."""
+        validated_plan = {
+            "execution_strategy": plan.get("execution_strategy", "sequential"),
+            "phases": [],
+            "replanning_conditions": plan.get("replanning_conditions", []),
+            "success_criteria": plan.get("success_criteria", "Complete all tasks successfully")
+        }
+        
+        # Validate each phase
+        for phase in plan.get("phases", []):
+            validated_phase = {
+                "phase_id": phase.get("phase_id", 1),
+                "description": phase.get("description", "Execution phase"),
+                "parallel_tasks": []
+            }
+            
+            # Validate each task in the phase
+            for task in phase.get("parallel_tasks", []):
+                if (task.get("agent") in agent_keys and 
+                    task.get("action") == "invoke" and 
+                    isinstance(task.get("prompt"), str)):
+                    
+                    validated_task = {
+                        "task_id": task.get("task_id", f"task_{len(validated_phase['parallel_tasks'])}"),
+                        "action": "invoke",
+                        "agent": task["agent"],
+                        "prompt": task["prompt"],
+                        "priority": task.get("priority", "medium"),
+                        "estimated_duration": task.get("estimated_duration", "medium"),
+                        "dependencies": task.get("dependencies", []),
+                        "replanning_triggers": task.get("replanning_triggers", [])
+                    }
+                    validated_phase["parallel_tasks"].append(validated_task)
+            
+            if validated_phase["parallel_tasks"]:
+                validated_plan["phases"].append(validated_phase)
+        
+        # Ensure we have at least one phase
+        if not validated_plan["phases"]:
+            validated_plan = self._create_fallback_plan("", [{"name": list(agent_keys)[0] if agent_keys else "default"}], history_agent)
+            
+        return validated_plan
+
+    async def _execute_parallel_tasks(self, tasks: List[Dict[str, Any]], history: List[Dict]) -> Dict[str, Any]:
+        """Execute a group of tasks in parallel."""
+        import asyncio
+        from core.utils.llm_connector import AgentLLMConnector
+        from core.utils.skills_registry import get_tool_by_name
+        
+        # Create coroutines for each task
+        task_coroutines = []
+        task_ids = []
+        
+        for task in tasks:
+            # Check dependencies
+            dependencies_met = True
+            for dep in task.get("dependencies", []):
+                if dep not in self.state["intermediate_results"]:
+                    dependencies_met = False
+                    break
+            
+            if not dependencies_met:
+                continue  # Skip this task for now
+                
+            task_ids.append(task["task_id"])
+            task_coroutines.append(self._execute_single_task(task, history))
+        
+        # Execute tasks in parallel
+        if task_coroutines:
+            results = await asyncio.gather(*task_coroutines, return_exceptions=True)
+            
+            # Process results
+            phase_results = {}
+            for i, result in enumerate(results):
+                task_id = task_ids[i]
+                if isinstance(result, Exception):
+                    phase_results[task_id] = {"error": str(result), "success": False}
+                else:
+                    phase_results[task_id] = {"result": result, "success": True}
+                    # Store for potential replanning
+                    self.state["intermediate_results"][task_id] = result
+                    
+            return phase_results
+        
+        return {}
+
+    async def _execute_single_task(self, task: Dict[str, Any], history: List[Dict]) -> str:
+        """Execute a single agent task."""
+        from core.utils.llm_connector import AgentLLMConnector
+        from core.utils.skills_registry import get_tool_by_name
+        
+        agent_key = task["agent"]
+        prompt = task["prompt"]
+        
+        # Get agent configuration
+        cfg = json.loads(self.cfg[agent_key])
+        skills = [get_tool_by_name(s, {"user_query": prompt}) for s in cfg.get("skills", [])]
+        skills = [t for t in skills if t]
+        
+        # Create agent connector
+        child = AgentLLMConnector(api_key=self.client.api_key, skills=skills)
+        
+        # Prepare messages
+        sys_msg = {"role": "system", "content": f"You are {cfg['agent_name']}, a {cfg['agent_type']} agent."}
+        user_msg = {"role": "user", "content": prompt}
+        
+        # Execute and collect response
+        response_buffer = ""
+        async for token in child.chat_with_agent_stream(
+            model_name=child.agent_model_mapping[cfg["agent_type"]],
+            messages=[sys_msg, user_msg]
+        ):
+            response_buffer += token
+            
+        return response_buffer.strip()
+
+    async def _execute_single_task_with_timeout(self, task: Dict[str, Any], history: List[Dict], timeout: int = 45) -> Dict[str, Any]:
+        """Execute a single task with timeout and simplified error handling."""
+        import asyncio
+        
+        try:
+            # Execute with timeout
+            result = await asyncio.wait_for(
+                self._execute_single_task_fast(task, history), 
+                timeout=timeout
+            )
+            return {"success": True, "result": result}
+        except asyncio.TimeoutError:
+            return {"success": False, "error": f"Task timed out after {timeout} seconds"}
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+
+    async def _execute_single_task_fast(self, task: Dict[str, Any], history: List[Dict]) -> str:
+        """Fast execution with minimal tool usage."""
+        from core.utils.llm_connector import AgentLLMConnector
+        
+        agent_key = task["agent"]
+        prompt = task["prompt"]
+        
+        # Get agent configuration
+        cfg = json.loads(self.cfg[agent_key])
+        
+        # Use simplified agent with minimal tools for speed
+        child = AgentLLMConnector(api_key=self.client.api_key, skills=[])
+        
+        # Add concise response guidelines
+        system_content = f"You are {cfg['agent_name']}, a {cfg['agent_type']} agent. {cfg.get('agent_mission', '')}"
+        system_content += (
+            "\n\nRESPONSE GUIDELINES:\n"
+            "- Be concise and clinically focused\n"
+            "- Provide clear, actionable recommendations\n"
+            "- Avoid excessive reasoning or explanation\n"
+            "- Structure responses with bullet points when appropriate\n"
+            "- Maximum 300 words"
+        )
+        
+        sys_msg = {"role": "system", "content": system_content}
+        user_msg = {"role": "user", "content": prompt}
+        
+        # Execute and collect response
+        response_buffer = ""
+        async for token in child.chat_with_agent_stream(
+            model_name=child.agent_model_mapping.get(cfg["agent_type"], "gpt-4o-mini"),
+            messages=[sys_msg, user_msg]
+        ):
+            response_buffer += token
+            
+        return response_buffer.strip()[:2000]  # Limit response length
+
+    async def _generate_updated_synthesis(self, new_context: str, results: Dict) -> str:
+        """Generate updated synthesis incorporating new user context."""
+        from core.utils.llm_connector import call_llm
+        
+        synthesis_prompt = (
+            "You are an expert clinical synthesizer. The user has provided additional context to an existing clinical recommendation. "
+            "Create a focused update that incorporates this new information.\n\n"
+            f"New context from user: {new_context}\n\n"
+            f"Previous recommendations: {json.dumps(results, indent=2)}\n\n"
+            "RESPONSE GUIDELINES:\n"
+            "- Focus specifically on how the new context changes recommendations\n"
+            "- Be concise and clinically focused\n"
+            "- Provide clear, actionable updates\n"
+            "- Use bullet points for specific changes\n"
+            "- Maximum 400 words\n\n"
+            "Provide only the updated/modified recommendations based on the new context:"
+        )
+        
+        try:
+            updated_response = await call_llm(
+                [{"role": "user", "content": synthesis_prompt}],
+                model="gpt-4o-mini"
+            )
+            return updated_response
+        except Exception as e:
+            return f"Unable to generate updated synthesis: {str(e)}"
+
+    async def _check_replanning_conditions(self, phase_results: Dict[str, Any], current_phase: Dict[str, Any]) -> bool:
+        """Check if replanning is needed based on intermediate results."""
+        # Check global replanning conditions
+        for condition in self.state.get("replanning_conditions", []):
+            if await self._evaluate_condition(condition, phase_results):
+                return True
+        
+        # Check task-specific replanning triggers
+        for task in current_phase.get("parallel_tasks", []):
+            task_id = task["task_id"]
+            if task_id in phase_results:
+                result = phase_results[task_id]
+                for trigger in task.get("replanning_triggers", []):
+                    if await self._evaluate_trigger(trigger, result):
+                        return True
+                        
+        return False
+
+    async def _evaluate_condition(self, condition: str, results: Dict[str, Any]) -> bool:
+        """Evaluate a replanning condition using LLM."""
+        evaluation_prompt = (
+            f"Evaluate if this condition is met based on the results:\n"
+            f"Condition: {condition}\n"
+            f"Results: {json.dumps(results, indent=2)}\n"
+            f"Return only 'true' or 'false'."
+        )
+        
+        response = await call_llm(
+            [{"role": "user", "content": evaluation_prompt}],
+            model="gpt-5-mini"
+        )
+        
+        return response.strip().lower() == "true"
+    
+    async def _evaluate_trigger(self, trigger: str, result: Dict[str, Any]) -> bool:
+        """Evaluate a specific replanning trigger."""
+        evaluation_prompt = (
+            f"Evaluate if this trigger condition is met:\n"
+            f"Trigger: {trigger}\n"
+            f"Task Result: {json.dumps(result, indent=2)}\n"
+            f"Return only 'true' or 'false'."
+        )
+        
+        response = await call_llm(
+            [{"role": "user", "content": evaluation_prompt}],
+            model="gpt-5-mini"
+        )
+        
+        return response.strip().lower() == "true"
+
+    def _create_default_phase(self, user_input, avail, history_agent):
+        """Create a default phase when validation fails."""
+        return {
+            "phase_id": "default_phase",
+            "description": "Default sequential execution",
+            "parallel_tasks": [{
+                "task_id": "default_task",
+                "agent": "stewardship_agent",
+                "prompt": user_input,
+                "priority": "medium",
+                "dependencies": []
+            }]
+        }
+
+    import uuid
+    import datetime
+    async def answer(self, history, user_input, debug=False):
+        """
+        Enhanced main entry point with parallel execution and dynamic replanning.
+
+        Args:
+            history (list): Conversation history for context.
+            user_input (str): The user's request or question.
+            debug (bool): If True, enables debug output.
+
+        Yields:
+            dict: Assistant responses, including streaming output and error messages.
+        """
+        from tools.utils import ToolExecutionError, logger
+        request_id = str(uuid.uuid4())
+        request_time = datetime.datetime.utcnow().isoformat()
+        
+        try:
+            if GREETING_RE.match(user_input.strip()):
+                logger.info(f"[request_id={request_id}] Greeting detected. user_input={user_input!r}")
+                yield {"role":"assistant","content":"👋 Hello! How can I help?"}
+                return
+
+            # Enhanced planning with parallel execution support
+            if not self.state.get("execution_phases"):
+                logger.info(f"[request_id={request_id}] Starting enhanced planning...")
+                enhanced_plan = await self.planning_agent(user_input)
+                self.state["execution_phases"] = enhanced_plan["phases"]
+                self.state["replanning_conditions"] = enhanced_plan["replanning_conditions"]
+                
+                logger.info(f"[request_id={request_id}] Enhanced plan created with {len(enhanced_plan['phases'])} phases")
+                yield {"role":"assistant", "content":f"🎯 **Enhanced Execution Plan ({enhanced_plan['execution_strategy']}):**\n```json\n{json.dumps(enhanced_plan, indent=2)}\n```\n\n**Ready to execute!** Say 'proceed' to start execution or provide additional context."}
+                return
+
+            # Check if user wants to proceed with execution
+            proceed_keywords = ["proceed", "execute", "start", "go", "continue", "run"]
+            if any(keyword in user_input.lower() for keyword in proceed_keywords):
+                # Fast execution mode - execute tasks sequentially with timeout
+                yield {"role":"assistant", "content":"🚀 **Executing plan...**"}
+                
+                all_results = []
+                total_tasks = sum(len(phase["parallel_tasks"]) for phase in self.state["execution_phases"])
+                completed_tasks = 0
+                
+                for phase in self.state["execution_phases"]:
+                    for task in phase["parallel_tasks"]:
+                        completed_tasks += 1
+                        yield {"role":"assistant", "content":f"⚡ **Task {completed_tasks}/{total_tasks}:** {task['agent']} - {task['prompt'][:100]}..."}
+                        
+                        # Execute task with timeout
+                        try:
+                            result = await self._execute_single_task_with_timeout(task, history, timeout=45)
+                            if result.get("success"):
+                                all_results.append({
+                                    "agent": task["agent"],
+                                    "result": result["result"]
+                                })
+                                yield {"role":"assistant", "content":f"✅ **{task['agent']} completed**"}
+                            else:
+                                yield {"role":"assistant", "content":f"⚠️ **{task['agent']} failed** - {result.get('error', 'Unknown error')}"}
+                        except Exception as e:
+                            yield {"role":"assistant", "content":f"⚠️ **{task['agent']} timeout/error** - {str(e)[:100]}"}
+                
+                # Mark all phases as complete
+                self.state["current_phase"] = len(self.state["execution_phases"])
+                self.state["results"] = {result["agent"]: [result["result"]] for result in all_results}
+            else:
+                # User provided additional context - update the plan to incorporate it
+                yield {"role":"assistant", "content":"📝 **Processing additional context...**"}
+                
+                # Check if execution is complete and user wants updated synthesis
+                if self.state["current_phase"] >= len(self.state["execution_phases"]) and self.state.get("results"):
+                    # Generate updated synthesis with new context
+                    updated_synthesis = await self._generate_updated_synthesis(user_input, self.state["results"])
+                    yield {"role":"assistant", "content":f"� **Updated recommendation incorporating your context:**\n\n{updated_synthesis}"}
+                    return
+                
+                # If execution not started, update the plan with new context
+                if not self.state.get("results"):
+                    # Add context to existing plan
+                    self.state["additional_context"] = self.state.get("additional_context", [])
+                    self.state["additional_context"].append(user_input)
+                    
+                    # Update task prompts to include new context
+                    context_update = f"Additional context: {user_input}"
+                    for phase in self.state["execution_phases"]:
+                        for task in phase["parallel_tasks"]:
+                            if not task["prompt"].endswith(context_update):
+                                task["prompt"] += f"\n\n{context_update}"
+                    
+                    yield {"role":"assistant", "content":"✅ **Context incorporated into execution plan.** Say 'proceed' to start execution with updated context."}
+                else:
+                    yield {"role":"assistant", "content":"📝 **Additional context noted.** Say 'proceed' to continue or provide more details."}
+                return
+
+            # Enhanced synthesis with intermediate results
+            all_results = {
+                "agent_results": self.state["results"],
+                "intermediate_results": self.state["intermediate_results"],
+                "execution_summary": {
+                    "total_phases": len(self.state["execution_phases"]),
+                    "parallel_execution": True,
+                    "replanning_occurred": len(self.state.get("replanning_conditions", [])) > 0
+                }
+            }
+            
+            synthesis_prompt = (
+                "You are an expert clinical synthesizer. Create a comprehensive, actionable response by combining:\n"
+                "1. All agent outputs into coherent clinical recommendations\n"
+                "2. Highlight any conflicting advice and provide resolution\n"
+                "3. Prioritize recommendations by clinical urgency\n"
+                "4. Include specific next steps for the clinician\n\n"
+                "RESPONSE GUIDELINES:\n"
+                "- Be concise and clinically focused\n"
+                "- Provide clear, actionable recommendations\n"
+                "- Avoid excessive reasoning or explanation unless specifically requested\n"
+                "- Structure responses with clear sections when appropriate\n"
+                "- Use bullet points or numbered lists for multiple recommendations\n\n"
+                f"Results to synthesize:\n{json.dumps(all_results, indent=2)}"
+            )
+            
+            summary = await call_llm(
+                [{"role":"system","content": synthesis_prompt}],
+                model=SUMMARY_MODEL
+            )
+            
+            logger.info(f"[request_id={request_id}] Enhanced synthesis complete. Summary length: {len(summary)}")
+            yield {"role":"assistant","content":f"🎯 **Comprehensive Clinical Recommendation:**\n\n{summary}"}
+
+        except ToolExecutionError as te:
+            logger.error(f"[request_id={request_id}] ToolExecutionError [{te.code}]: {te.message} | user_input={user_input!r}")
+            yield {
+                "role": "assistant",
+                "content": f"❗ Error ({te.code}) [Request ID: {request_id} | {request_time}]: {te.user_message}"
+            }
+        except Exception as e:
+            logger.exception(f"[request_id={request_id}] Unexpected error in enhanced orchestrator | user_input={user_input!r}")
+            yield {
+                "role": "assistant",
+                "content": f"❗ An unexpected error occurred in enhanced orchestrator. [Request ID: {request_id} | {request_time}] Please try again or contact support."
+            }

core/ui/__init__.py

@@ -0,0 +1 @@
+# UI components for the ID Agents application

core/ui/ui.py

@@ -0,0 +1,111 @@
+import gradio as gr
+import json
+from core.agents.agent_utils import build_agent, preload_demo_chat, prepare_download, load_prefilled
+from core.agents.chat_orchestrator import simulate_agent_response_stream
+import logging
+from config import agents_config, skills_library, prefilled_agents
+
+def show_landing():
+    return gr.update(visible=True),  gr.update(visible=False), gr.update(visible=False)
+
+def show_builder():
+    return gr.update(visible=False), gr.update(visible=True),  gr.update(visible=False)
+
+def show_chat():
+    return gr.update(visible=False), gr.update(visible=False), gr.update(visible=True)
+
+def build_active_agents_markdown_and_dropdown():
+    if not agents_config:
+        return "### 🧠 Active Agents\n_(None yet)_", []
+    output = "### 🧠 Active Agents\n"
+    dropdown_choices = []
+    for name, agent_json in agents_config.items():
+        agent_type = json.loads(agent_json)["agent_type"]
+        output += f"- {name} ({agent_type})\n"
+        dropdown_choices.append(name)
+    return output, dropdown_choices
+
+def refresh_active_agents_widgets():
+    md, dd = build_active_agents_markdown_and_dropdown()
+    return gr.update(value=md), gr.update(choices=dd, value=None)
+
+# All other UI callback functions from app.py
+def build_ui():
+    def _convert_history_for_gradio(history):
+        # Convert OpenAI-style history to Gradio Chatbot format: [(user, assistant), ...]
+        result = []
+        last_user = None
+        for msg in history:
+            if msg["role"] == "user":
+                last_user = msg["content"]
+            elif msg["role"] == "assistant":
+                if last_user is not None:
+                    result.append((last_user, msg["content"]))
+                    last_user = None
+                else:
+                    # orphan assistant message (e.g. greeting)
+                    result.append((None, msg["content"]))
+        if last_user is not None:
+            result.append((last_user, None))
+        return result
+
+    # --- App Layout ---
+    with gr.Blocks() as app:
+        chat_histories = gr.State({})
+        with gr.Row():
+            with gr.Column(scale=3):
+                # Use unique elem_id for each chatbox
+                builder_chatbox = gr.Chatbot(elem_id="builder-chatbox")
+                # ...other chat UI elements (inputs, buttons, etc.)...
+            with gr.Column(scale=3):
+                # If you have a deployed chatbox elsewhere, ensure it also uses a unique elem_id, e.g., "deployed-chatbox"
+                deployed_chatbox = gr.Chatbot(elem_id="deployed-chatbox")
+            with gr.Column(scale=1):
+                gr.HTML(
+                    """
+                    <div id=\"sidebar\" style=\"width:100%;height:600px;border:1px solid #ccc;\">
+                      <iframe id=\"sidebar-iframe\" src=\"\" style=\"width:100%;height:100%;border:none;\"></iframe>
+                    </div>
+                    """,
+                    elem_id="sidebar-html"
+                )
+
+        # Add a shared class to all chatboxes by elem_id, then intercept links for all with that class
+        gr.HTML(
+            """
+            <script>
+            // Add shared class to all chatboxes by elem_id
+            function addChatboxSharedClass() {
+                ["builder-chatbox", "deployed-chatbox"].forEach(function(id) {
+                    var el = document.getElementById(id);
+                    if (el && !el.classList.contains("chatbox-shared")) {
+                        el.classList.add("chatbox-shared");
+                    }
+                });
+            }
+            // Run on load and after each Gradio update
+            document.addEventListener("DOMContentLoaded", addChatboxSharedClass);
+            document.addEventListener("gradio:updated", addChatboxSharedClass);
+
+            // Intercept chat links for all chatboxes with shared class
+            document.addEventListener("click", function(e) {
+                let target = e.target;
+                if (target.tagName === "A" && target.closest(".chatbox-shared")) {
+                    e.preventDefault();
+                    let iframe = document.getElementById("sidebar-iframe");
+                    if (iframe) {
+                        iframe.src = target.href;
+                    }
+                }
+            }, true);
+            </script>
+            """,
+            elem_id="sidebar-js"
+        )
+        # ...rest of your UI and callback wiring...
+    return app
+"""
+ui.py
+------
+Gradio UI layout, callbacks, and event wiring for the modular AI agent system.
+"""

core/utils/__init__.py

@@ -0,0 +1 @@
+# Utility modules for the ID Agents application

core/utils/llm_connector.py

@@ -0,0 +1,467 @@
+async def challenge_agent_response(user_message: str, agent_reply: str, conversation_history: list = None, challenge_prompt: str = None, model: str = None) -> str:
+    """
+    Uses an LLM to adversarially critique the agent's draft reply before it is shown to the user.
+    Returns either the original reply, a corrected reply, or a warning if unsafe/incomplete.
+    
+    Args:
+        user_message: The current user input
+        agent_reply: The agent's draft response
+        conversation_history: List of previous messages for context (optional)
+        challenge_prompt: Optional custom prompt template
+        model: LLM model to use
+    """
+    
+    # Skip challenger if the agent is properly asking for required information for tool calling
+    # These are legitimate information-gathering responses that should not be critiqued
+    info_gathering_patterns = [
+        "I need some additional information",
+        "I need some specific information", 
+        "To recommend.*I need",
+        "To provide.*I need",
+        "Please provide.*required information",
+        "required information.*for.*therapy",
+        "following required information",
+        "need.*following.*information",
+        "Could you please provide",
+        "Patient age.*allergies.*laboratory.*results",  # Specific empiric therapy pattern
+        "age.*known drug allergies.*laboratory results",  # Alternative pattern
+        "provide.*information.*and.*assist.*determining",  # Tool workflow pattern
+        "Patient age or age bracket.*allergies.*laboratory results.*Culture.*sensitivity",  # Exact empiric therapy pattern
+        "Please provide this information.*assist.*determining.*treatment"  # Tool conclusion pattern
+    ]
+    
+    # Additional patterns for ongoing tool workflows that should not be critiqued
+    ongoing_workflow_patterns = [
+        "🔔 Tool.*invoked",  # Tool invocation indicator
+        "still need.*following.*information",  # Continuing info gathering
+        "appears.*issue.*reporting.*process",  # IPC reporting continuation
+        "ensure.*report.*completed.*correctly",  # Report completion workflow
+        "provide.*following.*details.*clear.*format",  # Structured data collection
+        "formatted.*correctly.*proceed.*report",  # Report finalization
+        "Sorry.*ran into.*issue.*tool",  # Tool error messages that should not be critiqued
+        "Could you please clarify or try again",  # Tool error recovery
+        "No current reporting requirements found",  # IPC search failures
+        "Unable to find current reporting requirements"  # IPC search failures
+    ]
+    
+    # Check conversation history for ongoing tool workflows
+    is_ongoing_workflow = False
+    if conversation_history:
+        recent_messages = conversation_history[-10:]  # Check last 10 messages
+        for msg in recent_messages:
+            if msg.get("role") == "assistant" and msg.get("content"):
+                content = msg["content"]
+                # Check if recent conversation involved tool usage
+                if any(pattern in content for pattern in ["🔔 Tool", "invoked", "reporting", "provide the following"]):
+                    is_ongoing_workflow = True
+                    break
+    
+    # Skip challenger for ongoing workflows unless there's a clear safety issue
+    if is_ongoing_workflow:
+        # Only challenge if there are obvious safety concerns
+        safety_keywords = ["dosage", "contraindicated", "allergy", "toxic", "dangerous", "fatal"]
+        has_safety_concern = any(keyword in agent_reply.lower() for keyword in safety_keywords)
+        if not has_safety_concern:
+            with open("challenger_debug.log", "a", encoding="utf-8") as f:
+                f.write("\n--- Challenger SKIPPED (Ongoing Tool Workflow) ---\n")
+                f.write(f"Agent reply: {agent_reply[:200]}...\n")
+            return "OK"
+    
+    import re
+    for pattern in info_gathering_patterns + ongoing_workflow_patterns:
+        if re.search(pattern, agent_reply, re.IGNORECASE):
+            # This is a legitimate info-gathering response, don't critique it
+            # DEBUG: Log when challenger is skipped
+            with open("challenger_debug.log", "a", encoding="utf-8") as f:
+                f.write("\n--- Challenger SKIPPED (Info Gathering Response) ---\n")
+                f.write(f"Pattern matched: {pattern}\n")
+                f.write(f"Agent reply: {agent_reply[:200]}...\n")
+            return "OK"
+    
+    if not challenge_prompt:
+        # Build context from conversation history if available
+        context_str = ""
+        if conversation_history:
+            recent_context = conversation_history[-6:]  # Last 6 messages for context
+            context_lines = []
+            for msg in recent_context:
+                role = msg.get("role", "")
+                content = msg.get("content", "")[:200]  # Limit length
+                if role and content:
+                    context_lines.append(f"{role}: {content}")
+            if context_lines:
+                context_str = f"\n\nConversation context:\n" + "\n".join(context_lines) + "\n"
+        
+        challenge_prompt = (
+            "You are a clinical safety and accuracy reviewer for an infectious diseases AI assistant. "
+            "Given the user's question and the agent's draft reply, identify any clinical errors, unsafe advice, missing references, or unsupported statements. "
+            "Consider the conversation context to understand if this is part of an ongoing workflow (like data collection for reporting or treatment planning). "
+            "If the reply is safe and accurate, or if it's part of a legitimate ongoing process, respond with 'OK'. "
+            "If you find a problem, respond with a short warning or correction, and suggest a safer or more accurate reply if possible. "
+            f"{context_str}"
+            "\n\nUser question: {user_message}\n\nAgent reply: {agent_reply}"
+        )
+    prompt = challenge_prompt.format(user_message=user_message, agent_reply=agent_reply)
+    # --- FORCE a challenger suggestion for testing ---
+    # If the agent reply contains a special marker, always suggest a new answer
+    if "FORCE_CHALLENGE" in agent_reply or "FORCE_CHALLENGE" in user_message:
+        # Instead of a canned string, return a realistic sample answer for testing
+        return (
+            "Micafungin is an effective antifungal for Candida species, including C. albicans, but it achieves low concentrations in urine. "
+            "For urinary tract infections caused by C. albicans, fluconazole is generally preferred due to its high urinary excretion. "
+            "If the isolate is susceptible, consider switching to fluconazole. If fluconazole cannot be used (e.g., resistance or intolerance), amphotericin B deoxycholate is an alternative. "
+            "Always tailor antifungal therapy to the patient's clinical status and susceptibility results."
+        )
+    critique = await call_llm(prompt, model=model)
+    # DEBUG: Log the prompt and critique for challenger step
+    with open("challenger_debug.log", "a", encoding="utf-8") as f:
+        f.write("\n--- Challenger Call ---\n")
+        f.write(f"Prompt:\n{prompt}\n")
+        f.write(f"Critique:\n{critique}\n")
+    return critique
+
+async def refine_final_answer(user_message: str, original_reply: str, critique: str, model: str = None) -> str:
+    """
+    Given the user message, original agent reply, and the challenger critique (which may include warnings and a suggested revision),
+    draft a clean, precise, and accurate reply for the user. If a suggested revision is present, use it. Do not include any warnings,
+    critique, or meta-commentary—just the best final answer.
+    """
+    prompt = (
+        "You are an expert clinical assistant. Given the user's question, the agent's original answer, and the critique (which may include warnings and a suggested revision), "
+        "draft a clean, precise, and accurate reply for the user. If a suggested revision is present, use it. "
+        "Do not include any warnings, critique, or meta-commentary—just the best final answer.\n\n"
+        f"User question: {user_message}\n\nAgent original answer: {original_reply}\n\nCritique: {critique}\n\nFinal user-facing answer:"
+    )
+    return await call_llm(prompt, model=model)
+"""
+llm_connector.py
+---------------
+
+Abstraction layer for LLM (OpenAI) API calls, with retry logic, streaming, and agent skill integration.
+
+- Provides AgentLLMConnector for managing LLM chat, streaming, and function/tool calls.
+- Implements robust retry/backoff for API reliability.
+- Supports skill registration and OpenAI function-calling interface.
+- Used by orchestrator and app for all LLM interactions.
+- Designed for future integration with Model Context Protocol (MCP) and Agent-to-Agent (A2A) standards.
+
+"""
+
+import os
+import json
+import time
+import random
+import asyncio
+
+
+# --- OpenAI Client Setup ---
+import openai
+from openai import RateLimitError, APIError, APIConnectionError, OpenAI
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+if not OPENAI_API_KEY:
+    raise RuntimeError("OPENAI_API_KEY environment variable is not set. Please set it before running the application.")
+client = OpenAI(api_key=OPENAI_API_KEY)
+
+
+
+def call_with_backoff(fn, *args, max_retries=5, base_delay=1.0, **kwargs):
+    """
+    Retry helper for OpenAI API calls.
+    """
+    delay = base_delay
+    for _ in range(max_retries):
+        try:
+            return fn(*args, **kwargs)
+        except (RateLimitError, APIError, APIConnectionError) as e:
+            # Log the retry attempt
+            print(f"API call failed, retrying in {delay:.1f}s: {type(e).__name__}")
+            time.sleep(delay + random.random())
+            delay *= 2
+    
+    # Final attempt with proper error handling
+    try:
+        return fn(*args, **kwargs)
+    except APIConnectionError:
+        # Network connection error
+        raise ConnectionError("Unable to connect to OpenAI API. Please check your internet connection.")
+    except RateLimitError:
+        # Rate limit exceeded
+        raise ConnectionError("OpenAI API rate limit exceeded. Please wait a moment and try again.")
+    except APIError as e:
+        # Other API errors (invalid key, etc.)
+        raise ConnectionError(f"OpenAI API error: {str(e)}")
+    except Exception as e:
+        # Catch any other unexpected errors
+        raise ConnectionError(f"Unexpected API error: {str(e)}")
+
+class AgentLLMConnector:
+    def __init__(self, api_key: str, skills: list = None, allow_fallback: bool = True, trusted_links=None, grounded_files=None, rag_retriever=None):
+        """
+        api_key: your OpenAI API key
+        skills: list of Tool instances (each with .name and .openai_spec())
+        allow_fallback: if False, do not allow fallback to LLM general knowledge
+        trusted_links: list of trusted source URLs (if any)
+        grounded_files: list of uploaded RAG files (if any)
+        rag_retriever: SimpleRAGRetriever instance for knowledge retrieval
+        """
+        # API key is set globally via client above; this arg is kept for compatibility
+        self.skills = skills or []
+        self.invocations = []
+
+        self.allow_fallback = allow_fallback
+        self.trusted_links = trusted_links or []
+        self.grounded_files = grounded_files or []
+        self.rag_retriever = rag_retriever
+
+         # map agent_type (from your builder) → model name
+        self.agent_model_mapping = {
+            "🛡️ Antimicrobial Stewardship":      "gpt-5-mini",
+            "🦠 Infection Prevention and Control":"gpt-5-mini",
+            "🔬 Research Assistant":             "gpt-5-mini",
+            "🏥 Clinical Assistant":             "gpt-5-mini",
+            "📚 Education Assistant":            "gpt-5-mini",
+            "🎼 Orchestrator":                   "gpt-5"
+        }
+
+    
+    def _chat_create(self, **kwargs):
+        """
+        Internal wrapper around client.chat.completions.create with backoff.
+        """
+        return call_with_backoff(client.chat.completions.create, **kwargs)
+
+    async def chat_with_agent_stream(self,
+                                     model_name: str,
+                                     messages: list[dict]):
+        """
+        Async generator: streams the assistant's response, handling function calls.
+        """
+        try:
+            # 1) Gather function specs from skills
+            tools = []
+            if self.skills:
+                for tool in self.skills:
+                    spec = tool.openai_spec(legacy=False)
+                    tools.append({
+                        "type": "function",
+                        "function": spec
+                    })
+        
+            # 2) RAG retrieval if available
+            if self.rag_retriever and messages:
+                # Get the latest user message for RAG query
+                user_messages = [msg for msg in messages if msg.get("role") == "user"]
+                if user_messages:
+                    latest_query = user_messages[-1].get("content", "")
+                    relevant_chunks = self.rag_retriever.retrieve_relevant_chunks(latest_query)
+                    
+                    if relevant_chunks:
+                        # Add knowledge context to the conversation
+                        knowledge_context = "📚 **Knowledge Base Context:**\n\n" + "\n\n---\n\n".join(relevant_chunks)
+                        
+                        # Insert knowledge before the latest user message
+                        messages = list(messages[:-1])  # All messages except the last
+                        messages.append({"role": "system", "content": knowledge_context})
+                        messages.append(user_messages[-1])  # Add back the latest user message
+        
+            # 3) Local copy of the conversation
+            convo = list(messages)
+        
+            # 4) Recursive loop: handle tool_calls until normal reply
+            while True:
+                # Prepare call arguments, including functions if any
+                call_args = {
+                    "model": model_name,
+                    "messages": convo,
+                    "stream": False
+                }
+                if tools:
+                    call_args["tools"] = tools
+                    call_args["tool_choice"] = "auto"
+        
+                try:
+                    # Call the API with error handling
+                    resp = self._chat_create(**call_args)
+                    choice = resp.choices[0]
+                    msg = choice.message
+                except ConnectionError as e:
+                    # Network or API connection error - yield user-friendly message
+                    error_message = f"⚠️ Connection Error: {str(e)}\n\nPlease check your internet connection and try again."
+                    for char in error_message:
+                        yield char
+                        await asyncio.sleep(0.01)  # Small delay for visual effect
+                    return
+                except Exception as e:
+                    # Any other unexpected error
+                    error_message = f"⚠️ Unexpected Error: {str(e)}\n\nPlease try again or contact support if the issue persists."
+                    for char in error_message:
+                        yield char
+                        await asyncio.sleep(0.01)
+                    return
+        
+                # a) If model wants to call a tool, execute it
+                if msg.tool_calls:
+                    for tool_call in msg.tool_calls:
+                        fname = tool_call.function.name
+                        raw_args = tool_call.function.arguments or "{}"
+                        try:
+                            func_args = json.loads(raw_args)
+                        except json.JSONDecodeError:
+                            func_args = {}
+            
+                        # Find and run the correct tool
+                        tool = next((t for t in self.skills if t.name == fname), None)
+                        if not tool:
+                            err = f"[Error] Tool '{fname}' not found."
+                            for ch in err:
+                                yield ch
+                            return
+            
+                        # Execute tool (may be async)
+                        result = await tool.run(**func_args)
+
+                        # Record both the call and its output for the invocation log
+                        self.invocations.append({
+                            "tool":   fname,
+                            "args":   func_args,
+                            "result": result
+                        })
+
+                        # Handle tool-level errors gracefully
+                        if isinstance(result, dict) and "error" in result:
+                            apology = (
+                                f"⚠️ Sorry, I ran into an issue with the `{fname}` tool: {result['error']}. "
+                                "Could you please clarify or try again?"
+                            )
+                            for ch in apology:
+                                yield ch
+                            return
+
+                        # Surface partial tool results to the user
+                        partial = f"🔔 Tool `{fname}` invoked\n"
+                        for ch in partial:
+                            yield ch
+            
+                        # Inject the tool call message and its output using modern format
+                        convo.append({
+                            "role": "assistant",
+                            "content": None,
+                            "tool_calls": [{
+                                "id": tool_call.id,
+                                "type": "function",
+                                "function": {
+                                    "name": fname,
+                                    "arguments": json.dumps(func_args)
+                                }
+                            }]
+                        })
+                        convo.append({
+                            "role": "tool",
+                            "tool_call_id": tool_call.id,
+                            "content": json.dumps(result)
+                        })
+            
+                    # After processing all tool calls, loop to let the model respond to the results
+                    continue
+        
+                # b) Normal assistant reply: stream content then exit
+                content = msg.content or ""
+                # --- ENFORCE NO FALLBACK TO LLM IF NOT ALLOWED ---
+                # Allow clarifying questions and tool result summaries, only block unsupported final answers
+                if not self.allow_fallback and (self.trusted_links or self.grounded_files):
+                    # Heuristic: allow clarifying questions (contains '?', 'please provide', 'missing', etc.)
+                    clarifying_phrases = [
+                        '?',
+                        'please provide',
+                        'missing',
+                        'required information',
+                        'what is',
+                        'could you',
+                        'specify',
+                        'enter',
+                        'need to know',
+                        'tell me',
+                        'which',
+                        'select',
+                    ]
+                    content_lower = content.lower()
+                    is_clarifying = any(phrase in content_lower for phrase in clarifying_phrases)
+                    # Heuristic: allow tool result summaries (contains 'according to', 'the following', 'results found', etc.)
+                    tool_summary_phrases = [
+                        'according to',
+                        'the following',
+                        'results found',
+                        'based on',
+                        'search result',
+                        'tool',
+                        'invoked',
+                        'here are',
+                        'found at',
+                    ]
+                    is_tool_summary = any(phrase in content_lower for phrase in tool_summary_phrases)
+                    # If content is empty, or is a clarifying question, or is a tool summary, allow it
+                    if not content.strip() or is_clarifying or is_tool_summary:
+                        for ch in content:
+                            yield ch
+                        break
+                    # Otherwise, block with default message
+                    default_msg = "⚠️ No information found in the provided sources. Please try rephrasing your question or upload more relevant documents."
+                    for ch in default_msg:
+                        yield ch
+                    break
+                # Otherwise, allow normal LLM answer
+                for ch in content:
+                    yield ch
+                break
+        
+        except Exception as e:
+            # Catch any remaining unhandled errors at the top level
+            error_message = f"⚠️ System Error: {str(e)}\n\nPlease try again or contact support if the issue persists."
+            for char in error_message:
+                yield char
+                await asyncio.sleep(0.01)
+
+
+    async def chat_with_agent(self,
+                              model_name: str,
+                              messages: list[dict]) -> str:
+        """
+        Convenience: collect and return the full assistant response.
+        """
+        out = ""
+        async for tok in self.chat_with_agent_stream(model_name, messages):
+            out += tok
+        return out
+
+async def call_llm(prompt: str | list[dict],
+                   model: str = None) -> str:
+    """
+    Helper for tools: run a simple prompt or message array through the LLM.
+    """
+    # Normalize prompt to a messages list
+    if isinstance(prompt, list):
+        messages = prompt
+    else:
+        try:
+            # If prompt is a JSON-stringified message list
+            parsed = json.loads(prompt)
+            messages = parsed if isinstance(parsed, list) else []
+        except Exception:
+            messages = []
+
+        if not messages:
+            # Fallback to a simple system+user framing
+            messages = [
+                {"role": "system", "content": "You are an assistant."},
+                {"role": "user", "content": prompt}
+            ]
+
+    # Call the API
+
+    response = call_with_backoff(
+        client.chat.completions.create,
+        model=model or os.getenv("OPENAI_MODEL", "gpt-5-mini"),
+        messages=messages
+    )
+
+    return response.choices[0].message.content

core/utils/rag.py

@@ -0,0 +1,85 @@
+
+"""
+rag.py
+------
+KnowledgeLoader and SimpleRAGRetriever classes for document ingestion and retrieval.
+"""
+
+import os
+import pdfplumber
+import docx
+import numpy as np
+from openai import OpenAI
+
+class KnowledgeLoader:
+    def load_text_from_file(self, file_obj):
+        ext = file_obj.name.split(".")[-1].lower()
+        if ext == "pdf":
+            return self._load_pdf(file_obj)
+        elif ext == "docx":
+            return self._load_docx(file_obj)
+        elif ext == "csv" or ext == "txt":
+            try:
+                return file_obj.read().decode("utf-8")
+            except UnicodeDecodeError:
+                try:
+                    return file_obj.read().decode("latin-1")
+                except Exception as e:
+                    return f"⚠️ Failed to decode file: {str(e)}"
+        else:
+            return ""
+
+    def _load_pdf(self, file_obj):
+        try:
+            with pdfplumber.open(file_obj) as pdf:
+                text = "\n".join([page.extract_text() or "" for page in pdf.pages])
+            return text
+        except Exception as e:
+            return f"⚠️ Failed to read PDF: {str(e)}"
+
+    def _load_docx(self, file_obj):
+        try:
+            doc = docx.Document(file_obj)
+            text = "\n".join([p.text for p in doc.paragraphs])
+            return text
+        except Exception as e:
+            return f"⚠️ Failed to read DOCX: {str(e)}"
+
+class SimpleRAGRetriever:
+    def __init__(self, openai_api_key, chunk_size=600):
+        self.chunk_size = chunk_size
+        self.embeddings = {}
+        self.text_chunks = {}
+        self.client = OpenAI(api_key=openai_api_key)
+
+    def split_text(self, text):
+        return [text[i:i+self.chunk_size] for i in range(0, len(text), self.chunk_size)]
+
+    def embed_text(self, texts):
+        if not texts:
+            return []
+        response = self.client.embeddings.create(
+            input=texts,
+            model="text-embedding-ada-002"
+        )
+        return [np.array(d.embedding) for d in response.data]
+
+    def add_knowledge(self, file_obj):
+        loader = KnowledgeLoader()
+        full_text = loader.load_text_from_file(file_obj)
+        chunks = self.split_text(full_text)
+        chunk_embeddings = self.embed_text(chunks)
+        for idx, (chunk, emb) in enumerate(zip(chunks, chunk_embeddings)):
+            self.embeddings[len(self.embeddings)] = emb
+            self.text_chunks[len(self.text_chunks)] = chunk
+
+    def retrieve_relevant_chunks(self, query, top_k=2):
+        if not self.embeddings:
+            return []
+        query_emb = self.embed_text([query])[0]
+        similarities = {}
+        for idx, emb in self.embeddings.items():
+            similarities[idx] = float(np.dot(query_emb, emb) / (np.linalg.norm(query_emb) * np.linalg.norm(emb)))
+        sorted_idxs = sorted(similarities, key=lambda idx: similarities[idx], reverse=True)
+        top_chunks = [self.text_chunks[idx] for idx in sorted_idxs[:top_k]]
+        return top_chunks

core/utils/skills_registry.py

@@ -0,0 +1,132 @@
+import os
+import json
+import re
+import math
+from typing import Optional
+from openai import OpenAI, OpenAIError
+
+from tools.registry import TOOL_REGISTRY
+
+from typing import Any, Callable, Dict, Optional, Type, Union
+from tools.base import Tool
+
+
+
+
+# Instantiate stateless tools once and store in a dict
+STATIC_TOOL_INSTANCES = {name: cls() for name, cls in TOOL_REGISTRY.items() if name != "history_taking"}
+
+"""
+skills_registry.py
+------------------
+Registry and helper functions for tool instantiation, syndrome matching, and embedding lookup.
+"""
+
+#match for KB
+# 1) Initialize the OpenAI client
+openai_api_key = os.getenv("OPENAI_API_KEY")
+if not openai_api_key:
+    raise RuntimeError("OPENAI_API_KEY environment variable is not set. Please set it before running the application.")
+_client = OpenAI(api_key=openai_api_key)
+
+# 2) Load your precomputed syndrome embeddings
+#    Make sure syndrome_embeddings.json is in your working dir
+with open("syndrome_embeddings.json", "r") as f:
+    SYNDROME_EMBS = json.load(f)  # { syndrome_key: [float, ...], … }
+
+
+def _cosine_sim(a: list[float], b: list[float]) -> float:
+    """
+    Compute the cosine similarity between two vectors.
+
+    Args:
+        a (list[float]): First vector.
+        b (list[float]): Second vector.
+
+    Returns:
+        float: Cosine similarity between a and b.
+    """
+    dot = sum(x*y for x, y in zip(a, b))
+    norm_a = math.sqrt(sum(x*x for x in a))
+    norm_b = math.sqrt(sum(y*y for y in b))
+    return dot / (norm_a * norm_b) if norm_a and norm_b else 0.0
+
+def _match_syndrome(user_query: str,
+                   model: str = "text-embedding-ada-002",
+                   threshold: float = 0.7
+                  ) -> Optional[str]:
+    # TODO: implement syndrome matching logic or remove if unused
+    pass
+    # This function is now implemented at the end of the file (see below)
+    pass
+    """
+    Semantically match the user_query to the best syndrome_key
+    via cosine similarity against precomputed embeddings.
+
+    Args:
+        user_query (str): The user's query string.
+        model (str, optional): Embedding model to use. Defaults to "text-embedding-ada-002".
+        threshold (float, optional): Minimum similarity threshold. Defaults to 0.7.
+
+    Returns:
+        Optional[str]: The best-matching syndrome key, or None if no match meets the threshold.
+    """
+    # normalize
+    q = user_query.lower()
+    q = re.sub(r"[^a-z0-9\s]", " ", q)
+    q = re.sub(r"\s+", " ", q).strip()
+
+    # embed the query
+    try:
+        resp = _client.embeddings.create(model=model, input=[q])
+        q_emb = resp.data[0].embedding
+    except OpenAIError as e:
+        # if embedding fails, fall back to no match
+        print(f"[Embedding error] {e}")
+        return None
+
+    # find best cosine similarity
+    best_key, best_score = None, -1.0
+    for key, emb in SYNDROME_EMBS.items():
+        score = _cosine_sim(q_emb, emb)
+        if score > best_score:
+            best_key, best_score = key, score
+
+    return best_key if best_score >= threshold else None
+
+
+# Unified tool registry: uses TOOL_REGISTRY for class references and STATIC_TOOL_INSTANCES for stateless tools
+from tools.history_taking import HistoryTakingTool
+
+tool_registry: Dict[str, Dict[str, Any]] = {}
+for name, cls in TOOL_REGISTRY.items():
+    if name == "history_taking":
+        tool_registry[name] = {"fn": HistoryTakingTool}
+    else:
+        instance = STATIC_TOOL_INSTANCES[name]
+        tool_registry[name] = {"fn": instance, "args_schema": instance.args_schema}
+
+def get_tool_by_name(
+    name: str,
+    context: Dict[str, Any]
+) -> Optional[Tool]:
+    """
+    Retrieve a tool instance by name, optionally using context for dynamic instantiation.
+
+    Args:
+        name (str): The tool key, e.g. "history_taking".
+        context (Dict[str, Any]): Must include "user_query" for dynamic tools.
+
+    Returns:
+        Optional[Tool]: The tool instance, or None if not found or not instantiable.
+    """
+    entry = tool_registry[name]
+    fn = entry["fn"]
+    if name == "history_taking":
+        syndrome_key = _match_syndrome(context["user_query"])
+        if not syndrome_key:
+            return None
+        return fn(syndrome_key)  # instantiate with dynamic key
+    else:
+        # static tools: fn is already an instance
+        return fn

prompts/alert_prolonged_antibiotic_use.j2

@@ -0,0 +1,9 @@
+{% raw %}
+[
+  {"role": "system", "content":
+   "You are an infectious diseases consultant. Based on all provided clinical data and guidelines, determine if the patient is at risk for prolonged or unnecessary antibiotic use and summarize recommended durations for the specified condition. Provide rationale and cite relevant guidelines if possible."},
+
+  {"role": "user", "content":
+   "Clinical condition: {{ condition }}\nSite of infection: {{ site_of_infection }}\nRisk or presence of biofilm: {{ risk_of_biofilm }}\nCurrent response to antibiotics: {{ current_response }}\nCreatinine clearance: {{ creatinine_clearance }}\nSeverity of infection: {{ severity_of_infection }}\nKnown drug allergies: {{ known_allergies }}\n\nPlease:\n1. Summarize recommended antibiotic duration for this condition.\n2. Indicate if current therapy may be prolonged.\n3. Provide rationale and cite guidelines if possible."}
+]
+{% endraw %}

prompts/deescalation.j2

@@ -0,0 +1,9 @@
+{% raw %}
+[
+  {"role": "system", "content":
+   "You are an infectious diseases consultant. Based on all provided clinical data, recommend appropriate antibiotic de‐escalation."},
+
+  {"role": "user", "content":
+   "Patient culture results: {{ culture }}\nCurrent antibiotics: {{ meds }}\nSite of infection: {{ site_of_infection }}\nRisk or presence of biofilm: {{ risk_of_biofilm }}\nCurrent response to antibiotics: {{ current_response }}\nCreatinine clearance: {{ creatinine_clearance }}\nSeverity of infection: {{ severity_of_infection }}\nKnown drug allergies: {{ known_allergies }}\n\nPlease:\n1. Identify if de‐escalation is safe.\n2. Recommend the narrowest effective agent.\n3. Provide rationale in 2–3 sentences."}
+]
+{% endraw %}

prompts/diagnostic_recommendation.j2

@@ -0,0 +1,12 @@
+{% raw %}
+[
+{"role": "system", "content":
+"You are an infectious diseases consultant who has gathered the patient’s clinical history and now will provide a diagnostic and management recommendation."},
+
+{"role": "user", "content":
+"The user’s concern: '{{ syndrome_query }}'.\n\n"
+"Collected History:\n"
+"{% for question_key, answer in history.items() %}- {{ question_key.replace('_', ' ').capitalize() }}: {{ answer }}\n{% endfor %}\n\n"
+"Based on this information, please provide your diagnostic impression and recommended management plan, including appropriate empiric therapy, isolation precautions, and any other relevant considerations."}
+]
+{% endraw %}

prompts/draft_critique_enhance_board_exam.j2

@@ -0,0 +1,96 @@
+You are an expert Infectious Diseases fellowship board exam question writer and critic.
+
+Your task is to DRAFT an initial question, CRITIQUE it thoroughly, and then ENHANCE it to board-level excellence.
+
+**BLUEPRINT TO IMPLEMENT:**
+{{ blueprint }}
+
+**TOPIC:** {{ topic }}
+**DIFFICULTY LEVEL:** {{ difficulty_level }}
+**QUESTION TYPE:** {{ question_type }}
+
+**YOUR 3-PHASE MISSION:**
+
+## PHASE 1: DRAFT INITIAL QUESTION
+Based on the blueprint, create:
+1. **Clinical Vignette:** Rich clinical scenario implementing the blueprint strategy
+2. **Question Stem:** Clear, specific question 
+3. **Answer Choices:** 5 options matching the blueprint differential diagnoses
+4. **Explanations:** Detailed explanations for correct and incorrect answers
+
+## PHASE 2: CRITIQUE THE DRAFT
+Analyze your draft question for:
+- **Diagnostic Giveaways:** Any obvious clues that make the answer too easy?
+- **Wrong Answer Quality:** Are the distractors plausible for ID specialists?
+- **Clinical Realism:** Does the vignette reflect real-world presentations?
+- **Difficulty Level:** Will this challenge ID fellowship trainees?
+- **Blueprint Adherence:** Does it follow the planned strategy?
+
+## PHASE 3: ENHANCE BASED ON CRITIQUE
+Revise the question to:
+- Eliminate any diagnostic giveaways identified
+- Strengthen weak distractors
+- Add clinical complexity and sophistication
+- Ensure blueprint strategy is perfectly executed
+- Achieve ID fellowship-level difficulty
+
+**ENHANCEMENT REQUIREMENTS:**
+
+1. **Vignette Excellence:**
+   - Include specific lab values, imaging findings
+   - Add clinical complexity (comorbidities, medications)
+   - Use sophisticated medical terminology
+   - Implement all blueprint clues naturally
+
+2. **Question Sophistication:**
+   - Avoid obvious diagnostic language
+   - Focus on clinical reasoning
+   - Require expert-level differentiation
+
+3. **Answer Choice Quality:**
+   - Each distractor must be plausible for ID specialists
+   - Implement the blueprint's wrong answer reasoning
+   - Ensure choices require clinical expertise to differentiate
+
+4. **Explanation Depth:**
+   - Detailed reasoning for correct answer
+   - Specific reasons why each wrong answer is incorrect
+   - Educational value for ID trainees
+
+**CRITICAL RULES:**
+- NO classic travel + classic symptoms combinations that give away answers
+- Each wrong answer must have the specific reasoning from the blueprint
+- Include 3+ supporting clues for correct diagnosis as planned
+- Add misleading clues to increase complexity
+- Target ID fellowship-level difficulty
+
+**OUTPUT FORMAT:**
+Return a JSON object with this exact structure:
+
+```json
+{
+  "vignette": "Enhanced clinical vignette with sophisticated details",
+  "question_stem": "Clear, specific question requiring ID expertise",
+  "answer_choices": [
+    "Correct answer - first choice",
+    "Plausible distractor 2",
+    "Plausible distractor 3", 
+    "Plausible distractor 4",
+    "Plausible distractor 5"
+  ],
+  "explanations": {
+    "correct": "Detailed explanation of why this is correct with ID-specific reasoning",
+    "incorrect": "Detailed explanation of why other choices are incorrect, implementing blueprint reasoning"
+  },
+  "enhancement_notes": "Summary of key enhancements made during critique phase",
+  "critique_summary": "Brief summary of issues identified and how they were resolved"
+}
+```
+
+**EXAMPLE OF BLUEPRINT IMPLEMENTATION:**
+
+If blueprint says "Blastomyces wrong because yeast description will be small 2-4 microns":
+- Vignette should describe: "BAL fluid microscopy reveals small budding yeasts measuring 2-4 micrometers"
+- Explanation should state: "Blastomyces dermatitidis typically shows broad-based budding yeasts that are 8-15 micrometers, not the small 2-4 micrometer yeasts described"
+
+**Remember:** Follow the blueprint strategy exactly while creating a sophisticated question that challenges ID specialists!

prompts/empiric_therapy.j2

@@ -0,0 +1,13 @@
+{% raw %}
+[
+  {
+    "role": "system",
+    "content": "You are a clinical decision support agent. Suggest empiric antibiotic therapy per standard guidelines, considering all provided clinical variables."
+  },
+  {
+    "role": "user",
+    "content": "Patient profile:\n- Age: {{ age }}\n- Allergies: {{ allergies }}\n- Recent labs: {{ labs }}\n- Culture & Sensitivity Results: {{ culture }}\n- Current Antibiotic Regimen: {{ meds }}\n- Site of Infection: {{ site_of_infection }}\n- Risk or Presence of Biofilm: {{ risk_of_biofilm }}\n- Current Response to Antibiotics: {{ current_response }}\n- Creatinine Clearance: {{ creatinine_clearance }}\n- Severity of Infection: {{ severity_of_infection }}\n- Known Drug Allergies: {{ known_allergies }}\n\nBased on this, recommend:\n1. One or two empiric antibiotic regimens.\n2. Dosing and route.\n3. Brief justification."
+  }
+]
+
+{% endraw %}

prompts/evaluate_nhsn_definition.j2

@@ -0,0 +1,19 @@
+[
+  {
+    "role": "system",
+    "content": "You are an expert at applying NHSN surveillance definitions to patient cases.  \n\n"
+               "Here is the formal logic extracted from the NHSN site:\n"
+               "<JSON>{{ definition_logic | tojson }}</JSON>\n\n"
+               "And here are the user-provided field values:\n"
+               "<JSON>{{ values | tojson }}</JSON>\n\n"
+               "Based on this logic and these values, decide whether the case **meets** the definition.  \n"
+               "Return **only** a JSON object wrapped in <JSON>…</JSON> tags with exactly two keys:\n"
+               "  • `meets_definition`: true or false\n"
+               "  • `reasoning`: a brief justification referencing the logic.\n"
+               "Do not output any additional text."
+  },
+  {
+    "role": "user",
+    "content": "Case: {{ case_description }}"
+  }
+]

prompts/extract_nhsn_fields.j2

@@ -0,0 +1,12 @@
+[
+  {
+    "role": "system",
+    "content": "You are an expert in NHSN surveillance definitions.  \n"
+               "From the following webpage snippets, extract ONLY the list of required data elements (field names) that a user must collect to apply the definition.  \n"
+               "Return **only** a JSON array wrapped in <JSON>…</JSON> tags—no extra text."
+  },
+  {
+    "role": "user",
+    "content": "Snippets:\n\n{{ snippets }}"
+  }
+]

prompts/extract_nhsn_logic.j2

@@ -0,0 +1,12 @@
+[
+  {
+    "role": "system",
+    "content": "You are an expert in NHSN surveillance definitions.  \n"
+               "From the same webpage snippets, extract the core logic or rule text that describes how to decide the definition (e.g., “central line in place >2 calendar days…”, “no alternate source of infection…”, etc.).  \n"
+               "Return **only** a JSON object wrapped in <JSON>…</JSON> tags with a single key `logic` whose value is that text."
+  },
+  {
+    "role": "user",
+    "content": "Snippets:\n\n{{ snippets }}"
+  }
+]

prompts/extract_reporting_fields.j2

@@ -0,0 +1,17 @@
+{% raw %}
+
+[
+  {
+    "role": "system",
+    "content": "You are an expert at extracting field names from public health reporting requirement snippets."
+  },
+  {
+    "role": "user",
+    "content": "From these snippets, extract only the list of required reporting fields. "
+               "Return **only** a JSON array wrapped between <JSON> and </JSON> tags, for example:\n\n"
+               "<JSON>\n[\"Name\",\"Age\",…]\n</JSON>\n\n"
+               "Snippets:\n\n{{ snippets }}"
+  }
+]
+
+{% endraw %}

prompts/extract_reporting_format.j2

@@ -0,0 +1,23 @@
+{% raw %}
+
+[
+  {
+    "role": "system",
+    "content": "You are an expert at understanding state public health reporting templates."
+  },
+  {
+    "role": "user",
+    "content": "From these snippets, extract only the JSON object describing the report format (columns, column_headers, file_name). "
+               "Return **only** that object wrapped between <JSON> and </JSON> tags, for example:\n\n"
+               "<JSON>\n"
+               "{\n"
+               "  \"columns\": [\"Name\",\"DOB\",…],\n"
+               "  \"column_headers\": {\"Name\":\"Full Name\",…},\n"
+               "  \"file_name\":\"Typhoid_Report_Dallas_TX.csv\"\n"
+               "}\n"
+               "</JSON>\n\n"
+               "Snippets:\n\n{{ snippets }}"
+  }
+]
+
+{% endraw %}

prompts/final_enhancement_board_exam.j2

@@ -0,0 +1,143 @@
+You are an expert Infectious Diseases fellowship board exam question reviewer and enhancer.
+
+Your task is to take a drafted board exam question and enhance it to ensure it meets the highest standards for ID fellowship board examinations.
+
+**CURRENT DRAFTED QUESTION:**
+
+**Topic:** {{ topic }}
+
+**Vignette:** 
+{{ current_vignette }}
+
+**Question Stem:** 
+{{ current_question }}
+
+**Answer Choices:** 
+{{ current_choices }}
+
+**Explanations:** 
+{{ current_explanations }}
+
+**QUALITY REVIEW FEEDBACK:**
+{{ quality_feedback }}
+
+**YOUR ENHANCEMENT MISSION:**
+
+🚨 **IMMEDIATE ACTION REQUIRED:** 
+The quality review shows this question FAILS board exam standards. You MUST follow these mandatory steps:
+
+**STEP 1: EMERGENCY QUALITY CHECK**
+- Quality score: {{ quality_feedback.percentage_score }}%
+- Board readiness: {{ quality_feedback.board_exam_readiness }}
+- **TARGET REQUIRED: 80%+ score AND board_readiness = True**
+- If score <80% OR board_readiness = False → **EMERGENCY PROTOCOL ACTIVATED**
+
+**STEP 2: EMERGENCY PROTOCOL (MANDATORY)**
+When quality review shows problems, you MUST:
+1. **COMPLETELY DISCARD** the current vignette 
+2. **START OVER** with an entirely new clinical scenario
+3. **REMOVE ALL** forbidden combinations identified in quality review
+4. **CREATE** a genuinely difficult scenario requiring fellowship-level expertise
+5. **ENSURE 3+ EQUALLY PLAUSIBLE diagnoses** with overlapping features
+
+**FORBIDDEN ACTIONS** (Will result in continued failure):
+- ❌ Making minor modifications to existing vignette
+- ❌ Keeping any elements that quality review flagged as "too obvious"  
+- ❌ Maintaining travel history that gives away diagnosis
+- ❌ Using any combination identified as "strongly suggests" the correct answer
+
+**MANDATORY ACTIONS** (Required for passing):
+- ✅ Completely new patient scenario 
+- ✅ Remove or mislead all geographic/exposure clues
+- ✅ Create multiple equally plausible diagnoses
+- ✅ Require expert-level ID reasoning to differentiate
+
+2. **CRITICAL: Eliminate All Diagnostic Giveaways**
+   - **Question stem**: NEVER mention suspected diagnosis, pathogen type, or disease category
+   - **Vignette**: REMOVE obvious combinations:
+     * Classic geographic exposure + classic symptoms = REMOVE one or both
+     * Specific travel history + pathognomonic findings = REMOVE or change
+     * Immunocompromised + classic opportunistic infection signs = ADD confounding factors
+   - **Create genuine uncertainty**: Each differential diagnosis should have 2-3 supporting clues
+
+3. **CRITICAL: Implement 3-Clue Rule** 
+   - **Correct diagnosis**: Must have EXACTLY 3 clear but subtle diagnostic clues
+   - **Each distractor**: Should have 1-2 misleading clues suggesting that diagnosis
+   - **Ensure diagnostic confusion**: Clinical picture should suggest multiple possibilities
+
+4. **Maximize difficulty for ID specialists:**
+   - Create atypical presentations requiring expert reasoning
+   - Include overlapping features between differential diagnoses
+   - Add confounding clinical information that misleads
+   - Use complex clinical scenarios (immunocompromised, nosocomial, drug interactions)
+
+5. **Include ID-specific sophisticated details:**
+   - Antimicrobial resistance patterns
+   - Specific pathogens and their characteristics
+   - Complex clinical scenarios (immunocompromised patients, healthcare settings, etc.)
+   - Laboratory interpretations (cultures, molecular diagnostics, serology)
+   - Treatment decisions and drug interactions
+
+**ENHANCEMENT REQUIREMENTS:**
+
+- **Vignette Enhancement:** Add clinical complexity, specific lab values, imaging findings, patient history that increases difficulty
+- **Question Refinement:** Make the question stem more sophisticated and ID-specific
+- **Answer Choice Improvement:** Ensure all distractors are plausible for an ID specialist
+- **Explanation Enhancement:** Provide detailed ID-specific reasoning that teaches key concepts
+
+**CRITICAL RULES for MAXIMUM DIFFICULTY:**
+- **MANDATORY: If quality review score <75%** → COMPLETELY REWRITE the vignette from scratch
+- **MANDATORY: If "board_exam_readiness = False"** → ABANDON current approach and create entirely new scenario
+- **3-Clue Rule**: Correct answer has exactly 3 diagnostic clues, distractors have 1-2 clues each
+- **NO obvious combinations**: Classic exposure + classic symptoms + confirmatory tests = TOO EASY
+- **Geographic clues**: Either REMOVE entirely or make misleading (wrong endemic area)
+- **Diagnostic confusion**: Include findings that could suggest 3+ different diagnoses
+- **ID expertise required**: Should challenge infectious disease attendings
+- **Atypical presentations**: Completely avoid textbook classic cases
+- **Clinical complexity**: Multiple confounding factors that mislead from correct diagnosis
+
+**EXAMPLES OF PROPER DIFFICULTY:**
+
+❌ **FAILING APPROACH** (What you must NOT do):
+- "Patient with HIV traveled to Southeast Asia and has skin lesions" → Obviously Penicillium marneffei
+- Minor tweaks: "traveled to multiple regions in Southeast Asia" → Still obvious
+- Cosmetic changes: "atypical skin findings" → Diagnosis still clear
+
+✅ **PASSING APPROACH** (What you MUST do):
+- **Option A**: Completely different scenario: "Hospital-acquired infection in ICU patient with complex comorbidities and atypical presentation suggesting multiple resistant pathogens"
+- **Option B**: Misleading scenario: "Recent travel to Europe, pneumonia-like symptoms, multiple possible bacterial/viral/fungal etiologies requiring expert differentiation"
+- **Option C**: Complex presentation: "Immunocompromised patient with overlapping symptoms suggesting 3+ different opportunistic infections, requiring laboratory interpretation skills"
+
+**TRANSFORMATION EXAMPLES:**
+- **Before**: HIV + Southeast Asia travel + skin lesions → Penicillium marneffei
+- **After**: HIV + Recent European travel + respiratory symptoms + complex lab findings → Could be PCP, bacterial pneumonia, atypical mycobacteria, or resistant fungal infection
+
+**EMERGENCY REWRITE TRIGGERS:**
+- Any mention of Southeast Asia in context of HIV + skin lesions
+- Any "classic" exposure + symptoms combination  
+- Any scenario where quality review says "diagnosis too obvious"
+- Quality score <75% or board_exam_readiness = False
+
+**OUTPUT FORMAT:**
+Return a JSON object with this exact structure:
+
+```json
+{
+  "vignette": "Enhanced clinical vignette with ID-specific complexity",
+  "question_stem": "Enhanced question that requires ID expertise",
+  "answer_choices": [
+    "Correct answer - first choice",
+    "Plausible distractor 2",
+    "Plausible distractor 3", 
+    "Plausible distractor 4",
+    "Plausible distractor 5"
+  ],
+  "explanations": {
+    "correct": "Detailed explanation of why this is correct with ID-specific reasoning",
+    "incorrect": "Detailed explanation of why other choices are incorrect, with teaching points"
+  },
+  "enhancement_notes": "Summary of key enhancements made to increase difficulty and ID-specificity"
+}
+```
+
+**Remember:** This question should challenge an Infectious Diseases fellow or attending physician. Make it clinically sophisticated and ID-specialty specific!

prompts/generate_board_exam_vignette.j2

@@ -0,0 +1,75 @@
+You are an expert medical education specialist creating advanced board exam questions.
+
+Using the following comparison table, generate a complete board exam question including vignette, question stem, answer choices, and explanations.
+
+**Comparison Table:**
+{{ comparison_table }}
+
+**Requirements for CHALLENGING Board Exam Questions:**
+
+1. **CRITICAL Diagnostic Clue Distribution:**
+   - **Correct diagnosis ONLY**: Must have exactly 3 clear but subtle diagnostic clues
+   - **Each distractor**: Should have 1-2 misleading clues suggesting that diagnosis
+   - **Create confusion**: Include overlapping symptoms, labs, imaging between diagnoses
+   - **Avoid giveaways**: NO obvious exposure + classic symptoms + confirmatory tests
+
+2. **Clinical Vignette Complexity**: Create a realistic, challenging clinical scenario that:
+   - Uses specific patient demographics, medical history, and presentation timeline
+   - Includes detailed vital signs, physical exam findings, and laboratory results
+   - Incorporates specific imaging findings and diagnostic test results
+   - **Includes confounding elements**: Red herrings from differential diagnoses
+   - **Atypical presentations**: Avoid textbook classic presentations
+   - **Expert-level reasoning required**: Should challenge ID specialists
+   - Uses realistic medical details (specific lab values, medication names, dosages)
+   - **Multiple comorbidities/factors** that complicate the clinical picture
+
+3. **Question Stem**: 
+   - For diagnosis questions: "Which of the following is the most likely diagnosis?"
+   - For treatment questions: "Which of the following is the most appropriate next step in management?"
+   - For identification questions: "Which of the following is the most likely causative organism?"
+
+4. **Answer Choices**: Extract the condition names from the comparison table:
+   - A. [Correct answer condition]
+   - B. [Distractor 1 condition]  
+   - C. [Distractor 2 condition]
+   - D. [Distractor 3 condition]
+   - E. [Distractor 4 condition]
+
+4. **Explanations**:
+   - **Correct Answer**: Explain why this diagnosis is most consistent with the clinical presentation, citing specific discriminating features
+   - **Each Distractor**: Explain why this diagnosis is less likely, highlighting key differences in presentation, lab findings, or clinical context
+
+**Quality Standards:**
+- Board exam level complexity and clinical accuracy
+- Specific medical details that demonstrate expertise
+- Clear clinical reasoning that teaches key concepts
+- Appropriate difficulty for advanced learners
+
+**Topic**: {{ topic }}
+**Question Type**: {{ question_type }}
+**Difficulty**: {{ difficulty_level }}
+
+**Output Format:**
+Return a JSON object with this exact structure:
+```json
+{
+  "vignette": "Detailed clinical scenario with specific medical details...",
+  "question_stem": "Complete question including vignette + question",
+  "answer_choices": [
+    "A. Correct condition name",
+    "B. Distractor 1 condition name", 
+    "C. Distractor 2 condition name",
+    "D. Distractor 3 condition name",
+    "E. Distractor 4 condition name"
+  ],
+  "explanations": {
+    "correct_explanation": "Why A is correct with specific clinical reasoning...",
+    "distractor_explanations": [
+      "Why B is incorrect with specific differences...",
+      "Why C is incorrect with specific differences...", 
+      "Why D is incorrect with specific differences...",
+      "Why E is incorrect with specific differences..."
+    ]
+  }
+}
+```

prompts/generate_comparison_table.j2

@@ -0,0 +1,77 @@
+You are an expert medical education specialist creating advanced board exam questions for healthcare professionals.
+
+Generate a comprehensive comparison table for differential diagnosis of: {{ topic }}
+
+{% if guideline_context and guideline_context != "No specific guidelines found. Use standard medical knowledge." %}
+**EVIDENCE-BASED CONTEXT:**
+{{ guideline_context }}
+
+**Important:** Base your comparison table on the above evidence-based guidelines and current medical literature.
+{% else %}
+**Context:** No specific guidelines available. Use current standard medical knowledge and evidence-based practice.
+{% endif %}
+
+**Instructions:**
+1. Create a comparison table with 5 conditions:
+   - 1 CORRECT answer (the actual condition)
+   - 4 plausible DISTRACTORS (similar conditions that could be confused)
+
+2. For each condition, provide specific clinical details:
+   - **Clinical Presentation**: Specific symptoms, timeline, severity
+   - **Epidemiology/Risk Factors**: Patient demographics, exposures, comorbidities
+   - **Laboratory Findings**: Specific lab values, patterns, biomarkers
+   - **Imaging Characteristics**: Specific radiologic findings, patterns
+   - **Diagnostic Tests**: Confirmatory tests, sensitivity/specificity
+   - **Treatment**: First-line therapy, dosing, duration
+   - **Clinical Reasoning**: Why this diagnosis fits or doesn't fit
+
+3. **Quality Requirements for DIFFICULT Board Questions:**
+   - Use specific medical details (lab values, imaging findings, medications)
+   - Include discriminating features that distinguish conditions
+   - **CRITICAL: Create diagnostic complexity** - include misleading information from differential diagnoses
+   - **Clue Distribution Rule**: Correct diagnosis should have exactly 3 clear diagnostic clues, distractors should have 1-2 misleading clues
+   - Ensure clinical accuracy and board exam relevance
+   - Make distractors plausible with overlapping presentations
+   - **Avoid obvious giveaways** (no classic exposure history + classic symptoms + confirmatory tests)
+   - Reference current guidelines and evidence-based practice when available
+
+4. **Difficulty Enhancement Requirements:**
+   - **Confusing Clinical Picture**: Include symptoms/findings that could suggest multiple diagnoses
+   - **Overlapping Presentations**: Each distractor should share some features with the correct answer
+   - **Subtle Distinguishing Features**: The correct diagnosis should be evident only through careful analysis
+   - **Expert-Level Reasoning Required**: Should challenge ID fellows/attendings, not be obvious to general internists
+
+4. **Difficulty Level**: {{ difficulty_level }}
+5. **Question Type**: {{ question_type }}
+
+**Output Format:**
+Return a JSON object with this exact structure:
+```json
+{
+  "correct_answer": {
+    "condition": "Exact condition name",
+    "clinical_presentation": "Detailed clinical features",
+    "epidemiology_risk_factors": "Specific risk factors and demographics",
+    "laboratory_findings": "Specific lab values and patterns",
+    "imaging_characteristics": "Detailed imaging findings",
+    "diagnostic_tests": "Confirmatory diagnostic approaches",
+    "treatment": "Specific treatment recommendations",
+    "clinical_reasoning": "Why this is the most likely diagnosis"
+  },
+  "distractor_1": {
+    "condition": "Alternative diagnosis 1",
+    "clinical_presentation": "How this condition typically presents",
+    "epidemiology_risk_factors": "Risk factors for this condition",
+    "laboratory_findings": "Lab pattern for this condition",
+    "imaging_characteristics": "Imaging findings for this condition",
+    "diagnostic_tests": "How to diagnose this condition",
+    "treatment": "Treatment for this condition",
+    "clinical_reasoning": "Why this could be considered but is less likely"
+  },
+  "distractor_2": { ... },
+  "distractor_3": { ... },
+  "distractor_4": { ... }
+}
+```
+
+Focus on creating clinically accurate, educationally valuable content that tests advanced medical reasoning.

prompts/generate_presentation_slide.j2

@@ -0,0 +1,65 @@
+You are an expert medical educator creating comprehensive educational presentation slides. Your task is to generate detailed, educational content for a specific slide based on research information.
+
+**Presentation Context:**
+- Topic: {{ topic }}
+- Target Audience: {{ target_audience }}
+- Slide Title: {{ slide_title }}
+- Section: {{ section }}
+- Content Description: {{ content_description }}
+
+**Research Information Available:**
+{{ research_report }}
+
+**Slide Content Requirements:**
+
+1. **Educational Value**: Content should be appropriate for {{ target_audience }} level
+2. **Clinical Relevance**: Include practical, clinically applicable information
+3. **Evidence-Based**: Use the research information to support all claims
+4. **Structured Format**: Organize content in clear, digestible bullet points
+5. **Engagement**: Make content engaging and memorable
+
+**Content Guidelines:**
+- Use 4-6 main bullet points per slide
+- Each bullet point should be concise but informative (1-2 sentences)
+- Include specific clinical details, dosages, guidelines when appropriate
+- Add sub-bullets for important details or examples
+- Ensure content flows logically and builds knowledge
+
+**Special Instructions by Slide Type:**
+- **Learning Objectives**: Focus on measurable, achievable goals
+- **Case Vignettes**: Create realistic, detailed clinical scenarios
+- **Pathophysiology**: Explain mechanisms clearly with clinical correlation
+- **Diagnosis**: Include specific tests, criteria, and interpretation
+- **Treatment**: Provide evidence-based protocols, dosages, monitoring
+- **Guidelines**: Reference current society recommendations
+- **Clinical Pearls**: Share practical tips and expert insights
+
+**Output Format:**
+Return a JSON object with this exact structure:
+```json
+{
+  "slide_title": "{{ slide_title }}",
+  "main_content": [
+    "First main bullet point with clinical detail",
+    "Second main bullet point with evidence-based information", 
+    "Third main bullet point with practical application",
+    "Fourth main bullet point with specific examples",
+    "Fifth main bullet point with clinical correlation",
+    "Sixth main bullet point with key takeaways"
+  ],
+  "sub_bullets": {
+    "First main bullet point": [
+      "Supporting detail or example",
+      "Additional clinical correlation"
+    ],
+    "Third main bullet point": [
+      "Specific dosage or protocol",
+      "Monitoring parameters"
+    ]
+  },
+  "clinical_notes": "Key clinical insights, warnings, or pearls for this slide content",
+  "references_used": "Brief mention of which research sources informed this content"
+}
+```
+
+Generate comprehensive, educationally valuable content that advances the learner's understanding of {{ topic }}.

prompts/generate_question_blueprint.j2

@@ -0,0 +1,87 @@
+You are an expert Infectious Diseases fellowship board exam question designer.
+
+Your task is to create a strategic blueprint for a challenging ID board exam question.
+
+**TOPIC:** {{ topic }}
+**DIFFICULTY LEVEL:** {{ difficulty_level }}
+**QUESTION TYPE:** {{ question_type }}
+
+**YOUR MISSION:**
+Create a detailed blueprint that outlines the strategy for a challenging ID fellowship-level question.
+Think like an expert test writer planning how to create a question that will challenge ID specialists.
+
+**BLUEPRINT REQUIREMENTS:**
+
+1. **Scenario Description:** Describe the clinical scenario you will use (e.g., "immunocompromised patient with new onset fever and pulmonary nodules")
+
+2. **Primary Diagnosis:** The correct answer you want to test
+
+3. **Differential Diagnoses:** List exactly 5 differential diagnoses that will become your answer choices:
+   - Position 1: The correct diagnosis
+   - Positions 2-5: Plausible but incorrect differential diagnoses
+
+4. **Diagnostic Clues Strategy:** Plan your clues carefully:
+   - **Supporting Primary:** List 3-4 clues that support the correct diagnosis
+   - **Misleading Clues:** List 2-3 clues that might initially mislead toward other diagnoses
+   - **Geographic/Exposure Clues:** If using travel/exposure, specify how they support or mislead
+
+5. **Wrong Answer Reasoning:** For each wrong answer, explain exactly why it will be wrong:
+   - Example: "Blastomyces will be wrong because the yeast description will be small 2-4 microns"
+   - Example: "Coccidioidomycosis will be wrong based on the patient living location"
+   - Example: "Aspergillus and mucor will be wrong because the BAL growing yeast not mold"
+
+**EXAMPLE BLUEPRINT FORMAT:**
+
+For the topic "Penicillium marneffei":
+- **Scenario:** "Immunocompromised patient with new onset fever and pulmonary nodules"
+- **Primary Diagnosis:** Histoplasma capsulatum
+- **Differentials:** Histoplasma, Blastomyces, Coccidioidomycosis, Aspergillus, Mucormycosis
+- **Supporting Clues:** Patient lives in Mississippi, has a parrot pet, BAL culture growing yeast
+- **Wrong Answer Logic:** 
+  - Blastomyces: Wrong because yeast description will be small 2-4 microns
+  - Cocci: Wrong based on patient living location  
+  - Aspergillus/Mucor: Wrong because BAL growing yeast not mold
+
+**CRITICAL RULES:**
+- NO obvious diagnostic giveaways (avoid classic travel + classic symptoms)
+- Each wrong answer must have a clear, specific reason why it's wrong
+- Include 3+ supporting clues for correct answer
+- Add 1-2 misleading clues to increase difficulty
+- Ensure ID fellowship-level sophistication
+
+**OUTPUT FORMAT:**
+Return a JSON object with this exact structure:
+
+```json
+{
+  "scenario_description": "Brief description of the clinical scenario",
+  "primary_diagnosis": "The correct diagnosis",
+  "differential_diagnoses": [
+    "Correct diagnosis (position 1)",
+    "Wrong diagnosis 2", 
+    "Wrong diagnosis 3",
+    "Wrong diagnosis 4",
+    "Wrong diagnosis 5"
+  ],
+  "diagnostic_clues": {
+    "supporting_primary": [
+      "Clue 1 supporting correct diagnosis",
+      "Clue 2 supporting correct diagnosis", 
+      "Clue 3 supporting correct diagnosis"
+    ],
+    "misleading_clues": [
+      "Misleading clue 1",
+      "Misleading clue 2"
+    ]
+  },
+  "wrong_answer_reasoning": {
+    "wrong_diagnosis_2": "Specific reason why this diagnosis is wrong",
+    "wrong_diagnosis_3": "Specific reason why this diagnosis is wrong",
+    "wrong_diagnosis_4": "Specific reason why this diagnosis is wrong", 
+    "wrong_diagnosis_5": "Specific reason why this diagnosis is wrong"
+  },
+  "reasoning_strategy": "Overall strategy for how this question will challenge ID specialists"
+}
+```
+
+Create a sophisticated blueprint that will result in a challenging ID fellowship-level question!

prompts/history_taking.j2

@@ -0,0 +1,9 @@
+{% raw %}
+[
+  {"role": "system", "content":
+   "You are an infectious diseases consultant preparing to advise a clinician. But first, you must gather the appropriate clinical history."},
+
+  {"role": "user", "content":
+   "The user described the concern as: '{{ syndrome_query }}'.\n\nHere is a list of questions to ask the user based on your knowledge base:\n\n{{ questions | join('\\n') }}\n\nNow, ask the user these questions one at a time, in a conversational and efficient way. Do not give advice yet."}
+]
+{% endraw %}

prompts/ipc_reporting.j2

@@ -0,0 +1,14 @@
+{% raw %}
+
+[
+  {
+    "role": "system",
+    "content": "You are an IPC reporting assistant. Your only way to get reporting requirements is by calling the `IPC_reporting` function. Do NOT free-text beyond gathering inputs for that function call."
+  },
+  {
+    "role": "user",
+    "content": "Case summary: {{ case_summary }}\nJurisdiction: {{ jurisdiction }}"
+  }
+]
+
+{% endraw %}

prompts/ipc_reporting_followup.j2

@@ -0,0 +1,18 @@
+{% raw %}
+[
+  {
+    "role": "system",
+    "content": "You have collected these fields: {{ collected_fields }}.\n\n"
+               "• If any required fields are still missing, ask the user one at a time:\n"
+               "    “Please provide the <field>:”\n\n"
+               "• Once **all** fields are collected, output **only** a JSON object wrapped in <JSON>…</JSON> tags, for example:\n\n"
+               "<JSON>\n"
+               "{\n"
+               "  \"meets_definition\": true,\n"
+               "  \"reasoning\": \"The patient had a central line in place for more than 2 days and no other sources identified.\"\n"
+               "}\n"
+               "</JSON>\n\n"
+               "Do **not** output any additional text."
+  }
+]
+{% endraw %}

prompts/isolation_precautions.j2

@@ -0,0 +1,13 @@
+{% raw %}
+[
+  {
+    "role": "system",
+    "content": "You are an infection prevention specialist. Interpret isolation precautions guidelines."
+  },
+  {
+    "role": "user",
+    "content": "Patient diagnosis: {{ diagnosis }}\nSymptoms: {{ symptoms }}\nKnown pathogens: {{ pathogen_list }}\n\nUsing CDC/APIC recommendations:\n- List required precautions (e.g., Contact, Droplet, Airborne).\n- Mention any special room or PPE requirements."
+  }
+]
+
+{% endraw %}

prompts/nhsn_criteria_evaluator_followup.j2

@@ -0,0 +1,17 @@
+
+[
+  {
+    "role": "system",
+    "content": "I have these required fields: {{ required_fields }}  \n"
+               "Ask the user for **each** missing field one at a time, using exactly:\n\n"
+               “Please provide the <field>:”\n\n
+               "When you have all values, output a single JSON object wrapped in <JSON>…</JSON> with keys:\n"
+               ```json
+               {
+                 "meets_definition": true|false,
+                 "reasoning": "..."
+               }
+               ```  
+               "Do **not** output any other text."
+  }
+]

prompts/nhsn_criteria_evaluator_start.j2

@@ -0,0 +1,16 @@
+
+[
+  {
+    "role": "system",
+    "content": "You are an expert in NHSN surveillance definitions.  \n"
+               "Your **only** output must be a JSON array of required data elements, wrapped in <JSON>…</JSON> tags.  \n"
+               "Do **not** output any other text."
+  },
+  {
+    "role": "user",
+    "content": "Patient case: {{ case_description }}  \n"
+               "Extract and return only the array of required NHSN fields."
+  }
+]
+
+

prompts/quality_review_board_exam.j2

@@ -0,0 +1,83 @@
+You are a stringent medical education quality assurance expert with a focus on creating MAXIMUM DIFFICULTY board exam questions. Your job is to be highly critical and identify every flaw that makes questions too easy or gives away answers.
+
+**Question to Review:**
+**Topic**: {{ topic }}
+**Vignette**: {{ vignette }}
+**Question**: {{ question_stem }}
+**Answer Choices**: {{ answer_choices }}
+**Explanations**: {{ explanations }}
+
+**CRITICAL FLAW DETECTION - BE RUTHLESS:**
+
+🚨 **ANSWER GIVEAWAYS IN VIGNETTE** (Automatic score reduction):
+- Does vignette mention specific test results revealing diagnosis? (e.g., "positive Coccidioides serology", "fungal pathogen antibodies")
+- Are there overly specific findings that make answer obvious?
+- Does travel history + specific test results = obvious diagnosis?
+- Are there unnecessary diagnostic details that eliminate differential?
+
+🚨 **ANSWER GIVEAWAYS IN QUESTION STEM** (Automatic score reduction):
+- Does question mention suspected diagnosis? (e.g., "suspected coccidioidomycosis", "this TB patient")
+- Does wording hint at correct answer category?
+- Is question diagnostically neutral or biased?
+
+🚨 **INSUFFICIENT DISTRACTORS IN VIGNETTE** (Major weakness):
+- Could misleading clinical findings support alternative diagnoses?
+- Are there missing symptoms that would make other conditions plausible?
+- Could lab results include red herrings or be more ambiguous?
+- Does vignette need MORE confounding factors?
+
+🚨 **TOO EASY FOR BOARD LEVEL** (Difficulty failure):
+- Can residents easily eliminate distractors?
+- Does this require fellowship-level reasoning or just pattern recognition?
+- Are distractors clinically implausible to experienced physicians?
+
+**Quality Assessment Criteria:**
+
+1. **Clinical Accuracy (0-5 points)**: Medical facts, dosages, procedures correct
+2. **Educational Value (0-5 points)**: Tests important clinical reasoning  
+3. **Difficulty Appropriateness (0-5 points)**: Requires advanced clinical reasoning, fellowship-level knowledge
+4. **Vignette Quality (0-5 points)**: Complex, realistic, includes distractors, NO giveaways
+5. **Answer Choice Quality (0-5 points)**: All options plausible to experienced physicians
+
+**SCORING PENALTIES:**
+- Automatic -2 points if vignette gives away diagnosis
+- Automatic -2 points if question stem mentions suspected diagnosis  
+- Automatic -1 point if distractors are too easily eliminated
+- Automatic -1 point if insufficient clinical complexity
+
+**Assessment Instructions:**
+- BE HIGHLY CRITICAL - assume most questions are too easy
+- Demand maximum difficulty appropriate for ID fellowship/board certification
+- Suggest adding MORE distractors and confounding factors
+- Eliminate ANY details that make diagnosis obvious
+
+**Output Format:**
+Return a JSON object with this exact structure:
+```json
+{
+  "clinical_accuracy_score": 4,
+  "educational_value_score": 5,
+  "difficulty_score": 3, 
+  "vignette_quality_score": 4,
+  "answer_choice_quality_score": 4,
+  "total_score": 20,
+  "percentage_score": 80,
+  "quality_level": "EXCELLENT/GOOD/ADEQUATE/NEEDS_IMPROVEMENT/POOR",
+  "strengths": [
+    "Specific strength 1",
+    "Specific strength 2"
+  ],
+  "weaknesses": [
+    "Specific weakness 1", 
+    "Specific weakness 2"
+  ],
+  "improvement_suggestions": [
+    "Specific suggestion 1",
+    "Specific suggestion 2"
+  ],
+  "board_exam_readiness": true/false,
+  "overall_assessment": "Detailed summary of question quality and recommendations"
+}
+```
+
+Provide honest, constructive feedback to ensure the highest quality medical education content.

prompts/summarize_antibiotic_duration.j2

@@ -0,0 +1,13 @@
+{% raw %}
+[
+  {
+    "role": "system",
+    "content": "You are an expert in infectious diseases guidelines. Summarize the recommended antibiotic duration for {{ condition }} using the IDSA search results first, then any other society guidelines."
+  },
+  {
+    "role": "user",
+    "content": "IDSA results:\n{{ idsa_results }}\n\nOther society results:\n{{ other_results }}\n\nPlease provide:\n1. The recommended duration(s) with your source for each.\n2. A brief rationale if durations differ."
+  }
+]
+
+{% endraw %}

requirements.txt

@@ -1 +1,60 @@
+# ID Agents Production Requirements
+# Updated: 2025-08-10 15:54:20
+# Python 3.12.7
+# 
+# This file contains pinned versions for reproducible deployments
+# Tested and verified working in development environment
+
+# Core AI/ML Framework
+openai>=1.3.0
 gradio==4.40.0
+
+# Data Processing & Scientific Computing
+pandas>=2.0.0
+numpy>=1.24.0
+
+# Document Processing
+pdfplumber
+python-docx
+
+# Web Requests & Search
+requests>=2.31.0
+duckduckgo-search>=4.0.0
+
+# Configuration & Environment Management
+python-dotenv>=1.0.0
+
+# Authentication & Security
+bcrypt>=4.0.0
+PyJWT>=2.8.0
+
+# Logging & Monitoring
+structlog>=23.0.0
+
+# Template Processing
+jinja2
+
+# Analytics & Visualization (optional)
+matplotlib>=3.5.0
+
+# Advanced AI Libraries (optional - enable for enhanced features)
+# Uncomment the following if you need advanced AI capabilities:
+# transformers
+# langchain
+# autogen
+# llama_index
+# farm-haystack
+# faiss-cpu
+
+# Development & Testing (optional - remove for production)
+# pytest
+
+# Load Testing Dependencies
+aiohttp>=3.8.0
+psutil>=5.9.0
+
+# Notes:
+# - All core dependencies use minimum version pinning (>=)
+# - Advanced AI libraries are commented out to reduce deployment size
+# - Uncomment additional libraries as needed for specific features
+# - For strict version pinning, replace >= with == and specific versions

tools/alert_prolonged_antibiotic_use.py

@@ -0,0 +1,119 @@
+from tools.base import Tool
+
+
+from tools.utils import ToolExecutionError, logger
+from typing import Any
+
+class AlertProlongedAntibioticUseTool(Tool):
+
+    def openai_spec(self, legacy=False):
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.args_schema
+        }
+    """
+    Tool to summarize recommended antibiotic durations for a given condition based on guidelines.
+
+    This tool searches IDSA and other society guidelines to provide a summary of recommended antibiotic durations for a specified clinical condition.
+    """
+    def __init__(self) -> None:
+        """
+        Initialize the AlertProlongedAntibioticUseTool with its name, description, and argument schema.
+        """
+        super().__init__()
+        self.name = "alert_prolonged_antibiotic_use"
+        self.description = (
+            "Search IDSA (and then other society) guidelines to summarize "
+            "recommended antibiotic durations for a given condition, considering all relevant clinical variables."
+        )
+        self.args_schema = {
+            "type": "object",
+            "properties": {
+                "condition": {
+                    "type": "string",
+                    "description": "Clinical condition to lookup antibiotic duration for"
+                },
+                "site_of_infection": {
+                    "type": "string",
+                    "description": "Site of infection (e.g., lung, urine, blood, etc.)"
+                },
+                "risk_of_biofilm": {
+                    "type": "string",
+                    "description": "Risk or presence of biofilm (e.g., prosthetic material, indwelling devices)"
+                },
+                "current_response": {
+                    "type": "string",
+                    "description": "Current response to antibiotics (e.g., improving, stable, worsening)"
+                },
+                "creatinine_clearance": {
+                    "type": "string",
+                    "description": "Creatinine clearance or renal function (e.g., 60 mL/min, ESRD, etc.)"
+                },
+                "severity_of_infection": {
+                    "type": "string",
+                    "description": "Severity of infection (e.g., mild, moderate, severe, septic shock)"
+                },
+                "known_allergies": {
+                    "type": "string",
+                    "description": "Known drug allergies (e.g., penicillin, sulfa, none)"
+                }
+            },
+            "required": [
+                "condition",
+                "site_of_infection",
+                "risk_of_biofilm",
+                "current_response",
+                "creatinine_clearance",
+                "severity_of_infection",
+                "known_allergies"
+            ]
+        }
+
+    async def run(
+        self,
+        condition: str,
+        site_of_infection: str,
+        risk_of_biofilm: str,
+        current_response: str,
+        creatinine_clearance: str,
+        severity_of_infection: str,
+        known_allergies: str
+    ) -> str:
+        """
+        Summarize recommended antibiotic duration for a given clinical condition, considering all relevant clinical variables.
+
+        Args:
+            condition (str): Clinical condition to lookup antibiotic duration for.
+            site_of_infection (str): Site of infection.
+            risk_of_biofilm (str): Risk or presence of biofilm.
+            current_response (str): Current response to antibiotics.
+            creatinine_clearance (str): Renal function.
+            severity_of_infection (str): Severity of infection.
+            known_allergies (str): Known drug allergies.
+
+        Returns:
+            str: The antibiotic duration summary (placeholder).
+
+        Raises:
+            ToolExecutionError: If the tool fails to summarize duration.
+        """
+        try:
+            # Placeholder for actual search and summarization logic
+            return (
+                f"Antibiotic duration summary for: {condition}\n"
+                f"Site of infection: {site_of_infection}\n"
+                f"Risk of biofilm: {risk_of_biofilm}\n"
+                f"Current response: {current_response}\n"
+                f"Creatinine clearance: {creatinine_clearance}\n"
+                f"Severity: {severity_of_infection}\n"
+                f"Allergies: {known_allergies}"
+            )
+        except Exception as e:
+            logger.error(f"AlertProlongedAntibioticUseTool failed: {e}", exc_info=True)
+            raise ToolExecutionError(
+                message=f"AlertProlongedAntibioticUseTool failed: {e}",
+                code="ANTIBIOTIC_DURATION_ERROR",
+                user_message="Unable to summarize antibiotic duration. Please try again or contact support.",
+                original_exception=e
+            )

tools/base.py

@@ -0,0 +1,56 @@
+
+from typing import Any, Dict
+from tools.utils import ToolExecutionError, logger
+
+class Tool:
+    def openai_spec(self, legacy=False):
+        """
+        Return the OpenAI function calling spec for this tool.
+        Subclasses should override this if they support function calling.
+        """
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.args_schema
+        }
+    """
+    Base class for all tools in the agent framework.
+
+    Attributes:
+        name (str): The unique name of the tool.
+        description (str): A short description of the tool's purpose.
+        args_schema (dict): The schema describing the tool's input arguments.
+    """
+    name: str
+    description: str
+    args_schema: Dict[str, Any]
+
+    def __init__(self) -> None:
+        """
+        Initialize the base Tool with default values.
+        Subclasses should override these attributes as needed.
+        """
+        self.name = "tool"
+        self.description = ""
+        self.args_schema = {}
+
+    async def run(self, **kwargs: Any) -> Any:
+        """
+        Run the tool with the provided arguments.
+        Subclasses must implement this method.
+
+        Args:
+            **kwargs: Arbitrary keyword arguments for the tool.
+
+        Returns:
+            Any: The result of the tool's execution.
+
+        Raises:
+            ToolExecutionError: If the method is not implemented by a subclass.
+        """
+        logger.error(f"Tool '{self.name}' does not implement the run method.")
+        raise ToolExecutionError(
+            message=f"Tool '{self.name}' does not implement the run method.",
+            code="TOOL_NOT_IMPLEMENTED",
+            user_message="This tool is not available. Please contact support.",
+        )

tools/create_educational_presentation.py

@@ -0,0 +1,1308 @@
+"""
+create_educational_presentation.py
+---------------------------------
+
+Tool for creating comprehensive educational presentations through iterative research.
+
+This tool conducts deep research on medical topics, creates detailed reports, and converts
+them into structured slide presentations for educational purposes. It uses an iterative
+research approach with user confirmation before finalizing the presentation.
+
+Key Features:
+- Iterative internet research with 4-5 rounds of 3-5 pages each
+- User clarification questions before research
+- Comprehensive report generation
+- Structured slide presentation creation
+- Educational flow: objectives → vignette → education → application → Q&A
+"""
+
+import asyncio
+import json
+from typing import Any, Dict, List, Union
+from tools.base import Tool
+from tools.utils import ToolExecutionError, logger, load_prompt
+from core.utils.llm_connector import call_llm
+from tools.internet_search import InternetSearchTool
+
+class CreateEducationalPresentationTool(Tool):
+    """
+    Tool for creating comprehensive educational presentations through iterative research.
+    
+    This tool conducts deep research, creates detailed reports, and converts them into
+    structured slide presentations for educational purposes.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize the CreateEducationalPresentationTool."""
+        super().__init__()
+        self.name = "create_educational_presentation"
+        self.description = "Create comprehensive educational presentations through AI-powered dynamic research and content generation."
+        self.internet_search = InternetSearchTool()
+        self.args_schema = {
+            "type": "object",
+            "properties": {
+                "topic": {
+                    "type": "string", 
+                    "description": "The medical topic for the educational presentation (e.g., 'sepsis management', 'heart failure diagnosis', 'antibiotic stewardship')"
+                },
+                "target_audience": {
+                    "type": "string", 
+                    "description": "The target audience for the presentation",
+                    "enum": ["medical_students", "residents", "attendings", "nurses", "pharmacists", "multidisciplinary"],
+                    "default": "medical_students"
+                },
+                "presentation_duration": {
+                    "type": "integer", 
+                    "description": "Expected duration of presentation in minutes",
+                    "default": 45,
+                    "minimum": 15,
+                    "maximum": 120
+                },
+                "focus_area": {
+                    "type": "string", 
+                    "description": "Specific focus area within the topic",
+                    "default": "comprehensive_overview"
+                },
+                "aspects_to_emphasize": {
+                    "type": "string", 
+                    "description": "What specific aspects to emphasize (e.g., 'pathophysiology, diagnosis, treatment')"
+                },
+                "guidelines_to_include": {
+                    "type": "string", 
+                    "description": "Specific guidelines or evidence to include (e.g., 'IDSA guidelines')"
+                },
+                "learning_objectives": {
+                    "type": "string", 
+                    "description": "What should the audience learn (e.g., 'diagnostic skills, treatment decisions')"
+                },
+                "clinical_scenarios": {
+                    "type": "string", 
+                    "description": "Specific clinical scenarios to highlight (e.g., 'common presentations')"
+                },
+                "takeaway_message": {
+                    "type": "string", 
+                    "description": "Key clinical pearl or takeaway message (e.g., 'early recognition saves lives')"
+                }
+            },
+            "required": ["topic"]
+        }
+
+    def openai_spec(self, legacy=False):
+        """Return OpenAI function specification."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.args_schema
+        }
+
+    async def run(
+        self,
+        topic: str,
+        target_audience: str = "medical_students",
+        presentation_duration: int = 45,
+        focus_area: str = "comprehensive_overview",
+        aspects_to_emphasize: Union[str, None] = None,
+        guidelines_to_include: Union[str, None] = None,
+        learning_objectives: Union[str, None] = None,
+        clinical_scenarios: Union[str, None] = None,
+        takeaway_message: Union[str, None] = None
+    ) -> Dict[str, Any]:
+        """
+        Create a comprehensive educational presentation through iterative research.
+        
+        Args:
+            topic (str): The medical topic for the presentation
+            target_audience (str): The target audience
+            presentation_duration (int): Duration in minutes
+            focus_area (str): Specific focus area
+            aspects_to_emphasize (str): What specific aspects to emphasize
+            guidelines_to_include (str): Specific guidelines or evidence to include
+            learning_objectives (str): What should the audience learn
+            clinical_scenarios (str): Specific clinical scenarios to highlight
+            takeaway_message (str): Key clinical pearl or takeaway message
+            
+        Returns:
+            Dict[str, Any]: Complete presentation with research, report, and slides
+        """
+        try:
+            logger.info(f"Starting educational presentation creation for topic: {topic}")
+            
+            # Build clarification responses from provided parameters
+            clarification_responses = {}
+            
+            # Check if we have enough information to proceed
+            if aspects_to_emphasize and guidelines_to_include and learning_objectives and clinical_scenarios and takeaway_message:
+                clarification_responses = {
+                    "aspects": aspects_to_emphasize,
+                    "guidelines": guidelines_to_include,
+                    "learning_objectives": learning_objectives,
+                    "clinical_scenarios": clinical_scenarios,
+                    "takeaway_message": takeaway_message
+                }
+            else:
+                # Use intelligent defaults based on the topic and focus area
+                clarification_responses = self._generate_intelligent_defaults(topic, target_audience, focus_area)
+                logger.info(f"Using intelligent defaults for presentation creation")
+            
+            # Proceed with full presentation creation
+            logger.info(f"Proceeding with presentation creation using responses")
+            
+            # Step 2: Conduct iterative research
+            research_results = await self._conduct_iterative_research(topic, clarification_responses)
+            
+            # Step 3: Generate comprehensive report
+            research_report = self._generate_research_report(topic, research_results, clarification_responses)
+            
+            # Step 4: Create presentation structure
+            presentation_structure = self._create_presentation_structure(
+                topic, target_audience, presentation_duration, research_report
+            )
+            
+            # Step 5: Create final presentation using existing method
+            final_presentation = await self.create_final_presentation(
+                topic, target_audience, presentation_duration, research_report, 
+                presentation_structure, ""
+            )
+            
+            logger.info(f"Successfully created educational presentation for {topic}")
+            return final_presentation
+            
+        except Exception as e:
+            logger.error(f"CreateEducationalPresentationTool failed: {e}", exc_info=True)
+            raise ToolExecutionError(f"Failed to create educational presentation: {e}")
+
+    async def continue_with_research(
+        self,
+        topic: str,
+        target_audience: str,
+        presentation_duration: int,
+        focus_area: str,
+        clarification_responses: Dict[str, str]
+    ) -> Dict[str, Any]:
+        """
+        Continue with research phase after receiving clarification responses.
+        
+        Args:
+            topic (str): The medical topic
+            target_audience (str): Target audience
+            presentation_duration (int): Duration in minutes
+            focus_area (str): Focus area
+            clarification_responses (Dict[str, str]): User responses to clarification questions
+            
+        Returns:
+            Dict[str, Any]: Research results and next steps
+        """
+        try:
+            logger.info(f"Continuing with research for topic: {topic}")
+            
+            # Step 2: Conduct iterative research
+            research_results = await self._conduct_iterative_research(topic, clarification_responses)
+            
+            # Step 3: Generate comprehensive report
+            research_report = self._generate_research_report(topic, research_results, clarification_responses)
+            
+            # Step 4: Create presentation structure
+            presentation_structure = self._create_presentation_structure(
+                topic, target_audience, presentation_duration, research_report
+            )
+            
+            return {
+                "status": "research_complete",
+                "topic": topic,
+                "target_audience": target_audience,
+                "presentation_duration": presentation_duration,
+                "research_results": research_results,
+                "research_report": research_report,
+                "proposed_structure": presentation_structure,
+                "next_step": "Please review the research report and presentation structure. Confirm to proceed with slide creation."
+            }
+            
+        except Exception as e:
+            logger.error(f"Research phase failed: {e}", exc_info=True)
+            raise ToolExecutionError(f"Failed to complete research: {e}")
+
+    async def create_final_presentation(
+        self,
+        topic: str,
+        target_audience: str,
+        presentation_duration: int,
+        research_report: str,
+        presentation_structure: Dict[str, Any],
+        user_feedback: str = ""
+    ) -> Dict[str, Any]:
+        """
+        Create the final presentation slides.
+        
+        Args:
+            topic (str): The medical topic
+            target_audience (str): Target audience
+            presentation_duration (int): Duration in minutes
+            research_report (str): The research report
+            presentation_structure (Dict): Presentation structure
+            user_feedback (str): User feedback on structure
+            
+        Returns:
+            Dict[str, Any]: Complete presentation with slides
+        """
+        try:
+            logger.info(f"Creating final presentation for topic: {topic}")
+            
+            # Adjust structure based on user feedback if provided
+            if user_feedback:
+                presentation_structure = self._adjust_structure_based_on_feedback(
+                    presentation_structure, user_feedback
+                )
+            
+            # Generate all slides
+            slides = await self._generate_all_slides(
+                topic, target_audience, research_report, presentation_structure
+            )
+            
+            # Create speaker notes
+            speaker_notes = self._generate_speaker_notes(slides, research_report)
+            
+            # Generate presentation metadata
+            presentation_metadata = self._generate_presentation_metadata(
+                topic, target_audience, presentation_duration, len(slides)
+            )
+            
+            return {
+                "status": "presentation_complete",
+                "topic": topic,
+                "target_audience": target_audience,
+                "presentation_duration": presentation_duration,
+                "total_slides": len(slides),
+                "slides": slides,
+                "speaker_notes": speaker_notes,
+                "metadata": presentation_metadata,
+                "research_report": research_report,
+                "created_date": "2025-07-18"
+            }
+            
+        except Exception as e:
+            logger.error(f"Final presentation creation failed: {e}", exc_info=True)
+            raise ToolExecutionError(f"Failed to create final presentation: {e}")
+
+    def _generate_clarification_questions(self, topic: str, target_audience: str, focus_area: str) -> List[Dict[str, str]]:
+        """Generate 3-5 clarification questions for the user."""
+        
+        questions = [
+            {
+                "question": f"What specific aspects of {topic} would you like to emphasize in this presentation?",
+                "purpose": "To focus the research on the most relevant areas",
+                "examples": "e.g., pathophysiology, diagnosis, treatment, recent advances, guidelines"
+            },
+            {
+                "question": f"Are there any specific guidelines, studies, or evidence you want to include?",
+                "purpose": "To ensure important references are included",
+                "examples": "e.g., specific society guidelines, landmark studies, recent publications"
+            },
+            {
+                "question": f"What learning objectives should the {target_audience} achieve after this presentation?",
+                "purpose": "To structure the educational content appropriately",
+                "examples": "e.g., diagnostic skills, treatment decisions, understanding pathophysiology"
+            },
+            {
+                "question": f"Are there any specific clinical scenarios or patient populations you want to highlight?",
+                "purpose": "To create relevant clinical vignettes",
+                "examples": "e.g., pediatric patients, elderly, specific comorbidities, severity levels"
+            },
+            {
+                "question": f"What should be the takeaway message or key clinical pearl from this presentation?",
+                "purpose": "To ensure the presentation has a clear, memorable message",
+                "examples": "e.g., early recognition saves lives, personalized treatment approach, guideline adherence"
+            }
+        ]
+        
+        return questions
+
+    def _generate_intelligent_defaults(self, topic: str, target_audience: str, focus_area: str) -> Dict[str, str]:
+        """
+        Generate intelligent default responses based on topic and focus area.
+        
+        Args:
+            topic (str): The medical topic
+            target_audience (str): Target audience
+            focus_area (str): Focus area
+            
+        Returns:
+            Dict[str, str]: Intelligent default responses
+        """
+        try:
+            # Topic-specific intelligent defaults
+            topic_lower = topic.lower()
+            
+            if "dimorphic fungi" in topic_lower or "fungal" in topic_lower:
+                return {
+                    "aspects": "comprehensive coverage including pathophysiology, diagnosis, treatment, epidemiology, and clinical presentations",
+                    "guidelines": "IDSA guidelines and recent evidence-based recommendations",
+                    "learning_objectives": "comprehensive understanding of diagnosis, treatment, and key clinical presentations for board exam preparation",
+                    "clinical_scenarios": "common clinical presentations of each dimorphic fungus including histoplasmosis, coccidioidomycosis, blastomycosis, and others",
+                    "takeaway_message": "systematic approach to diagnosis and management with focus on board exam question patterns"
+                }
+            elif "sepsis" in topic_lower:
+                return {
+                    "aspects": "pathophysiology, early recognition, diagnosis, management, and outcomes",
+                    "guidelines": "Surviving Sepsis Campaign guidelines and recent updates",
+                    "learning_objectives": "early recognition, appropriate management, and outcome improvement",
+                    "clinical_scenarios": "emergency department presentations, ICU management, and complications",
+                    "takeaway_message": "early recognition and prompt treatment save lives"
+                }
+            elif "heart failure" in topic_lower:
+                return {
+                    "aspects": "pathophysiology, classification, diagnosis, management, and prognosis",
+                    "guidelines": "ACC/AHA heart failure guidelines",
+                    "learning_objectives": "diagnostic skills, treatment optimization, and guideline adherence",
+                    "clinical_scenarios": "acute decompensated heart failure, chronic management, and comorbidities",
+                    "takeaway_message": "guideline-directed medical therapy improves outcomes"
+                }
+            else:
+                # Generic intelligent defaults
+                return {
+                    "aspects": "comprehensive coverage including pathophysiology, diagnosis, treatment, and recent advances",
+                    "guidelines": "latest evidence-based guidelines from relevant professional societies",
+                    "learning_objectives": "comprehensive understanding of diagnosis, treatment, and key clinical pearls",
+                    "clinical_scenarios": "common clinical presentations and real-world case studies",
+                    "takeaway_message": "evidence-based approach to diagnosis and management"
+                }
+                
+        except Exception as e:
+            logger.warning(f"Failed to generate intelligent defaults: {e}")
+            # Fallback to basic defaults
+            return {
+                "aspects": "comprehensive overview of the topic",
+                "guidelines": "current evidence-based guidelines",
+                "learning_objectives": "understanding of key concepts",
+                "clinical_scenarios": "common clinical presentations",
+                "takeaway_message": "evidence-based clinical approach"
+            }
+
+    async def _conduct_iterative_research(self, topic: str, clarification_responses: Dict[str, str]) -> Dict[str, Any]:
+        """Conduct 4-5 rounds of iterative research."""
+        
+        research_results = {
+            "rounds": [],
+            "total_sources": 0,
+            "key_themes": [],
+            "evidence_summary": {}
+        }
+        
+        # Import internet search tool
+        from tools.internet_search import InternetSearchTool
+        internet_tool = InternetSearchTool()
+        
+        # Round 1: General topic overview
+        round1_queries = [
+            f"{topic} overview clinical guidelines",
+            f"{topic} pathophysiology mechanisms",
+            f"{topic} diagnosis treatment current evidence",
+            f"{topic} management recommendations 2024",
+            f"{topic} clinical practice guidelines"
+        ]
+        
+        round1_results = await self._conduct_research_round(internet_tool, round1_queries, 1, "General Overview")
+        research_results["rounds"].append(round1_results)
+        
+        # Round 2: Specific focus based on clarification
+        focus_keywords = self._extract_focus_keywords(clarification_responses)
+        round2_queries = [
+            f"{topic} {focus_keywords[0]} latest research",
+            f"{topic} {focus_keywords[1]} clinical studies",
+            f"{topic} {focus_keywords[0]} best practices",
+            f"{topic} guidelines {focus_keywords[1]}",
+            f"{topic} evidence based {focus_keywords[0]}"
+        ]
+        
+        round2_results = await self._conduct_research_round(internet_tool, round2_queries, 2, "Focused Research")
+        research_results["rounds"].append(round2_results)
+        
+        # Round 3: Clinical evidence and studies
+        round3_queries = [
+            f"{topic} randomized controlled trials",
+            f"{topic} systematic review meta-analysis",
+            f"{topic} clinical outcomes studies",
+            f"{topic} evidence quality assessment",
+            f"{topic} landmark studies"
+        ]
+        
+        round3_results = await self._conduct_research_round(internet_tool, round3_queries, 3, "Clinical Evidence")
+        research_results["rounds"].append(round3_results)
+        
+        # Round 4: Guidelines and recommendations
+        round4_queries = [
+            f"{topic} society guidelines recommendations",
+            f"{topic} international consensus statements",
+            f"{topic} practice guidelines updates",
+            f"{topic} expert consensus recommendations",
+            f"{topic} clinical practice standards"
+        ]
+        
+        round4_results = await self._conduct_research_round(internet_tool, round4_queries, 4, "Guidelines & Recommendations")
+        research_results["rounds"].append(round4_results)
+        
+        # Calculate total sources
+        research_results["total_sources"] = sum(len(round_data["sources"]) for round_data in research_results["rounds"])
+        
+        # Extract key themes
+        research_results["key_themes"] = self._extract_key_themes(research_results["rounds"])
+        
+        return research_results
+
+    async def _conduct_research_round(self, internet_tool, queries: List[str], round_number: int, round_focus: str) -> Dict[str, Any]:
+        """Conduct a single round of research."""
+        
+        round_results = {
+            "round_number": round_number,
+            "focus": round_focus,
+            "queries": queries,
+            "sources": [],
+            "summary": ""
+        }
+        
+        for query in queries:
+            try:
+                search_results = await internet_tool.run(query)
+                if search_results:
+                    # Parse and extract key information
+                    parsed_sources = self._parse_search_results(search_results, query)
+                    round_results["sources"].extend(parsed_sources)
+                    
+                    # Limit to 3-5 sources per round
+                    if len(round_results["sources"]) >= 5:
+                        break
+                        
+            except Exception as e:
+                logger.warning(f"Search failed for query '{query}': {e}")
+                continue
+        
+        # Generate summary for this round
+        round_results["summary"] = self._generate_round_summary(round_results["sources"], round_focus)
+        
+        return round_results
+
+    def _parse_search_results(self, search_results: str, query: str) -> List[Dict[str, str]]:
+        """Parse search results string into structured sources."""
+        
+        sources = []
+        
+        # Split by entries (each entry starts with **)
+        import re
+        entries = re.split(r'\*\*([^*]+)\*\*', search_results)
+        
+        for i in range(1, len(entries), 2):
+            if i + 1 < len(entries):
+                title = entries[i].strip()
+                content_and_link = entries[i + 1].strip()
+                
+                # Extract the link
+                link_match = re.search(r'\[Read more\]\(([^)]+)\)', content_and_link)
+                url = link_match.group(1) if link_match else ""
+                
+                # Extract the content
+                content = re.sub(r'\[Read more\]\([^)]+\)', '', content_and_link).strip()
+                
+                if title and content:
+                    sources.append({
+                        "title": title,
+                        "url": url,
+                        "content": content,
+                        "query": query,
+                        "relevance": "high"  # Could be improved with actual relevance scoring
+                    })
+        
+        return sources
+
+    def _extract_focus_keywords(self, clarification_responses: Dict[str, str]) -> List[str]:
+        """Extract focus keywords from clarification responses."""
+        
+        keywords = ["diagnosis", "treatment", "management", "pathophysiology", "guidelines"]
+        
+        # Extract keywords from user responses
+        for response in clarification_responses.values():
+            if response:
+                # Simple keyword extraction - could be improved
+                if "diagnosis" in response.lower():
+                    keywords.insert(0, "diagnosis")
+                elif "treatment" in response.lower():
+                    keywords.insert(0, "treatment")
+                elif "management" in response.lower():
+                    keywords.insert(0, "management")
+        
+        return keywords[:2]  # Return top 2 keywords
+
+    def _generate_round_summary(self, sources: List[Dict], round_focus: str) -> str:
+        """Generate a summary for a research round."""
+        
+        if not sources:
+            return f"No relevant sources found for {round_focus}."
+        
+        # Extract key points from sources
+        key_points = []
+        for source in sources:
+            content = source.get("content", "")
+            if len(content) > 50:
+                # Extract first sentence or key point
+                first_sentence = content.split('.')[0]
+                if len(first_sentence) > 20:
+                    key_points.append(first_sentence)
+        
+        summary = f"**{round_focus}** ({len(sources)} sources):\n"
+        for i, point in enumerate(key_points[:3], 1):
+            summary += f"{i}. {point}\n"
+        
+        return summary
+
+    def _extract_key_themes(self, rounds: List[Dict]) -> List[str]:
+        """Extract key themes from all research rounds."""
+        
+        themes = []
+        
+        for round_data in rounds:
+            summary = round_data.get("summary", "")
+            if "diagnosis" in summary.lower():
+                themes.append("Diagnostic Approach")
+            if "treatment" in summary.lower():
+                themes.append("Treatment Strategies")
+            if "management" in summary.lower():
+                themes.append("Clinical Management")
+            if "guidelines" in summary.lower():
+                themes.append("Evidence-Based Guidelines")
+            if "pathophysiology" in summary.lower():
+                themes.append("Pathophysiology")
+        
+        # Remove duplicates and return unique themes
+        return list(set(themes))
+
+    def _generate_research_report(self, topic: str, research_results: Dict, clarification_responses: Dict) -> str:
+        """Generate a comprehensive research report."""
+        
+        report = f"# Comprehensive Research Report: {topic.title()}\n\n"
+        
+        # Executive summary
+        report += "## Executive Summary\n"
+        report += f"This report synthesizes findings from {research_results['total_sources']} sources across {len(research_results['rounds'])} research rounds.\n\n"
+        
+        # Key themes
+        report += "## Key Themes Identified\n"
+        for theme in research_results["key_themes"]:
+            report += f"- {theme}\n"
+        report += "\n"
+        
+        # Research rounds summary
+        report += "## Research Findings by Round\n"
+        for round_data in research_results["rounds"]:
+            report += f"### Round {round_data['round_number']}: {round_data['focus']}\n"
+            report += f"{round_data['summary']}\n\n"
+        
+        # Evidence synthesis
+        report += "## Evidence Synthesis\n"
+        report += f"Based on the research conducted, the following key points emerge about {topic}:\n\n"
+        
+        # Add synthesized content based on themes
+        for theme in research_results["key_themes"]:
+            report += f"**{theme}**: [Evidence-based summary for {theme}]\n\n"
+        
+        # Clinical implications
+        report += "## Clinical Implications\n"
+        report += f"The research findings have the following implications for clinical practice:\n"
+        report += "- [Key clinical implication 1]\n"
+        report += "- [Key clinical implication 2]\n"
+        report += "- [Key clinical implication 3]\n\n"
+        
+        # Recommendations
+        report += "## Recommendations\n"
+        report += "Based on the evidence review:\n"
+        report += "1. [Recommendation 1]\n"
+        report += "2. [Recommendation 2]\n"
+        report += "3. [Recommendation 3]\n\n"
+        
+        return report
+
+    def _create_presentation_structure(self, topic: str, target_audience: str, duration: int, research_report: str) -> Dict[str, Any]:
+        """Create the presentation structure."""
+        
+        # Calculate approximate slides based on duration
+        slides_estimate = max(10, duration // 3)  # ~3 minutes per slide
+        
+        structure = {
+            "title": f"{topic.title()}: A Comprehensive Review",
+            "estimated_slides": slides_estimate,
+            "estimated_duration": duration,
+            "sections": [
+                {
+                    "section": "Introduction",
+                    "slides": [
+                        {"title": "Title Slide", "content": f"{topic.title()}", "duration": 1},
+                        {"title": "Learning Objectives", "content": "What you will learn today", "duration": 2},
+                        {"title": "Case Vignette", "content": "Clinical scenario introduction", "duration": 3}
+                    ]
+                },
+                {
+                    "section": "Educational Content",
+                    "slides": [
+                        {"title": "Definition & Overview", "content": f"What is {topic}?", "duration": 5},
+                        {"title": "Pathophysiology", "content": "Understanding the mechanisms", "duration": 7},
+                        {"title": "Clinical Presentation", "content": "Recognition and diagnosis", "duration": 7},
+                        {"title": "Diagnostic Approach", "content": "Evidence-based diagnosis", "duration": 8},
+                        {"title": "Treatment Strategies", "content": "Management options", "duration": 8},
+                        {"title": "Guidelines & Evidence", "content": "Current recommendations", "duration": 5}
+                    ]
+                },
+                {
+                    "section": "Application",
+                    "slides": [
+                        {"title": "Case Application", "content": "Applying knowledge to the vignette", "duration": 5},
+                        {"title": "Clinical Pearls", "content": "Key takeaways", "duration": 3}
+                    ]
+                },
+                {
+                    "section": "Assessment",
+                    "slides": [
+                        {"title": "Rapid Fire Questions", "content": "Quick knowledge check", "duration": 5},
+                        {"title": "Discussion", "content": "Open discussion and Q&A", "duration": 5}
+                    ]
+                }
+            ]
+        }
+        
+        return structure
+
+    def _adjust_structure_based_on_feedback(self, structure: Dict, feedback: str) -> Dict:
+        """Adjust presentation structure based on user feedback."""
+        
+        # Simple feedback processing - could be enhanced
+        if "more slides" in feedback.lower():
+            # Add more detail slides
+            for section in structure["sections"]:
+                if section["section"] == "Educational Content":
+                    section["slides"].append({
+                        "title": "Advanced Topics",
+                        "content": "Additional detailed information",
+                        "duration": 5
+                    })
+        
+        if "shorter" in feedback.lower():
+            # Remove some slides
+            for section in structure["sections"]:
+                if len(section["slides"]) > 2:
+                    section["slides"] = section["slides"][:2]
+        
+        return structure
+
+    async def _generate_all_slides(self, topic: str, target_audience: str, research_report: str, structure: Dict) -> List[Dict[str, Any]]:
+        """Generate all presentation slides using AI and research content."""
+        
+        slides = []
+        slide_number = 1
+        
+        logger.info(f"Starting AI-powered slide generation for {topic}")
+        
+        for section in structure["sections"]:
+            for slide_template in section["slides"]:
+                try:
+                    slide = await self._create_ai_slide(
+                        slide_number,
+                        slide_template["title"],
+                        slide_template["content"],
+                        topic,
+                        target_audience,
+                        research_report,
+                        section["section"]
+                    )
+                    slides.append(slide)
+                    slide_number += 1
+                    logger.info(f"Generated slide {slide_number-1}: {slide_template['title']}")
+                    
+                except Exception as e:
+                    logger.error(f"Failed to generate slide {slide_number}: {e}")
+                    # Fallback to basic slide structure
+                    slide = self._create_fallback_slide(slide_number, slide_template["title"], section["section"])
+                    slides.append(slide)
+                    slide_number += 1
+        
+        logger.info(f"Completed slide generation: {len(slides)} slides created")
+        return slides
+
+    async def _create_ai_slide(self, slide_number: int, title: str, content_desc: str, topic: str, 
+                               target_audience: str, research_report: str, section: str) -> Dict[str, Any]:
+        """Create an individual slide with AI-generated content based on research."""
+        
+        try:
+            # Load the slide generation prompt
+            logger.info(f"Generating AI content for slide: {title}")
+            prompt = load_prompt('generate_presentation_slide.j2', 
+                topic=topic,
+                target_audience=target_audience.replace('_', ' '),
+                slide_title=title,
+                section=section,
+                content_description=content_desc,
+                research_report=research_report[:3000]  # Limit research content to avoid token limits
+            )
+            
+            # Generate slide content with OpenAI
+            response = await asyncio.wait_for(
+                call_llm(prompt), 
+                timeout=30.0
+            )
+            
+            # Parse AI response
+            if response.strip().startswith('```json'):
+                response = response.strip()[7:-3].strip()
+            elif response.strip().startswith('```'):
+                response = response.strip()[3:-3].strip()
+            
+            slide_content = json.loads(response)
+            
+            # Construct the slide with AI-generated content
+            slide = {
+                "slide_number": slide_number,
+                "title": slide_content.get("slide_title", title),
+                "section": section,
+                "content": {
+                    "bullet_points": slide_content.get("main_content", []),
+                    "sub_bullets": slide_content.get("sub_bullets", {}),
+                    "clinical_notes": slide_content.get("clinical_notes", ""),
+                    "references_used": slide_content.get("references_used", ""),
+                    "generation_method": "AI-powered with research integration"
+                }
+            }
+            
+            logger.info(f"Successfully generated AI slide: {title} ({len(slide['content']['bullet_points'])} main points)")
+            return slide
+            
+        except Exception as e:
+            logger.error(f"AI slide generation failed for {title}: {e}")
+            # Return fallback slide
+            return self._create_fallback_slide(slide_number, title, section)
+
+    def _create_fallback_slide(self, slide_number: int, title: str, section: str) -> Dict[str, Any]:
+        """Create a basic fallback slide if AI generation fails."""
+        return {
+            "slide_number": slide_number,
+            "title": title,
+            "section": section,
+            "content": {
+                "bullet_points": [
+                    f"Content for {title} slide",
+                    "Key points to be covered",
+                    "Clinical applications",
+                    "Important considerations"
+                ],
+                "sub_bullets": {},
+                "clinical_notes": "Fallback content - consider manual review",
+                "generation_method": "Fallback template"
+            }
+        }
+
+    def _create_slide(self, slide_number: int, title: str, content_desc: str, topic: str, target_audience: str, research_report: str, section: str) -> Dict[str, Any]:
+        """Create an individual slide with detailed, presentation-ready content."""
+        
+        slide = {
+            "slide_number": slide_number,
+            "title": title,
+            "section": section,
+            "content": {
+                "bullet_points": [],
+                "images": [],
+                "notes": ""
+            }
+        }
+        
+        # Generate detailed content based on slide type and topic
+        if "Title Slide" in title:
+            slide["content"]["bullet_points"] = [
+                f"{topic.title()}: A Comprehensive Review",
+                f"For {target_audience.replace('_', ' ').title()}",
+                f"Date: July 18, 2025"
+            ]
+        elif "Learning Objectives" in title:
+            slide["content"]["bullet_points"] = self._generate_learning_objectives_content(topic)
+        elif "Case Vignette" in title:
+            slide["content"]["bullet_points"] = self._generate_case_vignette_content(topic)
+        elif "Definition" in title or "Overview" in title:
+            slide["content"]["bullet_points"] = self._generate_definition_overview_content(topic)
+        elif "Pathophysiology" in title:
+            slide["content"]["bullet_points"] = self._generate_pathophysiology_content(topic)
+        elif "Clinical Presentation" in title:
+            slide["content"]["bullet_points"] = self._generate_clinical_presentation_content(topic)
+        elif "Diagnostic" in title:
+            slide["content"]["bullet_points"] = self._generate_diagnostic_content(topic)
+        elif "Treatment" in title:
+            slide["content"]["bullet_points"] = self._generate_treatment_content(topic)
+        elif "Guidelines" in title:
+            slide["content"]["bullet_points"] = self._generate_guidelines_content(topic)
+        elif "Case Application" in title:
+            slide["content"]["bullet_points"] = self._generate_case_application_content(topic)
+        elif "Clinical Pearls" in title:
+            slide["content"]["bullet_points"] = self._generate_clinical_pearls_content(topic)
+        elif "Rapid Fire" in title:
+            slide["content"]["bullet_points"] = self._generate_rapid_fire_content(topic)
+        elif "Discussion" in title:
+            slide["content"]["bullet_points"] = self._generate_discussion_content(topic)
+        else:
+            # Fallback for other slide types
+            slide["content"]["bullet_points"] = self._generate_generic_content(title, topic)
+        
+        return slide
+
+    def _generate_learning_objectives_content(self, topic: str) -> List[str]:
+        """Generate specific learning objectives based on topic."""
+        
+        if "dimorphic fungi" in topic.lower():
+            return [
+                "Identify the three major endemic dimorphic fungi in the United States",
+                "Describe the unique morphological characteristics of dimorphic fungi",
+                "Recognize geographic distribution patterns and epidemiologic risk factors",
+                "Differentiate clinical presentations of histoplasmosis, blastomycosis, and coccidioidomycosis",
+                "Apply appropriate diagnostic testing strategies and interpret results",
+                "Implement evidence-based antifungal treatment protocols per IDSA guidelines"
+            ]
+        elif "pneumonia" in topic.lower():
+            return [
+                "Classify pneumonia by etiology and clinical setting (CAP, HAP, VAP)",
+                "Recognize clinical presentation and physical examination findings",
+                "Select appropriate diagnostic tests and interpret chest imaging",
+                "Apply severity scoring systems (CURB-65, PSI) for risk stratification",
+                "Implement evidence-based antibiotic therapy based on guidelines",
+                "Identify complications and indications for hospitalization"
+            ]
+        else:
+            return [
+                f"Define key concepts related to {topic}",
+                f"Recognize clinical manifestations of {topic}",
+                f"Apply diagnostic approaches for {topic}",
+                f"Implement evidence-based treatment strategies",
+                f"Integrate current guidelines into clinical practice"
+            ]
+
+    def _generate_case_vignette_content(self, topic: str) -> List[str]:
+        """Generate specific case vignette based on topic."""
+        
+        if "dimorphic fungi" in topic.lower():
+            return [
+                "45-year-old construction worker from Ohio River Valley",
+                "Recent spelunking activities in Kentucky caves (6 weeks ago)",
+                "3-week history: fever, nonproductive cough, 15-pound weight loss",
+                "Physical exam: erythema nodosum, bilateral hilar lymphadenopathy",
+                "Labs: lymphopenia, elevated ESR, positive Histoplasma urine antigen",
+                "Question: What is the most likely diagnosis and treatment?"
+            ]
+        elif "pneumonia" in topic.lower():
+            return [
+                "68-year-old man with COPD and diabetes",
+                "Recent cruise ship travel, acute onset (48 hours)",
+                "Productive cough with rust-colored sputum, pleuritic chest pain",
+                "Physical exam: dullness to percussion, bronchial breath sounds",
+                "Labs: elevated WBC with left shift, positive pneumococcal antigen",
+                "Question: What is the most appropriate treatment approach?"
+            ]
+        else:
+            return [
+                f"Clinical scenario presenting with {topic}",
+                "Relevant patient history and risk factors",
+                "Physical examination findings",
+                "Initial diagnostic workup results",
+                "Clinical decision-making challenge"
+            ]
+
+    def _generate_definition_overview_content(self, topic: str) -> List[str]:
+        """Generate definition and overview content."""
+        
+        if "dimorphic fungi" in topic.lower():
+            return [
+                "Dimorphic fungi: organisms that exist in two distinct morphological forms",
+                "Yeast form at body temperature (37°C) - pathogenic phase",
+                "Mold form at room temperature (25°C) - environmental phase",
+                "Three major endemic fungi in US: Histoplasma, Blastomyces, Coccidioides",
+                "Cause significant morbidity in immunocompromised and healthy hosts",
+                "Geographic distribution correlates with environmental factors"
+            ]
+        elif "pneumonia" in topic.lower():
+            return [
+                "Pneumonia: infection of the lung parenchyma and alveolar spaces",
+                "Leading cause of infectious disease mortality worldwide",
+                "Classification: Community-acquired (CAP), Healthcare-associated (HAP/VAP)",
+                "Etiology: bacterial, viral, fungal, or atypical pathogens",
+                "Risk factors: age, comorbidities, immunosuppression, aspiration",
+                "Clinical spectrum: mild outpatient to severe septic shock"
+            ]
+        else:
+            return [
+                f"Definition and key characteristics of {topic}",
+                f"Epidemiology and prevalence of {topic}",
+                f"Clinical significance in medical practice",
+                f"Risk factors and predisposing conditions"
+            ]
+
+    def _generate_pathophysiology_content(self, topic: str) -> List[str]:
+        """Generate pathophysiology content."""
+        
+        if "dimorphic fungi" in topic.lower():
+            return [
+                "Inhalation of microconidia from contaminated soil or bird/bat droppings",
+                "Conversion to yeast form in lung alveoli at body temperature",
+                "Phagocytosis by alveolar macrophages - intracellular survival",
+                "Hematogenous dissemination to reticuloendothelial system",
+                "Host immune response: cell-mediated immunity crucial for control",
+                "Granulomatous inflammation with potential for reactivation"
+            ]
+        elif "pneumonia" in topic.lower():
+            return [
+                "Pathogen invasion of lower respiratory tract via inhalation or aspiration",
+                "Overwhelm of normal host defense mechanisms (mucociliary clearance, alveolar macrophages)",
+                "Inflammatory response: neutrophil recruitment, cytokine release",
+                "Alveolar filling with inflammatory exudate and impaired gas exchange",
+                "Systemic inflammatory response syndrome (SIRS) in severe cases",
+                "Complications: pleural effusion, empyema, respiratory failure"
+            ]
+        else:
+            return [
+                f"Underlying mechanisms of {topic}",
+                f"Pathophysiologic pathways involved",
+                f"Host response and immune system involvement",
+                f"Disease progression and complications"
+            ]
+
+    def _generate_clinical_presentation_content(self, topic: str) -> List[str]:
+        """Generate clinical presentation content."""
+        
+        if "dimorphic fungi" in topic.lower():
+            return [
+                "Histoplasmosis: fever, cough, weight loss, erythema nodosum",
+                "Blastomycosis: skin lesions, pulmonary symptoms, bone involvement",
+                "Coccidioidomycosis: Valley fever, arthralgias, desert rheumatism",
+                "Pulmonary manifestations: nodules, cavitation, hilar lymphadenopathy",
+                "Disseminated disease: CNS, skin, bone, adrenal involvement",
+                "Chronic forms: progressive pulmonary fibrosis, cavitary disease"
+            ]
+        elif "pneumonia" in topic.lower():
+            return [
+                "Classic triad: fever, cough, and dyspnea",
+                "Productive cough with purulent sputum (bacterial)",
+                "Pleuritic chest pain and decreased breath sounds",
+                "Physical signs: dullness to percussion, crackles, bronchial breath sounds",
+                "Systemic symptoms: malaise, myalgias, headache",
+                "Severe cases: sepsis, altered mental status, respiratory failure"
+            ]
+        else:
+            return [
+                f"Common signs and symptoms of {topic}",
+                f"Physical examination findings",
+                f"Disease spectrum and severity variations",
+                f"Complications and warning signs"
+            ]
+
+    def _generate_diagnostic_content(self, topic: str) -> List[str]:
+        """Generate diagnostic approach content."""
+        
+        if "dimorphic fungi" in topic.lower():
+            return [
+                "Urine antigen testing: rapid, sensitive for Histoplasma",
+                "Serology: complement fixation, EIA antibodies (takes weeks)",
+                "Culture: gold standard but requires 2-6 weeks for growth",
+                "Histopathology: special stains (GMS, PAS) for tissue diagnosis",
+                "Molecular testing: PCR increasingly available",
+                "Imaging: chest CT for pulmonary nodules, lymphadenopathy"
+            ]
+        elif "pneumonia" in topic.lower():
+            return [
+                "Chest X-ray: first-line imaging for consolidation",
+                "Laboratory: CBC with differential, procalcitonin, blood cultures",
+                "Sputum culture: if good quality specimen available",
+                "Urinary antigens: pneumococcal and Legionella",
+                "Severity assessment: CURB-65, PSI scoring systems",
+                "Advanced imaging: chest CT if complicated or atypical"
+            ]
+        else:
+            return [
+                f"Laboratory tests for {topic}",
+                f"Imaging studies and interpretation",
+                f"Differential diagnosis considerations",
+                f"Confirmatory diagnostic procedures"
+            ]
+
+    def _generate_treatment_content(self, topic: str) -> List[str]:
+        """Generate treatment strategies content."""
+        
+        if "dimorphic fungi" in topic.lower():
+            return [
+                "Mild-moderate disease: Itraconazole 200 mg BID × 6-12 weeks",
+                "Severe disease: Amphotericin B 0.7-1.0 mg/kg/day × 1-2 weeks",
+                "Step-down therapy: Itraconazole after amphotericin stabilization",
+                "CNS disease: Amphotericin B × 4-6 weeks, then fluconazole",
+                "Duration: 6-12 months for pulmonary, 12-24 months for disseminated",
+                "Monitoring: drug levels, hepatic function, treatment response"
+            ]
+        elif "pneumonia" in topic.lower():
+            return [
+                "Outpatient CAP: Amoxicillin or macrolide monotherapy",
+                "Hospitalized CAP: Beta-lactam + macrolide or fluoroquinolone",
+                "Severe CAP: Broad-spectrum beta-lactam + macrolide",
+                "Duration: 5-7 days for most cases, longer if complications",
+                "Supportive care: oxygen, fluids, bronchodilators if needed",
+                "Prevention: pneumococcal and influenza vaccination"
+            ]
+        else:
+            return [
+                f"First-line treatment options for {topic}",
+                f"Alternative therapies and second-line agents",
+                f"Treatment duration and monitoring parameters",
+                f"Management of complications"
+            ]
+
+    def _generate_guidelines_content(self, topic: str) -> List[str]:
+        """Generate guidelines and evidence content."""
+        
+        if "dimorphic fungi" in topic.lower():
+            return [
+                "IDSA 2007 Guidelines for Endemic Mycoses (updated recommendations)",
+                "Treatment recommendations based on disease severity and location",
+                "Antifungal drug selection considers penetration and efficacy",
+                "Monitoring guidelines for drug toxicity and therapeutic response",
+                "Prevention strategies for high-risk populations",
+                "Quality indicators for optimal clinical outcomes"
+            ]
+        elif "pneumonia" in topic.lower():
+            return [
+                "IDSA/ATS 2019 Guidelines for Community-Acquired Pneumonia",
+                "Antimicrobial selection based on severity and risk factors",
+                "Biomarker-guided therapy duration (procalcitonin)",
+                "Quality measures: appropriate antibiotic selection and timing",
+                "Prevention: vaccination recommendations and smoking cessation",
+                "Stewardship: narrow-spectrum therapy when possible"
+            ]
+        else:
+            return [
+                f"Current clinical practice guidelines for {topic}",
+                f"Evidence-based recommendations and quality indicators",
+                f"Emerging research and future directions",
+                f"Implementation strategies in clinical practice"
+            ]
+
+    def _generate_case_application_content(self, topic: str) -> List[str]:
+        """Generate case application content."""
+        
+        if "dimorphic fungi" in topic.lower():
+            return [
+                "Case diagnosis: Acute pulmonary histoplasmosis",
+                "Rationale: Geographic exposure + clinical presentation + positive urine antigen",
+                "Treatment plan: Itraconazole 200 mg BID × 6-12 weeks",
+                "Monitoring: Clinical response, itraconazole levels, hepatic function",
+                "Patient education: Prognosis, medication adherence, follow-up",
+                "Prevention: Avoid high-risk activities in endemic areas"
+            ]
+        elif "pneumonia" in topic.lower():
+            return [
+                "Case diagnosis: Community-acquired pneumonia, moderate severity",
+                "CURB-65 score: 2 points (age > 65, confusion absent)",
+                "Treatment: Ceftriaxone 2g IV daily + azithromycin 500mg IV daily",
+                "Expected response: Clinical improvement within 48-72 hours",
+                "Discharge criteria: Stable vital signs, tolerating oral therapy",
+                "Follow-up: Chest X-ray in 6 weeks if high-risk patient"
+            ]
+        else:
+            return [
+                f"Application of diagnostic criteria for {topic}",
+                f"Treatment decision-making based on evidence",
+                f"Monitoring response and adjusting therapy",
+                f"Patient education and follow-up planning"
+            ]
+
+    def _generate_clinical_pearls_content(self, topic: str) -> List[str]:
+        """Generate clinical pearls content."""
+        
+        if "dimorphic fungi" in topic.lower():
+            return [
+                "Geographic history is crucial - ask about travel to endemic areas",
+                "Urine antigen testing provides rapid diagnosis for Histoplasma",
+                "Lymphopenia is characteristic of histoplasmosis vs. bacterial infections",
+                "Erythema nodosum suggests acute infection with good prognosis",
+                "Itraconazole levels should be checked after 2 weeks of therapy",
+                "Immunocompromised patients require longer, more intensive treatment"
+            ]
+        elif "pneumonia" in topic.lower():
+            return [
+                "Procalcitonin > 0.5 ng/mL suggests bacterial etiology",
+                "Positive urinary antigens guide targeted antibiotic therapy",
+                "CURB-65 score helps determine site of care (outpatient vs. hospital)",
+                "Atypical pathogens require macrolide or fluoroquinolone coverage",
+                "Clinical response expected within 48-72 hours of appropriate therapy",
+                "Chest X-ray may lag behind clinical improvement by several days"
+            ]
+        else:
+            return [
+                f"Key clinical insights for {topic}",
+                f"Common pitfalls to avoid in diagnosis",
+                f"Practical tips for optimal patient management",
+                f"Important prognostic factors to consider"
+            ]
+
+    def _generate_rapid_fire_content(self, topic: str) -> List[str]:
+        """Generate rapid fire questions content."""
+        
+        if "dimorphic fungi" in topic.lower():
+            return [
+                "Q: Which dimorphic fungus is associated with spelunking? A: Histoplasma",
+                "Q: What is the most sensitive test for histoplasmosis? A: Urine antigen",
+                "Q: Which form is pathogenic at body temperature? A: Yeast form",
+                "Q: What skin finding suggests acute coccidioidomycosis? A: Erythema nodosum",
+                "Q: First-line treatment for mild histoplasmosis? A: Itraconazole",
+                "Q: How long should treatment continue? A: 6-12 weeks for pulmonary disease"
+            ]
+        elif "pneumonia" in topic.lower():
+            return [
+                "Q: What is the most common cause of CAP? A: Streptococcus pneumoniae",
+                "Q: Which score predicts 30-day mortality? A: CURB-65 or PSI",
+                "Q: When should blood cultures be obtained? A: Before antibiotics in hospitalized patients",
+                "Q: First-line outpatient treatment for CAP? A: Amoxicillin or macrolide",
+                "Q: What biomarker helps guide antibiotic duration? A: Procalcitonin",
+                "Q: How soon should clinical improvement occur? A: Within 48-72 hours"
+            ]
+        else:
+            return [
+                f"Quick review questions about {topic}",
+                f"Key facts and figures to remember",
+                f"High-yield testing points",
+                f"Clinical scenarios for practice"
+            ]
+
+    def _generate_discussion_content(self, topic: str) -> List[str]:
+        """Generate discussion content."""
+        
+        return [
+            "Questions and answers session",
+            "Case-based discussion and clinical experiences",
+            "Challenging scenarios and problem-solving",
+            "Summary of key learning points",
+            "Resources for further learning",
+            "Contact information for follow-up questions"
+        ]
+
+    def _generate_generic_content(self, title: str, topic: str) -> List[str]:
+        """Generate generic content for unspecified slide types."""
+        
+        return [
+            f"Key concepts related to {title.lower()} in {topic}",
+            f"Clinical significance and practical applications",
+            f"Evidence-based approaches and recommendations",
+            f"Integration with current clinical practice"
+        ]
+
+    def _generate_speaker_notes(self, slides: List[Dict], research_report: str) -> Dict[str, str]:
+        """Generate detailed speaker notes for each slide."""
+        
+        speaker_notes = {}
+        
+        for slide in slides:
+            slide_number = slide["slide_number"]
+            title = slide["title"]
+            
+            # Generate specific speaker notes based on slide content
+            if "Title Slide" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Welcome the audience and introduce the topic.\n"
+                notes += "Mention the importance of understanding dimorphic fungi in clinical practice.\n"
+                notes += "Preview the learning objectives and interactive elements.\n"
+                notes += "Encourage questions throughout the presentation.\n"
+            elif "Learning Objectives" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Review each learning objective with the audience.\n"
+                notes += "Explain how these objectives relate to clinical practice.\n"
+                notes += "Ask: 'What is your current experience with diagnosing fungal infections?'\n"
+                notes += "Set expectations for active participation.\n"
+            elif "Case Vignette" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Present the case systematically, pausing for audience input.\n"
+                notes += "Ask: 'What additional history would you want to obtain?'\n"
+                notes += "Highlight key clinical clues that point to the diagnosis.\n"
+                notes += "Build suspense - we'll return to this case later.\n"
+            elif "Definition" in title or "Overview" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Explain the unique characteristics of dimorphic fungi.\n"
+                notes += "Use the temperature-dependent morphology as a key teaching point.\n"
+                notes += "Emphasize the geographic distribution and clinical significance.\n"
+                notes += "Ask: 'Which endemic areas are you familiar with?'\n"
+            elif "Pathophysiology" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Walk through the infection process step by step.\n"
+                notes += "Emphasize the importance of cell-mediated immunity.\n"
+                notes += "Explain why immunocompromised patients are at higher risk.\n"
+                notes += "Connect pathophysiology to clinical presentation.\n"
+            elif "Clinical Presentation" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Describe the spectrum of disease for each fungus.\n"
+                notes += "Highlight distinguishing features between organisms.\n"
+                notes += "Use clinical images if available to illustrate skin findings.\n"
+                notes += "Ask: 'What clinical clues help differentiate these infections?'\n"
+            elif "Diagnostic" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Discuss the pros and cons of each diagnostic method.\n"
+                notes += "Emphasize the rapid turnaround time of urine antigen testing.\n"
+                notes += "Explain when to use each test based on clinical scenario.\n"
+                notes += "Address common pitfalls in diagnosis.\n"
+            elif "Treatment" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Review IDSA guidelines for treatment recommendations.\n"
+                notes += "Explain rationale for drug selection and duration.\n"
+                notes += "Discuss monitoring parameters and side effects.\n"
+                notes += "Address when to consult infectious disease specialists.\n"
+            elif "Guidelines" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Highlight key recommendations from IDSA guidelines.\n"
+                notes += "Discuss recent updates and changes in recommendations.\n"
+                notes += "Emphasize evidence-based approach to treatment.\n"
+                notes += "Provide resources for accessing current guidelines.\n"
+            elif "Case Application" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Return to the opening case vignette.\n"
+                notes += "Walk through the diagnostic reasoning process.\n"
+                notes += "Explain treatment selection and monitoring plan.\n"
+                notes += "Ask: 'What would you do differently in this case?'\n"
+            elif "Clinical Pearls" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Emphasize practical tips for clinical practice.\n"
+                notes += "Share memorable mnemonics or decision aids.\n"
+                notes += "Highlight common mistakes to avoid.\n"
+                notes += "Encourage audience to share their own pearls.\n"
+            elif "Rapid Fire" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Engage the audience with quick questions.\n"
+                notes += "Encourage rapid responses to build confidence.\n"
+                notes += "Provide immediate feedback and explanations.\n"
+                notes += "Use this as a knowledge check before concluding.\n"
+            elif "Discussion" in title:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += "Open the floor for questions and discussion.\n"
+                notes += "Encourage sharing of clinical experiences.\n"
+                notes += "Address any remaining questions or concerns.\n"
+                notes += "Provide contact information and additional resources.\n"
+                notes += "Thank the audience for their participation.\n"
+            else:
+                notes = f"**Speaker Notes for Slide {slide_number}: {title}**\n\n"
+                notes += f"Key talking points for {title}.\n"
+                notes += "Connect to research findings and clinical evidence.\n"
+                notes += "Engage audience with relevant questions.\n"
+                notes += "Ensure smooth transition to next slide.\n"
+            
+            speaker_notes[str(slide_number)] = notes
+        
+        return speaker_notes
+
+    def _generate_presentation_metadata(self, topic: str, target_audience: str, duration: int, total_slides: int) -> Dict[str, Any]:
+        """Generate presentation metadata."""
+        
+        metadata = {
+            "topic": topic,
+            "target_audience": target_audience,
+            "duration_minutes": duration,
+            "total_slides": total_slides,
+            "created_date": "2025-07-18",
+            "presentation_type": "Educational",
+            "format": "PowerPoint/Slides",
+            "estimated_time_per_slide": duration / total_slides if total_slides > 0 else 3,
+            "learning_level": "Intermediate",
+            "prerequisites": f"Basic knowledge of {topic}",
+            "materials_needed": "Projector, handouts (optional)"
+        }
+        
+        return metadata

tools/explain_in_layman_language.py

@@ -0,0 +1,370 @@
+"""
+explain_in_layman_language.py
+-----------------------------
+
+Tool for explaining medical assessment and plans in patient-friendly language with educational resources.
+
+This tool takes complex medical terminology from assessments and plans and translates them into
+easy-to-understand language for patients. It also searches for reliable educational resources
+to help patients better understand their conditions and treatments.
+"""
+
+import asyncio
+from typing import Dict, List, Union, Any
+from tools.base import Tool
+from tools.utils import ToolExecutionError, logger
+from tools.internet_search import InternetSearchTool
+
+
+class ExplainInLaymanLanguageTool(Tool):
+    """
+    Tool for explaining medical assessments and plans in patient-friendly language.
+    
+    This tool:
+    1. Takes medical assessment and plan text
+    2. Translates complex medical terminology into layman terms
+    3. Searches for 2-3 reliable educational links on the topics
+    4. Provides a comprehensive patient-friendly explanation
+    """
+    
+    def __init__(self) -> None:
+        """Initialize the ExplainInLaymanLanguageTool."""
+        super().__init__()
+        self.name = "explain_in_layman_language"
+        self.description = "Explain medical assessment and plan in patient-friendly language with educational resources"
+        self.args_schema = {
+            "type": "object",
+            "properties": {
+                "assessment_and_plan": {
+                    "type": "string",
+                    "description": "The medical assessment and plan text to explain in layman terms"
+                },
+                "patient_context": {
+                    "type": "string",
+                    "description": "Additional context about the patient (age, relevant history, etc.)",
+                    "default": ""
+                }
+            },
+            "required": ["assessment_and_plan"]
+        }
+        
+        # Initialize internet search tool for finding educational resources
+        self.internet_search = InternetSearchTool()
+    
+    def openai_spec(self, legacy=False):
+        """Return OpenAI function specification for this tool."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.args_schema
+        }
+    
+    async def run(
+        self,
+        assessment_and_plan: str,
+        patient_context: str = ""
+    ) -> Dict[str, Any]:
+        """
+        Explain medical assessment and plan in layman language with educational resources.
+        
+        Args:
+            assessment_and_plan (str): The medical assessment and plan to explain
+            patient_context (str): Additional patient context
+            
+        Returns:
+            Dict[str, Any]: Patient-friendly explanation with educational resources
+        """
+        try:
+            logger.info(f"Explaining medical assessment in layman language")
+            
+            # Step 1: Extract key medical topics from the assessment and plan
+            key_topics = self._extract_medical_topics(assessment_and_plan)
+            
+            # Step 2: Create patient-friendly explanation
+            layman_explanation = self._create_layman_explanation(
+                assessment_and_plan, 
+                patient_context, 
+                key_topics
+            )
+            
+            # Step 3: Search for educational resources
+            educational_links = await self._find_educational_resources(key_topics)
+            
+            # Step 4: Combine everything into a comprehensive response
+            result = {
+                "layman_explanation": layman_explanation,
+                "educational_resources": educational_links,
+                "key_topics_covered": key_topics,
+                "patient_context": patient_context
+            }
+            
+            logger.info(f"Successfully created layman explanation with {len(educational_links)} educational resources")
+            return result
+            
+        except Exception as e:
+            logger.error(f"ExplainInLaymanLanguageTool failed: {e}", exc_info=True)
+            raise ToolExecutionError(f"Failed to explain assessment in layman language: {e}")
+    
+    def _extract_medical_topics(self, assessment_and_plan: str) -> List[str]:
+        """Extract key medical topics from the assessment and plan."""
+        # Common medical terms and their categories
+        medical_terms = {
+            # Infections
+            "pneumonia": "lung infection",
+            "sepsis": "blood infection",
+            "cellulitis": "skin infection",
+            "uti": "urinary tract infection",
+            "urinary tract infection": "urinary tract infection",
+            "meningitis": "brain infection",
+            "endocarditis": "heart infection",
+            
+            # Antibiotics
+            "antibiotic": "antibiotic treatment",
+            "vancomycin": "antibiotic treatment",
+            "ceftriaxone": "antibiotic treatment",
+            "azithromycin": "antibiotic treatment",
+            "levofloxacin": "antibiotic treatment",
+            "piperacillin": "antibiotic treatment",
+            "meropenem": "antibiotic treatment",
+            
+            # Conditions
+            "diabetes": "diabetes",
+            "hypertension": "high blood pressure",
+            "copd": "chronic lung disease",
+            "asthma": "asthma",
+            "heart failure": "heart failure",
+            "kidney disease": "kidney disease",
+            "liver disease": "liver disease",
+            
+            # Procedures
+            "blood culture": "blood tests",
+            "chest x-ray": "chest imaging",
+            "ct scan": "CT scan",
+            "mri": "MRI scan",
+            "lumbar puncture": "spinal fluid test",
+            "biopsy": "tissue sample",
+            
+            # Symptoms
+            "fever": "fever",
+            "shortness of breath": "breathing difficulty",
+            "chest pain": "chest pain",
+            "abdominal pain": "stomach pain",
+            "nausea": "nausea",
+            "vomiting": "vomiting",
+            "diarrhea": "diarrhea"
+        }
+        
+        topics = []
+        assessment_lower = assessment_and_plan.lower()
+        
+        for term, category in medical_terms.items():
+            if term in assessment_lower:
+                if category not in topics:
+                    topics.append(category)
+        
+        # If no specific topics found, extract general categories
+        if not topics:
+            if "infection" in assessment_lower:
+                topics.append("infection")
+            if "antibiotic" in assessment_lower:
+                topics.append("antibiotic treatment")
+            if "treatment" in assessment_lower:
+                topics.append("treatment")
+        
+        return topics[:5]  # Limit to top 5 topics
+    
+    def _create_layman_explanation(
+        self, 
+        assessment_and_plan: str, 
+        patient_context: str, 
+        key_topics: List[str]
+    ) -> str:
+        """Create a patient-friendly explanation of the assessment and plan."""
+        
+        # Medical terminology translations
+        translations = {
+            # Infections
+            "pneumonia": "a lung infection",
+            "sepsis": "a serious blood infection",
+            "bacteremia": "bacteria in the blood",
+            "cellulitis": "a skin and soft tissue infection",
+            "uti": "a urinary tract infection (bladder infection)",
+            "urinary tract infection": "a bladder infection",
+            "pyelonephritis": "a kidney infection",
+            "meningitis": "an infection of the brain and spinal cord lining",
+            "endocarditis": "an infection of the heart valves",
+            
+            # Antibiotics
+            "vancomycin": "a strong antibiotic medication",
+            "ceftriaxone": "an antibiotic medication",
+            "azithromycin": "an antibiotic medication (Z-pack)",
+            "levofloxacin": "an antibiotic medication",
+            "piperacillin-tazobactam": "a combination antibiotic medication",
+            "meropenem": "a powerful antibiotic medication",
+            "clindamycin": "an antibiotic medication",
+            
+            # Medical procedures
+            "blood culture": "blood tests to check for bacteria",
+            "chest x-ray": "a picture of your lungs",
+            "ct scan": "a detailed scan using X-rays",
+            "mri": "a detailed scan using magnets",
+            "lumbar puncture": "a procedure to test spinal fluid",
+            "biopsy": "taking a small sample of tissue for testing",
+            
+            # Conditions
+            "copd": "chronic obstructive pulmonary disease (long-term lung condition)",
+            "chf": "congestive heart failure (heart not pumping well)",
+            "dm": "diabetes mellitus (diabetes)",
+            "htn": "hypertension (high blood pressure)",
+            "ckd": "chronic kidney disease (long-term kidney problems)",
+            
+            # Symptoms
+            "dyspnea": "shortness of breath",
+            "tachycardia": "fast heart rate",
+            "hypotension": "low blood pressure",
+            "hypertension": "high blood pressure",
+            "pyrexia": "fever",
+            "malaise": "feeling unwell",
+            "lethargy": "extreme tiredness"
+        }
+        
+        # Start with a friendly introduction
+        explanation = "Here's what your medical team has found and what the plan is, explained in simple terms:\n\n"
+        
+        # Add patient context if provided
+        if patient_context:
+            explanation += f"**About You:** {patient_context}\n\n"
+        
+        # Process the assessment and plan
+        explanation += "**What's Happening:**\n"
+        
+        # Simple word replacement for common medical terms
+        simplified_text = assessment_and_plan.lower()
+        for medical_term, layman_term in translations.items():
+            simplified_text = simplified_text.replace(medical_term, layman_term)
+        
+        # Add the simplified explanation
+        explanation += simplified_text.capitalize() + "\n\n"
+        
+        # Add key points section
+        if key_topics:
+            explanation += "**Key Points to Remember:**\n"
+            for topic in key_topics:
+                explanation += f"• {topic.capitalize()}\n"
+            explanation += "\n"
+        
+        # Add encouragement and next steps
+        explanation += "**What This Means for You:**\n"
+        explanation += "Your medical team is working to give you the best care possible. "
+        explanation += "It's important to follow the treatment plan and ask questions if anything is unclear. "
+        explanation += "Your health and understanding are our top priorities.\n\n"
+        
+        return explanation
+    
+    async def _find_educational_resources(self, key_topics: List[str]) -> List[Dict[str, str]]:
+        """Find 2-3 reliable educational resources about the key topics."""
+        educational_links = []
+        
+        # Trusted medical education websites
+        trusted_sites = [
+            "mayoclinic.org",
+            "webmd.com",
+            "healthline.com",
+            "medlineplus.gov",
+            "cdc.gov",
+            "nih.gov",
+            "patient.info"
+        ]
+        
+        try:
+            # Search for educational resources for each topic
+            for topic in key_topics[:3]:  # Limit to 3 topics
+                search_queries = [
+                    f"{topic} patient education site:mayoclinic.org",
+                    f"{topic} patient information site:medlineplus.gov",
+                    f"what is {topic} patient guide site:healthline.com"
+                ]
+                
+                for query in search_queries:
+                    try:
+                        search_results = await self.internet_search.run(q=query, max_results=3)
+                        
+                        # Parse the search results string to extract links
+                        if search_results and isinstance(search_results, str):
+                            # Extract links from the formatted string response
+                            import re
+                            # Pattern to match [Read more](url) links
+                            link_pattern = r'\[Read more\]\(([^)]+)\)'
+                            title_pattern = r'\*\*([^*]+)\*\*'
+                            
+                            links = re.findall(link_pattern, search_results)
+                            titles = re.findall(title_pattern, search_results)
+                            
+                            # Match titles with links
+                            for i, (title, link) in enumerate(zip(titles, links)):
+                                if any(site in link.lower() for site in trusted_sites):
+                                    educational_links.append({
+                                        "title": title,
+                                        "url": link,
+                                        "topic": topic,
+                                        "description": f"Learn more about {topic}"
+                                    })
+                                    break  # Found a good link for this topic
+                        
+                        if len(educational_links) >= 3:
+                            break
+                            
+                    except Exception as e:
+                        logger.warning(f"Failed to search for {topic}: {e}")
+                        continue
+                
+                if len(educational_links) >= 3:
+                    break
+            
+            # If we don't have enough links, add some general reliable resources
+            if len(educational_links) < 2:
+                general_resources = [
+                    {
+                        "title": "MedlinePlus Health Information",
+                        "url": "https://medlineplus.gov/",
+                        "topic": "general health",
+                        "description": "Reliable health information from the National Library of Medicine"
+                    },
+                    {
+                        "title": "Mayo Clinic Patient Education",
+                        "url": "https://www.mayoclinic.org/patient-visitor-guide/patient-education",
+                        "topic": "general health",
+                        "description": "Comprehensive patient education resources from Mayo Clinic"
+                    },
+                    {
+                        "title": "CDC Health Information",
+                        "url": "https://www.cdc.gov/healthypeople/",
+                        "topic": "general health",
+                        "description": "Health information and resources from the CDC"
+                    }
+                ]
+                
+                # Add general resources to reach at least 2-3 links
+                for resource in general_resources:
+                    if len(educational_links) < 3:
+                        educational_links.append(resource)
+            
+        except Exception as e:
+            logger.warning(f"Failed to find educational resources: {e}")
+            # Provide fallback resources
+            educational_links = [
+                {
+                    "title": "MedlinePlus - Easy-to-Read Health Information",
+                    "url": "https://medlineplus.gov/",
+                    "topic": "general health",
+                    "description": "Trusted health information from the National Library of Medicine"
+                },
+                {
+                    "title": "Mayo Clinic - Patient Education",
+                    "url": "https://www.mayoclinic.org/diseases-conditions",
+                    "topic": "general health",
+                    "description": "Comprehensive information about diseases and conditions"
+                }
+            ]
+        
+        return educational_links[:3]  # Return maximum 3 links

tools/fhir_patient.py

@@ -0,0 +1,50 @@
+from tools.base import Tool
+
+
+from tools.utils import ToolExecutionError, logger
+from typing import Any, Dict
+
+class FHIRPatientTool(Tool):
+
+    def openai_spec(self, legacy=False):
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.args_schema
+        }
+    """
+    Tool to fetch synthetic patient labs and vitals from a FHIR server by patient ID.
+
+    This tool queries a FHIR API for a given patient ID and returns labs and vitals (placeholder implementation).
+    """
+    def __init__(self) -> None:
+        """
+        Initialize the FHIRPatientTool with its name, description, and argument schema.
+        """
+        super().__init__()
+        self.name = "synthetic_patient_lookup"
+        self.description = "Fetch synthetic patient labs / vitals from FHIR by patient_id."
+        self.args_schema = {
+            "type": "object",
+            "properties": {
+                "patient_id": {"type": "string", "description": "Patient ID to query"}
+            },
+            "required": ["patient_id"]
+        }
+
+    async def run(self, patient_id: str) -> Dict[str, Any]:
+        """
+        Fetch synthetic patient labs and vitals for a given patient ID.
+
+        Args:
+            patient_id (str): The patient ID to query.
+
+        Returns:
+            Dict[str, Any]: The patient data (placeholder).
+        """
+        try:
+            # Placeholder for actual FHIR API call
+            return {"patient_id": patient_id, "labs": [], "vitals": []}
+        except Exception as e:
+            logger.error(f"FHIRPatientTool failed: {e}", exc_info=True)
+            raise ToolExecutionError(f"FHIRPatientTool failed: {e}")

tools/format_references.py

@@ -0,0 +1,423 @@
+"""
+Format References Tool
+Smart reference formatting for any journal's requirements
+"""
+
+import json
+import re
+import requests
+import os
+from tools.base import Tool
+
+
+class FormatReferencesTool(Tool):
+    """
+    Smart reference formatting tool that can format references according to any journal's specific requirements.
+    Asks for the target journal, looks up formatting instructions, and applies them to user-provided references.
+    """
+    
+    def __init__(self):
+        super().__init__()
+    
+    def execute(self, references_text, target_journal=None, max_length=2000):
+        """
+        Format references according to target journal requirements.
+        
+        Args:
+            references_text (str): Raw references to format
+            target_journal (str, optional): Target journal name
+            max_length (int): Maximum response length
+            
+        Returns:
+            dict: Formatted references and formatting guidelines
+        """
+        try:
+            # Step 1: If no journal specified, ask for it
+            if not target_journal or not target_journal.strip():
+                return {
+                    "status": "journal_required",
+                    "message": "Please specify the target journal for reference formatting. For example: 'Clinical Infectious Diseases', 'The Lancet', 'Nature Medicine', etc.",
+                    "formatted_references": "",
+                    "formatting_guidelines": ""
+                }
+            
+            # Step 2: Clean and validate input references
+            if not references_text or not references_text.strip():
+                return {
+                    "status": "references_required",
+                    "message": "Please provide the references you'd like to format.",
+                    "formatted_references": "",
+                    "formatting_guidelines": ""
+                }
+            
+            # Step 3: Search for journal-specific formatting guidelines
+            formatting_guidelines = self._get_journal_formatting_guidelines(target_journal)
+            
+            # Step 4: Parse input references
+            parsed_references = self._parse_references(references_text)
+            
+            # Step 5: Apply journal-specific formatting
+            formatted_references = self._apply_journal_formatting(
+                parsed_references, 
+                target_journal, 
+                formatting_guidelines
+            )
+            
+            # Step 6: Prepare response
+            response = {
+                "status": "success",
+                "journal": target_journal,
+                "formatted_references": formatted_references,
+                "formatting_guidelines": formatting_guidelines,
+                "reference_count": len(parsed_references),
+                "message": f"Successfully formatted {len(parsed_references)} references for {target_journal}"
+            }
+            
+            # Trim response if too long
+            response_str = json.dumps(response)
+            if len(response_str) > max_length:
+                # Truncate formatted references if needed
+                available_space = max_length - len(json.dumps({**response, "formatted_references": ""}))
+                if available_space > 100:
+                    response["formatted_references"] = response["formatted_references"][:available_space-50] + "...[truncated]"
+            
+            return response
+            
+        except Exception as e:
+            return {
+                "status": "error",
+                "message": f"Error formatting references: {str(e)}",
+                "formatted_references": "",
+                "formatting_guidelines": ""
+            }
+    
+    def _get_journal_formatting_guidelines(self, journal_name):
+        """Search for journal-specific reference formatting guidelines"""
+        try:
+            # Search for journal reference formatting guidelines
+            search_queries = [
+                f"{journal_name} reference format guidelines",
+                f"{journal_name} citation style requirements",
+                f"{journal_name} author guidelines references",
+                f"how to format references for {journal_name}"
+            ]
+            
+            guidelines = ""
+            for query in search_queries:
+                try:
+                    # Use a simple synchronous approach with requests for now
+                    import requests
+                    import os
+                    
+                    print(f"Searching for: {query}")  # Debug
+                    
+                    # Use Serper API directly
+                    api_key = os.getenv("SERPER_API_KEY")
+                    if api_key:
+                        payload = {"q": query, "num": 3}
+                        headers = {"X-API-KEY": api_key, "Content-Type": "application/json"}
+                        resp = requests.post("https://google.serper.dev/search", 
+                                           json=payload, headers=headers, timeout=5)
+                        print(f"Search response status: {resp.status_code}")  # Debug
+                        
+                        if resp.status_code == 200:
+                            results = resp.json().get("organic", [])
+                            print(f"Found {len(results)} results")  # Debug
+                            
+                            for result in results:
+                                snippet = result.get("snippet", "")
+                                title = result.get("title", "")
+                                content = f"{title} {snippet}"
+                                if self._contains_formatting_info(content, journal_name):
+                                    guidelines += content + "\n\n"
+                                    print(f"Found relevant guidelines")  # Debug
+                                    break
+                    if guidelines:
+                        break
+                except Exception:
+                    continue
+            
+            if not guidelines:
+                guidelines = self._get_fallback_guidelines(journal_name)
+            
+            return guidelines[:1500]  # Limit length
+            
+        except Exception as e:
+            return f"Error retrieving guidelines: {str(e)}"
+    
+    def _contains_formatting_info(self, content, journal_name):
+        """Check if content contains relevant formatting information"""
+        keywords = [
+            "reference", "citation", "format", "style", "bibliography",
+            "author", "title", "journal", "volume", "page", "doi",
+            "vancouver", "ama", "chicago", "harvard", "numbered"
+        ]
+        
+        content_lower = content.lower()
+        journal_lower = journal_name.lower()
+        
+        # Must contain journal name and at least 3 formatting keywords
+        return (journal_lower in content_lower and 
+                sum(1 for keyword in keywords if keyword in content_lower) >= 3)
+    
+    def _parse_references(self, references_text):
+        """Parse input references into structured format"""
+        # Split references by common delimiters
+        references = []
+        
+        # Split by numbered patterns (1., 2., etc.) or line breaks
+        ref_parts = re.split(r'\n+|\d+\.\s+', references_text.strip())
+        ref_parts = [part.strip() for part in ref_parts if part.strip()]
+        
+        for i, ref_text in enumerate(ref_parts, 1):
+            parsed_ref = self._extract_reference_components(ref_text)
+            parsed_ref["original"] = ref_text
+            parsed_ref["number"] = str(i)
+            references.append(parsed_ref)
+        
+        return references
+    
+    def _extract_reference_components(self, ref_text):
+        """Extract components from a single reference"""
+        components = {
+            "authors": "",
+            "title": "",
+            "journal": "",
+            "year": "",
+            "volume": "",
+            "issue": "",
+            "pages": "",
+            "doi": "",
+            "pmid": "",
+            "url": ""
+        }
+        
+        # Extract DOI
+        doi_match = re.search(r'doi:\s*([^\s,;]+)', ref_text, re.IGNORECASE)
+        if doi_match:
+            components["doi"] = doi_match.group(1)
+        
+        # Extract PMID
+        pmid_match = re.search(r'pmid:\s*(\d+)', ref_text, re.IGNORECASE)
+        if pmid_match:
+            components["pmid"] = pmid_match.group(1)
+        
+        # Extract year (4 digits)
+        year_match = re.search(r'\b(19|20)\d{2}\b', ref_text)
+        if year_match:
+            components["year"] = year_match.group(0)
+        
+        # Extract volume and pages pattern like "2023;45(3):123-130"
+        vol_pages_match = re.search(r'(\d+)\((\d+)\):(\d+[-–]\d+)', ref_text)
+        if vol_pages_match:
+            components["volume"] = vol_pages_match.group(1)
+            components["issue"] = vol_pages_match.group(2)
+            components["pages"] = vol_pages_match.group(3)
+        
+        # Extract URL
+        url_match = re.search(r'https?://[^\s,;]+', ref_text)
+        if url_match:
+            components["url"] = url_match.group(0)
+        
+        # Simple author extraction (everything before first period if present)
+        if '.' in ref_text:
+            potential_authors = ref_text.split('.')[0]
+            if len(potential_authors) < 100:  # Reasonable author length
+                components["authors"] = potential_authors.strip()
+        
+        return components
+    
+    def _apply_journal_formatting(self, references, journal_name, guidelines):
+        """Apply journal-specific formatting to references"""
+        formatted_refs = []
+        
+        # Determine formatting style based on journal and guidelines
+        style = self._determine_formatting_style(journal_name, guidelines)
+        
+        for ref in references:
+            if style == "vancouver":
+                formatted_ref = self._format_vancouver_style(ref)
+            elif style == "ama":
+                formatted_ref = self._format_ama_style(ref)
+            elif style == "chicago":
+                formatted_ref = self._format_chicago_style(ref)
+            else:
+                formatted_ref = self._format_generic_style(ref)
+            
+            formatted_refs.append(f"{ref['number']}. {formatted_ref}")
+        
+        return "\n\n".join(formatted_refs)
+    
+    def _determine_formatting_style(self, journal_name, guidelines):
+        """Determine the appropriate formatting style for the journal"""
+        journal_lower = journal_name.lower()
+        guidelines_lower = guidelines.lower()
+        
+        # Medical journals often use Vancouver or AMA
+        medical_journals = [
+            "clinical infectious diseases", "journal of infectious diseases",
+            "the lancet", "new england journal of medicine", "jama",
+            "nature medicine", "bmj", "plos"
+        ]
+        
+        if any(j in journal_lower for j in medical_journals):
+            if "vancouver" in guidelines_lower:
+                return "vancouver"
+            elif "ama" in guidelines_lower:
+                return "ama"
+            else:
+                return "vancouver"  # Default for medical journals
+        
+        # Check guidelines for specific style mentions
+        if "vancouver" in guidelines_lower:
+            return "vancouver"
+        elif "ama" in guidelines_lower:
+            return "ama"
+        elif "chicago" in guidelines_lower:
+            return "chicago"
+        
+        return "generic"
+    
+    def _format_vancouver_style(self, ref):
+        """Format reference in Vancouver style"""
+        parts = []
+        
+        if ref["authors"]:
+            # Format authors (last name, first initial)
+            authors = self._format_authors_vancouver(ref["authors"])
+            parts.append(authors)
+        
+        if ref["title"]:
+            title = ref["title"].strip().rstrip('.')
+            parts.append(title + ".")
+        
+        if ref["journal"]:
+            journal_part = ref["journal"]
+            if ref["year"]:
+                journal_part += f" {ref['year']}"
+            if ref["volume"]:
+                journal_part += f";{ref['volume']}"
+                if ref["issue"]:
+                    journal_part += f"({ref['issue']})"
+            if ref["pages"]:
+                journal_part += f":{ref['pages']}"
+            parts.append(journal_part + ".")
+        
+        if ref["doi"]:
+            parts.append(f"doi:{ref['doi']}")
+        
+        return " ".join(parts)
+    
+    def _format_ama_style(self, ref):
+        """Format reference in AMA style"""
+        parts = []
+        
+        if ref["authors"]:
+            authors = self._format_authors_ama(ref["authors"])
+            parts.append(authors)
+        
+        if ref["title"]:
+            title = ref["title"].strip().rstrip('.')
+            parts.append(title + ".")
+        
+        if ref["journal"]:
+            journal_part = f"{ref['journal']}."
+            if ref["year"] and ref["volume"]:
+                journal_part += f" {ref['year']};{ref['volume']}"
+                if ref["issue"]:
+                    journal_part += f"({ref['issue']})"
+            if ref["pages"]:
+                journal_part += f":{ref['pages']}"
+            parts.append(journal_part)
+        
+        if ref["doi"]:
+            parts.append(f"doi:{ref['doi']}")
+        
+        return " ".join(parts)
+    
+    def _format_chicago_style(self, ref):
+        """Format reference in Chicago style"""
+        parts = []
+        
+        if ref["authors"]:
+            authors = self._format_authors_chicago(ref["authors"])
+            parts.append(authors)
+        
+        if ref["title"]:
+            title = f'"{ref["title"].strip().rstrip(".")}"'
+            parts.append(title)
+        
+        if ref["journal"]:
+            journal_part = ref["journal"]
+            if ref["volume"]:
+                journal_part += f" {ref['volume']}"
+                if ref["issue"]:
+                    journal_part += f", no. {ref['issue']}"
+            if ref["year"]:
+                journal_part += f" ({ref['year']})"
+            if ref["pages"]:
+                journal_part += f": {ref['pages']}"
+            parts.append(journal_part + ".")
+        
+        return " ".join(parts)
+    
+    def _format_generic_style(self, ref):
+        """Format reference in generic academic style"""
+        return self._format_vancouver_style(ref)  # Default to Vancouver
+    
+    def _format_authors_vancouver(self, authors_str):
+        """Format authors in Vancouver style"""
+        # Simple formatting - could be enhanced
+        if "," in authors_str:
+            return authors_str.strip().rstrip('.') + "."
+        return authors_str.strip() + "."
+    
+    def _format_authors_ama(self, authors_str):
+        """Format authors in AMA style"""
+        return self._format_authors_vancouver(authors_str)
+    
+    def _format_authors_chicago(self, authors_str):
+        """Format authors in Chicago style"""
+        return authors_str.strip().rstrip('.') + "."
+    
+    def _get_fallback_guidelines(self, journal_name):
+        """Provide fallback formatting guidelines when internet search fails"""
+        journal_lower = journal_name.lower()
+        
+        # Known guidelines for major medical journals
+        known_guidelines = {
+            "clinical infectious diseases": "Uses numbered Vancouver style: Author(s). Title. Journal Name. Year;Volume(Issue):Pages. doi:xxx",
+            "the lancet": "Uses numbered references in Vancouver style with specific formatting requirements", 
+            "nature medicine": "Uses numbered references with Nature style formatting",
+            "jama": "Uses AMA style numbered references with author-year format",
+            "new england journal of medicine": "Uses numbered Vancouver style references",
+            "plos one": "Uses numbered references with specific PLOS formatting requirements",
+            "infection control": "Uses Vancouver style for infection control journals",
+            "antimicrobial": "Uses medical journal Vancouver style formatting"
+        }
+        
+        # Check for exact or partial matches
+        for known_journal, guideline in known_guidelines.items():
+            if known_journal in journal_lower:
+                return f"Formatting guidelines for {journal_name}: {guideline}"
+        
+        # Generic medical journal guidelines
+        return f"Standard medical journal formatting for {journal_name}: Uses numbered Vancouver style references with Author(s). Title. Journal Name. Year;Volume(Issue):Pages. doi:xxx format."
+
+
+# Tool metadata
+TOOL_METADATA = {
+    "name": "format_references",
+    "description": "Smart reference formatting tool that formats citations according to any journal's specific requirements",
+    "parameters": {
+        "references_text": {
+            "type": "string",
+            "description": "The references to format (can be in any format)"
+        },
+        "target_journal": {
+            "type": "string", 
+            "description": "The target journal name (e.g., 'Clinical Infectious Diseases', 'Nature Medicine')"
+        }
+    },
+    "category": "research"
+}

tools/generate_flash_cards.py

@@ -0,0 +1,324 @@
+"""
+generate_flash_cards.py
+-----------------------
+
+Tool for generating educational flash cards for medical topics.
+
+This tool creates flash card style educational content to help with memorization and
+quick review of key medical concepts, facts, and clinical pearls.
+
+Key Features:
+- Creates front/back flash card format
+- Generates multiple cards per topic
+- Includes mnemonics and memory aids
+- Covers key facts, clinical pearls, and high-yield information
+- Organizes cards by difficulty and subtopic
+"""
+
+import asyncio
+from typing import Any, Dict, List, Union
+from tools.base import Tool
+from tools.utils import ToolExecutionError, logger
+
+class GenerateFlashCardsTool(Tool):
+    """
+    Tool for generating educational flash cards for medical topics.
+    
+    This tool creates flash card style educational content to help with memorization
+    and quick review of key medical concepts.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize the GenerateFlashCardsTool."""
+        super().__init__()
+        self.name = "generate_flash_cards"
+        self.description = "Generate educational flash cards for medical topics to aid memorization and quick review."
+        self.args_schema = {
+            "type": "object",
+            "properties": {
+                "topic": {
+                    "type": "string", 
+                    "description": "The medical topic to create flash cards about (e.g., 'hypertension', 'diabetes medications', 'heart murmurs')"
+                },
+                "number_of_cards": {
+                    "type": "integer", 
+                    "description": "Number of flash cards to generate (default: 10)",
+                    "default": 10,
+                    "minimum": 5,
+                    "maximum": 20
+                },
+                "card_type": {
+                    "type": "string", 
+                    "description": "Type of flash cards to generate",
+                    "enum": ["basic_facts", "clinical_pearls", "mnemonics", "differential_diagnosis", "medications", "mixed"],
+                    "default": "mixed"
+                },
+                "difficulty_level": {
+                    "type": "string", 
+                    "description": "Difficulty level for the cards",
+                    "enum": ["medical_student", "resident", "board_review", "advanced"],
+                    "default": "medical_student"
+                }
+            },
+            "required": ["topic"]
+        }
+
+    def openai_spec(self, legacy=False):
+        """Return OpenAI function specification."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.args_schema
+        }
+
+    async def run(
+        self,
+        topic: str,
+        number_of_cards: int = 10,
+        card_type: str = "mixed",
+        difficulty_level: str = "medical_student"
+    ) -> Dict[str, Any]:
+        """
+        Generate educational flash cards for a medical topic.
+        
+        Args:
+            topic (str): The medical topic to create flash cards about
+            number_of_cards (int): Number of flash cards to generate
+            card_type (str): Type of flash cards (basic_facts, clinical_pearls, mnemonics, etc.)
+            difficulty_level (str): Difficulty level for the cards
+            
+        Returns:
+            Dict[str, Any]: Complete flash card set with organized cards
+        """
+        try:
+            logger.info(f"Generating {number_of_cards} flash cards for topic: {topic}")
+            
+            # Generate flash cards
+            flash_cards = self._generate_flash_cards(topic, number_of_cards, card_type, difficulty_level)
+            
+            # Organize cards by subtopic
+            organized_cards = self._organize_cards_by_subtopic(flash_cards, topic)
+            
+            # Generate study tips and usage instructions
+            study_tips = self._generate_study_tips(topic, card_type)
+            
+            # Create the complete flash card set
+            flash_card_set = {
+                "topic": topic,
+                "card_type": card_type,
+                "difficulty_level": difficulty_level,
+                "total_cards": len(flash_cards),
+                "flash_cards": flash_cards,
+                "organized_by_subtopic": organized_cards,
+                "study_tips": study_tips,
+                "review_schedule": self._generate_review_schedule(),
+                "created_date": "2025-07-18"
+            }
+            
+            logger.info(f"Successfully generated {len(flash_cards)} flash cards for {topic}")
+            return flash_card_set
+            
+        except Exception as e:
+            logger.error(f"GenerateFlashCardsTool failed: {e}", exc_info=True)
+            raise ToolExecutionError(f"Failed to generate flash cards: {e}")
+
+    def _generate_flash_cards(self, topic: str, number_of_cards: int, card_type: str, difficulty_level: str) -> List[Dict[str, Any]]:
+        """Generate individual flash cards."""
+        
+        flash_cards = []
+        
+        # Define card templates based on topic and type
+        card_templates = self._get_card_templates(topic, card_type, difficulty_level)
+        
+        # Generate cards using templates
+        for i in range(number_of_cards):
+            if i < len(card_templates):
+                card = card_templates[i]
+            else:
+                # Generate additional cards if needed
+                card = self._generate_additional_card(topic, card_type, difficulty_level, i)
+            
+            flash_cards.append(card)
+        
+        return flash_cards
+
+    def _get_card_templates(self, topic: str, card_type: str, difficulty_level: str) -> List[Dict[str, Any]]:
+        """Get predefined card templates for common topics."""
+        
+        templates = {
+            "hypertension": [
+                {
+                    "card_id": 1,
+                    "subtopic": "Definition",
+                    "front": "What is the definition of hypertension?",
+                    "back": "Blood pressure ≥140/90 mmHg on two separate occasions, or ≥130/80 mmHg for patients with diabetes or chronic kidney disease.",
+                    "memory_aid": "Remember: 140/90 for general population, 130/80 for high-risk groups",
+                    "difficulty": "basic"
+                },
+                {
+                    "card_id": 2,
+                    "subtopic": "Classification",
+                    "front": "What are the stages of hypertension according to AHA/ACC guidelines?",
+                    "back": "Normal: <120/80\nElevated: 120-129/<80\nStage 1: 130-139/80-89\nStage 2: ≥140/90\nCrisis: >180/120",
+                    "memory_aid": "Mnemonic: Never Ever Stop Managing Crises (Normal, Elevated, Stage 1, Stage 2, Crisis)",
+                    "difficulty": "basic"
+                },
+                {
+                    "card_id": 3,
+                    "subtopic": "First-line medications",
+                    "front": "What are the first-line medications for hypertension?",
+                    "back": "ACE inhibitors, ARBs, Calcium channel blockers, Thiazide diuretics",
+                    "memory_aid": "Mnemonic: ACCT (ACE, ARB, CCB, Thiazide) - ACCounT for first-line HTN meds",
+                    "difficulty": "basic"
+                },
+                {
+                    "card_id": 4,
+                    "subtopic": "Complications",
+                    "front": "What are the major complications of untreated hypertension?",
+                    "back": "Stroke, Heart attack, Heart failure, Kidney disease, Vision loss, Peripheral artery disease",
+                    "memory_aid": "Mnemonic: SHOCKS (Stroke, Heart attack, Heart failure, Kidney disease, Vision loss, PAD)",
+                    "difficulty": "intermediate"
+                }
+            ],
+            "diabetes": [
+                {
+                    "card_id": 1,
+                    "subtopic": "Diagnosis",
+                    "front": "What are the diagnostic criteria for diabetes mellitus?",
+                    "back": "Fasting glucose ≥126 mg/dL OR Random glucose ≥200 mg/dL + symptoms OR HbA1c ≥6.5% OR 2-hour OGTT ≥200 mg/dL",
+                    "memory_aid": "Remember: 126 fasting, 200 random, 6.5% A1c, 200 OGTT",
+                    "difficulty": "basic"
+                },
+                {
+                    "card_id": 2,
+                    "subtopic": "HbA1c targets",
+                    "front": "What is the HbA1c target for most adults with diabetes?",
+                    "back": "<7% for most adults. <6.5% for selected patients if achievable without hypoglycemia. <8% for patients with limited life expectancy or high risk of hypoglycemia.",
+                    "memory_aid": "Lucky 7: <7% for most, adjust based on individual factors",
+                    "difficulty": "basic"
+                }
+            ]
+        }
+        
+        # Return templates for the topic or generate generic ones
+        if topic.lower() in templates:
+            return templates[topic.lower()]
+        else:
+            return self._generate_generic_templates(topic, card_type, difficulty_level)
+
+    def _generate_generic_templates(self, topic: str, card_type: str, difficulty_level: str) -> List[Dict[str, Any]]:
+        """Generate generic card templates for any topic."""
+        
+        generic_templates = [
+            {
+                "card_id": 1,
+                "subtopic": "Definition",
+                "front": f"What is {topic}?",
+                "back": f"[Definition and key characteristics of {topic}]",
+                "memory_aid": f"Key concept: {topic}",
+                "difficulty": "basic"
+            },
+            {
+                "card_id": 2,
+                "subtopic": "Clinical Presentation",
+                "front": f"What are the main signs and symptoms of {topic}?",
+                "back": f"[List of key clinical features of {topic}]",
+                "memory_aid": f"Clinical pearl for {topic}",
+                "difficulty": "basic"
+            },
+            {
+                "card_id": 3,
+                "subtopic": "Diagnosis",
+                "front": f"How is {topic} diagnosed?",
+                "back": f"[Diagnostic criteria and tests for {topic}]",
+                "memory_aid": f"Diagnostic approach for {topic}",
+                "difficulty": "intermediate"
+            },
+            {
+                "card_id": 4,
+                "subtopic": "Treatment",
+                "front": f"What is the treatment for {topic}?",
+                "back": f"[Treatment options and management for {topic}]",
+                "memory_aid": f"Treatment strategy for {topic}",
+                "difficulty": "intermediate"
+            },
+            {
+                "card_id": 5,
+                "subtopic": "Complications",
+                "front": f"What are the complications of {topic}?",
+                "back": f"[Potential complications and monitoring for {topic}]",
+                "memory_aid": f"Watch for complications of {topic}",
+                "difficulty": "advanced"
+            }
+        ]
+        
+        return generic_templates
+
+    def _generate_additional_card(self, topic: str, card_type: str, difficulty_level: str, card_number: int) -> Dict[str, Any]:
+        """Generate additional cards when more are needed."""
+        
+        additional_subtopics = [
+            "Pathophysiology", "Epidemiology", "Risk factors", "Differential diagnosis",
+            "Prognosis", "Prevention", "Monitoring", "Patient education", "Guidelines"
+        ]
+        
+        subtopic_index = (card_number - 5) % len(additional_subtopics)
+        subtopic = additional_subtopics[subtopic_index]
+        
+        return {
+            "card_id": card_number + 1,
+            "subtopic": subtopic,
+            "front": f"What should you know about {subtopic.lower()} of {topic}?",
+            "back": f"[Key information about {subtopic.lower()} related to {topic}]",
+            "memory_aid": f"Clinical pearl: {subtopic} in {topic}",
+            "difficulty": "intermediate"
+        }
+
+    def _organize_cards_by_subtopic(self, flash_cards: List[Dict], topic: str) -> Dict[str, List[Dict]]:
+        """Organize cards by subtopic for structured learning."""
+        
+        organized = {}
+        
+        for card in flash_cards:
+            subtopic = card.get("subtopic", "General")
+            if subtopic not in organized:
+                organized[subtopic] = []
+            organized[subtopic].append(card)
+        
+        return organized
+
+    def _generate_study_tips(self, topic: str, card_type: str) -> List[str]:
+        """Generate study tips for using the flash cards effectively."""
+        
+        tips = [
+            "Review cards daily for optimal retention",
+            "Use spaced repetition - review difficult cards more frequently",
+            "Study the memory aids and mnemonics separately",
+            "Test yourself by covering the back of the card first",
+            "Create your own examples for each concept",
+            "Review in both directions (front-to-back and back-to-front)",
+            "Focus on understanding, not just memorization",
+            "Connect concepts to real patient cases when possible"
+        ]
+        
+        if card_type == "mnemonics":
+            tips.append("Practice writing out the mnemonics from memory")
+        elif card_type == "clinical_pearls":
+            tips.append("Think of patient scenarios where each pearl would apply")
+        
+        return tips
+
+    def _generate_review_schedule(self) -> Dict[str, str]:
+        """Generate a spaced repetition review schedule."""
+        
+        schedule = {
+            "Day 1": "Initial learning - review all cards",
+            "Day 2": "Review all cards again",
+            "Day 4": "Review cards you found difficult",
+            "Day 7": "Review entire set",
+            "Day 14": "Review difficult cards only",
+            "Day 30": "Complete review of all cards",
+            "Day 60": "Final review and assessment"
+        }
+        
+        return schedule