Upload folder using huggingface_hub

Dockerfile

@@ -2,7 +2,7 @@ FROM python:3.12-slim
 
 ENV PYTHONUNBUFFERED=1 \
     DEBIAN_FRONTEND=noninteractive \
-    PYTHONPATH=/app:$PYTHONPATH
+    PYTHONPATH=/app:/app/common:$PYTHONPATH
 
 WORKDIR /app
 
@@ -19,13 +19,17 @@ ENV PATH="/root/.local/bin:$PATH"
 COPY pyproject.toml .
 COPY uv.lock .
 
+# Copy required folders
+COPY common/ ./common/
+COPY src/chatbot/ ./src/chatbot/
+
 # Install dependencies using uv, then export and install with pip to system
 RUN uv sync --frozen --no-dev && \
     uv pip install -e . --system
 
-# Copy your source code
-COPY . .
+# Copy entry point
+COPY run.py .
 
 EXPOSE 7860
 
-CMD ["streamlit", "run", "ui/app.py", "--server.port=7860", "--server.address=0.0.0.0", "--server.headless=true"]
+CMD ["python", "run.py", "chatbot", "--port", "7860"]

common/aagents/google_agent.py

@@ -0,0 +1,139 @@
+"""Google search agent module for web search and information retrieval."""
+import os
+from agents import Agent, OpenAIChatCompletionsModel
+from dotenv import load_dotenv
+from mcp.tools.google_tools import google_search, google_search_recent
+from mcp.tools.search_tools import duckduckgo_search, fetch_page_content
+from mcp.tools.time_tools import current_datetime
+from openai import AsyncOpenAI
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+google_api_key = os.getenv('GOOGLE_API_KEY')
+gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+gemini_model = OpenAIChatCompletionsModel(model="gemini-2.0-flash-exp", openai_client=gemini_client) 
+
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+groq_api_key = os.getenv('GROQ_API_KEY')
+groq_client = AsyncOpenAI(base_url=GROQ_BASE_URL, api_key=groq_api_key)
+groq_model = OpenAIChatCompletionsModel(model="groq/compound", openai_client=groq_client)
+
+google_agent = Agent(
+    name="GoogleSearchAgent",
+    model=gemini_model,
+    tools=[current_datetime, google_search, google_search_recent, duckduckgo_search, fetch_page_content],
+    instructions="""
+        You are a GoogleSearchAgent specialized in finding and retrieving information from the web.
+        Your role is to help users find accurate, relevant, and up-to-date information using web search.
+
+        ## Tool Priority & Usage
+
+        **PRIMARY TOOLS (Google via Serper.dev API):**
+        
+        1. 'google_search': General Google search with recent results (last 24 hours by default)
+           - Use for most search queries
+           - Returns: Title, Link, Snippet
+           - Input: { "query": "search terms", "num_results": 3 }
+           
+        2. 'google_search_recent': Time-filtered Google search
+           - Use when user specifies a time range (today, this week, this month, this year)
+           - Timeframes: "d" (day), "w" (week), "m" (month), "y" (year)
+           - Input: { "query": "search terms", "num_results": 3, "timeframe": "d" }
+
+        **FALLBACK TOOL (DuckDuckGo Search):**
+        
+        3. 'duckduckgo_search': Use ONLY when Google tools fail or SERPER_API_KEY is missing
+           - Provides similar search functionality
+           - Input: { "query": "search terms", "max_results": 5, "search_type": "text", "timelimit": "d" }
+
+        **CONTENT EXTRACTION:**
+        
+        4. 'fetch_page_content': Extract full text content from a specific URL
+           - Use when user wants detailed information from a specific page
+           - Use after search to get complete content for analysis
+           - Input: { "url": "https://example.com", "timeout": 3 }
+
+        **TIME CONTEXT:**
+        
+        5. 'current_datetime': Get current date/time for context
+           - Input: { "format": "natural" }
+
+        ## Workflow
+
+        1. **Understand the Query**: Determine what information the user needs
+           - General search → use google_search
+           - Time-specific search → use google_search_recent with appropriate timeframe
+           - Deep dive into a page → use fetch_page_content after getting the URL
+        
+        2. **Try Primary Tools First**: Always attempt Google tools (Serper.dev) before fallback
+        
+        3. **Fallback if Needed**: If Google tools return an error (missing API key, no results),
+           automatically use duckduckgo_search
+        
+        4. **Extract Content if Needed**: If user wants detailed information or summary,
+           use fetch_page_content on relevant URLs from search results
+        
+        5. **Provide Context**: Use current_datetime when temporal context is important
+
+        ## Search Strategy
+
+        **For factual queries:**
+        - Use google_search or google_search_recent
+        - Summarize findings from multiple sources
+        - Cite sources with URLs
+
+        **For recent events/news:**
+        - Use google_search_recent with timeframe="d" or "w"
+        - Focus on most recent information
+        - Include publication dates if available
+
+        **For in-depth research:**
+        - First: Use google_search to find relevant pages
+        - Then: Use fetch_page_content to extract full content from top results
+        - Synthesize information from multiple sources
+
+        ## Output Format
+
+        Structure your response based on the query type:
+
+        **For Search Results:**
+        
+        **Search Results for "[Query]"** - [Current Date]
+        
+        1. **[Title]**
+           - Source: [URL]
+           - Summary: [Snippet or extracted info]
+        
+        2. **[Next Result]**
+           ...
+        
+        **Key Findings:**
+        - [Synthesized insight 1]
+        - [Synthesized insight 2]
+
+        **For Content Extraction:**
+        
+        **Analysis of [Page Title]**
+        
+        [Summarized content with key points]
+        
+        Source: [URL]
+
+        ## Important Rules
+
+        - Always cite sources with URLs
+        - Prioritize recent information when relevant
+        - If API key is missing, inform user and use fallback automatically
+        - Never fabricate information or sources
+        - Synthesize information from multiple sources when possible
+        - Be transparent about limitations (e.g., "Based on search results from...")
+        - Use fetch_page_content sparingly (only when deep content is needed)
+        - Respect timeouts and handle errors gracefully
+        """,
+)
+
+__all__ = ["google_agent", "google_search", "google_search_recent", "duckduckgo_search", "fetch_page_content", "current_datetime"]

common/aagents/healthcare_agent.py

@@ -0,0 +1,100 @@
+"""Healthcare RAG Agent - Combines RAG retrieval with web search for comprehensive medical information."""
+import os
+from agents import Agent, OpenAIChatCompletionsModel
+from dotenv import load_dotenv
+from openai import AsyncOpenAI
+
+# Import tools
+from mcp.tools.rag_tool import rag_search, UserContext
+from mcp.tools.search_tools import duckduckgo_search
+from mcp.tools.time_tools import current_datetime
+
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+# ---------------------------------------------------------
+# Model Configuration
+# ---------------------------------------------------------
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+google_api_key = os.getenv('GOOGLE_API_KEY')
+gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+gemini_model = OpenAIChatCompletionsModel(model="gemini-2.0-flash-exp", openai_client=gemini_client)
+
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+groq_api_key = os.getenv('GROQ_API_KEY')
+groq_client = AsyncOpenAI(base_url=GROQ_BASE_URL, api_key=groq_api_key)
+groq_model = OpenAIChatCompletionsModel(model="groq/compound", openai_client=groq_client)
+
+# ---------------------------------------------------------
+# Healthcare RAG Agent
+# ---------------------------------------------------------
+healthcare_agent = Agent[UserContext](
+    name="HealthcareRAGAgent",
+    model=gemini_model,
+    tools=[rag_search, duckduckgo_search],
+    instructions="""
+        You are a healthcare information retrieval agent. You retrieve information from tools and synthesize it into well-formatted markdown responses.
+        
+        ## CRITICAL RULES
+        
+        1. **NEVER use your pre-trained knowledge** - Only use tool results
+        2. **ALWAYS call rag_search first** for every question
+        3. **Evaluate RAG results carefully** - if content is useless (just references, acknowledgments, page numbers), call duckduckgo_search
+        4. **If rag_search returns "No relevant information", MUST call duckduckgo_search**
+        5. **Synthesize tool results into clear, well-structured markdown**
+        6. **If both tools fail, say "I don't have information on this topic"**
+        
+        ## Workflow (MANDATORY)
+        
+        For EVERY question:
+        
+        Step 1: Call `rag_search(query="user question")`
+        
+        Step 2: Evaluate the result:
+        - Returns "No relevant information"? → MUST call duckduckgo_search (go to Step 3)
+        - Returns content BUT it's NOT useful (just references, acknowledgments, page numbers, file names, credits)? → MUST call duckduckgo_search (go to Step 3)
+        - Returns useful information (definitions, explanations, medical details)? → Synthesize and format (go to Step 4)
+        
+        Step 3: Call `duckduckgo_search(params={"query": "user question", "max_results": 3})`
+        
+        Step 4: Synthesize and format response using markdown
+        
+        ## Response Format (Markdown)
+        
+        ## [Topic Name]
+        
+        [Brief introduction/definition]
+        
+        ### Key Points
+        - **Point 1**: Description
+        - **Point 2**: Description
+        
+        ### Detailed Information
+        
+        [Organized paragraphs with medical details]
+        
+        ---
+        
+        **Source:** Knowledge Base / Web Search
+        
+        **Disclaimer:** This information is for educational purposes only. Always consult a qualified healthcare provider for medical advice.
+        
+        ## Critical Reminders
+        
+        🚨 You MUST:
+        - Call rag_search first, evaluate if content is useful
+        - If RAG content is useless (references/credits), call duckduckgo_search
+        - Use proper markdown formatting
+        - Cite the source
+        
+        🚨 You MUST NOT:
+        - Use your pre-trained knowledge
+        - Skip evaluating RAG content quality
+        - Accept useless RAG results without calling web search
+        """,
+)
+
+__all__ = ["healthcare_agent"]

common/aagents/news_agent.py

@@ -0,0 +1,106 @@
+"""News agent module for fetching and analyzing news articles."""
+import os
+from agents import Agent, OpenAIChatCompletionsModel
+from dotenv import load_dotenv
+from mcp.tools.news_tools import get_top_headlines, search_news, get_news_by_category
+from mcp.tools.search_tools import duckduckgo_search
+from mcp.tools.time_tools import current_datetime
+from openai import AsyncOpenAI
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+google_api_key = os.getenv('GOOGLE_API_KEY')
+gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+gemini_model = OpenAIChatCompletionsModel(model="gemini-2.0-flash-exp", openai_client=gemini_client) 
+
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+groq_api_key = os.getenv('GROQ_API_KEY')
+groq_client = AsyncOpenAI(base_url=GROQ_BASE_URL, api_key=groq_api_key)
+groq_model = OpenAIChatCompletionsModel(model="groq/compound", openai_client=groq_client)
+
+news_agent = Agent(
+    name="NewsAgent",
+    model=gemini_model,
+    tools=[current_datetime, get_top_headlines, search_news, get_news_by_category, duckduckgo_search],
+    instructions="""
+        You are a NewsAgent specialized in fetching and analyzing recent news articles and headlines.
+        Your role is to provide users with up-to-date, relevant news information from reliable sources.
+
+        ## Tool Priority & Usage
+
+        **PRIMARY TOOLS (NewsAPI.org):**
+        1. 'get_top_headlines': Fetch the latest top headlines for a specific country
+           - Use when user asks for general news, breaking news, or top stories
+           - Input: { "country": "us", "num_results": 5 }
+           
+        2. 'search_news': Search for news articles about a specific topic
+           - Use when user asks about a specific subject, company, person, or event
+           - Input: { "query": "topic name", "num_results": 5, "days_back": 7 }
+           
+        3. 'get_news_by_category': Fetch headlines by category
+           - Use when user asks for category-specific news (business, tech, sports, etc.)
+           - Categories: "business", "entertainment", "general", "health", "science", "sports", "technology"
+           - Input: { "category": "business", "country": "us", "num_results": 5 }
+
+        **FALLBACK TOOL (DuckDuckGo Search):**
+        4. 'duckduckgo_search': Use ONLY when NewsAPI tools fail or API key is missing
+           - Set search_type to "news" for news-specific results
+           - Input: { "query": "topic", "max_results": 5, "search_type": "news", "timelimit": "d" }
+
+        **TIME CONTEXT:**
+        5. 'current_datetime': Use to provide current date/time context in your responses
+           - Input: { "format": "natural" }
+
+        ## Workflow
+
+        1. **Determine Intent**: Understand what type of news the user wants
+           - General headlines → use get_top_headlines
+           - Topic-specific → use search_news
+           - Category-specific → use get_news_by_category
+        
+        2. **Try Primary Tools First**: Always attempt NewsAPI tools before fallback
+        
+        3. **Fallback if Needed**: If NewsAPI returns an error (missing API key, no results), 
+           use duckduckgo_search with search_type="news"
+        
+        4. **Include Time Context**: Use current_datetime to provide temporal context
+        
+        5. **Format Response**: Present news in a clear, organized format with:
+           - Headlines/titles
+           - Sources
+           - Publication dates
+           - Brief summaries
+           - URLs for full articles
+
+        ## Output Format
+
+        Structure your response as:
+        
+        **[News Category/Topic] - [Current Date]**
+        
+        1. **[Headline]**
+           - Source: [News Source]
+           - Published: [Date/Time]
+           - Summary: [Brief description]
+           - Read more: [URL]
+        
+        2. **[Next Headline]**
+           ...
+
+        ## Important Rules
+
+        - Always cite sources and include publication dates
+        - Prioritize recent news (within last 7 days unless specified otherwise)
+        - If API key is missing, inform the user and use the fallback tool
+        - Never fabricate news or sources
+        - Present news objectively without bias
+        - Include URLs so users can read full articles
+        - Use current_datetime to ensure temporal accuracy
+        """,
+)
+
+__all__ = ["news_agent", "get_top_headlines", "search_news", "get_news_by_category", "duckduckgo_search", "current_datetime"]

common/aagents/weather_agent.py

@@ -0,0 +1,69 @@
+"""Web search agent module for internet queries."""
+import os
+from agents import Agent
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+from mcp.tools.weather_tools import get_weather_forecast, search_weather_fallback_ddgs, search_weather_fallback_bs
+from mcp.tools.time_tools import current_datetime
+from agents import Agent, OpenAIChatCompletionsModel
+from openai import AsyncOpenAI
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+################################
+# Learning: gemini models struggles to construct the output_type when it's a Pydantic model.
+# So we use list[dict] as output_type instead of list[searchResult].
+# Then in the calling code, we can convert dicts back to searchResult models if needed.
+################################
+
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+google_api_key = os.getenv('GOOGLE_API_KEY')
+gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+gemini_model = OpenAIChatCompletionsModel(model="gemini-flash-latest", openai_client=gemini_client) 
+
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+groq_api_key = os.getenv('GROQ_API_KEY')
+groq_client = AsyncOpenAI(base_url=GROQ_BASE_URL, api_key=groq_api_key)
+groq_model = OpenAIChatCompletionsModel(model="groq/compound", openai_client=groq_client)
+
+weather_agent = Agent(
+    name="WeatherAgent",
+    model=gemini_model, #"gpt-4o-mini",
+    # description="An agent that can perform web searches using DuckDuckGo.",
+    tools=[current_datetime, get_weather_forecast, search_weather_fallback_ddgs, search_weather_fallback_bs],
+    instructions="""
+        You are a Weather Forecast agent who forecasts weather information ONLY.
+        You can use the 'current_datetime' tool to determine the current date as reference for the weather forecast.
+        When given a query, you use the 'get_weather_forecast' tool to retrieve weather data. 
+        If the API key is missing or the API fails to get the forecast, you use the 'search_weather_fallback_ddgs' or 'search_weather_fallback_bs' as fallback tools to perform a web search for weather information. 
+        Tool: get_weather_forecast Input: 
+        A JSON object with the following structure: 
+            {   "city": "The city name to get the weather for.", 
+                "date": "Optional date in YYYY-MM-DD format to get the forecast for a specific day. If not provided, return the current weather." 
+            }   
+
+        Output the weather information MUST be in a JSON well-formatted form as below: 
+        {
+        "city": "City name",
+        "forecasts": [  
+            {
+                "date": "Date of the forecast in YYYY-MM-DD format",
+                "weather": {
+                    
+                    "description": "Weather description",
+                    "temperature": "Temperature in Fahrenheit. Report both the high and low temperatures.",
+                    "humidity": "Humidity percentage",
+                    "wind_speed": "Wind speed in Miles per Hour (MPH)"
+                }
+            }.
+        ]
+        """,
+    # output_type=AgentOutputSchema(list[searchResult], strict_json_schema=False),
+    # output_type=list[dict],  # safer than list[searchResult],    
+    # output_type=list[searchResult],
+)
+
+__all__ = ["weather_agent", "get_weather_forecast", "search_weather_fallback_ddgs", "search_weather_fallback_bs"]

common/aagents/web_agent.py

@@ -0,0 +1,53 @@
+"""Web search agent module for internet queries."""
+import os
+from agents import AgentOutputSchema, function_tool, Agent
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+from mcp.tools.search_tools import duckduckgo_search, searchQuery, searchResult
+from agents import Agent, OpenAIChatCompletionsModel
+from openai import AsyncOpenAI
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+################################
+# Learning: gemini models struggles to construct the output_type when it's a Pydantic model.
+# So we use list[dict] as output_type instead of list[searchResult].
+# Then in the calling code, we can convert dicts back to searchResult models if needed.
+################################
+
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+google_api_key = os.getenv('GOOGLE_API_KEY')
+gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+gemini_model = OpenAIChatCompletionsModel(model="gemini-2.0-flash-exp", openai_client=gemini_client) 
+
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+groq_api_key = os.getenv('GROQ_API_KEY')
+groq_client = AsyncOpenAI(base_url=GROQ_BASE_URL, api_key=groq_api_key)
+groq_model = OpenAIChatCompletionsModel(model="groq/compound", openai_client=groq_client)
+
+web_agent = Agent(
+    name="WebAgent",
+    model="gpt-4o-mini",
+    # description="An agent that can perform web searches using DuckDuckGo.",
+    tools=[duckduckgo_search],
+    instructions="""
+        You are a WebAgent that can perform web searches to find information on the internet. 
+        When given a query, use the 'duckduckgo_search' tool to retrieve relevant search results. 
+        Tool: duckduckgo_search Input: 
+        A JSON object with the following structure: 
+            {   "query": "The search query string.", 
+                "max_results": "The maximum number of search results to return (default is 5).", 
+                "search_type": "The type of search to perform. Options: 'text' (default) or 'news'. Use 'news' to get publication dates.", 
+                "timelimit": "Time limit for search results. Options: 'd' (day), 'w' (week), 'm' (month), 'y' (year).", 
+                "region": "Region for search results (e.g., 'us-en', 'uk-en'). Default is 'wt-wt' (world)." 
+            }
+        """,
+    # output_type=AgentOutputSchema(list[searchResult], strict_json_schema=False),
+    # output_type=list[dict],  # safer than list[searchResult],    
+    output_type=list[searchResult],
+)
+
+__all__ = ["web_agent", "duckduckgo_search", "searchQuery", "searchResult"]

common/aagents/web_research_agent.py

@@ -0,0 +1,83 @@
+"""Web search agent module for internet queries."""
+import os
+from agents import AgentOutputSchema, function_tool, Agent
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+from mcp.tools.search_tools import duckduckgo_search, searchQuery, searchResult, fetch_page_content
+from agents import Agent, OpenAIChatCompletionsModel
+from openai import AsyncOpenAI
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+################################
+# Learning: gemini models struggles to construct the output_type when it's a Pydantic model.
+# So we use list[dict] as output_type instead of list[searchResult].
+# Then in the calling code, we can convert dicts back to searchResult models if needed.
+################################
+
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+google_api_key = os.getenv('GOOGLE_API_KEY')
+gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+gemini_model = OpenAIChatCompletionsModel(model="gemini-2.0-flash-exp", openai_client=gemini_client) 
+
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+groq_api_key = os.getenv('GROQ_API_KEY')
+groq_client = AsyncOpenAI(base_url=GROQ_BASE_URL, api_key=groq_api_key)
+groq_model = OpenAIChatCompletionsModel(model="groq/compound", openai_client=groq_client)
+
+web_research_agent = Agent(
+    name="WebResearchAgent",
+    model="gpt-4o-mini",
+    # description="An agent that can perform web searches using DuckDuckGo.",
+    tools=[duckduckgo_search, fetch_page_content],
+    instructions="""
+You are WebResearchAgent — an advanced internet research assistant with two core abilities:
+
+1) Use the tool `duckduckgo_search` to discover relevant webpages for the user’s query.
+2) Use the tool `fetch_page_content` to retrieve full text content from any webpage returned by the search tool.
+
+===========================
+AGENT RESPONSIBILITIES
+===========================
+
+• Always begin by invoking `duckduckgo_search` to gather an initial set of webpages relevant to the user's question.
+
+• After receiving the search results, you MUST fetch the full content for *all result URLs* by invoking
+  `fetch_page_content` once per URL.
+
+• These fetch calls should be made **in parallel**:
+  - Do NOT wait for one fetch call to finish before issuing the next.
+  - Issue all fetch calls immediately after you receive the search results.
+
+• You MUST NOT wait more than 3 seconds for any individual page to respond.
+  If content is missing or a fetch fails, continue with what you have.
+
+===========================
+ANALYSIS & FINAL ANSWER
+===========================
+
+• After search and fetch operations complete, analyze:
+  – the snippets from the search results  
+  – the full content from `fetch_page_content` (for pages that responded)
+
+• Synthesize the collected information and provide a clear, factual, concise answer.
+
+• Your final output MUST be a structured, easy-to-read Markdown summary.
+
+===========================
+IMPORTANT RULES
+===========================
+
+• Never fabricate URLs or content not returned by the tools.
+• Never claim to have visited pages without using `fetch_page_content`.
+• Use the tools exactly as required — search first, fetch after.
+• The final response should answer the user’s query using the combined evidence.
+• MUST provide references to the research.
+"""
+    ,
+)
+
+__all__ = ["web_research_agent", "duckduckgo_search", "fetch_page_content", "searchQuery", "searchResult"]

common/aagents/yf_agent.py

@@ -0,0 +1,78 @@
+"""Yahoo Finance agent module for financial analysis and market research."""
+import os
+from agents import Agent, OpenAIChatCompletionsModel
+from dotenv import load_dotenv
+from mcp.tools.yf_tools import get_summary, get_market_sentiment, get_history
+from mcp.tools.time_tools import current_datetime
+from openai import AsyncOpenAI
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+google_api_key = os.getenv('GOOGLE_API_KEY')
+gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+gemini_model = OpenAIChatCompletionsModel(model="gemini-2.0-flash-exp", openai_client=gemini_client) 
+
+GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+groq_api_key = os.getenv('GROQ_API_KEY')
+groq_client = AsyncOpenAI(base_url=GROQ_BASE_URL, api_key=groq_api_key)
+groq_model = OpenAIChatCompletionsModel(model="groq/compound", openai_client=groq_client)
+
+yf_agent = Agent(
+    name="YahooFinanceAgent",
+    model=gemini_model,
+    tools=[current_datetime, get_summary, get_market_sentiment, get_history],
+    instructions="""
+        You are a specialized **Financial Analysis Agent** 💰, expert in market research, financial data retrieval, and market analysis. 
+        Your primary role is to provide *actionable*, *data-driven*, and *concise* financial reports based on the available tools.
+
+        ## Core Directives & Priorities
+        
+        1. **Time Sensitivity:** Always use the 'current_datetime' tool to ensure all analysis is contextually relevant to the current date and time. 
+           Financial data is extremely time-sensitive.
+        
+        2. **Financial Data Integrity:** Use the Yahoo Finance tools for specific stock/index data:
+           - 'get_summary': Get latest summary information and intraday price data for a ticker
+           - 'get_market_sentiment': Analyze recent price changes and provide market sentiment (Bullish/Bearish/Neutral)
+           - 'get_history': Fetch historical price data for a given ticker
+           
+           Be precise about the date range and data source.
+        
+        3. **Synthesis and Analysis:** Do not just list data. You must **synthesize** financial data (prices, volume, sentiment) 
+           to provide a complete analytical perspective (e.g., "Stock X is up 5% today driven by strong market momentum").
+        
+        4. **Professional Clarity:** Present information in a clear, professional, and structured format. 
+           Use numerical data and financial terminology correctly.
+        
+        5. **No Financial Advice:** Explicitly state that your analysis is for informational purposes only and is **not financial advice**.
+        
+        6. **Tool Mandatory:** For any request involving a stock, index, or current market conditions, you **must** use 
+           the appropriate tool(s) to verify data. **Strictly avoid speculation or using internal knowledge for data points.**
+
+        ## Tool Usage Examples
+        
+        Tool: current_datetime
+        Input: { "format": "natural" }
+        
+        Tool: get_summary
+        Input: { "symbol": "AAPL", "period": "1d", "interval": "1h" }
+        
+        Tool: get_market_sentiment
+        Input: { "symbol": "AAPL", "period": "1mo" }
+        
+        Tool: get_history
+        Input: { "symbol": "AAPL", "period": "1mo" }
+
+        ## Output Format Guidelines
+        
+        * Use **bold** for key financial metrics (e.g., Stock Symbol, Price, Volume).
+        * Cite the tools used to obtain the data (e.g., "Data sourced from Yahoo Finance as of [Date]").
+        * If a symbol or data point cannot be found, clearly state "Data for [X] is unavailable or invalid."
+        * Always include a disclaimer: "This analysis is for informational purposes only and is not financial advice."
+        """,
+)
+
+__all__ = ["yf_agent", "get_summary", "get_market_sentiment", "get_history", "current_datetime"]

common/mcp/README.md

@@ -0,0 +1,139 @@
+# MCP Tools Server
+
+A Model Context Protocol (MCP) server that exposes all tools from the `tools/` folder via stdio transport.
+
+## Features
+
+- **Dynamic Tool Discovery**: Automatically discovers and registers all tools from the tools folder
+- **Stdio Transport**: Compatible with Claude Desktop and other MCP clients
+- **Comprehensive Tool Coverage**: Exposes ~13 tools across 6 categories:
+  - Google Search (google_tools)
+  - News API (news_tools)
+  - DuckDuckGo Search (search_tools)
+  - Time Utilities (time_tools)
+  - Weather Forecast (weather_tools)
+  - Yahoo Finance (yf_tools)
+
+## Installation
+
+1. Install required dependencies:
+```bash
+pip install mcp requests beautifulsoup4 ddgs yfinance python-dotenv pydantic
+```
+
+2. Set up environment variables in `.env`:
+```bash
+# Google Search (Serper.dev)
+SERPER_API_KEY=your_serper_api_key
+
+# News API
+NEWS_API_KEY=your_news_api_key
+
+# Weather API
+OPENWEATHER_API_KEY=your_openweather_api_key
+
+# Google AI (for agents)
+GOOGLE_API_KEY=your_google_api_key
+
+# Groq (for agents)
+GROQ_API_KEY=your_groq_api_key
+```
+
+## Usage
+
+### Running the Server
+
+```bash
+cd common/mcp
+python mcp_server.py
+```
+
+The server will:
+1. Discover all tools from the `tools/` folder
+2. Print registered tools to stderr
+3. Start listening on stdio for MCP protocol messages
+
+### Integrating with Claude Desktop
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "tools-server": {
+      "command": "python",
+      "args": ["/absolute/path/to/agenticaiprojects/common/mcp/mcp_server.py"],
+      "env": {
+        "SERPER_API_KEY": "your_key",
+        "NEWS_API_KEY": "your_key",
+        "OPENWEATHER_API_KEY": "your_key"
+      }
+    }
+  }
+}
+```
+
+### Available Tools
+
+The server exposes the following tools:
+
+**Google Search:**
+- `google_tools.google_search` - General Google search
+- `google_tools.google_search_recent` - Time-filtered Google search
+
+**News:**
+- `news_tools.get_top_headlines` - Top headlines by country
+- `news_tools.search_news` - Search news by topic
+- `news_tools.get_news_by_category` - News by category
+
+**Search & Content:**
+- `search_tools.duckduckgo_search` - DuckDuckGo search
+- `search_tools.fetch_page_content` - Extract page content
+
+**Time:**
+- `time_tools.current_datetime` - Get current date/time
+
+**Weather:**
+- `weather_tools.get_weather_forecast` - Weather forecast via API
+- `weather_tools.search_weather_fallback_ddgs` - Weather via DuckDuckGo
+- `weather_tools.search_weather_fallback_bs` - Weather via web scraping
+
+**Finance:**
+- `yf_tools.get_summary` - Stock summary
+- `yf_tools.get_market_sentiment` - Market sentiment analysis
+- `yf_tools.get_history` - Historical stock data
+
+## Development
+
+### Adding New Tools
+
+1. Create a new file in `tools/` folder (e.g., `my_tools.py`)
+2. Decorate functions with `@function_tool`
+3. The server will automatically discover and register them on next restart
+
+### Testing
+
+```bash
+# Test the server
+cd common/mcp
+python mcp_server.py
+
+# In another terminal, you can send MCP protocol messages via stdin
+# Or use an MCP client library to test
+```
+
+## Troubleshooting
+
+**Tools not discovered:**
+- Check that functions are decorated with `@function_tool`
+- Verify the module is in the `tools/` folder
+- Check stderr output for registration messages
+
+**API errors:**
+- Verify environment variables are set correctly
+- Check API key validity
+- Review tool-specific error messages in stderr
+
+## License
+
+Part of the agenticaiprojects repository.

common/mcp/mcp_server.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""
+MCP Server with stdio transport that exposes all tools from the tools folder.
+"""
+import asyncio
+import sys
+import os
+import inspect
+import importlib
+from pathlib import Path
+from typing import Any, Callable
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import Tool, TextContent
+
+# Initialize MCP server
+app = Server("tools-server")
+
+# Dictionary to store all discovered tools
+TOOLS_REGISTRY: dict[str, Callable] = {}
+
+def discover_tools():
+    """
+    Dynamically discover all @function_tool decorated functions from the tools folder.
+    """
+    tools_dir = Path(__file__).parent / "tools"
+    tool_modules = [
+        "google_tools",
+        "news_tools", 
+        "search_tools",
+        "time_tools",
+        "weather_tools",
+        "yf_tools"
+    ]
+    
+    print(f"[MCP Server] Discovering tools from: {tools_dir}", file=sys.stderr)
+    
+    for module_name in tool_modules:
+        try:
+            # Import the module
+            module = importlib.import_module(f"mcp.tools.{module_name}")
+            
+            # Find all functions in the module
+            for name, obj in inspect.getmembers(module, inspect.isfunction):
+                # Check if it has the function_tool decorator
+                # The @function_tool decorator typically adds metadata to the function
+                if hasattr(obj, '__wrapped__') or name.startswith('_'):
+                    continue
+                    
+                # Check if it's a tool by looking for common patterns
+                if callable(obj) and not name.startswith('_'):
+                    # Register the tool
+                    tool_name = f"{module_name}.{name}"
+                    TOOLS_REGISTRY[tool_name] = obj
+                    print(f"[MCP Server] Registered tool: {tool_name}", file=sys.stderr)
+                    
+        except Exception as e:
+            print(f"[MCP Server] Error loading module {module_name}: {e}", file=sys.stderr)
+    
+    print(f"[MCP Server] Total tools registered: {len(TOOLS_REGISTRY)}", file=sys.stderr)
+
+
+@app.list_tools()
+async def list_tools() -> list[Tool]:
+    """
+    List all available tools.
+    """
+    tools = []
+    
+    for tool_name, tool_func in TOOLS_REGISTRY.items():
+        # Extract function signature and docstring
+        sig = inspect.signature(tool_func)
+        doc = inspect.getdoc(tool_func) or "No description available"
+        
+        # Build input schema from function parameters
+        properties = {}
+        required = []
+        
+        for param_name, param in sig.parameters.items():
+            param_type = "string"  # Default type
+            param_desc = ""
+            
+            # Try to infer type from annotation
+            if param.annotation != inspect.Parameter.empty:
+                annotation = param.annotation
+                if annotation == int:
+                    param_type = "integer"
+                elif annotation == bool:
+                    param_type = "boolean"
+                elif annotation == float:
+                    param_type = "number"
+            
+            properties[param_name] = {
+                "type": param_type,
+                "description": param_desc or f"Parameter: {param_name}"
+            }
+            
+            # Check if parameter is required (no default value)
+            if param.default == inspect.Parameter.empty:
+                required.append(param_name)
+        
+        # Create tool definition
+        tool = Tool(
+            name=tool_name,
+            description=doc.split('\n')[0][:200],  # First line, max 200 chars
+            inputSchema={
+                "type": "object",
+                "properties": properties,
+                "required": required
+            }
+        )
+        tools.append(tool)
+    
+    return tools
+
+
+@app.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
+    """
+    Execute a tool with the provided arguments.
+    """
+    print(f"[MCP Server] Calling tool: {name} with args: {arguments}", file=sys.stderr)
+    
+    if name not in TOOLS_REGISTRY:
+        raise ValueError(f"Tool not found: {name}")
+    
+    tool_func = TOOLS_REGISTRY[name]
+    
+    try:
+        # Call the tool function
+        if inspect.iscoroutinefunction(tool_func):
+            result = await tool_func(**arguments)
+        else:
+            result = tool_func(**arguments)
+        
+        # Convert result to string if needed
+        if not isinstance(result, str):
+            result = str(result)
+        
+        return [TextContent(type="text", text=result)]
+        
+    except Exception as e:
+        error_msg = f"Error executing tool {name}: {str(e)}"
+        print(f"[MCP Server] {error_msg}", file=sys.stderr)
+        return [TextContent(type="text", text=error_msg)]
+
+
+async def main():
+    """
+    Main entry point for the MCP server.
+    """
+    # Discover all tools before starting the server
+    discover_tools()
+    
+    print(f"[MCP Server] Starting MCP server with {len(TOOLS_REGISTRY)} tools", file=sys.stderr)
+    
+    # Run the server with stdio transport
+    async with stdio_server() as (read_stream, write_stream):
+        await app.run(
+            read_stream,
+            write_stream,
+            app.create_initialization_options()
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

common/mcp/tools/google_tools.py

@@ -0,0 +1,139 @@
+import os
+import requests
+from dotenv import load_dotenv
+from agents import function_tool
+from typing import Optional
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+# ============================================================
+# 🔹 GOOGLE SEARCH TOOLSET (Serper.dev API)
+# ============================================================
+
+@function_tool
+def google_search(query: str, num_results: int = 3) -> str:
+    """
+    Perform a general Google search using Serper.dev API.
+
+    Parameters:
+    -----------
+    query : str
+        The search query string, e.g., "latest Tesla stock news".
+    num_results : int, optional (default=3)
+        Maximum number of search results to return.
+
+    Returns:
+    --------
+    str
+        Formatted string of top search results, each including:
+        - Title of the page
+        - URL link
+        - Snippet / description
+        If no results are found or API key is missing, returns an error message.
+
+    Example:
+    --------
+    google_search("AI in finance", num_results=2)
+
+    Output:
+    Title: How AI is Transforming Finance
+    Link: https://example.com/ai-finance
+    Snippet: AI is increasingly used for trading, risk management...
+    
+    Title: AI Applications in Banking
+    Link: https://example.com/ai-banking
+    Snippet: Banks are leveraging AI for customer service, fraud detection...
+    """
+    print(f"[DEBUG] google_search called with query='{query}', num_results={num_results}")
+    
+    try:
+        api_key = os.getenv("SERPER_API_KEY")
+        if not api_key:
+            return "Error: SERPER_API_KEY missing in environment variables."
+
+        url = "https://google.serper.dev/search"
+        headers = {"X-API-KEY": api_key, "Content-Type": "application/json"}
+        payload = {"q": query, "num": num_results, "tbs": "qdr:d"}  # results from last 24h
+
+        response = requests.post(url, headers=headers, json=payload, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+
+        if "organic" not in data or not data["organic"]:
+            return f"No results found for query: '{query}'"
+
+        formatted_results = [
+            f"Title: {item.get('title')}\n"
+            f"Link: {item.get('link')}\n"
+            f"Snippet: {item.get('snippet', '')}\n"
+            for item in data["organic"][:num_results]
+        ]
+        return "\n".join(formatted_results)
+
+    except requests.exceptions.RequestException as e:
+        print(f"[DEBUG] Network error during Google search: {e}")
+        return f"Network error during Google search: {e}"
+    except Exception as e:
+        print(f"[DEBUG] Error performing Google search: {e}")
+        return f"Error performing Google search: {e}"
+
+
+@function_tool
+def google_search_recent(query: str, num_results: int = 3, timeframe: str = "d") -> str:
+    """
+    Perform a Google search with time-based filtering using Serper.dev API.
+
+    Parameters:
+    -----------
+    query : str
+        The search query string.
+    num_results : int, optional (default=3)
+        Maximum number of search results to return.
+    timeframe : str, optional (default="d")
+        Time range for results:
+        - "d" = past day
+        - "w" = past week
+        - "m" = past month
+        - "y" = past year
+
+    Returns:
+    --------
+    str
+        Formatted string of recent search results.
+    """
+    print(f"[DEBUG] google_search_recent called with query='{query}', timeframe={timeframe}")
+    
+    try:
+        api_key = os.getenv("SERPER_API_KEY")
+        if not api_key:
+            return "Error: SERPER_API_KEY missing in environment variables."
+
+        url = "https://google.serper.dev/search"
+        headers = {"X-API-KEY": api_key, "Content-Type": "application/json"}
+        payload = {"q": query, "num": num_results, "tbs": f"qdr:{timeframe}"}
+
+        response = requests.post(url, headers=headers, json=payload, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+
+        if "organic" not in data or not data["organic"]:
+            return f"No recent results found for query: '{query}'"
+
+        formatted_results = [
+            f"Title: {item.get('title')}\n"
+            f"Link: {item.get('link')}\n"
+            f"Snippet: {item.get('snippet', '')}\n"
+            for item in data["organic"][:num_results]
+        ]
+        
+        return f"Recent results ({timeframe}):\n\n" + "\n".join(formatted_results)
+
+    except requests.exceptions.RequestException as e:
+        print(f"[DEBUG] Network error: {e}")
+        return f"Network error during Google search: {e}"
+    except Exception as e:
+        print(f"[DEBUG] Error: {e}")
+        return f"Error performing Google search: {e}"

common/mcp/tools/news_tools.py

@@ -0,0 +1,200 @@
+import os
+import requests
+from dotenv import load_dotenv
+from agents import function_tool
+from typing import Optional
+import datetime
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+# ============================================================
+# 🔹 NEWS TOOLSET (NewsAPI.org)
+# ============================================================
+
+@function_tool
+def get_top_headlines(country: str = "us", num_results: int = 5) -> str:
+    """
+    Fetch the latest top headlines for a country using NewsAPI.org.
+
+    Parameters:
+    -----------
+    country : str, optional (default="us")
+        Two-letter country code (e.g., "us", "gb", "in").
+    num_results : int, optional (default=5)
+        Number of articles to fetch.
+
+    Returns:
+    --------
+    str
+        Formatted headlines with title, source, published date, and URL.
+        If API key is missing or no results found, returns an error message.
+    """
+    print(f"[DEBUG] get_top_headlines called for country={country}, num_results={num_results}")
+    
+    try:
+        api_key = os.getenv("NEWS_API_KEY")
+        if not api_key:
+            return "Error: NEWS_API_KEY missing in environment variables."
+
+        url = "https://newsapi.org/v2/top-headlines"
+        params = {
+            "country": country,
+            "pageSize": num_results,
+            "apiKey": api_key
+        }
+
+        response = requests.get(url, params=params, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+
+        if not data.get("articles"):
+            return f"No top headlines found for country: {country}"
+
+        formatted = []
+        for article in data["articles"][:num_results]:
+            formatted.append(
+                f"📰 {article.get('title')}\n"
+                f"   Source: {article.get('source', {}).get('name')}\n"
+                f"   Published: {article.get('publishedAt', 'N/A')}\n"
+                f"   URL: {article.get('url')}\n"
+            )
+        
+        return f"Top Headlines ({country.upper()}):\n\n" + "\n".join(formatted)
+
+    except requests.exceptions.RequestException as e:
+        print(f"[DEBUG] Network error: {e}")
+        return f"Network error while calling News API: {e}"
+    except Exception as e:
+        print(f"[DEBUG] Error: {e}")
+        return f"Unexpected error fetching news: {e}"
+
+
+@function_tool
+def search_news(query: str, num_results: int = 5, days_back: int = 7) -> str:
+    """
+    Search for recent news articles about a specific topic using NewsAPI.org.
+
+    Parameters:
+    -----------
+    query : str
+        Keyword or topic to search (e.g., "Tesla earnings", "AI healthcare").
+    num_results : int, optional (default=5)
+        Number of articles to fetch.
+    days_back : int, optional (default=7)
+        Number of days to look back for articles (1-30).
+
+    Returns:
+    --------
+    str
+        Formatted news articles with title, source, published date, and URL.
+        If API key is missing or no results found, returns an error message.
+    """
+    print(f"[DEBUG] search_news called with query='{query}', num_results={num_results}, days_back={days_back}")
+    
+    try:
+        api_key = os.getenv("NEWS_API_KEY")
+        if not api_key:
+            return "Error: NEWS_API_KEY missing in environment variables."
+
+        # Calculate date range
+        today = datetime.datetime.utcnow()
+        from_date = (today - datetime.timedelta(days=days_back)).strftime('%Y-%m-%dT%H:%M:%SZ')
+
+        url = "https://newsapi.org/v2/everything"
+        params = {
+            "q": query,
+            "pageSize": num_results,
+            "apiKey": api_key,
+            "sortBy": "publishedAt",
+            "language": "en",
+            "from": from_date
+        }
+
+        response = requests.get(url, params=params, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+
+        if not data.get("articles"):
+            return f"No news found for query: '{query}'"
+
+        formatted = []
+        for article in data["articles"][:num_results]:
+            formatted.append(
+                f"📰 {article.get('title')}\n"
+                f"   Source: {article.get('source', {}).get('name')}\n"
+                f"   Published: {article.get('publishedAt', 'N/A')}\n"
+                f"   URL: {article.get('url')}\n"
+            )
+        
+        return f"News Search Results for '{query}' (last {days_back} days):\n\n" + "\n".join(formatted)
+
+    except requests.exceptions.RequestException as e:
+        print(f"[DEBUG] Network error: {e}")
+        return f"Network error while calling News API: {e}"
+    except Exception as e:
+        print(f"[DEBUG] Error: {e}")
+        return f"Unexpected error fetching news: {e}"
+
+
+@function_tool
+def get_news_by_category(category: str = "business", country: str = "us", num_results: int = 5) -> str:
+    """
+    Fetch top headlines by category using NewsAPI.org.
+
+    Parameters:
+    -----------
+    category : str, optional (default="business")
+        News category: "business", "entertainment", "general", "health", 
+        "science", "sports", "technology".
+    country : str, optional (default="us")
+        Two-letter country code.
+    num_results : int, optional (default=5)
+        Number of articles to fetch.
+
+    Returns:
+    --------
+    str
+        Formatted headlines for the specified category.
+    """
+    print(f"[DEBUG] get_news_by_category called for category={category}, country={country}")
+    
+    try:
+        api_key = os.getenv("NEWS_API_KEY")
+        if not api_key:
+            return "Error: NEWS_API_KEY missing in environment variables."
+
+        url = "https://newsapi.org/v2/top-headlines"
+        params = {
+            "category": category,
+            "country": country,
+            "pageSize": num_results,
+            "apiKey": api_key
+        }
+
+        response = requests.get(url, params=params, timeout=10)
+        response.raise_for_status()
+        data = response.json()
+
+        if not data.get("articles"):
+            return f"No headlines found for category: {category}"
+
+        formatted = []
+        for article in data["articles"][:num_results]:
+            formatted.append(
+                f"📰 {article.get('title')}\n"
+                f"   Source: {article.get('source', {}).get('name')}\n"
+                f"   Published: {article.get('publishedAt', 'N/A')}\n"
+                f"   URL: {article.get('url')}\n"
+            )
+        
+        return f"Top {category.capitalize()} Headlines ({country.upper()}):\n\n" + "\n".join(formatted)
+
+    except requests.exceptions.RequestException as e:
+        print(f"[DEBUG] Network error: {e}")
+        return f"Network error while calling News API: {e}"
+    except Exception as e:
+        print(f"[DEBUG] Error: {e}")
+        return f"Unexpected error fetching news: {e}"

common/mcp/tools/rag_tool.py

@@ -0,0 +1,106 @@
+"""RAG Search Tool - Search the local healthcare knowledge base"""
+import os
+from pathlib import Path
+from agents import function_tool, RunContextWrapper
+from dotenv import load_dotenv
+from rag.rag import Retriever
+from dataclasses import dataclass
+
+
+@dataclass
+class UserContext:
+    uid: str
+    db_path: str = ""
+    file_path: str = ""
+    similarity_threshold: float = 0.4  # FAISS L2 distance threshold for RAG relevance
+
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+# ---------------------------------------------------------
+# Initialize RAG Retriever
+# ---------------------------------------------------------
+# Get the healthcare-rag-chatbot directory path
+# healthcare_dir = str(Path(__file__).parent.parent.parent)
+# retriever = None
+
+# ---------------------------------------------------------
+# RAG Search Tool
+# ---------------------------------------------------------
+@function_tool
+def rag_search(wrapper: RunContextWrapper[UserContext], query: str) -> str:
+    """
+    Search the local healthcare knowledge base for relevant information.
+    
+    Args:
+        query: The medical question or topic to search for
+        
+    Returns:
+        Relevant information from the healthcare knowledge base
+    """
+    print(f"[DEBUG] RAG_SEARCH called with query: '{query}'")
+    
+    # Get similarity threshold from user context
+    similarity_threshold = wrapper.context.similarity_threshold
+    print(f"[DEBUG] RAG_SEARCH: Using similarity threshold: {similarity_threshold}")
+    
+    try:
+        # Initialize retriever with user context
+        retriever = Retriever(
+            db_path=wrapper.context.db_path,
+            file_path=wrapper.context.file_path
+        )
+
+        # Get results with similarity scores
+        results_with_scores = retriever.retrieve_with_scores(query, k=5)  # Increased from 4 to 5
+        
+        if not results_with_scores:
+            print("[DEBUG] RAG_SEARCH: No results found in knowledge base")
+            return "No relevant information found in the knowledge base."
+        
+        print(f"[DEBUG] RAG_SEARCH: Found {len(results_with_scores)} results")
+        
+        # Check if the best match meets the threshold
+        # FAISS returns (document, distance) where lower distance = better match
+        best_score = results_with_scores[0][1]
+        print(f"[DEBUG] RAG_SEARCH: Best similarity score (distance): {best_score:.4f} (threshold: {similarity_threshold})")
+        
+        if best_score > similarity_threshold:
+            print(f"[DEBUG] RAG_SEARCH: Best match score {best_score:.4f} is above threshold {similarity_threshold}")
+            print("[DEBUG] RAG_SEARCH: Results not relevant enough, triggering web search fallback")
+            return "No relevant information found in the knowledge base."
+        
+        print(f"[DEBUG] RAG_SEARCH: Results are relevant (score: {best_score:.4f} <= {similarity_threshold})")
+        
+        # Log all scores for debugging
+        all_scores = [f"{score:.4f}" for _, score in results_with_scores]
+        print(f"[DEBUG] RAG_SEARCH: All scores: {', '.join(all_scores)}")
+        
+        # Format results - only include documents that meet the similarity threshold
+        formatted_results = []
+        for i, (doc, score) in enumerate(results_with_scores[:5], 1):  # Top 5 results
+            if score <= similarity_threshold:
+                content = doc.page_content.strip()
+                formatted_results.append(f"Result {i} (score: {score:.4f}):\n{content}\n")
+        
+        if not formatted_results:
+            print("[DEBUG] RAG_SEARCH: No results met the similarity threshold")
+            print("[DEBUG] RAG_SEARCH: Triggering web search fallback")
+            return "No relevant information found in the knowledge base."
+        
+        result_text = "\n".join(formatted_results)
+        print(f"[DEBUG] RAG_SEARCH: Returning {len(formatted_results)} results, total length: {len(result_text)} characters")
+        print(f"[DEBUG] RAG_SEARCH: First 300 chars: {result_text[:300]}...")
+        
+        return result_text
+        
+    except Exception as e:
+        print(f"[DEBUG] RAG_SEARCH: Error occurred - {str(e)}")
+        return f"Error retrieving from knowledge base: {str(e)}"
+
+
+
+__all__ = ["rag_search", "retriever"]

common/mcp/tools/search_tools.py

@@ -0,0 +1,115 @@
+from ddgs import DDGS
+from agents import function_tool
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+import requests
+from bs4 import BeautifulSoup
+from typing import Optional
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+# ---------------------- MODELS ---------------------------
+class searchQuery(BaseModel):
+    query: str = Field(..., description="The search query string.")
+    max_results: int = Field(5, description="The maximum number of search results to return.")
+    search_type: str = Field(
+        "text",
+        description="Search type: 'text' (default) or 'news'. Use 'news' to get publication dates."
+    )
+    timelimit: str = Field(
+        'd',
+        description="Time limit for search results: 'd' (day), 'w' (week), 'm' (month), 'y' (year)."
+    )
+    region: str = Field("us-en", description="Region for search results (e.g., 'us-en').")
+
+
+class searchResult(BaseModel):
+    title: str
+    link: str
+    snippet: str
+    datetime: Optional[str] = None
+
+
+# ---------------------- PAGE FETCH TOOL ---------------------------
+@function_tool
+def fetch_page_content(url: str, timeout: int = 3) -> Optional[str]:
+    """Fetch and extract text content from a web page."""
+    print(f"[DEBUG] fetch_page_content called with: {url} - timeout: {timeout}")
+    try:
+        headers = {
+            'User-Agent': (
+                'Mozilla/5.0 (Windows NT 10.0; Win64; x64) '
+                'AppleWebKit/537.36 (KHTML, like Gecko) '
+                'Chrome/91.0.4472.124 Safari/537.36'
+            )
+        }
+        response = requests.get(url, headers=headers, timeout=timeout)
+        response.raise_for_status()
+
+        soup = BeautifulSoup(response.content, 'html.parser')
+
+        # Remove irrelevant elements
+        for tag in soup(["script", "style", "nav", "footer", "header"]):
+            tag.decompose()
+
+        # Extract text
+        text = soup.get_text(separator='\n', strip=True)
+
+        # Clean whitespace
+        lines = (line.strip() for line in text.splitlines())
+        chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
+        text = '\n'.join(chunk for chunk in chunks if chunk)
+
+        return text
+    except Exception as e:
+        print(f"[WARNING] Failed to fetch content from {url}: {str(e)}")
+        return None
+
+
+# ---------------------- SEARCH TOOL ---------------------------
+@function_tool
+def duckduckgo_search(params: searchQuery) -> list[dict]:
+    """Perform a DuckDuckGo search and return only snippets.  
+    No page content fetched here."""
+    print(f"[DEBUG] duckduckgo_search called with: {params}")
+
+    results = []
+    with DDGS() as ddgs:
+        if params.search_type == "news":
+            search_results = ddgs.news(
+                params.query,
+                max_results=params.max_results,
+                timelimit=params.timelimit,
+                region=params.region
+            )
+            for result in search_results:
+                results.append(
+                    searchResult(
+                        title=result.get("title", ""),
+                        link=result.get("url", ""),
+                        snippet=result.get("body", ""),
+                        datetime=result.get("date", "")
+                    ).model_dump()
+                )
+        else:
+            search_results = ddgs.text(
+                params.query,
+                max_results=params.max_results,
+                timelimit=params.timelimit,
+                region=params.region
+            )
+            for result in search_results:
+                results.append(
+                    searchResult(
+                        title=result.get("title", ""),
+                        link=result.get("href", ""),
+                        snippet=result.get("body", "")
+                    ).model_dump()
+                )
+
+    print(f"[DEBUG] duckduckgo_search returning {len(results)} results")
+    return results
+

common/mcp/tools/time_tools.py

@@ -0,0 +1,32 @@
+from datetime import datetime
+from agents import function_tool
+# from ..common.utility.logger import log_call
+
+@function_tool
+# @log_call
+def current_datetime(format: str = "natural") -> str:
+    """
+    Returns the current date and time as a formatted string.
+    
+    Args:
+        format (str): Format style for the datetime. Options:
+            - "natural" (default): "Saturday, December 7, 2025 at 3:59 PM"
+            - "natural_short": "Dec 7, 2025 at 3:59 PM"
+            - "natural_full": "Saturday, December 7, 2025 at 3:59:30 PM CST"
+            - Custom strftime format string (e.g., "%Y-%m-%d %H:%M:%S")
+    
+    Returns:
+        str: Current date and time in the specified format
+    """
+    now = datetime.now()
+    
+    # Natural format options
+    if format == "natural":
+        return now.strftime("%A, %B %d, %Y at %I:%M %p")
+    elif format == "natural_short":
+        return now.strftime("%b %d, %Y at %I:%M %p")
+    elif format == "natural_full":
+        return now.strftime("%A, %B %d, %Y at %I:%M:%S %p %Z")
+    else:
+        # Custom format string
+        return now.strftime(format)

common/mcp/tools/weather_tools.py

@@ -0,0 +1,235 @@
+import os
+import re
+import requests
+import datetime
+from dotenv import load_dotenv
+from typing import Optional
+
+from ddgs import DDGS
+from agents import function_tool
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+load_dotenv()
+
+@function_tool
+def get_weather_forecast(city: str, date: Optional[str] = None) -> str:
+    """
+    PRIMARY TOOL: Fetch weather using OpenWeatherMap API.
+    """
+    print(f"[DEBUG] Primary API get_weather_forecast called for city={city}")
+
+    api_key = os.getenv("OPENWEATHER_API_KEY")
+    if not api_key:
+        return "Error: OPENWEATHER_API_KEY missing. Please use the fallback search tool."
+
+    url = "https://api.openweathermap.org/data/2.5/forecast"
+
+    try:
+        response = requests.get(
+            url,
+            params={"q": city, "appid": api_key, "units": "metric"},
+            timeout=5
+        )
+        data = response.json()
+    except Exception as e:
+        return f"Error calling weather API: {str(e)}"
+
+    if str(data.get("cod")) != "200":
+        return f"Error from API: {data.get('message', 'Unknown error')}"
+
+    # Build the report string
+    report_lines = []
+    found_date = False
+
+    for entry in data.get("list", []):
+        dt_txt = entry["dt_txt"].split(" ")[0]
+
+        if date and dt_txt != date:
+            continue
+        
+        found_date = True
+        desc = entry['weather'][0]['description'].capitalize()
+        temp = entry['main']['temp']
+        hum = entry['main']['humidity']
+        wind = entry['wind']['speed']
+        
+        report_lines.append(f"{dt_txt}: {desc}, Temp: {temp}°C, Humidity: {hum}%, Wind: {wind} m/s")
+
+    # Handle "Date not found" case
+    if date and not found_date:
+        return f"API valid, but date {date} is out of range (5-day limit). Try the search fallback tool."
+
+    final_report = "\n".join(report_lines)
+
+    return f"API Forecast for {city}:\n{final_report}"
+
+# ---------------------------------------------------------
+# Tool 2: Web Search Fallback (Secondary)
+# ---------------------------------------------------------
+
+@function_tool
+def search_weather_fallback_ddgs(city: str, date: Optional[str] = None) -> str:
+    """
+    SECONDARY TOOL: Search-based fallback that produces an API-like structured forecast.
+    """
+    print(f"[DEBUG] Fallback API (DDGS) called for city={city}, date={date}")
+
+    # --- Build Query ---
+    try:
+        if date:
+            try:
+                dt_obj = datetime.strptime(date, "%Y-%m-%d")
+                natural_date = dt_obj.strftime("%B %d, %Y")
+                month_name = dt_obj.strftime("%B")
+            except ValueError:
+                natural_date = date
+                month_name = ""
+        else:
+            natural_date = datetime.now().strftime("%B %d, %Y")
+            month_name = natural_date.split()[0]  # Month name
+
+        query = f"weather {city} {natural_date}"
+        print(f"[DEBUG] Search query: {query}")
+
+        # --- Perform Search ---
+        results = list(DDGS().text(query, max_results=3))
+        print(f"[DEBUG] Number of search results: {len(results)}")
+
+        if not results:
+            return f"Web Estimated Forecast for {city}:\nNo reliable search data found."
+
+        # --- Aggregate Text ---
+        full_text = " ".join([r.get("body", "") for r in results])
+
+        # --- Extract Values with Robust Regex ---
+        temp_match = re.findall(r'(-?\d+)\s*(?:°|deg|C|F)', full_text, re.I)
+        temperature = temp_match[0] if temp_match else "?"
+
+        humidity_match = re.findall(r'(\d+)\s*%', full_text)
+        humidity = humidity_match[0] if humidity_match else "?"
+
+        wind_match = re.findall(r'(\d+)\s*(?:mph|km/h|m/s)', full_text, re.I)
+        wind = wind_match[0] if wind_match else "?"
+
+        # --- Condition ---
+        # Take first word(s) of first title as best guess
+        condition_raw = results[0].get("title", "Unknown").split("-")[0].strip()
+        condition = condition_raw[0].upper() + condition_raw[1:] if condition_raw else "Unknown"
+
+        # --- Construct API-like Forecast ---
+        forecast = (
+            f"Web Estimated Forecast for {city}:\n"
+            f"{natural_date}: {condition}, Temp: {temperature}° (approx), "
+            f"Humidity: {humidity}%, Wind: {wind}\n"
+        )
+
+        # Optional: add raw snippets for debugging
+        # snippet_block = "\nSearch Snippets (Raw):\n" + "\n".join(
+        #     f"- {r['title']}: {r['body']}" for r in results
+        # )
+        # return forecast + snippet_block
+
+        return forecast
+
+    except Exception as e:
+        print(f"[DEBUG] Error in fallback: {e}")
+        return f"Error performing web search: {str(e)}"
+
+
+import requests
+from bs4 import BeautifulSoup
+import re
+from typing import Optional
+from agents import function_tool
+from datetime import datetime
+
+@function_tool
+def search_weather_fallback_bs(city: str, date: Optional[str] = None) -> str:
+    """
+    SECONDARY TOOL: Web-scraping fallback using BeautifulSoup.
+    Produces an API-like structured forecast.
+    """
+    import requests
+    from bs4 import BeautifulSoup
+    import re
+    from datetime import datetime
+
+    print(f"[DEBUG] Fallback API (BeautifulSoup) called for city={city}, date={date}")
+
+    try:
+        # --- Build Query ---
+        if date:
+            try:
+                dt_obj = datetime.strptime(date, "%Y-%m-%d")
+                natural_date = dt_obj.strftime("%B %d, %Y")
+            except ValueError:
+                natural_date = date
+        else:
+            natural_date = datetime.now().strftime("%B %d, %Y")
+
+        query = f"weather {city} {natural_date}"
+        print(f"[DEBUG] Search query: {query}")
+
+        # --- DuckDuckGo Search ---
+        search_url = f"https://duckduckgo.com/html/?q={query.replace(' ', '+')}"
+        headers = {"User-Agent": "Mozilla/5.0"}
+        response = requests.get(search_url, headers=headers, timeout=5)
+        if response.status_code != 200:
+            return f"Error fetching search results: {response.status_code}"
+
+        soup = BeautifulSoup(response.text, "html.parser")
+        results = []
+        for result in soup.select(".result__body"):
+            title_tag = result.select_one(".result__title a")
+            snippet_tag = result.select_one(".result__snippet")
+            if title_tag and snippet_tag:
+                results.append({
+                    "title": title_tag.get_text(strip=True),
+                    "body": snippet_tag.get_text(strip=True)
+                })
+
+        if not results:
+            return f"Web Estimated Forecast for {city}:\nNo reliable search data found."
+
+        # --- Aggregate Text ---
+        full_text = " ".join([r["body"] for r in results])
+
+        # --- Extract Temperature ---
+        temp_matches = re.findall(r'(-?\d{1,2})\s*(?:°|deg|C|F)', full_text, re.I)
+        temperature = temp_matches[0] if temp_matches else "?"
+
+        # --- Extract Humidity ---
+        humidity_matches = re.findall(r'(\d{1,3})\s*%', full_text)
+        humidity = humidity_matches[0] if humidity_matches else "?"
+
+        # --- Extract Wind ---
+        wind_matches = re.findall(r'(\d{1,3})\s*(?:mph|km/h|m/s)', full_text, re.I)
+        wind = wind_matches[0] if wind_matches else "?"
+
+        # --- Extract Condition ---
+        # Look in all results first, fallback to first title
+        condition = "Unknown"
+        for r in results:
+            m = re.search(r'(clear|sunny|cloudy|rain|snow|storm|fog|mist)', r["body"], re.I)
+            if m:
+                condition = m.group(1).capitalize()
+                break
+        if condition == "Unknown":
+            # Fallback
+            condition_raw = results[0]["title"].split("-")[0].strip()
+            condition = condition_raw[0].upper() + condition_raw[1:] if condition_raw else "Unknown"
+
+        # --- Build Forecast ---
+        forecast = (
+            f"Web Estimated Forecast for {city}:\n"
+            f"{natural_date}: {condition}, Temp: {temperature}° (approx), "
+            f"Humidity: {humidity}%, Wind: {wind}\n"
+        )
+
+        return forecast
+
+    except Exception as e:
+        print(f"[DEBUG] Error in fallback: {e}")
+        return f"Error performing web search: {str(e)}"

common/mcp/tools/yf_tools.py

@@ -0,0 +1,192 @@
+import os
+import requests
+import yfinance as yf
+from dotenv import load_dotenv
+from agents import function_tool
+from datetime import datetime, timedelta
+
+# Load environment variables
+load_dotenv()
+
+
+# ============================================================
+# 🔹 YAHOO FINANCE TOOLSET
+# ============================================================
+@function_tool
+def get_summary(symbol: str, period: str = "1d", interval: str = "1h") -> str:
+    """
+    Fetch the latest summary information and intraday price data for a given ticker.
+    Ensures recent data is retrieved by calculating start/end dates dynamically.
+
+    Parameters:
+    -----------
+    symbol : str
+        The ticker symbol (e.g., "AAPL", "GOOG", "BTC-USD").
+    period : str, optional (default="1d")
+        Time range for price data. Examples: "1d", "5d", "1mo", "3mo".
+    interval : str, optional (default="1h")
+        Granularity of the data. Examples: "1m", "5m", "1h", "1d".
+
+    Returns:
+    --------
+    str
+        A formatted string containing:
+        - Company/ticker name
+        - Current price and change
+        - Open, High, Low prices
+        - Volume
+        - Period and interval used
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+
+        # Calculate start and end dates based on period
+        end_date = datetime.today()
+        if period.endswith("d"):
+            days = int(period[:-1])
+        elif period.endswith("mo"):
+            days = int(period[:-2]) * 30
+        elif period.endswith("y"):
+            days = int(period[:-1]) * 365
+        else:
+            days = 30  # default 1 month
+        start_date = end_date - timedelta(days=days)
+
+        # Fetch recent data explicitly
+        data = ticker.history(
+            start=start_date.strftime("%Y-%m-%d"),
+            end=end_date.strftime("%Y-%m-%d"),
+            interval=interval
+        )
+
+        if data.empty:
+            return f"No data found for symbol '{symbol}'."
+
+        latest = data.iloc[-1]
+        current_price = round(latest["Close"], 2)
+        open_price = round(latest["Open"], 2)
+        change = round(current_price - open_price, 2)
+        pct_change = round((change / open_price) * 100, 2)
+
+        info = ticker.info
+        long_name = info.get("longName", symbol)
+        currency = info.get("currency", "USD")
+
+        formatted = [
+            f"📈 {long_name} ({symbol})",
+            f"Current Price: {current_price} {currency}",
+            f"Change: {change} ({pct_change}%)",
+            f"Open: {open_price} | High: {round(latest['High'], 2)} | Low: {round(latest['Low'], 2)}",
+            f"Volume: {int(latest['Volume'])}",
+            f"Period: {period} | Interval: {interval}",
+        ]
+        return "\n".join(formatted)
+
+    except Exception as e:
+        return f"Error fetching data for '{symbol}': {e}"
+
+@function_tool
+def get_market_sentiment(symbol: str, period: str = "1mo") -> str:
+    """
+    Analyze recent price changes and provide a simple market sentiment.
+    Uses dynamic start/end dates to ensure recent data.
+
+    This tool computes the percentage change over the specified period and
+    classifies the sentiment as:
+    - Bullish (if price increased >2%)
+    - Bearish (if price decreased >2%)
+    - Neutral (otherwise)
+
+    Parameters:
+    -----------
+    symbol : str
+        The ticker symbol (e.g., "AAPL", "GOOG", "BTC-USD").
+    period : str, optional (default="1mo")
+        Time range to analyze. Examples: "7d", "1mo", "3mo".
+
+    Returns:
+    --------
+    str
+        A human-readable sentiment string including percentage change.
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+
+        # Calculate start/end dynamically
+        end_date = datetime.today()
+        if period.endswith("d"):
+            days = int(period[:-1])
+        elif period.endswith("mo"):
+            days = int(period[:-2]) * 30
+        elif period.endswith("y"):
+            days = int(period[:-1]) * 365
+        else:
+            days = 30
+        start_date = end_date - timedelta(days=days)
+
+        data = ticker.history(
+            start=start_date.strftime("%Y-%m-%d"),
+            end=end_date.strftime("%Y-%m-%d")
+        )
+
+        if data.empty:
+            return f"No data for {symbol}."
+
+        recent_change = data["Close"].iloc[-1] - data["Close"].iloc[0]
+        pct_change = (recent_change / data["Close"].iloc[0]) * 100
+
+        sentiment = "Neutral"
+        if pct_change > 2:
+            sentiment = "Bullish"
+        elif pct_change < -2:
+            sentiment = "Bearish"
+
+        return f"{symbol} market sentiment ({period}): {sentiment} ({pct_change:.2f}% change)"
+
+    except Exception as e:
+        return f"Error fetching market sentiment for '{symbol}': {e}"
+
+@function_tool
+def get_history(symbol: str, period: str = "1mo") -> str:
+    """
+    Fetch historical price data for a given ticker.
+    Ensures recent data is retrieved dynamically using start/end dates.
+
+    Parameters:
+    -----------
+    symbol : str
+        The ticker symbol (e.g., "AAPL", "GOOG", "BTC-USD").
+    period : str, optional (default="1mo")
+        The length of historical data to retrieve. Examples: "1d", "5d", "1mo", "3mo", "1y", "5y".
+
+    Returns:
+    --------
+    str
+        A formatted string showing the last 5 rows of historical prices (Open, High, Low, Close, Volume).
+    """
+    try:
+        ticker = yf.Ticker(symbol)
+
+        # Calculate start/end dynamically
+        end_date = datetime.today()
+        if period.endswith("d"):
+            days = int(period[:-1])
+        elif period.endswith("mo"):
+            days = int(period[:-2]) * 30
+        elif period.endswith("y"):
+            days = int(period[:-1]) * 365
+        else:
+            days = 30
+        start_date = end_date - timedelta(days=days)
+
+        data = ticker.history(
+            start=start_date.strftime("%Y-%m-%d"),
+            end=end_date.strftime("%Y-%m-%d")
+        )
+
+        if data.empty:
+            return f"No historical data found for '{symbol}'."
+        return f"Historical data for {symbol} ({period}):\n{data.tail(5).to_string()}"
+
+    except Exception as e:
+        return f"Error fetching historical data for '{symbol}': {e}"

common/rag/rag.py

@@ -0,0 +1,94 @@
+import os
+import shutil
+from langchain_community.document_loaders import PyPDFLoader, DirectoryLoader
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_community.vectorstores import FAISS
+
+DB_NAME = 'healthcare_db'
+DIRECTORY_NAME = "healthcare"
+
+class Retriever:
+    def __init__(self,  
+                        file_path:str = os.path.join(os.getcwd(), "data"), 
+                        db_path:str = os.path.join(os.getcwd(), "db") ):
+        self.directory_path = os.path.join(file_path, DIRECTORY_NAME)
+        self.db_path = os.path.join(db_path, DB_NAME)
+        self.embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")
+        self.text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=1024,
+            chunk_overlap=200,
+            length_function=len,
+            # separators=["\n\n", "\n", ".", "!", "?", ",", " ", ""],
+            is_separator_regex=False,
+        )
+        self.retriever = None
+
+    def load_knowledge_base(self):
+        if os.path.exists(self.db_path):
+            self.retriever = FAISS.load_local(
+                self.db_path, 
+                self.embeddings,
+                allow_dangerous_deserialization=True
+            ).as_retriever()
+        else:
+            self.retriever = self._create_knowledge_base()
+
+    def _create_knowledge_base(self):
+        documents = self._load_documents()
+        chunks = self._split_documents(documents)
+        # embeddings = self._embed_documents(texts)
+        vectorstore = FAISS.from_documents(chunks, self.embeddings)
+        vectorstore.save_local(self.db_path)
+        return vectorstore.as_retriever()
+
+    def _load_documents(self):
+        documents = []
+        loader = DirectoryLoader(
+            self.directory_path,
+            glob="**/*.pdf",
+            loader_cls=PyPDFLoader,
+            show_progress=True
+        )
+        documents = loader.load()
+        return documents
+
+    def _split_documents(self, documents):
+        chunks = []
+        for doc in documents:
+            chunks.extend(self.text_splitter.split_documents([doc]))
+        return chunks
+
+    # def _embed_documents(self, texts):
+    #     return [self.embeddings.embed_query(text.page_content) for text in texts]   
+
+    def retrieve(self, query, k=4):
+        """Retrieve documents without scores (backward compatible)"""
+        if not self.retriever:
+            self.load_knowledge_base()
+        return self.retriever.invoke(query)
+    
+    def retrieve_with_scores(self, query, k=4):
+        """Retrieve documents with similarity scores"""
+        if not self.retriever:
+            self.load_knowledge_base()
+        
+        # Get the underlying vectorstore from the retriever
+        vectorstore = self.retriever.vectorstore
+        
+        # Use similarity_search_with_score to get scores
+        # Note: FAISS returns L2 distance, lower is better
+        results = vectorstore.similarity_search_with_score(query, k=k)
+        
+        return results
+
+
+    def update_knowledge_base(self):
+        self._create_knowledge_base()
+
+    def delete_knowledge_base(self):
+        if os.path.exists(self.db_path):
+            shutil.rmtree(self.db_path) 
+
+    # No cleanup needed for VectorStoreRetriever
+    

common/utility/embedding_factory.py

@@ -0,0 +1,49 @@
+import os
+from typing import Union
+# from azure.identity import DefaultAzureCredential
+from langchain_openai import AzureOpenAIEmbeddings, OpenAIEmbeddings
+from langchain_ollama import OllamaEmbeddings
+from langchain_huggingface import HuggingFaceEmbeddings
+
+
+class EmbeddingFactory:
+    """
+    A static utility class to create and return LLM Embedding instances based on the input type.
+    """
+
+    @staticmethod
+    def get_llm(llm_type: str) -> Union[AzureOpenAIEmbeddings, OpenAIEmbeddings]:
+        """
+        Returns an LLM instance based on the specified type.
+
+        Parameters:
+            llm_type (str): The type of LLM to return. Valid values are 'azure' or 'openai'.
+
+        Returns:
+            Union[AzureOpenAIEmbeddings, OpenAIEmbeddings]: The LLM instance.
+        """
+        if llm_type.lower() == "azure":
+            # Get the Azure Credential
+            # credential = DefaultAzureCredential()
+            # token=credential.get_token("https://cognitiveservices.azure.com/.default").token
+
+            # if not token:
+            #     raise ValueError("Token is required for AzureOpenAIEmbeddings.")
+            # return AzureOpenAIEmbeddings(
+            #     azure_endpoint=os.environ["AZURE_OPENAI_API_URI"],
+            #     azure_deployment="text-embedding-3-small", #os.environ["AZURE_OPENAI_API_BASE_MODEL"],
+            #     api_version=os.environ["AZURE_OPENAI_API_VERSION"],
+            #     api_key=token
+            # )
+            pass
+        elif llm_type.lower() == "openai":
+            return OpenAIEmbeddings(
+                api_key=os.environ["OPENAI_API_KEY"],
+                model="text-embedding-3-large"
+            )
+        elif llm_type.lower() == "ollama": # must have ollama running locally with the following model
+            return OllamaEmbeddings(model="gemma:2b") 
+        elif llm_type.lower() == "hf": # must have key update in env:HF_TOKEN
+            return HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
+        else:
+            raise ValueError("Invalid llm_type. Use 'azure' or 'openai'.")

common/utility/llm_factory.py

@@ -0,0 +1,130 @@
+import os
+import tiktoken
+from typing import Any
+from langchain_openai.chat_models import ChatOpenAI, AzureChatOpenAI
+from langchain_openai.embeddings import AzureOpenAIEmbeddings, OpenAIEmbeddings
+# from azure.identity import DefaultAzureCredential
+from huggingface_hub import login
+from langchain_huggingface import ChatHuggingFace, HuggingFaceEmbeddings
+from langchain_ollama import ChatOllama, OllamaEmbeddings
+from langchain_groq import ChatGroq
+# from langchain_openai import OpenAIEmbeddings
+
+class LLMFactory:
+    """
+    Factory class to provide LLM and embedding model instances for different providers.
+    """
+
+    @staticmethod
+    def get_llm(provider: str, **kwargs) -> Any:
+        """
+        Returns a chat/completion LLM instance based on the provider.
+        Supported providers: openai, azureopenai, huggingface, ollama, groq
+        """
+        if provider == "openai":
+            # OpenAI Chat Model
+            return ChatOpenAI(
+                openai_api_key=kwargs.get("api_key", os.environ.get("OPENAI_API_KEY")),
+                model_name=kwargs.get("model_name", "gpt-4")
+            )
+
+        # elif provider == "azureopenai":
+        #     # Azure OpenAI Chat Model using Azure Identity for token
+        #     credential = DefaultAzureCredential()
+        #     token = credential.get_token("https://cognitiveservices.azure.com/.default").token
+        #     if not token:
+        #         raise ValueError("Token is required for AzureChatOpenAI.")
+        #     return AzureChatOpenAI(
+        #         azure_endpoint=kwargs["endpoint"],
+        #         azure_deployment=kwargs.get("deployment_name", "gpt-4"),
+        #         api_version=kwargs["api_version"],
+        #         api_key=token
+        #     )
+
+        # pip install langchain langchain-huggingface huggingface_hub
+        elif provider == "huggingface":
+            # If using a private model or endpoint, authenticate
+            login(token=kwargs.get("api_key", os.environ.get("HF_TOKEN")))  
+
+            return ChatHuggingFace(
+                repo_id=kwargs.get("model_name", "mistralai/Mistral-Nemo-Instruct-2407"),  # Or any other chat-friendly model
+                task="text-generation",
+                model_kwargs={
+                    "temperature": 0.7,
+                    "max_new_tokens": 256
+                }
+            )
+
+        elif provider == "ollama":
+            # Ollama local model
+            return ChatOllama(
+                model=kwargs.get("model_name", "gemma:2b"),
+                temperature=0
+            )
+
+        elif provider == "groq":
+            # Groq LLM
+            return ChatGroq(
+                model=kwargs.get("model_name", "Gemma2-9b-It"),
+                max_tokens=512,
+                api_key=kwargs.get("api_key", os.environ.get("GROQ_API_KEY"))
+            )
+
+        else:
+            raise ValueError(f"Unsupported provider: {provider}")
+
+    @staticmethod
+    def get_embedding_model(provider: str, **kwargs) -> Any:
+        """
+        Returns an embedding model instance based on the provider.
+        Supported providers: openai, huggingface
+        """
+        if provider == "openai":
+            return OpenAIEmbeddings(
+                model=kwargs.get("model_name", "text-embedding-3-large"),
+                openai_api_key=kwargs.get("api_key", os.environ.get("OPENAI_API_KEY"))
+            )
+        # if provider == "azureopenai":
+        #     # Get the Azure Credential
+        #     credential = DefaultAzureCredential()
+        #     token=credential.get_token("https://cognitiveservices.azure.com/.default").token
+
+        #     if not token:
+        #         raise ValueError("Token is required for AzureOpenAIEmbeddings.")
+        #     return AzureOpenAIEmbeddings(
+        #         azure_endpoint=os.environ["AZURE_OPENAI_API_URI"],
+        #         azure_deployment=kwargs.get("azure_deployment", "text-embedding-3-large"), 
+        #         api_version=os.environ["AZURE_OPENAI_API_VERSION"],
+        #         api_key=token
+        #     )
+        elif provider == "huggingface":
+            # If using a private model or endpoint, authenticate
+            login(token=kwargs.get("api_key", os.environ.get("HF_TOKEN")))  
+
+            return HuggingFaceEmbeddings(
+                model_name=kwargs.get("model_name", "all-MiniLM-L6-v2")
+            )
+        elif provider == "groq":
+            raise ValueError(f"No embedding support from the provider: {provider}")
+        elif provider == "ollama":
+            return OllamaEmbeddings(model=kwargs.get("model_name", "gemma:2b")) 
+        else:
+            raise ValueError(f"Unsupported embedding provider: {provider}")
+
+    @staticmethod
+    def num_tokens_from_messages(messages) -> int:
+        """
+        Return the number of tokens used by a list of messages.
+        Adapted from the OpenAI cookbook token counter.
+        """
+        encoding = tiktoken.encoding_for_model("gpt-3.5-turbo")
+        tokens_per_message = 3  # <|start|>, role, <|end|>
+        num_tokens = 0
+
+        for message in messages:
+            num_tokens += tokens_per_message
+            for key, value in message.items():
+                num_tokens += len(encoding.encode(value))
+
+        num_tokens += 3  # every reply is primed with <|start|>assistant<|message|>
+        return num_tokens

common/utility/llm_factory2.py

@@ -0,0 +1,75 @@
+import os
+import tiktoken
+from typing import Union
+# from azure.identity import DefaultAzureCredential
+from langchain_openai.chat_models import AzureChatOpenAI, ChatOpenAI
+
+
+class LLMFactory:
+    """
+    A static utility class to create and return LLM instances based on the input type.
+    """
+
+    @staticmethod
+    def get_llm(llm_type: str) -> Union[AzureChatOpenAI, ChatOpenAI]:
+        """
+        Returns an LLM instance based on the specified type.
+
+        Parameters:
+            llm_type (str): The type of LLM to return. Valid values are 'azure' or 'openai'.
+
+        Returns:
+            Union[AzureChatOpenAI, ChatOpenAI]: The LLM instance.
+        """
+        if llm_type.lower() == "azure":
+            # # Get the Azure Credential
+            # credential = DefaultAzureCredential()
+            # token=credential.get_token("https://cognitiveservices.azure.com/.default").token
+
+            # if not token:
+            #     raise ValueError("Token is required for AzureChatOpenAI.")
+            # return AzureChatOpenAI(
+            #     azure_endpoint=os.environ["AZURE_OPENAI_API_URI"],
+            #     azure_deployment=os.environ["AZURE_OPENAI_API_BASE_MODEL"],
+            #     api_version=os.environ["AZURE_OPENAI_API_VERSION"],
+            #     api_key=token
+            # )
+            pass
+        elif llm_type.lower() == "openai":
+            return ChatOpenAI(
+                api_key=os.environ["OPENAI_API_KEY"],
+                model_name="gpt-4"
+            )
+        elif llm_type.lower() == "openai_chat":
+            return ChatOpenAI(
+                api_key=os.environ["OPENAI_API_KEY"],
+                model_name="gpt-4"
+            )
+        else:
+            raise ValueError("Invalid llm_type. Use 'azure' or 'openai'.")
+        
+    @staticmethod
+    def num_tokens_from_messages(messages):
+
+        """
+        Return the number of tokens used by a list of messages.
+        Adapted from the Open AI cookbook token counter
+        """
+
+        encoding = tiktoken.encoding_for_model("gpt-3.5-turbo")
+
+        # Each message is sandwiched with <|start|>role and <|end|>
+        # Hence, messages look like: <|start|>system or user or assistant{message}<|end|>
+
+        tokens_per_message = 3 # token1:<|start|>, token2:system(or user or assistant), token3:<|end|>
+
+        num_tokens = 0
+
+        for message in messages:
+            num_tokens += tokens_per_message
+            for key, value in message.items():
+                num_tokens += len(encoding.encode(value))
+
+        num_tokens += 3  # every reply is primed with <|start|>assistant<|message|>
+
+        return num_tokens

common/utility/logger.py

@@ -0,0 +1,22 @@
+import functools
+import datetime
+
+def log_call(func):
+    """
+    A decorator that logs when a function is called and when it finishes.
+    """
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        arg_list = ", ".join(
+            [repr(a) for a in args] + [f"{k}={v!r}" for k, v in kwargs.items()]
+        )
+        print(f"[{timestamp}] 🚀 Calling: {func.__name__}({arg_list})")
+        try:
+            result = func(*args, **kwargs)
+            print(f"[{timestamp}] ✅ Finished: {func.__name__}")
+            return result
+        except Exception as e:
+            print(f"[{timestamp}] ❌ Error in {func.__name__}: {e}")
+            raise
+    return wrapper

pyproject.toml

@@ -67,6 +67,7 @@ dependencies = [
     "logfire",
     "serpapi",
     "smithery>=0.4.4",
+    "sendgrid",
 
     # =======================
     # WEB SCRAPING
@@ -100,6 +101,7 @@ dependencies = [
     # =======================
     "scikit-learn>=1.7.2",
     "huggingface_hub<=1.1.4",
+    "datasets>=4.4.1",
 
     # =======================
     # IPYNB SUPPORT

run.py

@@ -1,11 +1,215 @@
-import os
-import subprocess
-import sys
-
-# Use module execution to guarantee Streamlit runs inside the current interpreter
-subprocess.run([
-    sys.executable, "-m", "streamlit",
-    "run",
-    os.path.join("ui", "app.py"),
-    "--server.runOnSave", "true"
-])
+#!/usr/bin/env python3
+"""
+Universal App Launcher for AgenticAI Projects
+
+Usage:
+    python run.py <app_name> [--port PORT] [--help]
+
+Examples:
+    python run.py healthcare
+    python run.py deep-research --port 8502
+    python run.py stock-advisor
+    python run.py --list
+"""
+
+import sys
+import os
+import subprocess
+import argparse
+from pathlib import Path
+from typing import Dict, Optional
+
+
+# App registry - maps app names to their paths and entry points
+APP_REGISTRY: Dict[str, Dict[str, str]] = {
+    "healthcare": {
+        "path": "src/healthcare-assistant",
+        "entry": "app.py",
+        "description": "Healthcare Assistant - Medical information with RAG and web search"
+    },
+    "deep-research": {
+        "path": "src/deep-research",
+        "entry": "app.py",
+        "description": "Deep Research AI - Comprehensive research assistant"
+    },
+    "stock-advisor": {
+        "path": "src/stock-advisor",
+        "entry": "app.py",
+        "description": "Stock Advisor - Financial analysis and stock recommendations"
+    },
+    "travel-agent": {
+        "path": "src/travel-agent",
+        "entry": "app.py",
+        "description": "Travel Agent - Trip planning and travel recommendations"
+    },
+    "trip-planner": {
+        "path": "src/trip-planner",
+        "entry": "app.py",
+        "description": "Trip Planner - Detailed trip itinerary planning"
+    },
+    "chatbot": {
+        "path": "src/chatbot",
+        "entry": "app.py",
+        "description": "General Chatbot - Multi-purpose conversational AI"
+    },
+    "accessibility": {
+        "path": "src/accessibility",
+        "entry": "app.py",
+        "description": "Accessibility Tools - Assistive technology applications"
+    }
+}
+
+
+def print_banner():
+    """Print a nice banner."""
+    print("=" * 70)
+    print("🚀 AgenticAI Projects Launcher".center(70))
+    print("=" * 70)
+    print()
+
+
+def list_apps():
+    """List all available apps."""
+    print_banner()
+    print("Available Applications:\n")
+    
+    max_name_len = max(len(name) for name in APP_REGISTRY.keys())
+    
+    for name, config in sorted(APP_REGISTRY.items()):
+        print(f"  {name.ljust(max_name_len + 2)} - {config['description']}")
+    
+    print("\n" + "=" * 70)
+    print("\nUsage: python run.py <app_name> [--port PORT]")
+    print("Example: python run.py healthcare --port 8501\n")
+
+
+def validate_app(app_name: str) -> Optional[Dict[str, str]]:
+    """
+    Validate that the app exists and its files are present.
+    
+    Args:
+        app_name: Name of the app to validate
+        
+    Returns:
+        App configuration dict if valid, None otherwise
+    """
+    if app_name not in APP_REGISTRY:
+        print(f"❌ Error: Unknown app '{app_name}'")
+        print(f"\nAvailable apps: {', '.join(sorted(APP_REGISTRY.keys()))}")
+        print("\nRun 'python run.py --list' to see all available apps.")
+        return None
+    
+    config = APP_REGISTRY[app_name]
+    project_root = Path(__file__).parent
+    app_path = project_root / config["path"] / config["entry"]
+    
+    if not app_path.exists():
+        print(f"❌ Error: App file not found at {app_path}")
+        return None
+    
+    return config
+
+
+def launch_app(app_name: str, port: Optional[int] = None):
+    """
+    Launch a Streamlit app.
+    
+    Args:
+        app_name: Name of the app to launch
+        port: Optional port number (default: 8501)
+    """
+    config = validate_app(app_name)
+    if not config:
+        sys.exit(1)
+    
+    project_root = Path(__file__).parent
+    app_dir = project_root / config["path"]
+    app_file = config["entry"]
+    
+    print_banner()
+    print(f"📱 Launching: {config['description']}")
+    print(f"📂 Location: {config['path']}")
+    print(f"🌐 Entry Point: {app_file}")
+    
+    # Build streamlit command
+    cmd = ["streamlit", "run", app_file]
+    
+    # Add port if specified
+    if port:
+        cmd.extend(["--server.port", str(port)])
+        print(f"🔌 Port: {port}")
+    else:
+        print(f"🔌 Port: 8501 (default)")
+    
+    print("\n" + "=" * 70)
+    print("\n🎯 Starting application...\n")
+    
+    try:
+        # Change to app directory and run
+        os.chdir(app_dir)
+        subprocess.run(cmd)
+    except KeyboardInterrupt:
+        print("\n\n👋 Application stopped by user")
+    except FileNotFoundError:
+        print("\n❌ Error: Streamlit not found. Please install it:")
+        print("   pip install streamlit")
+        sys.exit(1)
+    except Exception as e:
+        print(f"\n❌ Error launching app: {e}")
+        sys.exit(1)
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="Universal launcher for AgenticAI project applications",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python run.py healthcare              # Launch healthcare chatbot
+  python run.py deep-research --port 8502   # Launch on custom port
+  python run.py --list                  # List all available apps
+
+Available Apps:
+  """ + "\n  ".join(f"{name}: {config['description']}" 
+                     for name, config in sorted(APP_REGISTRY.items()))
+    )
+    
+    parser.add_argument(
+        "app_name",
+        nargs="?",
+        help="Name of the app to launch"
+    )
+    
+    parser.add_argument(
+        "--port",
+        type=int,
+        help="Port number for Streamlit server (default: 8501)"
+    )
+    
+    parser.add_argument(
+        "--list",
+        action="store_true",
+        help="List all available apps"
+    )
+    
+    args = parser.parse_args()
+    
+    # Handle --list flag
+    if args.list:
+        list_apps()
+        return
+    
+    # Require app name if not listing
+    if not args.app_name:
+        parser.print_help()
+        print("\n")
+        list_apps()
+        return
+    
+    # Launch the app
+    launch_app(args.app_name, args.port)
+
+
+if __name__ == "__main__":
+    main()

src/chatbot/Dockerfile

@@ -0,0 +1,35 @@
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    DEBIAN_FRONTEND=noninteractive \
+    PYTHONPATH=/app:/app/common:$PYTHONPATH
+
+WORKDIR /app
+
+# System deps
+RUN apt-get update && apt-get install -y \
+    git build-essential curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:$PATH"
+
+# Copy project metadata
+COPY pyproject.toml .
+COPY uv.lock .
+
+# Copy required folders
+COPY common/ ./common/
+COPY src/chatbot/ ./src/chatbot/
+
+# Install dependencies using uv, then export and install with pip to system
+RUN uv sync --frozen --no-dev && \
+    uv pip install -e . --system
+
+# Copy entry point
+COPY run.py .
+
+EXPOSE 7860
+
+CMD ["python", "run.py", "chatbot", "--port", "7860"]

src/chatbot/README.md

@@ -0,0 +1,219 @@
+---
+title: AI Chatbot
+emoji: 🤖
+colorFrom: green
+colorTo: indigo
+sdk: docker
+sdk_version: "0.0.1"
+app_file: ui/app.py
+pinned: false
+---
+
+# AI Chatbot
+
+This is an experimental chatbot for chatting with AI. It is equipped with agents & tools to give you realtime data from the web. It uses **OpenAI - SDK** and **OpenAI - Agents**.
+
+## Features
+- Predefined prompts for quick analysis
+- Chat interface with AI responses
+- Enter key support and responsive design
+- Latest messages appear on top
+
+## Usage
+1. Type a message or select a predefined prompt
+2. Press **Enter** or click **Send**
+3. AI responses appear instantly in the chat interface
+
+## Supported APIs
+- OpenAI
+- Google
+- GROQ
+- SERPER
+- News API
+
+## Notes
+- Make sure your API keys are configured in the Space secrets
+- Built using Streamlit and deployed as a Docker Space
+
+## References
+
+https://openai.github.io/openai-agents-python/
+
+https://github.com/openai/openai-agents-python/tree/main/examples/mcp
+
+## Project Folder Structure
+
+```
+chatbot/
+├── ui/
+│   ├── __init__.py               # Package initialization
+│   └── app.py                    # Main Streamlit chatbot interface
+├── appagents/
+│   ├── __init__.py               # Package initialization
+│   ├── OrchestratorAgent.py      # Main orchestrator - coordinates all agents
+│   ├── FinancialAgent.py         # Financial data and analysis agent
+│   ├── NewsAgent.py              # News retrieval and summarization agent
+│   ├── SearchAgent.py            # General web search agent
+│   └── InputValidationAgent.py   # Input validation and sanitization agent
+├── core/
+│   ├── __init__.py               # Package initialization
+│   └── logger.py                 # Centralized logging configuration
+├── tools/
+│   ├── __init__.py               # Package initialization
+│   ├── google_tools.py           # Google search API wrapper
+│   ├── yahoo_tools.py            # Yahoo Finance API wrapper
+│   ├── news_tools.py             # News API wrapper
+│   └── time_tools.py             # Time-related utility functions
+├── prompts/
+│   ├── economic_news.txt         # Prompt for economic news analysis
+│   ├── market_sentiment.txt      # Prompt for market sentiment analysis
+│   ├── news_headlines.txt        # Prompt for news headline summarization
+│   ├── trade_recommendation.txt  # Prompt for trade recommendations
+│   └── upcoming_earnings.txt     # Prompt for upcoming earnings alerts
+├── Dockerfile                     # Docker configuration for container deployment
+├── pyproject.toml                 # Project metadata and dependencies (copied from root)
+├── uv.lock                        # Locked dependency versions (copied from root)
+├── README.md                      # Project documentation
+└── run.py                         # Script to run the application locally
+```
+
+## File Descriptions
+
+### UI Layer (`ui/`)
+- **app.py** - Main Streamlit chatbot interface that provides:
+  - Chat message display with user and AI messages
+  - Text input for user queries
+  - Predefined prompt buttons for quick analysis
+  - Real-time AI responses
+  - Support for Enter key submission
+  - Responsive design with latest messages appearing first
+
+### Agents (`appagents/`)
+- **OrchestratorAgent.py** - Main orchestrator that:
+  - Coordinates communication between all specialized agents
+  - Routes user queries to appropriate agents
+  - Manages conversation flow and context
+  - Integrates tool responses
+
+- **FinancialAgent.py** - Financial data and analysis:
+  - Retrieves stock prices and financial metrics
+  - Performs financial analysis using Yahoo Finance API
+  - Provides market insights and recommendations
+  - Integrates with yahoo_tools for data fetching
+
+- **NewsAgent.py** - News retrieval and summarization:
+  - Fetches latest news articles
+  - Summarizes news content
+  - Integrates with News API for real-time updates
+  - Provides news-based market insights
+
+- **SearchAgent.py** - General web search:
+  - Performs web searches for general queries
+  - Integrates with Google Search / Serper API
+  - Returns relevant search results
+  - Supports multi-source data gathering
+
+- **InputValidationAgent.py** - Input validation:
+  - Sanitizes user input
+  - Validates query format and content
+  - Prevents malicious inputs
+  - Ensures appropriate content
+
+### Core Utilities (`core/`)
+- **logger.py** - Centralized logging configuration:
+  - Provides consistent logging across agents
+  - Handles different log levels
+  - Formats log messages for clarity
+
+### Tools (`tools/`)
+- **google_tools.py** - Google Search API wrapper:
+  - Executes web searches via Google Search / Serper API
+  - Parses and returns search results
+  - Handles API authentication
+
+- **yahoo_tools.py** - Yahoo Finance API integration:
+  - Retrieves stock price data
+  - Fetches financial metrics and indicators
+  - Provides historical price data
+  - Returns earnings information
+
+- **news_tools.py** - News API integration:
+  - Fetches latest news articles
+  - Filters news by category and keywords
+  - Returns news headlines and summaries
+  - Provides market-related news feeds
+
+- **time_tools.py** - Time utility functions:
+  - Provides current time information
+  - Formats timestamps
+  - Handles timezone conversions
+
+### Prompts (`prompts/`)
+Predefined prompts for specialized analysis:
+- **economic_news.txt** - Analyzes economic news and implications
+- **market_sentiment.txt** - Analyzes market sentiment trends
+- **news_headlines.txt** - Summarizes and explains news headlines
+- **trade_recommendation.txt** - Provides trading recommendations
+- **upcoming_earnings.txt** - Alerts about upcoming earnings reports
+
+### Configuration Files
+- **Dockerfile** - Container deployment:
+  - Builds Docker image with Python 3.12
+  - Installs dependencies using `uv`
+  - Sets up Streamlit server on port 8501
+  - Configures PYTHONPATH for module imports
+
+- **pyproject.toml** - Project metadata:
+  - Package name: "agents"
+  - Python version requirement: 3.12
+  - Lists all dependencies (OpenAI, LangChain, Streamlit, etc.)
+
+- **uv.lock** - Dependency lock file:
+  - Ensures reproducible builds
+  - Pins exact versions of all dependencies
+
+## Key Technologies
+
+| Component | Technology | Purpose |
+|-----------|-----------|---------|
+| LLM Framework | OpenAI Agents | Multi-agent orchestration |
+| Chat Interface | Streamlit | User interaction and display |
+| Web Search | Google Search / Serper API | Web search results |
+| Financial Data | Yahoo Finance API | Stock prices and metrics |
+| News Data | News API | Latest news articles |
+| Async Operations | AsyncIO | Parallel agent execution |
+| Dependencies | UV | Fast Python package management |
+| Containerization | Docker | Cloud deployment |
+
+## Predefined Prompts
+
+The chatbot includes quick-access buttons for common analysis:
+
+1. **Economic News** - Analyzes current economic trends and news
+2. **Market Sentiment** - Provides market sentiment analysis
+3. **News Headlines** - Summarizes latest news headlines
+4. **Trade Recommendation** - Suggests trading strategies
+5. **Upcoming Earnings** - Lists upcoming company earnings
+
+## Running Locally
+
+```bash
+# Install dependencies
+uv sync
+
+# Set environment variables defined in .env.name file
+export OPENAI_API_KEY="your-key"
+export SERPER_API_KEY="your-key"
+export NEWS_API_KEY="your-key"
+
+# Run the Streamlit app
+python run.py
+```
+
+## Deployment
+
+The project is deployed on Hugging Face Spaces as a Docker container:
+- **Space**: https://huggingface.co/spaces/mishrabp/chatbot-app
+- **URL**: https://mishrabp-chatbot-app.hf.space
+- **Trigger**: Automatic deployment on push to `main` branch
+- **Configuration**: `.github/workflows/chatbot-app-hf.yml`

src/chatbot/app.py

@@ -0,0 +1,230 @@
+import streamlit as st
+import os
+import glob
+import asyncio
+import sys
+import uuid
+
+# Add project root
+sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), ".")))
+
+from appagents.OrchestratorAgent import OrchestratorAgent
+from agents import Runner, trace, SQLiteSession
+from agents.exceptions import InputGuardrailTripwireTriggered
+
+# -----------------------------
+# Configuration & Utils
+# -----------------------------
+st.set_page_config(
+    page_title="AI Assistant",
+    layout="wide",
+    page_icon="🤖"
+)
+
+def load_prompts(folder="prompts"):
+    prompts = []
+    prompt_labels = []
+    if os.path.exists(folder):
+        for file_path in glob.glob(os.path.join(folder, "*.txt")):
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = f.read().strip()
+                if content:
+                    prompts.append(content)
+                    prompt_labels.append(os.path.basename(file_path).replace("_", " ").replace(".txt", "").title())
+    return prompts, prompt_labels
+
+prompts, prompt_labels = load_prompts()
+
+# -----------------------------
+# Session State
+# -----------------------------
+if "messages" not in st.session_state:
+    st.session_state.messages = []
+
+if "ai_session_id" not in st.session_state:
+    st.session_state.ai_session_id = str(uuid.uuid4())
+
+# Persistent SQLite session
+if "ai_session" not in st.session_state:
+    st.session_state.ai_session = SQLiteSession(f"conversation_{st.session_state.ai_session_id}.db")
+
+session = st.session_state.ai_session
+
+# -----------------------------
+# Premium Styling
+# -----------------------------
+st.markdown("""
+<style>
+    /* Global Cleanliness */
+    .stApp {
+        background-color: #f8f9fa;
+    }
+    
+    .block-container {
+        padding-top: 1rem !important;
+    }
+    
+    /* Remove default header decoration */
+    header[data-testid="stHeader"] {
+        background-color: transparent;
+    }
+    
+    /* Typography */
+    h1, h2, h3 {
+        font-family: 'Inter', sans-serif;
+        font-weight: 600;
+        color: #1a1a1a;
+    }
+    
+    /* Hero Section */
+    .hero-container {
+        position: sticky;
+        top: 0;
+        z-index: 1000;
+        padding: 2rem 0;
+        text-align: center;
+        margin-bottom: 2rem;
+        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+        border-radius: 0 0 16px 16px; /* Rounded only at bottom to look like a header */
+        color: white;
+        box-shadow: 0 4px 15px rgba(0,0,0,0.1);
+        width: auto;
+        margin-left: -5rem;
+        margin-right: -5rem;
+        margin-top: -3rem;
+    }
+    .hero-title {
+        font-size: 2rem;
+        margin-bottom: 0.5rem;
+        font-weight: 700;
+    }
+    .hero-subtitle {
+        font-size: 1rem;
+        opacity: 0.9;
+        font-weight: 400;
+    }
+    
+    /* Spacer to prevent content form being hidden under sticky header initially if needed, 
+       but standard flow usually puts it after. */
+
+    /* Chat Bubbles */
+    .stChatMessage {
+        background-color: transparent;
+        border-radius: 10px;
+        padding: 1rem;
+        margin-bottom: 0.5rem;
+    }
+    div[data-testid="stChatMessageContent"] {
+        font-size: 1.05rem;
+        line-height: 1.6;
+    }
+
+    /* Sidebar Styling */
+    section[data-testid="stSidebar"] {
+        background-color: #ffffff;
+        border-right: 1px solid #eaeaea;
+    }
+    .suggestion-btn {
+        width: 100%;
+        text-align: left;
+        padding: 0.75rem 1rem;
+        margin-bottom: 0.5rem;
+        background-color: #f8f9fa;
+        border: 1px solid #e9ecef;
+        border-radius: 8px;
+        color: #495057;
+        font-size: 0.95rem;
+        transition: all 0.2s ease;
+        cursor: pointer;
+        display: block;
+        text-decoration: none;
+    }
+    .suggestion-btn:hover {
+        background-color: #e2e6ea;
+        border-color: #dae0e5;
+        text-decoration: none;
+        color: #212529;
+    }
+
+</style>
+""", unsafe_allow_html=True)
+
+# -----------------------------
+# Logic
+# -----------------------------
+async def get_ai_response(prompt: str) -> str:
+    try:
+        agent = OrchestratorAgent.create()
+        # Ensure session is valid
+        current_session = st.session_state.ai_session
+        with trace("Chatbot Agent Run"):
+            # Run agent
+            result = await Runner.run(agent, prompt, session=current_session)
+            return result.final_output
+    except InputGuardrailTripwireTriggered as e:
+        reasoning = getattr(e, "reasoning", None) \
+            or getattr(getattr(e, "output", None), "reasoning", None) \
+            or getattr(getattr(e, "guardrail_output", None), "reasoning", None) \
+            or "Guardrail triggered, but no reasoning provided."
+        return f"⚠️ **Guardrail Blocked Input**\n\n{reasoning}"
+    except Exception as e:
+        return f"❌ **Error**: {str(e)}"
+
+# -----------------------------
+# Sidebar - Quick Actions
+# -----------------------------
+with st.sidebar:
+    st.markdown("### ⚡ Quick Starters")
+    st.markdown("Select a prompt to start:")
+    
+    # We use a trick with st.button to act as input triggers
+    # If a button is clicked, we'll handle it in the main loop logic
+    selected_prompt = None
+    for idx, prompt_text in enumerate(prompts):
+        label = prompt_labels[idx] if idx < len(prompt_labels) else f"Prompt {idx+1}"
+        if st.button(label, key=f"sidebar_btn_{idx}", use_container_width=True):
+            selected_prompt = prompt_text
+
+    st.markdown("---")
+    if st.button("🗑️ Clear Conversation", use_container_width=True):
+        st.session_state.messages = []
+        st.rerun()
+
+# -----------------------------
+# Main Content
+# -----------------------------
+
+# Hero Banner (Always visible & Sticky)
+st.markdown("""
+    <div class="hero-container">
+        <div class="hero-title">🤖 AI Companion</div>
+        <div class="hero-subtitle">Your intelligent partner for research, analysis, and more.</div>
+    </div>
+""", unsafe_allow_html=True)
+
+# Display Chat History
+for message in st.session_state.messages:
+    with st.chat_message(message["role"]):
+        st.markdown(message["content"])
+
+# Chat Input Handling
+# We handle both the chat input widget and the sidebar selection here
+if prompt := (st.chat_input("Type your message...") or selected_prompt):
+    # User Message
+    st.session_state.messages.append({"role": "user", "content": prompt})
+    with st.chat_message("user"):
+        st.markdown(prompt)
+
+    # Assistant Response
+    with st.chat_message("assistant"):
+        with st.spinner("Thinking..."):
+            response_text = asyncio.run(get_ai_response(prompt))
+            st.markdown(response_text)
+            
+    st.session_state.messages.append({"role": "assistant", "content": response_text})
+    
+    # If it was a sidebar click, we need to rerun to clear the selection state potentially, 
+    # but st.chat_input usually handles focus. With buttons, a rerun happens automatically 
+    # but we want to make sure the input box is cleared (which 'selected_prompt' doesn't use).
+    if selected_prompt:
+        st.rerun()

src/chatbot/appagents/FinancialAgent.py

@@ -0,0 +1,56 @@
+from tools.yahoo_tools import FinanceTools
+from tools.time_tools import TimeTools
+from tools.google_tools import GoogleTools
+import os
+from agents import Agent, OpenAIChatCompletionsModel
+from openai import AsyncOpenAI
+
+class FinancialAgent:
+    """
+    Encapsulates the AI agent definition for financial analysis and market research.
+    """
+
+    @staticmethod
+    def create():
+        """
+        Returns a configured Agent instance ready for use.
+        """
+        # Included all relevant tools
+        tools = [
+            TimeTools.current_datetime,
+            FinanceTools.get_market_sentiment,
+            FinanceTools.get_history,
+            GoogleTools.search
+        ]
+
+        instructions = """
+            You are a specialized **Financial Analysis Agent** 💰, expert in market research, financial data retrieval, and news correlation. Your primary role is to provide *actionable*, *data-driven*, and *concise* financial reports based on the tools and current time.
+
+            ## Core Directives & Priorities
+            1.  **Time Sensitivity (TimeTools):** Always use the **TimeTools.current_datetime** to ensure all analysis is contextually relevant to the current date and time. Financial data is extremely time-sensitive.
+            2.  **Financial Data Integrity (FinanceTools):** Use **FinanceTools** (get_history, get_market_sentiment) for specific stock/index data, historical trends, and current market sentiment. Be precise about the date range and data source.
+            3.  **Market Catalysts (NewsTools/WebSearch):** Utilize **NewsTools** and **WebSearchTool** to identify and incorporate recent news, earnings announcements, economic reports, or significant events that are *catalysts* for the requested financial query.
+            4.  **Synthesis and Analysis:** Do not just list data. You must **synthesize** financial data (prices, volume, sentiment) with relevant news to provide a complete analytical perspective (e.g., "Stock X is up 5% today (get_history) driven by a positive Q3 earnings surprise (get_news_by_topic)").
+            5.  **Professional Clarity:** Present information in a clear, professional, and structured format. Use numerical data and financial terminology correctly.
+            6.  **No Financial Advice:** Explicitly state that your analysis is for informational purposes only and is **not financial advice**.
+            7.  **Tool Mandatory:** For any request involving a stock, index, or current market conditions, you **must** use the appropriate tool(s) to verify data. **Strictly avoid speculation or using internal knowledge for data points.**
+
+            ## Output Format Guidelines
+            * Use **bold** for key financial metrics (e.g., Stock Symbol, Price, Volume).
+            * Cite the tools used to obtain the data (e.g., Data sourced from FinanceTools (Yahoo) as of [Date]).
+            * If a symbol or data point cannot be found, clearly state "Data for [X] is unavailable or invalid."
+        """
+
+
+        GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+        google_api_key = os.getenv('GOOGLE_API_KEY')
+        gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+        gemini_model = OpenAIChatCompletionsModel(model="gemini-2.0-flash", openai_client=gemini_client) 
+
+        agent = Agent(
+            name="Financial Analysis Agent",
+            tools=tools,
+            instructions=instructions,
+            model=gemini_model
+        )
+        return agent

src/chatbot/appagents/InputValidationAgent.py

@@ -0,0 +1,76 @@
+import os
+from agents import Agent, OpenAIChatCompletionsModel, Runner, GuardrailFunctionOutput
+from pydantic import BaseModel
+import json
+from openai import AsyncOpenAI
+
+class ValidatedOutput(BaseModel):
+    is_valid: bool
+    reasoning: str
+
+class InputValidationAgent:
+    """
+    Encapsulates the AI agent definition for conducting comprehensive web searches and synthesizing information.
+    """
+
+    @staticmethod
+    def create():
+        """
+        Returns a configured Agent instance ready for use.
+        """
+
+        instructions = """
+            You are a highly efficient and specialized **Agent** 🌐. Your sole function is to validate the user inputs.
+            
+            ## Core Directives & Priorities
+            1. You should flag if the user uses unparaliamentary language ONLY.
+            2. You MUST give reasoning for the same.
+            
+            ## Rules
+            - If it contains any of these, mark `"is_valid": false` and explain **why** in `"reasoning"`.
+            - Otherwise, mark `"is_valid": true` with reasoning like "The input follows respectful communication guidelines."
+
+
+            ## Output Format (MANDATORY)
+            * Return a JSON object with the following structure:
+            {
+                "is_valid": <boolean>,
+                "reasoning": <string>
+            }
+
+        """
+
+
+        GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+        google_api_key = os.getenv('GOOGLE_API_KEY')
+        gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+        gemini_model = OpenAIChatCompletionsModel(model="gemini-2.0-flash", openai_client=gemini_client) 
+
+        agent = Agent(
+            name="Guardrail Input Validation Agent",
+            instructions=instructions,
+            model=gemini_model,
+            output_type=ValidatedOutput,
+        )
+        return agent
+    
+async def input_validation_guardrail(ctx, agent, input_data):
+    result = await Runner.run(InputValidationAgent.create(), input_data, context=ctx.context)
+    raw_output = result.final_output
+
+    # print("Raw Output from Guardrail Model:", raw_output)
+
+    # Handle different return shapes gracefully
+    if isinstance(raw_output, ValidatedOutput):
+        final_output = raw_output
+        print("Parsed ValidatedOutput:", final_output)
+    else:
+        final_output = ValidatedOutput(
+            is_valid=False,
+            reasoning=f"Unexpected output type: {type(raw_output)}"
+        )
+
+    return GuardrailFunctionOutput(
+        output_info=final_output,
+        tripwire_triggered=not final_output.is_valid,
+    )

src/chatbot/appagents/NewsAgent.py

@@ -0,0 +1,66 @@
+from tools.news_tools import NewsTools
+from tools.time_tools import TimeTools
+from tools.google_tools import GoogleTools
+# from tools.yahoo_tools import FinanceTools # Removed: Not needed for a pure News Agent
+import os
+from agents import Agent, OpenAIChatCompletionsModel
+from openai import AsyncOpenAI
+
+class NewsAgent:
+    """
+    Encapsulates the AI agent definition for real-time news gathering, summarization, and reporting.
+    """
+
+    @staticmethod
+    def create():
+        """
+        Returns a configured Agent instance ready for use.
+        """
+        # Corrected tool list: removed FinanceTools, added WebSearchTool
+        tools = [
+            TimeTools.current_datetime,
+            NewsTools.top_headlines,
+            NewsTools.search_news,
+            GoogleTools.search
+        ]
+
+        instructions = """
+            You are a specialized **News Reporting Agent** 📰, expert in retrieving, summarizing, and synthesizing current events and information from various sources. Your primary role is to deliver a concise, objective, and timely news digest or report.
+
+            ## Core Directives & Priorities
+            1.  **Immediacy and Context (TimeTools):** Always use **TimeTools.current_datetime** to contextualize all reports. Clearly indicate when the information was retrieved (e.g., "As of [Date/Time]").
+            2.  **News Retrieval (NewsTools):**
+                * For general awareness, use **NewsTools.top_headlines**.
+                * For specific topics, use **NewsTools.search_news**.
+                * Prioritize the most recent articles.
+            3.  **Comprehensive Search (WebSearchTool):** Use the **WebSearchTool (Google Search)** for:
+                * Verifying facts or statistics found in news articles.
+                * Gathering background context on a complex story.
+                * Finding information not covered by the dedicated news API.
+            4.  **Objective Synthesis:** Do not express opinions or speculate. You must **synthesize** information from multiple articles or tools to provide a **balanced and neutral summary**. Avoid sensationalism.
+            5.  **Attribution and Transparency:** Every piece of reported information must be sourced. Cite the original publication or the tool used (e.g., "The New York Times reported...", "According to data found via WebSearch..."). Provide links where available.
+            6.  **Structured Reporting:** Present the information clearly. For complex topics, use bullet points, subheadings, and a brief introductory summary.
+            7.  **Data Gaps:** If a requested topic yields no recent or verifiable information, explicitly state: **"No verifiable recent news could be found on [Topic]."**
+
+            ## Output Format Guidelines
+            * Start with a brief, high-level summary of the answer.
+            * Use **bold** for key names, dates, and locations.
+            * List news sources clearly with the article title and, if possible, the link/publication name.
+            * Maintain a professional, journalistic tone.
+
+            **Strictly adhere to verifiable facts and avoid making up any information.**
+        """
+
+
+        GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+        google_api_key = os.getenv('GOOGLE_API_KEY')
+        gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+        gemini_model = OpenAIChatCompletionsModel(model="gemini-2.0-flash", openai_client=gemini_client) 
+
+        agent = Agent(
+            name="News Reporting Agent",
+            tools=tools,
+            instructions=instructions,
+            model=gemini_model #"gpt-4o-mini"
+        )
+        return agent

src/chatbot/appagents/OrchestratorAgent.py

@@ -0,0 +1,167 @@
+import os
+import asyncio
+from appagents.FinancialAgent import FinancialAgent
+from appagents.NewsAgent import NewsAgent
+from appagents.SearchAgent import SearchAgent
+from appagents.InputValidationAgent import input_validation_guardrail
+from agents import Agent, OpenAIChatCompletionsModel, InputGuardrail
+from openai import AsyncOpenAI
+
+
+class OrchestratorAgent:
+    """
+    The OrchestratorAgent coordinates multiple specialized sub-agents
+    (Financial, News, and Search) to provide accurate, up-to-date,
+    and well-routed market research insights.
+    """
+
+    MAX_RETRIES = 2
+
+    # ----------------------------------------------------------
+    # MAIN CREATION METHOD
+    # ----------------------------------------------------------
+    @staticmethod
+    def create(model: str = "gpt-4o-mini"):
+        """
+        Creates and returns a configured Orchestrator agent.
+        """
+
+        # --- Sub-agent setup ---
+        handoffs = [
+            FinancialAgent.create(),
+            NewsAgent.create(),
+            SearchAgent.create(),
+        ]
+
+        # --- Behavioral instructions ---
+        instructions = """
+        You are the Orchestrator Agent responsible for coordinating specialized sub-agents 
+        to generate accurate and well-rounded market research responses.
+
+        **Your Core Responsibilities**
+        1. **Task Routing:** Determine which sub-agent (Financial, News, or Search) is best suited 
+           to handle each user query based on intent and context.
+        2. **Delegation:** Forward the request to the appropriate sub-agent and wait for its result.
+        3. **Synthesis:** When multiple agents provide responses, summarize and merge their findings 
+           into a clear, concise, and accurate overall answer.
+        4. **Recency and Accuracy:** Prioritize the most up-to-date, verifiable data from sub-agents.
+        5. **Transparency:** Clearly identify which insights came from which sub-agent when relevant.
+        6. **Error Handling:** If a sub-agent fails or provides insufficient data, attempt fallback 
+           strategies such as rerouting the query or notifying the user.
+        7. **Clarity:** Always present the final response in a professional, well-structured, 
+           and easy-to-understand format.
+
+        ⚠️ Do **not** perform the underlying data analysis or external lookup yourself — 
+        ALWAYS delegate those tasks to the respective sub-agents.
+        """
+
+        # --- Model setup ---
+        GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+        google_api_key = os.getenv("GOOGLE_API_KEY")
+        gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+        gemini_model = OpenAIChatCompletionsModel(
+            model="gemini-2.0-flash",
+            openai_client=gemini_client
+        )
+
+        # --- Create orchestrator agent ---
+        agent = Agent(
+            name="AI Market Research Assistant",
+            handoffs=handoffs,
+            instructions=instructions.strip(),
+            model=gemini_model,
+            # input_guardrails=[
+            #     InputGuardrail(
+            #         name="Input Validation Guardrail",
+            #         guardrail_function=input_validation_guardrail,
+            #     )
+            # ],
+        )
+
+        # Attach orchestration logic
+        agent.respond = lambda prompt: OrchestratorAgent.respond(prompt, handoffs, gemini_model)
+        return agent
+
+    # ----------------------------------------------------------
+    # RESPONSE HANDLING + SELF-CORRECTION
+    # ----------------------------------------------------------
+    @staticmethod
+    async def respond(prompt: str, handoffs: list, model) -> str:
+        """
+        Routes prompt to the most relevant agent, retries if output seems irrelevant.
+        """
+        attempted_agents = set()
+
+        for attempt in range(OrchestratorAgent.MAX_RETRIES):
+            # Step 1: Route intelligently
+            chosen_agent = await OrchestratorAgent._route_to_agent(prompt, handoffs, attempted_agents)
+            if not chosen_agent:
+                return "⚠️ No available agent could handle this query."
+
+            print(f"🤖 Attempt {attempt+1}: Sending query to {chosen_agent.name}")
+
+            # Step 2: Run agent
+            try:
+                response = await chosen_agent.run(prompt)
+            except Exception as e:
+                print(f"⚠️ Agent {chosen_agent.name} failed: {e}")
+                attempted_agents.add(chosen_agent.name)
+                continue
+
+            # Step 3: Evaluate if relevant
+            if await OrchestratorAgent._is_relevant(prompt, response, model):
+                return f"✅ {chosen_agent.name} handled this successfully:\n\n{response}"
+
+            print(f"🔁 {chosen_agent.name}'s response deemed irrelevant. Re-routing...")
+            attempted_agents.add(chosen_agent.name)
+
+        return "⚠️ Could not find a relevant answer after multiple attempts."
+
+    # ----------------------------------------------------------
+    # ROUTING LOGIC
+    # ----------------------------------------------------------
+    @staticmethod
+    async def _route_to_agent(prompt: str, handoffs: list, attempted_agents: set):
+        """
+        Determines the best-fit agent for the given prompt.
+        Avoids previously tried agents.
+        """
+        lowered = prompt.lower()
+        available = [a for a in handoffs if a.name not in attempted_agents]
+
+        if not available:
+            return None
+
+        if any(k in lowered for k in ["finance", "stock", "market", "earnings"]):
+            return next((a for a in available if "financial" in a.name.lower()), available[0])
+        elif any(k in lowered for k in ["news", "headline", "press release"]):
+            return next((a for a in available if "news" in a.name.lower()), available[0])
+        elif any(k in lowered for k in ["search", "find", "lookup", "discover"]):
+            return next((a for a in available if "search" in a.name.lower()), available[0])
+        else:
+            # fallback — first available agent
+            return available[0]
+
+    # ----------------------------------------------------------
+    # LLM-BASED EVALUATOR
+    # ----------------------------------------------------------
+    @staticmethod
+    async def _is_relevant(prompt: str, response: str, model) -> bool:
+        """
+        Uses the model itself to check if the response matches the prompt intent.
+        """
+        eval_prompt = f"""
+        You are an evaluator checking multi-agent responses.
+        User asked: "{prompt}"
+        Agent responded: "{response}"
+
+        Does this response accurately and completely answer the user's intent?
+        Reply with only 'yes' or 'no'.
+        """
+        try:
+            eval_result = await model.run(eval_prompt)
+            print(f"🧠 Evaluation result: {eval_result}")
+            return "yes" in eval_result.lower()
+        except Exception as e:
+            print(f"⚠️ Evaluation failed: {e}")
+            return False

src/chatbot/appagents/SearchAgent.py

@@ -0,0 +1,57 @@
+from tools.google_tools import GoogleTools
+from tools.time_tools import TimeTools
+import os
+from agents import Agent, OpenAIChatCompletionsModel
+from openai import AsyncOpenAI
+
+class SearchAgent:
+    """
+    Encapsulates the AI agent definition for conducting comprehensive web searches and synthesizing information.
+    """
+
+    @staticmethod
+    def create():
+        """
+        Returns a configured Agent instance ready for use.
+        """
+        # The tool list is correct for a pure search agent
+        tools = [
+            TimeTools.current_datetime,
+            GoogleTools.search,
+        ]
+
+        instructions = """
+            You are a highly efficient and specialized **Web Search Agent** 🌐. Your sole function is to retrieve and analyze information from the internet using the **GoogleTools.search** function. You must act as a digital librarian and researcher, providing synthesized, cited, and up-to-date answers.
+
+            ## Core Directives & Priorities
+            1.  **Search First:** For virtually *every* factual query, you must invoke **GoogleTools.search** before responding. Your primary source of truth is the current web search results.
+            2.  **Query Optimization:** Before calling the tool, analyze the user's request and construct the most effective, concise, and targeted search queries (1-3 queries max). Use specific keywords, dates, or phrases to ensure relevant results.
+            3.  **Time Sensitivity (TimeTools):** Use **TimeTools.current_datetime** to contextualize time-sensitive queries. Results must reflect the current state of information.
+            4.  **Verification and Synthesis:**
+                * **Verification:** Corroborate facts by checking multiple search results if necessary. If results conflict, report the disagreement and the most common or reputable finding.
+                * **Synthesis:** Aggregate the key findings from the search snippets into a single, comprehensive, and easy-to-read answer. Do not simply list the search results.
+            5.  **Source Transparency (Citation Mandatory):** You **must** provide clear citation for all facts. At the end of your response, list the source titles and URLs from the Google Search results used to construct the answer.
+            6.  **Clarity and Brevity:** Use professional, plain language. Structure the response using headings and bullet points for complex topics. Avoid filler text or unnecessary detail.
+            7.  **Data Gaps:** If no relevant or conclusive information is found via the search tool, explicitly state: **"A conclusive answer could not be verified by current web search results."**
+
+            ## Output Format Guidelines
+            * Begin with a direct answer to the user's question.
+            * Use **bold** for key facts, names, dates, or statistics.
+            * Conclude the response with a separate "Sources" section citing the search results.
+
+            **Crucially, never fabricate information or provide an answer without grounding it in the search results.**
+        """
+
+
+        GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+        google_api_key = os.getenv('GOOGLE_API_KEY')
+        gemini_client = AsyncOpenAI(base_url=GEMINI_BASE_URL, api_key=google_api_key)
+        gemini_model = OpenAIChatCompletionsModel(model="gemini-2.0-flash", openai_client=gemini_client) 
+
+        agent = Agent(
+            name="Web Search Agent",
+            tools=tools,
+            instructions=instructions,
+            model=gemini_model
+        )
+        return agent

src/chatbot/core/logger.py

@@ -0,0 +1,22 @@
+import functools
+import datetime
+
+def log_call(func):
+    """
+    A decorator that logs when a function is called and when it finishes.
+    """
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        arg_list = ", ".join(
+            [repr(a) for a in args] + [f"{k}={v!r}" for k, v in kwargs.items()]
+        )
+        print(f"[{timestamp}] 🚀 Calling: {func.__name__}({arg_list})")
+        try:
+            result = func(*args, **kwargs)
+            print(f"[{timestamp}] ✅ Finished: {func.__name__}")
+            return result
+        except Exception as e:
+            print(f"[{timestamp}] ❌ Error in {func.__name__}: {e}")
+            raise
+    return wrapper

src/chatbot/prompts/economic_news.txt

@@ -0,0 +1,2 @@
+Provide an update on major economic indicators released today.
+Include interest rates, unemployment data, and other relevant statistics.

src/chatbot/prompts/market_sentiment.txt

@@ -0,0 +1 @@
+What is the current market sentiment based on the news and market index?

src/chatbot/prompts/news_headlines.txt

@@ -0,0 +1,5 @@
+Tell me the top 3 world headlines. Present me the headlines in the following way:
+- Show the title in Bold
+- Summerize the headline in 3 lines.
+- show me the headline publish date and time.
+- give me a link to the exct source url.

src/chatbot/prompts/trade_recommendation.txt

@@ -0,0 +1,4 @@
+Recommend 3 option spreades which has more than 80% likelihood of profiting me. 
+You must do a **thorough analysis** of the stocks 3 months trend and study the market sentiment to conclude into the answer.
+Explain each spread legs with the strike price, exact expiry date and premium entry.
+Provide a rational of your recommendation and likelyhood of winning it in %.

src/chatbot/prompts/upcoming_earnings.txt

@@ -0,0 +1 @@
+Provide me the upcoming critical earnings in next 2 weeks.

src/chatbot/tools/google_tools.py

@@ -0,0 +1,145 @@
+import os
+import requests
+from dotenv import load_dotenv
+from agents import function_tool
+from core.logger import log_call
+
+# Load environment variables once
+load_dotenv()
+
+
+# ============================================================
+# 🔹 GOOGLE SEARCH TOOLSET (Serper.dev API)
+# ============================================================
+class GoogleTools:
+    """
+    GoogleTools provides function tools to perform web searches
+    using the Serper.dev API (Google Search). I am a fallback for
+    retrieving recent information from the web.
+
+    Features:
+    - Search for recent web pages.
+    - Limit number of results.
+    - Returns formatted title, link, date, and snippet for each result.
+    """
+
+    @staticmethod
+    @function_tool
+    @log_call
+    def search(query: str, num_results: int = 3) -> str:
+        """
+        Perform a general Google search using Serper.dev API.
+
+        Parameters:
+        -----------
+        query : str
+            The search query string, e.g., "latest Tesla stock news".
+        num_results : int, optional (default=3)
+            Maximum number of search results to return.
+
+        Returns:
+        --------
+        str
+            Formatted string of top search results, each including:
+            - Title of the page
+            - URL link
+            - Published date
+            - Snippet / description
+            If no results are found or API key is missing, returns an error message.
+
+        Example:
+        --------
+        search("AI in finance", num_results=2)
+
+        Output:
+        Title: How AI is Transforming Finance
+        Link: https://example.com/ai-finance
+        Published: 2024-06-15
+        Snippet: AI is increasingly used for trading, risk management...
+        
+        Title: AI Applications in Banking
+        Link: https://example.com/ai-banking
+        Published: 2024-06-10
+        Snippet: Banks are leveraging AI for customer service, fraud detection...
+        """
+        try:
+            api_key = os.getenv("SERPER_API_KEY")
+            if not api_key:
+                return "Missing SERPER_API_KEY in environment variables."
+
+            url = "https://google.serper.dev/search"
+            headers = {"X-API-KEY": api_key, "Content-Type": "application/json"}
+            payload = {"q": query, "num": num_results, "tbs": "qdr:d"}  # results from last 24h
+
+            response = requests.post(url, headers=headers, json=payload)
+            response.raise_for_status()
+            data = response.json()
+
+            if "organic" not in data or not data["organic"]:
+                return "No results found."
+
+            formatted_results = [
+                f"Title: {item.get('title')}\n"
+                f"Link: {item.get('link')}\n"
+                f"Snippet: {item.get('snippet', '')}\n"
+                for item in data["organic"][:num_results]
+            ]
+            return "\n".join(formatted_results)
+
+        except requests.exceptions.RequestException as e:
+            return f"Network error during Google search: {e}"
+        except Exception as e:
+            return f"Error performing Google search: {e}"
+
+
+# ============================================================
+# 🔹 OPENAI & OTHER MODEL TOOLS
+# ============================================================
+class ModelTools:
+    """
+    ModelTools provides function tools to interact with LLM APIs
+    such as OpenAI, Gemini, or Groq. 
+
+    Features:
+    - Send prompts to a language model.
+    - Receive structured text completions.
+    - Can be extended to support multiple LLM providers.
+    """
+
+    @staticmethod
+    @function_tool
+    def query_openai(prompt: str, model: str = "gpt-4o-mini") -> str:
+        """
+        Query an OpenAI language model with a prompt.
+
+        Parameters:
+        -----------
+        prompt : str
+            User-provided prompt for the model.
+        model : str, optional (default="gpt-4o-mini")
+            Model name to query (e.g., "gpt-4o-mini", "gpt-4").
+
+        Returns:
+        --------
+        str
+            Model's response content as text.
+            If an error occurs (network/API), returns an error message.
+
+        Example:
+        --------
+        query_openai("Explain AI in finance")
+
+        Output:
+        "AI in finance refers to the use of machine learning and natural language
+        processing techniques to automate trading, risk assessment, and customer service..."
+        """
+        try:
+            from openai import OpenAI  # delayed import
+            client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+            response = client.chat.completions.create(
+                model=model,
+                messages=[{"role": "user", "content": prompt}],
+            )
+            return response.choices[0].message.content
+        except Exception as e:
+            return f"Error querying OpenAI API: {e}"

src/chatbot/tools/news_tools.py

@@ -0,0 +1,129 @@
+import os
+import requests
+from dotenv import load_dotenv
+from agents import function_tool
+from core.logger import log_call
+import datetime
+
+# Load environment variables once
+load_dotenv()
+
+
+# ============================================================
+# 🔹 NEWS TOOLSET (NewsAPI.org)
+# ============================================================
+class NewsTools:
+    """
+    NewsTools provides function tools to fetch recent news headlines or
+    topic-specific articles from NewsAPI.org. Always returns recent data.
+    """
+
+    @staticmethod
+    @function_tool
+    @log_call
+    def top_headlines(country: str = "us", num_results: int = 5) -> str:
+        """
+        Fetch the latest top headlines for a country.
+
+        Parameters:
+        -----------
+        country : str, optional (default="us")
+            Two-letter country code.
+        num_results : int, optional (default=5)
+            Number of articles to fetch.
+
+        Returns:
+        --------
+        str
+            Formatted headlines with title, source, and URL.
+        """
+        return NewsTools._fetch_news(query="", country=country, num_results=num_results)
+
+    @staticmethod
+    @function_tool
+    @log_call
+    def search_news(query: str, num_results: int = 5) -> str:
+        """
+        Search for recent news articles about a specific topic.
+
+        Parameters:
+        -----------
+        query : str
+            Keyword or topic to search (e.g., "Tesla earnings").
+        num_results : int, optional (default=5)
+            Number of articles to fetch.
+
+        Returns:
+        --------
+        str
+            Formatted news articles with title, source, and URL.
+        """
+        return NewsTools._fetch_news(query=query, country="", num_results=num_results)
+
+    @staticmethod
+    @log_call
+    def _fetch_news(query: str, country: str, num_results: int) -> str:
+        """
+        Internal helper to fetch news from NewsAPI.org.
+
+        Ensures always recent news (last 7 days).
+
+        Parameters:
+        -----------
+        query : str
+            Search query (leave empty for top headlines).
+        country : str
+            Two-letter country code (ignored if query provided).
+        num_results : int
+            Max articles to return.
+
+        Returns:
+        --------
+        str
+            Formatted articles or error message.
+        """
+        try:
+            api_key = os.getenv("NEWS_API_KEY")
+            if not api_key:
+                return "Missing NEWS_API_KEY in environment variables."
+
+            today = datetime.datetime.utcnow()
+            from_date = (today - datetime.timedelta(days=7)).strftime('%Y-%m-%dT%H:%M:%SZ')
+
+            if query:
+                url = "https://newsapi.org/v2/everything"
+                params = {
+                    "q": query,
+                    "pageSize": num_results,
+                    "apiKey": api_key,
+                    "sortBy": "publishedAt",
+                    "language": "en",
+                    "from": from_date
+                }
+            else:
+                url = "https://newsapi.org/v2/top-headlines"
+                params = {
+                    "country": country or "us",
+                    "pageSize": num_results,
+                    "apiKey": api_key
+                }
+
+            response = requests.get(url, params=params)
+            response.raise_for_status()
+            data = response.json()
+
+            if not data.get("articles"):
+                return f"No news found for '{query or country}'."
+
+            formatted = [
+                f"📰 {a.get('title')}\n"
+                f"   Source: {a.get('source', {}).get('name')}\n"
+                f"   URL: {a.get('url')}\n"
+                for a in data["articles"][:num_results]
+            ]
+            return "\n".join(formatted)
+
+        except requests.exceptions.RequestException as e:
+            return f"Network error while calling News API: {e}"
+        except Exception as e:
+            return f"Unexpected error fetching news: {e}"

src/chatbot/tools/time_tools.py

@@ -0,0 +1,22 @@
+from datetime import datetime
+from agents import function_tool
+from core.logger import log_call
+
+class TimeTools:
+    """Provides tools related to current date and time."""
+
+    @staticmethod
+    @function_tool
+    @log_call
+    def current_datetime(format: str = "%Y-%m-%d %H:%M:%S") -> str:
+        """
+        Returns the current date and time as a formatted string.
+        
+        Args:
+            format (str): Optional datetime format (default: "YYYY-MM-DD HH:MM:SS")
+        
+        Returns:
+            str: Current date and time in the specified format
+        """
+        now = datetime.now()
+        return now.strftime(format)

src/chatbot/tools/yahoo_tools.py

@@ -0,0 +1,206 @@
+import os
+import requests
+import yfinance as yf
+from dotenv import load_dotenv
+from agents import function_tool
+from core.logger import log_call
+from datetime import datetime, timedelta
+
+# Load environment variables
+load_dotenv()
+
+
+# ============================================================
+# 🔹 YAHOO FINANCE TOOLSET
+# ============================================================
+class FinanceTools:
+    """
+    FinanceTools provides a set of function tools for interacting with Yahoo Finance for **Financial Data** only.
+    These tools can be used by an AI agent to fetch stock, ETF, or crypto data,
+    analyze recent market trends, market sentiments, and generate market insights.
+    """
+
+    @staticmethod
+    @function_tool
+    @log_call
+    def get_summary(symbol: str, period: str = "1d", interval: str = "1h") -> str:
+        """
+        Fetch the latest summary information and intraday price data for a given ticker.
+        Ensures recent data is retrieved by calculating start/end dates dynamically.
+
+        Parameters:
+        -----------
+        symbol : str
+            The ticker symbol (e.g., "AAPL", "GOOG", "BTC-USD").
+        period : str, optional (default="1d")
+            Time range for price data. Examples: "1d", "5d", "1mo", "3mo".
+        interval : str, optional (default="1h")
+            Granularity of the data. Examples: "1m", "5m", "1h", "1d".
+
+        Returns:
+        --------
+        str
+            A formatted string containing:
+            - Company/ticker name
+            - Current price and change
+            - Open, High, Low prices
+            - Volume
+            - Period and interval used
+        """
+        try:
+            ticker = yf.Ticker(symbol)
+
+            # Calculate start and end dates based on period
+            end_date = datetime.today()
+            if period.endswith("d"):
+                days = int(period[:-1])
+            elif period.endswith("mo"):
+                days = int(period[:-2]) * 30
+            elif period.endswith("y"):
+                days = int(period[:-1]) * 365
+            else:
+                days = 30  # default 1 month
+            start_date = end_date - timedelta(days=days)
+
+            # Fetch recent data explicitly
+            data = ticker.history(
+                start=start_date.strftime("%Y-%m-%d"),
+                end=end_date.strftime("%Y-%m-%d"),
+                interval=interval
+            )
+
+            if data.empty:
+                return f"No data found for symbol '{symbol}'."
+
+            latest = data.iloc[-1]
+            current_price = round(latest["Close"], 2)
+            open_price = round(latest["Open"], 2)
+            change = round(current_price - open_price, 2)
+            pct_change = round((change / open_price) * 100, 2)
+
+            info = ticker.info
+            long_name = info.get("longName", symbol)
+            currency = info.get("currency", "USD")
+
+            formatted = [
+                f"📈 {long_name} ({symbol})",
+                f"Current Price: {current_price} {currency}",
+                f"Change: {change} ({pct_change}%)",
+                f"Open: {open_price} | High: {round(latest['High'], 2)} | Low: {round(latest['Low'], 2)}",
+                f"Volume: {int(latest['Volume'])}",
+                f"Period: {period} | Interval: {interval}",
+            ]
+            return "\n".join(formatted)
+
+        except Exception as e:
+            return f"Error fetching data for '{symbol}': {e}"
+
+    @staticmethod
+    @function_tool
+    @log_call
+    def get_market_sentiment(symbol: str, period: str = "1mo") -> str:
+        """
+        Analyze recent price changes and provide a simple market sentiment.
+        Uses dynamic start/end dates to ensure recent data.
+
+        This tool computes the percentage change over the specified period and
+        classifies the sentiment as:
+        - Bullish (if price increased >2%)
+        - Bearish (if price decreased >2%)
+        - Neutral (otherwise)
+
+        Parameters:
+        -----------
+        symbol : str
+            The ticker symbol (e.g., "AAPL", "GOOG", "BTC-USD").
+        period : str, optional (default="1mo")
+            Time range to analyze. Examples: "7d", "1mo", "3mo".
+
+        Returns:
+        --------
+        str
+            A human-readable sentiment string including percentage change.
+        """
+        try:
+            ticker = yf.Ticker(symbol)
+
+            # Calculate start/end dynamically
+            end_date = datetime.today()
+            if period.endswith("d"):
+                days = int(period[:-1])
+            elif period.endswith("mo"):
+                days = int(period[:-2]) * 30
+            elif period.endswith("y"):
+                days = int(period[:-1]) * 365
+            else:
+                days = 30
+            start_date = end_date - timedelta(days=days)
+
+            data = ticker.history(
+                start=start_date.strftime("%Y-%m-%d"),
+                end=end_date.strftime("%Y-%m-%d")
+            )
+
+            if data.empty:
+                return f"No data for {symbol}."
+
+            recent_change = data["Close"].iloc[-1] - data["Close"].iloc[0]
+            pct_change = (recent_change / data["Close"].iloc[0]) * 100
+
+            sentiment = "Neutral"
+            if pct_change > 2:
+                sentiment = "Bullish"
+            elif pct_change < -2:
+                sentiment = "Bearish"
+
+            return f"{symbol} market sentiment ({period}): {sentiment} ({pct_change:.2f}% change)"
+
+        except Exception as e:
+            return f"Error fetching market sentiment for '{symbol}': {e}"
+
+    @staticmethod
+    @function_tool
+    @log_call
+    def get_history(symbol: str, period: str = "1mo") -> str:
+        """
+        Fetch historical price data for a given ticker.
+        Ensures recent data is retrieved dynamically using start/end dates.
+
+        Parameters:
+        -----------
+        symbol : str
+            The ticker symbol (e.g., "AAPL", "GOOG", "BTC-USD").
+        period : str, optional (default="1mo")
+            The length of historical data to retrieve. Examples: "1d", "5d", "1mo", "3mo", "1y", "5y".
+
+        Returns:
+        --------
+        str
+            A formatted string showing the last 5 rows of historical prices (Open, High, Low, Close, Volume).
+        """
+        try:
+            ticker = yf.Ticker(symbol)
+
+            # Calculate start/end dynamically
+            end_date = datetime.today()
+            if period.endswith("d"):
+                days = int(period[:-1])
+            elif period.endswith("mo"):
+                days = int(period[:-2]) * 30
+            elif period.endswith("y"):
+                days = int(period[:-1]) * 365
+            else:
+                days = 30
+            start_date = end_date - timedelta(days=days)
+
+            data = ticker.history(
+                start=start_date.strftime("%Y-%m-%d"),
+                end=end_date.strftime("%Y-%m-%d")
+            )
+
+            if data.empty:
+                return f"No historical data found for '{symbol}'."
+            return f"Historical data for {symbol} ({period}):\n{data.tail(5).to_string()}"
+
+        except Exception as e:
+            return f"Error fetching historical data for '{symbol}': {e}"