Add TTS on-demand with UI credentials, improve UI layout, and fix References removal

.github/scripts/deploy_to_hf_space.py

@@ -5,12 +5,11 @@ import shutil
 import subprocess
 import tempfile
 from pathlib import Path
-from typing import Set
 
 from huggingface_hub import HfApi
 
 
-def get_excluded_dirs() -> Set[str]:
+def get_excluded_dirs() -> set[str]:
     """Get set of directory names to exclude from deployment."""
     return {
         "docs",
@@ -43,7 +42,7 @@ def get_excluded_dirs() -> Set[str]:
     }
 
 
-def get_excluded_files() -> Set[str]:
+def get_excluded_files() -> set[str]:
     """Get set of file names to exclude from deployment."""
     return {
         ".pre-commit-config.yaml",
@@ -61,17 +60,17 @@ def get_excluded_files() -> Set[str]:
     }
 
 
-def should_exclude(path: Path, excluded_dirs: Set[str], excluded_files: Set[str]) -> bool:
+def should_exclude(path: Path, excluded_dirs: set[str], excluded_files: set[str]) -> bool:
     """Check if a path should be excluded from deployment."""
     # Check if any parent directory is excluded
     for parent in path.parents:
         if parent.name in excluded_dirs:
             return True
-    
+
     # Check if the path itself is a directory that should be excluded
     if path.is_dir() and path.name in excluded_dirs:
         return True
-    
+
     # Check if the file name matches excluded patterns
     if path.is_file():
         # Check exact match
@@ -84,24 +83,24 @@ def should_exclude(path: Path, excluded_dirs: Set[str], excluded_files: Set[str]
                 suffix = pattern.replace("*", "")
                 if path.name.endswith(suffix):
                     return True
-    
+
     return False
 
 
 def deploy_to_hf_space() -> None:
     """Deploy repository to Hugging Face Space.
-    
+
     Supports both user and organization Spaces:
     - User Space: username/space-name
     - Organization Space: organization-name/space-name
-    
+
     Works with both classic tokens and fine-grained tokens.
     """
     # Get configuration from environment variables
     hf_token = os.getenv("HF_TOKEN")
     hf_username = os.getenv("HF_USERNAME")  # Can be username or organization name
     space_name = os.getenv("HF_SPACE_NAME")
-    
+
     # Check which variables are missing and provide helpful error message
     missing = []
     if not hf_token:
@@ -110,7 +109,7 @@ def deploy_to_hf_space() -> None:
         missing.append("HF_USERNAME (should be in repository variables)")
     if not space_name:
         missing.append("HF_SPACE_NAME (should be in repository variables)")
-    
+
     if missing:
         raise ValueError(
             f"Missing required environment variables: {', '.join(missing)}\n"
@@ -119,17 +118,17 @@ def deploy_to_hf_space() -> None:
             f"  - HF_USERNAME in Settings > Secrets and variables > Actions > Variables\n"
             f"  - HF_SPACE_NAME in Settings > Secrets and variables > Actions > Variables"
         )
-    
+
     # HF_USERNAME can be either a username or organization name
     # Format: {username|organization}/{space_name}
     repo_id = f"{hf_username}/{space_name}"
     local_dir = "hf_space"
-    
+
     print(f"🚀 Deploying to Hugging Face Space: {repo_id}")
-    
+
     # Initialize HF API
     api = HfApi(token=hf_token)
-    
+
     # Create Space if it doesn't exist
     try:
         api.repo_info(repo_id=repo_id, repo_type="space", token=hf_token)
@@ -147,43 +146,45 @@ def deploy_to_hf_space() -> None:
             exist_ok=True,
         )
         print(f"✅ Created new Space: {repo_id}")
-    
+
     # Configure Git credential helper for authentication
     # This is needed for Git LFS to work properly with fine-grained tokens
     print("🔐 Configuring Git credentials...")
-    
+
     # Use Git credential store to store the token
     # This allows Git LFS to authenticate properly
     temp_dir = Path(tempfile.gettempdir())
     credential_store = temp_dir / ".git-credentials-hf"
-    
+
     # Write credentials in the format: https://username:[email protected]
-    credential_store.write_text(f"https://{hf_username}:{hf_token}@huggingface.co\n", encoding="utf-8")
+    credential_store.write_text(
+        f"https://{hf_username}:{hf_token}@huggingface.co\n", encoding="utf-8"
+    )
     try:
         credential_store.chmod(0o600)  # Secure permissions (Unix only)
     except OSError:
         # Windows doesn't support chmod, skip
         pass
-    
+
     # Configure Git to use the credential store
     subprocess.run(
         ["git", "config", "--global", "credential.helper", f"store --file={credential_store}"],
         check=True,
         capture_output=True,
     )
-    
+
     # Also set environment variable for Git LFS
     os.environ["GIT_CREDENTIAL_HELPER"] = f"store --file={credential_store}"
-    
+
     # Clone repository using git
     # Use the token in the URL for initial clone, but LFS will use credential store
     space_url = f"https://{hf_username}:{hf_token}@huggingface.co/spaces/{repo_id}"
-    
+
     if Path(local_dir).exists():
         print(f"🧹 Removing existing {local_dir} directory...")
         shutil.rmtree(local_dir)
-    
-    print(f"📥 Cloning Space repository...")
+
+    print("📥 Cloning Space repository...")
     try:
         result = subprocess.run(
             ["git", "clone", space_url, local_dir],
@@ -191,8 +192,8 @@ def deploy_to_hf_space() -> None:
             capture_output=True,
             text=True,
         )
-        print(f"✅ Cloned Space repository")
-        
+        print("✅ Cloned Space repository")
+
         # After clone, configure the remote to use credential helper
         # This ensures future operations (like push) use the credential store
         os.chdir(local_dir)
@@ -202,17 +203,17 @@ def deploy_to_hf_space() -> None:
             capture_output=True,
         )
         os.chdir("..")
-        
+
     except subprocess.CalledProcessError as e:
         error_msg = e.stderr if e.stderr else e.stdout if e.stdout else "Unknown error"
         print(f"❌ Failed to clone Space repository: {error_msg}")
-        
+
         # Try alternative: clone with LFS skip, then fetch LFS files separately
         print("🔄 Trying alternative clone method (skip LFS during clone)...")
         try:
             env = os.environ.copy()
             env["GIT_LFS_SKIP_SMUDGE"] = "1"  # Skip LFS during clone
-            
+
             subprocess.run(
                 ["git", "clone", space_url, local_dir],
                 check=True,
@@ -220,8 +221,8 @@ def deploy_to_hf_space() -> None:
                 text=True,
                 env=env,
             )
-            print(f"✅ Cloned Space repository (LFS skipped)")
-            
+            print("✅ Cloned Space repository (LFS skipped)")
+
             # Configure remote
             os.chdir(local_dir)
             subprocess.run(
@@ -229,7 +230,7 @@ def deploy_to_hf_space() -> None:
                 check=True,
                 capture_output=True,
             )
-            
+
             # Try to fetch LFS files with proper authentication
             print("📥 Fetching LFS files...")
             subprocess.run(
@@ -239,16 +240,16 @@ def deploy_to_hf_space() -> None:
                 text=True,
             )
             os.chdir("..")
-            print(f"✅ Repository cloned (LFS files may be incomplete, but deployment can continue)")
+            print("✅ Repository cloned (LFS files may be incomplete, but deployment can continue)")
         except subprocess.CalledProcessError as e2:
             error_msg2 = e2.stderr if e2.stderr else e2.stdout if e2.stdout else "Unknown error"
             print(f"❌ Alternative clone method also failed: {error_msg2}")
             raise RuntimeError(f"Git clone failed: {error_msg}") from e
-    
+
     # Get exclusion sets
     excluded_dirs = get_excluded_dirs()
     excluded_files = get_excluded_files()
-    
+
     # Remove all existing files in HF Space (except .git)
     print("🧹 Cleaning existing files...")
     for item in Path(local_dir).iterdir():
@@ -258,43 +259,43 @@ def deploy_to_hf_space() -> None:
             shutil.rmtree(item)
         else:
             item.unlink()
-    
+
     # Copy files from repository root
     print("📦 Copying files...")
     repo_root = Path(".")
     files_copied = 0
     dirs_copied = 0
-    
+
     for item in repo_root.rglob("*"):
         # Skip if in .git directory
         if ".git" in item.parts:
             continue
-        
+
         # Skip if in hf_space directory (the cloned Space directory)
         if "hf_space" in item.parts:
             continue
-        
+
         # Skip if should be excluded
         if should_exclude(item, excluded_dirs, excluded_files):
             continue
-        
+
         # Calculate relative path
         try:
             rel_path = item.relative_to(repo_root)
         except ValueError:
             # Item is outside repo root, skip
             continue
-        
+
         # Skip if in excluded directory
         if any(part in excluded_dirs for part in rel_path.parts):
             continue
-        
+
         # Destination path
         dest_path = Path(local_dir) / rel_path
-        
+
         # Create parent directories
         dest_path.parent.mkdir(parents=True, exist_ok=True)
-        
+
         # Copy file or directory
         if item.is_file():
             shutil.copy2(item, dest_path)
@@ -302,16 +303,16 @@ def deploy_to_hf_space() -> None:
         elif item.is_dir():
             # Directory will be created by parent mkdir, but we track it
             dirs_copied += 1
-    
+
     print(f"✅ Copied {files_copied} files and {dirs_copied} directories")
-    
+
     # Commit and push changes using git
     print("💾 Committing changes...")
-    
+
     # Change to the Space directory
     original_cwd = os.getcwd()
     os.chdir(local_dir)
-    
+
     try:
         # Configure git user (required for commit)
         subprocess.run(
@@ -324,21 +325,22 @@ def deploy_to_hf_space() -> None:
             check=True,
             capture_output=True,
         )
-        
+
         # Add all files
         subprocess.run(
             ["git", "add", "."],
             check=True,
             capture_output=True,
         )
-        
+
         # Check if there are changes to commit
         result = subprocess.run(
             ["git", "status", "--porcelain"],
+            check=False,
             capture_output=True,
             text=True,
         )
-        
+
         if result.stdout.strip():
             # There are changes, commit and push
             subprocess.run(
@@ -373,7 +375,7 @@ def deploy_to_hf_space() -> None:
     finally:
         # Return to original directory
         os.chdir(original_cwd)
-        
+
         # Clean up credential store for security
         try:
             if credential_store.exists():
@@ -381,10 +383,9 @@ def deploy_to_hf_space() -> None:
         except Exception:
             # Ignore cleanup errors
             pass
-    
+
     print(f"🎉 Successfully deployed to: https://huggingface.co/spaces/{repo_id}")
 
 
 if __name__ == "__main__":
     deploy_to_hf_space()
-

deployments/modal_tts.py

@@ -92,10 +92,6 @@ def kokoro_tts_function(text: str, voice: str, speed: float) -> tuple[int, np.nd
 def test():
     """Test the TTS function."""
     print("Testing Modal TTS function...")
-    sample_rate, audio = kokoro_tts_function.remote(
-        "Hello, this is a test.",
-        "af_heart",
-        1.0
-    )
+    sample_rate, audio = kokoro_tts_function.remote("Hello, this is a test.", "af_heart", 1.0)
     print(f"Generated audio: {sample_rate}Hz, shape={audio.shape}")
     print("✓ TTS function works!")

src/agent_factory/agents.py

@@ -27,7 +27,9 @@ if TYPE_CHECKING:
 logger = structlog.get_logger()
 
 
-def create_input_parser_agent(model: Any | None = None, oauth_token: str | None = None) -> "InputParserAgent":
+def create_input_parser_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> "InputParserAgent":
     """
     Create input parser agent for query analysis and research mode detection.
 
@@ -51,7 +53,9 @@ def create_input_parser_agent(model: Any | None = None, oauth_token: str | None
         raise ConfigurationError(f"Failed to create input parser agent: {e}") from e
 
 
-def create_planner_agent(model: Any | None = None, oauth_token: str | None = None) -> "PlannerAgent":
+def create_planner_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> "PlannerAgent":
     """
     Create planner agent with web search and crawl tools.
 
@@ -76,7 +80,9 @@ def create_planner_agent(model: Any | None = None, oauth_token: str | None = Non
         raise ConfigurationError(f"Failed to create planner agent: {e}") from e
 
 
-def create_knowledge_gap_agent(model: Any | None = None, oauth_token: str | None = None) -> "KnowledgeGapAgent":
+def create_knowledge_gap_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> "KnowledgeGapAgent":
     """
     Create knowledge gap agent for evaluating research completeness.
 
@@ -100,7 +106,9 @@ def create_knowledge_gap_agent(model: Any | None = None, oauth_token: str | None
         raise ConfigurationError(f"Failed to create knowledge gap agent: {e}") from e
 
 
-def create_tool_selector_agent(model: Any | None = None, oauth_token: str | None = None) -> "ToolSelectorAgent":
+def create_tool_selector_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> "ToolSelectorAgent":
     """
     Create tool selector agent for choosing tools to address gaps.
 
@@ -124,7 +132,9 @@ def create_tool_selector_agent(model: Any | None = None, oauth_token: str | None
         raise ConfigurationError(f"Failed to create tool selector agent: {e}") from e
 
 
-def create_thinking_agent(model: Any | None = None, oauth_token: str | None = None) -> "ThinkingAgent":
+def create_thinking_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> "ThinkingAgent":
     """
     Create thinking agent for generating observations.
 
@@ -172,7 +182,9 @@ def create_writer_agent(model: Any | None = None, oauth_token: str | None = None
         raise ConfigurationError(f"Failed to create writer agent: {e}") from e
 
 
-def create_long_writer_agent(model: Any | None = None, oauth_token: str | None = None) -> "LongWriterAgent":
+def create_long_writer_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> "LongWriterAgent":
     """
     Create long writer agent for iteratively writing report sections.
 
@@ -196,7 +208,9 @@ def create_long_writer_agent(model: Any | None = None, oauth_token: str | None =
         raise ConfigurationError(f"Failed to create long writer agent: {e}") from e
 
 
-def create_proofreader_agent(model: Any | None = None, oauth_token: str | None = None) -> "ProofreaderAgent":
+def create_proofreader_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> "ProofreaderAgent":
     """
     Create proofreader agent for finalizing report drafts.
 

src/agent_factory/graph_builder.py

@@ -487,12 +487,13 @@ def create_iterative_graph(
     # Add nodes
     builder.add_agent_node("thinking", thinking_agent, "Generate observations")
     builder.add_agent_node("knowledge_gap", knowledge_gap_agent, "Evaluate knowledge gaps")
+
     def _decision_function(result: Any) -> str:
         """Decision function for continue_decision node.
-        
+
         Args:
             result: Result from knowledge_gap node (KnowledgeGapOutput or tuple)
-            
+
         Returns:
             Next node ID: "writer" if research complete, "tool_selector" otherwise
         """
@@ -510,11 +511,11 @@ def create_iterative_graph(
                     return "writer" if item["research_complete"] else "tool_selector"
             # Default to continuing research if we can't determine
             return "tool_selector"
-        
+
         # Normal case: result is KnowledgeGapOutput object
         research_complete = getattr(result, "research_complete", False)
         return "writer" if research_complete else "tool_selector"
-    
+
     builder.add_decision_node(
         "continue_decision",
         decision_function=_decision_function,

src/agent_factory/judges.py

@@ -37,7 +37,7 @@ def get_model(oauth_token: str | None = None) -> Any:
     1. HuggingFace (if OAuth token or API key available - preferred for free tier)
     2. OpenAI (if API key available)
     3. Anthropic (if API key available)
-    
+
     If OAuth token is available, prefer HuggingFace (even if provider is set to OpenAI).
     This ensures users logged in via HuggingFace Spaces get the free tier.
 
@@ -175,9 +175,8 @@ class JudgeHandler:
             from src.utils.hf_error_handler import (
                 extract_error_details,
                 get_user_friendly_error_message,
-                should_retry_with_fallback,
             )
-            
+
             error_details = extract_error_details(e)
             logger.error(
                 "Assessment failed",
@@ -187,12 +186,12 @@ class JudgeHandler:
                 is_auth_error=error_details.get("is_auth_error"),
                 is_model_error=error_details.get("is_model_error"),
             )
-            
+
             # Log user-friendly message for debugging
             if error_details.get("is_auth_error") or error_details.get("is_model_error"):
                 user_msg = get_user_friendly_error_message(e, error_details.get("model_name"))
                 logger.warning("API error details", user_message=user_msg[:200])
-            
+
             # Return a safe default assessment on failure
             return self._create_fallback_assessment(question, str(e))
 
@@ -244,9 +243,7 @@ class HFInferenceJudgeHandler:
         "HuggingFaceH4/zephyr-7b-beta",  # Fallback (Ungated)
     ]
 
-    def __init__(
-        self, model_id: str | None = None, api_key: str | None = None
-    ) -> None:
+    def __init__(self, model_id: str | None = None, api_key: str | None = None) -> None:
         """
         Initialize with HF Inference client.
 

src/agents/audio_refiner.py

@@ -5,7 +5,6 @@ audio-friendly plain text suitable for text-to-speech synthesis.
 """
 
 import re
-from typing import Optional
 
 import structlog
 from pydantic_ai import Agent
@@ -27,18 +26,30 @@ class AudioRefiner:
     """
 
     # Roman numeral to integer mapping
-    ROMAN_VALUES = {
-        'I': 1, 'V': 5, 'X': 10, 'L': 50,
-        'C': 100, 'D': 500, 'M': 1000
-    }
+    ROMAN_VALUES = {"I": 1, "V": 5, "X": 10, "L": 50, "C": 100, "D": 500, "M": 1000}
 
     # Number to word mapping (1-20, common in medical literature)
     NUMBER_TO_WORD = {
-        1: 'One', 2: 'Two', 3: 'Three', 4: 'Four', 5: 'Five',
-        6: 'Six', 7: 'Seven', 8: 'Eight', 9: 'Nine', 10: 'Ten',
-        11: 'Eleven', 12: 'Twelve', 13: 'Thirteen', 14: 'Fourteen',
-        15: 'Fifteen', 16: 'Sixteen', 17: 'Seventeen', 18: 'Eighteen',
-        19: 'Nineteen', 20: 'Twenty'
+        1: "One",
+        2: "Two",
+        3: "Three",
+        4: "Four",
+        5: "Five",
+        6: "Six",
+        7: "Seven",
+        8: "Eight",
+        9: "Nine",
+        10: "Ten",
+        11: "Eleven",
+        12: "Twelve",
+        13: "Thirteen",
+        14: "Fourteen",
+        15: "Fifteen",
+        16: "Sixteen",
+        17: "Seventeen",
+        18: "Eighteen",
+        19: "Nineteen",
+        20: "Twenty",
     }
 
     async def refine_for_audio(self, markdown_text: str, use_llm_polish: bool = False) -> str:
@@ -55,7 +66,7 @@ class AudioRefiner:
 
         text = markdown_text
 
-        # Step 1: Keep only content before first References section
+        # Step 1: Remove References sections first (before other processing)
         text = self._remove_references_sections(text)
 
         # Step 2: Remove markdown formatting
@@ -81,7 +92,7 @@ class AudioRefiner:
             "Audio refinement complete",
             original_length=len(markdown_text),
             refined_length=len(text),
-            llm_polish_applied=use_llm_polish
+            llm_polish_applied=use_llm_polish,
         )
 
         return text.strip()
@@ -97,10 +108,11 @@ class AudioRefiner:
         - ## References
         - **References:**
         - **Additional References:**
+        - References: (plain text)
         """
         # Pattern to match References section heading (case-insensitive)
-        # Only matches headings that contain "Reference" or "References"
-        references_pattern = r'\n(?:#+\s*References?:?\s*\n|\*\*\s*(?:Additional\s+)?References?:?\s*\*\*\s*\n)'
+        # Matches: markdown headers (# References), bold (**References:**), or plain text (References:)
+        references_pattern = r"\n(?:#+\s*References?:?\s*\n|\*\*\s*(?:Additional\s+)?References?:?\s*\*\*\s*\n|References?:?\s*\n)"
 
         # Find all References sections
         while True:
@@ -114,11 +126,11 @@ class AudioRefiner:
             # Find the next section (markdown header or bold heading) or end of document
             # Match: "# Header", "## Header", or "**Header**"
             next_section_patterns = [
-                r'\n#+\s+\w+',  # Markdown headers (# Section, ## Section)
-                r'\n\*\*[A-Z][^*]+\*\*',  # Bold headings (**Section Name**)
+                r"\n#+\s+\w+",  # Markdown headers (# Section, ## Section)
+                r"\n\*\*[A-Z][^*]+\*\*",  # Bold headings (**Section Name**)
             ]
 
-            remaining_text = text[match.end():]
+            remaining_text = text[match.end() :]
             next_section_match = None
 
             # Try all patterns and find the earliest match
@@ -139,10 +151,7 @@ class AudioRefiner:
 
             # Remove the References section
             text = text[:section_start] + text[section_end:]
-            logger.debug(
-                "Removed References section",
-                removed_chars=section_end - section_start
-            )
+            logger.debug("Removed References section", removed_chars=section_end - section_start)
 
         return text
 
@@ -150,38 +159,38 @@ class AudioRefiner:
         """Remove markdown formatting syntax."""
 
         # Headers (# ## ###)
-        text = re.sub(r'^\s*#+\s+', '', text, flags=re.MULTILINE)
+        text = re.sub(r"^\s*#+\s+", "", text, flags=re.MULTILINE)
 
         # Bold (**text** or __text__)
-        text = re.sub(r'\*\*([^*]+)\*\*', r'\1', text)
-        text = re.sub(r'__([^_]+)__', r'\1', text)
+        text = re.sub(r"\*\*([^*]+)\*\*", r"\1", text)
+        text = re.sub(r"__([^_]+)__", r"\1", text)
 
         # Italic (*text* or _text_)
-        text = re.sub(r'\*([^*]+)\*', r'\1', text)
-        text = re.sub(r'_([^_]+)_', r'\1', text)
+        text = re.sub(r"\*([^*]+)\*", r"\1", text)
+        text = re.sub(r"_([^_]+)_", r"\1", text)
 
         # Links [text](url) → text
-        text = re.sub(r'\[([^\]]+)\]\([^)]+\)', r'\1', text)
+        text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
 
         # Inline code `code` → code
-        text = re.sub(r'`([^`]+)`', r'\1', text)
+        text = re.sub(r"`([^`]+)`", r"\1", text)
 
         # Strikethrough ~~text~~
-        text = re.sub(r'~~([^~]+)~~', r'\1', text)
+        text = re.sub(r"~~([^~]+)~~", r"\1", text)
 
         # Blockquotes (> text)
-        text = re.sub(r'^\s*>\s+', '', text, flags=re.MULTILINE)
+        text = re.sub(r"^\s*>\s+", "", text, flags=re.MULTILINE)
 
         # Horizontal rules (---, ***, ___)
-        text = re.sub(r'^\s*[-*_]{3,}\s*$', '', text, flags=re.MULTILINE)
+        text = re.sub(r"^\s*[-*_]{3,}\s*$", "", text, flags=re.MULTILINE)
 
         # List markers (-, *, 1., 2.)
-        text = re.sub(r'^\s*[-*]\s+', '', text, flags=re.MULTILINE)
-        text = re.sub(r'^\s*\d+\.\s+', '', text, flags=re.MULTILINE)
+        text = re.sub(r"^\s*[-*]\s+", "", text, flags=re.MULTILINE)
+        text = re.sub(r"^\s*\d+\.\s+", "", text, flags=re.MULTILINE)
 
         return text
 
-    def _roman_to_int(self, roman: str) -> Optional[int]:
+    def _roman_to_int(self, roman: str) -> int | None:
         """Convert roman numeral string to integer.
 
         Args:
@@ -236,10 +245,10 @@ class AudioRefiner:
         - Standalone I, II, III (with word boundaries)
         """
 
-        def replace_roman(match):
+        def replace_roman(match: re.Match[str]) -> str:
             """Callback to replace matched roman numeral."""
             prefix = match.group(1)  # Word before roman numeral (if any)
-            roman = match.group(2)   # The roman numeral
+            roman = match.group(2)  # The roman numeral
 
             # Convert to integer
             num = self._roman_to_int(roman)
@@ -258,7 +267,7 @@ class AudioRefiner:
         # Pattern: Optional word + space + roman numeral
         # Matches: "Phase I", "Trial II", standalone "I", "II"
         # Uses word boundaries to avoid matching "I" in "INVALID"
-        pattern = r'\b(Phase|Trial|Type|Stage|Class|Group|Arm|Cohort)?\s*([IVXLCDM]+)\b'
+        pattern = r"\b(Phase|Trial|Type|Stage|Class|Group|Arm|Cohort)?\s*([IVXLCDM]+)\b"
 
         text = re.sub(pattern, replace_roman, text)
 
@@ -268,19 +277,19 @@ class AudioRefiner:
         """Remove citation markers and references."""
 
         # Numbered citations [1], [2], [1,2], [1-3]
-        text = re.sub(r'\[\d+(?:[-,]\d+)*\]', '', text)
+        text = re.sub(r"\[\d+(?:[-,]\d+)*\]", "", text)
 
         # Author citations (Smith et al., 2023) or (Smith et al. 2023)
-        text = re.sub(r'\([A-Z][a-z]+\s+et\s+al\.?,?\s+\d{4}\)', '', text)
+        text = re.sub(r"\([A-Z][a-z]+\s+et\s+al\.?,?\s+\d{4}\)", "", text)
 
         # Simple year citations (2023)
-        text = re.sub(r'\(\d{4}\)', '', text)
+        text = re.sub(r"\(\d{4}\)", "", text)
 
         # Author-year (Smith, 2023)
-        text = re.sub(r'\([A-Z][a-z]+,?\s+\d{4}\)', '', text)
+        text = re.sub(r"\([A-Z][a-z]+,?\s+\d{4}\)", "", text)
 
         # Footnote markers (¹, ², ³)
-        text = re.sub(r'[¹²³⁴⁵⁶⁷⁸⁹⁰]+', '', text)
+        text = re.sub(r"[¹²³⁴⁵⁶⁷⁸⁹⁰]+", "", text)
 
         return text
 
@@ -288,26 +297,26 @@ class AudioRefiner:
         """Clean up special characters and formatting artifacts."""
 
         # Replace em dashes with regular dashes
-        text = text.replace('\u2014', '-')  # em dash
-        text = text.replace('\u2013', '-')  # en dash
+        text = text.replace("\u2014", "-")  # em dash
+        text = text.replace("\u2013", "-")  # en dash
 
         # Replace smart quotes with regular quotes
-        text = text.replace('\u201c', '"')  # left double quote
-        text = text.replace('\u201d', '"')  # right double quote
-        text = text.replace('\u2018', "'")  # left single quote
-        text = text.replace('\u2019', "'")  # right single quote
+        text = text.replace("\u201c", '"')  # left double quote
+        text = text.replace("\u201d", '"')  # right double quote
+        text = text.replace("\u2018", "'")  # left single quote
+        text = text.replace("\u2019", "'")  # right single quote
 
         # Remove excessive punctuation (!!!, ???)
-        text = re.sub(r'([!?]){2,}', r'\1', text)
+        text = re.sub(r"([!?]){2,}", r"\1", text)
 
         # Remove asterisks used for footnotes
-        text = re.sub(r'\*+', '', text)
+        text = re.sub(r"\*+", "", text)
 
         # Remove hash symbols (from headers)
-        text = text.replace('#', '')
+        text = text.replace("#", "")
 
         # Remove excessive dots (...)
-        text = re.sub(r'\.{4,}', '...', text)
+        text = re.sub(r"\.{4,}", "...", text)
 
         return text
 
@@ -315,13 +324,13 @@ class AudioRefiner:
         """Normalize whitespace for clean audio output."""
 
         # Replace multiple spaces with single space
-        text = re.sub(r' {2,}', ' ', text)
+        text = re.sub(r" {2,}", " ", text)
 
         # Replace multiple newlines with double newline (paragraph break)
-        text = re.sub(r'\n{3,}', '\n\n', text)
+        text = re.sub(r"\n{3,}", "\n\n", text)
 
         # Remove trailing/leading whitespace from lines
-        text = '\n'.join(line.strip() for line in text.split('\n'))
+        text = "\n".join(line.strip() for line in text.split("\n"))
 
         # Remove empty lines at start/end
         text = text.strip()
@@ -363,18 +372,14 @@ class AudioRefiner:
             polished_text = result.output.strip()
 
             logger.info(
-                "llm_polish_applied",
-                original_length=len(text),
-                polished_length=len(polished_text)
+                "llm_polish_applied", original_length=len(text), polished_length=len(polished_text)
             )
 
             return polished_text
 
         except Exception as e:
             logger.warning(
-                "llm_polish_failed",
-                error=str(e),
-                message="Falling back to rule-based output"
+                "llm_polish_failed", error=str(e), message="Falling back to rule-based output"
             )
             # Graceful fallback: return original text if LLM fails
             return text

src/agents/knowledge_gap.py

@@ -142,7 +142,9 @@ HISTORY OF ACTIONS, FINDINGS AND THOUGHTS:
             )
 
 
-def create_knowledge_gap_agent(model: Any | None = None, oauth_token: str | None = None) -> KnowledgeGapAgent:
+def create_knowledge_gap_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> KnowledgeGapAgent:
     """
     Factory function to create a knowledge gap agent.
 

src/agents/long_writer.py

@@ -225,25 +225,27 @@ class LongWriterAgent:
             "Section writing failed after all attempts",
             error=str(last_exception) if last_exception else "Unknown error",
         )
-        
+
         # Try to enhance fallback with evidence if available
         try:
             from src.middleware.state_machine import get_workflow_state
-            
+
             state = get_workflow_state()
             if state and state.evidence:
                 # Include evidence citations in fallback
                 evidence_refs: list[str] = []
                 for i, ev in enumerate(state.evidence[:10], 1):  # Limit to 10
-                    authors = ", ".join(ev.citation.authors[:2]) if ev.citation.authors else "Unknown"
+                    authors = (
+                        ", ".join(ev.citation.authors[:2]) if ev.citation.authors else "Unknown"
+                    )
                     evidence_refs.append(
                         f"[{i}] {authors}. *{ev.citation.title}*. {ev.citation.url}"
                     )
-                
+
                 enhanced_draft = f"## {next_section_title}\n\n{next_section_draft}"
                 if evidence_refs:
                     enhanced_draft += "\n\n### Sources\n\n" + "\n".join(evidence_refs)
-                
+
                 return LongWriterOutput(
                     next_section_markdown=enhanced_draft,
                     references=evidence_refs,
@@ -253,7 +255,7 @@ class LongWriterAgent:
                 "Failed to enhance fallback with evidence",
                 error=str(e),
             )
-        
+
         # Basic fallback
         return LongWriterOutput(
             next_section_markdown=f"## {next_section_title}\n\n{next_section_draft}",
@@ -437,7 +439,9 @@ class LongWriterAgent:
         return re.sub(r"^(#+)\s(.+)$", adjust_heading_level, section_markdown, flags=re.MULTILINE)
 
 
-def create_long_writer_agent(model: Any | None = None, oauth_token: str | None = None) -> LongWriterAgent:
+def create_long_writer_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> LongWriterAgent:
     """
     Factory function to create a long writer agent.
 

src/agents/proofreader.py

@@ -181,7 +181,9 @@ REPORT DRAFT:
         return f"# Research Report\n\n## Query\n{query}\n\n" + "\n\n".join(sections)
 
 
-def create_proofreader_agent(model: Any | None = None, oauth_token: str | None = None) -> ProofreaderAgent:
+def create_proofreader_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> ProofreaderAgent:
     """
     Factory function to create a proofreader agent.
 

src/agents/thinking.py

@@ -134,7 +134,9 @@ HISTORY OF ACTIONS, FINDINGS AND THOUGHTS:
             return f"Starting iteration {iteration}. Need to gather information about: {query}"
 
 
-def create_thinking_agent(model: Any | None = None, oauth_token: str | None = None) -> ThinkingAgent:
+def create_thinking_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> ThinkingAgent:
     """
     Factory function to create a thinking agent.
 

src/agents/tool_selector.py

@@ -154,7 +154,9 @@ HISTORY OF ACTIONS, FINDINGS AND THOUGHTS:
             )
 
 
-def create_tool_selector_agent(model: Any | None = None, oauth_token: str | None = None) -> ToolSelectorAgent:
+def create_tool_selector_agent(
+    model: Any | None = None, oauth_token: str | None = None
+) -> ToolSelectorAgent:
     """
     Factory function to create a tool selector agent.
 

src/agents/writer.py

@@ -175,12 +175,12 @@ FINDINGS:
             "Report writing failed after all attempts",
             error=str(last_exception) if last_exception else "Unknown error",
         )
-        
+
         # Try to use evidence-based report generator for better fallback
         try:
             from src.middleware.state_machine import get_workflow_state
             from src.utils.report_generator import generate_report_from_evidence
-            
+
             state = get_workflow_state()
             if state and state.evidence:
                 self.logger.info(
@@ -197,7 +197,7 @@ FINDINGS:
                 "Failed to use evidence-based report generator",
                 error=str(e),
             )
-        
+
         # Fallback to simple report if evidence generator fails
         # Truncate findings in fallback if too long
         fallback_findings = findings[:500] + "..." if len(findings) > 500 else findings

src/app.py

@@ -18,7 +18,6 @@ import structlog
 
 from src.agent_factory.judges import HFInferenceJudgeHandler, JudgeHandler, MockJudgeHandler
 from src.orchestrator_factory import create_orchestrator
-from src.services.audio_processing import get_audio_service
 from src.services.multimodal_processing import get_multimodal_service
 from src.utils.config import settings
 from src.utils.models import AgentEvent, OrchestratorConfig
@@ -445,9 +444,6 @@ async def research_agent(
     use_graph: bool = True,
     enable_image_input: bool = True,
     enable_audio_input: bool = True,
-    tts_voice: str = "af_heart",
-    tts_speed: float = 1.0,
-    tts_use_llm_polish: bool = False,
     web_search_provider: str = "auto",
     oauth_token: gr.OAuthToken | None = None,
     oauth_profile: gr.OAuthProfile | None = None,
@@ -465,15 +461,12 @@ async def research_agent(
         use_graph: Whether to use graph execution
         enable_image_input: Whether to process image inputs
         enable_audio_input: Whether to process audio inputs
-        tts_voice: TTS voice selection
-        tts_speed: TTS speech speed
-        tts_use_llm_polish: Apply LLM-based final polish to audio text (costs API calls)
         web_search_provider: Web search provider selection
         oauth_token: Gradio OAuth token (None if user not logged in)
         oauth_profile: Gradio OAuth profile (None if user not logged in)
 
     Yields:
-        Chat message dictionaries or tuples with audio data
+        Chat message dictionaries
     """
     # Extract OAuth token and username
     token_value = _extract_oauth_token(oauth_token)
@@ -585,33 +578,8 @@ async def research_agent(
             chat_msg = event_to_chat_message(event)
             yield chat_msg
 
-        # Optional: Generate audio output if enabled
-        if settings.enable_audio_output and settings.modal_available:
-            try:
-                audio_service = get_audio_service()
-                # Get the last message from history for TTS
-                last_message = history[-1].get("content", "") if history else processed_text
-                if last_message:
-                    # Temporarily override tts_use_llm_polish setting from UI
-                    original_llm_polish = settings.tts_use_llm_polish
-                    try:
-                        settings.tts_use_llm_polish = tts_use_llm_polish
-                        # Use UI-configured voice and speed, fallback to settings defaults
-                        await audio_service.generate_audio_output(
-                            text=last_message,
-                            voice=tts_voice or settings.tts_voice,
-                            speed=tts_speed if tts_speed else settings.tts_speed,
-                        )
-                    finally:
-                        # Restore original setting
-                        settings.tts_use_llm_polish = original_llm_polish
-            except Exception as e:
-                logger.warning("audio_synthesis_failed", error=str(e))
-                # Continue without audio output
-
-        # Note: Audio output is handled separately via TTS service
-        # Gradio ChatInterface doesn't support tuple yields, so we skip audio output here
-        # Audio can be handled via a separate component if needed
+        # Note: Audio output is now handled via on-demand TTS button
+        # Users click "Generate Audio" button to create TTS for the last response
 
     except Exception as e:
         # Return error message without metadata to avoid issues during example caching
@@ -746,19 +714,26 @@ def create_demo() -> gr.Blocks:
             )
             gr.LoginButton("Sign in with Hugging Face")
             gr.Markdown("---")
-            gr.Markdown("### ℹ️ About")  # noqa: RUF001
-            gr.Markdown(
-                "**The DETERMINATOR** - Generalist Deep Research Agent\n\n"
-                "A powerful research agent that stops at nothing until finding precise answers to complex questions.\n\n"
-                "**Available Sources**:\n"
-                "- Web Search (general knowledge)\n"
-                "- PubMed (biomedical literature)\n"
-                "- ClinicalTrials.gov (clinical trials)\n"
-                "- Europe PMC (preprints & papers)\n"
-                "- RAG (semantic search)\n\n"
-                "**Automatic Detection**: Automatically determines if medical knowledge sources are needed for your query.\n\n"
-                "⚠️ **Research tool only** - Synthesizes evidence but cannot provide medical advice."
-            )
+
+            # About Section - Collapsible with details
+            with gr.Accordion("ℹ️ About", open=False):
+                gr.Markdown(
+                    "**The DETERMINATOR** - Generalist Deep Research Agent\n\n"
+                    "Stops at nothing until finding precise answers to complex questions.\n\n"
+                    "**How It Works**:\n"
+                    "- 🔍 Multi-source search (Web, PubMed, ClinicalTrials.gov, Europe PMC, RAG)\n"
+                    "- 🧠 Automatic medical knowledge detection\n"
+                    "- 🔄 Iterative refinement with search-judge loops\n"
+                    "- ⏹️ Continues until budget/time/iteration limits\n"
+                    "- 📊 Evidence synthesis with citations\n\n"
+                    "**Multimodal Input**:\n"
+                    "- 📷 **Images**: Click image icon in textbox (OCR)\n"
+                    "- 🎤 **Audio**: Click microphone icon (speech-to-text)\n"
+                    "- 📄 **Files**: Drag & drop or click to upload\n\n"
+                    "**MCP Server**: Connect Claude Desktop to `/gradio_api/mcp/`\n\n"
+                    "⚠️ **Research tool only** - Synthesizes evidence but cannot provide medical advice."
+                )
+
             gr.Markdown("---")
 
             # Settings Section - Organized in Accordions
@@ -924,231 +899,321 @@ def create_demo() -> gr.Blocks:
                     info="Process uploaded/recorded audio with speech-to-text",
                 )
 
-                # Audio Output Configuration
-                gr.Markdown("### 🔊 Audio Output (TTS)")
-
-                enable_audio_output_checkbox = gr.Checkbox(
-                    value=settings.enable_audio_output,
-                    label="Enable Audio Output",
-                    info="Generate audio responses using text-to-speech",
+            # Audio Output Configuration - Collapsible
+            with gr.Accordion("🔊 Audio Output (TTS)", open=False):
+                gr.Markdown(
+                    "**Generate audio for research responses on-demand.**\n\n"
+                    "Enter Modal keys below or set `MODAL_TOKEN_ID`/`MODAL_TOKEN_SECRET` in `.env` for local development."
                 )
 
-                tts_voice_dropdown = gr.Dropdown(
-                    choices=[
-                        "af_heart",
-                        "af_bella",
-                        "af_sarah",
-                        "af_sky",
-                        "af_nova",
-                        "af_shimmer",
-                        "af_echo",
-                        "af_fable",
-                        "af_onyx",
-                        "af_angel",
-                        "af_asteria",
-                        "af_jessica",
-                        "af_elli",
-                        "af_domi",
-                        "af_gigi",
-                        "af_freya",
-                        "af_glinda",
-                        "af_cora",
-                        "af_serena",
-                        "af_liv",
-                        "af_naomi",
-                        "af_rachel",
-                        "af_antoni",
-                        "af_thomas",
-                        "af_charlie",
-                        "af_emily",
-                        "af_george",
-                        "af_arnold",
-                        "af_adam",
-                        "af_sam",
-                        "af_paul",
-                        "af_josh",
-                        "af_daniel",
-                        "af_liam",
-                        "af_dave",
-                        "af_fin",
-                        "af_sarah",
-                        "af_glinda",
-                        "af_grace",
-                        "af_dorothy",
-                        "af_michael",
-                        "af_james",
-                        "af_joseph",
-                        "af_jeremy",
-                        "af_ryan",
-                        "af_oliver",
-                        "af_harry",
-                        "af_kyle",
-                        "af_leo",
-                        "af_otto",
-                        "af_owen",
-                        "af_pepper",
-                        "af_phil",
-                        "af_raven",
-                        "af_rocky",
-                        "af_rusty",
-                        "af_serena",
-                        "af_sky",
-                        "af_spark",
-                        "af_stella",
-                        "af_storm",
-                        "af_taylor",
-                        "af_vera",
-                        "af_will",
-                        "af_aria",
-                        "af_ash",
-                        "af_ballad",
-                        "af_bella",
-                        "af_breeze",
-                        "af_cove",
-                        "af_dusk",
-                        "af_ember",
-                        "af_flash",
-                        "af_flow",
-                        "af_glow",
-                        "af_harmony",
-                        "af_journey",
-                        "af_lullaby",
-                        "af_lyra",
-                        "af_melody",
-                        "af_midnight",
-                        "af_moon",
-                        "af_muse",
-                        "af_music",
-                        "af_narrator",
-                        "af_nightingale",
-                        "af_poet",
-                        "af_rain",
-                        "af_redwood",
-                        "af_rewind",
-                        "af_river",
-                        "af_sage",
-                        "af_seashore",
-                        "af_shadow",
-                        "af_silver",
-                        "af_song",
-                        "af_starshine",
-                        "af_story",
-                        "af_summer",
-                        "af_sun",
-                        "af_thunder",
-                        "af_tide",
-                        "af_time",
-                        "af_valentino",
-                        "af_verdant",
-                        "af_verse",
-                        "af_vibrant",
-                        "af_vivid",
-                        "af_warmth",
-                        "af_whisper",
-                        "af_wilderness",
-                        "af_willow",
-                        "af_winter",
-                        "af_wit",
-                        "af_witness",
-                        "af_wren",
-                        "af_writer",
-                        "af_zara",
-                        "af_zeus",
-                        "af_ziggy",
-                        "af_zoom",
-                        "af_river",
-                        "am_michael",
-                        "am_fenrir",
-                        "am_puck",
-                        "am_echo",
-                        "am_eric",
-                        "am_liam",
-                        "am_onyx",
-                        "am_santa",
-                        "am_adam",
-                    ],
-                    value=settings.tts_voice,
-                    label="TTS Voice",
-                    info="Select TTS voice (American English voices: af_*, am_*)",
+                with gr.Accordion("🔑 Modal Credentials (Optional)", open=False):
+                    modal_token_id_input = gr.Textbox(
+                        label="Modal Token ID",
+                        placeholder="ak-... (leave empty to use .env)",
+                        type="password",
+                        value="",
+                    )
+
+                    modal_token_secret_input = gr.Textbox(
+                        label="Modal Token Secret",
+                        placeholder="as-... (leave empty to use .env)",
+                        type="password",
+                        value="",
+                    )
+
+                with gr.Accordion("🎚️ Voice & Quality Settings", open=False):
+                    tts_voice_dropdown = gr.Dropdown(
+                        choices=[
+                            "af_heart",
+                            "af_bella",
+                            "af_sarah",
+                            "af_sky",
+                            "af_nova",
+                            "af_shimmer",
+                            "af_echo",
+                            "af_fable",
+                            "af_onyx",
+                            "af_angel",
+                            "af_asteria",
+                            "af_jessica",
+                            "af_elli",
+                            "af_domi",
+                            "af_gigi",
+                            "af_freya",
+                            "af_glinda",
+                            "af_cora",
+                            "af_serena",
+                            "af_liv",
+                            "af_naomi",
+                            "af_rachel",
+                            "af_antoni",
+                            "af_thomas",
+                            "af_charlie",
+                            "af_emily",
+                            "af_george",
+                            "af_arnold",
+                            "af_adam",
+                            "af_sam",
+                            "af_paul",
+                            "af_josh",
+                            "af_daniel",
+                            "af_liam",
+                            "af_dave",
+                            "af_fin",
+                            "af_sarah",
+                            "af_glinda",
+                            "af_grace",
+                            "af_dorothy",
+                            "af_michael",
+                            "af_james",
+                            "af_joseph",
+                            "af_jeremy",
+                            "af_ryan",
+                            "af_oliver",
+                            "af_harry",
+                            "af_kyle",
+                            "af_leo",
+                            "af_otto",
+                            "af_owen",
+                            "af_pepper",
+                            "af_phil",
+                            "af_raven",
+                            "af_rocky",
+                            "af_rusty",
+                            "af_serena",
+                            "af_sky",
+                            "af_spark",
+                            "af_stella",
+                            "af_storm",
+                            "af_taylor",
+                            "af_vera",
+                            "af_will",
+                            "af_aria",
+                            "af_ash",
+                            "af_ballad",
+                            "af_bella",
+                            "af_breeze",
+                            "af_cove",
+                            "af_dusk",
+                            "af_ember",
+                            "af_flash",
+                            "af_flow",
+                            "af_glow",
+                            "af_harmony",
+                            "af_journey",
+                            "af_lullaby",
+                            "af_lyra",
+                            "af_melody",
+                            "af_midnight",
+                            "af_moon",
+                            "af_muse",
+                            "af_music",
+                            "af_narrator",
+                            "af_nightingale",
+                            "af_poet",
+                            "af_rain",
+                            "af_redwood",
+                            "af_rewind",
+                            "af_river",
+                            "af_sage",
+                            "af_seashore",
+                            "af_shadow",
+                            "af_silver",
+                            "af_song",
+                            "af_starshine",
+                            "af_story",
+                            "af_summer",
+                            "af_sun",
+                            "af_thunder",
+                            "af_tide",
+                            "af_time",
+                            "af_valentino",
+                            "af_verdant",
+                            "af_verse",
+                            "af_vibrant",
+                            "af_vivid",
+                            "af_warmth",
+                            "af_whisper",
+                            "af_wilderness",
+                            "af_willow",
+                            "af_winter",
+                            "af_wit",
+                            "af_witness",
+                            "af_wren",
+                            "af_writer",
+                            "af_zara",
+                            "af_zeus",
+                            "af_ziggy",
+                            "af_zoom",
+                            "af_river",
+                            "am_michael",
+                            "am_fenrir",
+                            "am_puck",
+                            "am_echo",
+                            "am_eric",
+                            "am_liam",
+                            "am_onyx",
+                            "am_santa",
+                            "am_adam",
+                        ],
+                        value=settings.tts_voice,
+                        label="TTS Voice",
+                        info="Select TTS voice (American English voices: af_*, am_*)",
+                    )
+
+                    tts_speed_slider = gr.Slider(
+                        minimum=0.5,
+                        maximum=2.0,
+                        value=settings.tts_speed,
+                        step=0.1,
+                        label="TTS Speech Speed",
+                        info="Adjust TTS speech speed (0.5x to 2.0x)",
+                    )
+
+                    gr.Dropdown(
+                        choices=["T4", "A10", "A100", "L4", "L40S"],
+                        value=settings.tts_gpu or "T4",
+                        label="TTS GPU Type",
+                        info="Modal GPU type for TTS (T4 is cheapest, A100 is fastest). Note: GPU changes require app restart.",
+                        visible=settings.modal_available,
+                        interactive=False,  # GPU type set at function definition time, requires restart
+                    )
+
+                    tts_use_llm_polish_checkbox = gr.Checkbox(
+                        value=settings.tts_use_llm_polish,
+                        label="Use LLM Polish for Audio",
+                        info="Apply LLM-based final polish to remove remaining formatting artifacts (costs API calls)",
+                    )
+
+                tts_generate_button = gr.Button(
+                    "🎵 Generate Audio for Last Response",
+                    variant="primary",
+                    size="lg",
                 )
 
-                tts_speed_slider = gr.Slider(
-                    minimum=0.5,
-                    maximum=2.0,
-                    value=settings.tts_speed,
-                    step=0.1,
-                    label="TTS Speech Speed",
-                    info="Adjust TTS speech speed (0.5x to 2.0x)",
+                tts_status_text = gr.Markdown(
+                    "Click the button above to generate audio for the last research response.",
+                    elem_classes="tts-status",
                 )
 
-                gr.Dropdown(
-                    choices=["T4", "A10", "A100", "L4", "L40S"],
-                    value=settings.tts_gpu or "T4",
-                    label="TTS GPU Type",
-                    info="Modal GPU type for TTS (T4 is cheapest, A100 is fastest). Note: GPU changes require app restart.",
-                    visible=settings.modal_available,
-                    interactive=False,  # GPU type set at function definition time, requires restart
+                # Audio output component (for TTS response)
+                audio_output = gr.Audio(
+                    label="🔊 Audio Output",
+                    visible=True,
                 )
 
-                tts_use_llm_polish_checkbox = gr.Checkbox(
-                    value=settings.tts_use_llm_polish,
-                    label="Use LLM Polish for Audio",
-                    info="Apply LLM-based final polish to remove remaining formatting artifacts (costs API calls)",
-                    visible=settings.enable_audio_output,
-                )
+        # TTS on-demand generation handler
+        async def handle_tts_generation(
+            history: list[dict[str, Any]],
+            modal_token_id: str,
+            modal_token_secret: str,
+            voice: str,
+            speed: float,
+            use_llm_polish: bool,
+        ) -> tuple[Any | None, str]:
+            """Generate audio on-demand for the last response.
+
+            Args:
+                history: Chat history
+                modal_token_id: Modal token ID from UI
+                modal_token_secret: Modal token secret from UI
+                voice: TTS voice selection
+                speed: TTS speed
+                use_llm_polish: Enable LLM polish
+
+            Returns:
+                Tuple of (audio_output, status_message)
+            """
+            from src.services.tts_modal import generate_audio_on_demand
+
+            # Get last assistant message from history
+            # History is a list of tuples: [(user_msg, assistant_msg), ...]
+            if not history:
+                logger.warning("tts_no_history", history=history)
+                return None, "❌ No messages in history to generate audio for"
+
+            # Debug: Log history format
+            logger.info(
+                "tts_history_debug",
+                history_type=type(history).__name__,
+                history_length=len(history) if isinstance(history, list) else 0,
+                first_entry_type=type(history[0]).__name__
+                if isinstance(history, list) and len(history) > 0
+                else None,
+                first_entry_sample=str(history[0])[:200]
+                if isinstance(history, list) and len(history) > 0
+                else None,
+            )
 
-                # Audio output component (for TTS response) - moved to sidebar
-                audio_output = gr.Audio(
-                    label="🔊 Audio Response",
-                    visible=settings.enable_audio_output,
+            # Get the last assistant message (second element of last tuple)
+            last_message = None
+            if isinstance(history, list) and len(history) > 0:
+                last_entry = history[-1]
+                # ChatInterface format: (user_message, assistant_message)
+                if isinstance(last_entry, (tuple, list)) and len(last_entry) >= 2:
+                    last_message = last_entry[1]
+                    logger.info(
+                        "tts_extracted_from_tuple", message_type=type(last_message).__name__
+                    )
+                # Dict format: {"role": "assistant", "content": "..."}
+                elif isinstance(last_entry, dict):
+                    if last_entry.get("role") == "assistant":
+                        content = last_entry.get("content", "")
+                        # Content might be a list (multimodal) or string
+                        if isinstance(content, list):
+                            # Extract text from multimodal content list
+                            last_message = " ".join(str(item) for item in content if item)
+                        else:
+                            last_message = content
+                        logger.info(
+                            "tts_extracted_from_dict",
+                            message_type=type(content).__name__,
+                            message_length=len(last_message)
+                            if isinstance(last_message, str)
+                            else 0,
+                        )
+                else:
+                    logger.warning(
+                        "tts_unknown_format",
+                        entry_type=type(last_entry).__name__,
+                        entry=str(last_entry)[:200],
+                    )
+
+            # Also handle if last_message itself is a list
+            if isinstance(last_message, list):
+                last_message = " ".join(str(item) for item in last_message if item)
+
+            if not last_message or not isinstance(last_message, str) or not last_message.strip():
+                logger.error(
+                    "tts_no_message_found",
+                    last_message_type=type(last_message).__name__ if last_message else None,
+                    last_message_value=str(last_message)[:100] if last_message else None,
                 )
-
-        # Update TTS component visibility based on enable_audio_output_checkbox
-        # This must be after audio_output is defined
-        def update_tts_visibility(
-            enabled: bool,
-        ) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any], dict[str, Any]]:
-            """Update visibility of TTS components based on enable checkbox."""
-            return (
-                gr.update(visible=enabled),
-                gr.update(visible=enabled),
-                gr.update(visible=enabled),
-                gr.update(visible=enabled),
+                return None, "❌ No assistant response found in history"
+
+            # Generate audio
+            audio_output, status_message = await generate_audio_on_demand(
+                text=last_message,
+                modal_token_id=modal_token_id,
+                modal_token_secret=modal_token_secret,
+                voice=voice,
+                speed=speed,
+                use_llm_polish=use_llm_polish,
             )
 
-        enable_audio_output_checkbox.change(
-            fn=update_tts_visibility,
-            inputs=[enable_audio_output_checkbox],
-            outputs=[tts_voice_dropdown, tts_speed_slider, tts_use_llm_polish_checkbox, audio_output],
-        )
+            return audio_output, status_message
 
         # Chat interface with multimodal support
         # Examples are provided but will NOT run at startup (cache_examples=False)
         # Users must log in first before using examples or submitting queries
-        gr.ChatInterface(
+        chat_interface = gr.ChatInterface(
             fn=research_agent,
             multimodal=True,  # Enable multimodal input (text + images + audio)
             title="🔬 The DETERMINATOR",
             description=(
-                "*Generalist Deep Research Agent — stops at nothing until finding precise answers to complex questions*\n\n"
-                "---\n"
-                "**The DETERMINATOR** uses iterative search-and-judge loops to comprehensively investigate any research question. "
-                "It automatically determines if medical knowledge sources (PubMed, ClinicalTrials.gov) are needed and adapts its search strategy accordingly.\n\n"
-                "**Key Features**:\n"
-                "- 🔍 Multi-source search (Web, PubMed, ClinicalTrials.gov, Europe PMC, RAG)\n"
-                "- 🧠 Automatic medical knowledge detection\n"
-                "- 🔄 Iterative refinement until precise answers are found\n"
-                "- ⏹️ Stops only at configured limits (budget, time, iterations)\n"
-                "- 📊 Evidence synthesis with citations\n\n"
-                "**MCP Server Active**: Connect Claude Desktop to `/gradio_api/mcp/`\n\n"
-                "**📷🎤 Multimodal Input Support**:\n"
-                "- **Images**: Click the 📷 image icon in the textbox to upload images (OCR)\n"
-                "- **Audio**: Click the 🎤 microphone icon in the textbox to record audio (STT)\n"
-                "- **Files**: Drag & drop or click to upload image/audio files\n"
-                "- **Text**: Type your research questions directly\n\n"
-                "💡 **Tip**: Look for the 📷 and 🎤 icons in the text input box below!\n\n"
-                "Configure multimodal inputs in the sidebar settings.\n\n"
-                "**⚠️ Authentication Required**: Please **sign in with HuggingFace** above before using this application."
+                "*Generalist Deep Research Agent — stops at nothing until finding precise answers*\n\n"
+                "💡 **Quick Start**: Type your research question below. Use 📷 for images, 🎤 for audio.\n\n"
+                "⚠️ **Sign in with HuggingFace** (sidebar) before starting."
             ),
             examples=[
                 # When additional_inputs are provided, examples must be lists of lists
@@ -1211,15 +1276,26 @@ def create_demo() -> gr.Blocks:
                 use_graph_checkbox,
                 enable_image_input_checkbox,
                 enable_audio_input_checkbox,
-                tts_voice_dropdown,
-                tts_speed_slider,
-                tts_use_llm_polish_checkbox,
                 web_search_provider_dropdown,
                 # Note: gr.OAuthToken and gr.OAuthProfile are automatically passed as function parameters
             ],
             cache_examples=False,  # Don't cache examples - requires authentication
         )
 
+        # Wire up TTS generation button
+        tts_generate_button.click(
+            fn=handle_tts_generation,
+            inputs=[
+                chat_interface.chatbot,  # Get chat history from ChatInterface
+                modal_token_id_input,
+                modal_token_secret_input,
+                tts_voice_dropdown,
+                tts_speed_slider,
+                tts_use_llm_polish_checkbox,
+            ],
+            outputs=[audio_output, tts_status_text],
+        )
+
     return demo  # type: ignore[no-any-return]
 
 

src/mcp_tools.py

@@ -242,7 +242,6 @@ async def extract_text_from_image(
         Extracted text from the image
     """
     from src.services.image_ocr import get_image_ocr_service
-
     from src.utils.config import settings
 
     try:
@@ -280,7 +279,6 @@ async def transcribe_audio_file(
         Transcribed text from the audio file
     """
     from src.services.stt_gradio import get_stt_service
-
     from src.utils.config import settings
 
     try:
@@ -300,4 +298,4 @@ async def transcribe_audio_file(
         return f"## Audio Transcription\n\n{transcribed_text}"
 
     except Exception as e:
-        return f"Error transcribing audio: {e}"
+        return f"Error transcribing audio: {e}"

src/middleware/state_machine.py

@@ -169,14 +169,3 @@ def get_workflow_state() -> WorkflowState:
         logger.debug("Workflow state not found, auto-initializing")
         return init_workflow_state()
     return state
-
-
-
-
-
-
-
-
-
-
-

src/orchestrator/research_flow.py

@@ -219,7 +219,9 @@ class IterativeResearchFlow:
 
             # 4. Select tools for next gap
             next_gap = evaluation.outstanding_gaps[0] if evaluation.outstanding_gaps else query
-            selection_plan = await self._select_agents(next_gap, query, background_context, message_history)
+            selection_plan = await self._select_agents(
+                next_gap, query, background_context, message_history
+            )
 
             # 5. Execute tools
             await self._execute_tools(selection_plan.tasks)
@@ -324,7 +326,10 @@ class IterativeResearchFlow:
         return True
 
     async def _generate_observations(
-        self, query: str, background_context: str = "", message_history: list[ModelMessage] | None = None
+        self,
+        query: str,
+        background_context: str = "",
+        message_history: list[ModelMessage] | None = None,
     ) -> str:
         """Generate observations from current research state."""
         # Build input prompt for token estimation
@@ -364,7 +369,10 @@ ORIGINAL QUERY:
         return observations
 
     async def _evaluate_gaps(
-        self, query: str, background_context: str = "", message_history: list[ModelMessage] | None = None
+        self,
+        query: str,
+        background_context: str = "",
+        message_history: list[ModelMessage] | None = None,
     ) -> KnowledgeGapOutput:
         """Evaluate knowledge gaps in current research."""
         if self.start_time:
@@ -812,7 +820,9 @@ class DeepResearchFlow:
         else:
             return await self._run_with_chains(query, message_history)
 
-    async def _run_with_chains(self, query: str, message_history: list[ModelMessage] | None = None) -> str:
+    async def _run_with_chains(
+        self, query: str, message_history: list[ModelMessage] | None = None
+    ) -> str:
         """
         Run the deep research flow using agent chains.
 
@@ -868,7 +878,9 @@ class DeepResearchFlow:
 
         return final_report
 
-    async def _run_with_graph(self, query: str, message_history: list[ModelMessage] | None = None) -> str:
+    async def _run_with_graph(
+        self, query: str, message_history: list[ModelMessage] | None = None
+    ) -> str:
         """
         Run the deep research flow using graph execution.
 

src/services/audio_processing.py

@@ -105,13 +105,14 @@ class AudioService:
             # Refine text for audio (remove markdown, citations, etc.)
             # Use LLM polish if enabled in settings
             refined_text = await audio_refiner.refine_for_audio(
-                text,
-                use_llm_polish=settings.tts_use_llm_polish
+                text, use_llm_polish=settings.tts_use_llm_polish
+            )
+            logger.info(
+                "text_refined_for_audio",
+                original_length=len(text),
+                refined_length=len(refined_text),
+                llm_polish_enabled=settings.tts_use_llm_polish,
             )
-            logger.info("text_refined_for_audio",
-                       original_length=len(text),
-                       refined_length=len(refined_text),
-                       llm_polish_enabled=settings.tts_use_llm_polish)
 
             # Use provided voice/speed or fallback to settings defaults
             voice = voice if voice else settings.tts_voice

src/services/multimodal_processing.py

@@ -83,7 +83,9 @@ class MultimodalService:
                         # For now, log a warning
                         logger.warning("audio_file_upload_not_supported", file_path=file_path)
                     except Exception as e:
-                        logger.warning("audio_file_processing_failed", file_path=file_path, error=str(e))
+                        logger.warning(
+                            "audio_file_processing_failed", file_path=file_path, error=str(e)
+                        )
 
         # Add original text if present
         if text and text.strip():
@@ -142,7 +144,3 @@ def get_multimodal_service() -> MultimodalService:
         MultimodalService instance
     """
     return MultimodalService()
-
-
-
-

src/services/report_file_service.py

@@ -329,4 +329,3 @@ def get_report_file_service() -> ReportFileService:
         return ReportFileService()
 
     return _get_service()
-

src/services/tts_modal.py

@@ -2,15 +2,19 @@
 
 import asyncio
 import os
+from collections.abc import Iterator
+from contextlib import contextmanager
 from functools import lru_cache
-from typing import Any
+from typing import Any, cast
 
 import numpy as np
+from numpy.typing import NDArray
 import structlog
 
 # Load .env file BEFORE importing Modal SDK
 # Modal SDK reads MODAL_TOKEN_ID and MODAL_TOKEN_SECRET from environment on import
 from dotenv import load_dotenv
+
 load_dotenv()
 
 from src.utils.config import settings
@@ -33,6 +37,60 @@ _tts_function: Any | None = None
 _tts_image: Any | None = None
 
 
+@contextmanager
+def modal_credentials_override(token_id: str | None, token_secret: str | None) -> Iterator[None]:
+    """Context manager to temporarily override Modal credentials.
+
+    Args:
+        token_id: Modal token ID (overrides env if provided)
+        token_secret: Modal token secret (overrides env if provided)
+
+    Yields:
+        None
+
+    Note:
+        Resets global Modal state to force re-initialization with new credentials.
+    """
+    global _modal_app, _tts_function
+
+    # Save original credentials
+    original_token_id = os.environ.get("MODAL_TOKEN_ID")
+    original_token_secret = os.environ.get("MODAL_TOKEN_SECRET")
+
+    # Save original Modal state
+    original_app = _modal_app
+    original_function = _tts_function
+
+    try:
+        # Override environment variables if provided
+        if token_id:
+            os.environ["MODAL_TOKEN_ID"] = token_id
+        if token_secret:
+            os.environ["MODAL_TOKEN_SECRET"] = token_secret
+
+        # Reset Modal state to force re-initialization
+        _modal_app = None
+        _tts_function = None
+
+        yield
+
+    finally:
+        # Restore original credentials
+        if original_token_id is not None:
+            os.environ["MODAL_TOKEN_ID"] = original_token_id
+        elif "MODAL_TOKEN_ID" in os.environ:
+            del os.environ["MODAL_TOKEN_ID"]
+
+        if original_token_secret is not None:
+            os.environ["MODAL_TOKEN_SECRET"] = original_token_secret
+        elif "MODAL_TOKEN_SECRET" in os.environ:
+            del os.environ["MODAL_TOKEN_SECRET"]
+
+        # Restore original Modal state
+        _modal_app = original_app
+        _tts_function = original_function
+
+
 def _get_modal_app() -> Any:
     """Get or create Modal app instance.
 
@@ -69,7 +127,8 @@ def _get_modal_app() -> Any:
             )
 
             try:
-                _modal_app = modal.App("deepcritical-tts")
+                # Use lookup with create_if_missing for inline function fallback
+                _modal_app = modal.App.lookup("deepcritical-tts", create_if_missing=True)
             except Exception as e:
                 error_msg = str(e).lower()
                 if "token" in error_msg or "malformed" in error_msg or "invalid" in error_msg:
@@ -121,7 +180,7 @@ def _create_tts_function() -> Any:
 
     # Get GPU and timeout from settings (with defaults)
     gpu_type = getattr(settings, "tts_gpu", None) or "T4"
-    timeout_seconds = getattr(settings, "tts_timeout", None) or 60
+    timeout_seconds = getattr(settings, "tts_timeout", None) or 120  # 2 minutes for cold starts
 
     @app.function(
         image=tts_image,
@@ -129,7 +188,7 @@ def _create_tts_function() -> Any:
         timeout=timeout_seconds,
         serialized=True,  # Allow function to be defined outside global scope
     )
-    def kokoro_tts_function(text: str, voice: str, speed: float) -> tuple[int, np.ndarray]:
+    def kokoro_tts_function(text: str, voice: str, speed: float) -> tuple[int, NDArray[np.float32]]:
         """Modal GPU function for Kokoro TTS.
 
         This function runs on Modal's GPU infrastructure.
@@ -170,10 +229,13 @@ def _create_tts_function() -> Any:
 def _setup_modal_function() -> None:
     """Setup Modal GPU function for TTS (called once, lazy initialization).
 
-    Looks up the deployed Modal function instead of creating a new one.
-    This requires the 'deepcritical-tts' app to be deployed on Modal.
+    Hybrid approach:
+    1. Try to lookup pre-deployed function (fast path for advanced users)
+    2. If lookup fails, create function inline (fallback for casual users)
 
-    To deploy: modal deploy <script_with_tts_function>.py
+    This allows both workflows:
+    - Advanced: Deploy with `modal deploy deployments/modal_tts.py` for best performance
+    - Casual: Just add Modal keys and it auto-creates function on first use
     """
     global _tts_function
 
@@ -183,24 +245,38 @@ def _setup_modal_function() -> None:
     try:
         import modal
 
-        # Look up the deployed function from the Modal server
-        # This requires the app to be deployed: modal deploy tts_modal.py
-        _tts_function = modal.Function.from_name(
-            "deepcritical-tts",
-            "kokoro_tts_function"
-        )
+        # Try path 1: Lookup pre-deployed function (fast path)
+        try:
+            _tts_function = modal.Function.from_name("deepcritical-tts", "kokoro_tts_function")
+            logger.info(
+                "modal_tts_function_lookup_success",
+                app_name="deepcritical-tts",
+                function_name="kokoro_tts_function",
+                method="lookup",
+            )
+            return
+        except Exception as lookup_error:
+            logger.info(
+                "modal_tts_function_lookup_failed",
+                error=str(lookup_error),
+                fallback="Creating function inline",
+            )
 
+        # Try path 2: Create function inline (fallback for casual users)
+        logger.info("modal_tts_creating_inline_function")
+        _tts_function = _create_tts_function()
         logger.info(
-            "modal_tts_function_lookup_complete",
+            "modal_tts_function_setup_complete",
             app_name="deepcritical-tts",
             function_name="kokoro_tts_function",
+            method="inline",
         )
 
     except Exception as e:
         logger.error("modal_tts_function_setup_failed", error=str(e))
         raise ConfigurationError(
-            f"Failed to lookup Modal TTS function: {e}. "
-            "Make sure the 'deepcritical-tts' app is deployed on Modal."
+            f"Failed to setup Modal TTS function: {e}. "
+            "Ensure Modal credentials (MODAL_TOKEN_ID, MODAL_TOKEN_SECRET) are valid."
         ) from e
 
 
@@ -233,8 +309,8 @@ class ModalTTSExecutor:
         text: str,
         voice: str = "af_heart",
         speed: float = 1.0,
-        timeout: int = 60,
-    ) -> tuple[int, np.ndarray]:
+        timeout: int = 120,
+    ) -> tuple[int, NDArray[np.float32]]:
         """Synthesize text to speech using Kokoro on Modal GPU.
 
         Args:
@@ -259,7 +335,7 @@ class ModalTTSExecutor:
 
         try:
             # Call the GPU function remotely
-            result = _tts_function.remote(text, voice, speed)
+            result = cast(tuple[int, NDArray[np.float32]], _tts_function.remote(text, voice, speed))
 
             logger.info(
                 "tts_synthesis_complete", sample_rate=result[0], audio_shape=result[1].shape
@@ -296,7 +372,7 @@ class TTSService:
         text: str,
         voice: str = "af_heart",
         speed: float = 1.0,
-    ) -> tuple[int, np.ndarray] | None:
+    ) -> tuple[int, NDArray[np.float32]] | None:
         """Async wrapper for TTS synthesis.
 
         Args:
@@ -334,3 +410,73 @@ def get_tts_service() -> TTSService:
         ConfigurationError: If Modal credentials not configured
     """
     return TTSService()
+
+
+async def generate_audio_on_demand(
+    text: str,
+    modal_token_id: str | None = None,
+    modal_token_secret: str | None = None,
+    voice: str = "af_heart",
+    speed: float = 1.0,
+    use_llm_polish: bool = False,
+) -> tuple[tuple[int, NDArray[np.float32]] | None, str]:
+    """Generate audio on-demand with optional runtime credentials.
+
+    Args:
+        text: Text to synthesize
+        modal_token_id: Modal token ID (UI input, overrides .env)
+        modal_token_secret: Modal token secret (UI input, overrides .env)
+        voice: Voice ID (default: af_heart)
+        speed: Speech speed (default: 1.0)
+        use_llm_polish: Apply LLM polish to text (default: False)
+
+    Returns:
+        Tuple of (audio_output, status_message)
+        - audio_output: (sample_rate, audio_array) or None if failed
+        - status_message: Status/error message for user
+
+    Priority: UI credentials > .env credentials
+    """
+    # Priority: UI keys > .env keys
+    token_id = (modal_token_id or "").strip() or os.getenv("MODAL_TOKEN_ID")
+    token_secret = (modal_token_secret or "").strip() or os.getenv("MODAL_TOKEN_SECRET")
+
+    if not token_id or not token_secret:
+        return (
+            None,
+            "❌ Modal credentials required. Enter keys above or set MODAL_TOKEN_ID and MODAL_TOKEN_SECRET in .env",
+        )
+
+    try:
+        # Use credentials override context
+        with modal_credentials_override(token_id, token_secret):
+            # Import audio_processing here to avoid circular import
+            from src.services.audio_processing import AudioService
+
+            # Temporarily override LLM polish setting
+            original_llm_polish = settings.tts_use_llm_polish
+            try:
+                settings.tts_use_llm_polish = use_llm_polish
+
+                # Create fresh AudioService instance (bypass cache to pick up new credentials)
+                audio_service = AudioService()
+                audio_output = await audio_service.generate_audio_output(
+                    text=text,
+                    voice=voice,
+                    speed=speed,
+                )
+
+                if audio_output:
+                    return audio_output, "✅ Audio generated successfully"
+                else:
+                    return None, "⚠️ Audio generation returned no output"
+
+            finally:
+                settings.tts_use_llm_polish = original_llm_polish
+
+    except ConfigurationError as e:
+        logger.error("audio_generation_config_error", error=str(e))
+        return None, f"❌ Configuration error: {e}"
+    except Exception as e:
+        logger.error("audio_generation_failed", error=str(e), exc_info=True)
+        return None, f"❌ Audio generation failed: {e}"

src/tools/crawl_adapter.py

@@ -56,8 +56,3 @@ async def crawl_website(starting_url: str) -> str:
     except Exception as e:
         logger.error("Crawl failed", error=str(e), url=starting_url)
         return f"Error crawling website: {e!s}"
-
-
-
-
-

src/tools/search_handler.py

@@ -5,11 +5,11 @@ from typing import TYPE_CHECKING, cast
 
 import structlog
 
+from src.services.neo4j_service import get_neo4j_service
 from src.tools.base import SearchTool
 from src.tools.rag_tool import create_rag_tool
 from src.utils.exceptions import ConfigurationError, SearchError
 from src.utils.models import Evidence, SearchResult, SourceName
-from src.services.neo4j_service import get_neo4j_service
 
 if TYPE_CHECKING:
     from src.services.llamaindex_rag import LlamaIndexRAGService
@@ -133,7 +133,15 @@ class SearchHandler:
 
                 # Map tool.name to SourceName (handle tool names that don't match SourceName literals)
                 tool_name = tool_name_to_source.get(tool.name, cast(SourceName, tool.name))
-                if tool_name not in ["pubmed", "clinicaltrials", "biorxiv", "europepmc", "preprint", "rag", "web"]:
+                if tool_name not in [
+                    "pubmed",
+                    "clinicaltrials",
+                    "biorxiv",
+                    "europepmc",
+                    "preprint",
+                    "rag",
+                    "web",
+                ]:
                     logger.warning(
                         "Tool name not in SourceName literals, defaulting to 'web'",
                         tool_name=tool.name,
@@ -175,18 +183,20 @@ class SearchHandler:
                     disease = query
                     if "for" in query.lower():
                         disease = query.split("for")[-1].strip().rstrip("?")
-                    
+
                     # Convert Evidence objects to dicts for Neo4j
                     papers = []
                     for ev in all_evidence:
-                        papers.append({
-                            'id': ev.citation.url or '',
-                            'title': ev.citation.title or '',
-                            'abstract': ev.content,
-                            'url': ev.citation.url or '',
-                            'source': ev.citation.source,
-                        })
-                    
+                        papers.append(
+                            {
+                                "id": ev.citation.url or "",
+                                "title": ev.citation.title or "",
+                                "abstract": ev.content,
+                                "url": ev.citation.url or "",
+                                "source": ev.citation.source,
+                            }
+                        )
+
                     stats = neo4j_service.ingest_search_results(disease, papers)
                     logger.info("💾 Saved to Neo4j", stats=stats)
             except Exception as e:

src/tools/searchxng_web_search.py

@@ -89,7 +89,7 @@ class SearchXNGWebSearchTool:
                 title = result.title
                 if len(title) > 500:
                     title = title[:497] + "..."
-                
+
                 ev = Evidence(
                     content=result.text,
                     citation=Citation(
@@ -118,18 +118,3 @@ class SearchXNGWebSearchTool:
         except Exception as e:
             logger.error("Unexpected error in SearchXNG search", error=str(e), query=final_query)
             raise SearchError(f"SearchXNG search failed: {e}") from e
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

src/tools/serper_web_search.py

@@ -89,7 +89,7 @@ class SerperWebSearchTool:
                 title = result.title
                 if len(title) > 500:
                     title = title[:497] + "..."
-                
+
                 ev = Evidence(
                     content=result.text,
                     citation=Citation(
@@ -118,18 +118,3 @@ class SerperWebSearchTool:
         except Exception as e:
             logger.error("Unexpected error in Serper search", error=str(e), query=final_query)
             raise SearchError(f"Serper search failed: {e}") from e
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

src/tools/tool_executor.py

@@ -182,9 +182,9 @@ async def execute_tool_tasks(
             results[f"{task.agent}_{i}"] = ToolAgentOutput(output=f"Error: {result!s}", sources=[])
         else:
             # Type narrowing: result is ToolAgentOutput after Exception check
-            assert isinstance(
-                result, ToolAgentOutput
-            ), "Expected ToolAgentOutput after Exception check"
+            assert isinstance(result, ToolAgentOutput), (
+                "Expected ToolAgentOutput after Exception check"
+            )
             key = f"{task.agent}_{task.gap or i}" if task.gap else f"{task.agent}_{i}"
             results[key] = result
 

src/tools/vendored/__init__.py

@@ -16,12 +16,12 @@ from src.tools.vendored.web_search_core import (
 __all__ = [
     "CONTENT_LENGTH_LIMIT",
     "ScrapeResult",
-    "WebpageSnippet",
-    "SerperClient",
     "SearchXNGClient",
-    "scrape_urls",
+    "SerperClient",
+    "WebpageSnippet",
+    "crawl_website",
     "fetch_and_process_url",
     "html_to_text",
     "is_valid_url",
-    "crawl_website",
+    "scrape_urls",
 ]

src/tools/web_search.py

@@ -3,6 +3,7 @@
 import asyncio
 
 import structlog
+
 try:
     from ddgs import DDGS  # New package name
 except ImportError:
@@ -59,7 +60,7 @@ class WebSearchTool:
                 title = r.get("title", "No Title")
                 if len(title) > 500:
                     title = title[:497] + "..."
-                
+
                 ev = Evidence(
                     content=r.get("body", ""),
                     citation=Citation(

src/tools/web_search_adapter.py

@@ -53,11 +53,3 @@ async def web_search(query: str) -> str:
     except Exception as e:
         logger.error("Web search failed", error=str(e), query=query)
         return f"Error performing web search: {e!s}"
-
-
-
-
-
-
-
-

src/tools/web_search_factory.py

@@ -50,7 +50,7 @@ def create_web_search_tool(provider: str | None = None) -> SearchTool | None:
                     "Failed to initialize Serper, falling back",
                     error=str(e),
                 )
-        
+
         # Try SearchXNG as second choice
         if settings.searchxng_host:
             try:
@@ -64,7 +64,7 @@ def create_web_search_tool(provider: str | None = None) -> SearchTool | None:
                     "Failed to initialize SearchXNG, falling back",
                     error=str(e),
                 )
-        
+
         # Fall back to DuckDuckGo
         if provider == "auto":
             logger.info(
@@ -113,18 +113,3 @@ def create_web_search_tool(provider: str | None = None) -> SearchTool | None:
     except Exception as e:
         logger.error("Unexpected error creating web search tool", error=str(e), provider=provider)
         return None
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

src/utils/config.py

@@ -77,9 +77,11 @@ class Settings(BaseSettings):
     )
 
     # Web Search Configuration
-    web_search_provider: Literal["serper", "searchxng", "brave", "tavily", "duckduckgo", "auto"] = Field(
-        default="auto",
-        description="Web search provider to use. 'auto' will auto-detect best available (prefers Serper > SearchXNG > DuckDuckGo)",
+    web_search_provider: Literal["serper", "searchxng", "brave", "tavily", "duckduckgo", "auto"] = (
+        Field(
+            default="auto",
+            description="Web search provider to use. 'auto' will auto-detect best available (prefers Serper > SearchXNG > DuckDuckGo)",
+        )
     )
     serper_api_key: str | None = Field(default=None, description="Serper API key for Google search")
     searchxng_host: str | None = Field(default=None, description="SearchXNG host URL")
@@ -284,10 +286,10 @@ class Settings(BaseSettings):
 
     def get_hf_fallback_models_list(self) -> list[str]:
         """Get the list of fallback models as a list.
-        
+
         Parses the comma-separated HF_FALLBACK_MODELS string into a list,
         stripping whitespace from each model ID.
-        
+
         Returns:
             List of model IDs
         """

src/utils/llm_factory.py

@@ -102,7 +102,7 @@ def get_chat_client_for_agent(oauth_token: str | None = None) -> Any:
     """
     # Check if we have OAuth token or env vars
     has_hf_key = bool(oauth_token or settings.has_huggingface_key)
-    
+
     # Prefer HuggingFace if available (free tier)
     if has_hf_key:
         return get_huggingface_chat_client(oauth_token=oauth_token)

src/utils/models.py

@@ -6,7 +6,9 @@ from typing import Any, ClassVar, Literal
 from pydantic import BaseModel, Field
 
 # Centralized source type - add new sources here (e.g., "biorxiv" in Phase 11)
-SourceName = Literal["pubmed", "clinicaltrials", "biorxiv", "europepmc", "preprint", "rag", "web", "neo4j"]
+SourceName = Literal[
+    "pubmed", "clinicaltrials", "biorxiv", "europepmc", "preprint", "rag", "web", "neo4j"
+]
 
 
 class Citation(BaseModel):