enhance research mcp server to use more tools and refine output

app.py

@@ -2,6 +2,13 @@ import gradio as gr
 from ui.chat import build_app
 import subprocess, pathlib, time, os
 
+# Load .env file if present
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:
+    pass  # python-dotenv not installed
+
 def maybe_start_ideation_server():
     if os.environ.get("CELEBRATE_AI_IDEATION_ENDPOINT"):
         return  # using SSE/HTTP endpoint elsewhere

core/orchestrator.py

@@ -249,10 +249,13 @@ class MCPResearchClient:
     def available(self) -> bool:
         return bool(self._endpoint or self._command or DEFAULT_MCP_RESEARCH_COMMAND)
 
-    def generate(self, payload: RequestPayload) -> ResearchResponse:
-        return anyio.run(self._generate_async, payload)
+    def generate(self, payload: RequestPayload, idea_context: dict | None = None) -> ResearchResponse:
+        return anyio.run(lambda: self._generate_async(payload, idea_context))
 
-    async def _generate_async(self, payload: RequestPayload) -> ResearchResponse:
+    async def _generate_async(self, payload: RequestPayload, idea_context: dict | None = None) -> ResearchResponse:
+        # Build rich context for research agent
+        honoree = payload.celebration_profile.honoree_profile
+        
         arguments = {
             "payload": {
                 "session_id": payload.session_id,
@@ -261,6 +264,19 @@ class MCPResearchClient:
                 "location": payload.celebration_profile.location,
                 "budget_tier": payload.celebration_profile.budget_tier,
                 "constraints": payload.celebration_profile.constraints,
+                # New rich context fields
+                "occasion": payload.celebration_profile.occasion,
+                "event_date": payload.celebration_profile.date,
+                "honoree": {
+                    "age_range": honoree.age_range,
+                    "interests": honoree.interests,
+                    "preferences": honoree.preferences,
+                    "guest_count": honoree.guest_count,
+                },
+                # Pass full idea context if available
+                "idea": idea_context,
+                # Pass conversation history for context
+                "conversation_history": payload.interaction_context.history[-10:],  # Last 10 messages
             }
         }
 
@@ -340,12 +356,12 @@ class ResearchOrchestrator:
         )
         self._mock_provider = MockResearchProvider()
 
-    def generate_plan(self, payload_dict: Dict[str, Any]) -> ResearchResponse:
+    def generate_plan(self, payload_dict: Dict[str, Any], idea_context: dict | None = None) -> ResearchResponse:
         payload = RequestPayload.model_validate(payload_dict)
 
         if self._mcp_client.available:
             try:
-                return self._mcp_client.generate(payload)
+                return self._mcp_client.generate(payload, idea_context)
             except Exception as exc:
                 return self._mock_provider.generate(payload, reason=f"MCP research call failed: {exc}")
 

mcp_servers/research/config.py

@@ -1,9 +1,14 @@
 from pydantic_settings import BaseSettings
 
 class ResearchSettings(BaseSettings):
-    provider: str = "duckduckgo"
+    provider: str = "agent"
     max_items: int = 3
     search_safe: str = "moderate"  # strict/moderate/off
+    nebius_base_url: str | None = None
+    nebius_api_key: str | None = None
+    nebius_model: str = "meta-llama/llama-3.1-8b-instruct"
+    nebius_temperature: float = 0.6
+    max_tool_calls: int = 4
 
     class Config:
         env_prefix = "CELEBRATE_AI_RESEARCH_"

mcp_servers/research/provider.py

@@ -1,33 +1,1306 @@
+"""
+Research Agent Provider - ReAct-style agent for celebration planning research.
+
+This module implements a research agent that uses a ReAct (Reasoning + Acting) cycle
+to plan celebrations, search for products, generate invites, and create execution plans.
+"""
+
 from __future__ import annotations
 
+import json
 import logging
-import uuid
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import List
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urljoin, urlparse
+
+import httpx
+from bs4 import BeautifulSoup
 
 try:
     from ddgs import DDGS
-except Exception:  # pragma: no cover - optional dependency
-    DDGS = None  # type: ignore
+except Exception:
+    DDGS = None
 
 from .config import settings
-from .tool_schemas import PlanItem, ResearchRequest, ResearchResponse
+from .tool_schemas import (
+    PlanItem, ResearchRequest, ResearchResponse,
+    SourceLink, ShoppingItem, IdeaContext
+)
 
 logger = logging.getLogger(__name__)
 
 
+# =============================================================================
+# Tool Infrastructure
+# =============================================================================
+
+@dataclass
+class ToolResult:
+    """Result from a tool execution."""
+    success: bool
+    data: Dict[str, Any] = field(default_factory=dict)
+    error: Optional[str] = None
+
+
+class BaseTool(ABC):
+    """Base class for all research tools."""
+    
+    name: str
+    description: str
+    
+    @abstractmethod
+    def execute(self, **kwargs) -> ToolResult:
+        """Execute the tool with given parameters."""
+        pass
+    
+    def get_schema(self) -> Dict[str, Any]:
+        """Return JSON schema for tool parameters."""
+        return {}
+
+
+class WebSearchTool(BaseTool):
+    """Search the web using DuckDuckGo."""
+    
+    name = "web_search"
+    description = (
+        "Search the web for information about celebration planning, venues, activities, "
+        "decorations, food ideas, or any general information. Returns search results with "
+        "titles, snippets, and URLs."
+    )
+    
+    # Domains to filter out as they rarely have relevant party planning content
+    IRRELEVANT_DOMAINS = [
+        "microsoft.com", "apple.com", "support.", "answers.microsoft",
+        "stackoverflow.com", "github.com", "gitlab.com", "bitbucket.org",
+        "techsupport", "forum.nvidia", "developer.mozilla",
+    ]
+    
+    # URL patterns that indicate ads or tracking (not actual content)
+    AD_TRACKING_PATTERNS = [
+        "/aclick?", "/adclick?", "doubleclick.", "googleadservices.",
+        "go.redirectingat.", "tracking.", "click.linksynergy.",
+        "bing.com/aclick", "r.search.yahoo.com/cbclk",
+    ]
+    
+    def __init__(self, max_results: int = 5, safe: str = "moderate"):
+        self.max_results = max_results
+        self.safe = safe
+        if DDGS is None:
+            raise RuntimeError("ddgs (DuckDuckGo search) is not installed")
+    
+    def _is_relevant_result(self, url: str, title: str, snippet: str) -> bool:
+        """Check if a search result is likely relevant to party planning."""
+        url_lower = url.lower()
+        
+        # Filter out known irrelevant domains
+        for domain in self.IRRELEVANT_DOMAINS:
+            if domain in url_lower:
+                return False
+        
+        # Filter out ad/tracking URLs
+        for pattern in self.AD_TRACKING_PATTERNS:
+            if pattern in url_lower:
+                return False
+        
+        # Check for relevance indicators
+        combined = (title + " " + snippet).lower()
+        relevant_keywords = [
+            "party", "celebration", "ideas", "decor", "activity", "game",
+            "host", "plan", "diy", "craft", "food", "drink", "theme",
+            "birthday", "event", "invite", "guest", "fun", "entertainment",
+        ]
+        
+        # At least one relevant keyword should be present
+        return any(kw in combined for kw in relevant_keywords)
+    
+    def execute(self, query: str, **kwargs) -> ToolResult:
+        """Execute web search."""
+        if not query or not query.strip():
+            return ToolResult(success=False, error="Query cannot be empty")
+        
+        try:
+            results = []
+            # Request more results than needed to allow for filtering
+            with DDGS() as ddgs:
+                search_results = ddgs.text(
+                    query.strip(),
+                    safesearch=self.safe,
+                    max_results=self.max_results * 3
+                )
+                for item in search_results or []:
+                    url = item.get("href", "")
+                    title = item.get("title", "")
+                    snippet = item.get("body", "")
+                    
+                    # Filter for relevance
+                    if self._is_relevant_result(url, title, snippet):
+                        results.append({
+                            "title": title,
+                            "snippet": snippet,
+                            "url": url,
+                        })
+                        
+                        if len(results) >= self.max_results:
+                            break
+            
+            return ToolResult(
+                success=True,
+                data={"query": query, "results": results, "count": len(results)}
+            )
+        except Exception as exc:
+            logger.error("Web search failed: %s", exc)
+            return ToolResult(success=False, error=str(exc))
+    
+    def get_schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search query for finding information"
+                }
+            },
+            "required": ["query"]
+        }
+
+
+class PageVisitorTool(BaseTool):
+    """Visit a web page and extract its content."""
+    
+    name = "visit_page"
+    description = (
+        "Visit a webpage URL and extract its main text content. Use this to get detailed "
+        "information from a search result. Returns the page title, description, and main text."
+    )
+    
+    def __init__(self, timeout: int = 15):
+        self.timeout = timeout
+        self._client = httpx.Client(
+            timeout=timeout,
+            follow_redirects=True,
+            headers={
+                "User-Agent": (
+                    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+                    "(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+                )
+            }
+        )
+    
+    def execute(self, url: str, **kwargs) -> ToolResult:
+        """Visit a page and extract content."""
+        if not url or not url.strip():
+            return ToolResult(success=False, error="URL cannot be empty")
+        
+        try:
+            response = self._client.get(url.strip())
+            response.raise_for_status()
+            
+            soup = BeautifulSoup(response.text, "html.parser")
+            
+            # Remove script and style elements
+            for element in soup(["script", "style", "nav", "footer", "header", "aside"]):
+                element.decompose()
+            
+            # Extract title
+            title = ""
+            title_tag = soup.find("title")
+            if title_tag:
+                title = title_tag.get_text(strip=True)
+            
+            # Extract description
+            description = ""
+            meta_desc = soup.find("meta", attrs={"name": "description"})
+            if meta_desc:
+                description = meta_desc.get("content", "")
+            
+            # Extract main text content
+            text_parts = []
+            for tag in soup.find_all(["h1", "h2", "h3", "p", "li"]):
+                text = tag.get_text(strip=True)
+                if text and len(text) > 20:
+                    text_parts.append(text)
+            
+            # Limit content length
+            content = "\n".join(text_parts[:30])
+            if len(content) > 3000:
+                content = content[:3000] + "..."
+            
+            return ToolResult(
+                success=True,
+                data={
+                    "url": url,
+                    "title": title,
+                    "description": description,
+                    "content": content,
+                }
+            )
+        except Exception as exc:
+            logger.error("Page visit failed for %s: %s", url, exc)
+            return ToolResult(success=False, error=f"Failed to fetch page: {str(exc)}")
+    
+    def get_schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "url": {
+                    "type": "string",
+                    "description": "URL of the webpage to visit"
+                }
+            },
+            "required": ["url"]
+        }
+
+
+class AmazonSearchTool(BaseTool):
+    """Search for products on Amazon."""
+    
+    name = "amazon_search"
+    description = (
+        "Search for products on Amazon. Use this for finding gifts, party supplies, "
+        "decorations, balloons, banners, cakes, or any items to buy for the celebration."
+    )
+    
+    # Patterns that indicate a product page vs search/category page
+    PRODUCT_URL_PATTERNS = ["/dp/", "/gp/product/", "/gp/aw/d/"]
+    
+    def __init__(self, max_results: int = 5, safe: str = "moderate"):
+        self.max_results = max_results
+        self.safe = safe
+        if DDGS is None:
+            raise RuntimeError("ddgs is not installed")
+    
+    def _is_product_url(self, url: str) -> bool:
+        """Check if URL is an actual product page, not a search or category page."""
+        url_lower = url.lower()
+        # Must be Amazon domain
+        if "amazon" not in url_lower:
+            return False
+        # Check for product URL patterns
+        return any(pattern in url_lower for pattern in self.PRODUCT_URL_PATTERNS)
+    
+    def _is_search_or_category_url(self, url: str) -> bool:
+        """Check if URL is a search or category page."""
+        url_lower = url.lower()
+        search_patterns = ["/s?", "/s/", "/b?", "/b/", "node=", "keywords="]
+        return any(pattern in url_lower for pattern in search_patterns)
+    
+    def execute(self, query: str, **kwargs) -> ToolResult:
+        """Search Amazon via DuckDuckGo site search."""
+        if not query or not query.strip():
+            return ToolResult(success=False, error="Query cannot be empty")
+        
+        try:
+            # Search for specific products
+            search_query = f"site:amazon.com OR site:amazon.in {query.strip()}"
+            results = []
+            product_results = []
+            category_results = []
+            
+            with DDGS() as ddgs:
+                # Request more results to filter for product pages
+                search_results = ddgs.text(
+                    search_query,
+                    safesearch=self.safe,
+                    max_results=self.max_results * 4  # Get more to filter
+                )
+                for item in search_results or []:
+                    href = item.get("href", "")
+                    if "amazon" in href.lower():
+                        # Extract price if present in snippet or title
+                        snippet = item.get("body", "")
+                        title = item.get("title", "")
+                        price = self._extract_price(title + " " + snippet)
+                        
+                        product_info = {
+                            "title": title,
+                            "snippet": snippet,
+                            "url": href,
+                            "price": price,
+                        }
+                        
+                        # Prioritize actual product pages over search/category pages
+                        if self._is_product_url(href):
+                            product_results.append(product_info)
+                        elif not self._is_search_or_category_url(href):
+                            category_results.append(product_info)
+            
+            # Prefer product pages, then category pages
+            results = product_results[:self.max_results]
+            if len(results) < self.max_results:
+                results.extend(category_results[:self.max_results - len(results)])
+            
+            return ToolResult(
+                success=True,
+                data={"query": query, "products": results, "count": len(results)}
+            )
+        except Exception as exc:
+            logger.error("Amazon search failed: %s", exc)
+            return ToolResult(success=False, error=str(exc))
+    
+    def _extract_price(self, text: str) -> Optional[str]:
+        """Extract price from text."""
+        patterns = [
+            r'₹\s*[\d,]+(?:\.\d{2})?',
+            r'\$\s*[\d,]+(?:\.\d{2})?',
+            r'Rs\.?\s*[\d,]+(?:\.\d{2})?',
+        ]
+        for pattern in patterns:
+            match = re.search(pattern, text)
+            if match:
+                return match.group(0)
+        return None
+    
+    def get_schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Product search query (e.g., 'birthday decorations', 'party balloons')"
+                }
+            },
+            "required": ["query"]
+        }
+
+
+class MessageGeneratorTool(BaseTool):
+    """Generate invitation messages, birthday wishes, or greeting cards."""
+    
+    name = "generate_message"
+    description = (
+        "Generate personalized messages like party invitations, birthday wishes, "
+        "thank you notes, or greeting card content. Provide the occasion, recipient, "
+        "and any specific details to include."
+    )
+    
+    def __init__(self, llm_client: Optional[httpx.Client] = None):
+        self._client = llm_client or httpx.Client(timeout=60)
+    
+    def execute(
+        self,
+        occasion: str,
+        recipient: str = "Guest",
+        tone: str = "warm and friendly",
+        details: str = "",
+        **kwargs
+    ) -> ToolResult:
+        """Generate a message using LLM or templates."""
+        if not occasion:
+            return ToolResult(success=False, error="Occasion is required")
+        
+        # Try LLM generation first
+        if settings.nebius_base_url and settings.nebius_api_key:
+            try:
+                message = self._generate_with_llm(occasion, recipient, tone, details)
+                if message:
+                    return ToolResult(
+                        success=True,
+                        data={
+                            "message": message,
+                            "occasion": occasion,
+                            "recipient": recipient,
+                            "generated_by": "llm"
+                        }
+                    )
+            except Exception as exc:
+                logger.error("LLM message generation failed: %s", exc)
+        
+        # Fallback to template-based generation
+        message = self._generate_template_message(occasion, recipient, tone, details)
+        return ToolResult(
+            success=True,
+            data={
+                "message": message,
+                "occasion": occasion,
+                "recipient": recipient,
+                "generated_by": "template"
+            }
+        )
+    
+    def _generate_with_llm(
+        self, occasion: str, recipient: str, tone: str, details: str
+    ) -> Optional[str]:
+        """Generate message using LLM."""
+        system_prompt = (
+            "You are a creative writer specializing in celebration messages. "
+            "Write warm, engaging messages that are personal and memorable. "
+            "Keep messages concise (60-100 words) but heartfelt."
+        )
+        user_prompt = (
+            f"Write a {tone} message for a {occasion}.\n"
+            f"Recipient: {recipient}\n"
+            f"Additional details: {details or 'None'}\n"
+            "Write only the message, no explanations."
+        )
+        
+        body = {
+            "model": settings.nebius_model,
+            "temperature": settings.nebius_temperature,
+            "messages": [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+        }
+        
+        resp = self._client.post(
+            f"{settings.nebius_base_url.rstrip('/')}/chat/completions",
+            headers={
+                "Authorization": f"Bearer {settings.nebius_api_key}",
+                "Content-Type": "application/json",
+            },
+            json=body,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return data["choices"][0]["message"]["content"]
+    
+    def _generate_template_message(
+        self, occasion: str, recipient: str, tone: str, details: str
+    ) -> str:
+        """Generate message using templates."""
+        templates = {
+            "birthday": [
+                f"🎂 Happy Birthday, {recipient}! 🎉\n\nWishing you a day filled with joy, laughter, and all your favorite things. May this year bring you endless happiness and amazing adventures!\n\nCheers to you! 🥳",
+                f"🎈 Happy Birthday, {recipient}!\n\nAnother year older, another year wiser, and definitely another year more awesome! Hope your special day is as wonderful as you are.\n\nEnjoy your day! 🎁",
+            ],
+            "party invitation": [
+                f"🎉 You're Invited!\n\nHey {recipient}!\n\nWe're throwing a celebration and it wouldn't be the same without you! Join us for an unforgettable time.\n\n{details if details else 'Details to follow!'}\n\nHope to see you there! 🥳",
+            ],
+            "thank you": [
+                f"Dear {recipient},\n\nThank you so much for being part of our celebration! Your presence made the day even more special.\n\nWith gratitude,\n❤️",
+            ],
+        }
+        
+        occasion_lower = occasion.lower()
+        for key, msgs in templates.items():
+            if key in occasion_lower:
+                return msgs[0]
+        
+        # Default template
+        return (
+            f"Dear {recipient},\n\n"
+            f"You're invited to celebrate with us! "
+            f"{'Details: ' + details if details else 'More details coming soon.'}\n\n"
+            f"Looking forward to seeing you!\n🎉"
+        )
+    
+    def get_schema(self) -> Dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "occasion": {
+                    "type": "string",
+                    "description": "Type of occasion (birthday, party invitation, thank you, etc.)"
+                },
+                "recipient": {
+                    "type": "string",
+                    "description": "Name of the recipient"
+                },
+                "tone": {
+                    "type": "string",
+                    "description": "Tone of the message (warm, formal, funny, casual)"
+                },
+                "details": {
+                    "type": "string",
+                    "description": "Additional details to include (date, time, venue, etc.)"
+                }
+            },
+            "required": ["occasion"]
+        }
+
+
+# =============================================================================
+# Agent State and ReAct Implementation
+# =============================================================================
+
+@dataclass
+class AgentState:
+    """State maintained during agent execution."""
+    idea: str  # The idea title
+    context: Dict[str, Any]  # location, budget, constraints, etc.
+    
+    # Full idea details from ideation (summary, highlights, next_steps, etc.)
+    idea_details: Optional[Dict[str, Any]] = None
+    
+    # User profile and preferences
+    honoree: Optional[Dict[str, Any]] = None
+    occasion: Optional[str] = None
+    
+    messages: List[Dict[str, str]] = field(default_factory=list)
+    tool_results: List[Dict[str, Any]] = field(default_factory=list)
+    iteration: int = 0
+    max_iterations: int = 5
+    final_response: Optional[str] = None
+
+
+class ReActResearchAgent:
+    """
+    ReAct-style research agent for celebration planning.
+    
+    Uses a Reasoning + Acting cycle:
+    1. Reason about what information is needed
+    2. Select and execute appropriate tools
+    3. Observe results and reason about next steps
+    4. Repeat until sufficient information gathered
+    5. Synthesize final response
+    """
+    
+    def __init__(self):
+        self.tools: Dict[str, BaseTool] = {}
+        self._httpx_client = httpx.Client(timeout=60)
+        self._initialize_tools()
+    
+    def _initialize_tools(self):
+        """Initialize available tools."""
+        try:
+            self.tools["web_search"] = WebSearchTool(
+                max_results=settings.max_items,
+                safe=settings.search_safe
+            )
+        except Exception as exc:
+            logger.warning("WebSearchTool initialization failed: %s", exc)
+        
+        try:
+            self.tools["visit_page"] = PageVisitorTool()
+        except Exception as exc:
+            logger.warning("PageVisitorTool initialization failed: %s", exc)
+        
+        try:
+            self.tools["amazon_search"] = AmazonSearchTool(
+                max_results=settings.max_items,
+                safe=settings.search_safe
+            )
+        except Exception as exc:
+            logger.warning("AmazonSearchTool initialization failed: %s", exc)
+        
+        self.tools["generate_message"] = MessageGeneratorTool(self._httpx_client)
+        
+        logger.info("Initialized %d tools: %s", len(self.tools), list(self.tools.keys()))
+    
+    def _get_tools_description(self) -> str:
+        """Get formatted description of all available tools."""
+        lines = []
+        for name, tool in self.tools.items():
+            schema = tool.get_schema()
+            params = schema.get("properties", {})
+            param_str = ", ".join(
+                f"{k}: {v.get('description', 'no description')}"
+                for k, v in params.items()
+            )
+            lines.append(f"- {name}: {tool.description}\n  Parameters: {param_str}")
+        return "\n".join(lines)
+    
+    def _parse_idea_from_message(self, message: str) -> Tuple[str, str]:
+        """
+        Extract the celebration idea and additional context from user message.
+        
+        Handles formats like:
+        - "Plan this idea in detail: At-Home Studio Night. Additional context: ..."
+        - Direct idea names
+        """
+        idea = message
+        context = ""
+        
+        # Pattern 1: "Plan this idea in detail: X. Additional context: Y"
+        if "Plan this idea in detail:" in message:
+            try:
+                parts = message.split("Plan this idea in detail:")
+                if len(parts) > 1:
+                    after_plan = parts[1]
+                    if "Additional context:" in after_plan:
+                        idea_parts = after_plan.split("Additional context:")
+                        idea = idea_parts[0].strip().rstrip(".")
+                        context = idea_parts[1].strip() if len(idea_parts) > 1 else ""
+                    else:
+                        idea = after_plan.strip().rstrip(".")
+            except Exception:
+                pass
+        
+        # Clean up the idea
+        idea = idea.strip()
+        if not idea:
+            idea = message[:100]  # Fallback to first 100 chars
+        
+        return idea, context
+    
+    def _call_llm(self, messages: List[Dict[str, str]]) -> Optional[str]:
+        """Call LLM API for reasoning."""
+        if not settings.nebius_base_url or not settings.nebius_api_key:
+            return None
+        
+        try:
+            body = {
+                "model": settings.nebius_model,
+                "temperature": settings.nebius_temperature,
+                "messages": messages,
+            }
+            
+            resp = self._httpx_client.post(
+                f"{settings.nebius_base_url.rstrip('/')}/chat/completions",
+                headers={
+                    "Authorization": f"Bearer {settings.nebius_api_key}",
+                    "Content-Type": "application/json",
+                },
+                json=body,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            return data["choices"][0]["message"]["content"]
+        except Exception as exc:
+            logger.error("LLM call failed: %s", exc)
+            return None
+    
+    def _plan_tool_calls(self, state: AgentState) -> List[Dict[str, Any]]:
+        """
+        Use LLM to plan which tools to call, or use heuristics as fallback.
+        
+        Returns list of tool calls like:
+        [{"tool": "web_search", "params": {"query": "..."}}]
+        """
+        # Build system prompt
+        system_prompt = f"""You are a celebration planning research assistant. Your task is to help plan "{state.idea}".
+
+Available tools:
+{self._get_tools_description()}
+
+Based on what you know so far, decide which tools to use to gather information.
+Return a JSON object with "calls" array containing tool calls.
+
+Example response:
+{{"calls": [
+    {{"tool": "web_search", "params": {{"query": "birthday party at home ideas activities"}}}},
+    {{"tool": "amazon_search", "params": {{"query": "birthday party decorations supplies"}}}}
+]}}
+
+Keep queries specific and relevant to the celebration idea.
+Maximum 3 tool calls per response."""
+
+        # Build user prompt with context
+        user_content = f"Celebration idea: {state.idea}\n"
+        if state.context:
+            user_content += f"Additional context: {json.dumps(state.context)}\n"
+        
+        if state.tool_results:
+            user_content += "\nPrevious tool results summary:\n"
+            for result in state.tool_results[-3:]:  # Last 3 results
+                user_content += f"- {result.get('tool')}: {result.get('summary', 'completed')}\n"
+        
+        user_content += "\nWhat tools should we use next to gather useful information?"
+        
+        # Try LLM planning
+        llm_response = self._call_llm([
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content},
+        ])
+        
+        if llm_response:
+            try:
+                # Try to parse JSON from response
+                # Handle markdown code blocks
+                json_match = re.search(r'\{[\s\S]*\}', llm_response)
+                if json_match:
+                    parsed = json.loads(json_match.group())
+                    calls = parsed.get("calls", [])
+                    if calls:
+                        return calls[:3]  # Limit to 3 calls
+            except Exception as exc:
+                logger.warning("Failed to parse LLM tool planning response: %s", exc)
+        
+        # Fallback: Use heuristics based on the idea
+        return self._heuristic_tool_planning(state)
+    
+    def _heuristic_tool_planning(self, state: AgentState) -> List[Dict[str, Any]]:
+        """Fallback heuristic-based tool planning when LLM is unavailable."""
+        idea_lower = state.idea.lower()
+        calls = []
+        
+        # Extract additional context from idea details if available
+        idea_summary = ""
+        idea_highlights = []
+        if state.idea_details:
+            idea_summary = state.idea_details.get("summary", "")
+            idea_highlights = state.idea_details.get("highlights", [])
+        
+        # Get interests from honoree if available
+        interests = []
+        if state.honoree:
+            interests = state.honoree.get("interests", [])
+        
+        # First iteration: Do multiple targeted searches
+        if state.iteration == 0:
+            # Build a more specific search query using full context
+            idea_themes = self._extract_themes_from_idea(state.idea)
+            
+            # Build search query with idea summary context
+            search_context = state.idea
+            if idea_summary:
+                # Extract key action words from summary
+                search_context = f"{state.idea} {idea_summary[:100]}"
+            
+            # Web search for party/celebration ideas with better keywords
+            calls.append({
+                "tool": "web_search",
+                "params": {"query": f"how to plan {state.idea} party ideas activities guide"}
+            })
+            
+            # Search for specific supplies based on highlights
+            amazon_terms = [idea_themes]
+            if idea_highlights:
+                # Extract shopping-related terms from highlights
+                for highlight in idea_highlights[:2]:
+                    highlight_lower = highlight.lower()
+                    if any(word in highlight_lower for word in ["station", "kit", "supplies", "decor", "activity"]):
+                        amazon_terms.append(highlight[:30])
+            
+            amazon_query = " ".join(amazon_terms[:3]) + " party supplies"
+            calls.append({
+                "tool": "amazon_search",
+                "params": {"query": amazon_query}
+            })
+            
+            # Generate invitation message with more context
+            invite_details = []
+            if state.context.get("location"):
+                invite_details.append(f"Location: {state.context['location']}")
+            if state.context.get("event_date"):
+                invite_details.append(f"Date: {state.context['event_date']}")
+            if state.occasion:
+                invite_details.append(f"Occasion: {state.occasion}")
+            
+            calls.append({
+                "tool": "generate_message",
+                "params": {
+                    "occasion": f"{state.occasion or 'party'} invitation for {state.idea}",
+                    "recipient": "Guest",
+                    "tone": "fun and exciting",
+                    "details": ". ".join(invite_details) if invite_details else "at my place"
+                }
+            })
+        
+        # Second iteration: Do more specific searches based on first results
+        elif state.iteration == 1:
+            # Do a second, more specific search
+            calls.append({
+                "tool": "web_search",
+                "params": {"query": f"{state.idea} step by step planning checklist timeline"}
+            })
+            
+            # Check if we have relevant URLs to visit from previous searches
+            for result in state.tool_results:
+                if result.get("tool") == "web_search" and result.get("success"):
+                    data = result.get("data", {})
+                    results = data.get("results", [])
+                    # Visit pages that look relevant (filter out obvious junk)
+                    for r in results[:3]:
+                        url = r.get("url", "")
+                        title = r.get("title", "").lower()
+                        url_lower = url.lower()
+                        
+                        # Skip irrelevant domains and tracking URLs
+                        skip_patterns = [
+                            "microsoft.com", "apple.com", "support.", "answers.", 
+                            "forum.", "stackoverflow", "github.com",
+                            "/aclick?", "/adclick?", "doubleclick.", "tracking.",
+                            "bing.com/aclick", "amazon.com/s?", "amazon.in/s?",
+                        ]
+                        if url and not any(p in url_lower for p in skip_patterns):
+                            # Check if title seems relevant
+                            relevant_keywords = ["party", "celebration", "ideas", "how to", 
+                                                "guide", "tips", "plan", "host", "decor",
+                                                "activity", "game", "diy", "craft"]
+                            if any(kw in title for kw in relevant_keywords):
+                                calls.append({
+                                    "tool": "visit_page",
+                                    "params": {"url": url}
+                                })
+                                break
+        
+        return calls[:3]
+    
+    def _extract_themes_from_idea(self, idea: str) -> str:
+        """Extract key themes from the idea for better search queries."""
+        idea_lower = idea.lower()
+        
+        # Map common celebration types to search themes
+        theme_mappings = {
+            "studio": "art craft painting",
+            "art": "art craft painting canvas",
+            "paint": "painting art canvas",
+            "movie": "movie night cinema film",
+            "game": "gaming video games board games",
+            "spa": "spa relaxation wellness",
+            "picnic": "outdoor picnic garden",
+            "bbq": "barbecue grill outdoor",
+            "karaoke": "karaoke music singing",
+            "dance": "dance music disco",
+            "birthday": "birthday celebration",
+            "anniversary": "anniversary romantic",
+            "graduation": "graduation celebration",
+            "baby shower": "baby shower celebration",
+            "bridal": "bridal shower wedding",
+            "cocktail": "cocktail drinks mixology",
+            "dinner": "dinner party elegant",
+            "brunch": "brunch morning",
+            "tea": "tea party afternoon",
+            "sports": "sports game viewing",
+            "trivia": "trivia quiz game night",
+        }
+        
+        themes = []
+        for keyword, theme in theme_mappings.items():
+            if keyword in idea_lower:
+                themes.append(theme)
+        
+        if themes:
+            return " ".join(themes[:2])
+        
+        # Default to the idea itself cleaned up
+        return idea
+    
+    def _execute_tool(self, tool_name: str, params: Dict[str, Any]) -> ToolResult:
+        """Execute a single tool."""
+        tool = self.tools.get(tool_name)
+        if not tool:
+            return ToolResult(success=False, error=f"Unknown tool: {tool_name}")
+        
+        try:
+            return tool.execute(**params)
+        except Exception as exc:
+            logger.error("Tool %s execution failed: %s", tool_name, exc)
+            return ToolResult(success=False, error=str(exc))
+    
+    def _synthesize_response(self, state: AgentState) -> str:
+        """
+        Synthesize a final user-friendly response from all gathered information.
+        Uses LLM if available, otherwise uses template-based synthesis.
+        """
+        # Build context from tool results
+        context_parts = []
+        web_results = []
+        products = []
+        messages = []
+        page_contents = []
+        
+        for result in state.tool_results:
+            tool = result.get("tool")
+            data = result.get("data", {})
+            
+            if tool == "web_search" and data.get("results"):
+                for r in data["results"]:
+                    web_results.append({
+                        "title": r.get("title", ""),
+                        "snippet": r.get("snippet", ""),
+                        "url": r.get("url", "")
+                    })
+            elif tool == "amazon_search" and data.get("products"):
+                products.extend(data["products"])
+            elif tool == "generate_message" and data.get("message"):
+                messages.append(data["message"])
+            elif tool == "visit_page" and data.get("content"):
+                page_contents.append({
+                    "title": data.get("title", ""),
+                    "content": data.get("content", "")[:500]
+                })
+        
+        # Try LLM synthesis
+        if settings.nebius_base_url and settings.nebius_api_key:
+            synthesis_result = self._llm_synthesize(state, web_results, products, messages, page_contents)
+            if synthesis_result:
+                return synthesis_result
+        
+        # Fallback to template-based synthesis
+        return self._template_synthesize(state, web_results, products, messages, page_contents)
+    
+    def _llm_synthesize(
+        self,
+        state: AgentState,
+        web_results: List[Dict],
+        products: List[Dict],
+        messages: List[str],
+        page_contents: List[Dict]
+    ) -> Optional[str]:
+        """Use LLM to synthesize a comprehensive response."""
+        system_prompt = """You are a celebration planning assistant. Based on the research gathered, 
+create a comprehensive, actionable plan for the user.
+
+Structure your response as:
+1. **Overview** - Brief summary of the celebration idea
+2. **Key Activities** - 3-5 suggested activities with details
+3. **Shopping List** - Items to buy with links if available
+4. **Timeline** - Suggested schedule for preparation and event day
+5. **Sample Invitation** - If applicable
+6. **Tips** - 2-3 practical tips
+
+Be specific, practical, and enthusiastic!"""
+
+        user_content = f"Celebration idea: {state.idea}\n\n"
+        
+        if web_results:
+            user_content += "Research findings:\n"
+            for r in web_results[:5]:
+                user_content += f"- {r['title']}: {r['snippet'][:200]}\n"
+        
+        if page_contents:
+            user_content += "\nDetailed information from visited pages:\n"
+            for p in page_contents[:2]:
+                user_content += f"- {p['title']}: {p['content'][:300]}...\n"
+        
+        if products:
+            user_content += "\nRecommended products:\n"
+            for p in products[:5]:
+                user_content += f"- {p['title'][:80]}: {p.get('price', 'Check price')} - {p['url']}\n"
+        
+        if messages:
+            user_content += f"\nSample message/invitation:\n{messages[0][:300]}\n"
+        
+        user_content += "\nPlease create a comprehensive celebration plan based on this information."
+        
+        return self._call_llm([
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_content},
+        ])
+    
+    def _template_synthesize(
+        self,
+        state: AgentState,
+        web_results: List[Dict],
+        products: List[Dict],
+        messages: List[str],
+        page_contents: List[Dict]
+    ) -> str:
+        """Template-based response synthesis when LLM is unavailable."""
+        parts = []
+        
+        # Header
+        parts.append(f"# 🎉 Celebration Plan: {state.idea}\n")
+        
+        # Overview from page content or web results
+        if page_contents:
+            parts.append("## Overview\n")
+            parts.append(page_contents[0].get("content", "")[:500] + "\n")
+        elif web_results:
+            parts.append("## Key Insights\n")
+            for r in web_results[:3]:
+                if r.get("snippet"):
+                    parts.append(f"- {r['snippet'][:150]}\n")
+        
+        # Suggested activities
+        parts.append("\n## Suggested Activities\n")
+        activity_suggestions = [
+            "Set up a themed decoration area",
+            "Plan interactive games or activities",
+            "Prepare a special playlist",
+            "Arrange for food and refreshments",
+            "Create a photo booth corner"
+        ]
+        for i, activity in enumerate(activity_suggestions, 1):
+            parts.append(f"{i}. {activity}\n")
+        
+        # Shopping list with products
+        if products:
+            parts.append("\n## Shopping List\n")
+            for p in products[:5]:
+                price = p.get("price", "Check price")
+                parts.append(f"- [{p['title'][:60]}]({p['url']}) - {price}\n")
+        
+        # Sample invitation
+        if messages:
+            parts.append("\n## Sample Invitation\n")
+            parts.append(f"```\n{messages[0]}\n```\n")
+        
+        # Reference links
+        if web_results:
+            parts.append("\n## Helpful Resources\n")
+            for r in web_results[:3]:
+                if r.get("url"):
+                    parts.append(f"- [{r['title'][:50]}]({r['url']})\n")
+        
+        # Tips
+        parts.append("\n## Tips\n")
+        parts.append("- Start preparations at least a week in advance\n")
+        parts.append("- Create a checklist to track tasks\n")
+        parts.append("- Don't forget to enjoy the celebration yourself!\n")
+        
+        return "".join(parts)
+    
+    def run(self, payload: ResearchRequest) -> ResearchResponse:
+        """
+        Execute the ReAct agent loop.
+        
+        1. Parse the idea from the request
+        2. Plan tool calls (using LLM or heuristics)
+        3. Execute tools
+        4. Check if more information needed
+        5. Synthesize final response
+        """
+        # Parse the idea - use idea context if available, otherwise parse from message
+        if payload.idea and payload.idea.title:
+            idea = payload.idea.title
+            idea_details = {
+                "title": payload.idea.title,
+                "summary": payload.idea.summary,
+                "highlights": payload.idea.highlights,
+                "estimated_budget": payload.idea.estimated_budget,
+                "effort": payload.idea.effort,
+                "next_steps": payload.idea.next_steps,
+                "persona_fit": payload.idea.persona_fit,
+            }
+            additional_context = ""
+        else:
+            idea, additional_context = self._parse_idea_from_message(
+                payload.user_message or payload.topic or ""
+            )
+            idea_details = None
+        
+        logger.info("Research agent starting for idea: %s", idea)
+        if idea_details:
+            logger.info("Full idea context available: %s", idea_details.get("summary", "")[:100])
+        
+        # Extract honoree info if available
+        honoree_info = None
+        if payload.honoree:
+            honoree_info = {
+                "age_range": payload.honoree.age_range,
+                "interests": payload.honoree.interests,
+                "preferences": payload.honoree.preferences,
+                "guest_count": payload.honoree.guest_count,
+            }
+        
+        # Initialize state with full context
+        state = AgentState(
+            idea=idea,
+            context={
+                "location": payload.location,
+                "budget_tier": payload.budget_tier,
+                "constraints": payload.constraints,
+                "additional": additional_context,
+                "event_date": payload.event_date,
+            },
+            idea_details=idea_details,
+            honoree=honoree_info,
+            occasion=payload.occasion,
+            max_iterations=settings.max_tool_calls,
+        )
+        
+        # ReAct loop
+        while state.iteration < state.max_iterations:
+            logger.info("ReAct iteration %d", state.iteration + 1)
+            
+            # Plan tool calls
+            tool_calls = self._plan_tool_calls(state)
+            
+            if not tool_calls:
+                logger.info("No more tool calls planned, moving to synthesis")
+                break
+            
+            # Execute tools
+            for call in tool_calls:
+                tool_name = call.get("tool")
+                params = call.get("params", {})
+                
+                logger.info("Executing tool: %s with params: %s", tool_name, params)
+                result = self._execute_tool(tool_name, params)
+                
+                # Store result
+                state.tool_results.append({
+                    "tool": tool_name,
+                    "params": params,
+                    "success": result.success,
+                    "data": result.data,
+                    "error": result.error,
+                    "summary": self._summarize_result(tool_name, result),
+                })
+            
+            state.iteration += 1
+        
+        # Synthesize response
+        final_text = self._synthesize_response(state)
+        
+        # Extract structured data from tool results
+        web_sources = self._get_web_sources(state)
+        products = self._get_products(state)
+        invitation = self._get_invitation(state)
+        
+        # Build overview from idea details or synthesized text
+        overview = ""
+        if state.idea_details:
+            overview = state.idea_details.get("summary", "")
+            if state.idea_details.get("highlights"):
+                overview += "\n\n**Highlights:**\n"
+                for h in state.idea_details["highlights"]:
+                    overview += f"• {h}\n"
+        else:
+            # Extract overview from synthesized text
+            overview = final_text[:800] if len(final_text) > 800 else final_text
+        
+        # Build steps - prefer idea's next_steps if available
+        steps = []
+        if state.idea_details and state.idea_details.get("next_steps"):
+            steps = state.idea_details["next_steps"]
+        else:
+            steps = self._extract_steps_from_text(final_text)
+        
+        # Build references (combined sources and links)
+        references = [
+            SourceLink(
+                title=r.get("title", "Reference")[:60],
+                url=r.get("url", ""),
+                snippet=r.get("snippet", "")[:150]
+            )
+            for r in web_sources if r.get("url")
+        ]
+        
+        # Build shopping list from products
+        shopping_list = [
+            ShoppingItem(
+                name=p.get("title", "Product")[:80],
+                price=p.get("price"),
+                url=p.get("url", ""),
+                source="Amazon"
+            )
+            for p in products if p.get("url")
+        ]
+        
+        # Convert to PlanItem format with new schema
+        plans = [
+            PlanItem(
+                title=f"Celebration Plan: {state.idea}",
+                summary=overview[:500] if len(overview) > 500 else overview,
+                overview=overview,
+                activities=state.idea_details.get("highlights", []) if state.idea_details else [],
+                steps=steps,
+                timeline=f"Preparation: 1-2 weeks before the event",
+                estimated_budget=state.idea_details.get("estimated_budget") if state.idea_details else (payload.budget_tier or "Varies"),
+                duration=f"Effort: {state.idea_details.get('effort', 'medium')}" if state.idea_details else "Plan ahead: 1-2 weeks",
+                references=references,
+                shopping_list=shopping_list,
+                sample_invitation=invitation,
+                # Legacy fields for backward compatibility
+                sources=[r.get("title", "") for r in web_sources],
+                links=[r.get("url", "") for r in web_sources],
+            )
+        ]
+        
+        return ResearchResponse(
+            session_id=payload.session_id,
+            plans=plans,
+            metadata={
+                "source": "react_agent",
+                "provider": "agent",
+                "idea": state.idea,
+                "idea_details": state.idea_details,
+                "iterations": state.iteration,
+                "tools_used": list(set(r.get("tool") for r in state.tool_results)),
+                "timestamp": datetime.now(tz=timezone.utc).isoformat(),
+                "full_response": final_text,
+            },
+        )
+    
+    def _summarize_result(self, tool_name: str, result: ToolResult) -> str:
+        """Create a brief summary of a tool result."""
+        if not result.success:
+            return f"Failed: {result.error}"
+        
+        if tool_name == "web_search":
+            count = result.data.get("count", 0)
+            return f"Found {count} results"
+        elif tool_name == "amazon_search":
+            count = result.data.get("count", 0)
+            return f"Found {count} products"
+        elif tool_name == "visit_page":
+            title = result.data.get("title", "page")
+            return f"Visited: {title[:50]}"
+        elif tool_name == "generate_message":
+            return "Generated message"
+        
+        return "Completed"
+    
+    def _extract_steps_from_text(self, text: str) -> List[str]:
+        """Extract actionable steps from synthesized text."""
+        steps = []
+        
+        # Look for numbered items or bullet points
+        lines = text.split("\n")
+        for line in lines:
+            line = line.strip()
+            # Match numbered steps or bullet points
+            if re.match(r'^[\d]+\.|\-|\*|\→', line):
+                clean_line = re.sub(r'^[\d]+\.|\-|\*|\→\s*', '', line).strip()
+                if clean_line and len(clean_line) > 10:
+                    steps.append(clean_line[:100])
+        
+        # If no steps found, create default ones
+        if not steps:
+            steps = [
+                "Review the plan and customize for your needs",
+                "Purchase necessary supplies and decorations",
+                "Send invitations to guests",
+                "Prepare the venue and activities",
+                "Enjoy the celebration!"
+            ]
+        
+        return steps[:8]  # Limit to 8 steps
+    
+    def _get_web_sources(self, state: AgentState) -> List[Dict[str, str]]:
+        """Extract web sources from tool results."""
+        sources = []
+        for result in state.tool_results:
+            if result.get("tool") == "web_search":
+                for r in result.get("data", {}).get("results", []):
+                    if r.get("url"):
+                        sources.append({
+                            "title": r.get("title", "")[:60],
+                            "url": r.get("url", ""),
+                            "snippet": r.get("snippet", "")[:150]
+                        })
+        return sources[:5]
+    
+    def _get_products(self, state: AgentState) -> List[Dict[str, str]]:
+        """Extract product results from Amazon search."""
+        products = []
+        for result in state.tool_results:
+            if result.get("tool") == "amazon_search" and result.get("success"):
+                for p in result.get("data", {}).get("products", []):
+                    if p.get("url"):
+                        products.append({
+                            "title": p.get("title", "Product")[:80],
+                            "price": p.get("price"),
+                            "url": p.get("url", ""),
+                            "snippet": p.get("snippet", "")[:100]
+                        })
+        return products[:5]
+    
+    def _get_invitation(self, state: AgentState) -> str:
+        """Extract generated invitation message from tool results."""
+        for result in state.tool_results:
+            if result.get("tool") == "generate_message" and result.get("success"):
+                return result.get("data", {}).get("message", "")
+        return ""
+
+
+# =============================================================================
+# Provider Factory
+# =============================================================================
+
 class BaseResearchProvider:
+    """Base class for research providers."""
+    
     def generate(self, payload: ResearchRequest) -> ResearchResponse:
         raise NotImplementedError
 
 
 class MockResearchProvider(BaseResearchProvider):
+    """Mock provider for testing."""
+    
     def generate(self, payload: ResearchRequest) -> ResearchResponse:
-        plans: List[PlanItem] = [
+        plans = [
             PlanItem(
                 title="Vendor shortlist",
                 summary="List 2-3 vendors that fit the brief.",
-                steps=["Identify 3 local options", "Compare pricing and availability", "Prepare contact info"],
+                steps=["Identify 3 local options", "Compare pricing", "Prepare contact info"],
                 estimated_budget="Varies",
                 duration="1-2 days",
                 sources=[],
@@ -42,7 +1315,8 @@ class MockResearchProvider(BaseResearchProvider):
                 sources=[],
                 links=[],
             ),
-        ][: settings.max_items]
+        ][:settings.max_items]
+        
         return ResearchResponse(
             session_id=payload.session_id,
             plans=plans,
@@ -55,42 +1329,64 @@ class MockResearchProvider(BaseResearchProvider):
 
 
 class DuckDuckGoResearchProvider(BaseResearchProvider):
-    """Lightweight web search provider for gift/venue ideas."""
-
-    def __init__(self, max_items: int, safe: str = "moderate") -> None:
+    """Simple DuckDuckGo search provider (no agent loop)."""
+    
+    def __init__(self, max_items: int, safe: str = "moderate"):
         self.max_items = max_items
         self.safe = safe
         if DDGS is None:
-            raise RuntimeError("duckduckgo_search is not installed")
-
+            raise RuntimeError("ddgs is not installed")
+    
+    def _parse_idea(self, payload: ResearchRequest) -> str:
+        """Extract the actual idea from the payload."""
+        message = payload.user_message or payload.topic or ""
+        
+        # Handle "Plan this idea in detail: X" format
+        if "Plan this idea in detail:" in message:
+            try:
+                parts = message.split("Plan this idea in detail:")
+                if len(parts) > 1:
+                    idea = parts[1].split("Additional context:")[0].strip().rstrip(".")
+                    if idea:
+                        return idea
+            except Exception:
+                pass
+        
+        return message[:100] if message else "celebration"
+    
     def generate(self, payload: ResearchRequest) -> ResearchResponse:
-        query = self._build_query(payload)
-        links: List[str] = []
-        sources: List[str] = []
+        idea = self._parse_idea(payload)
+        query = f"{idea} celebration party ideas activities how to plan"
+        
+        logger.info("DuckDuckGo search for: %s", query)
+        
+        links, titles, snippets = [], [], []
         try:
             with DDGS() as ddgs:
                 results = ddgs.text(query, safesearch=self.safe, max_results=self.max_items)
-            for item in results or []:
-                href = item.get("href")
-                if href:
-                    links.append(href)
-                    sources.append(item.get("title") or href)
-        except Exception as exc:  # pragma: no cover
+                for item in results or []:
+                    if item.get("href"):
+                        links.append(item["href"])
+                        titles.append(item.get("title", ""))
+                        snippets.append(item.get("body", ""))
+        except Exception as exc:
             logger.error("DuckDuckGo search failed: %s", exc)
-
+        
         plan = PlanItem(
-            title="Web search results",
-            summary=f"Quick links for: {query}",
+            title=f"Research: {idea}",
+            summary=f"Web search results for planning {idea}",
             steps=[
-                "Review the links for suitability (location, budget, vibe).",
-                "Shortlist the top 2-3 options and check availability.",
-                "Follow up with vendors or add items to a shared cart.",
+                "Review the links for relevant ideas and inspiration",
+                "Note down activities and supplies that fit your budget",
+                "Create a checklist of items to purchase",
+                "Plan your timeline for preparation",
             ],
             estimated_budget="Varies",
-            duration="15-30 minutes",
-            sources=sources[: self.max_items],
-            links=links[: self.max_items],
+            duration="30-60 minutes research",
+            sources=titles[:self.max_items],
+            links=links[:self.max_items],
         )
+        
         return ResearchResponse(
             session_id=payload.session_id,
             plans=[plan],
@@ -98,28 +1394,41 @@ class DuckDuckGoResearchProvider(BaseResearchProvider):
                 "source": "duckduckgo",
                 "provider": "duckduckgo",
                 "query": query,
+                "idea": idea,
                 "timestamp": datetime.now(tz=timezone.utc).isoformat(),
             },
         )
 
-    def _build_query(self, payload: ResearchRequest) -> str:
-        parts = [
-            payload.topic or payload.user_message or "",
-            payload.location or "",
-            payload.budget_tier or "",
-            "celebration gifts vendors decor food music ideas",
-        ]
-        return " ".join([p for p in parts if p]).strip() or "celebration gifts decor ideas"
+
+class AgentResearchProvider(BaseResearchProvider):
+    """ReAct agent-based research provider."""
+    
+    def __init__(self):
+        self._agent = ReActResearchAgent()
+    
+    def generate(self, payload: ResearchRequest) -> ResearchResponse:
+        return self._agent.run(payload)
 
 
 def get_provider() -> BaseResearchProvider:
+    """Get the configured research provider."""
     name = settings.provider.lower()
     logger.info("Research provider selected: %s", name)
-
+    
     if name == "mock":
         return MockResearchProvider()
-
+    
     if name == "duckduckgo":
-        return DuckDuckGoResearchProvider(max_items=settings.max_items, safe=settings.search_safe)
-
+        return DuckDuckGoResearchProvider(
+            max_items=settings.max_items,
+            safe=settings.search_safe
+        )
+    
+    if name == "agent":
+        try:
+            return AgentResearchProvider()
+        except Exception as exc:
+            logger.error("Agent provider failed to initialize: %s", exc)
+            return MockResearchProvider()
+    
     raise ValueError(f"Unsupported research provider: {settings.provider}")

mcp_servers/research/tool_schemas.py

@@ -1,23 +1,94 @@
 from pydantic import BaseModel, Field
+from typing import List, Optional, Dict, Any
+
+
+class IdeaContext(BaseModel):
+    """Full context of the idea being researched."""
+    title: str
+    summary: str = ""
+    highlights: List[str] = Field(default_factory=list)
+    estimated_budget: str | None = None
+    effort: str | None = None
+    next_steps: List[str] = Field(default_factory=list)
+    persona_fit: str | None = None
+
+
+class HonoreeProfile(BaseModel):
+    """Profile of the person being celebrated."""
+    age_range: str | None = None
+    interests: List[str] = Field(default_factory=list)
+    preferences: str | None = None
+    guest_count: int | None = None
+
 
 class ResearchRequest(BaseModel):
+    """Request payload for research agent with full context."""
     session_id: str
     user_message: str
+    
+    # The idea being researched (full context from ideation)
+    idea: IdeaContext | None = None
+    
+    # Legacy fields (kept for backward compatibility)
     topic: str | None = None
     location: str | None = None
     budget_tier: str | None = None
-    constraints: list[str] = Field(default_factory=list)
+    constraints: List[str] = Field(default_factory=list)
+    
+    # New fields for richer context
+    occasion: str | None = None
+    event_date: str | None = None
+    honoree: HonoreeProfile | None = None
+    
+    # Conversation history for context
+    conversation_history: List[Dict[str, Any]] = Field(default_factory=list)
+
+
+class SourceLink(BaseModel):
+    """Combined source with title and URL."""
+    title: str
+    url: str
+    snippet: str = ""
+
+
+class ShoppingItem(BaseModel):
+    """A specific product recommendation."""
+    name: str
+    price: str | None = None
+    url: str
+    source: str = "Amazon"  # Amazon, Flipkart, etc.
+
 
 class PlanItem(BaseModel):
+    """A detailed plan item with combined sources."""
     title: str
     summary: str
-    steps: list[str] = Field(default_factory=list)
+    
+    # Detailed sections
+    overview: str = ""  # Detailed overview of what this plan entails
+    activities: List[str] = Field(default_factory=list)  # Suggested activities
+    steps: List[str] = Field(default_factory=list)  # Actionable steps
+    timeline: str = ""  # Suggested timeline
+    
+    # Budget and duration
     estimated_budget: str | None = None
     duration: str | None = None
-    sources: list[str] = Field(default_factory=list)
-    links: list[str] = Field(default_factory=list)
+    
+    # Combined sources (title + URL together)
+    references: List[SourceLink] = Field(default_factory=list)
+    
+    # Shopping recommendations (specific products)
+    shopping_list: List[ShoppingItem] = Field(default_factory=list)
+    
+    # Generated content
+    sample_invitation: str = ""
+    
+    # Legacy fields (for backward compatibility)
+    sources: List[str] = Field(default_factory=list)
+    links: List[str] = Field(default_factory=list)
+
 
 class ResearchResponse(BaseModel):
     session_id: str
-    plans: list[PlanItem] = Field(default_factory=list)
-    metadata: dict = Field(default_factory=dict)
+    plans: List[PlanItem] = Field(default_factory=list)
+    metadata: Dict[str, Any] = Field(default_factory=dict)

requirements.txt

@@ -4,3 +4,5 @@ pydantic-settings
 pydantic
 httpx
 ddgs
+langgraph>=1.0.0
+langchain-core>=1.1.0

ui/chat.py

@@ -39,7 +39,8 @@ def _make_initial_state() -> Dict[str, Any]:
             "source": "gradio",
             "last_interaction": datetime.now(tz=timezone.utc).isoformat(),
         },
-        "last_ideas": [],
+        "last_ideas": [],  # List of idea titles for dropdown
+        "last_ideas_full": {},  # Dict mapping title -> full idea details
     }
 
 
@@ -148,20 +149,67 @@ def _format_research_response(response: ResearchResponse) -> str:
 
     sections: List[str] = []
     for idx, plan in enumerate(response.plans, start=1):
-        steps = "\n".join(f"→ {step}" for step in plan.steps) or "→ Next steps will be added."
-        sources = "\n".join(f"- {s}" for s in plan.sources) if plan.sources else ""
-        links = "\n".join(f"- {l}" for l in plan.links) if plan.links else ""
-        sections.append(
-            (
-                f"### Plan {idx}: {plan.title}\n"
-                f"{plan.summary}\n\n"
-                f"**Budget:** {plan.estimated_budget or 'Varies'} · "
-                f"**Duration:** {plan.duration or 'TBD'}\n\n"
-                f"**Steps**\n{steps}\n\n"
-                + (f"**Sources**\n{sources}\n\n" if sources else "")
-                + (f"**Links**\n{links}\n\n" if links else "")
-            )
+        parts = [f"### Plan {idx}: {plan.title}\n"]
+        
+        # Overview section (use overview if available, else summary)
+        overview = getattr(plan, 'overview', '') or plan.summary
+        if overview:
+            parts.append(f"{overview}\n")
+        
+        # Budget and duration
+        parts.append(
+            f"\n**Budget:** {plan.estimated_budget or 'Varies'} · "
+            f"**Duration:** {plan.duration or 'TBD'}\n"
         )
+        
+        # Activities (if available)
+        activities = getattr(plan, 'activities', [])
+        if activities:
+            parts.append("\n**Suggested Activities**")
+            for activity in activities:
+                parts.append(f"\n• {activity}")
+            parts.append("\n")
+        
+        # Steps
+        if plan.steps:
+            parts.append("\n**Steps**")
+            for step in plan.steps:
+                parts.append(f"\n→ {step}")
+            parts.append("\n")
+        
+        # Shopping list (specific products)
+        shopping = getattr(plan, 'shopping_list', [])
+        if shopping:
+            parts.append("\n**Shopping List**")
+            for item in shopping:
+                price_str = f" - {item.price}" if getattr(item, 'price', None) else ""
+                parts.append(f"\n• [{item.name}]({item.url}){price_str}")
+            parts.append("\n")
+        
+        # Sample invitation
+        invitation = getattr(plan, 'sample_invitation', '')
+        if invitation:
+            parts.append(f"\n**Sample Invitation**\n```\n{invitation}\n```\n")
+        
+        # Combined references (title + URL)
+        references = getattr(plan, 'references', [])
+        if references:
+            parts.append("\n**References**")
+            for ref in references:
+                title = getattr(ref, 'title', 'Link')
+                url = getattr(ref, 'url', '')
+                if url:
+                    parts.append(f"\n• [{title}]({url})")
+            parts.append("\n")
+        elif plan.sources or plan.links:
+            # Fallback to legacy format - combine sources and links
+            parts.append("\n**References**")
+            for i, link in enumerate(plan.links or []):
+                title = plan.sources[i] if i < len(plan.sources or []) else "Link"
+                parts.append(f"\n• [{title}]({link})")
+            parts.append("\n")
+        
+        sections.append("".join(parts))
 
     note = response.metadata.get("reason") if response.metadata else None
     if note:
@@ -230,7 +278,20 @@ def handle_message(
         payload_for_call = _build_request_payload(state, user_message=message or "")
         try:
             ideation_response = orchestrator.generate_ideas(payload_for_call)
+            # Store both titles (for dropdown) and full details (for research)
             state["last_ideas"] = [idea.title for idea in ideation_response.ideas]
+            state["last_ideas_full"] = {
+                idea.title: {
+                    "title": idea.title,
+                    "summary": idea.summary,
+                    "highlights": idea.highlights,
+                    "estimated_budget": idea.estimated_budget,
+                    "effort": idea.effort,
+                    "next_steps": idea.next_steps,
+                    "persona_fit": idea.persona_fit,
+                }
+                for idea in ideation_response.ideas
+            }
             bot_content = _format_ideation_response(ideation_response)
         except Exception as exc:  # pragma: no cover
             bot_content = (
@@ -288,6 +349,9 @@ def handle_plan_selection(
         choices = state.get("last_ideas") or []
         return chat_history, state, _build_request_payload(state), state["session_id"], gr.update(choices=choices, value=None)
 
+    # Get full idea context if available
+    idea_context = state.get("last_ideas_full", {}).get(plan_choice)
+    
     # craft a planning prompt using the selected idea
     plan_prompt = f"Plan this idea in detail: {plan_choice}. Additional context: {message}"
     user_entry = {"role": "user", "content": plan_prompt}
@@ -296,7 +360,8 @@ def handle_plan_selection(
 
     payload_for_call = _build_request_payload(state, user_message=plan_prompt)
     try:
-        research_response = research_orchestrator.generate_plan(payload_for_call)
+        # Pass full idea context to research agent
+        research_response = research_orchestrator.generate_plan(payload_for_call, idea_context=idea_context)
         bot_content = _format_research_response(research_response)
     except Exception as exc:  # pragma: no cover
         bot_content = (