attempts to solve the api_key issue for huggingface , settings not appearing , set settings for audio , adds modal gpu , speech to text with mic input addon, adds graphs

docs/api/agents.md

@@ -270,3 +270,4 @@ def create_input_parser_agent(model: Any | None = None) -> InputParserAgent
 
 
 
+

docs/api/models.md

@@ -248,3 +248,4 @@ class BudgetStatus(BaseModel):
 
 
 
+

docs/api/orchestrators.md

@@ -195,3 +195,4 @@ Runs Magentic orchestration.
 
 
 
+

docs/api/services.md

@@ -201,3 +201,4 @@ Analyzes a hypothesis using statistical methods.
 
 
 
+

docs/api/tools.md

@@ -235,3 +235,4 @@ Searches multiple tools in parallel.
 
 
 
+

docs/architecture/agents.md

@@ -192,3 +192,4 @@ Factory functions:
 
 
 
+

docs/architecture/middleware.md

@@ -142,3 +142,4 @@ All middleware components use `ContextVar` for thread-safe isolation:
 
 
 
+

docs/architecture/services.md

@@ -142,3 +142,4 @@ if settings.has_openai_key:
 
 
 
+

docs/architecture/tools.md

@@ -175,3 +175,4 @@ search_handler = SearchHandler(
 
 
 
+

docs/contributing/code-quality.md

@@ -81,3 +81,4 @@ async def search(self, query: str, max_results: int = 10) -> list[Evidence]:
 
 
 
+

docs/contributing/code-style.md

@@ -61,3 +61,4 @@ result = await loop.run_in_executor(None, cpu_bound_function, args)
 
 
 
+

docs/contributing/error-handling.md

@@ -69,3 +69,4 @@ except httpx.HTTPError as e:
 
 
 
+

docs/contributing/implementation-patterns.md

@@ -84,3 +84,4 @@ def get_embedding_service() -> EmbeddingService:
 
 
 
+

docs/contributing/index.md

@@ -163,3 +163,4 @@ Thank you for contributing to DeepCritical!
 
 
 
+

docs/contributing/prompt-engineering.md

@@ -69,3 +69,4 @@ This document outlines prompt engineering guidelines and citation validation rul
 
 
 
+

docs/contributing/testing.md

@@ -65,3 +65,4 @@ async def test_real_pubmed_search():
 
 
 
+

docs/getting-started/examples.md

@@ -209,3 +209,4 @@ USE_GRAPH_EXECUTION=true
 
 
 
+

docs/getting-started/installation.md

@@ -148,3 +148,4 @@ uv run pre-commit install
 
 
 
+

docs/getting-started/mcp-integration.md

@@ -215,3 +215,4 @@ You can configure multiple DeepCritical instances:
 
 
 
+

docs/getting-started/quick-start.md

@@ -119,3 +119,4 @@ What are the active clinical trials investigating Alzheimer's disease treatments
 
 
 
+

docs/implementation/IMPLEMENTATION_SUMMARY.md

@@ -178,3 +178,4 @@ Located in `src/app.py` lines 667-712:
 
 
 
+

docs/implementation/TTS_MODAL_IMPLEMENTATION.md

@@ -132,3 +132,4 @@ To test TTS:
 
 
 
+

docs/license.md

@@ -39,3 +39,4 @@ SOFTWARE.
 
 
 
+

docs/overview/architecture.md

@@ -196,3 +196,4 @@ The system supports complex research workflows through:
 
 
 
+

docs/overview/features.md

@@ -148,3 +148,4 @@ DeepCritical provides a comprehensive set of features for AI-assisted research:
 
 
 
+

docs/team.md

@@ -44,3 +44,4 @@ We welcome contributions! See the [Contributing Guide](contributing/index.md) fo
 
 
 
+

new_env.txt

@@ -94,3 +94,4 @@ MODAL_TOKEN_SECRET=your_modal_token_secret_here
 
 
 
+

src/agent_factory/agents.py

@@ -27,12 +27,13 @@ if TYPE_CHECKING:
 logger = structlog.get_logger()
 
 
-def create_input_parser_agent(model: Any | 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.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured InputParserAgent instance
@@ -44,18 +45,19 @@ def create_input_parser_agent(model: Any | None = None) -> "InputParserAgent":
 
     try:
         logger.debug("Creating input parser agent")
-        return _create_agent(model=model)
+        return _create_agent(model=model, oauth_token=oauth_token)
     except Exception as e:
         logger.error("Failed to create input parser agent", error=str(e))
         raise ConfigurationError(f"Failed to create input parser agent: {e}") from e
 
 
-def create_planner_agent(model: Any | 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.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured PlannerAgent instance
@@ -68,18 +70,19 @@ def create_planner_agent(model: Any | None = None) -> "PlannerAgent":
 
     try:
         logger.debug("Creating planner agent")
-        return _create_planner_agent(model=model)
+        return _create_planner_agent(model=model, oauth_token=oauth_token)
     except Exception as e:
         logger.error("Failed to create planner agent", error=str(e))
         raise ConfigurationError(f"Failed to create planner agent: {e}") from e
 
 
-def create_knowledge_gap_agent(model: Any | 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.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured KnowledgeGapAgent instance
@@ -91,18 +94,19 @@ def create_knowledge_gap_agent(model: Any | None = None) -> "KnowledgeGapAgent":
 
     try:
         logger.debug("Creating knowledge gap agent")
-        return _create_agent(model=model)
+        return _create_agent(model=model, oauth_token=oauth_token)
     except Exception as e:
         logger.error("Failed to create knowledge gap agent", error=str(e))
         raise ConfigurationError(f"Failed to create knowledge gap agent: {e}") from e
 
 
-def create_tool_selector_agent(model: Any | 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.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured ToolSelectorAgent instance
@@ -114,18 +118,19 @@ def create_tool_selector_agent(model: Any | None = None) -> "ToolSelectorAgent":
 
     try:
         logger.debug("Creating tool selector agent")
-        return _create_agent(model=model)
+        return _create_agent(model=model, oauth_token=oauth_token)
     except Exception as e:
         logger.error("Failed to create tool selector agent", error=str(e))
         raise ConfigurationError(f"Failed to create tool selector agent: {e}") from e
 
 
-def create_thinking_agent(model: Any | None = None) -> "ThinkingAgent":
+def create_thinking_agent(model: Any | None = None, oauth_token: str | None = None) -> "ThinkingAgent":
     """
     Create thinking agent for generating observations.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured ThinkingAgent instance
@@ -137,18 +142,19 @@ def create_thinking_agent(model: Any | None = None) -> "ThinkingAgent":
 
     try:
         logger.debug("Creating thinking agent")
-        return _create_agent(model=model)
+        return _create_agent(model=model, oauth_token=oauth_token)
     except Exception as e:
         logger.error("Failed to create thinking agent", error=str(e))
         raise ConfigurationError(f"Failed to create thinking agent: {e}") from e
 
 
-def create_writer_agent(model: Any | None = None) -> "WriterAgent":
+def create_writer_agent(model: Any | None = None, oauth_token: str | None = None) -> "WriterAgent":
     """
     Create writer agent for generating final reports.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured WriterAgent instance
@@ -160,18 +166,19 @@ def create_writer_agent(model: Any | None = None) -> "WriterAgent":
 
     try:
         logger.debug("Creating writer agent")
-        return _create_agent(model=model)
+        return _create_agent(model=model, oauth_token=oauth_token)
     except Exception as e:
         logger.error("Failed to create writer agent", error=str(e))
         raise ConfigurationError(f"Failed to create writer agent: {e}") from e
 
 
-def create_long_writer_agent(model: Any | 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.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured LongWriterAgent instance
@@ -183,18 +190,19 @@ def create_long_writer_agent(model: Any | None = None) -> "LongWriterAgent":
 
     try:
         logger.debug("Creating long writer agent")
-        return _create_agent(model=model)
+        return _create_agent(model=model, oauth_token=oauth_token)
     except Exception as e:
         logger.error("Failed to create long writer agent", error=str(e))
         raise ConfigurationError(f"Failed to create long writer agent: {e}") from e
 
 
-def create_proofreader_agent(model: Any | None = None) -> "ProofreaderAgent":
+def create_proofreader_agent(model: Any | None = None, oauth_token: str | None = None) -> "ProofreaderAgent":
     """
     Create proofreader agent for finalizing report drafts.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured ProofreaderAgent instance
@@ -206,7 +214,7 @@ def create_proofreader_agent(model: Any | None = None) -> "ProofreaderAgent":
 
     try:
         logger.debug("Creating proofreader agent")
-        return _create_agent(model=model)
+        return _create_agent(model=model, oauth_token=oauth_token)
     except Exception as e:
         logger.error("Failed to create proofreader agent", error=str(e))
         raise ConfigurationError(f"Failed to create proofreader agent: {e}") from e

src/agent_factory/judges.py

@@ -32,34 +32,60 @@ def get_model(oauth_token: str | None = None) -> Any:
     Explicitly passes API keys from settings to avoid requiring
     users to export environment variables manually.
 
+    Priority: 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.
+
     Args:
         oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
     """
-    llm_provider = settings.llm_provider
-
     # Priority: oauth_token > env vars
     effective_hf_token = oauth_token or settings.hf_token or settings.huggingface_api_key
 
+    # If OAuth token is available, prefer HuggingFace (free tier on Spaces)
+    if effective_hf_token:
+        model_name = settings.huggingface_model or "meta-llama/Llama-3.1-8B-Instruct"
+        hf_provider = HuggingFaceProvider(api_key=effective_hf_token)
+        logger.info(
+            "using_huggingface_with_token",
+            has_oauth=bool(oauth_token),
+            model=model_name,
+        )
+        return HuggingFaceModel(model_name, provider=hf_provider)
+
+    llm_provider = settings.llm_provider
+
     if llm_provider == "anthropic":
+        if not settings.anthropic_api_key:
+            logger.warning("Anthropic provider selected but no API key available, defaulting to HuggingFace")
+            # Fallback to HuggingFace without token (public models)
+            model_name = settings.huggingface_model or "meta-llama/Llama-3.1-8B-Instruct"
+            hf_provider = HuggingFaceProvider(api_key=None)
+            return HuggingFaceModel(model_name, provider=hf_provider)
         provider = AnthropicProvider(api_key=settings.anthropic_api_key)
         return AnthropicModel(settings.anthropic_model, provider=provider)
 
     if llm_provider == "huggingface":
-        # Free tier - uses OAuth token or HF_TOKEN from environment if available
+        # No token available, use public models
         model_name = settings.huggingface_model or "meta-llama/Llama-3.1-8B-Instruct"
-        hf_provider = HuggingFaceProvider(api_key=effective_hf_token)
+        hf_provider = HuggingFaceProvider(api_key=None)
         return HuggingFaceModel(model_name, provider=hf_provider)
 
     if llm_provider == "openai":
+        if not settings.openai_api_key:
+            logger.warning("OpenAI provider selected but no API key available, defaulting to HuggingFace")
+            # Fallback to HuggingFace without token (public models)
+            model_name = settings.huggingface_model or "meta-llama/Llama-3.1-8B-Instruct"
+            hf_provider = HuggingFaceProvider(api_key=None)
+            return HuggingFaceModel(model_name, provider=hf_provider)
         openai_provider = OpenAIProvider(api_key=settings.openai_api_key)
         return OpenAIModel(settings.openai_model, provider=openai_provider)
 
     # Default to HuggingFace if provider is unknown or not specified
-    if llm_provider != "huggingface":
+    if llm_provider not in ("huggingface", "openai", "anthropic"):
         logger.warning("Unknown LLM provider, defaulting to HuggingFace", provider=llm_provider)
 
     model_name = settings.huggingface_model or "meta-llama/Llama-3.1-8B-Instruct"
-    hf_provider = HuggingFaceProvider(api_key=effective_hf_token)
+    hf_provider = HuggingFaceProvider(api_key=None)  # Public models
     return HuggingFaceModel(model_name, provider=hf_provider)
 
 

src/agents/input_parser.py

@@ -152,12 +152,13 @@ class InputParserAgent:
             )
 
 
-def create_input_parser_agent(model: Any | None = None) -> InputParserAgent:
+def create_input_parser_agent(model: Any | None = None, oauth_token: str | None = None) -> InputParserAgent:
     """
     Factory function to create an input parser agent.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured InputParserAgent instance
@@ -168,7 +169,7 @@ def create_input_parser_agent(model: Any | None = None) -> InputParserAgent:
     try:
         # Get model from settings if not provided
         if model is None:
-            model = get_model()
+            model = get_model(oauth_token=oauth_token)
 
         # Create and return input parser agent
         return InputParserAgent(model=model)

src/agents/knowledge_gap.py

@@ -132,12 +132,13 @@ HISTORY OF ACTIONS, FINDINGS AND THOUGHTS:
             )
 
 
-def create_knowledge_gap_agent(model: Any | 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.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured KnowledgeGapAgent instance
@@ -147,7 +148,7 @@ def create_knowledge_gap_agent(model: Any | None = None) -> KnowledgeGapAgent:
     """
     try:
         if model is None:
-            model = get_model()
+            model = get_model(oauth_token=oauth_token)
 
         return KnowledgeGapAgent(model=model)
 

src/agents/long_writer.py

@@ -407,12 +407,13 @@ class LongWriterAgent:
         return re.sub(r"^(#+)\s(.+)$", adjust_heading_level, section_markdown, flags=re.MULTILINE)
 
 
-def create_long_writer_agent(model: Any | 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.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured LongWriterAgent instance
@@ -422,7 +423,7 @@ def create_long_writer_agent(model: Any | None = None) -> LongWriterAgent:
     """
     try:
         if model is None:
-            model = get_model()
+            model = get_model(oauth_token=oauth_token)
 
         return LongWriterAgent(model=model)
 

src/agents/proofreader.py

@@ -181,12 +181,13 @@ 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) -> ProofreaderAgent:
+def create_proofreader_agent(model: Any | None = None, oauth_token: str | None = None) -> ProofreaderAgent:
     """
     Factory function to create a proofreader agent.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured ProofreaderAgent instance
@@ -196,7 +197,7 @@ def create_proofreader_agent(model: Any | None = None) -> ProofreaderAgent:
     """
     try:
         if model is None:
-            model = get_model()
+            model = get_model(oauth_token=oauth_token)
 
         return ProofreaderAgent(model=model)
 

src/agents/thinking.py

@@ -124,12 +124,13 @@ 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) -> ThinkingAgent:
+def create_thinking_agent(model: Any | None = None, oauth_token: str | None = None) -> ThinkingAgent:
     """
     Factory function to create a thinking agent.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured ThinkingAgent instance
@@ -139,7 +140,7 @@ def create_thinking_agent(model: Any | None = None) -> ThinkingAgent:
     """
     try:
         if model is None:
-            model = get_model()
+            model = get_model(oauth_token=oauth_token)
 
         return ThinkingAgent(model=model)
 

src/agents/tool_selector.py

@@ -144,12 +144,13 @@ HISTORY OF ACTIONS, FINDINGS AND THOUGHTS:
             )
 
 
-def create_tool_selector_agent(model: Any | 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.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured ToolSelectorAgent instance
@@ -159,7 +160,7 @@ def create_tool_selector_agent(model: Any | None = None) -> ToolSelectorAgent:
     """
     try:
         if model is None:
-            model = get_model()
+            model = get_model(oauth_token=oauth_token)
 
         return ToolSelectorAgent(model=model)
 

src/agents/writer.py

@@ -185,12 +185,13 @@ FINDINGS:
         )
 
 
-def create_writer_agent(model: Any | None = None) -> WriterAgent:
+def create_writer_agent(model: Any | None = None, oauth_token: str | None = None) -> WriterAgent:
     """
     Factory function to create a writer agent.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured WriterAgent instance
@@ -200,7 +201,7 @@ def create_writer_agent(model: Any | None = None) -> WriterAgent:
     """
     try:
         if model is None:
-            model = get_model()
+            model = get_model(oauth_token=oauth_token)
 
         return WriterAgent(model=model)
 

src/middleware/state_machine.py

@@ -133,3 +133,4 @@ def get_workflow_state() -> WorkflowState:
 
 
 
+

src/orchestrator/graph_orchestrator.py

@@ -124,6 +124,7 @@ class GraphOrchestrator:
         use_graph: bool = True,
         search_handler: SearchHandlerProtocol | None = None,
         judge_handler: JudgeHandlerProtocol | None = None,
+        oauth_token: str | None = None,
     ) -> None:
         """
         Initialize graph orchestrator.
@@ -135,6 +136,7 @@ class GraphOrchestrator:
             use_graph: Whether to use graph execution (True) or agent chains (False)
             search_handler: Optional search handler for tool execution
             judge_handler: Optional judge handler for evidence assessment
+            oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
         """
         self.mode = mode
         self.max_iterations = max_iterations
@@ -142,6 +144,7 @@ class GraphOrchestrator:
         self.use_graph = use_graph
         self.search_handler = search_handler
         self.judge_handler = judge_handler
+        self.oauth_token = oauth_token
         self.logger = logger
 
         # Initialize flows (for backward compatibility)
@@ -256,6 +259,7 @@ class GraphOrchestrator:
                     max_iterations=self.max_iterations,
                     max_time_minutes=self.max_time_minutes,
                     judge_handler=self.judge_handler,
+                    oauth_token=self.oauth_token,
                 )
 
             try:
@@ -291,6 +295,7 @@ class GraphOrchestrator:
                 self._deep_flow = DeepResearchFlow(
                     max_iterations=self.max_iterations,
                     max_time_minutes=self.max_time_minutes,
+                    oauth_token=self.oauth_token,
                 )
 
             try:
@@ -322,11 +327,11 @@ class GraphOrchestrator:
             Constructed ResearchGraph
         """
         if mode == "iterative":
-            # Get agents
-            knowledge_gap_agent = create_knowledge_gap_agent()
-            tool_selector_agent = create_tool_selector_agent()
-            thinking_agent = create_thinking_agent()
-            writer_agent = create_writer_agent()
+            # Get agents - pass OAuth token for HuggingFace authentication
+            knowledge_gap_agent = create_knowledge_gap_agent(oauth_token=self.oauth_token)
+            tool_selector_agent = create_tool_selector_agent(oauth_token=self.oauth_token)
+            thinking_agent = create_thinking_agent(oauth_token=self.oauth_token)
+            writer_agent = create_writer_agent(oauth_token=self.oauth_token)
 
             # Create graph
             graph = create_iterative_graph(
@@ -336,13 +341,13 @@ class GraphOrchestrator:
                 writer_agent=writer_agent.agent,
             )
         else:  # deep
-            # Get agents
-            planner_agent = create_planner_agent()
-            knowledge_gap_agent = create_knowledge_gap_agent()
-            tool_selector_agent = create_tool_selector_agent()
-            thinking_agent = create_thinking_agent()
-            writer_agent = create_writer_agent()
-            long_writer_agent = create_long_writer_agent()
+            # Get agents - pass OAuth token for HuggingFace authentication
+            planner_agent = create_planner_agent(oauth_token=self.oauth_token)
+            knowledge_gap_agent = create_knowledge_gap_agent(oauth_token=self.oauth_token)
+            tool_selector_agent = create_tool_selector_agent(oauth_token=self.oauth_token)
+            thinking_agent = create_thinking_agent(oauth_token=self.oauth_token)
+            writer_agent = create_writer_agent(oauth_token=self.oauth_token)
+            long_writer_agent = create_long_writer_agent(oauth_token=self.oauth_token)
 
             # Create graph
             graph = create_deep_graph(
@@ -610,7 +615,7 @@ class GraphOrchestrator:
             )
 
             # Get LongWriterAgent instance and call write_report directly
-            long_writer_agent = create_long_writer_agent()
+            long_writer_agent = create_long_writer_agent(oauth_token=self.oauth_token)
             final_report = await long_writer_agent.write_report(
                 original_query=query,
                 report_title=report_plan.report_title,
@@ -906,6 +911,7 @@ class GraphOrchestrator:
                     verbose=False,  # Less verbose in parallel execution
                     use_graph=False,  # Use agent chains for section research
                     judge_handler=self.judge_handler or judge_handler,
+                    oauth_token=self.oauth_token,
                 )
 
                 # Run research for this section
@@ -1008,7 +1014,7 @@ class GraphOrchestrator:
         """
         try:
             # Use input parser agent for intelligent mode detection
-            input_parser = create_input_parser_agent()
+            input_parser = create_input_parser_agent(oauth_token=self.oauth_token)
             parsed_query = await input_parser.parse(query)
             self.logger.info(
                 "Research mode detected by input parser",
@@ -1048,6 +1054,7 @@ def create_graph_orchestrator(
     use_graph: bool = True,
     search_handler: SearchHandlerProtocol | None = None,
     judge_handler: JudgeHandlerProtocol | None = None,
+    oauth_token: str | None = None,
 ) -> GraphOrchestrator:
     """
     Factory function to create a graph orchestrator.
@@ -1059,6 +1066,7 @@ def create_graph_orchestrator(
         use_graph: Whether to use graph execution (True) or agent chains (False)
         search_handler: Optional search handler for tool execution
         judge_handler: Optional judge handler for evidence assessment
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured GraphOrchestrator instance
@@ -1070,4 +1078,5 @@ def create_graph_orchestrator(
         use_graph=use_graph,
         search_handler=search_handler,
         judge_handler=judge_handler,
+        oauth_token=oauth_token,
     )

src/orchestrator/planner_agent.py

@@ -158,12 +158,13 @@ class PlannerAgent:
             )
 
 
-def create_planner_agent(model: Any | None = None) -> PlannerAgent:
+def create_planner_agent(model: Any | None = None, oauth_token: str | None = None) -> PlannerAgent:
     """
     Factory function to create a planner agent.
 
     Args:
         model: Optional Pydantic AI model. If None, uses settings default.
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Configured PlannerAgent instance
@@ -174,7 +175,7 @@ def create_planner_agent(model: Any | None = None) -> PlannerAgent:
     try:
         # Get model from settings if not provided
         if model is None:
-            model = get_model()
+            model = get_model(oauth_token=oauth_token)
 
         # Create and return planner agent
         return PlannerAgent(model=model)

src/orchestrator/research_flow.py

@@ -60,6 +60,7 @@ class IterativeResearchFlow:
         verbose: bool = True,
         use_graph: bool = False,
         judge_handler: Any | None = None,
+        oauth_token: str | None = None,
     ) -> None:
         """
         Initialize iterative research flow.
@@ -69,19 +70,21 @@ class IterativeResearchFlow:
             max_time_minutes: Maximum time in minutes
             verbose: Whether to log progress
             use_graph: Whether to use graph-based execution (True) or agent chains (False)
+            oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
         """
         self.max_iterations = max_iterations
         self.max_time_minutes = max_time_minutes
         self.verbose = verbose
         self.use_graph = use_graph
+        self.oauth_token = oauth_token
         self.logger = logger
 
         # Initialize agents (only needed for agent chain execution)
         if not use_graph:
-            self.knowledge_gap_agent = create_knowledge_gap_agent()
-            self.tool_selector_agent = create_tool_selector_agent()
-            self.thinking_agent = create_thinking_agent()
-            self.writer_agent = create_writer_agent()
+            self.knowledge_gap_agent = create_knowledge_gap_agent(oauth_token=self.oauth_token)
+            self.tool_selector_agent = create_tool_selector_agent(oauth_token=self.oauth_token)
+            self.thinking_agent = create_thinking_agent(oauth_token=self.oauth_token)
+            self.writer_agent = create_writer_agent(oauth_token=self.oauth_token)
             # Initialize judge handler (use provided or create new)
             self.judge_handler = judge_handler or create_judge_handler()
 
@@ -678,6 +681,7 @@ class DeepResearchFlow:
         verbose: bool = True,
         use_long_writer: bool = True,
         use_graph: bool = False,
+        oauth_token: str | None = None,
     ) -> None:
         """
         Initialize deep research flow.
@@ -688,19 +692,21 @@ class DeepResearchFlow:
             verbose: Whether to log progress
             use_long_writer: Whether to use long writer (True) or proofreader (False)
             use_graph: Whether to use graph-based execution (True) or agent chains (False)
+            oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
         """
         self.max_iterations = max_iterations
         self.max_time_minutes = max_time_minutes
         self.verbose = verbose
         self.use_long_writer = use_long_writer
         self.use_graph = use_graph
+        self.oauth_token = oauth_token
         self.logger = logger
 
         # Initialize agents (only needed for agent chain execution)
         if not use_graph:
-            self.planner_agent = create_planner_agent()
-            self.long_writer_agent = create_long_writer_agent()
-            self.proofreader_agent = create_proofreader_agent()
+            self.planner_agent = create_planner_agent(oauth_token=self.oauth_token)
+            self.long_writer_agent = create_long_writer_agent(oauth_token=self.oauth_token)
+            self.proofreader_agent = create_proofreader_agent(oauth_token=self.oauth_token)
             # Initialize judge handler for section loop completion
             self.judge_handler = create_judge_handler()
             # Initialize budget tracker for token tracking

src/orchestrator_factory.py

@@ -46,6 +46,7 @@ def create_orchestrator(
     judge_handler: JudgeHandlerProtocol | None = None,
     config: OrchestratorConfig | None = None,
     mode: Literal["simple", "magentic", "advanced", "iterative", "deep", "auto"] | None = None,
+    oauth_token: str | None = None,
 ) -> Any:
     """
     Create an orchestrator instance.
@@ -60,6 +61,7 @@ def create_orchestrator(
             - "iterative": Knowledge-gap-driven research (Free Tier)
             - "deep": Parallel section-based research (Free Tier)
             - "auto": Intelligent mode detection (Free Tier)
+        oauth_token: Optional OAuth token from HuggingFace login (takes priority over env vars)
 
     Returns:
         Orchestrator instance
@@ -83,6 +85,7 @@ def create_orchestrator(
             use_graph=True,
             search_handler=search_handler,
             judge_handler=judge_handler,
+            oauth_token=oauth_token,
         )
 
     # Simple mode requires handlers

src/services/image_ocr.py

@@ -55,10 +55,11 @@ class ImageOCRService:
         if self.client is None:
             loop = asyncio.get_running_loop()
             # Pass token to Client for authenticated Spaces
+            # Gradio Client uses 'token' parameter, not 'hf_token'
             if token:
                 self.client = await loop.run_in_executor(
                     None,
-                    lambda: Client(self.api_url, hf_token=token),
+                    lambda: Client(self.api_url, token=token),
                 )
             else:
                 self.client = await loop.run_in_executor(
@@ -240,3 +241,4 @@ def get_image_ocr_service() -> ImageOCRService:
 
 
 
+

src/services/multimodal_processing.py

@@ -134,3 +134,4 @@ def get_multimodal_service() -> MultimodalService:
 
 
 
+

src/services/stt_gradio.py

@@ -54,10 +54,11 @@ class STTService:
         if self.client is None:
             loop = asyncio.get_running_loop()
             # Pass token to Client for authenticated Spaces
+            # Gradio Client uses 'token' parameter, not 'hf_token'
             if token:
                 self.client = await loop.run_in_executor(
                     None,
-                    lambda: Client(self.api_url, hf_token=token),
+                    lambda: Client(self.api_url, token=token),
                 )
             else:
                 self.client = await loop.run_in_executor(

src/tools/crawl_adapter.py

@@ -62,3 +62,4 @@ async def crawl_website(starting_url: str) -> str:
 
 
 
+

src/tools/web_search_adapter.py

@@ -67,3 +67,4 @@ async def web_search(query: str) -> str:
 
 
 
+

src/utils/config.py

@@ -24,7 +24,7 @@ class Settings(BaseSettings):
     openai_api_key: str | None = Field(default=None, description="OpenAI API key")
     anthropic_api_key: str | None = Field(default=None, description="Anthropic API key")
     llm_provider: Literal["openai", "anthropic", "huggingface"] = Field(
-        default="openai", description="Which LLM provider to use"
+        default="huggingface", description="Which LLM provider to use"
     )
     openai_model: str = Field(default="gpt-5.1", description="OpenAI model name")
     anthropic_model: str = Field(
@@ -140,62 +140,6 @@ class Settings(BaseSettings):
         description="Automatically ingest evidence into RAG",
     )
 
-    # Audio Processing Configuration
-    tts_model: str = Field(
-        default="hexgrad/Kokoro-82M",
-        description="Kokoro TTS model ID for text-to-speech",
-    )
-    tts_voice: str = Field(
-        default="af_heart",
-        description="Kokoro voice ID (e.g., af_heart, af_bella, am_michael)",
-    )
-    tts_speed: float = Field(
-        default=1.0,
-        ge=0.5,
-        le=2.0,
-        description="TTS speech speed multiplier",
-    )
-    tts_gpu: str | None = Field(
-        default="T4",
-        description="Modal GPU type for TTS (T4, A10, A100, etc.)",
-    )
-    tts_timeout: int = Field(
-        default=60,
-        ge=10,
-        le=300,
-        description="TTS synthesis timeout in seconds",
-    )
-    stt_api_url: str = Field(
-        default="nvidia/canary-1b-v2",
-        description="Gradio Space URL for STT API (nvidia/canary-1b-v2)",
-    )
-    stt_source_lang: str = Field(
-        default="English",
-        description="Source language for STT transcription",
-    )
-    stt_target_lang: str = Field(
-        default="English",
-        description="Target language for STT transcription",
-    )
-    enable_audio_input: bool = Field(
-        default=True,
-        description="Enable audio input (microphone/file upload)",
-    )
-    enable_audio_output: bool = Field(
-        default=True,
-        description="Enable audio output (TTS response)",
-    )
-
-    # Image OCR Configuration
-    ocr_api_url: str = Field(
-        default="prithivMLmods/Multimodal-OCR3",
-        description="Gradio Space URL for image OCR API",
-    )
-    enable_image_input: bool = Field(
-        default=True,
-        description="Enable image input (file upload with OCR)",
-    )
-
     @property
     def modal_available(self) -> bool:
         """Check if Modal credentials are configured."""
@@ -259,16 +203,6 @@ class Settings(BaseSettings):
             return bool(self.tavily_api_key)
         return False
 
-    @property
-    def audio_available(self) -> bool:
-        """Check if audio processing is available (Modal + STT API)."""
-        return self.modal_available and bool(self.stt_api_url)
-
-    @property
-    def image_ocr_available(self) -> bool:
-        """Check if image OCR is available (OCR API URL configured)."""
-        return bool(self.ocr_api_url)
-
 
 def get_settings() -> Settings:
     """Factory function to get settings (allows mocking in tests)."""

tests/unit/middleware/__init__.py

@@ -18,4 +18,5 @@
 
 
 
+
 

tests/unit/middleware/test_budget_tracker_phase7.py

@@ -176,4 +176,5 @@ class TestIterationTokenTracking:
 
 
 
+
 

tests/unit/middleware/test_state_machine.py

@@ -373,4 +373,5 @@ class TestContextVarIsolation:
 
 
 
+