Upload folder using huggingface_hub

.env.example

@@ -0,0 +1,26 @@
+# Deep Research AI Environment Configuration
+# Copy this file to .env and fill in your API keys
+
+# LLM Provider API Keys (at least one required)
+OPENAI_API_KEY=your-openai-api-key-here
+ANTHROPIC_API_KEY=your-anthropic-api-key-here
+
+# Search API Key (one required based on provider choice)
+# For Brave Search: https://brave.com/search/api/
+# For Serper: https://serper.dev/
+# For Tavily: https://tavily.com/
+SEARCH_API_KEY=your-search-api-key-here
+
+# Optional: Specify search provider (brave, serper, tavily)
+SEARCH_PROVIDER=brave
+
+# Optional: Specify LLM provider (openai, anthropic)
+LLM_PROVIDER=openai
+
+# Optional: Specify LLM model
+LLM_MODEL=gpt-4o
+
+# Optional: Research settings
+MAX_SOURCES=10
+VERIFY_CLAIMS=true
+DEFAULT_CITATION_STYLE=apa

README_HF.md

@@ -0,0 +1,65 @@
+---
+title: Deep Research AI
+emoji: 🔍
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 4.0.0
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# 🔍 Deep Research AI
+
+An AI-powered research assistant that searches the web and synthesizes information to answer your questions.
+
+## Features
+
+- 🌐 **Real-time web search** using DuckDuckGo (no API key required)
+- 🤖 **AI-powered synthesis** using Qwen 2.5 (free via Inference API)
+- 📰 **Optional news search** for current events
+- 📚 **Source citations** with links
+
+## How it Works
+
+1. **Enter a query** - Ask any research question
+2. **Web search** - The system searches DuckDuckGo for relevant sources
+3. **AI synthesis** - Qwen 2.5 analyzes sources and generates a comprehensive answer
+4. **View results** - See the synthesized answer with citations and source links
+
+## Example Queries
+
+- "What are the latest developments in quantum computing?"
+- "Compare Python vs Rust for systems programming"
+- "How does CRISPR gene editing work?"
+- "What is the current state of renewable energy?"
+
+## Technology Stack
+
+- **LLM**: Qwen 2.5 7B Instruct (via Hugging Face Inference API)
+- **Search**: DuckDuckGo (free, no API key)
+- **Frontend**: Gradio
+- **Hosting**: Hugging Face Spaces
+
+## Local Development
+
+```bash
+# Clone the repository
+git clone https://huggingface.co/spaces/YOUR_USERNAME/deep-research-ai
+
+# Install dependencies
+pip install -r requirements_hf.txt
+
+# Run locally
+python app.py
+```
+
+## Environment Variables (Optional)
+
+- `HF_TOKEN`: Hugging Face token for Inference API (optional, increases rate limits)
+- `MODEL_ID`: Custom model ID (default: `Qwen/Qwen2.5-7B-Instruct`)
+
+## License
+
+MIT License

README_SPACE.md

@@ -0,0 +1,65 @@
+---
+title: Deep Research AI
+emoji: 🔍
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 4.0.0
+app_file: app.py
+pinned: false
+license: mit
+---
+
+# 🔍 Deep Research AI
+
+An AI-powered research assistant that searches the web and synthesizes information to answer your questions.
+
+## Features
+
+- 🌐 **Real-time web search** using DuckDuckGo (no API key required)
+- 🤖 **AI-powered synthesis** using Qwen 2.5 (free via Inference API)
+- 📰 **Optional news search** for current events
+- 📚 **Source citations** with links
+
+## How it Works
+
+1. **Enter a query** - Ask any research question
+2. **Web search** - The system searches DuckDuckGo for relevant sources
+3. **AI synthesis** - Qwen 2.5 analyzes sources and generates a comprehensive answer
+4. **View results** - See the synthesized answer with citations and source links
+
+## Example Queries
+
+- "What are the latest developments in quantum computing?"
+- "Compare Python vs Rust for systems programming"
+- "How does CRISPR gene editing work?"
+- "What is the current state of renewable energy?"
+
+## Technology Stack
+
+- **LLM**: Qwen 2.5 7B Instruct (via Hugging Face Inference API)
+- **Search**: DuckDuckGo (free, no API key)
+- **Frontend**: Gradio
+- **Hosting**: Hugging Face Spaces
+
+## Local Development
+
+```bash
+# Clone the repository
+git clone https://huggingface.co/spaces/YOUR_USERNAME/deep-research-ai
+
+# Install dependencies
+pip install -r requirements_hf.txt
+
+# Run locally
+python app.py
+```
+
+## Environment Variables (Optional)
+
+- `HF_TOKEN`: Hugging Face token for Inference API (optional, increases rate limits)
+- `MODEL_ID`: Custom model ID (default: `Qwen/Qwen2.5-7B-Instruct`)
+
+## License
+
+MIT License

app.py

@@ -0,0 +1,303 @@
+"""
+Gradio App for Deep Research AI - Hugging Face Spaces Deployment
+
+This creates a web interface for the research system that can be
+deployed directly to Hugging Face Spaces.
+"""
+
+import asyncio
+import os
+from typing import Generator
+
+import gradio as gr
+
+from src.config import Config, LLMConfig, SearchConfig
+from src.llm_client_hf import HuggingFaceLLMClient, create_hf_client
+from src.search_duckduckgo import DuckDuckGoSearch
+from src.models import Source, OutputFormat, CitationStyle
+
+
+# Configuration
+HF_TOKEN = os.environ.get("HF_TOKEN", "")
+MODEL_ID = os.environ.get("MODEL_ID", "Qwen/Qwen2.5-7B-Instruct")
+
+
+class SimpleResearcher:
+    """
+    Simplified researcher for Hugging Face Spaces.
+    
+    Uses free models and DuckDuckGo search.
+    """
+    
+    def __init__(self):
+        self.llm = create_hf_client(
+            model_size="medium",
+            use_inference_api=True,
+            hf_token=HF_TOKEN
+        )
+        self.search = DuckDuckGoSearch(max_results=5)
+    
+    async def research(
+        self,
+        query: str,
+        num_sources: int = 5,
+        include_news: bool = False
+    ) -> dict:
+        """
+        Perform research on a query.
+        
+        Args:
+            query: Research query
+            num_sources: Number of sources to use
+            include_news: Include news search
+            
+        Returns:
+            Research results dictionary
+        """
+        results = {
+            "query": query,
+            "sources": [],
+            "answer": "",
+            "confidence": 0.0
+        }
+        
+        try:
+            # Step 1: Search for information
+            search_results = await self.search.search(query, max_results=num_sources)
+            
+            if include_news:
+                news_results = await self.search.search_news(query, max_results=3)
+                search_results.extend(news_results)
+            
+            # Convert to sources
+            sources = []
+            for r in search_results[:num_sources]:
+                sources.append({
+                    "title": r.title,
+                    "url": r.url,
+                    "snippet": r.snippet,
+                    "domain": r.domain
+                })
+            
+            results["sources"] = sources
+            
+            # Step 2: Synthesize answer using LLM
+            if sources:
+                synthesis_prompt = self._build_synthesis_prompt(query, sources)
+                answer = await self.llm.call(synthesis_prompt)
+                results["answer"] = answer
+                results["confidence"] = min(len(sources) / num_sources, 1.0)
+            else:
+                results["answer"] = "I couldn't find relevant information for this query."
+                results["confidence"] = 0.0
+            
+        except Exception as e:
+            results["answer"] = f"Research encountered an error: {str(e)}"
+            results["confidence"] = 0.0
+        
+        return results
+    
+    def _build_synthesis_prompt(self, query: str, sources: list[dict]) -> str:
+        """Build synthesis prompt from sources."""
+        sources_text = "\n\n".join([
+            f"**Source {i+1}: {s['title']}**\n{s['snippet']}\nURL: {s['url']}"
+            for i, s in enumerate(sources)
+        ])
+        
+        return f"""You are a research assistant. Based on the following sources, provide a comprehensive answer to the query.
+
+QUERY: {query}
+
+SOURCES:
+{sources_text}
+
+INSTRUCTIONS:
+1. Synthesize information from all relevant sources
+2. Provide a clear, well-structured answer
+3. Cite sources using [1], [2], etc.
+4. Acknowledge any limitations or conflicting information
+5. Be objective and factual
+
+ANSWER:"""
+
+
+# Create researcher instance
+researcher = SimpleResearcher()
+
+
+def format_sources(sources: list[dict]) -> str:
+    """Format sources for display."""
+    if not sources:
+        return "No sources found."
+    
+    formatted = []
+    for i, s in enumerate(sources, 1):
+        formatted.append(
+            f"**[{i}] {s['title']}**\n"
+            f"🔗 [{s['domain']}]({s['url']})\n"
+            f"_{s['snippet'][:200]}..._\n"
+        )
+    
+    return "\n".join(formatted)
+
+
+def format_result(result: dict) -> tuple[str, str, str]:
+    """Format research result for display."""
+    answer = result.get("answer", "No answer generated.")
+    sources = format_sources(result.get("sources", []))
+    confidence = f"**Confidence:** {result.get('confidence', 0):.0%}"
+    
+    return answer, sources, confidence
+
+
+async def research_async(
+    query: str,
+    num_sources: int,
+    include_news: bool
+) -> tuple[str, str, str]:
+    """Async research function."""
+    result = await researcher.research(
+        query=query,
+        num_sources=int(num_sources),
+        include_news=include_news
+    )
+    return format_result(result)
+
+
+def research(
+    query: str,
+    num_sources: int = 5,
+    include_news: bool = False
+) -> tuple[str, str, str]:
+    """
+    Main research function for Gradio.
+    
+    Args:
+        query: Research query
+        num_sources: Number of sources
+        include_news: Include news search
+        
+    Returns:
+        Tuple of (answer, sources, confidence)
+    """
+    if not query.strip():
+        return "Please enter a research query.", "", ""
+    
+    return asyncio.run(research_async(query, num_sources, include_news))
+
+
+# Create Gradio interface
+def create_app() -> gr.Blocks:
+    """Create the Gradio app."""
+    
+    with gr.Blocks(
+        title="Deep Research AI",
+        theme=gr.themes.Soft(),
+        css="""
+        .container { max-width: 900px; margin: auto; }
+        .header { text-align: center; margin-bottom: 20px; }
+        """
+    ) as app:
+        
+        gr.Markdown(
+            """
+            # 🔍 Deep Research AI
+            
+            An AI-powered research assistant that searches the web and synthesizes 
+            information to answer your questions.
+            
+            **Features:**
+            - 🌐 Real-time web search (DuckDuckGo)
+            - 🤖 AI-powered synthesis (Qwen 2.5)
+            - 📰 Optional news search
+            - 📚 Source citations
+            """,
+            elem_classes=["header"]
+        )
+        
+        with gr.Row():
+            with gr.Column(scale=3):
+                query_input = gr.Textbox(
+                    label="Research Query",
+                    placeholder="Enter your research question...",
+                    lines=2,
+                    max_lines=4
+                )
+            
+            with gr.Column(scale=1):
+                num_sources = gr.Slider(
+                    minimum=3,
+                    maximum=10,
+                    value=5,
+                    step=1,
+                    label="Number of Sources"
+                )
+                include_news = gr.Checkbox(
+                    label="Include News",
+                    value=False
+                )
+                research_btn = gr.Button(
+                    "🔍 Research",
+                    variant="primary",
+                    size="lg"
+                )
+        
+        with gr.Tabs():
+            with gr.TabItem("📝 Answer"):
+                answer_output = gr.Markdown(
+                    label="Research Answer",
+                    value="*Enter a query and click Research*"
+                )
+                confidence_output = gr.Markdown()
+            
+            with gr.TabItem("📚 Sources"):
+                sources_output = gr.Markdown(
+                    label="Sources",
+                    value="*Sources will appear here*"
+                )
+        
+        # Examples
+        gr.Examples(
+            examples=[
+                ["What are the latest developments in quantum computing?"],
+                ["Compare the benefits of Python vs Rust for systems programming"],
+                ["Explain how large language models work"],
+                ["What is the current state of renewable energy adoption?"],
+                ["How does CRISPR gene editing work?"],
+            ],
+            inputs=query_input,
+            label="Example Queries"
+        )
+        
+        # Connect button
+        research_btn.click(
+            fn=research,
+            inputs=[query_input, num_sources, include_news],
+            outputs=[answer_output, sources_output, confidence_output]
+        )
+        
+        # Also trigger on Enter
+        query_input.submit(
+            fn=research,
+            inputs=[query_input, num_sources, include_news],
+            outputs=[answer_output, sources_output, confidence_output]
+        )
+        
+        gr.Markdown(
+            """
+            ---
+            **Note:** This uses DuckDuckGo for search (no API key required) and 
+            Qwen 2.5 for synthesis. Results may vary based on available sources.
+            
+            Made with ❤️ using Gradio and Hugging Face
+            """
+        )
+    
+    return app
+
+
+# Create and launch app
+app = create_app()
+
+if __name__ == "__main__":
+    app.launch()

requirements_hf.txt

@@ -0,0 +1,25 @@
+# Hugging Face Spaces Requirements
+# These are optimized for free-tier deployment
+
+# Core
+gradio>=4.0.0
+huggingface_hub>=0.20.0
+
+# LLM (for inference API)
+transformers>=4.36.0
+torch>=2.1.0
+accelerate>=0.25.0
+
+# Free web search
+duckduckgo-search>=4.1.0
+
+# HTTP and async
+httpx>=0.25.0
+aiohttp>=3.9.0
+
+# Content extraction
+beautifulsoup4>=4.12.0
+trafilatura>=1.6.0
+
+# Utilities
+python-dotenv>=1.0.0

requirements_space.txt

@@ -0,0 +1,25 @@
+# Hugging Face Spaces Requirements
+# These are optimized for free-tier deployment
+
+# Core
+gradio>=4.0.0
+huggingface_hub>=0.20.0
+
+# LLM (for inference API)
+transformers>=4.36.0
+torch>=2.1.0
+accelerate>=0.25.0
+
+# Free web search
+duckduckgo-search>=4.1.0
+
+# HTTP and async
+httpx>=0.25.0
+aiohttp>=3.9.0
+
+# Content extraction
+beautifulsoup4>=4.12.0
+trafilatura>=1.6.0
+
+# Utilities
+python-dotenv>=1.0.0

src/__init__.py

@@ -0,0 +1,125 @@
+"""
+Deep Research AI
+
+A comprehensive AI-powered research system that combines web search,
+reasoning, verification, and citation to deliver accurate, well-sourced
+research results.
+
+Usage:
+    from src import research, ResearchOrchestrator, Config
+    
+    # Quick research
+    result = await research("What is quantum computing?")
+    
+    # Advanced usage
+    config = Config()
+    orchestrator = ResearchOrchestrator(config)
+    result = await orchestrator.research(
+        query="Compare Python and Rust",
+        audience=AudienceType.PROFESSIONAL,
+        max_sources=15
+    )
+"""
+
+from .config import Config, LLMConfig, SearchConfig, ResearchConfig
+from .models import (
+    Entity,
+    SubQuery,
+    QueryAnalysis,
+    SearchResult,
+    ContentExtraction,
+    Source,
+    ReasoningStep,
+    VerificationResult,
+    Citation,
+    ResearchResult,
+    OutputFormat,
+    CitationStyle,
+)
+from .llm_client import LLMClient
+from .orchestrator import ResearchOrchestrator, research, ResearchSession, ResearchProgress
+from .main import run_research, create_config
+
+# Module imports
+from .modules.query_understanding import QueryUnderstanding
+from .modules.web_search import WebSearch
+from .modules.reasoning_engine import ReasoningEngine
+from .modules.verification import Verification
+from .modules.citation import CitationManager
+from .modules.output_generation import OutputGenerator, SummaryLength, AudienceType
+from .modules.error_handling import (
+    ErrorHandler,
+    ErrorSeverity,
+    ComponentType,
+    ResearchError,
+    QueryError,
+    SearchError,
+    ReasoningError,
+    VerificationError,
+    CitationError,
+    LLMError,
+    RateLimitError,
+)
+
+__version__ = "1.0.0"
+__author__ = "Deep Research AI Team"
+
+__all__ = [
+    # Main API
+    "research",
+    "run_research",
+    "create_config",
+    "ResearchOrchestrator",
+    
+    # Configuration
+    "Config",
+    "LLMConfig",
+    "SearchConfig",
+    "ResearchConfig",
+    
+    # Models
+    "Entity",
+    "SubQuery",
+    "QueryAnalysis",
+    "SearchResult",
+    "ContentExtraction",
+    "Source",
+    "ReasoningStep",
+    "VerificationResult",
+    "Citation",
+    "ResearchResult",
+    "OutputFormat",
+    "CitationStyle",
+    
+    # Clients
+    "LLMClient",
+    
+    # Modules
+    "QueryUnderstanding",
+    "WebSearch",
+    "ReasoningEngine",
+    "Verification",
+    "CitationManager",
+    "OutputGenerator",
+    "ErrorHandler",
+    
+    # Enums
+    "SummaryLength",
+    "AudienceType",
+    "ErrorSeverity",
+    "ComponentType",
+    
+    # Exceptions
+    "ResearchError",
+    "QueryError",
+    "SearchError",
+    "ReasoningError",
+    "VerificationError",
+    "CitationError",
+    "LLMError",
+    "RateLimitError",
+    
+    # Session management
+    "ResearchSession",
+    "ResearchProgress",
+]

src/config.py

@@ -0,0 +1,76 @@
+"""
+Configuration settings for Deep Research AI.
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+
+@dataclass
+class LLMConfig:
+    """LLM provider configuration."""
+    provider: str = "openai"
+    model: str = "gpt-4"
+    temperature: float = 0.7
+    max_tokens: int = 4096
+    api_key: Optional[str] = field(default_factory=lambda: os.getenv("OPENAI_API_KEY"))
+    
+    # Fallback configuration
+    fallback_provider: str = "anthropic"
+    fallback_model: str = "claude-3-sonnet-20240229"
+    fallback_api_key: Optional[str] = field(default_factory=lambda: os.getenv("ANTHROPIC_API_KEY"))
+
+
+@dataclass
+class SearchConfig:
+    """Web search configuration."""
+    provider: str = "tavily"
+    api_key: Optional[str] = field(default_factory=lambda: os.getenv("TAVILY_API_KEY"))
+    max_results: int = 10
+    timeout_seconds: int = 30
+    
+    # Fallback search
+    fallback_provider: str = "serper"
+    fallback_api_key: Optional[str] = field(default_factory=lambda: os.getenv("SERPER_API_KEY"))
+
+
+@dataclass
+class ResearchConfig:
+    """Research operation configuration."""
+    # Timeouts
+    max_research_time_seconds: int = 120
+    quick_research_time_seconds: int = 30
+    
+    # Sources
+    max_sources: int = 15
+    min_sources_for_verification: int = 2
+    
+    # Verification
+    min_confidence_threshold: float = 0.5
+    require_cross_reference: bool = True
+    
+    # Output
+    default_output_format: str = "markdown"
+    include_confidence_scores: bool = True
+    include_sources: bool = True
+
+
+@dataclass
+class Config:
+    """Main application configuration."""
+    llm: LLMConfig = field(default_factory=LLMConfig)
+    search: SearchConfig = field(default_factory=SearchConfig)
+    research: ResearchConfig = field(default_factory=ResearchConfig)
+    
+    # Application settings
+    debug: bool = field(default_factory=lambda: os.getenv("DEBUG", "false").lower() == "true")
+    log_level: str = field(default_factory=lambda: os.getenv("LOG_LEVEL", "INFO"))
+
+
+# Global config instance
+config = Config()

src/llm_client.py

@@ -0,0 +1,257 @@
+"""
+LLM client for interacting with language models.
+"""
+
+import json
+import logging
+from typing import Optional, Dict, Any, List
+from abc import ABC, abstractmethod
+
+from openai import OpenAI
+from anthropic import Anthropic
+
+from .config import config
+
+logger = logging.getLogger(__name__)
+
+
+class BaseLLMClient(ABC):
+    """Base class for LLM clients."""
+    
+    @abstractmethod
+    async def generate(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        json_mode: bool = False
+    ) -> str:
+        """Generate a response from the LLM."""
+        pass
+    
+    @abstractmethod
+    async def generate_json(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: Optional[float] = None
+    ) -> Dict[str, Any]:
+        """Generate a JSON response from the LLM."""
+        pass
+
+
+class OpenAIClient(BaseLLMClient):
+    """OpenAI API client."""
+    
+    def __init__(self, api_key: Optional[str] = None, model: Optional[str] = None):
+        self.api_key = api_key or config.llm.api_key
+        self.model = model or config.llm.model
+        self.client = OpenAI(api_key=self.api_key)
+    
+    async def generate(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        json_mode: bool = False
+    ) -> str:
+        """Generate a response from OpenAI."""
+        messages = []
+        
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        
+        messages.append({"role": "user", "content": prompt})
+        
+        kwargs = {
+            "model": self.model,
+            "messages": messages,
+            "temperature": temperature or config.llm.temperature,
+            "max_tokens": max_tokens or config.llm.max_tokens,
+        }
+        
+        if json_mode:
+            kwargs["response_format"] = {"type": "json_object"}
+        
+        try:
+            response = self.client.chat.completions.create(**kwargs)
+            return response.choices[0].message.content
+        except Exception as e:
+            logger.error(f"OpenAI API error: {e}")
+            raise
+    
+    async def generate_json(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: Optional[float] = None
+    ) -> Dict[str, Any]:
+        """Generate a JSON response from OpenAI."""
+        # Add JSON instruction to prompt
+        json_prompt = prompt + "\n\nRespond with valid JSON only."
+        
+        response = await self.generate(
+            prompt=json_prompt,
+            system_prompt=system_prompt,
+            temperature=temperature,
+            json_mode=True
+        )
+        
+        try:
+            return json.loads(response)
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse JSON response: {e}")
+            # Try to extract JSON from response
+            return self._extract_json(response)
+    
+    def _extract_json(self, text: str) -> Dict[str, Any]:
+        """Extract JSON from text that might contain other content."""
+        # Try to find JSON block
+        start = text.find('{')
+        end = text.rfind('}') + 1
+        
+        if start != -1 and end > start:
+            try:
+                return json.loads(text[start:end])
+            except json.JSONDecodeError:
+                pass
+        
+        return {"error": "Failed to parse response", "raw": text}
+
+
+class AnthropicClient(BaseLLMClient):
+    """Anthropic API client."""
+    
+    def __init__(self, api_key: Optional[str] = None, model: Optional[str] = None):
+        self.api_key = api_key or config.llm.fallback_api_key
+        self.model = model or config.llm.fallback_model
+        self.client = Anthropic(api_key=self.api_key)
+    
+    async def generate(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        json_mode: bool = False
+    ) -> str:
+        """Generate a response from Anthropic."""
+        kwargs = {
+            "model": self.model,
+            "max_tokens": max_tokens or config.llm.max_tokens,
+            "messages": [{"role": "user", "content": prompt}],
+        }
+        
+        if system_prompt:
+            kwargs["system"] = system_prompt
+        
+        if temperature is not None:
+            kwargs["temperature"] = temperature
+        
+        try:
+            response = self.client.messages.create(**kwargs)
+            return response.content[0].text
+        except Exception as e:
+            logger.error(f"Anthropic API error: {e}")
+            raise
+    
+    async def generate_json(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: Optional[float] = None
+    ) -> Dict[str, Any]:
+        """Generate a JSON response from Anthropic."""
+        json_prompt = prompt + "\n\nRespond with valid JSON only, no other text."
+        
+        response = await self.generate(
+            prompt=json_prompt,
+            system_prompt=system_prompt,
+            temperature=temperature
+        )
+        
+        try:
+            return json.loads(response)
+        except json.JSONDecodeError:
+            # Try to extract JSON
+            start = response.find('{')
+            end = response.rfind('}') + 1
+            if start != -1 and end > start:
+                try:
+                    return json.loads(response[start:end])
+                except json.JSONDecodeError:
+                    pass
+            return {"error": "Failed to parse response", "raw": response}
+
+
+class LLMClient:
+    """Main LLM client with fallback support."""
+    
+    def __init__(self):
+        self.primary = OpenAIClient()
+        self.fallback = AnthropicClient()
+        self._use_fallback = False
+    
+    async def generate(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: Optional[float] = None,
+        max_tokens: Optional[int] = None,
+        json_mode: bool = False
+    ) -> str:
+        """Generate a response with fallback support."""
+        client = self.fallback if self._use_fallback else self.primary
+        
+        try:
+            return await client.generate(
+                prompt=prompt,
+                system_prompt=system_prompt,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                json_mode=json_mode
+            )
+        except Exception as e:
+            if not self._use_fallback:
+                logger.warning(f"Primary LLM failed, trying fallback: {e}")
+                self._use_fallback = True
+                return await self.generate(
+                    prompt=prompt,
+                    system_prompt=system_prompt,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                    json_mode=json_mode
+                )
+            raise
+    
+    async def generate_json(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        temperature: Optional[float] = None
+    ) -> Dict[str, Any]:
+        """Generate a JSON response with fallback support."""
+        client = self.fallback if self._use_fallback else self.primary
+        
+        try:
+            return await client.generate_json(
+                prompt=prompt,
+                system_prompt=system_prompt,
+                temperature=temperature
+            )
+        except Exception as e:
+            if not self._use_fallback:
+                logger.warning(f"Primary LLM failed, trying fallback: {e}")
+                self._use_fallback = True
+                return await self.generate_json(
+                    prompt=prompt,
+                    system_prompt=system_prompt,
+                    temperature=temperature
+                )
+            raise
+
+
+# Global LLM client instance
+llm_client = LLMClient()

src/llm_client_hf.py

@@ -0,0 +1,263 @@
+"""
+Hugging Face LLM Client for Deep Research AI.
+
+This module provides LLM integration using Hugging Face models,
+suitable for deployment on Hugging Face Spaces.
+"""
+
+import json
+import re
+from typing import Any
+
+try:
+    from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline
+    import torch
+    HF_AVAILABLE = True
+except ImportError:
+    HF_AVAILABLE = False
+
+try:
+    from huggingface_hub import InferenceClient
+    HF_INFERENCE_AVAILABLE = True
+except ImportError:
+    HF_INFERENCE_AVAILABLE = False
+
+
+class HuggingFaceLLMClient:
+    """
+    LLM client for Hugging Face models.
+    
+    Supports both local model loading and Hugging Face Inference API.
+    """
+    
+    # Recommended models for research tasks
+    RECOMMENDED_MODELS = {
+        "small": "mistralai/Mistral-7B-Instruct-v0.3",
+        "medium": "Qwen/Qwen2.5-7B-Instruct", 
+        "large": "meta-llama/Llama-3.1-8B-Instruct",
+        "best": "microsoft/Phi-3-medium-4k-instruct",
+    }
+    
+    def __init__(
+        self,
+        model_id: str = "Qwen/Qwen2.5-7B-Instruct",
+        use_inference_api: bool = True,
+        hf_token: str | None = None,
+        device: str = "auto",
+        max_new_tokens: int = 2048,
+        temperature: float = 0.7,
+    ) -> None:
+        """
+        Initialize the Hugging Face LLM client.
+        
+        Args:
+            model_id: Hugging Face model ID
+            use_inference_api: Use HF Inference API (recommended for Spaces)
+            hf_token: Hugging Face API token
+            device: Device to use ("auto", "cuda", "cpu")
+            max_new_tokens: Maximum tokens to generate
+            temperature: Sampling temperature
+        """
+        self.model_id = model_id
+        self.use_inference_api = use_inference_api
+        self.hf_token = hf_token
+        self.max_new_tokens = max_new_tokens
+        self.temperature = temperature
+        
+        self.client = None
+        self.pipeline = None
+        self.tokenizer = None
+        self.model = None
+        
+        if use_inference_api:
+            self._init_inference_client()
+        else:
+            self._init_local_model(device)
+    
+    def _init_inference_client(self) -> None:
+        """Initialize Hugging Face Inference API client."""
+        if not HF_INFERENCE_AVAILABLE:
+            raise ImportError(
+                "huggingface_hub not installed. "
+                "Install with: pip install huggingface_hub"
+            )
+        
+        self.client = InferenceClient(
+            model=self.model_id,
+            token=self.hf_token
+        )
+    
+    def _init_local_model(self, device: str) -> None:
+        """Initialize local model."""
+        if not HF_AVAILABLE:
+            raise ImportError(
+                "transformers not installed. "
+                "Install with: pip install transformers torch"
+            )
+        
+        # Determine device
+        if device == "auto":
+            device = "cuda" if torch.cuda.is_available() else "cpu"
+        
+        # Load tokenizer and model
+        self.tokenizer = AutoTokenizer.from_pretrained(
+            self.model_id,
+            token=self.hf_token
+        )
+        
+        self.model = AutoModelForCausalLM.from_pretrained(
+            self.model_id,
+            token=self.hf_token,
+            torch_dtype=torch.float16 if device == "cuda" else torch.float32,
+            device_map=device,
+            trust_remote_code=True
+        )
+        
+        self.pipeline = pipeline(
+            "text-generation",
+            model=self.model,
+            tokenizer=self.tokenizer,
+            max_new_tokens=self.max_new_tokens,
+            temperature=self.temperature,
+            do_sample=True,
+        )
+    
+    async def call(self, prompt: str, system_prompt: str | None = None) -> str:
+        """
+        Call the LLM with a prompt.
+        
+        Args:
+            prompt: User prompt
+            system_prompt: Optional system prompt
+            
+        Returns:
+            Generated text response
+        """
+        messages = []
+        
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        
+        messages.append({"role": "user", "content": prompt})
+        
+        if self.use_inference_api:
+            return await self._call_inference_api(messages)
+        else:
+            return self._call_local_model(messages)
+    
+    async def _call_inference_api(self, messages: list[dict]) -> str:
+        """Call using Inference API."""
+        import asyncio
+        
+        # Run in executor since client is sync
+        loop = asyncio.get_event_loop()
+        response = await loop.run_in_executor(
+            None,
+            lambda: self.client.chat_completion(
+                messages=messages,
+                max_tokens=self.max_new_tokens,
+                temperature=self.temperature,
+            )
+        )
+        
+        return response.choices[0].message.content
+    
+    def _call_local_model(self, messages: list[dict]) -> str:
+        """Call local model."""
+        # Format messages for the model
+        if hasattr(self.tokenizer, "apply_chat_template"):
+            prompt = self.tokenizer.apply_chat_template(
+                messages,
+                tokenize=False,
+                add_generation_prompt=True
+            )
+        else:
+            # Fallback formatting
+            prompt = ""
+            for msg in messages:
+                role = msg["role"]
+                content = msg["content"]
+                if role == "system":
+                    prompt += f"System: {content}\n\n"
+                elif role == "user":
+                    prompt += f"User: {content}\n\nAssistant: "
+        
+        outputs = self.pipeline(prompt, return_full_text=False)
+        return outputs[0]["generated_text"]
+    
+    async def call_json(
+        self,
+        prompt: str,
+        system_prompt: str | None = None
+    ) -> dict[str, Any]:
+        """
+        Call LLM and parse JSON response.
+        
+        Args:
+            prompt: User prompt (should request JSON output)
+            system_prompt: Optional system prompt
+            
+        Returns:
+            Parsed JSON as dictionary
+        """
+        # Add JSON instruction to prompt
+        json_prompt = prompt + "\n\nRespond with valid JSON only."
+        
+        response = await self.call(json_prompt, system_prompt)
+        
+        return self._parse_json_response(response)
+    
+    def _parse_json_response(self, response: str) -> dict[str, Any]:
+        """Parse JSON from response text."""
+        # Try direct parse
+        try:
+            return json.loads(response)
+        except json.JSONDecodeError:
+            pass
+        
+        # Try to extract JSON from markdown code blocks
+        json_patterns = [
+            r'```json\s*([\s\S]*?)\s*```',
+            r'```\s*([\s\S]*?)\s*```',
+            r'\{[\s\S]*\}',
+        ]
+        
+        for pattern in json_patterns:
+            matches = re.findall(pattern, response)
+            for match in matches:
+                try:
+                    return json.loads(match)
+                except json.JSONDecodeError:
+                    continue
+        
+        # Return empty dict if parsing fails
+        return {"raw_response": response, "parse_error": True}
+
+
+# Factory function
+def create_hf_client(
+    model_size: str = "medium",
+    use_inference_api: bool = True,
+    hf_token: str | None = None
+) -> HuggingFaceLLMClient:
+    """
+    Create a Hugging Face LLM client.
+    
+    Args:
+        model_size: "small", "medium", "large", or "best"
+        use_inference_api: Use Inference API (recommended)
+        hf_token: Hugging Face token
+        
+    Returns:
+        Configured HuggingFaceLLMClient
+    """
+    model_id = HuggingFaceLLMClient.RECOMMENDED_MODELS.get(
+        model_size,
+        HuggingFaceLLMClient.RECOMMENDED_MODELS["medium"]
+    )
+    
+    return HuggingFaceLLMClient(
+        model_id=model_id,
+        use_inference_api=use_inference_api,
+        hf_token=hf_token
+    )

src/main.py

@@ -0,0 +1,282 @@
+"""
+Deep Research AI - Main Entry Point
+
+A comprehensive AI-powered research system that combines web search,
+reasoning, verification, and citation to deliver accurate, well-sourced
+research results.
+"""
+
+import asyncio
+import argparse
+import json
+import sys
+from typing import Any
+
+from .config import Config, LLMConfig, SearchConfig, ResearchConfig
+from .orchestrator import ResearchOrchestrator, research
+from .models import OutputFormat, CitationStyle
+from .modules.output_generation import AudienceType
+
+
+def create_config(
+    llm_provider: str = "openai",
+    llm_model: str | None = None,
+    search_provider: str = "brave",
+    openai_api_key: str | None = None,
+    anthropic_api_key: str | None = None,
+    search_api_key: str | None = None
+) -> Config:
+    """
+    Create a configuration object.
+    
+    Args:
+        llm_provider: LLM provider ("openai" or "anthropic")
+        llm_model: Model name (uses default for provider if not specified)
+        search_provider: Search provider ("brave", "serper", or "tavily")
+        openai_api_key: OpenAI API key
+        anthropic_api_key: Anthropic API key
+        search_api_key: Search API key
+        
+    Returns:
+        Configured Config object
+    """
+    # Determine model based on provider
+    if llm_model is None:
+        llm_model = "gpt-4o" if llm_provider == "openai" else "claude-sonnet-4-20250514"
+    
+    llm_config = LLMConfig(
+        provider=llm_provider,
+        model=llm_model,
+        openai_api_key=openai_api_key or "",
+        anthropic_api_key=anthropic_api_key or ""
+    )
+    
+    search_config = SearchConfig(
+        provider=search_provider,
+        api_key=search_api_key or ""
+    )
+    
+    return Config(
+        llm_config=llm_config,
+        search_config=search_config
+    )
+
+
+async def run_research(
+    query: str,
+    config: Config | None = None,
+    audience: str = "general",
+    citation_style: str = "apa",
+    output_format: str = "markdown",
+    max_sources: int = 10,
+    verify: bool = True
+) -> dict[str, Any]:
+    """
+    Run a research query and return results.
+    
+    Args:
+        query: The research query
+        config: Configuration (uses defaults if not provided)
+        audience: Target audience (general, professional, academic, technical)
+        citation_style: Citation style (apa, mla, chicago, ieee, harvard)
+        output_format: Output format (text, markdown, html, json)
+        max_sources: Maximum number of sources to use
+        verify: Whether to verify claims
+        
+    Returns:
+        Dictionary containing research results
+    """
+    config = config or Config()
+    orchestrator = ResearchOrchestrator(config)
+    
+    # Convert string parameters to enums
+    audience_type = AudienceType(audience.lower())
+    cit_style = CitationStyle(citation_style.upper())
+    out_format = OutputFormat(output_format.lower())
+    
+    # Run research
+    result = await orchestrator.research(
+        query=query,
+        audience=audience_type,
+        citation_style=cit_style,
+        output_format=out_format,
+        max_sources=max_sources,
+        verify_claims=verify
+    )
+    
+    # Convert to dictionary
+    return {
+        "query": result.query,
+        "answer": result.answer,
+        "confidence": result.confidence,
+        "sources": [
+            {
+                "title": s.title,
+                "url": s.url,
+                "credibility_score": s.credibility_score
+            }
+            for s in result.sources
+        ],
+        "verification_status": result.verification_status,
+        "metadata": result.metadata
+    }
+
+
+def main():
+    """Main entry point for CLI usage."""
+    parser = argparse.ArgumentParser(
+        description="Deep Research AI - Comprehensive AI-powered research",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s "What is quantum computing?"
+  %(prog)s "Compare Python and Rust" --audience professional
+  %(prog)s "Latest AI developments" --max-sources 15 --no-verify
+        """
+    )
+    
+    parser.add_argument(
+        "query",
+        help="The research query to investigate"
+    )
+    
+    parser.add_argument(
+        "--llm-provider",
+        choices=["openai", "anthropic"],
+        default="openai",
+        help="LLM provider to use (default: openai)"
+    )
+    
+    parser.add_argument(
+        "--llm-model",
+        help="Specific model to use (default: provider's best model)"
+    )
+    
+    parser.add_argument(
+        "--search-provider",
+        choices=["brave", "serper", "tavily"],
+        default="brave",
+        help="Search provider to use (default: brave)"
+    )
+    
+    parser.add_argument(
+        "--audience",
+        choices=["general", "professional", "academic", "technical"],
+        default="general",
+        help="Target audience (default: general)"
+    )
+    
+    parser.add_argument(
+        "--citation-style",
+        choices=["apa", "mla", "chicago", "ieee", "harvard"],
+        default="apa",
+        help="Citation style (default: apa)"
+    )
+    
+    parser.add_argument(
+        "--output-format",
+        choices=["text", "markdown", "html", "json"],
+        default="markdown",
+        help="Output format (default: markdown)"
+    )
+    
+    parser.add_argument(
+        "--max-sources",
+        type=int,
+        default=10,
+        help="Maximum number of sources to use (default: 10)"
+    )
+    
+    parser.add_argument(
+        "--no-verify",
+        action="store_true",
+        help="Skip claim verification"
+    )
+    
+    parser.add_argument(
+        "--json-output",
+        action="store_true",
+        help="Output results as JSON"
+    )
+    
+    parser.add_argument(
+        "--openai-api-key",
+        help="OpenAI API key (or set OPENAI_API_KEY env var)"
+    )
+    
+    parser.add_argument(
+        "--anthropic-api-key",
+        help="Anthropic API key (or set ANTHROPIC_API_KEY env var)"
+    )
+    
+    parser.add_argument(
+        "--search-api-key",
+        help="Search API key (or set SEARCH_API_KEY env var)"
+    )
+    
+    args = parser.parse_args()
+    
+    # Create configuration
+    config = create_config(
+        llm_provider=args.llm_provider,
+        llm_model=args.llm_model,
+        search_provider=args.search_provider,
+        openai_api_key=args.openai_api_key,
+        anthropic_api_key=args.anthropic_api_key,
+        search_api_key=args.search_api_key
+    )
+    
+    # Run research
+    print(f"🔍 Researching: {args.query}\n")
+    
+    try:
+        result = asyncio.run(run_research(
+            query=args.query,
+            config=config,
+            audience=args.audience,
+            citation_style=args.citation_style,
+            output_format=args.output_format,
+            max_sources=args.max_sources,
+            verify=not args.no_verify
+        ))
+        
+        if args.json_output:
+            print(json.dumps(result, indent=2))
+        else:
+            print_result(result)
+            
+    except Exception as e:
+        print(f"❌ Research failed: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def print_result(result: dict) -> None:
+    """Print research result in a readable format."""
+    print("=" * 60)
+    print("📚 RESEARCH RESULTS")
+    print("=" * 60)
+    print()
+    
+    print(f"📋 Query: {result['query']}")
+    print(f"🎯 Confidence: {result['confidence']:.1%}")
+    print(f"✅ Verification: {result['verification_status']}")
+    print()
+    
+    print("📝 Answer:")
+    print("-" * 40)
+    print(result['answer'])
+    print()
+    
+    print(f"📚 Sources ({len(result['sources'])}):")
+    print("-" * 40)
+    for i, source in enumerate(result['sources'], 1):
+        print(f"{i}. {source['title']}")
+        print(f"   URL: {source['url']}")
+        print(f"   Credibility: {source['credibility_score']:.1%}")
+    print()
+    
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

src/models.py

@@ -0,0 +1,198 @@
+"""
+Data models for Deep Research AI.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import List, Optional, Dict, Any
+from enum import Enum
+import uuid
+
+
+class QueryComplexity(Enum):
+    """Query complexity levels."""
+    SIMPLE = "simple"
+    MEDIUM = "medium"
+    COMPLEX = "complex"
+
+
+class ResearchStatus(Enum):
+    """Research operation status."""
+    PENDING = "pending"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    PARTIAL = "partial"
+
+
+class ConfidenceLevel(Enum):
+    """Confidence level categories."""
+    VERY_HIGH = "very_high"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    VERY_LOW = "very_low"
+
+
+class VerificationStatus(Enum):
+    """Verification status for claims."""
+    VERIFIED = "verified"
+    PARTIALLY_VERIFIED = "partially_verified"
+    UNVERIFIED = "unverified"
+    DISPUTED = "disputed"
+
+
+@dataclass
+class Entity:
+    """Entity extracted from query."""
+    text: str
+    type: str  # PERSON, ORG, LOCATION, DATE, CONCEPT, PRODUCT, EVENT
+    relevance: str = "primary"  # primary, secondary
+    context: Optional[str] = None
+
+
+@dataclass
+class QueryAnalysis:
+    """Analyzed query structure."""
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    raw_query: str = ""
+    intent: str = ""
+    domain: str = ""
+    entities: List[Entity] = field(default_factory=list)
+    temporal_scope: Optional[str] = None
+    geographic_scope: Optional[str] = None
+    complexity: QueryComplexity = QueryComplexity.MEDIUM
+    output_type: str = "report"
+    sub_queries: List[str] = field(default_factory=list)
+    created_at: datetime = field(default_factory=datetime.now)
+
+
+@dataclass
+class Source:
+    """Web source information."""
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    url: str = ""
+    title: str = ""
+    content: str = ""
+    snippet: str = ""
+    author: Optional[str] = None
+    publication_date: Optional[str] = None
+    domain: str = ""
+    credibility_score: float = 0.5
+    credibility_level: str = "medium"
+    retrieved_at: datetime = field(default_factory=datetime.now)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ExtractedInfo:
+    """Information extracted from a source."""
+    source_id: str = ""
+    content: str = ""
+    info_type: str = ""  # fact, data, quote, claim, context
+    relevance: str = "medium"
+    location: str = ""
+
+
+@dataclass
+class Claim:
+    """A claim extracted from research."""
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    content: str = ""
+    source_ids: List[str] = field(default_factory=list)
+    verification_status: VerificationStatus = VerificationStatus.UNVERIFIED
+    confidence_score: float = 0.5
+    supporting_evidence: List[str] = field(default_factory=list)
+    contradicting_evidence: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Finding:
+    """A research finding."""
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    title: str = ""
+    content: str = ""
+    category: str = ""
+    confidence_score: float = 0.5
+    confidence_level: ConfidenceLevel = ConfidenceLevel.MEDIUM
+    source_ids: List[str] = field(default_factory=list)
+    claims: List[Claim] = field(default_factory=list)
+    reasoning_chain: List[str] = field(default_factory=list)
+    caveats: List[str] = field(default_factory=list)
+
+
+@dataclass
+class Conflict:
+    """Conflicting information from sources."""
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    topic: str = ""
+    conflict_type: str = ""  # factual, interpretive, temporal, scope
+    positions: List[Dict[str, str]] = field(default_factory=list)
+    severity: str = "medium"
+    resolution: Optional[str] = None
+
+
+@dataclass
+class Citation:
+    """A source citation."""
+    number: int = 0
+    source_id: str = ""
+    url: str = ""
+    title: str = ""
+    author: Optional[str] = None
+    date: Optional[str] = None
+    formatted: str = ""
+
+
+@dataclass
+class VerificationResult:
+    """Result of verification process."""
+    overall_confidence: float = 0.5
+    trust_level: str = "medium"
+    verified_claims: List[Claim] = field(default_factory=list)
+    conflicts: List[Conflict] = field(default_factory=list)
+    caveats: List[str] = field(default_factory=list)
+    flags: List[Dict[str, str]] = field(default_factory=list)
+
+
+@dataclass
+class ResearchResult:
+    """Complete research result."""
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    query: QueryAnalysis = field(default_factory=QueryAnalysis)
+    status: ResearchStatus = ResearchStatus.PENDING
+    
+    # Content
+    summary: str = ""
+    executive_summary: str = ""
+    findings: List[Finding] = field(default_factory=list)
+    sources: List[Source] = field(default_factory=list)
+    citations: List[Citation] = field(default_factory=list)
+    
+    # Verification
+    verification: Optional[VerificationResult] = None
+    overall_confidence: float = 0.5
+    
+    # Metadata
+    created_at: datetime = field(default_factory=datetime.now)
+    completed_at: Optional[datetime] = None
+    processing_time_seconds: float = 0.0
+    
+    # Output
+    markdown_output: str = ""
+    json_output: Dict[str, Any] = field(default_factory=dict)
+    
+    # Errors
+    errors: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ResearchRequest:
+    """Incoming research request."""
+    query: str
+    mode: str = "standard"  # quick, standard, deep
+    max_sources: int = 10
+    output_format: str = "markdown"
+    include_sources: bool = True
+    domain_hint: Optional[str] = None

src/modules/__init__.py

@@ -0,0 +1,68 @@
+"""
+Modules for Deep Research AI.
+"""
+
+from .query_understanding import query_understanding, QueryUnderstanding
+from .web_search import web_search, WebSearch
+from .reasoning_engine import reasoning_engine, ReasoningEngine
+from .verification import verification, Verification
+from .citation import citation_manager, CitationManager
+from .output_generation import output_generator, OutputGenerator, SummaryLength, AudienceType
+from .error_handling import (
+    error_handler,
+    ErrorHandler,
+    ErrorSeverity,
+    ComponentType,
+    ErrorContext,
+    ResearchError,
+    QueryError,
+    SearchError,
+    ReasoningError,
+    VerificationError,
+    CitationError,
+    LLMError,
+    RateLimitError,
+)
+
+__all__ = [
+    # Query Understanding
+    "query_understanding",
+    "QueryUnderstanding",
+    
+    # Web Search
+    "web_search",
+    "WebSearch",
+    
+    # Reasoning Engine
+    "reasoning_engine",
+    "ReasoningEngine",
+    
+    # Verification
+    "verification",
+    "Verification",
+    
+    # Citation
+    "citation_manager",
+    "CitationManager",
+    
+    # Output Generation
+    "output_generator",
+    "OutputGenerator",
+    "SummaryLength",
+    "AudienceType",
+    
+    # Error Handling
+    "error_handler",
+    "ErrorHandler",
+    "ErrorSeverity",
+    "ComponentType",
+    "ErrorContext",
+    "ResearchError",
+    "QueryError",
+    "SearchError",
+    "ReasoningError",
+    "VerificationError",
+    "CitationError",
+    "LLMError",
+    "RateLimitError",
+]

src/modules/citation.py

@@ -0,0 +1,394 @@
+"""
+Citation module for the Deep Research AI system.
+
+This module handles citation generation, source attribution, and reference
+list creation in multiple academic formats.
+"""
+
+import hashlib
+from datetime import date
+from typing import Any
+
+from ..config import Config
+from ..llm_client import LLMClient
+from ..models import Source, Citation, CitationStyle
+from ..prompts.citation_prompts import (
+    CITATION_GENERATION_PROMPT,
+    SOURCE_ATTRIBUTION_PROMPT,
+    REFERENCE_LIST_PROMPT,
+    INLINE_CITATION_PROMPT,
+    CITATION_VALIDATION_PROMPT,
+    SOURCE_METADATA_PROMPT,
+    FOOTNOTE_GENERATION_PROMPT,
+)
+
+
+class CitationManager:
+    """
+    Manages citation generation, formatting, and source attribution.
+    
+    Provides comprehensive citation support including:
+    - Multi-format citation generation (APA, MLA, Chicago, IEEE, Harvard)
+    - Source attribution mapping
+    - Reference list generation
+    - Inline citation insertion
+    - Citation validation
+    """
+    
+    def __init__(self, config: Config | None = None) -> None:
+        """
+        Initialize the CitationManager.
+        
+        Args:
+            config: Configuration object. Uses default if not provided.
+        """
+        self.config = config or Config()
+        self.llm_client = LLMClient(self.config.llm_config)
+    
+    async def generate_citations(
+        self,
+        sources: list[Source],
+        content: str
+    ) -> dict[str, Any]:
+        """
+        Generate citations for sources in multiple formats.
+        
+        Args:
+            sources: List of Source objects to cite
+            content: Content using these sources
+            
+        Returns:
+            Dictionary containing citations in multiple formats with metadata
+        """
+        sources_text = self._format_sources_for_prompt(sources)
+        
+        prompt = CITATION_GENERATION_PROMPT.format(
+            sources=sources_text,
+            content=content[:5000]  # Limit content length
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        # Convert to Citation objects
+        citations = []
+        for cit_data in result.get("citations", []):
+            citation = self._create_citation_from_data(cit_data)
+            citations.append(citation)
+        
+        return {
+            "citations": citations,
+            "bibliography": result.get("bibliography", {}),
+            "raw_response": result
+        }
+    
+    async def attribute_sources(
+        self,
+        content: str,
+        sources: list[Source]
+    ) -> dict[str, Any]:
+        """
+        Map claims in content to their original sources.
+        
+        Args:
+            content: Research content to analyze
+            sources: Available sources for attribution
+            
+        Returns:
+            Dictionary with claim-to-source attributions
+        """
+        sources_text = self._format_sources_for_prompt(sources)
+        
+        prompt = SOURCE_ATTRIBUTION_PROMPT.format(
+            content=content,
+            sources=sources_text
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "attributions": result.get("attributions", []),
+            "unattributed_claims": result.get("unattributed_claims", []),
+            "attribution_coverage": result.get("attribution_coverage", 0.0)
+        }
+    
+    async def generate_reference_list(
+        self,
+        sources: list[Source],
+        style: CitationStyle = CitationStyle.APA
+    ) -> dict[str, Any]:
+        """
+        Generate a formatted reference list in specified style.
+        
+        Args:
+            sources: Sources to include in reference list
+            style: Citation style to use
+            
+        Returns:
+            Dictionary with formatted reference list
+        """
+        sources_text = self._format_sources_for_prompt(sources)
+        
+        prompt = REFERENCE_LIST_PROMPT.format(
+            sources=sources_text,
+            citation_style=style.value
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "reference_list": result.get("reference_list", []),
+            "formatted_output": result.get("formatted_output", ""),
+            "style": style.value,
+            "total_references": result.get("total_references", len(sources))
+        }
+    
+    async def insert_inline_citations(
+        self,
+        content: str,
+        attributions: list[dict],
+        style: CitationStyle = CitationStyle.APA
+    ) -> dict[str, Any]:
+        """
+        Insert inline citations into content.
+        
+        Args:
+            content: Content to annotate
+            attributions: Source attributions from attribute_sources()
+            style: Citation style to use
+            
+        Returns:
+            Dictionary with annotated content and citation details
+        """
+        prompt = INLINE_CITATION_PROMPT.format(
+            content=content,
+            attributions=str(attributions),
+            citation_style=style.value
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "annotated_content": result.get("annotated_content", content),
+            "citation_count": result.get("citation_count", 0),
+            "citation_positions": result.get("citation_positions", []),
+            "style_used": style.value
+        }
+    
+    async def validate_citations(
+        self,
+        citations: list[Citation],
+        sources: list[Source]
+    ) -> dict[str, Any]:
+        """
+        Validate citations for accuracy and completeness.
+        
+        Args:
+            citations: Citations to validate
+            sources: Original sources for verification
+            
+        Returns:
+            Dictionary with validation results and recommendations
+        """
+        citations_text = self._format_citations_for_prompt(citations)
+        sources_text = self._format_sources_for_prompt(sources)
+        
+        prompt = CITATION_VALIDATION_PROMPT.format(
+            citations=citations_text,
+            sources=sources_text
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "validation_results": result.get("validation_results", []),
+            "overall_quality": result.get("overall_quality", 0.0),
+            "total_issues": result.get("total_issues", 0),
+            "recommendations": result.get("recommendations", [])
+        }
+    
+    async def extract_source_metadata(
+        self,
+        url: str,
+        content: str
+    ) -> dict[str, Any]:
+        """
+        Extract citation metadata from source content.
+        
+        Args:
+            url: Source URL
+            content: Source content to analyze
+            
+        Returns:
+            Dictionary with extracted metadata
+        """
+        prompt = SOURCE_METADATA_PROMPT.format(
+            url=url,
+            content=content[:8000]  # Limit content length
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "metadata": result.get("metadata", {}),
+            "extraction_confidence": result.get("extraction_confidence", {}),
+            "inferred_fields": result.get("inferred_fields", []),
+            "missing_fields": result.get("missing_fields", [])
+        }
+    
+    async def generate_footnotes(
+        self,
+        content: str,
+        sources: list[Source],
+        attributions: list[dict]
+    ) -> dict[str, Any]:
+        """
+        Generate footnotes for the content.
+        
+        Args:
+            content: Content to annotate
+            sources: Sources used
+            attributions: Source attributions
+            
+        Returns:
+            Dictionary with footnotes and annotated content
+        """
+        sources_text = self._format_sources_for_prompt(sources)
+        
+        prompt = FOOTNOTE_GENERATION_PROMPT.format(
+            content=content,
+            sources=sources_text,
+            attributions=str(attributions)
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "footnotes": result.get("footnotes", []),
+            "content_with_markers": result.get("content_with_markers", content),
+            "footnote_section": result.get("footnote_section", "")
+        }
+    
+    async def create_full_citation_package(
+        self,
+        content: str,
+        sources: list[Source],
+        style: CitationStyle = CitationStyle.APA
+    ) -> dict[str, Any]:
+        """
+        Create a complete citation package for content.
+        
+        This method combines all citation operations into one comprehensive
+        result including attributions, inline citations, and reference list.
+        
+        Args:
+            content: Research content
+            sources: Sources used in research
+            style: Citation style to use
+            
+        Returns:
+            Complete citation package with all components
+        """
+        # Step 1: Generate citations for all sources
+        citation_result = await self.generate_citations(sources, content)
+        
+        # Step 2: Attribute sources to claims
+        attribution_result = await self.attribute_sources(content, sources)
+        
+        # Step 3: Insert inline citations
+        inline_result = await self.insert_inline_citations(
+            content,
+            attribution_result["attributions"],
+            style
+        )
+        
+        # Step 4: Generate reference list
+        reference_result = await self.generate_reference_list(sources, style)
+        
+        # Step 5: Validate citations
+        validation_result = await self.validate_citations(
+            citation_result["citations"],
+            sources
+        )
+        
+        return {
+            "citations": citation_result["citations"],
+            "attributions": attribution_result["attributions"],
+            "attribution_coverage": attribution_result["attribution_coverage"],
+            "annotated_content": inline_result["annotated_content"],
+            "reference_list": reference_result["formatted_output"],
+            "citation_count": inline_result["citation_count"],
+            "validation": {
+                "quality": validation_result["overall_quality"],
+                "issues": validation_result["total_issues"],
+                "recommendations": validation_result["recommendations"]
+            },
+            "style": style.value
+        }
+    
+    def _format_sources_for_prompt(self, sources: list[Source]) -> str:
+        """Format sources for inclusion in prompts."""
+        formatted = []
+        for i, source in enumerate(sources, 1):
+            source_text = f"""
+Source {i}:
+- ID: {source.source_id}
+- URL: {source.url}
+- Title: {source.title}
+- Domain: {source.domain}
+- Content Preview: {source.content[:500] if source.content else 'N/A'}...
+- Credibility Score: {source.credibility_score}
+"""
+            formatted.append(source_text)
+        return "\n".join(formatted)
+    
+    def _format_citations_for_prompt(self, citations: list[Citation]) -> str:
+        """Format citations for inclusion in prompts."""
+        formatted = []
+        for citation in citations:
+            cit_text = f"""
+Citation for: {citation.source_id}
+- Style: {citation.style.value}
+- Formatted: {citation.formatted_citation}
+- In-text: {citation.in_text_citation}
+"""
+            formatted.append(cit_text)
+        return "\n".join(formatted)
+    
+    def _create_citation_from_data(self, data: dict) -> Citation:
+        """Create a Citation object from parsed data."""
+        source_id = data.get("source_id", "unknown")
+        
+        # Default to APA format
+        formats = data.get("formats", {})
+        formatted = formats.get("apa", "")
+        
+        in_text = data.get("in_text", {})
+        in_text_citation = in_text.get("apa", "")
+        
+        return Citation(
+            source_id=source_id,
+            style=CitationStyle.APA,
+            formatted_citation=formatted,
+            in_text_citation=in_text_citation,
+            metadata=data.get("metadata", {})
+        )
+    
+    def generate_source_id(self, url: str) -> str:
+        """
+        Generate a unique source ID from URL.
+        
+        Args:
+            url: Source URL
+            
+        Returns:
+            Unique identifier for the source
+        """
+        return hashlib.md5(url.encode()).hexdigest()[:12]
+    
+    def format_access_date(self) -> str:
+        """Get current date formatted for citations."""
+        return date.today().strftime("%Y-%m-%d")
+
+
+# Module singleton instance
+citation_manager = CitationManager()

src/modules/error_handling.py

@@ -0,0 +1,585 @@
+"""
+Error handling module for the Deep Research AI system.
+
+This module provides comprehensive error handling, recovery strategies,
+graceful degradation, and user-friendly error messaging.
+"""
+
+import logging
+import traceback
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Callable, TypeVar
+
+from ..config import Config
+from ..llm_client import LLMClient
+from ..prompts.error_prompts import (
+    ERROR_ANALYSIS_PROMPT,
+    GRACEFUL_DEGRADATION_PROMPT,
+    USER_ERROR_MESSAGE_PROMPT,
+    RETRY_STRATEGY_PROMPT,
+    ERROR_RECOVERY_PROMPT,
+    FALLBACK_CONTENT_PROMPT,
+    SYSTEM_HEALTH_PROMPT,
+)
+
+
+# Set up logging
+logger = logging.getLogger(__name__)
+
+
+class ErrorSeverity(Enum):
+    """Error severity levels."""
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+class ComponentType(Enum):
+    """System component types."""
+    QUERY_UNDERSTANDING = "query_understanding"
+    WEB_SEARCH = "web_search"
+    REASONING_ENGINE = "reasoning_engine"
+    VERIFICATION = "verification"
+    CITATION = "citation"
+    OUTPUT_GENERATION = "output_generation"
+    LLM_CLIENT = "llm_client"
+    ORCHESTRATOR = "orchestrator"
+
+
+@dataclass
+class ErrorContext:
+    """Context information for an error."""
+    component: ComponentType
+    operation: str
+    query: str | None = None
+    partial_results: dict | None = None
+    timestamp: datetime = field(default_factory=datetime.now)
+    attempt_number: int = 1
+    max_attempts: int = 3
+
+
+@dataclass
+class ErrorRecord:
+    """Record of an error occurrence."""
+    error_type: str
+    error_message: str
+    context: ErrorContext
+    severity: ErrorSeverity
+    traceback_str: str | None = None
+    recovery_attempted: bool = False
+    recovery_successful: bool = False
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+class ResearchError(Exception):
+    """Base exception for research system errors."""
+    
+    def __init__(
+        self,
+        message: str,
+        severity: ErrorSeverity = ErrorSeverity.ERROR,
+        recoverable: bool = True,
+        context: ErrorContext | None = None
+    ):
+        super().__init__(message)
+        self.message = message
+        self.severity = severity
+        self.recoverable = recoverable
+        self.context = context
+
+
+class QueryError(ResearchError):
+    """Error in query understanding."""
+    pass
+
+
+class SearchError(ResearchError):
+    """Error in web search."""
+    pass
+
+
+class ReasoningError(ResearchError):
+    """Error in reasoning engine."""
+    pass
+
+
+class VerificationError(ResearchError):
+    """Error in verification."""
+    pass
+
+
+class CitationError(ResearchError):
+    """Error in citation generation."""
+    pass
+
+
+class LLMError(ResearchError):
+    """Error in LLM communication."""
+    pass
+
+
+class RateLimitError(ResearchError):
+    """Rate limit exceeded error."""
+    pass
+
+
+# Type variable for generic retry function
+T = TypeVar('T')
+
+
+class ErrorHandler:
+    """
+    Comprehensive error handling for the research system.
+    
+    Provides:
+    - Error analysis and diagnosis
+    - Graceful degradation
+    - Retry strategies
+    - Recovery orchestration
+    - User-friendly error messages
+    """
+    
+    def __init__(self, config: Config | None = None) -> None:
+        """
+        Initialize the ErrorHandler.
+        
+        Args:
+            config: Configuration object. Uses default if not provided.
+        """
+        self.config = config or Config()
+        self.llm_client = LLMClient(self.config.llm_config)
+        self.error_history: list[ErrorRecord] = []
+        self.max_history = 100
+    
+    def record_error(
+        self,
+        error: Exception,
+        context: ErrorContext,
+        severity: ErrorSeverity = ErrorSeverity.ERROR
+    ) -> ErrorRecord:
+        """
+        Record an error occurrence.
+        
+        Args:
+            error: The exception that occurred
+            context: Error context
+            severity: Error severity level
+            
+        Returns:
+            ErrorRecord object
+        """
+        record = ErrorRecord(
+            error_type=type(error).__name__,
+            error_message=str(error),
+            context=context,
+            severity=severity,
+            traceback_str=traceback.format_exc()
+        )
+        
+        self.error_history.append(record)
+        
+        # Trim history if needed
+        if len(self.error_history) > self.max_history:
+            self.error_history = self.error_history[-self.max_history:]
+        
+        # Log the error
+        log_level = {
+            ErrorSeverity.INFO: logging.INFO,
+            ErrorSeverity.WARNING: logging.WARNING,
+            ErrorSeverity.ERROR: logging.ERROR,
+            ErrorSeverity.CRITICAL: logging.CRITICAL
+        }.get(severity, logging.ERROR)
+        
+        logger.log(
+            log_level,
+            f"Error in {context.component.value}: {record.error_message}"
+        )
+        
+        return record
+    
+    async def analyze_error(
+        self,
+        error: Exception,
+        context: ErrorContext
+    ) -> dict[str, Any]:
+        """
+        Analyze an error and suggest recovery strategies.
+        
+        Args:
+            error: The exception to analyze
+            context: Error context
+            
+        Returns:
+            Dictionary with analysis and recovery suggestions
+        """
+        prompt = ERROR_ANALYSIS_PROMPT.format(
+            error_type=type(error).__name__,
+            error_message=str(error),
+            context=str(context),
+            component=context.component.value
+        )
+        
+        try:
+            result = await self.llm_client.call_json(prompt)
+            return result
+        except Exception as e:
+            # Fallback if LLM analysis fails
+            logger.warning(f"Error analysis failed: {e}")
+            return {
+                "analysis": {
+                    "root_cause": "Unknown",
+                    "impact_level": "medium",
+                    "is_recoverable": True
+                },
+                "user_message": "An error occurred. Please try again.",
+                "recovery_strategies": []
+            }
+    
+    async def get_degraded_response(
+        self,
+        operation: str,
+        partial_results: dict | None,
+        missing_components: list[str]
+    ) -> dict[str, Any]:
+        """
+        Get a gracefully degraded response when full operation fails.
+        
+        Args:
+            operation: The failed operation
+            partial_results: Any partial results available
+            missing_components: Components that failed
+            
+        Returns:
+            Dictionary with degraded response strategy
+        """
+        prompt = GRACEFUL_DEGRADATION_PROMPT.format(
+            operation=operation,
+            partial_results=str(partial_results) if partial_results else "None",
+            missing_components=str(missing_components)
+        )
+        
+        try:
+            result = await self.llm_client.call_json(prompt)
+            return result
+        except Exception:
+            return {
+                "degraded_response": {
+                    "can_provide_partial": partial_results is not None,
+                    "available_results": partial_results,
+                    "quality_reduction": 0.5
+                },
+                "user_communication": {
+                    "message": "We encountered some issues but have partial results.",
+                    "limitations_explained": missing_components
+                }
+            }
+    
+    async def generate_user_message(
+        self,
+        error: Exception,
+        user_action: str,
+        severity: ErrorSeverity
+    ) -> dict[str, Any]:
+        """
+        Generate a user-friendly error message.
+        
+        Args:
+            error: The exception
+            user_action: What the user was trying to do
+            severity: Error severity
+            
+        Returns:
+            Dictionary with user-friendly message
+        """
+        prompt = USER_ERROR_MESSAGE_PROMPT.format(
+            error_type=type(error).__name__,
+            technical_message=str(error),
+            user_action=user_action,
+            severity=severity.value
+        )
+        
+        try:
+            result = await self.llm_client.call_json(prompt)
+            return result
+        except Exception:
+            return {
+                "user_message": {
+                    "headline": "Something went wrong",
+                    "explanation": "We encountered an issue processing your request.",
+                    "what_to_do": "Please try again. If the problem persists, try rephrasing your query.",
+                    "tone": "apologetic"
+                },
+                "severity_indicator": severity.value
+            }
+    
+    async def get_retry_strategy(
+        self,
+        operation: str,
+        failure_reason: str,
+        attempt_number: int,
+        context: dict
+    ) -> dict[str, Any]:
+        """
+        Determine optimal retry strategy.
+        
+        Args:
+            operation: Failed operation
+            failure_reason: Why it failed
+            attempt_number: Current attempt number
+            context: Operation context
+            
+        Returns:
+            Dictionary with retry strategy
+        """
+        prompt = RETRY_STRATEGY_PROMPT.format(
+            operation=operation,
+            failure_reason=failure_reason,
+            attempt_number=attempt_number,
+            context=str(context)
+        )
+        
+        try:
+            result = await self.llm_client.call_json(prompt)
+            return result
+        except Exception:
+            # Default retry strategy
+            return {
+                "retry_decision": {
+                    "should_retry": attempt_number < 3,
+                    "max_attempts": 3,
+                    "current_attempt": attempt_number
+                },
+                "timing": {
+                    "delay_seconds": attempt_number * 2,
+                    "backoff_strategy": "exponential"
+                },
+                "modifications": {
+                    "modify_request": False
+                }
+            }
+    
+    async def orchestrate_recovery(
+        self,
+        current_state: dict,
+        error_chain: list[ErrorRecord]
+    ) -> dict[str, Any]:
+        """
+        Orchestrate recovery from error state.
+        
+        Args:
+            current_state: Current system state
+            error_chain: Chain of errors that occurred
+            
+        Returns:
+            Dictionary with recovery plan
+        """
+        error_chain_text = "\n".join([
+            f"- {e.error_type}: {e.error_message}"
+            for e in error_chain
+        ])
+        
+        prompt = ERROR_RECOVERY_PROMPT.format(
+            current_state=str(current_state),
+            error_chain=error_chain_text,
+            available_resources=str(list(ComponentType))
+        )
+        
+        try:
+            result = await self.llm_client.call_json(prompt)
+            return result
+        except Exception:
+            return {
+                "state_assessment": {
+                    "corruption_level": "partial"
+                },
+                "recovery_plan": [
+                    {
+                        "step": 1,
+                        "action": "Reset to clean state",
+                        "fallback": "Manual intervention required"
+                    }
+                ]
+            }
+    
+    async def generate_fallback_content(
+        self,
+        query: str,
+        available_info: dict | None,
+        failed_sources: list[str],
+        cached_data: dict | None = None
+    ) -> dict[str, Any]:
+        """
+        Generate fallback content when primary sources fail.
+        
+        Args:
+            query: Original query
+            available_info: Any available information
+            failed_sources: Sources that failed
+            cached_data: Any cached data available
+            
+        Returns:
+            Dictionary with fallback content
+        """
+        prompt = FALLBACK_CONTENT_PROMPT.format(
+            query=query,
+            available_info=str(available_info) if available_info else "None",
+            failed_sources=str(failed_sources),
+            cached_data=str(cached_data) if cached_data else "None"
+        )
+        
+        try:
+            result = await self.llm_client.call_json(prompt)
+            return result
+        except Exception:
+            return {
+                "fallback_content": {
+                    "response": "Unable to complete the research at this time.",
+                    "confidence": 0.0,
+                    "completeness": 0.0
+                },
+                "limitations_disclosure": {
+                    "what_is_missing": failed_sources,
+                    "quality_impact": "significant"
+                }
+            }
+    
+    async def check_system_health(
+        self,
+        health_metrics: dict,
+        performance_data: dict
+    ) -> dict[str, Any]:
+        """
+        Check overall system health.
+        
+        Args:
+            health_metrics: Health metrics from components
+            performance_data: Performance statistics
+            
+        Returns:
+            Dictionary with health assessment
+        """
+        recent_errors = [
+            {"type": e.error_type, "message": e.error_message}
+            for e in self.error_history[-10:]
+        ]
+        
+        prompt = SYSTEM_HEALTH_PROMPT.format(
+            health_metrics=str(health_metrics),
+            recent_errors=str(recent_errors),
+            performance_data=str(performance_data)
+        )
+        
+        try:
+            result = await self.llm_client.call_json(prompt)
+            return result
+        except Exception:
+            # Calculate simple health based on error rate
+            error_count = len(self.error_history)
+            health_score = max(0.0, 1.0 - (error_count / 100))
+            
+            return {
+                "health_status": {
+                    "overall": "healthy" if health_score > 0.7 else "degraded",
+                    "score": health_score
+                },
+                "active_issues": [],
+                "recommendations": []
+            }
+    
+    async def retry_with_backoff(
+        self,
+        func: Callable[..., T],
+        *args,
+        max_attempts: int = 3,
+        initial_delay: float = 1.0,
+        backoff_factor: float = 2.0,
+        **kwargs
+    ) -> T:
+        """
+        Retry a function with exponential backoff.
+        
+        Args:
+            func: Async function to retry
+            *args: Positional arguments for func
+            max_attempts: Maximum retry attempts
+            initial_delay: Initial delay in seconds
+            backoff_factor: Backoff multiplier
+            **kwargs: Keyword arguments for func
+            
+        Returns:
+            Result from successful function call
+            
+        Raises:
+            Last exception if all retries fail
+        """
+        import asyncio
+        
+        last_exception = None
+        delay = initial_delay
+        
+        for attempt in range(1, max_attempts + 1):
+            try:
+                return await func(*args, **kwargs)
+            except Exception as e:
+                last_exception = e
+                
+                if attempt < max_attempts:
+                    logger.warning(
+                        f"Attempt {attempt} failed: {e}. Retrying in {delay}s..."
+                    )
+                    await asyncio.sleep(delay)
+                    delay *= backoff_factor
+        
+        raise last_exception
+    
+    def get_error_summary(self) -> dict[str, Any]:
+        """
+        Get a summary of recent errors.
+        
+        Returns:
+            Dictionary with error statistics and recent errors
+        """
+        if not self.error_history:
+            return {
+                "total_errors": 0,
+                "by_severity": {},
+                "by_component": {},
+                "recent_errors": []
+            }
+        
+        by_severity = {}
+        by_component = {}
+        
+        for record in self.error_history:
+            sev = record.severity.value
+            by_severity[sev] = by_severity.get(sev, 0) + 1
+            
+            comp = record.context.component.value
+            by_component[comp] = by_component.get(comp, 0) + 1
+        
+        return {
+            "total_errors": len(self.error_history),
+            "by_severity": by_severity,
+            "by_component": by_component,
+            "recent_errors": [
+                {
+                    "type": e.error_type,
+                    "message": e.error_message,
+                    "component": e.context.component.value,
+                    "timestamp": e.timestamp.isoformat()
+                }
+                for e in self.error_history[-5:]
+            ]
+        }
+    
+    def clear_error_history(self) -> None:
+        """Clear the error history."""
+        self.error_history = []
+        logger.info("Error history cleared")
+
+
+# Module singleton instance
+error_handler = ErrorHandler()

src/modules/output_generation.py

@@ -0,0 +1,438 @@
+"""
+Output generation module for the Deep Research AI system.
+
+This module handles the final synthesis and formatting of research results
+into user-friendly, well-structured outputs in various formats.
+"""
+
+from enum import Enum
+from typing import Any
+
+from ..config import Config
+from ..llm_client import LLMClient
+from ..models import Source, ResearchResult, OutputFormat
+from ..prompts.output_prompts import (
+    REPORT_GENERATION_PROMPT,
+    SUMMARY_GENERATION_PROMPT,
+    ANSWER_FORMATTING_PROMPT,
+    VISUALIZATION_SUGGESTION_PROMPT,
+    MULTI_FORMAT_OUTPUT_PROMPT,
+    RESPONSE_QUALITY_PROMPT,
+    FOLLOWUP_QUESTIONS_PROMPT,
+    EXPORT_FORMAT_PROMPT,
+)
+
+
+class SummaryLength(Enum):
+    """Summary length options."""
+    BRIEF = "brief"
+    STANDARD = "standard"
+    DETAILED = "detailed"
+
+
+class AudienceType(Enum):
+    """Target audience types."""
+    GENERAL = "general"
+    PROFESSIONAL = "professional"
+    ACADEMIC = "academic"
+    TECHNICAL = "technical"
+
+
+class ExportFormat(Enum):
+    """Export format options."""
+    PDF = "pdf"
+    DOCX = "docx"
+    SLIDES = "slides"
+    EMAIL = "email"
+    SOCIAL = "social"
+
+
+class OutputGenerator:
+    """
+    Generates formatted output from research results.
+    
+    Provides comprehensive output generation including:
+    - Full research reports
+    - Summaries at various lengths
+    - Multi-format output generation
+    - Quality assessment
+    - Follow-up question generation
+    """
+    
+    def __init__(self, config: Config | None = None) -> None:
+        """
+        Initialize the OutputGenerator.
+        
+        Args:
+            config: Configuration object. Uses default if not provided.
+        """
+        self.config = config or Config()
+        self.llm_client = LLMClient(self.config.llm_config)
+    
+    async def generate_report(
+        self,
+        query: str,
+        findings: dict[str, Any],
+        sources: list[Source],
+        confidence: float
+    ) -> dict[str, Any]:
+        """
+        Generate a comprehensive research report.
+        
+        Args:
+            query: Original research query
+            findings: Synthesized research findings
+            sources: Sources used in research
+            confidence: Overall confidence score
+            
+        Returns:
+            Dictionary containing the full research report
+        """
+        sources_text = self._format_sources(sources)
+        
+        prompt = REPORT_GENERATION_PROMPT.format(
+            query=query,
+            findings=str(findings),
+            sources=sources_text,
+            confidence=f"{confidence:.2%}"
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "report": result.get("report", {}),
+            "metadata": result.get("metadata", {}),
+            "format": OutputFormat.MARKDOWN
+        }
+    
+    async def generate_summary(
+        self,
+        findings: dict[str, Any],
+        length: SummaryLength = SummaryLength.STANDARD
+    ) -> dict[str, Any]:
+        """
+        Generate a summary of research findings.
+        
+        Args:
+            findings: Research findings to summarize
+            length: Desired summary length
+            
+        Returns:
+            Dictionary containing the summary
+        """
+        prompt = SUMMARY_GENERATION_PROMPT.format(
+            findings=str(findings),
+            length=length.value
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "summary": result.get("summary", {}),
+            "metadata": result.get("metadata", {})
+        }
+    
+    async def format_answer(
+        self,
+        answer: str,
+        audience: AudienceType = AudienceType.GENERAL,
+        output_format: OutputFormat = OutputFormat.MARKDOWN
+    ) -> dict[str, Any]:
+        """
+        Format an answer for a specific audience and format.
+        
+        Args:
+            answer: The answer to format
+            audience: Target audience
+            output_format: Desired output format
+            
+        Returns:
+            Dictionary containing the formatted answer
+        """
+        prompt = ANSWER_FORMATTING_PROMPT.format(
+            answer=answer,
+            audience=audience.value,
+            format=output_format.value
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "formatted_answer": result.get("formatted_answer", {}),
+            "readability_metrics": result.get("readability_metrics", {})
+        }
+    
+    async def suggest_visualizations(
+        self,
+        data: dict[str, Any],
+        findings: dict[str, Any]
+    ) -> dict[str, Any]:
+        """
+        Suggest visualizations for research data.
+        
+        Args:
+            data: Numerical or structured data
+            findings: Research findings
+            
+        Returns:
+            Dictionary with visualization suggestions
+        """
+        prompt = VISUALIZATION_SUGGESTION_PROMPT.format(
+            data=str(data),
+            findings=str(findings)
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "visualizations": result.get("visualizations", []),
+            "recommended_count": result.get("recommended_count", 0),
+            "data_visualization_potential": result.get("data_visualization_potential", "low")
+        }
+    
+    async def generate_multi_format(
+        self,
+        content: str,
+        citations: str
+    ) -> dict[str, Any]:
+        """
+        Generate output in multiple formats simultaneously.
+        
+        Args:
+            content: Research content
+            citations: Citation information
+            
+        Returns:
+            Dictionary with content in multiple formats
+        """
+        prompt = MULTI_FORMAT_OUTPUT_PROMPT.format(
+            content=content,
+            citations=citations
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "outputs": result.get("outputs", {}),
+            "recommended_format": result.get("recommended_format", "markdown"),
+            "format_notes": result.get("format_notes", {})
+        }
+    
+    async def assess_quality(
+        self,
+        query: str,
+        response: str,
+        sources: list[Source]
+    ) -> dict[str, Any]:
+        """
+        Assess the quality of a generated response.
+        
+        Args:
+            query: Original query
+            response: Generated response
+            sources: Sources used
+            
+        Returns:
+            Dictionary with quality assessment
+        """
+        sources_text = self._format_sources(sources)
+        
+        prompt = RESPONSE_QUALITY_PROMPT.format(
+            query=query,
+            response=response,
+            sources=sources_text
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "quality_assessment": result.get("quality_assessment", {}),
+            "confidence_level": result.get("confidence_level", "medium"),
+            "ready_for_delivery": result.get("ready_for_delivery", False),
+            "revision_needed": result.get("revision_needed", True)
+        }
+    
+    async def generate_followup_questions(
+        self,
+        query: str,
+        findings: dict[str, Any],
+        gaps: list[str]
+    ) -> dict[str, Any]:
+        """
+        Generate relevant follow-up questions.
+        
+        Args:
+            query: Original query
+            findings: Research findings
+            gaps: Identified information gaps
+            
+        Returns:
+            Dictionary with follow-up questions
+        """
+        prompt = FOLLOWUP_QUESTIONS_PROMPT.format(
+            query=query,
+            findings=str(findings),
+            gaps=str(gaps)
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "follow_up_questions": result.get("follow_up_questions", []),
+            "recommended_next_question": result.get("recommended_next_question", ""),
+            "research_continuation_score": result.get("research_continuation_score", 0.0)
+        }
+    
+    async def prepare_for_export(
+        self,
+        report: dict[str, Any],
+        export_format: ExportFormat
+    ) -> dict[str, Any]:
+        """
+        Prepare research output for export.
+        
+        Args:
+            report: Research report
+            export_format: Target export format
+            
+        Returns:
+            Dictionary with export-ready content
+        """
+        prompt = EXPORT_FORMAT_PROMPT.format(
+            report=str(report),
+            export_format=export_format.value
+        )
+        
+        result = await self.llm_client.call_json(prompt)
+        
+        return {
+            "export_ready": result.get("export_ready", {}),
+            "export_metadata": result.get("export_metadata", {})
+        }
+    
+    async def create_research_result(
+        self,
+        query: str,
+        findings: dict[str, Any],
+        sources: list[Source],
+        confidence: float,
+        audience: AudienceType = AudienceType.GENERAL
+    ) -> ResearchResult:
+        """
+        Create a complete ResearchResult object.
+        
+        This method combines all output generation capabilities into
+        a single comprehensive research result.
+        
+        Args:
+            query: Original query
+            findings: Research findings
+            sources: Sources used
+            confidence: Confidence score
+            audience: Target audience
+            
+        Returns:
+            Complete ResearchResult object
+        """
+        # Generate the main report
+        report_result = await self.generate_report(
+            query, findings, sources, confidence
+        )
+        
+        # Generate summary
+        summary_result = await self.generate_summary(
+            findings, SummaryLength.STANDARD
+        )
+        
+        # Assess quality
+        report_text = self._report_to_text(report_result["report"])
+        quality_result = await self.assess_quality(query, report_text, sources)
+        
+        # Generate follow-up questions
+        gaps = findings.get("information_gaps", [])
+        followup_result = await self.generate_followup_questions(
+            query, findings, gaps
+        )
+        
+        # Build the research result
+        return ResearchResult(
+            query=query,
+            answer=summary_result["summary"].get("text", ""),
+            confidence=confidence,
+            sources=sources,
+            reasoning_steps=findings.get("reasoning_steps", []),
+            verification_status=findings.get("verification_status", "unverified"),
+            metadata={
+                "full_report": report_result["report"],
+                "quality_assessment": quality_result["quality_assessment"],
+                "follow_up_questions": followup_result["follow_up_questions"],
+                "audience": audience.value
+            }
+        )
+    
+    def _format_sources(self, sources: list[Source]) -> str:
+        """Format sources for prompts."""
+        formatted = []
+        for i, source in enumerate(sources, 1):
+            formatted.append(f"""
+Source {i}:
+- Title: {source.title}
+- URL: {source.url}
+- Credibility: {source.credibility_score}
+""")
+        return "\n".join(formatted)
+    
+    def _report_to_text(self, report: dict) -> str:
+        """Convert report dict to plain text."""
+        parts = []
+        
+        if "title" in report:
+            parts.append(f"# {report['title']}\n")
+        
+        if "executive_summary" in report:
+            parts.append(f"## Executive Summary\n{report['executive_summary']}\n")
+        
+        if "main_findings" in report:
+            parts.append("## Main Findings\n")
+            for finding in report["main_findings"]:
+                parts.append(f"### {finding.get('theme', 'Finding')}\n")
+                parts.append(f"{finding.get('content', '')}\n")
+        
+        if "conclusion" in report:
+            conclusion = report["conclusion"]
+            parts.append("## Conclusion\n")
+            parts.append(f"{conclusion.get('answer', '')}\n")
+        
+        return "\n".join(parts)
+    
+    def render_markdown(self, report: dict) -> str:
+        """
+        Render a report as markdown.
+        
+        Args:
+            report: Report dictionary
+            
+        Returns:
+            Markdown formatted string
+        """
+        return self._report_to_text(report)
+    
+    def render_html(self, report: dict) -> str:
+        """
+        Render a report as HTML.
+        
+        Args:
+            report: Report dictionary
+            
+        Returns:
+            HTML formatted string
+        """
+        md = self._report_to_text(report)
+        # Basic markdown to HTML conversion
+        html = md.replace("# ", "<h1>").replace("\n## ", "</h1>\n<h2>")
+        html = html.replace("\n### ", "</h2>\n<h3>").replace("\n\n", "</p>\n<p>")
+        return f"<html><body>{html}</body></html>"
+
+
+# Module singleton instance
+output_generator = OutputGenerator()

src/modules/query_understanding.py

@@ -0,0 +1,224 @@
+"""
+Query Understanding Module - Parses and analyzes research queries.
+"""
+
+import logging
+from typing import Optional, Dict, Any, List
+
+from ..models import QueryAnalysis, Entity, QueryComplexity
+from ..llm_client import llm_client
+from ..prompts.query_prompts import QUERY_PROMPTS
+
+logger = logging.getLogger(__name__)
+
+
+class QueryUnderstanding:
+    """
+    Query Understanding module for analyzing and decomposing research queries.
+    
+    Implements FR-1: Query Understanding requirements.
+    """
+    
+    def __init__(self):
+        self.llm = llm_client
+    
+    async def analyze_query(self, query: str) -> QueryAnalysis:
+        """
+        Analyze a research query to understand intent, entities, and structure.
+        
+        Args:
+            query: Raw natural language research query
+            
+        Returns:
+            QueryAnalysis object with parsed query information
+        """
+        logger.info(f"Analyzing query: {query[:100]}...")
+        
+        # First, validate the query
+        validation = await self._validate_query(query)
+        if not validation.get("proceed", True):
+            logger.warning(f"Query validation failed: {validation}")
+            # Create minimal analysis for invalid query
+            analysis = QueryAnalysis(raw_query=query)
+            analysis.sub_queries = []
+            return analysis
+        
+        # Analyze the query
+        analysis_result = await self._analyze(query)
+        
+        # Extract entities
+        entities = await self._extract_entities(query)
+        
+        # Classify intent
+        intent_result = await self._classify_intent(query)
+        
+        # Build QueryAnalysis object
+        analysis = self._build_analysis(
+            query=query,
+            analysis_result=analysis_result,
+            entities=entities,
+            intent_result=intent_result
+        )
+        
+        # Decompose into sub-queries if complex
+        if analysis.complexity in [QueryComplexity.MEDIUM, QueryComplexity.COMPLEX]:
+            sub_queries = await self._decompose_query(query, analysis_result)
+            analysis.sub_queries = sub_queries
+        else:
+            analysis.sub_queries = [query]
+        
+        logger.info(f"Query analysis complete. Complexity: {analysis.complexity.value}, "
+                   f"Sub-queries: {len(analysis.sub_queries)}")
+        
+        return analysis
+    
+    async def _validate_query(self, query: str) -> Dict[str, Any]:
+        """Validate if the query is researchable and appropriate."""
+        prompt = QUERY_PROMPTS["validation"].format(query=query)
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Query validation failed: {e}")
+            return {"proceed": True, "is_valid": True}
+    
+    async def _analyze(self, query: str) -> Dict[str, Any]:
+        """Perform main query analysis."""
+        prompt = QUERY_PROMPTS["analysis"].format(query=query)
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Query analysis failed: {e}")
+            return {
+                "intent": "unknown",
+                "domain": "general",
+                "entities": [],
+                "complexity": "medium",
+                "output_type": "report"
+            }
+    
+    async def _extract_entities(self, query: str) -> List[Entity]:
+        """Extract named entities from the query."""
+        prompt = QUERY_PROMPTS["entity_extraction"].format(query=query)
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            entities = []
+            
+            for entity_data in result.get("entities", []):
+                entity = Entity(
+                    text=entity_data.get("text", ""),
+                    type=entity_data.get("type", "CONCEPT"),
+                    relevance=entity_data.get("relevance", "secondary"),
+                    context=entity_data.get("context")
+                )
+                entities.append(entity)
+            
+            return entities
+        except Exception as e:
+            logger.error(f"Entity extraction failed: {e}")
+            return []
+    
+    async def _classify_intent(self, query: str) -> Dict[str, Any]:
+        """Classify the query intent."""
+        prompt = QUERY_PROMPTS["intent_classification"].format(query=query)
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Intent classification failed: {e}")
+            return {
+                "primary_intent": "EXPLORATORY",
+                "confidence": 0.5,
+                "research_approach": "general"
+            }
+    
+    async def _decompose_query(
+        self, 
+        query: str, 
+        analysis: Dict[str, Any]
+    ) -> List[str]:
+        """Decompose a complex query into sub-queries."""
+        import json
+        
+        prompt = QUERY_PROMPTS["decomposition"].format(
+            query=query,
+            query_analysis=json.dumps(analysis, indent=2)
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            sub_queries = []
+            
+            for sq in result.get("sub_queries", []):
+                sub_queries.append(sq.get("query", ""))
+            
+            # Ensure we have at least the original query
+            if not sub_queries:
+                sub_queries = [query]
+            
+            return sub_queries
+        except Exception as e:
+            logger.error(f"Query decomposition failed: {e}")
+            return [query]
+    
+    async def check_clarity(self, query: str) -> Dict[str, Any]:
+        """Check if the query needs clarification."""
+        prompt = QUERY_PROMPTS["clarification"].format(query=query)
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Clarity check failed: {e}")
+            return {"is_clear": True, "ambiguities": []}
+    
+    def _build_analysis(
+        self,
+        query: str,
+        analysis_result: Dict[str, Any],
+        entities: List[Entity],
+        intent_result: Dict[str, Any]
+    ) -> QueryAnalysis:
+        """Build a QueryAnalysis object from component results."""
+        # Map complexity string to enum
+        complexity_map = {
+            "simple": QueryComplexity.SIMPLE,
+            "medium": QueryComplexity.MEDIUM,
+            "complex": QueryComplexity.COMPLEX
+        }
+        
+        complexity_str = analysis_result.get("complexity", "medium").lower()
+        complexity = complexity_map.get(complexity_str, QueryComplexity.MEDIUM)
+        
+        # Combine entities from analysis and extraction
+        all_entities = entities.copy()
+        for entity_data in analysis_result.get("entities", []):
+            if isinstance(entity_data, dict):
+                entity = Entity(
+                    text=entity_data.get("text", ""),
+                    type=entity_data.get("type", "CONCEPT"),
+                    relevance=entity_data.get("relevance", "secondary")
+                )
+                # Avoid duplicates
+                if not any(e.text == entity.text for e in all_entities):
+                    all_entities.append(entity)
+        
+        return QueryAnalysis(
+            raw_query=query,
+            intent=intent_result.get("primary_intent", analysis_result.get("intent", "")),
+            domain=analysis_result.get("domain", "general"),
+            entities=all_entities,
+            temporal_scope=analysis_result.get("temporal_scope"),
+            geographic_scope=analysis_result.get("geographic_scope"),
+            complexity=complexity,
+            output_type=analysis_result.get("output_type", "report")
+        )
+
+
+# Module instance
+query_understanding = QueryUnderstanding()

src/modules/reasoning_engine.py

@@ -0,0 +1,408 @@
+"""
+Reasoning Engine Module - Multi-step reasoning and information synthesis.
+"""
+
+import logging
+import json
+from typing import Optional, Dict, Any, List
+
+from ..models import (
+    QueryAnalysis, Source, Finding, Claim, 
+    ConfidenceLevel, VerificationStatus
+)
+from ..llm_client import llm_client
+from ..prompts.reasoning_prompts import REASONING_PROMPTS
+
+logger = logging.getLogger(__name__)
+
+
+class ReasoningEngine:
+    """
+    Reasoning Engine for multi-step reasoning over gathered information.
+    
+    Implements FR-3: Multi-Step Reasoning requirements.
+    """
+    
+    def __init__(self):
+        self.llm = llm_client
+    
+    async def reason(
+        self,
+        query: QueryAnalysis,
+        sources: List[Source],
+        extracted_info: Optional[List[Dict[str, Any]]] = None
+    ) -> List[Finding]:
+        """
+        Perform multi-step reasoning over gathered information.
+        
+        Args:
+            query: Analyzed query
+            sources: List of sources with content
+            extracted_info: Optional pre-extracted information
+            
+        Returns:
+            List of findings from reasoning
+        """
+        logger.info(f"Starting reasoning for query: {query.raw_query[:50]}...")
+        
+        # Prepare context from sources
+        context = self._prepare_context(sources, extracted_info)
+        
+        # Perform chain-of-thought reasoning
+        reasoning_result = await self._chain_of_thought(
+            query.raw_query,
+            context,
+            sources
+        )
+        
+        # Synthesize across sources
+        synthesis = await self._synthesize(query.raw_query, sources)
+        
+        # Check if this is a comparative query
+        if query.intent in ["COMPARATIVE", "EVALUATIVE"]:
+            comparison = await self._comparative_analysis(
+                query.raw_query,
+                sources,
+                context
+            )
+            synthesis["comparison"] = comparison
+        
+        # Build findings from reasoning results
+        findings = self._build_findings(
+            reasoning_result,
+            synthesis,
+            sources
+        )
+        
+        # Identify gaps
+        gaps = await self._identify_gaps(
+            query.raw_query,
+            findings,
+            sources
+        )
+        
+        # Add gap information to findings
+        if gaps.get("priority_gaps"):
+            for finding in findings:
+                finding.caveats.extend(gaps.get("priority_gaps", [])[:2])
+        
+        logger.info(f"Reasoning complete. Generated {len(findings)} findings")
+        return findings
+    
+    async def _chain_of_thought(
+        self,
+        query: str,
+        context: str,
+        sources: List[Source]
+    ) -> Dict[str, Any]:
+        """Perform chain-of-thought reasoning."""
+        sources_summary = self._summarize_sources(sources)
+        
+        prompt = REASONING_PROMPTS["chain_of_thought"].format(
+            query=query,
+            context=context,
+            sources=sources_summary
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Chain-of-thought reasoning failed: {e}")
+            return {
+                "reasoning_chain": [],
+                "final_answer": "",
+                "confidence": 0.5,
+                "gaps_identified": []
+            }
+    
+    async def _synthesize(
+        self,
+        query: str,
+        sources: List[Source]
+    ) -> Dict[str, Any]:
+        """Synthesize information across sources."""
+        sources_with_content = []
+        for source in sources:
+            sources_with_content.append({
+                "url": source.url,
+                "title": source.title,
+                "content": source.content[:3000] if source.content else source.snippet,
+                "credibility": source.credibility_level
+            })
+        
+        prompt = REASONING_PROMPTS["synthesis"].format(
+            query=query,
+            sources_with_content=json.dumps(sources_with_content, indent=2)
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Synthesis failed: {e}")
+            return {
+                "themes": [],
+                "consensus_findings": [],
+                "disagreements": [],
+                "synthesis": "",
+                "key_insights": []
+            }
+    
+    async def _comparative_analysis(
+        self,
+        query: str,
+        sources: List[Source],
+        context: str
+    ) -> Dict[str, Any]:
+        """Perform comparative analysis if query involves comparison."""
+        # Extract subjects to compare from query
+        subjects = self._extract_comparison_subjects(query)
+        
+        prompt = REASONING_PROMPTS["comparative_analysis"].format(
+            query=query,
+            subjects=json.dumps(subjects),
+            context=context
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Comparative analysis failed: {e}")
+            return {}
+    
+    async def _causal_analysis(
+        self,
+        query: str,
+        context: str
+    ) -> Dict[str, Any]:
+        """Perform causal analysis if applicable."""
+        prompt = REASONING_PROMPTS["causal_analysis"].format(
+            query=query,
+            context=context
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Causal analysis failed: {e}")
+            return {}
+    
+    async def _identify_gaps(
+        self,
+        query: str,
+        findings: List[Finding],
+        sources: List[Source]
+    ) -> Dict[str, Any]:
+        """Identify gaps in current research."""
+        findings_summary = [
+            {"title": f.title, "content": f.content[:500]}
+            for f in findings
+        ]
+        sources_summary = [
+            {"url": s.url, "title": s.title}
+            for s in sources
+        ]
+        
+        prompt = REASONING_PROMPTS["gap_analysis"].format(
+            query=query,
+            findings=json.dumps(findings_summary, indent=2),
+            sources=json.dumps(sources_summary, indent=2)
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Gap analysis failed: {e}")
+            return {"can_proceed": True, "priority_gaps": []}
+    
+    async def verify_reasoning(
+        self,
+        reasoning_chain: List[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Verify the logical soundness of a reasoning chain."""
+        prompt = REASONING_PROMPTS["reasoning_verification"].format(
+            reasoning_chain=json.dumps(reasoning_chain, indent=2)
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Reasoning verification failed: {e}")
+            return {"is_valid": True, "validity_score": 70}
+    
+    def _prepare_context(
+        self,
+        sources: List[Source],
+        extracted_info: Optional[List[Dict[str, Any]]] = None
+    ) -> str:
+        """Prepare context string from sources and extracted info."""
+        context_parts = []
+        
+        for i, source in enumerate(sources, 1):
+            content = source.content if source.content else source.snippet
+            if content:
+                context_parts.append(
+                    f"[Source {i}: {source.title}]\n"
+                    f"URL: {source.url}\n"
+                    f"Content: {content[:2000]}\n"
+                )
+        
+        if extracted_info:
+            context_parts.append("\n[Extracted Key Information]")
+            for info in extracted_info:
+                context_parts.append(f"- {info.get('content', '')}")
+        
+        return "\n".join(context_parts)
+    
+    def _summarize_sources(self, sources: List[Source]) -> str:
+        """Create a summary of sources for prompts."""
+        summaries = []
+        for i, source in enumerate(sources, 1):
+            summaries.append(
+                f"[{i}] {source.title} ({source.url}) - "
+                f"Credibility: {source.credibility_level}"
+            )
+        return "\n".join(summaries)
+    
+    def _extract_comparison_subjects(self, query: str) -> List[str]:
+        """Extract subjects being compared from query."""
+        # Simple extraction - in real implementation, use NLP
+        comparison_words = ["vs", "versus", "compare", "between", "and"]
+        subjects = []
+        
+        query_lower = query.lower()
+        for word in comparison_words:
+            if word in query_lower:
+                # Very basic extraction
+                parts = query_lower.split(word)
+                if len(parts) >= 2:
+                    subjects = [parts[0].strip(), parts[1].strip()]
+                    break
+        
+        return subjects if subjects else ["Subject A", "Subject B"]
+    
+    def _build_findings(
+        self,
+        reasoning_result: Dict[str, Any],
+        synthesis: Dict[str, Any],
+        sources: List[Source]
+    ) -> List[Finding]:
+        """Build Finding objects from reasoning results."""
+        findings = []
+        source_ids = [s.id for s in sources]
+        
+        # Create finding from main answer
+        if reasoning_result.get("final_answer"):
+            confidence = reasoning_result.get("confidence", 0.5)
+            
+            main_finding = Finding(
+                title="Main Finding",
+                content=reasoning_result["final_answer"],
+                category="main",
+                confidence_score=confidence,
+                confidence_level=self._score_to_level(confidence),
+                source_ids=source_ids[:5],  # Top 5 sources
+                reasoning_chain=[
+                    step.get("thought", "")
+                    for step in reasoning_result.get("reasoning_chain", [])
+                ],
+                caveats=reasoning_result.get("gaps_identified", [])
+            )
+            findings.append(main_finding)
+        
+        # Create findings from themes
+        for theme in synthesis.get("themes", []):
+            finding = Finding(
+                title=theme.get("theme", "Theme"),
+                content=theme.get("description", ""),
+                category="theme",
+                confidence_score=0.7,
+                confidence_level=ConfidenceLevel.HIGH,
+                source_ids=source_ids[:3],
+            )
+            
+            # Add key points as claims
+            for point in theme.get("key_points", []):
+                claim = Claim(
+                    content=point,
+                    source_ids=source_ids[:2],
+                    verification_status=VerificationStatus.PARTIALLY_VERIFIED,
+                    confidence_score=0.7
+                )
+                finding.claims.append(claim)
+            
+            findings.append(finding)
+        
+        # Create findings from consensus
+        for consensus in synthesis.get("consensus_findings", []):
+            confidence = 0.9 if consensus.get("confidence") == "high" else 0.7
+            
+            finding = Finding(
+                title="Consensus Finding",
+                content=consensus.get("finding", ""),
+                category="consensus",
+                confidence_score=confidence,
+                confidence_level=self._score_to_level(confidence),
+                source_ids=source_ids[:3],
+            )
+            findings.append(finding)
+        
+        # Note disagreements
+        for disagreement in synthesis.get("disagreements", []):
+            finding = Finding(
+                title=f"Disputed: {disagreement.get('topic', 'Topic')}",
+                content=self._format_disagreement(disagreement),
+                category="disagreement",
+                confidence_score=0.5,
+                confidence_level=ConfidenceLevel.MEDIUM,
+                source_ids=source_ids[:3],
+                caveats=["Sources disagree on this topic"]
+            )
+            findings.append(finding)
+        
+        # Add key insights
+        if synthesis.get("key_insights"):
+            finding = Finding(
+                title="Key Insights",
+                content="\n".join(f"• {insight}" for insight in synthesis["key_insights"]),
+                category="insights",
+                confidence_score=0.8,
+                confidence_level=ConfidenceLevel.HIGH,
+                source_ids=source_ids[:5],
+            )
+            findings.append(finding)
+        
+        return findings
+    
+    def _format_disagreement(self, disagreement: Dict[str, Any]) -> str:
+        """Format a disagreement for display."""
+        parts = [f"Topic: {disagreement.get('topic', 'Unknown')}"]
+        
+        for perspective in disagreement.get("perspectives", []):
+            parts.append(
+                f"• {perspective.get('source', 'Source')}: {perspective.get('position', '')}"
+            )
+        
+        return "\n".join(parts)
+    
+    def _score_to_level(self, score: float) -> ConfidenceLevel:
+        """Convert numeric score to confidence level."""
+        if score >= 0.9:
+            return ConfidenceLevel.VERY_HIGH
+        elif score >= 0.7:
+            return ConfidenceLevel.HIGH
+        elif score >= 0.5:
+            return ConfidenceLevel.MEDIUM
+        elif score >= 0.3:
+            return ConfidenceLevel.LOW
+        else:
+            return ConfidenceLevel.VERY_LOW
+
+
+# Module instance
+reasoning_engine = ReasoningEngine()

src/modules/verification.py

@@ -0,0 +1,399 @@
+"""
+Verification Module - Validates and verifies research findings.
+"""
+
+import logging
+import json
+from typing import Optional, Dict, Any, List
+
+from ..models import (
+    Source, Finding, Claim, VerificationResult, Conflict,
+    VerificationStatus, ConfidenceLevel
+)
+from ..llm_client import llm_client
+from ..prompts.verification_prompts import VERIFICATION_PROMPTS
+
+logger = logging.getLogger(__name__)
+
+
+class VerificationModule:
+    """
+    Verification module for validating research findings.
+    
+    Implements FR-4: Source Verification requirements.
+    """
+    
+    def __init__(self):
+        self.llm = llm_client
+    
+    async def verify(
+        self,
+        findings: List[Finding],
+        sources: List[Source]
+    ) -> VerificationResult:
+        """
+        Verify research findings against sources.
+        
+        Args:
+            findings: List of findings to verify
+            sources: List of sources used
+            
+        Returns:
+            VerificationResult with verification details
+        """
+        logger.info(f"Verifying {len(findings)} findings against {len(sources)} sources")
+        
+        # Extract claims from findings
+        all_claims = self._extract_claims(findings)
+        
+        # Cross-reference claims
+        cross_ref_result = await self._cross_reference(all_claims, sources)
+        
+        # Assess source credibility
+        credibility_result = await self._assess_credibility(sources)
+        
+        # Detect conflicts
+        conflict_result = await self._detect_conflicts(findings, sources)
+        
+        # Flag uncertainties
+        uncertainty_result = await self._flag_uncertainties(findings, sources)
+        
+        # Detect biases
+        bias_result = await self._detect_bias(findings, sources)
+        
+        # Generate verification summary
+        verification = await self._generate_summary(
+            findings,
+            cross_ref_result,
+            credibility_result,
+            conflict_result,
+            uncertainty_result
+        )
+        
+        # Update claims with verification status
+        self._update_claim_status(all_claims, cross_ref_result)
+        
+        # Build verification result
+        result = self._build_verification_result(
+            findings,
+            all_claims,
+            conflict_result,
+            verification
+        )
+        
+        logger.info(f"Verification complete. Overall confidence: {result.overall_confidence:.2f}")
+        return result
+    
+    async def _cross_reference(
+        self,
+        claims: List[Claim],
+        sources: List[Source]
+    ) -> Dict[str, Any]:
+        """Cross-reference claims against sources."""
+        claims_data = [
+            {"id": c.id, "content": c.content}
+            for c in claims
+        ]
+        
+        sources_data = [
+            {
+                "url": s.url,
+                "title": s.title,
+                "content": s.content[:2000] if s.content else s.snippet,
+                "credibility": s.credibility_level
+            }
+            for s in sources
+        ]
+        
+        prompt = VERIFICATION_PROMPTS["cross_reference"].format(
+            claims=json.dumps(claims_data, indent=2),
+            sources=json.dumps(sources_data, indent=2)
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Cross-reference failed: {e}")
+            return {"verified_claims": [], "verification_summary": {}}
+    
+    async def _assess_credibility(
+        self,
+        sources: List[Source]
+    ) -> Dict[str, Any]:
+        """Assess the credibility of sources."""
+        sources_data = [
+            {
+                "url": s.url,
+                "title": s.title,
+                "domain": s.domain,
+                "author": s.author,
+                "publication_date": s.publication_date,
+                "snippet": s.snippet[:500] if s.snippet else ""
+            }
+            for s in sources
+        ]
+        
+        prompt = VERIFICATION_PROMPTS["credibility_assessment"].format(
+            sources=json.dumps(sources_data, indent=2)
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            
+            # Update source credibility scores
+            assessments = {a["url"]: a for a in result.get("source_assessments", [])}
+            for source in sources:
+                if source.url in assessments:
+                    assessment = assessments[source.url]
+                    source.credibility_score = assessment.get("credibility_score", 50) / 100
+                    source.credibility_level = assessment.get("credibility_level", "medium")
+            
+            return result
+        except Exception as e:
+            logger.error(f"Credibility assessment failed: {e}")
+            return {"source_assessments": []}
+    
+    async def _detect_conflicts(
+        self,
+        findings: List[Finding],
+        sources: List[Source]
+    ) -> Dict[str, Any]:
+        """Detect conflicts in findings."""
+        findings_data = [
+            {"title": f.title, "content": f.content}
+            for f in findings
+        ]
+        
+        sources_data = [
+            {
+                "url": s.url,
+                "title": s.title,
+                "content": s.content[:1500] if s.content else s.snippet
+            }
+            for s in sources
+        ]
+        
+        prompt = VERIFICATION_PROMPTS["conflict_detection"].format(
+            findings=json.dumps(findings_data, indent=2),
+            sources=json.dumps(sources_data, indent=2)
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Conflict detection failed: {e}")
+            return {"conflicts_detected": [], "overall_consistency": 75}
+    
+    async def _flag_uncertainties(
+        self,
+        findings: List[Finding],
+        sources: List[Source]
+    ) -> Dict[str, Any]:
+        """Flag uncertain claims."""
+        findings_data = [
+            {"title": f.title, "content": f.content, "confidence": f.confidence_score}
+            for f in findings
+        ]
+        
+        sources_data = [
+            {"url": s.url, "title": s.title}
+            for s in sources
+        ]
+        
+        prompt = VERIFICATION_PROMPTS["uncertainty_flagging"].format(
+            findings=json.dumps(findings_data, indent=2),
+            sources=json.dumps(sources_data, indent=2)
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Uncertainty flagging failed: {e}")
+            return {"uncertain_claims": [], "caveats_to_include": []}
+    
+    async def _detect_bias(
+        self,
+        findings: List[Finding],
+        sources: List[Source]
+    ) -> Dict[str, Any]:
+        """Detect potential biases."""
+        findings_data = [
+            {"title": f.title, "content": f.content}
+            for f in findings
+        ]
+        
+        sources_data = [
+            {"url": s.url, "domain": s.domain, "title": s.title}
+            for s in sources
+        ]
+        
+        prompt = VERIFICATION_PROMPTS["bias_detection"].format(
+            findings=json.dumps(findings_data, indent=2),
+            sources=json.dumps(sources_data, indent=2)
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Bias detection failed: {e}")
+            return {"biases_detected": [], "balance_assessment": {"is_balanced": True}}
+    
+    async def _generate_summary(
+        self,
+        findings: List[Finding],
+        cross_ref: Dict[str, Any],
+        credibility: Dict[str, Any],
+        conflicts: Dict[str, Any],
+        uncertainty: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Generate verification summary."""
+        findings_data = [
+            {"title": f.title, "content": f.content[:500]}
+            for f in findings
+        ]
+        
+        prompt = VERIFICATION_PROMPTS["verification_summary"].format(
+            findings=json.dumps(findings_data, indent=2),
+            cross_reference_results=json.dumps(cross_ref.get("verification_summary", {})),
+            credibility_results=json.dumps(credibility.get("overall_source_quality", "medium")),
+            conflict_results=json.dumps({"count": len(conflicts.get("conflicts_detected", []))}),
+            uncertainty_results=json.dumps({"caveats": uncertainty.get("caveats_to_include", [])})
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Verification summary failed: {e}")
+            return {
+                "verification_summary": {
+                    "overall_confidence": 0.7,
+                    "trust_level": "medium"
+                },
+                "caveats": [],
+                "flags": []
+            }
+    
+    async def fact_check(
+        self,
+        claims: List[str],
+        context: str,
+        evidence: List[Dict[str, Any]]
+    ) -> Dict[str, Any]:
+        """Perform fact-checking on specific claims."""
+        prompt = VERIFICATION_PROMPTS["fact_check"].format(
+            claims=json.dumps(claims, indent=2),
+            context=context,
+            evidence=json.dumps(evidence, indent=2)
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result
+        except Exception as e:
+            logger.error(f"Fact check failed: {e}")
+            return {"fact_checks": []}
+    
+    def _extract_claims(self, findings: List[Finding]) -> List[Claim]:
+        """Extract all claims from findings."""
+        claims = []
+        
+        for finding in findings:
+            # Add existing claims
+            claims.extend(finding.claims)
+            
+            # Create a claim from the finding content if no claims exist
+            if not finding.claims:
+                claim = Claim(
+                    content=finding.content,
+                    source_ids=finding.source_ids,
+                    confidence_score=finding.confidence_score
+                )
+                claims.append(claim)
+                finding.claims.append(claim)
+        
+        return claims
+    
+    def _update_claim_status(
+        self,
+        claims: List[Claim],
+        cross_ref_result: Dict[str, Any]
+    ):
+        """Update claim verification status based on cross-reference results."""
+        verified_claims = {
+            vc.get("claim", ""): vc
+            for vc in cross_ref_result.get("verified_claims", [])
+        }
+        
+        for claim in claims:
+            # Find matching verified claim
+            for claim_text, vc in verified_claims.items():
+                if claim.content in claim_text or claim_text in claim.content:
+                    status = vc.get("status", "unverified")
+                    
+                    if status == "verified":
+                        claim.verification_status = VerificationStatus.VERIFIED
+                    elif status == "disputed":
+                        claim.verification_status = VerificationStatus.DISPUTED
+                    else:
+                        claim.verification_status = VerificationStatus.UNVERIFIED
+                    
+                    claim.confidence_score = vc.get("confidence", claim.confidence_score)
+                    
+                    # Add supporting evidence
+                    for support in vc.get("supporting_sources", []):
+                        claim.supporting_evidence.append(support.get("quote", ""))
+                    
+                    # Add contradicting evidence
+                    for contra in vc.get("contradicting_sources", []):
+                        claim.contradicting_evidence.append(contra.get("quote", ""))
+                    
+                    break
+    
+    def _build_verification_result(
+        self,
+        findings: List[Finding],
+        claims: List[Claim],
+        conflict_result: Dict[str, Any],
+        verification_summary: Dict[str, Any]
+    ) -> VerificationResult:
+        """Build the final verification result."""
+        summary = verification_summary.get("verification_summary", {})
+        
+        # Build conflicts
+        conflicts = []
+        for conflict_data in conflict_result.get("conflicts_detected", []):
+            conflict = Conflict(
+                topic=conflict_data.get("topic", ""),
+                conflict_type=conflict_data.get("type", "factual"),
+                positions=conflict_data.get("positions", []),
+                severity=conflict_data.get("severity", "medium"),
+                resolution=conflict_data.get("resolution", {}).get("resolved_statement")
+            )
+            conflicts.append(conflict)
+        
+        # Build flags
+        flags = []
+        for flag in verification_summary.get("flags", []):
+            flags.append({
+                "type": flag.get("type", "uncertainty"),
+                "message": flag.get("message", ""),
+                "severity": flag.get("severity", "medium")
+            })
+        
+        return VerificationResult(
+            overall_confidence=summary.get("overall_confidence", 0.7),
+            trust_level=summary.get("trust_level", "medium"),
+            verified_claims=claims,
+            conflicts=conflicts,
+            caveats=verification_summary.get("caveats", []),
+            flags=flags
+        )
+
+
+# Module instance
+verification_module = VerificationModule()

src/modules/web_search.py

@@ -0,0 +1,394 @@
+"""
+Web Search Module - Handles web search integration and content retrieval.
+"""
+
+import logging
+import json
+import httpx
+from typing import Optional, Dict, Any, List
+from abc import ABC, abstractmethod
+from urllib.parse import urlparse
+
+from ..models import Source, QueryAnalysis, ExtractedInfo
+from ..config import config
+from ..llm_client import llm_client
+from ..prompts.search_prompts import SEARCH_PROMPTS
+
+logger = logging.getLogger(__name__)
+
+
+class BaseSearchProvider(ABC):
+    """Base class for search providers."""
+    
+    @abstractmethod
+    async def search(self, query: str, max_results: int = 10) -> List[Dict[str, Any]]:
+        """Execute a search query."""
+        pass
+
+
+class TavilySearchProvider(BaseSearchProvider):
+    """Tavily search API provider."""
+    
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key or config.search.api_key
+        self.base_url = "https://api.tavily.com"
+    
+    async def search(self, query: str, max_results: int = 10) -> List[Dict[str, Any]]:
+        """Execute a search using Tavily API."""
+        if not self.api_key:
+            logger.warning("Tavily API key not configured")
+            return []
+        
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(
+                    f"{self.base_url}/search",
+                    json={
+                        "api_key": self.api_key,
+                        "query": query,
+                        "max_results": max_results,
+                        "include_answer": True,
+                        "include_raw_content": True,
+                    },
+                    timeout=config.search.timeout_seconds
+                )
+                response.raise_for_status()
+                data = response.json()
+                
+                results = []
+                for result in data.get("results", []):
+                    results.append({
+                        "url": result.get("url", ""),
+                        "title": result.get("title", ""),
+                        "snippet": result.get("content", ""),
+                        "content": result.get("raw_content", result.get("content", "")),
+                        "score": result.get("score", 0.5),
+                    })
+                
+                return results
+            except Exception as e:
+                logger.error(f"Tavily search failed: {e}")
+                return []
+
+
+class SerperSearchProvider(BaseSearchProvider):
+    """Serper (Google Search) API provider."""
+    
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key or config.search.fallback_api_key
+        self.base_url = "https://google.serper.dev"
+    
+    async def search(self, query: str, max_results: int = 10) -> List[Dict[str, Any]]:
+        """Execute a search using Serper API."""
+        if not self.api_key:
+            logger.warning("Serper API key not configured")
+            return []
+        
+        async with httpx.AsyncClient() as client:
+            try:
+                response = await client.post(
+                    f"{self.base_url}/search",
+                    headers={"X-API-KEY": self.api_key},
+                    json={"q": query, "num": max_results},
+                    timeout=config.search.timeout_seconds
+                )
+                response.raise_for_status()
+                data = response.json()
+                
+                results = []
+                for result in data.get("organic", []):
+                    results.append({
+                        "url": result.get("link", ""),
+                        "title": result.get("title", ""),
+                        "snippet": result.get("snippet", ""),
+                        "content": result.get("snippet", ""),  # Serper doesn't provide full content
+                        "score": 0.5,
+                    })
+                
+                return results
+            except Exception as e:
+                logger.error(f"Serper search failed: {e}")
+                return []
+
+
+class WebSearch:
+    """
+    Web Search module for searching and retrieving content from the web.
+    
+    Implements FR-2: Web Search Integration requirements.
+    """
+    
+    def __init__(self):
+        self.llm = llm_client
+        self.primary_provider = TavilySearchProvider()
+        self.fallback_provider = SerperSearchProvider()
+        self._use_fallback = False
+    
+    async def search(
+        self, 
+        query: str,
+        query_analysis: Optional[QueryAnalysis] = None,
+        max_results: int = 10
+    ) -> List[Source]:
+        """
+        Search the web for information related to the query.
+        
+        Args:
+            query: Search query string
+            query_analysis: Optional query analysis for context
+            max_results: Maximum number of results to return
+            
+        Returns:
+            List of Source objects with retrieved content
+        """
+        logger.info(f"Searching for: {query[:100]}...")
+        
+        # Generate optimized search queries
+        search_queries = await self._generate_search_queries(
+            query, query_analysis
+        )
+        
+        # Execute searches
+        all_results = []
+        for search_query in search_queries[:3]:  # Limit to top 3 queries
+            results = await self._execute_search(
+                search_query["query"],
+                max_results=max_results // len(search_queries[:3])
+            )
+            all_results.extend(results)
+        
+        # Remove duplicates by URL
+        seen_urls = set()
+        unique_results = []
+        for result in all_results:
+            if result["url"] not in seen_urls:
+                seen_urls.add(result["url"])
+                unique_results.append(result)
+        
+        # Evaluate relevance and convert to Source objects
+        sources = await self._process_results(query, unique_results[:max_results])
+        
+        logger.info(f"Found {len(sources)} relevant sources")
+        return sources
+    
+    async def search_sub_queries(
+        self,
+        sub_queries: List[str],
+        query_analysis: Optional[QueryAnalysis] = None,
+        max_results_per_query: int = 5
+    ) -> List[Source]:
+        """
+        Search for multiple sub-queries and combine results.
+        
+        Args:
+            sub_queries: List of sub-queries to search
+            query_analysis: Optional query analysis for context
+            max_results_per_query: Maximum results per sub-query
+            
+        Returns:
+            Combined list of Source objects
+        """
+        all_sources = []
+        seen_urls = set()
+        
+        for sub_query in sub_queries:
+            sources = await self.search(
+                sub_query,
+                query_analysis,
+                max_results=max_results_per_query
+            )
+            
+            for source in sources:
+                if source.url not in seen_urls:
+                    seen_urls.add(source.url)
+                    all_sources.append(source)
+        
+        return all_sources
+    
+    async def _generate_search_queries(
+        self,
+        query: str,
+        query_analysis: Optional[QueryAnalysis] = None
+    ) -> List[Dict[str, Any]]:
+        """Generate optimized search queries."""
+        entities = []
+        domain = "general"
+        
+        if query_analysis:
+            entities = [e.text for e in query_analysis.entities]
+            domain = query_analysis.domain
+        
+        prompt = SEARCH_PROMPTS["query_generation"].format(
+            sub_query=query,
+            original_query=query,
+            domain=domain,
+            entities=json.dumps(entities)
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            return result.get("queries", [{"query": query, "priority": 1}])
+        except Exception as e:
+            logger.error(f"Search query generation failed: {e}")
+            return [{"query": query, "priority": 1}]
+    
+    async def _execute_search(
+        self, 
+        query: str, 
+        max_results: int = 10
+    ) -> List[Dict[str, Any]]:
+        """Execute search using available provider."""
+        provider = self.fallback_provider if self._use_fallback else self.primary_provider
+        
+        try:
+            results = await provider.search(query, max_results)
+            if not results and not self._use_fallback:
+                # Try fallback
+                logger.warning("Primary search returned no results, trying fallback")
+                self._use_fallback = True
+                results = await self.fallback_provider.search(query, max_results)
+            return results
+        except Exception as e:
+            if not self._use_fallback:
+                logger.warning(f"Primary search failed, trying fallback: {e}")
+                self._use_fallback = True
+                return await self._execute_search(query, max_results)
+            logger.error(f"All search providers failed: {e}")
+            return []
+    
+    async def _process_results(
+        self,
+        query: str,
+        results: List[Dict[str, Any]]
+    ) -> List[Source]:
+        """Process and evaluate search results."""
+        if not results:
+            return []
+        
+        # Evaluate relevance
+        results_json = json.dumps([
+            {"url": r["url"], "title": r["title"], "snippet": r.get("snippet", "")}
+            for r in results
+        ], indent=2)
+        
+        prompt = SEARCH_PROMPTS["relevance_evaluation"].format(
+            query=query,
+            search_results=results_json
+        )
+        
+        try:
+            evaluation = await self.llm.generate_json(prompt)
+            evaluated = {r["url"]: r for r in evaluation.get("evaluated_results", [])}
+        except Exception as e:
+            logger.error(f"Relevance evaluation failed: {e}")
+            evaluated = {}
+        
+        # Convert to Source objects
+        sources = []
+        for result in results:
+            url = result["url"]
+            eval_data = evaluated.get(url, {})
+            
+            # Parse domain from URL
+            try:
+                domain = urlparse(url).netloc
+            except:
+                domain = ""
+            
+            # Determine credibility based on domain
+            credibility_score = self._estimate_credibility(domain, eval_data)
+            
+            source = Source(
+                url=url,
+                title=result.get("title", ""),
+                content=result.get("content", result.get("snippet", "")),
+                snippet=result.get("snippet", ""),
+                domain=domain,
+                credibility_score=credibility_score,
+                credibility_level=self._score_to_level(credibility_score),
+                metadata={
+                    "relevance_score": eval_data.get("relevance_score", 5),
+                    "information_value": eval_data.get("information_value", "medium"),
+                    "freshness": eval_data.get("freshness", "unknown"),
+                }
+            )
+            sources.append(source)
+        
+        # Sort by relevance
+        sources.sort(
+            key=lambda s: s.metadata.get("relevance_score", 0),
+            reverse=True
+        )
+        
+        return sources
+    
+    async def extract_content(self, source: Source, query: str) -> List[ExtractedInfo]:
+        """Extract relevant information from a source."""
+        if not source.content:
+            return []
+        
+        prompt = SEARCH_PROMPTS["content_extraction"].format(
+            query=query,
+            url=source.url,
+            title=source.title,
+            content=source.content[:10000]  # Limit content length
+        )
+        
+        try:
+            result = await self.llm.generate_json(prompt)
+            
+            extracted = []
+            for info in result.get("extracted_information", []):
+                extracted.append(ExtractedInfo(
+                    source_id=source.id,
+                    content=info.get("content", ""),
+                    info_type=info.get("type", "fact"),
+                    relevance=info.get("relevance", "medium"),
+                    location=info.get("location", "")
+                ))
+            
+            # Update source metadata
+            source_info = result.get("source", {})
+            if source_info.get("author"):
+                source.author = source_info["author"]
+            if source_info.get("publication_date"):
+                source.publication_date = source_info["publication_date"]
+            
+            return extracted
+        except Exception as e:
+            logger.error(f"Content extraction failed: {e}")
+            return []
+    
+    def _estimate_credibility(
+        self, 
+        domain: str, 
+        eval_data: Dict[str, Any]
+    ) -> float:
+        """Estimate source credibility based on domain and evaluation."""
+        # Base score from evaluation
+        quality = eval_data.get("source_quality", "medium")
+        quality_scores = {"high": 0.8, "medium": 0.5, "low": 0.3, "unknown": 0.4}
+        base_score = quality_scores.get(quality, 0.5)
+        
+        # Adjust based on domain
+        if any(ext in domain for ext in [".gov", ".edu"]):
+            base_score = min(1.0, base_score + 0.2)
+        elif any(ext in domain for ext in [".org"]):
+            base_score = min(1.0, base_score + 0.1)
+        elif any(term in domain for term in ["wikipedia", "reuters", "bbc", "nytimes"]):
+            base_score = min(1.0, base_score + 0.15)
+        
+        return base_score
+    
+    def _score_to_level(self, score: float) -> str:
+        """Convert numeric score to credibility level."""
+        if score >= 0.8:
+            return "high"
+        elif score >= 0.5:
+            return "medium"
+        else:
+            return "low"
+
+
+# Module instance
+web_search = WebSearch()

src/orchestrator.py

@@ -0,0 +1,572 @@
+"""
+Research Orchestrator for the Deep Research AI system.
+
+This module coordinates all research components to provide a unified
+research pipeline from query to final output.
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+from enum import Enum
+
+from .config import Config
+from .models import (
+    QueryAnalysis,
+    SearchResult,
+    Source,
+    ReasoningStep,
+    ResearchResult,
+    OutputFormat,
+    CitationStyle,
+)
+from .modules.query_understanding import QueryUnderstanding
+from .modules.web_search import WebSearch
+from .modules.reasoning_engine import ReasoningEngine
+from .modules.verification import Verification
+from .modules.citation import CitationManager
+from .modules.output_generation import OutputGenerator, SummaryLength, AudienceType
+from .modules.error_handling import (
+    ErrorHandler,
+    ErrorContext,
+    ErrorSeverity,
+    ComponentType,
+    ResearchError,
+)
+
+
+# Set up logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class ResearchStage(Enum):
+    """Stages of the research pipeline."""
+    QUERY_ANALYSIS = "query_analysis"
+    WEB_SEARCH = "web_search"
+    REASONING = "reasoning"
+    VERIFICATION = "verification"
+    CITATION = "citation"
+    OUTPUT_GENERATION = "output_generation"
+    COMPLETE = "complete"
+
+
+@dataclass
+class ResearchProgress:
+    """Tracks research progress."""
+    current_stage: ResearchStage
+    stages_completed: list[ResearchStage] = field(default_factory=list)
+    start_time: datetime = field(default_factory=datetime.now)
+    stage_times: dict[str, float] = field(default_factory=dict)
+    errors: list[str] = field(default_factory=list)
+    
+    def complete_stage(self, stage: ResearchStage, duration: float) -> None:
+        """Mark a stage as complete."""
+        self.stages_completed.append(stage)
+        self.stage_times[stage.value] = duration
+    
+    @property
+    def progress_percentage(self) -> float:
+        """Get completion percentage."""
+        total_stages = len(ResearchStage) - 1  # Exclude COMPLETE
+        return (len(self.stages_completed) / total_stages) * 100
+
+
+@dataclass
+class ResearchSession:
+    """A research session with all intermediate results."""
+    session_id: str
+    query: str
+    progress: ResearchProgress
+    query_analysis: QueryAnalysis | None = None
+    search_results: list[SearchResult] = field(default_factory=list)
+    sources: list[Source] = field(default_factory=list)
+    reasoning_steps: list[ReasoningStep] = field(default_factory=list)
+    synthesis: dict | None = None
+    verification: dict | None = None
+    citations: dict | None = None
+    final_result: ResearchResult | None = None
+    metadata: dict = field(default_factory=dict)
+
+
+class ResearchOrchestrator:
+    """
+    Orchestrates the complete research pipeline.
+    
+    Coordinates all modules to perform comprehensive research:
+    1. Query Understanding - Analyze and decompose the query
+    2. Web Search - Search and extract relevant content
+    3. Reasoning - Synthesize and analyze findings
+    4. Verification - Verify claims and assess credibility
+    5. Citation - Generate proper citations
+    6. Output Generation - Create formatted output
+    """
+    
+    def __init__(self, config: Config | None = None) -> None:
+        """
+        Initialize the ResearchOrchestrator.
+        
+        Args:
+            config: Configuration object. Uses default if not provided.
+        """
+        self.config = config or Config()
+        
+        # Initialize all modules
+        self.query_understanding = QueryUnderstanding(self.config)
+        self.web_search = WebSearch(self.config)
+        self.reasoning_engine = ReasoningEngine(self.config)
+        self.verification = Verification(self.config)
+        self.citation_manager = CitationManager(self.config)
+        self.output_generator = OutputGenerator(self.config)
+        self.error_handler = ErrorHandler(self.config)
+        
+        # Session tracking
+        self.active_sessions: dict[str, ResearchSession] = {}
+        self._session_counter = 0
+    
+    async def research(
+        self,
+        query: str,
+        audience: AudienceType = AudienceType.GENERAL,
+        citation_style: CitationStyle = CitationStyle.APA,
+        output_format: OutputFormat = OutputFormat.MARKDOWN,
+        max_sources: int = 10,
+        verify_claims: bool = True,
+        progress_callback: callable | None = None
+    ) -> ResearchResult:
+        """
+        Perform comprehensive research on a query.
+        
+        Args:
+            query: The research query
+            audience: Target audience type
+            citation_style: Citation style to use
+            output_format: Desired output format
+            max_sources: Maximum sources to use
+            verify_claims: Whether to verify claims
+            progress_callback: Optional callback for progress updates
+            
+        Returns:
+            Complete ResearchResult with findings
+        """
+        # Create session
+        session = self._create_session(query)
+        
+        try:
+            # Stage 1: Query Analysis
+            await self._run_stage(
+                session,
+                ResearchStage.QUERY_ANALYSIS,
+                self._analyze_query,
+                query,
+                progress_callback
+            )
+            
+            # Stage 2: Web Search
+            await self._run_stage(
+                session,
+                ResearchStage.WEB_SEARCH,
+                self._search_web,
+                session,
+                max_sources,
+                progress_callback
+            )
+            
+            # Stage 3: Reasoning
+            await self._run_stage(
+                session,
+                ResearchStage.REASONING,
+                self._reason,
+                session,
+                progress_callback
+            )
+            
+            # Stage 4: Verification (optional)
+            if verify_claims:
+                await self._run_stage(
+                    session,
+                    ResearchStage.VERIFICATION,
+                    self._verify,
+                    session,
+                    progress_callback
+                )
+            
+            # Stage 5: Citation
+            await self._run_stage(
+                session,
+                ResearchStage.CITATION,
+                self._generate_citations,
+                session,
+                citation_style,
+                progress_callback
+            )
+            
+            # Stage 6: Output Generation
+            await self._run_stage(
+                session,
+                ResearchStage.OUTPUT_GENERATION,
+                self._generate_output,
+                session,
+                audience,
+                progress_callback
+            )
+            
+            # Mark complete
+            session.progress.current_stage = ResearchStage.COMPLETE
+            if progress_callback:
+                progress_callback(ResearchStage.COMPLETE, 100.0)
+            
+            return session.final_result
+            
+        except Exception as e:
+            logger.error(f"Research failed: {e}")
+            
+            # Try to generate partial results
+            partial_result = await self._handle_research_failure(session, e)
+            return partial_result
+        
+        finally:
+            # Clean up session
+            self._cleanup_session(session.session_id)
+    
+    async def _run_stage(
+        self,
+        session: ResearchSession,
+        stage: ResearchStage,
+        stage_func: callable,
+        *args,
+        **kwargs
+    ) -> None:
+        """Run a research stage with error handling."""
+        progress_callback = kwargs.pop('progress_callback', None)
+        
+        session.progress.current_stage = stage
+        start_time = datetime.now()
+        
+        if progress_callback:
+            progress_callback(stage, session.progress.progress_percentage)
+        
+        logger.info(f"Starting stage: {stage.value}")
+        
+        try:
+            await stage_func(*args)
+            duration = (datetime.now() - start_time).total_seconds()
+            session.progress.complete_stage(stage, duration)
+            logger.info(f"Completed stage: {stage.value} in {duration:.2f}s")
+            
+        except Exception as e:
+            duration = (datetime.now() - start_time).total_seconds()
+            session.progress.errors.append(f"{stage.value}: {str(e)}")
+            logger.error(f"Stage {stage.value} failed: {e}")
+            raise
+    
+    async def _analyze_query(self, query: str) -> QueryAnalysis:
+        """Analyze the research query."""
+        session = self._get_current_session(query)
+        
+        analysis = await self.query_understanding.analyze(query)
+        session.query_analysis = analysis
+        
+        return analysis
+    
+    async def _search_web(
+        self,
+        session: ResearchSession,
+        max_sources: int
+    ) -> list[Source]:
+        """Search the web for relevant information."""
+        if not session.query_analysis:
+            raise ResearchError("Query analysis not available")
+        
+        # Generate search queries from sub-queries
+        all_results = []
+        
+        for sub_query in session.query_analysis.sub_queries:
+            results = await self.web_search.search(
+                sub_query.query,
+                max_results=max_sources // len(session.query_analysis.sub_queries) + 1
+            )
+            all_results.extend(results)
+        
+        # Also search main query
+        main_results = await self.web_search.search(
+            session.query,
+            max_results=max_sources
+        )
+        all_results.extend(main_results)
+        
+        # Deduplicate by URL
+        seen_urls = set()
+        unique_results = []
+        for result in all_results:
+            if result.url not in seen_urls:
+                seen_urls.add(result.url)
+                unique_results.append(result)
+        
+        session.search_results = unique_results[:max_sources]
+        
+        # Convert to Sources with extracted content
+        sources = []
+        for result in session.search_results:
+            content = await self.web_search.extract_content(result.url)
+            source = Source(
+                source_id=result.url[:32],
+                url=result.url,
+                title=result.title,
+                content=content.get("main_content", result.snippet),
+                domain=result.domain,
+                credibility_score=0.7  # Default, will be updated
+            )
+            sources.append(source)
+        
+        session.sources = sources
+        return sources
+    
+    async def _reason(self, session: ResearchSession) -> dict:
+        """Perform reasoning on gathered information."""
+        if not session.sources:
+            raise ResearchError("No sources available for reasoning")
+        
+        # Prepare information for reasoning
+        information = [
+            {
+                "source": source.title,
+                "url": source.url,
+                "content": source.content[:2000] if source.content else ""
+            }
+            for source in session.sources
+        ]
+        
+        # Use chain of thought reasoning
+        reasoning_result = await self.reasoning_engine.chain_of_thought(
+            session.query,
+            str(information)
+        )
+        
+        session.reasoning_steps = reasoning_result.get("reasoning_chain", [])
+        
+        # Synthesize information
+        synthesis_result = await self.reasoning_engine.synthesize_information(
+            session.query,
+            information
+        )
+        
+        session.synthesis = synthesis_result
+        
+        return synthesis_result
+    
+    async def _verify(self, session: ResearchSession) -> dict:
+        """Verify claims and assess source credibility."""
+        if not session.synthesis:
+            raise ResearchError("Synthesis not available for verification")
+        
+        # Extract claims from synthesis
+        claims = session.synthesis.get("key_findings", [])
+        
+        # Verify claims
+        verification_result = await self.verification.verify(
+            claims,
+            session.sources
+        )
+        
+        # Assess source credibility
+        for source in session.sources:
+            credibility = await self.verification.assess_credibility(source)
+            source.credibility_score = credibility.get("overall_score", 0.7)
+        
+        session.verification = verification_result
+        
+        return verification_result
+    
+    async def _generate_citations(
+        self,
+        session: ResearchSession,
+        style: CitationStyle
+    ) -> dict:
+        """Generate citations for sources."""
+        if not session.sources:
+            raise ResearchError("No sources available for citation")
+        
+        synthesis_text = session.synthesis.get("synthesis", "") if session.synthesis else ""
+        
+        citations = await self.citation_manager.generate_citations(
+            session.sources,
+            synthesis_text
+        )
+        
+        session.citations = citations
+        
+        return citations
+    
+    async def _generate_output(
+        self,
+        session: ResearchSession,
+        audience: AudienceType
+    ) -> ResearchResult:
+        """Generate the final research output."""
+        # Calculate confidence
+        confidence = self._calculate_confidence(session)
+        
+        # Prepare findings
+        findings = {
+            "synthesis": session.synthesis,
+            "verification": session.verification,
+            "reasoning_steps": session.reasoning_steps,
+            "information_gaps": session.synthesis.get("gaps", []) if session.synthesis else []
+        }
+        
+        # Generate report
+        report = await self.output_generator.generate_report(
+            session.query,
+            findings,
+            session.sources,
+            confidence
+        )
+        
+        # Generate summary
+        summary = await self.output_generator.generate_summary(
+            findings,
+            SummaryLength.STANDARD
+        )
+        
+        # Build final result
+        result = ResearchResult(
+            query=session.query,
+            answer=summary.get("summary", {}).get("text", ""),
+            confidence=confidence,
+            sources=session.sources,
+            reasoning_steps=session.reasoning_steps,
+            verification_status="verified" if session.verification else "unverified",
+            metadata={
+                "report": report,
+                "citations": session.citations,
+                "audience": audience.value,
+                "session_id": session.session_id,
+                "duration": session.progress.stage_times
+            }
+        )
+        
+        session.final_result = result
+        
+        return result
+    
+    def _calculate_confidence(self, session: ResearchSession) -> float:
+        """Calculate overall confidence score."""
+        factors = []
+        
+        # Source quality
+        if session.sources:
+            avg_credibility = sum(s.credibility_score for s in session.sources) / len(session.sources)
+            factors.append(avg_credibility)
+        
+        # Verification status
+        if session.verification:
+            verification_score = session.verification.get("overall_confidence", 0.5)
+            factors.append(verification_score)
+        
+        # Source count
+        source_score = min(len(session.sources) / 10, 1.0)
+        factors.append(source_score)
+        
+        # Error count
+        error_penalty = len(session.progress.errors) * 0.1
+        
+        if factors:
+            base_confidence = sum(factors) / len(factors)
+            return max(0.0, min(1.0, base_confidence - error_penalty))
+        
+        return 0.5
+    
+    async def _handle_research_failure(
+        self,
+        session: ResearchSession,
+        error: Exception
+    ) -> ResearchResult:
+        """Handle research failure and generate partial results."""
+        logger.warning(f"Generating partial results due to: {error}")
+        
+        # Try to generate fallback content
+        fallback = await self.error_handler.generate_fallback_content(
+            session.query,
+            session.synthesis,
+            [str(error)],
+            None
+        )
+        
+        # Build partial result
+        return ResearchResult(
+            query=session.query,
+            answer=fallback.get("fallback_content", {}).get("response", "Research could not be completed."),
+            confidence=0.2,
+            sources=session.sources,
+            reasoning_steps=session.reasoning_steps,
+            verification_status="failed",
+            metadata={
+                "error": str(error),
+                "partial": True,
+                "fallback": fallback
+            }
+        )
+    
+    def _create_session(self, query: str) -> ResearchSession:
+        """Create a new research session."""
+        self._session_counter += 1
+        session_id = f"session_{self._session_counter}_{datetime.now().strftime('%Y%m%d%H%M%S')}"
+        
+        session = ResearchSession(
+            session_id=session_id,
+            query=query,
+            progress=ResearchProgress(current_stage=ResearchStage.QUERY_ANALYSIS)
+        )
+        
+        self.active_sessions[session_id] = session
+        return session
+    
+    def _get_current_session(self, query: str) -> ResearchSession:
+        """Get the current session for a query."""
+        for session in self.active_sessions.values():
+            if session.query == query:
+                return session
+        raise ResearchError(f"No session found for query: {query}")
+    
+    def _cleanup_session(self, session_id: str) -> None:
+        """Clean up a research session."""
+        if session_id in self.active_sessions:
+            del self.active_sessions[session_id]
+    
+    async def get_session_status(self, session_id: str) -> dict:
+        """Get the status of a research session."""
+        if session_id not in self.active_sessions:
+            return {"error": "Session not found"}
+        
+        session = self.active_sessions[session_id]
+        return {
+            "session_id": session_id,
+            "query": session.query,
+            "current_stage": session.progress.current_stage.value,
+            "progress": session.progress.progress_percentage,
+            "stages_completed": [s.value for s in session.progress.stages_completed],
+            "errors": session.progress.errors,
+            "has_result": session.final_result is not None
+        }
+
+
+# Convenience function for quick research
+async def research(query: str, **kwargs) -> ResearchResult:
+    """
+    Perform research on a query.
+    
+    This is a convenience function that creates an orchestrator
+    and performs research.
+    
+    Args:
+        query: The research query
+        **kwargs: Additional arguments for research()
+        
+    Returns:
+        ResearchResult with findings
+    """
+    orchestrator = ResearchOrchestrator()
+    return await orchestrator.research(query, **kwargs)

src/prompts/__init__.py

@@ -0,0 +1,147 @@
+"""
+Prompt templates for Deep Research AI.
+
+This package contains all prompt templates used by the research modules.
+"""
+
+# System prompts
+from .system_prompts import (
+    RESEARCH_SYSTEM_PROMPT,
+    QUERY_ANALYSIS_SYSTEM_PROMPT,
+    REASONING_SYSTEM_PROMPT,
+    VERIFICATION_SYSTEM_PROMPT,
+    OUTPUT_SYSTEM_PROMPT,
+)
+
+# Query understanding prompts
+from .query_prompts import (
+    QUERY_ANALYSIS_PROMPT,
+    QUERY_DECOMPOSITION_PROMPT,
+    ENTITY_EXTRACTION_PROMPT,
+    QUERY_CLARIFICATION_PROMPT,
+    QUERY_VALIDATION_PROMPT,
+)
+
+# Search prompts
+from .search_prompts import (
+    SEARCH_QUERY_GENERATION_PROMPT,
+    RESULT_RELEVANCE_PROMPT,
+    CONTENT_EXTRACTION_PROMPT,
+    SOURCE_EVALUATION_PROMPT,
+)
+
+# Reasoning prompts
+from .reasoning_prompts import (
+    CHAIN_OF_THOUGHT_PROMPT,
+    INFORMATION_SYNTHESIS_PROMPT,
+    COMPARISON_ANALYSIS_PROMPT,
+    EVIDENCE_EVALUATION_PROMPT,
+    CONCLUSION_GENERATION_PROMPT,
+)
+
+# Verification prompts
+from .verification_prompts import (
+    CROSS_REFERENCE_PROMPT,
+    SOURCE_CREDIBILITY_PROMPT,
+    CONFLICT_DETECTION_PROMPT,
+    FACT_CHECK_PROMPT,
+    BIAS_DETECTION_PROMPT,
+)
+
+# Citation prompts
+from .citation_prompts import (
+    CITATION_GENERATION_PROMPT,
+    SOURCE_ATTRIBUTION_PROMPT,
+    REFERENCE_LIST_PROMPT,
+    INLINE_CITATION_PROMPT,
+    CITATION_VALIDATION_PROMPT,
+    SOURCE_METADATA_PROMPT,
+    FOOTNOTE_GENERATION_PROMPT,
+)
+
+# Output generation prompts
+from .output_prompts import (
+    REPORT_GENERATION_PROMPT,
+    SUMMARY_GENERATION_PROMPT,
+    ANSWER_FORMATTING_PROMPT,
+    VISUALIZATION_SUGGESTION_PROMPT,
+    MULTI_FORMAT_OUTPUT_PROMPT,
+    RESPONSE_QUALITY_PROMPT,
+    FOLLOWUP_QUESTIONS_PROMPT,
+    EXPORT_FORMAT_PROMPT,
+)
+
+# Error handling prompts
+from .error_prompts import (
+    ERROR_ANALYSIS_PROMPT,
+    GRACEFUL_DEGRADATION_PROMPT,
+    USER_ERROR_MESSAGE_PROMPT,
+    RETRY_STRATEGY_PROMPT,
+    ERROR_RECOVERY_PROMPT,
+    FALLBACK_CONTENT_PROMPT,
+    SYSTEM_HEALTH_PROMPT,
+)
+
+__all__ = [
+    # System prompts
+    "RESEARCH_SYSTEM_PROMPT",
+    "QUERY_ANALYSIS_SYSTEM_PROMPT",
+    "REASONING_SYSTEM_PROMPT",
+    "VERIFICATION_SYSTEM_PROMPT",
+    "OUTPUT_SYSTEM_PROMPT",
+    
+    # Query prompts
+    "QUERY_ANALYSIS_PROMPT",
+    "QUERY_DECOMPOSITION_PROMPT",
+    "ENTITY_EXTRACTION_PROMPT",
+    "QUERY_CLARIFICATION_PROMPT",
+    "QUERY_VALIDATION_PROMPT",
+    
+    # Search prompts
+    "SEARCH_QUERY_GENERATION_PROMPT",
+    "RESULT_RELEVANCE_PROMPT",
+    "CONTENT_EXTRACTION_PROMPT",
+    "SOURCE_EVALUATION_PROMPT",
+    
+    # Reasoning prompts
+    "CHAIN_OF_THOUGHT_PROMPT",
+    "INFORMATION_SYNTHESIS_PROMPT",
+    "COMPARISON_ANALYSIS_PROMPT",
+    "EVIDENCE_EVALUATION_PROMPT",
+    "CONCLUSION_GENERATION_PROMPT",
+    
+    # Verification prompts
+    "CROSS_REFERENCE_PROMPT",
+    "SOURCE_CREDIBILITY_PROMPT",
+    "CONFLICT_DETECTION_PROMPT",
+    "FACT_CHECK_PROMPT",
+    "BIAS_DETECTION_PROMPT",
+    
+    # Citation prompts
+    "CITATION_GENERATION_PROMPT",
+    "SOURCE_ATTRIBUTION_PROMPT",
+    "REFERENCE_LIST_PROMPT",
+    "INLINE_CITATION_PROMPT",
+    "CITATION_VALIDATION_PROMPT",
+    "SOURCE_METADATA_PROMPT",
+    "FOOTNOTE_GENERATION_PROMPT",
+    
+    # Output prompts
+    "REPORT_GENERATION_PROMPT",
+    "SUMMARY_GENERATION_PROMPT",
+    "ANSWER_FORMATTING_PROMPT",
+    "VISUALIZATION_SUGGESTION_PROMPT",
+    "MULTI_FORMAT_OUTPUT_PROMPT",
+    "RESPONSE_QUALITY_PROMPT",
+    "FOLLOWUP_QUESTIONS_PROMPT",
+    "EXPORT_FORMAT_PROMPT",
+    
+    # Error prompts
+    "ERROR_ANALYSIS_PROMPT",
+    "GRACEFUL_DEGRADATION_PROMPT",
+    "USER_ERROR_MESSAGE_PROMPT",
+    "RETRY_STRATEGY_PROMPT",
+    "ERROR_RECOVERY_PROMPT",
+    "FALLBACK_CONTENT_PROMPT",
+    "SYSTEM_HEALTH_PROMPT",
+]

src/prompts/citation_prompts.py

@@ -0,0 +1,379 @@
+"""
+Citation prompts for the Deep Research AI system.
+
+These prompts handle citation generation, formatting, and source attribution
+to ensure proper academic-style references and source tracking.
+"""
+
+# Citation Generation Prompt
+CITATION_GENERATION_PROMPT = """You are an expert citation and source attribution specialist.
+
+Your task is to generate proper citations for the sources used in research.
+
+SOURCES TO CITE:
+{sources}
+
+CONTENT USING THESE SOURCES:
+{content}
+
+Generate citations for each source following these guidelines:
+
+1. **Citation Style**: Generate citations in multiple formats:
+   - APA (7th edition)
+   - MLA (9th edition)
+   - Chicago (17th edition)
+   - IEEE
+   - Harvard
+
+2. **Source Metadata**: Extract and include:
+   - Author(s) or organization
+   - Publication date
+   - Title
+   - Publisher/Website name
+   - URL
+   - Access date
+
+3. **In-text Citations**: Generate appropriate in-text citation markers
+
+4. **Citation Quality**:
+   - Handle missing metadata gracefully
+   - Indicate when information is inferred
+   - Flag incomplete citations
+
+Respond in JSON format:
+{{
+    "citations": [
+        {{
+            "source_id": "unique_id",
+            "source_url": "original_url",
+            "metadata": {{
+                "authors": ["author names or null"],
+                "title": "title",
+                "publication_date": "date or null",
+                "publisher": "publisher name",
+                "access_date": "YYYY-MM-DD"
+            }},
+            "formats": {{
+                "apa": "APA formatted citation",
+                "mla": "MLA formatted citation",
+                "chicago": "Chicago formatted citation",
+                "ieee": "IEEE formatted citation",
+                "harvard": "Harvard formatted citation"
+            }},
+            "in_text": {{
+                "apa": "(Author, Year)",
+                "mla": "(Author Page)",
+                "numeric": "[1]"
+            }},
+            "completeness_score": 0.0-1.0,
+            "missing_fields": ["list of missing metadata"]
+        }}
+    ],
+    "bibliography": {{
+        "apa": "Full APA bibliography",
+        "mla": "Full MLA works cited",
+        "chicago": "Full Chicago bibliography"
+    }}
+}}
+"""
+
+# Source Attribution Prompt
+SOURCE_ATTRIBUTION_PROMPT = """You are an expert in source attribution and provenance tracking.
+
+Your task is to map claims in the research content to their original sources.
+
+RESEARCH CONTENT:
+{content}
+
+AVAILABLE SOURCES:
+{sources}
+
+For each significant claim or piece of information, attribute it to its source:
+
+1. **Claim Identification**: Identify each factual claim or data point
+2. **Source Mapping**: Map each claim to one or more sources
+3. **Attribution Confidence**: Rate confidence in the attribution
+4. **Quote vs Paraphrase**: Distinguish between direct quotes and paraphrased content
+
+Respond in JSON format:
+{{
+    "attributions": [
+        {{
+            "claim": "The factual claim or information",
+            "claim_type": "statistic|fact|quote|analysis|opinion",
+            "sources": [
+                {{
+                    "source_id": "source_identifier",
+                    "source_url": "url",
+                    "relevance": "direct|supporting|background",
+                    "is_quote": true/false,
+                    "original_text": "text from source if quote",
+                    "confidence": 0.0-1.0
+                }}
+            ],
+            "location_in_content": "paragraph/section reference",
+            "needs_citation": true/false
+        }}
+    ],
+    "unattributed_claims": [
+        {{
+            "claim": "claim without clear source",
+            "reason": "why it couldn't be attributed",
+            "suggestion": "suggested action"
+        }}
+    ],
+    "attribution_coverage": 0.0-1.0
+}}
+"""
+
+# Reference List Generation Prompt
+REFERENCE_LIST_PROMPT = """You are an expert in academic reference list generation.
+
+Your task is to create a properly formatted reference list from the sources used.
+
+SOURCES:
+{sources}
+
+CITATION STYLE: {citation_style}
+
+Generate a complete reference list following these guidelines:
+
+1. **Ordering**: 
+   - Alphabetical by author surname (APA, MLA, Chicago, Harvard)
+   - Numerical by order of appearance (IEEE)
+
+2. **Formatting**:
+   - Proper indentation (hanging indent where applicable)
+   - Correct punctuation and italicization
+   - Consistent date formatting
+
+3. **Web Sources**:
+   - Include retrieval dates for online sources
+   - Format URLs appropriately
+   - Handle DOIs when available
+
+4. **Special Cases**:
+   - Multiple authors (et al. rules)
+   - No author (organization or title)
+   - No date (n.d.)
+
+Respond in JSON format:
+{{
+    "reference_list": [
+        {{
+            "number": 1,
+            "formatted_reference": "complete formatted reference",
+            "source_id": "source_identifier"
+        }}
+    ],
+    "formatted_output": "Complete formatted reference list as text",
+    "style": "{citation_style}",
+    "total_references": 0
+}}
+"""
+
+# Inline Citation Insertion Prompt
+INLINE_CITATION_PROMPT = """You are an expert in inline citation insertion.
+
+Your task is to insert proper inline citations into the research content.
+
+CONTENT TO ANNOTATE:
+{content}
+
+SOURCE ATTRIBUTIONS:
+{attributions}
+
+CITATION STYLE: {citation_style}
+
+Insert inline citations following these rules:
+
+1. **Placement**:
+   - Place citations immediately after the claim
+   - Before punctuation for mid-sentence citations
+   - After punctuation for end-of-sentence citations
+
+2. **Format**:
+   - Use appropriate format for the citation style
+   - Handle multiple sources for same claim
+   - Use "ibid" or "op. cit." where appropriate
+
+3. **Readability**:
+   - Don't over-cite (one citation per claim usually sufficient)
+   - Group related citations
+   - Maintain text flow
+
+Respond in JSON format:
+{{
+    "annotated_content": "Full content with inline citations inserted",
+    "citation_count": 0,
+    "citation_positions": [
+        {{
+            "position": "character position",
+            "citation": "citation text",
+            "source_ids": ["source_id1", "source_id2"]
+        }}
+    ],
+    "style_used": "{citation_style}"
+}}
+"""
+
+# Citation Validation Prompt
+CITATION_VALIDATION_PROMPT = """You are an expert citation validator and quality checker.
+
+Your task is to validate the citations and ensure they meet academic standards.
+
+CITATIONS TO VALIDATE:
+{citations}
+
+SOURCES:
+{sources}
+
+Validate each citation for:
+
+1. **Accuracy**:
+   - Correct author names and order
+   - Accurate publication dates
+   - Correct titles (no typos)
+   - Valid URLs (format check)
+
+2. **Completeness**:
+   - All required fields present
+   - Appropriate handling of missing information
+
+3. **Formatting**:
+   - Correct punctuation
+   - Proper capitalization
+   - Correct italicization indicators
+   - Proper ordering
+
+4. **Consistency**:
+   - Same style throughout
+   - Consistent abbreviations
+   - Uniform date formats
+
+Respond in JSON format:
+{{
+    "validation_results": [
+        {{
+            "source_id": "source_identifier",
+            "is_valid": true/false,
+            "issues": [
+                {{
+                    "type": "accuracy|completeness|formatting|consistency",
+                    "field": "affected field",
+                    "issue": "description of issue",
+                    "suggestion": "how to fix"
+                }}
+            ],
+            "corrected_citation": "corrected version if needed"
+        }}
+    ],
+    "overall_quality": 0.0-1.0,
+    "total_issues": 0,
+    "recommendations": ["list of general recommendations"]
+}}
+"""
+
+# Source Metadata Extraction Prompt
+SOURCE_METADATA_PROMPT = """You are an expert in extracting metadata from web sources.
+
+Your task is to extract citation-relevant metadata from source content.
+
+SOURCE URL: {url}
+
+SOURCE CONTENT:
+{content}
+
+Extract the following metadata:
+
+1. **Authors**: 
+   - Individual authors with full names
+   - Corporate/organizational authors
+   - Author affiliations if available
+
+2. **Publication Info**:
+   - Publication date (exact or approximate)
+   - Last modified date
+   - Publisher/organization
+   - Publication type (article, report, webpage, etc.)
+
+3. **Document Info**:
+   - Full title
+   - Subtitle if any
+   - Section/chapter if applicable
+   - DOI if available
+
+4. **Web-specific**:
+   - Canonical URL
+   - Site name vs publisher name
+   - Archive/version information
+
+Respond in JSON format:
+{{
+    "metadata": {{
+        "authors": [
+            {{
+                "name": "full name",
+                "type": "individual|organization",
+                "affiliation": "affiliation or null"
+            }}
+        ],
+        "title": "document title",
+        "subtitle": "subtitle or null",
+        "publication_date": "YYYY-MM-DD or null",
+        "last_modified": "YYYY-MM-DD or null",
+        "publisher": "publisher name",
+        "site_name": "website name",
+        "publication_type": "article|report|webpage|blog|news|academic",
+        "doi": "DOI or null",
+        "url": "canonical URL",
+        "language": "language code"
+    }},
+    "extraction_confidence": {{
+        "authors": 0.0-1.0,
+        "date": 0.0-1.0,
+        "title": 0.0-1.0,
+        "overall": 0.0-1.0
+    }},
+    "inferred_fields": ["list of fields that were inferred"],
+    "missing_fields": ["list of fields that couldn't be found"]
+}}
+"""
+
+# Footnote Generation Prompt
+FOOTNOTE_GENERATION_PROMPT = """You are an expert in generating footnotes and endnotes.
+
+Your task is to generate appropriate footnotes for the research content.
+
+CONTENT:
+{content}
+
+SOURCES:
+{sources}
+
+ATTRIBUTIONS:
+{attributions}
+
+Generate footnotes following these guidelines:
+
+1. **First Reference**: Full citation on first mention
+2. **Subsequent References**: Shortened form (author, short title, page)
+3. **Ibid Usage**: Use "Ibid." for immediately repeated sources
+4. **Explanatory Notes**: Add brief explanatory notes where helpful
+
+Respond in JSON format:
+{{
+    "footnotes": [
+        {{
+            "number": 1,
+            "marker_position": "position in text",
+            "footnote_text": "complete footnote text",
+            "source_id": "source_identifier",
+            "is_first_reference": true/false,
+            "footnote_type": "citation|explanatory|both"
+        }}
+    ],
+    "content_with_markers": "content with footnote markers [1], [2], etc.",
+    "footnote_section": "formatted footnotes section"
+}}
+"""

src/prompts/error_prompts.py

@@ -0,0 +1,310 @@
+"""
+Error handling prompts for the Deep Research AI system.
+
+These prompts handle error recovery, graceful degradation, and
+user-friendly error message generation.
+"""
+
+# Error Analysis Prompt
+ERROR_ANALYSIS_PROMPT = """You are an expert at analyzing and diagnosing system errors.
+
+Your task is to analyze the error and suggest recovery strategies.
+
+ERROR DETAILS:
+- Type: {error_type}
+- Message: {error_message}
+- Context: {context}
+- Component: {component}
+
+Analyze the error and provide:
+
+1. **Root Cause**: What likely caused this error
+2. **Impact**: What functionality is affected
+3. **Recovery Options**: Possible ways to recover
+4. **Prevention**: How to prevent this in the future
+
+Respond in JSON format:
+{{
+    "analysis": {{
+        "root_cause": "most likely cause",
+        "impact_level": "low|medium|high|critical",
+        "affected_functionality": ["list of affected features"],
+        "is_recoverable": true/false
+    }},
+    "recovery_strategies": [
+        {{
+            "strategy": "strategy name",
+            "description": "how to implement",
+            "success_likelihood": 0.0-1.0,
+            "side_effects": ["potential side effects"]
+        }}
+    ],
+    "user_message": "friendly message for the user",
+    "technical_details": "detailed technical explanation",
+    "prevention_measures": ["how to prevent in future"]
+}}
+"""
+
+# Graceful Degradation Prompt
+GRACEFUL_DEGRADATION_PROMPT = """You are an expert at designing graceful degradation strategies.
+
+Your task is to suggest how to provide partial results when full functionality fails.
+
+FAILED OPERATION: {operation}
+PARTIAL RESULTS: {partial_results}
+MISSING COMPONENTS: {missing_components}
+
+Determine how to provide value despite the failure:
+
+1. **Partial Delivery**: What can still be delivered?
+2. **Quality Impact**: How is quality affected?
+3. **User Communication**: How to explain the limitation?
+4. **Workarounds**: Alternative approaches to try
+
+Respond in JSON format:
+{{
+    "degraded_response": {{
+        "can_provide_partial": true/false,
+        "available_results": "what can be delivered",
+        "missing_results": "what is unavailable",
+        "quality_reduction": 0.0-1.0
+    }},
+    "user_communication": {{
+        "message": "user-friendly explanation",
+        "limitations_explained": ["list of limitations"],
+        "workaround_suggestions": ["suggestions for user"]
+    }},
+    "alternative_approaches": [
+        {{
+            "approach": "alternative method",
+            "feasibility": 0.0-1.0,
+            "tradeoffs": ["tradeoffs"]
+        }}
+    ],
+    "retry_recommendation": {{
+        "should_retry": true/false,
+        "retry_strategy": "how to retry",
+        "delay_seconds": 0
+    }}
+}}
+"""
+
+# User Error Message Generation Prompt
+USER_ERROR_MESSAGE_PROMPT = """You are an expert at crafting user-friendly error messages.
+
+Your task is to create a helpful error message for the user.
+
+ERROR INFORMATION:
+- Error Type: {error_type}
+- Technical Message: {technical_message}
+- User Action: {user_action}
+- Severity: {severity}
+
+Create a user-friendly message that:
+
+1. **Explains** what went wrong in simple terms
+2. **Reassures** the user (if appropriate)
+3. **Guides** them on what to do next
+4. **Avoids** technical jargon
+
+Respond in JSON format:
+{{
+    "user_message": {{
+        "headline": "Brief, clear headline",
+        "explanation": "What happened in plain language",
+        "what_to_do": "Steps the user can take",
+        "tone": "apologetic|informative|helpful"
+    }},
+    "actions": [
+        {{
+            "action": "action name",
+            "description": "what it does",
+            "button_text": "text for button/link"
+        }}
+    ],
+    "show_technical_details": true/false,
+    "severity_indicator": "info|warning|error|critical"
+}}
+"""
+
+# Retry Strategy Prompt
+RETRY_STRATEGY_PROMPT = """You are an expert at designing retry strategies for failed operations.
+
+Your task is to determine the optimal retry strategy for the failed operation.
+
+FAILED OPERATION: {operation}
+FAILURE REASON: {failure_reason}
+ATTEMPT NUMBER: {attempt_number}
+OPERATION CONTEXT: {context}
+
+Determine the best retry approach:
+
+1. **Should Retry**: Is retrying worthwhile?
+2. **Timing**: How long to wait before retry
+3. **Modification**: Should the request be modified?
+4. **Limit**: Maximum retry attempts
+
+Respond in JSON format:
+{{
+    "retry_decision": {{
+        "should_retry": true/false,
+        "reason": "why or why not",
+        "max_attempts": 0,
+        "current_attempt": {attempt_number}
+    }},
+    "timing": {{
+        "delay_seconds": 0,
+        "backoff_strategy": "none|linear|exponential",
+        "max_delay_seconds": 0
+    }},
+    "modifications": {{
+        "modify_request": true/false,
+        "suggested_changes": ["changes to make"],
+        "reduce_scope": true/false
+    }},
+    "alternatives": [
+        {{
+            "alternative": "alternative approach",
+            "when_to_use": "when this alternative is appropriate"
+        }}
+    ]
+}}
+"""
+
+# Error Recovery Prompt
+ERROR_RECOVERY_PROMPT = """You are an expert at recovering from errors in complex systems.
+
+Your task is to orchestrate recovery from the current error state.
+
+CURRENT STATE:
+{current_state}
+
+ERROR CHAIN:
+{error_chain}
+
+AVAILABLE RESOURCES:
+{available_resources}
+
+Plan the recovery:
+
+1. **State Assessment**: What is the current system state?
+2. **Recovery Path**: Steps to recover
+3. **Data Salvage**: What data can be saved?
+4. **State Restoration**: How to restore normal operation
+
+Respond in JSON format:
+{{
+    "state_assessment": {{
+        "corruption_level": "none|partial|severe",
+        "salvageable_data": ["list of salvageable items"],
+        "lost_data": ["list of lost items"]
+    }},
+    "recovery_plan": [
+        {{
+            "step": 1,
+            "action": "action to take",
+            "expected_outcome": "what should happen",
+            "fallback": "what to do if this fails"
+        }}
+    ],
+    "data_recovery": {{
+        "recovered_items": ["items that can be recovered"],
+        "recovery_method": "how to recover"
+    }},
+    "post_recovery": {{
+        "verification_steps": ["how to verify recovery"],
+        "monitoring_period": "how long to monitor",
+        "success_indicators": ["indicators of successful recovery"]
+    }}
+}}
+"""
+
+# Fallback Content Generation Prompt
+FALLBACK_CONTENT_PROMPT = """You are an expert at generating fallback content when primary sources fail.
+
+Your task is to generate helpful fallback content based on available information.
+
+ORIGINAL QUERY: {query}
+AVAILABLE INFORMATION: {available_info}
+FAILED SOURCES: {failed_sources}
+CACHED DATA: {cached_data}
+
+Generate fallback content that:
+
+1. **Acknowledges** the limitation
+2. **Provides** whatever information is available
+3. **Suggests** alternatives
+4. **Maintains** quality standards
+
+Respond in JSON format:
+{{
+    "fallback_content": {{
+        "response": "best possible response given limitations",
+        "confidence": 0.0-1.0,
+        "completeness": 0.0-1.0,
+        "based_on": ["what information was used"]
+    }},
+    "limitations_disclosure": {{
+        "what_is_missing": ["missing information"],
+        "quality_impact": "how quality is affected",
+        "reliability_note": "note about reliability"
+    }},
+    "next_steps": [
+        {{
+            "suggestion": "what user could try",
+            "likelihood_of_success": 0.0-1.0
+        }}
+    ]
+}}
+"""
+
+# System Health Check Prompt
+SYSTEM_HEALTH_PROMPT = """You are an expert at assessing system health and diagnosing issues.
+
+Your task is to analyze the system health metrics and identify issues.
+
+HEALTH METRICS:
+{health_metrics}
+
+RECENT ERRORS:
+{recent_errors}
+
+PERFORMANCE DATA:
+{performance_data}
+
+Assess the system health:
+
+1. **Overall Status**: System health rating
+2. **Components**: Status of each component
+3. **Issues**: Current and potential issues
+4. **Recommendations**: What to do
+
+Respond in JSON format:
+{{
+    "health_status": {{
+        "overall": "healthy|degraded|unhealthy|critical",
+        "score": 0.0-1.0
+    }},
+    "components": [
+        {{
+            "name": "component name",
+            "status": "healthy|degraded|unhealthy",
+            "issues": ["issues if any"]
+        }}
+    ],
+    "active_issues": [
+        {{
+            "issue": "issue description",
+            "severity": "low|medium|high|critical",
+            "affected_functionality": ["affected features"]
+        }}
+    ],
+    "recommendations": [
+        {{
+            "action": "recommended action",
+            "priority": "immediate|soon|when_convenient",
+            "impact": "expected impact"
+        }}
+    ]
+}}
+"""

src/prompts/output_prompts.py

@@ -0,0 +1,362 @@
+"""
+Output generation prompts for the Deep Research AI system.
+
+These prompts handle the final synthesis and formatting of research results
+into user-friendly, well-structured output formats.
+"""
+
+# Report Generation Prompt
+REPORT_GENERATION_PROMPT = """You are an expert research report writer.
+
+Your task is to generate a comprehensive, well-structured research report.
+
+RESEARCH QUERY:
+{query}
+
+SYNTHESIZED FINDINGS:
+{findings}
+
+SOURCES USED:
+{sources}
+
+CONFIDENCE ASSESSMENT:
+{confidence}
+
+Generate a research report following this structure:
+
+1. **Executive Summary**: Brief overview of key findings (2-3 paragraphs)
+
+2. **Introduction**: 
+   - Research question context
+   - Scope and methodology used
+   - Key terms defined
+
+3. **Main Findings**:
+   - Organized by theme or sub-question
+   - Evidence-based claims with source references
+   - Data and statistics where available
+
+4. **Analysis**:
+   - Synthesis of findings
+   - Patterns and trends identified
+   - Conflicting viewpoints addressed
+
+5. **Limitations**:
+   - Gaps in available information
+   - Confidence levels explained
+   - Areas needing further research
+
+6. **Conclusion**:
+   - Direct answer to research question
+   - Key takeaways
+   - Recommendations if applicable
+
+Respond in JSON format:
+{{
+    "report": {{
+        "title": "Report title",
+        "executive_summary": "2-3 paragraph summary",
+        "introduction": {{
+            "context": "Research context",
+            "scope": "Scope of research",
+            "methodology": "Brief methodology",
+            "key_terms": {{"term": "definition"}}
+        }},
+        "main_findings": [
+            {{
+                "theme": "Finding theme",
+                "content": "Detailed findings",
+                "evidence": ["supporting evidence"],
+                "sources": ["source_ids"]
+            }}
+        ],
+        "analysis": {{
+            "synthesis": "Synthesized analysis",
+            "patterns": ["identified patterns"],
+            "conflicting_views": ["conflicts and how addressed"]
+        }},
+        "limitations": {{
+            "information_gaps": ["gaps"],
+            "confidence_notes": "confidence explanation",
+            "further_research": ["suggested areas"]
+        }},
+        "conclusion": {{
+            "answer": "Direct answer to query",
+            "key_takeaways": ["takeaway points"],
+            "recommendations": ["recommendations if any"]
+        }}
+    }},
+    "metadata": {{
+        "word_count": 0,
+        "reading_time_minutes": 0,
+        "complexity_level": "beginner|intermediate|advanced"
+    }}
+}}
+"""
+
+# Summary Generation Prompt
+SUMMARY_GENERATION_PROMPT = """You are an expert at creating concise, informative summaries.
+
+Your task is to create a summary of research findings at the specified detail level.
+
+RESEARCH FINDINGS:
+{findings}
+
+SUMMARY LENGTH: {length}
+
+Generate a summary following these guidelines:
+
+1. **Brief** (1-2 paragraphs): Key answer only
+2. **Standard** (3-5 paragraphs): Answer with main supporting points
+3. **Detailed** (6-10 paragraphs): Comprehensive summary with nuance
+
+Include:
+- Direct answer to the research question
+- Most important supporting evidence
+- Key caveats or limitations
+- Confidence level indication
+
+Respond in JSON format:
+{{
+    "summary": {{
+        "text": "The complete summary text",
+        "key_points": ["bullet point takeaways"],
+        "confidence_statement": "How confident we are in these findings",
+        "caveats": ["important caveats"]
+    }},
+    "metadata": {{
+        "length_type": "{length}",
+        "word_count": 0,
+        "source_count": 0
+    }}
+}}
+"""
+
+# Answer Formatting Prompt
+ANSWER_FORMATTING_PROMPT = """You are an expert at formatting research answers for different audiences.
+
+Your task is to format the research answer for the specified audience and format.
+
+RESEARCH ANSWER:
+{answer}
+
+TARGET AUDIENCE: {audience}
+OUTPUT FORMAT: {format}
+
+Format the answer according to these specifications:
+
+**Audience Levels:**
+- general: Non-technical, accessible language
+- professional: Business/industry appropriate
+- academic: Scholarly, formal language
+- technical: Technical details included
+
+**Output Formats:**
+- text: Plain text with paragraphs
+- markdown: Full markdown formatting
+- html: HTML formatted
+- structured: Bullet points and sections
+
+Respond in JSON format:
+{{
+    "formatted_answer": {{
+        "content": "The formatted answer",
+        "format": "{format}",
+        "audience": "{audience}"
+    }},
+    "readability_metrics": {{
+        "grade_level": "estimated reading grade level",
+        "technical_density": "low|medium|high"
+    }}
+}}
+"""
+
+# Visualization Suggestion Prompt
+VISUALIZATION_SUGGESTION_PROMPT = """You are an expert in data visualization and information design.
+
+Your task is to suggest visualizations that would enhance the research presentation.
+
+RESEARCH DATA:
+{data}
+
+FINDINGS:
+{findings}
+
+Suggest appropriate visualizations:
+
+1. **Charts**: For numerical/statistical data
+2. **Diagrams**: For relationships and processes
+3. **Tables**: For comparisons
+4. **Timelines**: For temporal information
+5. **Maps**: For geographical data
+
+Respond in JSON format:
+{{
+    "visualizations": [
+        {{
+            "type": "chart|diagram|table|timeline|map|infographic",
+            "subtype": "bar|line|pie|flowchart|comparison|etc",
+            "title": "Suggested title",
+            "description": "What it would show",
+            "data_requirements": ["data needed"],
+            "priority": "high|medium|low",
+            "implementation_notes": "How to create it"
+        }}
+    ],
+    "recommended_count": 0,
+    "data_visualization_potential": "low|medium|high"
+}}
+"""
+
+# Multi-format Output Prompt
+MULTI_FORMAT_OUTPUT_PROMPT = """You are an expert at generating research outputs in multiple formats.
+
+Your task is to generate the research output in multiple formats simultaneously.
+
+RESEARCH CONTENT:
+{content}
+
+CITATIONS:
+{citations}
+
+Generate outputs in these formats:
+
+1. **Plain Text**: Simple, readable text
+2. **Markdown**: With proper formatting
+3. **HTML**: Web-ready format
+4. **JSON**: Structured data format
+
+Respond in JSON format:
+{{
+    "outputs": {{
+        "plain_text": "Plain text version",
+        "markdown": "Markdown version with ## headers, **bold**, etc",
+        "html": "<html>HTML version</html>",
+        "json": {{
+            "structured": "data representation"
+        }}
+    }},
+    "recommended_format": "most suitable format",
+    "format_notes": {{
+        "plain_text": "notes about this format",
+        "markdown": "notes",
+        "html": "notes",
+        "json": "notes"
+    }}
+}}
+"""
+
+# Response Quality Assessment Prompt
+RESPONSE_QUALITY_PROMPT = """You are an expert at assessing research output quality.
+
+Your task is to evaluate the quality of the generated research response.
+
+ORIGINAL QUERY:
+{query}
+
+GENERATED RESPONSE:
+{response}
+
+SOURCES USED:
+{sources}
+
+Evaluate the response on these criteria:
+
+1. **Relevance**: How well does it answer the query?
+2. **Completeness**: Are all aspects addressed?
+3. **Accuracy**: Are claims properly supported?
+4. **Clarity**: Is it well-written and clear?
+5. **Citation Quality**: Are sources properly attributed?
+6. **Objectivity**: Is it balanced and unbiased?
+
+Respond in JSON format:
+{{
+    "quality_assessment": {{
+        "overall_score": 0.0-1.0,
+        "criteria_scores": {{
+            "relevance": 0.0-1.0,
+            "completeness": 0.0-1.0,
+            "accuracy": 0.0-1.0,
+            "clarity": 0.0-1.0,
+            "citation_quality": 0.0-1.0,
+            "objectivity": 0.0-1.0
+        }},
+        "strengths": ["identified strengths"],
+        "weaknesses": ["identified weaknesses"],
+        "improvement_suggestions": ["suggestions"]
+    }},
+    "confidence_level": "low|medium|high|very_high",
+    "ready_for_delivery": true/false,
+    "revision_needed": true/false
+}}
+"""
+
+# Follow-up Question Generation Prompt
+FOLLOWUP_QUESTIONS_PROMPT = """You are an expert at identifying valuable follow-up research questions.
+
+Your task is to generate relevant follow-up questions based on the research.
+
+ORIGINAL QUERY:
+{query}
+
+RESEARCH FINDINGS:
+{findings}
+
+INFORMATION GAPS:
+{gaps}
+
+Generate follow-up questions that would:
+1. Deepen understanding of the topic
+2. Address identified gaps
+3. Explore related areas
+4. Clarify ambiguities
+
+Respond in JSON format:
+{{
+    "follow_up_questions": [
+        {{
+            "question": "The follow-up question",
+            "rationale": "Why this question is valuable",
+            "type": "deepening|gap_filling|related|clarification",
+            "priority": "high|medium|low",
+            "estimated_complexity": "simple|moderate|complex"
+        }}
+    ],
+    "recommended_next_question": "most valuable next question",
+    "research_continuation_score": 0.0-1.0
+}}
+"""
+
+# Export Format Prompt
+EXPORT_FORMAT_PROMPT = """You are an expert at preparing research for export and sharing.
+
+Your task is to prepare the research output for the specified export format.
+
+RESEARCH REPORT:
+{report}
+
+EXPORT FORMAT: {export_format}
+
+Prepare the content for export considering:
+
+1. **PDF**: Proper structure, headers, pagination hints
+2. **DOCX**: Word-compatible formatting
+3. **Slides**: Key points for presentation
+4. **Email**: Professional email format
+5. **Social**: Social media appropriate snippets
+
+Respond in JSON format:
+{{
+    "export_ready": {{
+        "content": "Formatted content for export",
+        "format": "{export_format}",
+        "sections": ["section breakdown"],
+        "formatting_notes": "notes for the export format"
+    }},
+    "export_metadata": {{
+        "suggested_filename": "filename",
+        "estimated_pages": 0,
+        "includes_citations": true/false
+    }}
+}}
+"""

src/prompts/query_prompts.py

@@ -0,0 +1,173 @@
+"""
+Query understanding prompts.
+"""
+
+QUERY_PROMPTS = {
+    "analysis": """You are an expert research query analyzer. Your task is to deeply understand the user's research question and extract structured information.
+
+## User Query
+{query}
+
+## Instructions
+Analyze this query and provide:
+
+1. **Intent**: What is the user trying to learn or accomplish?
+2. **Domain**: What field or subject area does this query belong to?
+3. **Key Entities**: List all important people, organizations, concepts, or things mentioned
+4. **Temporal Scope**: Is there a time frame mentioned or implied?
+5. **Geographic Scope**: Is there a location focus?
+6. **Complexity Level**: Simple (single fact), Medium (comparison/analysis), Complex (multi-faceted research)
+7. **Expected Output Type**: Factual answer, comparison, analysis, explanation, or comprehensive report
+
+## Output Format
+Respond in JSON:
+{{
+  "intent": "string",
+  "domain": "string",
+  "entities": [
+    {{"text": "entity name", "type": "PERSON|ORG|LOCATION|DATE|CONCEPT|PRODUCT|EVENT", "relevance": "primary|secondary"}}
+  ],
+  "temporal_scope": "string or null",
+  "geographic_scope": "string or null",
+  "complexity": "simple|medium|complex",
+  "output_type": "string"
+}}""",
+
+    "decomposition": """You are an expert at breaking down complex research questions into smaller, searchable sub-queries.
+
+## Original Query
+{query}
+
+## Query Analysis
+{query_analysis}
+
+## Instructions
+Decompose this query into independent sub-queries that can be researched separately. Each sub-query should:
+- Be self-contained and searchable
+- Address one specific aspect of the main question
+- Be ordered by logical dependency (foundational questions first)
+
+## Output Format
+{{
+  "sub_queries": [
+    {{
+      "id": 1,
+      "query": "What is X?",
+      "purpose": "Establish foundational understanding of X",
+      "depends_on": [],
+      "priority": "high|medium|low"
+    }}
+  ],
+  "synthesis_strategy": "How to combine sub-query results into final answer"
+}}""",
+
+    "entity_extraction": """You are an expert Named Entity Recognition system. Extract all entities from the following research query.
+
+## Query
+{query}
+
+## Instructions
+Identify and categorize all entities:
+
+- **PERSON**: Names of individuals
+- **ORG**: Organizations, companies, institutions
+- **LOCATION**: Places, countries, regions
+- **DATE**: Dates, time periods, years
+- **CONCEPT**: Abstract concepts, theories, methodologies
+- **PRODUCT**: Products, technologies, tools
+- **EVENT**: Historical or current events
+
+## Output Format
+{{
+  "entities": [
+    {{
+      "text": "entity name",
+      "type": "PERSON|ORG|LOCATION|DATE|CONCEPT|PRODUCT|EVENT",
+      "relevance": "primary|secondary",
+      "context": "brief context of how it's used in query"
+    }}
+  ]
+}}""",
+
+    "clarification": """You are a research assistant helping to clarify ambiguous queries.
+
+## Query
+{query}
+
+## Instructions
+Analyze the query for potential ambiguities:
+
+1. **Ambiguous Terms**: Words or phrases that could have multiple meanings
+2. **Missing Context**: Important context that would help narrow the research
+3. **Scope Uncertainty**: Unclear boundaries of what to include/exclude
+4. **Implicit Assumptions**: Assumptions the user might be making
+
+For each issue, suggest a clarifying question.
+
+## Output Format
+{{
+  "is_clear": true|false,
+  "ambiguities": [
+    {{
+      "issue": "description of ambiguity",
+      "clarifying_question": "question to ask user",
+      "default_assumption": "what to assume if user doesn't clarify"
+    }}
+  ],
+  "refined_query": "Query with default assumptions applied"
+}}""",
+
+    "intent_classification": """You are an expert at classifying research query intents.
+
+## Query
+{query}
+
+## Intent Categories
+
+1. **FACTUAL**: Looking for specific facts or data
+2. **EXPLANATORY**: Seeking to understand how or why something works
+3. **COMPARATIVE**: Comparing two or more things
+4. **EXPLORATORY**: Open-ended exploration of a topic
+5. **ANALYTICAL**: Deep analysis requiring synthesis of multiple sources
+6. **PREDICTIVE**: Seeking forecasts or future projections
+7. **EVALUATIVE**: Assessing quality, effectiveness, or value
+8. **PROCEDURAL**: Looking for how-to or step-by-step guidance
+
+## Instructions
+Classify the primary and secondary intents, and explain your reasoning.
+
+## Output Format
+{{
+  "primary_intent": "INTENT_TYPE",
+  "secondary_intent": "INTENT_TYPE or null",
+  "confidence": 0.0-1.0,
+  "reasoning": "Brief explanation",
+  "research_approach": "Recommended approach based on intent"
+}}""",
+
+    "validation": """You are a query validator for a research system.
+
+## Query
+{query}
+
+## Validation Criteria
+
+Check the query against these criteria:
+1. **Researchable**: Can this be answered through web research?
+2. **Appropriate**: Is this a legitimate research question (not harmful/illegal)?
+3. **Specific Enough**: Is there enough detail to conduct research?
+4. **Within Scope**: Is this within the system's capabilities?
+
+## Output Format
+{{
+  "is_valid": true|false,
+  "validation_results": {{
+    "researchable": {{"passed": true|false, "reason": "string"}},
+    "appropriate": {{"passed": true|false, "reason": "string"}},
+    "specific": {{"passed": true|false, "reason": "string"}},
+    "in_scope": {{"passed": true|false, "reason": "string"}}
+  }},
+  "suggestions": ["Suggestion to improve query if invalid"],
+  "proceed": true|false
+}}"""
+}

src/prompts/reasoning_prompts.py

@@ -0,0 +1,288 @@
+"""
+Reasoning prompts for multi-step analysis.
+"""
+
+REASONING_PROMPTS = {
+    "chain_of_thought": """You are an expert research analyst performing chain-of-thought reasoning. Think through this research question step by step.
+
+## Research Question
+{query}
+
+## Gathered Information
+{context}
+
+## Sources
+{sources}
+
+## Instructions
+Reason through this step by step:
+
+1. **Understand the Question**: What exactly is being asked?
+2. **Identify Key Information**: What relevant facts do we have?
+3. **Analyze Relationships**: How do the pieces of information connect?
+4. **Draw Inferences**: What can we conclude from the evidence?
+5. **Identify Gaps**: What information is missing?
+6. **Formulate Answer**: What is the best answer based on available evidence?
+
+## Rules
+- Show your reasoning explicitly
+- Cite sources for each claim
+- Acknowledge uncertainty when present
+- Distinguish facts from inferences
+
+## Output Format
+{{
+  "reasoning_chain": [
+    {{
+      "step": 1,
+      "action": "understand|identify|analyze|infer|gap|formulate",
+      "thought": "Your reasoning at this step",
+      "evidence": ["source citations"],
+      "conclusion": "What you concluded"
+    }}
+  ],
+  "final_answer": "Synthesized answer to the question",
+  "confidence": 0.85,
+  "gaps_identified": ["Missing information that would improve answer"]
+}}""",
+
+    "synthesis": """You are an expert research synthesizer. Combine information from multiple sources into a coherent, well-organized synthesis.
+
+## Research Question
+{query}
+
+## Source Information
+{sources_with_content}
+
+## Instructions
+Synthesize the information by:
+
+1. **Identifying Common Themes**: What topics appear across multiple sources?
+2. **Finding Consensus**: Where do sources agree?
+3. **Noting Disagreements**: Where do sources conflict?
+4. **Filling Gaps**: How do sources complement each other?
+5. **Building Narrative**: Create a coherent story from the pieces
+
+## Synthesis Rules
+- Prioritize information from multiple corroborating sources
+- Clearly attribute claims to sources
+- Present balanced view when sources disagree
+- Do not add information not present in sources
+
+## Output Format
+{{
+  "themes": [
+    {{
+      "theme": "Theme name",
+      "description": "What this theme covers",
+      "sources": ["source1", "source2"],
+      "key_points": ["point1", "point2"]
+    }}
+  ],
+  "consensus_findings": [
+    {{
+      "finding": "What sources agree on",
+      "supporting_sources": ["source1", "source2"],
+      "confidence": "high|medium"
+    }}
+  ],
+  "disagreements": [
+    {{
+      "topic": "What they disagree about",
+      "perspectives": [
+        {{"source": "source1", "position": "their view"}},
+        {{"source": "source2", "position": "their view"}}
+      ]
+    }}
+  ],
+  "synthesis": "Narrative synthesis of all information",
+  "key_insights": ["Main takeaways"]
+}}""",
+
+    "comparative_analysis": """You are an expert comparative analyst. Perform a detailed comparison based on the research findings.
+
+## Comparison Query
+{query}
+
+## Subjects to Compare
+{subjects}
+
+## Gathered Information
+{context}
+
+## Instructions
+Create a structured comparison:
+
+1. **Identify Comparison Dimensions**: What aspects should be compared?
+2. **Extract Data Points**: Find comparable data for each subject
+3. **Analyze Similarities**: Where are the subjects alike?
+4. **Analyze Differences**: Where do they differ?
+5. **Draw Conclusions**: What does the comparison reveal?
+
+## Output Format
+{{
+  "subjects": ["Subject A", "Subject B"],
+  "dimensions": [
+    {{
+      "dimension": "Aspect being compared",
+      "subject_a": {{
+        "value": "Data or description",
+        "source": "citation"
+      }},
+      "subject_b": {{
+        "value": "Data or description",
+        "source": "citation"
+      }},
+      "analysis": "What this comparison shows"
+    }}
+  ],
+  "similarities": [
+    {{
+      "aspect": "What's similar",
+      "description": "Details",
+      "significance": "Why this matters"
+    }}
+  ],
+  "differences": [
+    {{
+      "aspect": "What's different",
+      "description": "Details",
+      "significance": "Why this matters"
+    }}
+  ],
+  "conclusion": "Overall comparative analysis"
+}}""",
+
+    "causal_analysis": """You are an expert at causal analysis. Identify and analyze cause-and-effect relationships in the research findings.
+
+## Research Question
+{query}
+
+## Context
+{context}
+
+## Instructions
+Perform causal analysis:
+
+1. **Identify Potential Causes**: What factors might cause the phenomenon?
+2. **Identify Effects**: What are the outcomes or consequences?
+3. **Establish Relationships**: How do causes link to effects?
+4. **Evaluate Evidence**: How strong is the evidence for each causal claim?
+5. **Consider Alternatives**: What other explanations exist?
+
+## Causal Reasoning Rules
+- Correlation does not imply causation
+- Consider confounding variables
+- Look for temporal ordering (cause before effect)
+- Seek multiple sources of evidence
+
+## Output Format
+{{
+  "causal_relationships": [
+    {{
+      "cause": "The proposed cause",
+      "effect": "The proposed effect",
+      "mechanism": "How the cause leads to effect",
+      "evidence": ["supporting evidence"],
+      "strength": "strong|moderate|weak",
+      "confidence": 0.75
+    }}
+  ],
+  "alternative_explanations": [
+    {{
+      "explanation": "Alternative cause",
+      "plausibility": "high|medium|low"
+    }}
+  ],
+  "confounding_factors": ["Factors that might affect the relationship"],
+  "causal_chain": "Narrative of the causal relationships",
+  "limitations": ["Limitations of this causal analysis"]
+}}""",
+
+    "gap_analysis": """You are a research gap analyst. Identify gaps in the current research findings.
+
+## Research Question
+{query}
+
+## Current Findings
+{findings}
+
+## Sources Consulted
+{sources}
+
+## Instructions
+Analyze gaps in the research:
+
+1. **Coverage Gaps**: What aspects of the question aren't addressed?
+2. **Depth Gaps**: Where is information superficial?
+3. **Recency Gaps**: Is information outdated?
+4. **Source Gaps**: Are important source types missing?
+5. **Perspective Gaps**: Are viewpoints underrepresented?
+
+## Output Format
+{{
+  "coverage_gaps": [
+    {{
+      "missing_aspect": "What's not covered",
+      "importance": "critical|important|nice_to_have",
+      "suggested_search": "Query to fill this gap"
+    }}
+  ],
+  "depth_gaps": [
+    {{
+      "topic": "Topic needing more depth",
+      "current_depth": "What we have",
+      "needed_depth": "What we need"
+    }}
+  ],
+  "recency_gaps": [
+    {{
+      "topic": "Outdated information area",
+      "most_recent_date": "Date of newest source",
+      "recommendation": "How to update"
+    }}
+  ],
+  "overall_completeness": 75,
+  "priority_gaps": ["Top gaps to fill before completing research"],
+  "can_proceed": true
+}}""",
+
+    "reasoning_verification": """You are a logic and reasoning validator. Verify the soundness of this reasoning chain.
+
+## Reasoning Chain
+{reasoning_chain}
+
+## Instructions
+Check for:
+
+1. **Logical Validity**: Do conclusions follow from premises?
+2. **Factual Accuracy**: Are stated facts correct?
+3. **Hidden Assumptions**: Are there unstated assumptions?
+4. **Logical Fallacies**: Are there reasoning errors?
+5. **Bias Detection**: Are there signs of bias?
+
+## Common Fallacies to Check
+- Hasty generalization
+- False causation
+- Appeal to authority (without merit)
+- Cherry picking
+- Circular reasoning
+
+## Output Format
+{{
+  "is_valid": true,
+  "validity_score": 85,
+  "issues": [
+    {{
+      "step": "Which step has the issue",
+      "issue_type": "logic|fact|assumption|fallacy|bias",
+      "description": "What the issue is",
+      "severity": "critical|moderate|minor",
+      "suggestion": "How to fix it"
+    }}
+  ],
+  "hidden_assumptions": ["Unstated assumptions in the reasoning"],
+  "overall_assessment": "Summary of reasoning quality",
+  "recommendations": ["How to improve the reasoning"]
+}}"""
+}

src/prompts/search_prompts.py

@@ -0,0 +1,257 @@
+"""
+Web search prompts.
+"""
+
+SEARCH_PROMPTS = {
+    "query_generation": """You are an expert at crafting effective web search queries. Your goal is to generate search queries that will return the most relevant and high-quality results.
+
+## Research Sub-Query
+{sub_query}
+
+## Context
+Original research question: {original_query}
+Domain: {domain}
+Entities: {entities}
+
+## Instructions
+Generate 3-5 search queries optimized for web search. Consider:
+
+1. **Primary Query**: Direct, keyword-focused search
+2. **Alternative Phrasing**: Same intent, different words
+3. **Specific Query**: Narrow, targeted search
+4. **Broad Query**: Wider scope for context
+5. **Source-Specific**: Target authoritative sources (e.g., "site:gov" or "site:edu")
+
+## Search Query Best Practices
+- Use specific keywords, not full sentences
+- Include important entities and dates
+- Use quotes for exact phrases when needed
+- Consider synonyms and alternative terms
+
+## Output Format
+{{
+  "queries": [
+    {{
+      "query": "search query string",
+      "strategy": "primary|alternative|specific|broad|source_specific",
+      "expected_results": "what results this should return",
+      "priority": 1
+    }}
+  ]
+}}""",
+
+    "query_expansion": """You are a search query expansion expert. Expand the given query with related terms to improve search coverage.
+
+## Original Query
+{query}
+
+## Domain Context
+{domain}
+
+## Instructions
+Expand the query by adding:
+
+1. **Synonyms**: Alternative words with similar meaning
+2. **Related Terms**: Conceptually related keywords
+3. **Acronyms/Abbreviations**: Both forms if applicable
+4. **Broader Terms**: More general category terms
+5. **Narrower Terms**: More specific sub-topics
+
+## Output Format
+{{
+  "original_query": "string",
+  "expanded_queries": [
+    {{
+      "query": "expanded query",
+      "expansion_type": "synonym|related|acronym|broader|narrower",
+      "added_terms": ["term1", "term2"]
+    }}
+  ],
+  "recommended_query": "Best combined query using expansion"
+}}""",
+
+    "relevance_evaluation": """You are a search result relevance evaluator. Assess how relevant each search result is to the research query.
+
+## Research Query
+{query}
+
+## Search Results
+{search_results}
+
+## Instructions
+For each result, evaluate:
+
+1. **Relevance Score (0-10)**: How directly does this address the query?
+2. **Information Value**: What unique information does this provide?
+3. **Source Quality**: Is this a credible source?
+4. **Freshness**: Is the information current enough?
+5. **Should Retrieve**: Should we fetch the full content?
+
+## Output Format
+{{
+  "evaluated_results": [
+    {{
+      "url": "string",
+      "title": "string",
+      "relevance_score": 8,
+      "information_value": "high|medium|low",
+      "source_quality": "high|medium|low|unknown",
+      "freshness": "current|recent|dated|unknown",
+      "should_retrieve": true,
+      "reasoning": "Brief explanation"
+    }}
+  ],
+  "recommended_sources": ["urls to retrieve in priority order"]
+}}""",
+
+    "content_extraction": """You are an expert content extractor. Extract the most relevant information from this web page content for the given research query.
+
+## Research Query
+{query}
+
+## Web Page Content
+URL: {url}
+Title: {title}
+Content:
+{content}
+
+## Instructions
+Extract:
+
+1. **Key Facts**: Specific facts relevant to the query
+2. **Data Points**: Numbers, statistics, dates
+3. **Quotes**: Important quotes with attribution
+4. **Claims**: Assertions made in the content
+5. **Context**: Background information that helps understand the topic
+
+## Rules
+- Only extract information directly from the content
+- Preserve original wording for quotes
+- Note any caveats or limitations mentioned
+- Identify the publication date if available
+
+## Output Format
+{{
+  "source": {{
+    "url": "string",
+    "title": "string",
+    "publication_date": "date or null",
+    "author": "string or null"
+  }},
+  "extracted_information": [
+    {{
+      "type": "fact|data|quote|claim|context",
+      "content": "extracted text",
+      "relevance": "high|medium|low",
+      "location": "where in the document"
+    }}
+  ],
+  "summary": "2-3 sentence summary of relevant content",
+  "limitations": ["any noted caveats or limitations"]
+}}""",
+
+    "search_strategy": """You are a search strategy advisor. Recommend the optimal search approach for this research query.
+
+## Query Analysis
+{query_analysis}
+
+## Available Search Strategies
+
+1. **Breadth-First**: Many queries, shallow depth - good for exploratory research
+2. **Depth-First**: Few queries, deep dive - good for specific topics
+3. **Authoritative Sources**: Target .gov, .edu, established publications
+4. **News Focus**: Recent news articles and press releases
+5. **Academic Focus**: Research papers and scholarly sources
+6. **Multi-Perspective**: Deliberately seek diverse viewpoints
+7. **Temporal**: Historical progression of information
+
+## Instructions
+Select and prioritize search strategies based on the query characteristics.
+
+## Output Format
+{{
+  "primary_strategy": "strategy name",
+  "secondary_strategies": ["strategy1", "strategy2"],
+  "reasoning": "Why these strategies suit this query",
+  "search_parameters": {{
+    "max_sources": 10,
+    "time_range": "any|past_year|past_month|past_week",
+    "source_types": ["news", "academic", "government", "general"],
+    "geographic_focus": "string or null"
+  }}
+}}""",
+
+    "failure_recovery": """You are a search recovery specialist. The initial search did not return useful results. Generate alternative approaches.
+
+## Original Query
+{query}
+
+## Failed Searches
+{failed_searches}
+
+## Failure Reasons
+{failure_reasons}
+
+## Instructions
+Propose recovery strategies:
+
+1. **Query Reformulation**: Rephrase the query completely
+2. **Broader Search**: Remove constraints, search more generally
+3. **Related Topics**: Search for related topics that might lead to the answer
+4. **Different Angle**: Approach the question from a different perspective
+5. **Source Suggestions**: Specific types of sources to try
+
+## Output Format
+{{
+  "diagnosis": "Why the original searches failed",
+  "recovery_strategies": [
+    {{
+      "strategy": "strategy name",
+      "new_queries": ["query1", "query2"],
+      "rationale": "Why this might work",
+      "priority": 1
+    }}
+  ],
+  "fallback_response": "What to tell user if all searches fail"
+}}""",
+
+    "duplicate_detection": """You are a duplicate content detector. Identify overlapping information across multiple search results.
+
+## Retrieved Content
+{content_list}
+
+## Instructions
+Analyze the content for:
+
+1. **Exact Duplicates**: Same information from multiple sources
+2. **Near Duplicates**: Paraphrased or slightly modified versions
+3. **Unique Content**: Information appearing in only one source
+4. **Conflicting Information**: Same topic, different claims
+
+## Output Format
+{{
+  "duplicate_groups": [
+    {{
+      "information": "The duplicated information",
+      "sources": ["url1", "url2"],
+      "duplicate_type": "exact|near",
+      "best_source": "url of the most authoritative source"
+    }}
+  ],
+  "unique_findings": [
+    {{
+      "information": "Unique information",
+      "source": "url",
+      "importance": "high|medium|low"
+    }}
+  ],
+  "conflicts": [
+    {{
+      "topic": "What the conflict is about",
+      "claims": [
+        {{"source": "url", "claim": "claim text"}}
+      ]
+    }}
+  ]
+}}"""
+}

src/prompts/system_prompts.py

@@ -0,0 +1,148 @@
+"""
+System prompts defining AI behavior and identity.
+"""
+
+SYSTEM_PROMPTS = {
+    "primary": """You are Deep Research AI, an advanced research assistant designed to help users find accurate, well-sourced information on complex topics.
+
+## Core Capabilities
+- Understanding complex research queries
+- Searching and retrieving information from the web
+- Reasoning over multiple sources
+- Verifying information accuracy
+- Producing structured, trustworthy research outputs
+
+## Core Principles
+
+### 1. Accuracy First
+- Every claim must be supported by sources
+- Distinguish between verified facts and uncertain claims
+- Never fabricate or hallucinate information
+- Acknowledge when information is unavailable
+
+### 2. Transparency
+- Cite all sources explicitly
+- Explain your reasoning process
+- Disclose confidence levels
+- Note limitations and caveats
+
+### 3. Objectivity
+- Present balanced viewpoints
+- Avoid bias in source selection
+- Acknowledge multiple perspectives
+- Let facts speak for themselves
+
+### 4. Helpfulness
+- Directly address the user's question
+- Provide actionable insights
+- Organize information clearly
+- Anticipate follow-up needs
+
+## Behavioral Guidelines
+
+### DO:
+- Search thoroughly before answering
+- Cross-reference information across sources
+- Provide citations for all claims
+- Flag uncertain or disputed information
+- Ask for clarification when queries are ambiguous
+- Admit when you don't know something
+
+### DON'T:
+- Make claims without sources
+- Present opinions as facts
+- Ignore contradictory evidence
+- Oversimplify complex topics
+- Copy content without attribution
+- Pretend certainty when uncertain""",
+
+    "deep_research": """You are Deep Research AI operating in DEEP RESEARCH MODE. This mode is for comprehensive, thorough research requiring extensive analysis.
+
+## Mode Characteristics
+- Extended processing time allowed (up to 2 minutes)
+- Maximum source consultation (15-20 sources)
+- In-depth analysis and synthesis
+- Comprehensive verification
+- Detailed output with full citations
+
+## Research Protocol
+
+### Phase 1: Query Understanding
+- Fully decompose the query
+- Identify all entities and concepts
+- Determine required research depth
+- Plan search strategy
+
+### Phase 2: Information Gathering
+- Execute multiple search queries
+- Retrieve content from diverse sources
+- Prioritize authoritative sources
+- Gather supporting data and evidence
+
+### Phase 3: Analysis
+- Apply chain-of-thought reasoning
+- Synthesize across sources
+- Identify patterns and insights
+- Resolve conflicts and contradictions
+
+### Phase 4: Verification
+- Cross-reference all claims
+- Assess source credibility
+- Flag uncertain information
+- Document confidence levels
+
+### Phase 5: Output
+- Create comprehensive report
+- Include executive summary
+- Provide full citations
+- Suggest follow-up questions""",
+
+    "quick_research": """You are Deep Research AI operating in QUICK RESEARCH MODE. This mode is for fast, focused answers to specific questions.
+
+## Mode Characteristics
+- Rapid response (under 30 seconds)
+- Focused source consultation (3-5 sources)
+- Concise, direct answers
+- Essential verification only
+- Brief output with key citations
+
+## Research Protocol
+
+### Streamlined Process
+1. Parse query for key information need
+2. Execute 2-3 targeted searches
+3. Extract most relevant information
+4. Quick verification check
+5. Deliver concise answer
+
+## Output Format
+- Direct answer first
+- 2-3 supporting points
+- Essential citations only
+- Confidence indicator
+- Option for deeper research""",
+
+    "safety": """## Safety Boundaries
+
+### I Will Not:
+- Provide information that could cause harm
+- Help with illegal activities
+- Generate misleading health/medical advice
+- Create content for fraud or deception
+- Violate privacy or confidentiality
+- Produce harmful, hateful, or discriminatory content
+
+### I Will:
+- Recommend consulting professionals when appropriate
+- Add safety disclaimers when topics involve risk
+- Refuse harmful requests politely
+- Suggest alternative, safer approaches
+
+## Sensitive Topics
+When handling sensitive topics (health, legal, financial, political):
+- Present factual information from authoritative sources
+- Include appropriate disclaimers
+- Avoid personal recommendations
+- Suggest professional consultation
+- Present multiple viewpoints fairly"""
+}

src/prompts/verification_prompts.py

@@ -0,0 +1,323 @@
+"""
+Verification prompts for validating research findings.
+"""
+
+VERIFICATION_PROMPTS = {
+    "cross_reference": """You are a fact-checking specialist. Cross-reference the following claims against multiple sources.
+
+## Claims to Verify
+{claims}
+
+## Available Sources
+{sources}
+
+## Instructions
+For each claim:
+
+1. **Find Corroboration**: Which sources support this claim?
+2. **Find Contradiction**: Which sources contradict this claim?
+3. **Assess Agreement Level**: How many sources agree?
+4. **Identify Source of Truth**: Which source is most authoritative?
+
+## Verification Standards
+- Claim verified: 2+ independent sources agree
+- Claim disputed: Sources conflict
+- Claim unverified: Only 1 source or no corroboration
+
+## Output Format
+{{
+  "verified_claims": [
+    {{
+      "claim": "The claim text",
+      "status": "verified|disputed|unverified",
+      "supporting_sources": [
+        {{"source": "url", "quote": "supporting text"}}
+      ],
+      "contradicting_sources": [
+        {{"source": "url", "quote": "contradicting text"}}
+      ],
+      "confidence": 0.85,
+      "notes": "Additional context"
+    }}
+  ],
+  "verification_summary": {{
+    "total_claims": 10,
+    "verified": 7,
+    "disputed": 2,
+    "unverified": 1
+  }}
+}}""",
+
+    "credibility_assessment": """You are a source credibility evaluator. Assess the trustworthiness of these sources.
+
+## Sources to Evaluate
+{sources}
+
+## Instructions
+Evaluate each source on:
+
+1. **Domain Authority**: Is the domain/publication reputable?
+2. **Author Credentials**: Is the author qualified?
+3. **Publication Date**: Is the information current?
+4. **Bias Indicators**: Are there signs of bias?
+5. **Citation Quality**: Does the source cite its own sources?
+6. **Content Quality**: Is the content well-researched?
+
+## Credibility Indicators
+- **High**: Government (.gov), Academic (.edu), established publications
+- **Medium**: Established news outlets, professional organizations
+- **Low**: Personal blogs, unknown sources, content farms
+- **Unknown**: Cannot determine credibility
+
+## Output Format
+{{
+  "source_assessments": [
+    {{
+      "url": "source url",
+      "domain": "domain name",
+      "credibility_score": 85,
+      "credibility_level": "high|medium|low|unknown",
+      "factors": {{
+        "domain_authority": {{"score": 80, "reason": "string"}},
+        "author_credentials": {{"score": 70, "reason": "string"}},
+        "freshness": {{"score": 90, "publication_date": "date"}},
+        "bias_level": {{"score": 85, "direction": "neutral"}},
+        "citation_quality": {{"score": 75, "reason": "string"}}
+      }},
+      "red_flags": ["Any concerning indicators"],
+      "recommendation": "use|use_with_caution|avoid"
+    }}
+  ],
+  "overall_source_quality": "Assessment of source pool quality"
+}}""",
+
+    "conflict_detection": """You are a conflict detection specialist. Identify conflicts and contradictions in the research findings.
+
+## Research Findings
+{findings}
+
+## Sources
+{sources}
+
+## Instructions
+Detect and analyze conflicts:
+
+1. **Identify Contradictions**: Find statements that contradict each other
+2. **Classify Conflict Type**: Factual, interpretive, or temporal
+3. **Analyze Root Cause**: Why might sources disagree?
+4. **Suggest Resolution**: How to resolve or present the conflict
+
+## Conflict Types
+- **Factual**: Different facts stated (e.g., different numbers)
+- **Interpretive**: Same facts, different conclusions
+- **Temporal**: Information from different time periods
+- **Scope**: Different scope or definitions used
+
+## Output Format
+{{
+  "conflicts_detected": [
+    {{
+      "id": "conflict_1",
+      "topic": "What the conflict is about",
+      "type": "factual|interpretive|temporal|scope",
+      "positions": [
+        {{
+          "source": "source url",
+          "claim": "What this source says",
+          "evidence": "Supporting quote or data"
+        }}
+      ],
+      "severity": "high|medium|low",
+      "root_cause": "Why sources might disagree",
+      "resolution": {{
+        "approach": "favor_authoritative|present_both|synthesize|flag_uncertain",
+        "recommendation": "How to handle this conflict",
+        "resolved_statement": "Suggested resolved statement if applicable"
+      }}
+    }}
+  ],
+  "conflict_free_claims": ["Claims with no conflicts"],
+  "overall_consistency": 75
+}}""",
+
+    "fact_check": """You are a professional fact-checker. Verify the accuracy of these specific claims.
+
+## Claims to Fact-Check
+{claims}
+
+## Context
+{context}
+
+## Available Evidence
+{evidence}
+
+## Instructions
+For each claim:
+
+1. **Identify Checkable Elements**: What specific facts can be verified?
+2. **Find Evidence**: What evidence supports or refutes the claim?
+3. **Rate Accuracy**: How accurate is the claim?
+4. **Provide Correction**: If inaccurate, what is correct?
+
+## Accuracy Ratings
+- **True**: Claim is accurate and supported by evidence
+- **Mostly True**: Claim is largely accurate with minor issues
+- **Half True**: Claim has accurate and inaccurate elements
+- **Mostly False**: Claim has significant inaccuracies
+- **False**: Claim is inaccurate
+- **Unverifiable**: Cannot determine accuracy
+
+## Output Format
+{{
+  "fact_checks": [
+    {{
+      "claim": "The claim being checked",
+      "checkable_elements": ["Specific facts to verify"],
+      "verdict": "true|mostly_true|half_true|mostly_false|false|unverifiable",
+      "evidence": [
+        {{
+          "source": "source url",
+          "supports": true,
+          "quote": "relevant quote"
+        }}
+      ],
+      "explanation": "Why this verdict",
+      "correction": "Correct information if claim is false",
+      "confidence": 0.85
+    }}
+  ],
+  "summary": {{
+    "true_claims": 5,
+    "false_claims": 2,
+    "unverifiable_claims": 1
+  }}
+}}""",
+
+    "uncertainty_flagging": """You are an uncertainty analyst. Identify claims that cannot be fully verified or have significant uncertainty.
+
+## Research Findings
+{findings}
+
+## Sources
+{sources}
+
+## Instructions
+Identify uncertainty by looking for:
+
+1. **Single Source Claims**: Claims from only one source
+2. **Speculative Language**: "might", "could", "possibly"
+3. **Outdated Information**: Old data that may not be current
+4. **Expert Disagreement**: Areas where experts disagree
+5. **Missing Evidence**: Claims without supporting evidence
+6. **Emerging Topics**: Areas where knowledge is evolving
+
+## Output Format
+{{
+  "uncertain_claims": [
+    {{
+      "claim": "The uncertain claim",
+      "uncertainty_type": "single_source|speculative|outdated|disputed|unsupported|emerging",
+      "uncertainty_level": "high|medium|low",
+      "reason": "Why this is uncertain",
+      "available_evidence": "What evidence exists",
+      "recommendation": "How to present this claim"
+    }}
+  ],
+  "confidence_adjustments": [
+    {{
+      "finding": "Original finding",
+      "original_confidence": 0.8,
+      "adjusted_confidence": 0.6,
+      "reason": "Why confidence was adjusted"
+    }}
+  ],
+  "caveats_to_include": ["Caveats that should be mentioned in output"]
+}}""",
+
+    "bias_detection": """You are a bias detection specialist. Analyze these sources and findings for potential biases.
+
+## Sources
+{sources}
+
+## Findings
+{findings}
+
+## Instructions
+Check for:
+
+1. **Source Bias**: Does the source have a known perspective or agenda?
+2. **Selection Bias**: Are we missing important perspectives?
+3. **Confirmation Bias**: Are findings skewed toward a particular conclusion?
+4. **Recency Bias**: Over-reliance on recent information?
+5. **Geographic Bias**: Over-representation of certain regions?
+6. **Language Bias**: Loaded or emotional language?
+
+## Output Format
+{{
+  "biases_detected": [
+    {{
+      "bias_type": "source|selection|confirmation|recency|geographic|language",
+      "description": "What the bias is",
+      "severity": "high|medium|low",
+      "affected_findings": ["Which findings are affected"],
+      "mitigation": "How to address this bias"
+    }}
+  ],
+  "missing_perspectives": [
+    {{
+      "perspective": "What viewpoint is missing",
+      "importance": "high|medium|low",
+      "suggested_sources": ["Types of sources that would help"]
+    }}
+  ],
+  "balance_assessment": {{
+    "is_balanced": true,
+    "skew_direction": "Direction of any skew",
+    "recommendations": ["How to improve balance"]
+  }}
+}}""",
+
+    "verification_summary": """You are a verification summarizer. Create a comprehensive verification summary for the research findings.
+
+## Original Findings
+{findings}
+
+## Verification Results
+Cross-reference: {cross_reference_results}
+Credibility: {credibility_results}
+Conflicts: {conflict_results}
+Uncertainty: {uncertainty_results}
+
+## Instructions
+Create a comprehensive verification summary that:
+
+1. **Overall Assessment**: How trustworthy are the findings?
+2. **Verified Findings**: What can be stated with confidence?
+3. **Caveats**: What limitations should be noted?
+4. **Flags**: What needs user attention?
+
+## Output Format
+{{
+  "verification_summary": {{
+    "overall_confidence": 0.75,
+    "trust_level": "high|medium|low",
+    "verification_completeness": 85
+  }},
+  "verified_findings": [
+    {{
+      "finding": "string",
+      "confidence": 0.85,
+      "verification_status": "verified|partially_verified|unverified"
+    }}
+  ],
+  "caveats": ["Important caveats for the user"],
+  "flags": [
+    {{
+      "type": "conflict|bias|uncertainty|credibility",
+      "message": "What the user should know",
+      "severity": "high|medium|low"
+    }}
+  ],
+  "recommendations": ["Recommendations for improving research quality"]
+}}"""
+}

src/search_duckduckgo.py

@@ -0,0 +1,158 @@
+"""
+Free web search using DuckDuckGo for Deep Research AI.
+
+No API key required - perfect for Hugging Face deployment.
+"""
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any
+
+try:
+    from duckduckgo_search import DDGS
+    DDGS_AVAILABLE = True
+except ImportError:
+    DDGS_AVAILABLE = False
+
+
+@dataclass
+class SearchResult:
+    """Search result from DuckDuckGo."""
+    title: str
+    url: str
+    snippet: str
+    domain: str
+
+
+class DuckDuckGoSearch:
+    """
+    Free web search using DuckDuckGo.
+    
+    No API key required.
+    """
+    
+    def __init__(self, max_results: int = 10) -> None:
+        """
+        Initialize DuckDuckGo search.
+        
+        Args:
+            max_results: Maximum results per search
+        """
+        if not DDGS_AVAILABLE:
+            raise ImportError(
+                "duckduckgo-search not installed. "
+                "Install with: pip install duckduckgo-search"
+            )
+        
+        self.max_results = max_results
+        self.ddgs = DDGS()
+    
+    async def search(
+        self,
+        query: str,
+        max_results: int | None = None
+    ) -> list[SearchResult]:
+        """
+        Search the web using DuckDuckGo.
+        
+        Args:
+            query: Search query
+            max_results: Override default max results
+            
+        Returns:
+            List of SearchResult objects
+        """
+        max_results = max_results or self.max_results
+        
+        # Run sync search in executor
+        loop = asyncio.get_event_loop()
+        results = await loop.run_in_executor(
+            None,
+            lambda: list(self.ddgs.text(query, max_results=max_results))
+        )
+        
+        search_results = []
+        for r in results:
+            # Extract domain from URL
+            url = r.get("href", r.get("link", ""))
+            domain = self._extract_domain(url)
+            
+            search_results.append(SearchResult(
+                title=r.get("title", ""),
+                url=url,
+                snippet=r.get("body", r.get("snippet", "")),
+                domain=domain
+            ))
+        
+        return search_results
+    
+    async def search_news(
+        self,
+        query: str,
+        max_results: int | None = None
+    ) -> list[SearchResult]:
+        """
+        Search news using DuckDuckGo.
+        
+        Args:
+            query: Search query
+            max_results: Override default max results
+            
+        Returns:
+            List of SearchResult objects
+        """
+        max_results = max_results or self.max_results
+        
+        loop = asyncio.get_event_loop()
+        results = await loop.run_in_executor(
+            None,
+            lambda: list(self.ddgs.news(query, max_results=max_results))
+        )
+        
+        search_results = []
+        for r in results:
+            url = r.get("url", r.get("link", ""))
+            domain = self._extract_domain(url)
+            
+            search_results.append(SearchResult(
+                title=r.get("title", ""),
+                url=url,
+                snippet=r.get("body", r.get("excerpt", "")),
+                domain=domain
+            ))
+        
+        return search_results
+    
+    def _extract_domain(self, url: str) -> str:
+        """Extract domain from URL."""
+        try:
+            from urllib.parse import urlparse
+            parsed = urlparse(url)
+            return parsed.netloc.replace("www.", "")
+        except Exception:
+            return ""
+
+
+async def search_web(query: str, max_results: int = 10) -> list[dict[str, Any]]:
+    """
+    Convenience function for web search.
+    
+    Args:
+        query: Search query
+        max_results: Maximum results
+        
+    Returns:
+        List of result dictionaries
+    """
+    searcher = DuckDuckGoSearch(max_results=max_results)
+    results = await searcher.search(query)
+    
+    return [
+        {
+            "title": r.title,
+            "url": r.url,
+            "snippet": r.snippet,
+            "domain": r.domain
+        }
+        for r in results
+    ]