Upload folder using huggingface_hub

Dockerfile

@@ -0,0 +1,36 @@
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    DEBIAN_FRONTEND=noninteractive \
+    PYTHONPATH=/app/src/interview-assistant:$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 application code
+COPY common/ ./common/
+COPY src/interview-assistant/ ./src/interview-assistant/
+
+# Install dependencies using uv, then export and install with pip to system
+# We use --no-dev to exclude dev dependencies if any
+RUN uv sync --frozen --no-dev && \
+    uv pip install -e . --system
+
+# Copy entry point
+COPY run.py .
+
+EXPOSE 7860
+
+CMD ["python", "run.py", "interview-assistant", "--port", "7860"]

README.md

@@ -1,10 +1,68 @@
----
-title: Interview Assistant
-emoji: 🌍
-colorFrom: indigo
-colorTo: pink
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: Interviewer Assistant
+emoji: 👔
+colorFrom: green
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+short_description: Agentic AI for Resume Analysis & Interview Prep
+---
+
+# 👔 Interviewer Assistant
+
+A **Multi-Agent System** designed to assist HR and technical interviewers by automatically analyzing job descriptions and resumes to generate tailored interview questions and fitness scores.
+
+## 🚀 Features
+
+- **🧠 Multi-Agent Swarm**:
+  - **Job Analyst**: Extracts key requirements from JDs.
+  - **Candidate Profiler**: Analyzes resumes for strengths and gaps.
+  - **Evaluator**: Scores candidates on Technical, Behavioral, and Leadership metrics.
+  - **Interview Designer**: Generates bespoke interview questions.
+- **📄 Input Flexibility**: Accepts raw text for JD and Resume/LinkedIn profile.
+- **📊 Structured Evaluation**: Provides a clear score and justification.
+
+## 🛠️ Architecture
+
+```
+src/interview-assistant/
+├── app.py                  # Streamlit UI (Orchestrator)
+├── teams/                  # Team Definitions
+│   └── team.py             # GroupChat Configuration
+├── aagents/                # Agent Definitions
+│   ├── job_analyst.py      
+│   ├── candidate_profiler.py
+│   ├── evaluator.py
+│   ├── interview_designer.py 
+│   └── admin.py            
+└── Dockerfile              # Deployment Configuration
+```
+
+## 📦 Startup
+
+### Local Run
+
+1. **Install Dependencies**:
+   ```bash
+   pip install -r src/interviewer-assistant/requirements.txt
+   ```
+
+2. **Run Application**:
+   ```bash
+   streamlit run src/interviewer-assistant/app.py
+   ```
+   The app will open at `http://localhost:8501`.
+
+## 🐳 Docker / Deployment
+
+The project is packaged for **Hugging Face Spaces** (Docker SDK).
+
+```bash
+# Build
+docker build -t interviewer-assistant -f src/interviewer-assistant/Dockerfile .
+
+# Run
+docker run -p 7860:7860 interviewer-assistant
+```

common/aagents/core/__init__.py

@@ -0,0 +1,4 @@
+
+from .model import get_model_client
+
+__all__ = ["get_model_client"]

common/aagents/core/model.py

@@ -0,0 +1,36 @@
+from common.utility.openai_model_factory  import OpenAIModelFactory
+
+def get_model_client(provider:str = "openai"):
+    if provider.lower() == "google":
+        return OpenAIModelFactory.get_model(
+            provider="google",
+            model_name="gemini-2.5-flash",
+            temperature=0
+    )
+    elif provider.lower() == "openai":
+        return OpenAIModelFactory.get_model(
+            provider="openai",
+            model_name="gpt-4.1-mini",
+            temperature=0
+    )
+    elif provider.lower() == "azure":
+        return OpenAIModelFactory.get_model(
+            provider="azure",
+            model_name="gpt-4o-mini",
+            temperature=0
+    )
+    elif provider.lower() == "groq":
+        return OpenAIModelFactory.get_model(
+            provider="groq",
+            model_name="gpt-4o-mini",
+            temperature=0
+    )
+    elif provider.lower() == "ollama":
+        return OpenAIModelFactory.get_model(
+            provider="ollama",
+            model_name="gpt-4o-mini",
+            temperature=0
+    )
+    else: 
+        raise  ValueError(f"Unsupported provider: {provider}")
+

common/aagents/google_agent.py

@@ -0,0 +1,123 @@
+"""Google search agent module for web search and information retrieval."""
+from agents import Agent
+from common.mcp.tools.google_tools import google_search, google_search_recent
+from common.mcp.tools.search_tools import duckduckgo_search, fetch_page_content
+from common.mcp.tools.time_tools import current_datetime
+from .core.model import get_model_client
+
+google_agent = Agent(
+    name="GoogleSearchAgent",
+    model=get_model_client(),
+    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
+        """,
+)
+google_agent.description = "A Google search agent that finds accurate, up-to-date information and recent news using Google Search."
+
+__all__ = ["google_agent", "google_search", "google_search_recent", "duckduckgo_search", "fetch_page_content", "current_datetime"]

common/aagents/healthcare_agent.py

@@ -0,0 +1,79 @@
+"""Healthcare RAG Agent - Combines RAG retrieval with web search for comprehensive medical information."""
+from agents import Agent
+from common.mcp.tools.rag_tool import rag_search, UserContext
+from common.mcp.tools.search_tools import duckduckgo_search, fetch_page_content
+from common.mcp.tools.time_tools import current_datetime
+from .core.model import get_model_client
+      
+
+# ---------------------------------------------------------
+# Healthcare RAG Agent
+# ---------------------------------------------------------
+healthcare_agent = Agent[UserContext](
+    name="HealthcareRAGAgent",
+    model=get_model_client(),
+    tools=[rag_search, duckduckgo_search, fetch_page_content],
+    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
+        """,
+)
+healthcare_agent.description = "A healthcare agent that combines RAG (Retrieval Augmented Generation) with web search to answer medical questions."
+
+__all__ = ["healthcare_agent"]

common/aagents/news_agent.py

@@ -0,0 +1,80 @@
+"""News agent module for fetching and analyzing news articles."""
+from agents import Agent
+from common.mcp.tools.news_tools import get_top_headlines, search_news, get_news_by_category
+from common.mcp.tools.time_tools import current_datetime
+from .core.model import get_model_client
+
+news_agent = Agent(
+    name="NewsAgent",
+    model=get_model_client(),
+    tools=[current_datetime, get_top_headlines, search_news, get_news_by_category],
+    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 }
+
+        **TIME CONTEXT:**
+        4. '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. **Execute Search**: Use the appropriate NewsAPI tool.
+        
+        3. **Include Time Context**: Use current_datetime to provide temporal context.
+        
+        4. **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)
+        - 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
+        """,
+)
+news_agent.description = "A news agent that fetches top headlines and searches for news articles by category or topic."
+
+__all__ = ["news_agent", "get_top_headlines", "search_news", "get_news_by_category", "current_datetime"]

common/aagents/search_agent.py

@@ -0,0 +1,39 @@
+"""Search agent module for comprehensive web searches."""
+from agents import Agent
+from common.mcp.tools.search_tools import duckduckgo_search, fetch_page_content
+from common.mcp.tools.time_tools import current_datetime
+from .core.model import get_model_client
+
+search_agent = Agent(
+    name="Web Search Agent",
+    model=get_model_client(),    
+    tools=[current_datetime, duckduckgo_search, fetch_page_content],
+    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 **duckduckgo_search** and **fetch_page_content** functions. You must act as a digital librarian and researcher, providing synthesized, cited, and up-to-date answers.
+
+        ## Core Directives & Priorities
+        1.  **Time Awareness First:** ALWAYS invoke **current_datetime** at the very beginning of your execution to establish the current temporal context. This is crucial for answering questions about "today", "yesterday", or recent events.
+        2.  **Search Strategy:**
+            *   Analyze the user's request and construct 1-3 targeted search queries.
+            *   Use **duckduckgo_search** to find relevant information. Use the 'news' type for current events.
+            *   **Mandatory Deep Dive:** You MUST select the **top 3** most relevant search results and use **fetch_page_content** to retrieve their full text. *Do not rely solely on the short search snippets.*
+        3.  **Synthesis & Answer Construction:**
+            *   Read the fetched content thoroughly.
+            *   Synthesize the information into a coherent answer.
+            *   **Conflict Resolution:** If sources disagree, note the discrepancy and favor the most recent or authoritative source.
+            *   **Citations:** You **must** cite your sources. At the end of your response, list the *Title* and *URL* of the pages you used.
+        4.  **Clarity:** Use professional, plain language. Use headings and bullet points for readability.
+        5.  **Data Gaps:** If you cannot find a conclusive answer after searching and fetching, state: **"A conclusive answer could not be verified by current web search results."**
+
+        ## Workflow Example
+        1.  Call `current_datetime()`.
+        2.  Call `duckduckgo_search(query="...")`.
+        3.  Loop through top 3 results: `fetch_page_content(url=...)`.
+        4.  Synthesize findings into final answer.
+
+        **Crucially, never fabricate information. Your answer must be grounded in the text you have fetched.**
+    """,
+)
+search_agent.description = "A web search agent that retrieves information using DuckDuckGo and fetches page content for detailed answers."
+
+__all__ = ["search_agent"]

common/aagents/weather_agent.py

@@ -0,0 +1,44 @@
+"""Web search agent module for internet queries."""
+import os
+from agents import Agent
+from pydantic import BaseModel, Field
+from common.mcp.tools.weather_tools import get_weather_forecast, search_weather_fallback_ddgs, search_weather_fallback_bs
+from common.mcp.tools.time_tools import current_datetime
+from .core.model import get_model_client
+    
+
+weather_agent = Agent(
+    name="WeatherAgent",
+    model=get_model_client(),
+    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)"
+                }
+            }.
+        ]
+        """,
+)
+weather_agent.description = "A weather agent that provides current and forecasted weather information for specific cities."
+
+__all__ = ["weather_agent", "get_weather_forecast", "search_weather_fallback_ddgs", "search_weather_fallback_bs"]

common/aagents/web_agent.py

@@ -0,0 +1,27 @@
+"""Web search agent module for internet queries."""
+from agents import Agent
+from common.mcp.tools.search_tools import duckduckgo_search, searchQuery, searchResult
+from .core.model import get_model_client
+    
+web_agent = Agent(
+    name="WebAgent",
+    model=get_model_client(),
+    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,58 @@
+"""Web search agent module for internet queries."""
+from agents import AgentOutputSchema, function_tool, Agent
+from pydantic import BaseModel, Field
+from common.mcp.tools.search_tools import duckduckgo_search, searchQuery, searchResult, fetch_page_content
+from .core.model import get_model_client
+
+web_research_agent = Agent(
+    model=get_model_client(),
+    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.
+"""
+    ,
+)
+web_research_agent.description = "A deep research agent that performs extensive web searches and content fetching for complex research queries."
+
+__all__ = ["web_research_agent", "duckduckgo_search", "fetch_page_content", "searchQuery", "searchResult"]

common/aagents/yf_agent.py

@@ -0,0 +1,68 @@
+"""Yahoo Finance agent module for financial analysis and market research."""
+from agents import Agent
+from common.mcp.tools.yf_tools import get_summary, get_market_sentiment, get_history, get_analyst_recommendations, get_earnings_calendar
+from common.mcp.tools.time_tools import current_datetime
+from .core.model import get_model_client
+
+
+yf_agent = Agent( 
+    name="YahooFinanceAgent",
+    model=get_model_client(),
+    tools=[current_datetime, get_summary, get_market_sentiment, get_history, get_analyst_recommendations, get_earnings_calendar],
+    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.
+           - 'get_analyst_recommendations': Fetch latest analyst ratings (Buy/Sell/Hold) for a symbol to provide **trading recommendations**.
+           - 'get_earnings_calendar': Fetch upcoming earnings dates for a symbol.
+           
+           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, recommendations) 
+           to provide a complete analytical perspective (e.g., "Stock X is up 5% today driven by strong market momentum and a generic 'Buy' rating from analysts").
+        
+        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_analyst_recommendations
+        Input: { "symbol": "AAPL" }
+
+        Tool: get_earnings_calendar
+        Input: { "symbol": "AAPL" }
+
+        ## 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."
+        """,
+)
+yf_agent.description = "A financial analysis agent that provides stock summaries, market sentiment, and historical data using Yahoo Finance."
+
+__all__ = ["yf_agent", "get_summary", "get_market_sentiment", "get_history", "get_analyst_recommendations", "get_earnings_calendar", "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,141 @@
+import os
+import requests
+
+from agents import function_tool
+from typing import Optional
+
+
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+
+
+# ============================================================
+# 🔹 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,206 @@
+import os
+import requests
+
+from agents import function_tool
+from typing import Optional
+import datetime
+
+
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+
+
+# ============================================================
+# 🔹 NEWS TOOLSET (NewsAPI.org)
+# ============================================================
+
+def _search_news(query: str, num_results: int = 5, days_back: int = 7) -> str:
+   
+    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_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.
+    """
+    return _search_news(query, num_results, days_back)
+
+
+@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,93 @@
+"""RAG Search Tool - Search the local healthcare knowledge base"""
+import os
+from pathlib import Path
+from agents import function_tool, RunContextWrapper
+
+from common.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
+
+
+# ---------------------------------------------------------
+# 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,142 @@
+import requests
+from ddgs import DDGS
+from agents import function_tool
+
+from pydantic import BaseModel, Field
+from bs4 import BeautifulSoup
+from typing import Optional
+
+
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+
+
+# ---------------------- 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 ---------------------------
+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
+
+
+@function_tool
+def fetch_page_content(url: str, timeout: int = 3) -> Optional[str]:
+    """Fetch and extract text content from a web page."""
+    return _fetch_page_content(url, timeout)
+
+
+# ---------------------- SEARCH 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
+
+@function_tool
+def duckduckgo_search(query: str, max_results: int = 5, search_type: str = "text", timelimit: str = "d", region: str = "us-en") -> list[dict]:
+    """
+    Perform a DuckDuckGo search and return only snippets.
+    
+    Args:
+        query: The search query string.
+        max_results: The maximum number of search results to return (default: 5).
+        search_type: Search type: 'text' (default) or 'news'. Use 'news' to get publication dates.
+        timelimit: Time limit for search results: 'd' (day), 'w' (week), 'm' (month), 'y' (year).
+        region: Region for search results (e.g., 'us-en').
+    """
+    params = searchQuery(
+        query=query, 
+        max_results=max_results, 
+        search_type=search_type, 
+        timelimit=timelimit, 
+        region=region
+    )
+    return _duckduckgo_search(params)
+

common/mcp/tools/time_tools.py

@@ -0,0 +1,35 @@
+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
+    """
+    print(f"[DEBUG] current_datetime called with format='{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,237 @@
+import os
+import re
+import requests
+import datetime
+
+from typing import Optional
+
+from ddgs import DDGS
+from agents import function_tool
+
+
+
+# ---------------------------------------------------------
+# Load environment variables
+# ---------------------------------------------------------
+
+
+@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,274 @@
+import os
+import requests
+import yfinance as yf
+
+from agents import function_tool
+from datetime import datetime, timedelta
+
+
+
+# Load environment variables
+
+
+
+# ============================================================
+# 🔹 YAHOO FINANCE TOOLSET
+# ============================================================
+def _get_summary(symbol: str, period: str = "1d", interval: str = "1h") -> str:
+    print(f"[DEBUG] get_summary called for symbol='{symbol}', period='{period}', interval='{interval}'")
+    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}"
+
+def _get_market_sentiment(symbol: str, period: str = "1mo") -> str:
+    print(f"[DEBUG] get_market_sentiment called for symbol='{symbol}', period='{period}'")
+    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}"
+
+def _get_history(symbol: str, period: str = "1mo") -> str:
+    print(f"[DEBUG] get_history called for symbol='{symbol}', period='{period}'")
+    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}"
+
+def _get_analyst_recommendations(symbol: str) -> str:
+    print(f"[DEBUG] get_analyst_recommendations called for symbol='{symbol}'")
+    try:
+        ticker = yf.Ticker(symbol)
+        recs = ticker.recommendations
+        if recs is None or recs.empty:
+             return f"No analyst recommendations found for {symbol}."
+        
+        # Format the last few recommendations
+        latest = recs.tail(5)
+        return f"Analyst Recommendations for {symbol}:\n{latest.to_string()}"
+    except Exception as e:
+         return f"Error fetching recommendations for '{symbol}': {e}"
+
+def _get_earnings_calendar(symbol: str) -> str:
+    print(f"[DEBUG] get_earnings_calendar called for symbol='{symbol}'")
+    try:
+        ticker = yf.Ticker(symbol)
+        calendar = ticker.calendar
+        if calendar is None:
+            return f"No earnings calendar found for {symbol}."
+        
+        # Handle dict (new yfinance) or DataFrame (old yfinance)
+        if isinstance(calendar, dict):
+             if not calendar:
+                 return f"No earnings calendar found for {symbol}."
+        elif hasattr(calendar, 'empty') and calendar.empty:
+             return f"No earnings calendar found for {symbol}."
+            
+        return f"Earnings Calendar for {symbol}:\n{calendar}"
+    except Exception as e:
+         return f"Error fetching earnings calendar for '{symbol}': {e}"
+           
+@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
+    """
+    return _get_summary(symbol, period, interval)
+    
+@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.
+    """
+    return _get_market_sentiment(symbol, period)
+
+@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).
+    """
+    return _get_history(symbol, period)
+
+@function_tool
+def get_analyst_recommendations(symbol: str) -> str:
+    """
+    Fetch analyst recommendations for a given ticker.
+    
+    Parameters:
+    -----------
+    symbol : str
+        The ticker symbol.
+
+    Returns:
+    --------
+    str
+        Formatted string string of analyst recommendations.
+    """
+    return _get_analyst_recommendations(symbol)
+
+@function_tool
+def get_earnings_calendar(symbol: str) -> str:
+    """
+    Fetch the next earnings date for a ticker.
+
+    Parameters:
+    -----------
+    symbol : str
+        The ticker symbol.
+
+    Returns:
+    --------
+    str
+        Next earnings date info.
+    """
+    return _get_earnings_calendar(symbol)
+

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=300,
+            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/autogen_model_factory.py

@@ -0,0 +1,88 @@
+import os
+from azure.identity import DefaultAzureCredential, get_bearer_token_provider
+
+class AutoGenModelFactory:
+    """
+    Factory for creating AutoGen compatible model instances.
+    """
+
+    @staticmethod
+    def get_model(provider: str = "azure", # azure, openai, google, groq, ollama
+                  model_name: str = "gpt-4o", 
+                  temperature: float = 0,
+                  model_info: dict = None
+                  ):
+        """
+        Returns an AutoGen OpenAIChatCompletionClient instance.
+        """
+        
+        # Lazy import to avoid dependency issues if autogen is not installed
+        try:
+            from autogen_ext.models.openai import OpenAIChatCompletionClient
+        except ImportError as e:
+            raise ImportError("AutoGen libraries (autogen-agentchat, autogen-ext[openai]) are not installed.") from e
+
+        # ----------------------------------------------------------------------
+        # AZURE
+        # ----------------------------------------------------------------------
+        if provider.lower() == "azure":
+            token_provider = get_bearer_token_provider(
+                DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
+            )
+            return OpenAIChatCompletionClient(
+                model=model_name,
+                azure_endpoint=os.environ["AZURE_OPENAI_API_URI"],
+                api_version=os.environ["AZURE_OPENAI_API_VERSION"],
+                azure_ad_token_provider=token_provider,
+                temperature=temperature,
+            )
+
+        # ----------------------------------------------------------------------
+        # OPENAI
+        # ----------------------------------------------------------------------
+        elif provider.lower() == "openai":
+            return OpenAIChatCompletionClient(
+                model=model_name,
+                api_key=os.environ["OPENAI_API_KEY"],
+                temperature=temperature,
+            )
+        
+        # ----------------------------------------------------------------------
+        # GOOGLE (GEMINI) via OpenAI Compat
+        # ----------------------------------------------------------------------
+        elif provider.lower() == "google" or provider.lower() == "gemini":
+            return OpenAIChatCompletionClient(
+                model=model_name,
+                base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
+                api_key=os.environ["GOOGLE_API_KEY"],
+                model_info=model_info, # Pass full model_info for capabilities
+                temperature=temperature,
+            )
+
+        # ----------------------------------------------------------------------
+        # GROQ
+        # ----------------------------------------------------------------------
+        elif provider.lower() == "groq":
+            return OpenAIChatCompletionClient(
+                model=model_name,
+                base_url="https://api.groq.com/openai/v1",
+                api_key=os.environ["GROQ_API_KEY"],
+                temperature=temperature,
+            )
+        
+        # ----------------------------------------------------------------------
+        # OLLAMA
+        # ----------------------------------------------------------------------
+        elif provider.lower() == "ollama":
+            # Ensure model_info defaults to empty dict if None
+            info = model_info if model_info is not None else {}
+            return OpenAIChatCompletionClient(
+                model=model_name,
+                base_url="http://localhost:11434/v1",
+                api_key="ollama", # dummy key
+                model_info=info,
+                temperature=temperature,
+            )
+        
+        else:
+            raise ValueError(f"Unsupported AutoGen provider: {provider}")

common/utility/bkp/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/bkp/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/bkp/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/langchain_model_factory.py

@@ -0,0 +1,70 @@
+import os
+from azure.identity import DefaultAzureCredential, get_bearer_token_provider
+from langchain_openai import AzureChatOpenAI, ChatOpenAI
+from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint
+from langchain_ollama import ChatOllama
+from huggingface_hub import login
+
+class LangChainModelFactory:
+    """
+    Factory for creating LangChain compatible model instances.
+    """
+
+    @staticmethod
+    def get_model(provider: str = "openai", # openai, azure, huggingface, ollama
+                  model_name: str = "gpt-4o", 
+                  temperature: float = 0
+                  ):
+        """
+        Returns a LangChain LLM instance.
+        """
+        
+        # ----------------------------------------------------------------------
+        # AZURE
+        # ----------------------------------------------------------------------
+        if provider.lower() == "azure":
+            token_provider = get_bearer_token_provider(
+                DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
+            )
+            return AzureChatOpenAI(
+                azure_endpoint=os.environ["AZURE_OPENAI_API_URI"],
+                azure_deployment=os.environ["AZURE_OPENAI_API_BASE_MODEL"], # Or specific model_name if deployment matches
+                api_version=os.environ["AZURE_OPENAI_API_VERSION"],
+                azure_ad_token_provider=token_provider,
+                model_name=model_name,
+                temperature=temperature,
+            )
+        
+        # ----------------------------------------------------------------------
+        # OPENAI
+        # ----------------------------------------------------------------------
+        elif provider.lower() == "openai":
+            return ChatOpenAI(
+                api_key=os.environ["OPENAI_API_KEY"],
+                model_name=model_name,
+                temperature=temperature,
+            )
+        
+        # ----------------------------------------------------------------------
+        # HUGGING FACE
+        # ----------------------------------------------------------------------
+        elif provider.lower() == "huggingface":
+            if os.environ.get("HF_TOKEN"):
+                login(token=os.environ.get("HF_TOKEN"))
+            llm = HuggingFaceEndpoint(
+                repo_id=model_name,
+                task="text-generation",
+                temperature=temperature,
+                max_new_tokens=512,
+                huggingfacehub_api_token=os.environ.get("HF_TOKEN")
+            )
+            return ChatHuggingFace(llm=llm)
+
+        # ----------------------------------------------------------------------
+        # OLLAMA
+        # ----------------------------------------------------------------------
+        elif provider.lower() == "ollama":
+            return ChatOllama(model=model_name, temperature=temperature)
+        
+        else:
+            raise ValueError(f"Unsupported LangChain provider: {provider}")

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

common/utility/model_factory_notused.py

@@ -0,0 +1,302 @@
+import os
+import tiktoken
+from typing import Union
+from azure.identity import DefaultAzureCredential, get_bearer_token_provider
+from langchain_openai import AzureChatOpenAI, ChatOpenAI, AzureOpenAIEmbeddings, OpenAIEmbeddings
+from agents import OpenAIChatCompletionsModel
+from openai import AsyncOpenAI, AsyncAzureOpenAI
+from huggingface_hub import login
+from langchain_huggingface import ChatHuggingFace, HuggingFaceEndpoint, HuggingFaceEmbeddings
+from langchain_ollama import ChatOllama, OllamaEmbeddings
+
+
+class ModelFactory:
+    """
+    A static utility class to create and return LLM instances based on the input type.
+    """
+
+    @staticmethod
+    def get_model(framework: str = "openai-sdk-agent", # openai-sdk-agent, langchain, autogen
+                  provider: str = "openai", # openai, azure, google, groq, huggingface, ollama
+                  model_name: str = "gpt-4o-mini", # gpt-4o-mini, gemini-flash-1.5, groq/compound
+                  model_info: dict = None, # additional info (e.g. backend provider for autogen/langchain)
+                  temperature: float = 0
+                  ) -> Union[AzureChatOpenAI, ChatOpenAI, OpenAIChatCompletionsModel, ChatHuggingFace, ChatOllama]:
+        """
+        Returns an LLM instance based on the specified parameters.
+
+        Parameters:
+            framework (str): The framework to use ('langchain', 'openai-sdk-agent', 'autogen').
+            provider (str): The model provider ('openai', 'azure', 'google', 'groq', 'huggingface', 'ollama').
+            model_name (str): The specific model name.
+            model_info (dict): Additional model info.
+            temperature (float): The temperature for generation (default 0).
+
+        Returns:
+            Union[...]: The model instance.
+        """
+        
+        # ----------------------------------------------------------------------
+        # AUTOGEN SUPPORT
+        # ----------------------------------------------------------------------
+        if framework.lower() == "autogen":
+            # Lazy import to avoid dependency issues if autogen is not installed
+            try:
+                from autogen_ext.models.openai import OpenAIChatCompletionClient
+            except ImportError as e:
+                raise ImportError("AutoGen libraries (autogen-agentchat, autogen-ext[openai]) are not installed.") from e
+
+            # Azure Backend
+            if provider.lower() == "azure":
+                token_provider = get_bearer_token_provider(
+                    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
+                )
+                return OpenAIChatCompletionClient(
+                    model=model_name,
+                    azure_endpoint=os.environ["AZURE_OPENAI_API_URI"],
+                    api_version=os.environ["AZURE_OPENAI_API_VERSION"],
+                    azure_ad_token_provider=token_provider,
+                    temperature=temperature,
+                )
+
+            # OpenAI Backend
+            elif provider.lower() == "openai":
+                return OpenAIChatCompletionClient(
+                    model=model_name,
+                    api_key=os.environ["OPENAI_API_KEY"],
+                    temperature=temperature,
+                )
+            
+            # Google Backend (Gemini via OpenAI compat)
+            elif provider.lower() == "google" or provider.lower() == "gemini":
+                return OpenAIChatCompletionClient(
+                    model=model_name,
+                    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
+                    api_key=os.environ["GOOGLE_API_KEY"],
+                    model_info=model_info, # Pass full model_info for capabilities
+                    temperature=temperature,
+                )
+
+            # Groq Backend
+            elif provider.lower() == "groq":
+                return OpenAIChatCompletionClient(
+                    model=model_name,
+                    base_url="https://api.groq.com/openai/v1",
+                    api_key=os.environ["GROQ_API_KEY"],
+                    temperature=temperature,
+                )
+            
+            # Ollama Backend
+            elif provider.lower() == "ollama":
+                # Ensure model_info defaults to empty dict if None
+                info = model_info if model_info is not None else {}
+                return OpenAIChatCompletionClient(
+                    model=model_name,
+                    base_url="http://localhost:11434/v1",
+                    api_key="ollama", # dummy key
+                    model_info=info,
+                    temperature=temperature,
+                )
+            
+            else:
+                raise ValueError(f"Unsupported AutoGen provider: {provider}")
+
+        # ----------------------------------------------------------------------
+        # LANGCHAIN SUPPORT
+        # ----------------------------------------------------------------------
+        elif framework.lower() == "langchain":
+            
+            if provider.lower() == "azure":
+                token_provider = get_bearer_token_provider(
+                    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
+                )
+                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"],
+                    azure_ad_token_provider=token_provider,
+                    model_name=model_name,
+                    temperature=temperature,
+                )
+            
+            elif provider.lower() == "openai":
+                return ChatOpenAI(
+                    api_key=os.environ["OPENAI_API_KEY"],
+                    model_name=model_name,
+                    temperature=temperature,
+                )
+            
+            elif provider.lower() == "huggingface":
+                if os.environ.get("HF_TOKEN"):
+                    login(token=os.environ.get("HF_TOKEN"))
+                llm = HuggingFaceEndpoint(
+                    repo_id=model_name,
+                    task="text-generation",
+                    temperature=temperature,
+                    max_new_tokens=512,
+                    huggingfacehub_api_token=os.environ.get("HF_TOKEN")
+                )
+                return ChatHuggingFace(llm=llm)
+
+            elif provider.lower() == "ollama":
+                return ChatOllama(model=model_name, temperature=temperature)
+            
+            else:
+                raise ValueError(f"Unsupported LangChain provider: {provider}")
+        
+        # ----------------------------------------------------------------------
+        # STANDARD LOGIC (Agents Lib / OpenAI SDK)
+        # ----------------------------------------------------------------------
+        elif framework.lower() == "openai-sdk-agent" or framework.lower() == "openai-sdk" or framework.lower() == "openai":
+        
+            if provider.lower() == "azure":
+                token_provider = get_bearer_token_provider(
+                    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
+                )
+                client = AsyncAzureOpenAI(
+                    azure_endpoint=os.environ["AZURE_OPENAI_API_URI"],
+                    api_version=os.environ["AZURE_OPENAI_API_VERSION"],
+                    azure_ad_token_provider=token_provider,
+                )
+                return OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+
+            elif provider.lower() == "openai":
+                client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])
+                return OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+                
+            elif provider.lower() == "google":
+                GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+                client = AsyncOpenAI(
+                    base_url=GEMINI_BASE_URL,
+                    api_key=os.environ["GOOGLE_API_KEY"]
+                )
+                return OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+
+            elif provider.lower() == "groq":
+                GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+                client = AsyncOpenAI(
+                    base_url=GROQ_BASE_URL,
+                    api_key=os.environ["GROQ_API_KEY"]
+                )
+                return OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+
+            elif provider.lower() == "ollama":
+                client = AsyncOpenAI(
+                    base_url="http://localhost:11434/v1",
+                    api_key="ollama"
+                )
+                return OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+
+            elif provider.lower() == "huggingface":
+                 # Agents lib doesn't have native HF support in the same way
+                 raise ValueError("For Hugging Face, please use framework='langchain'")
+
+            else:
+                raise ValueError(f"Unsupported provider for openai-sdk-agent: {provider}")
+
+        else:
+             raise ValueError(f"Unsupported framework: {framework}")
+
+
+    @staticmethod
+    def num_tokens_from_messages(messages, model: str = "gpt-4o"):
+        """
+        Return the number of tokens used by a list of messages.
+        """
+        try:
+            encoding = tiktoken.encoding_for_model(model)
+        except KeyError:
+            encoding = tiktoken.get_encoding("cl100k_base")
+
+        tokens_per_message = 3
+        num_tokens = 0
+
+        for message in messages:
+            num_tokens += tokens_per_message
+            for key, value in message.items():
+                if key == "name":
+                    num_tokens += 1
+                
+                # Encode values if they are strings
+                if isinstance(value, str):
+                    num_tokens += len(encoding.encode(value))
+                elif isinstance(value, list) and key == "content":
+                    for part in value:
+                        if isinstance(part, dict) and part.get("type") == "text":
+                             num_tokens += len(encoding.encode(part.get("text", "")))
+                        elif isinstance(part, dict) and part.get("type") == "image_url":
+                             num_tokens += 85 
+
+        num_tokens += 3 
+        return num_tokens
+
+
+class EmbeddingFactory:
+    """
+    A static utility class to create and return Embedding Model instances.
+    """
+
+    @staticmethod
+    def get_embedding_model(provider: str = "openai",
+                            model_name: str = "text-embedding-3-small"
+                            ) -> Union[AzureOpenAIEmbeddings, OpenAIEmbeddings, OllamaEmbeddings, HuggingFaceEmbeddings]:
+        
+        if provider.lower() == "azure":
+            token_provider = get_bearer_token_provider(
+                DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
+            )
+            return AzureOpenAIEmbeddings(
+                azure_endpoint=os.environ["AZURE_OPENAI_API_URI"],
+                azure_deployment=os.environ.get("AZURE_OPENAI_EMBEDDING_DEPLOYMENT", model_name),
+                api_version=os.environ["AZURE_OPENAI_API_VERSION"],
+                azure_ad_token_provider=token_provider,
+            )
+        elif provider.lower() == "openai":
+            return OpenAIEmbeddings(
+                api_key=os.environ["OPENAI_API_KEY"],
+                model=model_name
+            )
+        elif provider.lower() == "ollama":
+            return OllamaEmbeddings(model=model_name)
+        elif provider.lower() == "huggingface":
+            if os.environ.get("HF_TOKEN"):
+                login(token=os.environ.get("HF_TOKEN"))
+            return HuggingFaceEmbeddings(model_name=model_name)
+        else:
+            raise ValueError(f"Unsupported embedding provider: {provider}")
+
+# =================================================================================================
+# GLOBAL HELPER FUNCTIONS (for agents)
+# =================================================================================================
+
+# model used for orchestrator or executor
+# def get_model(provider:str = "google", framework:str = "openai-sdk", model_name:str = "gemini-2.5-flash"):
+def get_model(provider:str = "openai", framework:str = "openai", model_name:str = "gpt-4-turbo"):
+# def get_model(provider:str = "groq", framework:str = "openai-sdk", model_name:str = "openai/gpt-oss-120b"):
+    model_info = None
+    if provider in list["gemini", "google"]:
+        model_info = {
+            "family": "gemini",
+            "vision": True,
+            "function_calling": True,
+            "json_output": True,
+            "structured_output": True,
+        }
+    
+    return ModelFactory.get_model(  framework=framework,
+                                    provider=provider,
+                                    model_name=model_name,
+                                    model_info=model_info,
+                                    temperature=0)
+    # else:
+    #     return ModelFactory.get_model(  framework="openai-sdk", 
+    #                                 provider="openai",
+    #                                 model_name="gpt-4o-mini",
+    #                                 temperature=0)
+
+# Use this model where agent executing tool and returning JSON
+def get_model_json(model_name: str = "gpt-4.1-mini", provider: str = "openai"):
+    return ModelFactory.get_model(  framework="openai-sdk",
+                                    provider=provider,
+                                    model_name=model_name, 
+                                    temperature=0)

common/utility/openai_model_factory.py

@@ -0,0 +1,179 @@
+import os
+import tiktoken
+from typing import Union
+from azure.identity import DefaultAzureCredential, get_bearer_token_provider
+from agents import OpenAIChatCompletionsModel
+from openai import AsyncOpenAI, AsyncAzureOpenAI
+from langchain_openai import AzureOpenAIEmbeddings, OpenAIEmbeddings
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_ollama import OllamaEmbeddings
+from huggingface_hub import login
+
+class OpenAIModelFactory:
+    """
+    Factory for creating OpenAI-SDK compatible model instances (using the 'agents' library).
+    Supports multiple providers via the OpenAI-compatible API format.
+    """
+
+    @staticmethod
+    def get_model(provider: str = "openai", # openai, azure, google, groq, ollama
+                  model_name: str = "gpt-4o", 
+                  temperature: float = 0
+                  ) -> OpenAIChatCompletionsModel:
+        """
+        Returns an OpenAIChatCompletionsModel instance.
+        """
+        
+        # ----------------------------------------------------------------------
+        # AZURE OPENAI
+        # ----------------------------------------------------------------------
+        if provider.lower() == "azure":
+            token_provider = get_bearer_token_provider(
+                DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
+            )
+            client = AsyncAzureOpenAI(
+                azure_endpoint=os.environ["AZURE_OPENAI_API_URI"],
+                api_version=os.environ["AZURE_OPENAI_API_VERSION"],
+                azure_ad_token_provider=token_provider,
+            )
+            return OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+
+        # ----------------------------------------------------------------------
+        # STANDARD OPENAI
+        # ----------------------------------------------------------------------
+        elif provider.lower() == "openai":
+            client = AsyncOpenAI(api_key=os.environ["OPENAI_API_KEY"])
+            return OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+            
+        # ----------------------------------------------------------------------
+        # GOOGLE (GEMINI) via OpenAI Compat
+        # ----------------------------------------------------------------------
+        elif provider.lower() == "google" or provider.lower() == "gemini":
+            GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+            client = AsyncOpenAI(
+                base_url=GEMINI_BASE_URL,
+                api_key=os.environ["GOOGLE_API_KEY"]
+            )
+            return OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+
+        # ----------------------------------------------------------------------
+        # GROQ via OpenAI Compat
+        # ----------------------------------------------------------------------
+        elif provider.lower() == "groq":
+            GROQ_BASE_URL = "https://api.groq.com/openai/v1"
+            client = AsyncOpenAI(
+                base_url=GROQ_BASE_URL,
+                api_key=os.environ["GROQ_API_KEY"]
+            )
+            return OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+
+        # ----------------------------------------------------------------------
+        # OLLAMA via OpenAI Compat
+        # ----------------------------------------------------------------------
+        elif provider.lower() == "ollama":
+            client = AsyncOpenAI(
+                base_url="http://localhost:11434/v1",
+                api_key="ollama"
+            )
+            return OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+
+        # ----------------------------------------------------------------------
+        # UNSUPPORTED
+        # ----------------------------------------------------------------------
+        else:
+            raise ValueError(f"Unsupported provider for OpenAIModelFactory: {provider}")
+
+
+    @staticmethod
+    def num_tokens_from_messages(messages, model: str = "gpt-4o"):
+        """
+        Return the number of tokens used by a list of messages.
+        """
+        try:
+            encoding = tiktoken.encoding_for_model(model)
+        except KeyError:
+            encoding = tiktoken.get_encoding("cl100k_base")
+
+        tokens_per_message = 3
+        num_tokens = 0
+
+        for message in messages:
+            num_tokens += tokens_per_message
+            for key, value in message.items():
+                if key == "name":
+                    num_tokens += 1
+                
+                # Encode values if they are strings
+                if isinstance(value, str):
+                    num_tokens += len(encoding.encode(value))
+                elif isinstance(value, list) and key == "content":
+                    for part in value:
+                        if isinstance(part, dict) and part.get("type") == "text":
+                                num_tokens += len(encoding.encode(part.get("text", "")))
+                        elif isinstance(part, dict) and part.get("type") == "image_url":
+                                num_tokens += 85 
+
+        num_tokens += 3 
+        return num_tokens
+
+
+class EmbeddingFactory:
+    """
+    A static utility class to create and return Embedding Model instances.
+    """
+
+    @staticmethod
+    def get_embedding_model(provider: str = "openai",
+                            model_name: str = "text-embedding-3-small"
+                            ) -> Union[AzureOpenAIEmbeddings, OpenAIEmbeddings, OllamaEmbeddings, HuggingFaceEmbeddings]:
+        
+        if provider.lower() == "azure":
+            token_provider = get_bearer_token_provider(
+                DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
+            )
+            return AzureOpenAIEmbeddings(
+                azure_endpoint=os.environ["AZURE_OPENAI_API_URI"],
+                azure_deployment=os.environ.get("AZURE_OPENAI_EMBEDDING_DEPLOYMENT", model_name),
+                api_version=os.environ["AZURE_OPENAI_API_VERSION"],
+                azure_ad_token_provider=token_provider,
+            )
+        elif provider.lower() == "openai":
+            return OpenAIEmbeddings(
+                api_key=os.environ["OPENAI_API_KEY"],
+                model=model_name
+            )
+        elif provider.lower() == "ollama":
+            return OllamaEmbeddings(model=model_name)
+        elif provider.lower() == "huggingface":
+            if os.environ.get("HF_TOKEN"):
+                login(token=os.environ.get("HF_TOKEN"))
+            return HuggingFaceEmbeddings(model_name=model_name)
+        else:
+            raise ValueError(f"Unsupported embedding provider: {provider}")
+
+
+# =================================================================================================
+# GLOBAL HELPER FUNCTIONS
+# =================================================================================================
+
+def get_model(provider:str = "openai", model_name:str = "gpt-4o"):
+    """
+    Global helper to get an OpenAI-SDK compatible model.
+    Defaults to OpenAI provider and gpt-4o.
+    """
+    return OpenAIModelFactory.get_model(
+        provider=provider,
+        model_name=model_name,
+        temperature=0
+    )
+
+def get_model_json(model_name: str = "gpt-4o-2024-08-06", provider: str = "openai"):
+    """
+    Global helper to get a JSON-capable model (Structured Outputs).
+    Defaults to gpt-4o-2024-08-06 on OpenAI.
+    """
+    return OpenAIModelFactory.get_model(
+        provider=provider,
+        model_name=model_name,
+        temperature=0
+    )

pyproject.toml

@@ -0,0 +1,184 @@
+[project]
+name = "agents"
+version = "0.1.0"
+description = "Agentic AI project"
+readme = "README.md"
+requires-python = "==3.12.*"
+
+dependencies = [
+    # =======================
+    # LLM PROVIDERS / SDKs
+    # =======================
+    "openai>=2.8.1",
+    "openai-agents>=0.5.1",
+    "anthropic>=0.49.0",
+    "langchain-openai>=1.0.3",
+    "langchain-anthropic>=1.1.0",
+    "langchain_huggingface>=1.1.0",
+    "langchain_ollama>=1.0.0",
+    "langchain_google_genai>=3.0.3",
+    "langchain_groq>=1.0.1",
+
+
+    # =======================
+    # LANGCHAIN / LANGGRAPH
+    # =======================
+    "langchain>=1.0.7",
+    "langchain-community>=0.4.1",
+    "langgraph>=1.0.3",
+    "langgraph-checkpoint-sqlite>=3.0.0",
+    "langsmith>=0.4.43",
+    "langchain-text-splitters>=1.0.0",
+    "langchain-chroma>=1.0.0",
+    "html2text>=2025.4.15",
+    "traceloop-sdk>=0.33.0",
+
+    # =======================
+    # MICROSOFT AGENT FRAMEWORK
+    # =======================
+    #"agent-framework==1.0.0b251204",
+    #"agent-framework-azure-ai==1.0.0b251204",
+    #"azure-ai-projects",
+    #"azure-ai-agents",
+    #"azure-ai-agents>=1.2.0b5",
+    #"agent-framework-azure-ai",
+
+    # =======================
+    # VECTOR DB / INDEXING
+    # =======================
+    "faiss-cpu>=1.13.0",
+    "chromadb==1.3.5",
+    "sentence-transformers>=5.1.2",
+    "pymupdf",
+    "pypdf>=6.3.0",
+    "pypdf2>=3.0.1",
+    "arxiv>=2.3.1",
+    "wikipedia>=1.4.0",
+
+    # =======================
+    # AUTOGEN
+    # =======================
+    "autogen-agentchat>=0.7.5",
+    "autogen-ext[grpc,mcp,ollama,openai]>=0.7.5",
+    "asyncio",
+
+    # =======================
+    # MCP
+    # =======================
+    "mcp-server-fetch>=2025.1.17",
+    "mcp[cli]>=1.21.2",
+    
+    # =======================
+    # NETWORKING / UTILITIES
+    # =======================
+    "psutil>=7.0.0",
+    "python-dotenv>=1.0.1",
+    "requests>=2.32.3",
+    "aiohttp>=3.8.5",
+    "httpx>=0.28.1",
+    "speedtest-cli>=2.1.3",
+    "logfire",
+    "google-search-results",
+    "smithery>=0.4.4",
+    "sendgrid",
+
+    # =======================
+    # WEB SCRAPING
+    # =======================
+    "playwright>=1.51.0",
+    "beautifulsoup4>=4.12.3",
+    "lxml>=5.3.1",
+
+    # =======================
+    # FINANCE / NLP
+    # =======================
+    "yfinance>=0.2.66",
+    "textblob>=0.17.1",
+    "polygon-api-client>=1.16.3",
+
+    # =======================
+    # VISUAL / UI / PDF
+    # =======================
+    "plotly>=6.5.0",
+    "streamlit>=1.51.0",
+    "reportlab>=4.4.5",
+    "fastapi",
+    "Pillow",
+    "python-docx",
+    "matplotlib",
+    "fpdf",
+    "extra-streamlit-components",
+    "nest_asyncio",
+
+    # =======================
+    # AUDIO / VIDEO
+    # =======================
+    "yt_dlp>=2025.11.12",
+    "openai-whisper>=1.0.0",
+
+    # =======================
+    # MACHINE LEARNING
+    # =======================
+    "scikit-learn>=1.7.2",
+    "huggingface_hub<=1.1.4",
+    "datasets>=4.4.1",
+
+    # =======================
+    # IPYNB SUPPORT
+    # =======================
+    "ipykernel>=7.1.0",
+
+    # =======================
+    # TOOLS
+    # =======================
+    "ddgs>=9.9.2",
+    "duckduckgo_search",
+    "azure-identity>=1.25.1",
+
+    # =======================
+    # OBSERVABILITY
+    # =======================
+    "openinference-instrumentation-autogen>=0.1.0",
+    "openinference-instrumentation-openai>=0.1.15",
+    "opentelemetry-sdk>=1.20.0",
+    "opentelemetry-exporter-otlp>=1.20.0",
+    "opentelemetry-api>=1.20.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.3",
+    "ipykernel>=7.1.0",
+    "pytest-asyncio",
+]
+
+# ============================================================
+# BUILD SYSTEM
+# ============================================================
+# Defines how to build the project.
+# We use setuptools as the build backend, ensuring consistent packaging.
+[build-system]
+requires = ["setuptools>=80.9.0"]
+build-backend = "setuptools.build_meta"
+
+# ============================================================
+# PACKAGING & DISCOVERY
+# ============================================================
+# Tells setuptools where to find the source code.
+# This makes 'common' and 'src' importable when installed (pip install -e .).
+[tool.setuptools.packages.find]
+where = ["."]  # Look in the project root
+include = ["common*", "src*"]  # Treat 'common' and 'src' folders as packages
+
+
+# ============================================================
+# PYTEST SETTINGS
+# ============================================================
+# Configures the test runner to automatically find code.
+[tool.pytest.ini_options]
+# Adds 'src' and 'common' to the python path during tests.
+# This allows tests to import modules (e.g., 'import travel_agent')
+# just like the apps do locally, preventing ModuleNotFoundError.
+pythonpath = ["src", "common"]
+testpaths = ["tests"]  # Only look for tests in the 'tests' directory
+addopts = "-q"  # Run in quiet mode (less verbose output)

run.py

@@ -0,0 +1,246 @@
+#!/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-analyst
+    python run.py --list
+"""
+
+import sys
+import os
+import subprocess
+import argparse
+from pathlib import Path
+from typing import Dict, Optional
+from agents import Runner, SQLiteSession
+# from agents import set_trace_processors
+# from langsmith.wrappers import OpenAIAgentsTracingProcessor
+
+# Load environment variables explicitly
+from dotenv import load_dotenv
+load_dotenv(override=True)
+
+# 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-analyst": {
+        "path": "src/stock-analyst",
+        "entry": "app.py",
+        "description": "Stock Analyst - 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": "main.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"
+    },
+    "literature-review": {
+        "path": "src/literature-review",
+        "entry": "app.py",
+        "description": "Literature Review Assistant - Multi-agent literature review tool"
+    },
+    "market-analyst": {
+        "path": "src/market-analyst",
+        "entry": "app.py",
+        "description": "Market Analyst - Multi-agent market analysis tool"
+    },
+    "image": {
+        "path": "src/image-generator",
+        "entry": "app.py",
+        "description": "Image Generator - Multi-agent image generation tool"
+    },
+    "interview-assistant": {
+        "path": "src/interview-assistant",
+        "entry": "app.py",
+        "description": "Interview Assistant - Multi-agent interview tool"
+    }
+}
+
+
+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")
+    
+    # Prepare environment with project root in PYTHONPATH to fix imports
+    env = os.environ.copy()
+    env["PYTHONPATH"] = str(project_root) + os.pathsep + env.get("PYTHONPATH", "")
+    print(f"\n\nPYTHONPATH: {env['PYTHONPATH']}")
+
+    try:
+        # Change to app directory and run
+        os.chdir(app_dir)
+        subprocess.run(cmd, env=env)
+    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__":
+    # set_trace_processors([OpenAIAgentsTracingProcessor()])
+    main()

src/interview-assistant/Dockerfile

@@ -0,0 +1,36 @@
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    DEBIAN_FRONTEND=noninteractive \
+    PYTHONPATH=/app/src/interview-assistant:$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 application code
+COPY common/ ./common/
+COPY src/interview-assistant/ ./src/interview-assistant/
+
+# Install dependencies using uv, then export and install with pip to system
+# We use --no-dev to exclude dev dependencies if any
+RUN uv sync --frozen --no-dev && \
+    uv pip install -e . --system
+
+# Copy entry point
+COPY run.py .
+
+EXPOSE 7860
+
+CMD ["python", "run.py", "interview-assistant", "--port", "7860"]

src/interview-assistant/README.md

@@ -0,0 +1,68 @@
+---
+title: Interviewer Assistant
+emoji: 👔
+colorFrom: green
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+short_description: Agentic AI for Resume Analysis & Interview Prep
+---
+
+# 👔 Interviewer Assistant
+
+A **Multi-Agent System** designed to assist HR and technical interviewers by automatically analyzing job descriptions and resumes to generate tailored interview questions and fitness scores.
+
+## 🚀 Features
+
+- **🧠 Multi-Agent Swarm**:
+  - **Job Analyst**: Extracts key requirements from JDs.
+  - **Candidate Profiler**: Analyzes resumes for strengths and gaps.
+  - **Evaluator**: Scores candidates on Technical, Behavioral, and Leadership metrics.
+  - **Interview Designer**: Generates bespoke interview questions.
+- **📄 Input Flexibility**: Accepts raw text for JD and Resume/LinkedIn profile.
+- **📊 Structured Evaluation**: Provides a clear score and justification.
+
+## 🛠️ Architecture
+
+```
+src/interview-assistant/
+├── app.py                  # Streamlit UI (Orchestrator)
+├── teams/                  # Team Definitions
+│   └── team.py             # GroupChat Configuration
+├── aagents/                # Agent Definitions
+│   ├── job_analyst.py      
+│   ├── candidate_profiler.py
+│   ├── evaluator.py
+│   ├── interview_designer.py 
+│   └── admin.py            
+└── Dockerfile              # Deployment Configuration
+```
+
+## 📦 Startup
+
+### Local Run
+
+1. **Install Dependencies**:
+   ```bash
+   pip install -r src/interviewer-assistant/requirements.txt
+   ```
+
+2. **Run Application**:
+   ```bash
+   streamlit run src/interviewer-assistant/app.py
+   ```
+   The app will open at `http://localhost:8501`.
+
+## 🐳 Docker / Deployment
+
+The project is packaged for **Hugging Face Spaces** (Docker SDK).
+
+```bash
+# Build
+docker build -t interviewer-assistant -f src/interviewer-assistant/Dockerfile .
+
+# Run
+docker run -p 7860:7860 interviewer-assistant
+```

src/interview-assistant/aagents/candidate_profiler.py

@@ -0,0 +1,54 @@
+from autogen_agentchat.agents import AssistantAgent
+from autogen_core.tools import FunctionTool
+
+# Import tools
+import sys
+import os
+
+# Ensure we can import from parent directory if needed
+current_dir = os.path.dirname(os.path.abspath(__file__))
+parent_dir = os.path.abspath(os.path.join(current_dir, ".."))
+if parent_dir not in sys.path:
+    sys.path.append(parent_dir)
+
+from tools.resume_tools import read_local_file, scrape_web_page
+
+def get_candidate_profiler(model_client):
+    
+    # Wrap tools
+    read_tool = FunctionTool(read_local_file, description="Reads a local file (PDF, DOCX, or TXT) and returns its text content.")
+    scrape_tool = FunctionTool(scrape_web_page, description="Fetches the content of a web page (e.g., LinkedIn public profile) and returns the text.")
+
+    return AssistantAgent(
+        name="Candidate_Profiler",
+        model_client=model_client,
+        tools=[read_tool, scrape_tool],
+        system_message="""
+        You are an expert Candidate Profiler.
+        
+        Task:
+        1. Read the candidate's resume (using `read_local_file` if path provided) and/or LinkedIn profile (using `scrape_web_page` if URL provided).
+        2. Summarize the candidate's professional profile, key skills, years of experience, and notable achievements.
+        3. Do NOT evaluate the candidate against any job description yet. Just provide a factual, comprehensive summary. Also extract the Candidate's Name if available.
+        
+        IMPORTANT: 
+        - If you have the Resume content, that is sufficient. exact LinkedIn data is secondary. 
+        - Do not retry scraping if it fails or returns empty/short content. Proceed with the Resume only.
+        - Output the results in the JSON format below.
+        - After outputting the JSON, do not perform further actions.
+        
+        Output:
+        Return a JSON object:
+        ```json
+        {
+          "candidate_name": "...",
+          "candidate_summary": "...",
+          "key_skills": ["..."],
+          "years_of_experience": "...",
+          "recent_roles": ["..."]
+        }
+        ```
+        
+        End your message with: HANDOFF_TO_JOB_ANALYST
+        """,
+    )

src/interview-assistant/aagents/evaluator.py

@@ -0,0 +1,36 @@
+from autogen_agentchat.agents import AssistantAgent
+
+def get_evaluator(model_client):
+    return AssistantAgent(
+        name="Evaluator",
+        model_client=model_client,
+        system_message="""
+        You are the Hiring Evaluator.
+        
+        Inputs:
+        1. Context includes "Candidate Summary" (from Candidate_Profiler).
+        2. Context includes "Approved JD Analysis" (from Job_Analyst/Reviewer).
+        
+        Task:
+        1. Compare the Candidate's profile against the approved JD requirements across FOUR dimensions:
+           - Technical Proficiency
+           - Behavioral Fit
+           - Situational Judgment & Problem Solving
+           - Leadership Potential (Ownership/Influence)
+        2. Score the overall fitness (1-10) weighted by the priorities defined in the JD Analysis.
+        3. Identify Strengths and Gaps.
+        4. List specific areas to probe in the interview.
+        
+        Output:
+        Return a JSON object:
+        ```json
+        {
+          "fitness_score": 8,
+          "justification": "...",
+          "strengths": ["..."],
+          "gaps": ["..."],
+          "interview_focus_areas": ["..."]
+        }
+        ```
+        """,
+    )

src/interview-assistant/aagents/interview_designer.py

@@ -0,0 +1,44 @@
+from autogen_agentchat.agents import AssistantAgent
+
+def get_interview_designer(model_client):
+    return AssistantAgent(
+        name="Interview_Designer",
+        model_client=model_client,
+        system_message="""
+        You are an Expert Interview Designer.
+        
+        Input:
+        - Evaluator's output (Focus Areas, Gaps, Strengths).
+        - Approved JD Analysis (with Weights).
+        
+        Task:
+        1. Design a comprehensive structured interview based on the JD weights and Evaluator's focus areas.
+        2. **MANDATORY QUANTITY**: You MUST generate a minimum of **40 unique questions**. This is a hard requirement.
+        3. **SUGGESTED BREAKDOWN**: ~16 Technical, ~8 Behavioral, ~8 Situational, ~8 Leadership.
+        4. **DISTRIBUTION**: Allocate questions based on skill weights.
+        5. **STRICT ELABORATION**: Each question text ("q") and "sample_answer" MUST be substantive (spanning **at least 3-4 lines/sentences**) to provide deep context. NO ONE-LINERS.
+        6. **SITUATIONAL**: Ensure at least 8 questions are complex "Situational" scenarios.
+        7. **Sample Answers**: For EACH question, provide a detailed "Sample Answer" (3-4 sentences).
+        8. **Completeness**: Ensure the JSON is complete. Output the **FULL LIST** every time (do not strictly append, regenerate the full set if needed).
+        
+        Output:
+        Return a JSON object:
+        ```json
+        {
+           "structured_interview": [
+              {
+                 "skill": "Python (Weight: 40%)",
+                 "questions": [
+                    {
+                        "q": "Explain decorators...", 
+                        "complexity": "High", 
+                        "type": "Conceptual",
+                        "sample_answer": "Candidate should mention: Higher-order functions, @syntax, typical use cases like logging or auth."
+                    }
+                 ]
+              }
+           ]
+        }
+        ```
+        """,
+    )

src/interview-assistant/aagents/job_analyst.py

@@ -0,0 +1,34 @@
+from autogen_agentchat.agents import AssistantAgent
+
+def get_job_analyst(model_client):
+    return AssistantAgent(
+        name="Job_Analyst",
+        model_client=model_client,
+        system_message="""
+        You are an Expert Job Analyst.
+        
+        Task:
+        1. Analyze the provided Job Description (JD).
+        2. Identify key skills in four categories: 
+           - **Technical**: Hard skills, tools, languages.
+           - **Behavioral**: Soft skills, culture fit.
+           - **Situational Judgment**: Problem-solving, conflict resolution, strategic thinking scenarios.
+           - **Leadership**: Coaching, ownership, influence, team management (even for individual contributors).
+        3. Assign a PERCENTAGE WEIGHT to each skill based on its importance in the JD.
+        4. CONSTRAINT: The sum of weights across ALL skills in ALL categories MUST equal exactly 100.
+        
+        Output:
+        Return a JSON object:
+        ```json
+        {
+            "role_summary": "...",
+            "analysis": {
+                "technical": [{"skill": "Python", "weight": 30}, {"skill": "AWS", "weight": 20}],
+                "behavioral": [{"skill": "Teamwork", "weight": 10}],
+                "situational_judgment": [{"skill": "Production Outage Handling", "weight": 20}],
+                "leadership": [{"skill": "Mentoring", "weight": 20}]
+            }
+        }
+        ```
+        """,
+    )

src/interview-assistant/aagents/job_analyst_reviewer.py

@@ -0,0 +1,17 @@
+from autogen_agentchat.agents import AssistantAgent
+
+def get_job_analyst_reviewer(model_client):
+    return AssistantAgent(
+        name="Job_Analyst_Reviewer",
+        model_client=model_client,
+        system_message="""
+        You are a Senior HR Reviewer.
+        
+        Task:
+        1. Review the output from the "Job_Analyst".
+        2. Verify if the identified skills accurately reflect the JD.
+        3. CHECK MATH: Verify that the sum of ALL weights across all categories equals exactly 100.
+        4. If the math is wrong or skills are missing, reject and ask for corrections.
+        5. If acceptable, output "APPROVED".
+        """,
+    )

src/interview-assistant/aagents/team_lead.py

@@ -0,0 +1,21 @@
+from autogen_agentchat.agents import AssistantAgent
+
+def get_team_lead(model_client):
+    return AssistantAgent(
+        name="Team_Lead",
+        model_client=model_client,
+        system_message="""
+        You are the Quality Assurance Team Lead.
+        
+        Task:
+        1. Review the output of the Interview Designer.
+        2. **Quantity Check**: Count the total questions. If the count is **less than 35**, return "REJECT: Generated fewer than 35 questions. Need at least 35 unique questions. Please add more."
+        3. **Quality Check**: Read the "q" and "sample_answer" fields.
+           - If they are short (1-2 sentences), return "REJECT: Questions/Answers are too brief. Elaboration to 3-4 detailed sentences is REQUIRED for every item. Please rewrite."
+        4. **Validation**: Ensure the JSON is valid and complete.
+        
+        Action:
+        - If ALL checks pass: Reply with "TERMINATE".
+        - If ANY check fails: Reply with the specific feedback to the Interview_Designer.
+        """,
+    )

src/interview-assistant/app.py

@@ -0,0 +1,219 @@
+import streamlit as st
+import os
+import sys
+import tempfile
+import asyncio
+import traceback
+import extra_streamlit_components as stx
+from dotenv import load_dotenv
+
+# Ensure we can import from local modules
+current_dir = os.path.dirname(os.path.abspath(__file__))
+if current_dir not in sys.path:
+    sys.path.append(current_dir)
+
+from teams.team import get_interview_team
+from ui.styles import apply_custom_styles
+from ui.hero import render_hero
+from ui.sidebar import render_sidebar
+from ui.report import generate_markdown_report, create_pdf, render_persistent_view
+from common.utility.autogen_model_factory import AutoGenModelFactory
+
+# Load env variables
+load_dotenv()
+
+st.set_page_config(page_title="Interviewer Assistant", page_icon="👔", layout="wide")
+
+# Cookie Manager (Must be initialized at top level)
+def get_manager():
+    return stx.CookieManager()
+
+cookie_manager = get_manager()
+
+# 1. Apply Styles
+apply_custom_styles()
+
+# 2. Render Sidebar
+sidebar_data = render_sidebar(cookie_manager)
+mode = sidebar_data["mode"]
+job_description = sidebar_data["job_description"]
+uploaded_resume = sidebar_data["uploaded_resume"]
+linkedin_url = sidebar_data["linkedin_url"]
+
+# 3. Render Hero
+render_hero()
+
+# ------------------------------------------------------------------------------
+# LOGIC & ANALYSIS HELPERS
+# ------------------------------------------------------------------------------
+
+async def run_analysis_stream(model_client, task_msg):
+    team = get_interview_team(model_client)
+    # Return the stream generator
+    stream = team.run_stream(task=task_msg)
+    return stream
+
+# ------------------------------------------------------------------------------
+# MAIN CONTENT LOGIC
+# ------------------------------------------------------------------------------
+
+if mode == "Candidate":
+    st.markdown("## 🎓 Candidate Prep Portal")
+    st.info("This feature is under development. It will allow candidates to take mock interviews based on the generated guide.")
+    st.image("https://cdn-icons-png.flaticon.com/512/3220/3220565.png", width=150)
+    st.stop()
+
+if st.session_state.analyzing:
+    # Validation
+    if not os.getenv("OPENAI_API_KEY"):
+        st.error("Missing OpenAI API Key. Please check your .env file or environment variables.")
+        st.session_state.analyzing = False
+        st.stop()
+    if not job_description:
+        st.error("Missing Job Description.")
+        st.session_state.analyzing = False
+        st.stop()
+    if not uploaded_resume:
+        st.error("Missing Resume File.")
+        st.session_state.analyzing = False
+        st.stop()
+
+    try:
+        # Process Input
+        resume_path = ""
+        with tempfile.NamedTemporaryFile(delete=False, suffix=f".{uploaded_resume.name.split('.')[-1]}") as tmp_file:
+             tmp_file.write(uploaded_resume.getvalue())
+             resume_path = tmp_file.name
+
+        resume_content_msg = f"Candidate Resume File Path: {resume_path} (Please use `read_local_file` to read this)."
+        if linkedin_url:
+            resume_content_msg += f"\nAlso check LinkedIn: {linkedin_url} (use `scrape_web_page`)."
+
+        # Execution
+        prog_bar = st.progress(0)
+        status_text = st.empty()
+        
+        # Create Model Client using Factory
+        model_client = AutoGenModelFactory.get_model(
+            provider="openai", model_name="gpt-4-turbo", model_info={"vision": False, "function_calling": True, "json_output": False}
+        )
+        
+        task_msg = f"""
+        Here is the Job Description:
+        {job_description}
+
+        {resume_content_msg}
+
+        The team must follow the strict workflow: 
+        Profiler -> Job Analyst -> Reviewer -> Evaluator -> Designer.
+        """
+
+        status_text.text("Initializing Agents...")
+        prog_bar.progress(10)
+        
+        # Create a placeholder for debug output to avoid context issues inside async
+        debug_placeholder = st.empty()
+        
+        # Define debug print helper
+        def debug_print(msg):
+            print(f"DEBUG: {msg}")
+
+        debug_print("Analysis Started. Loop initializing...")
+
+        async def execute_analysis(placeholder):
+            try:
+                debug_print("Entering execute_analysis async function")
+                with st.spinner("Analyzing candidate and designing interview..."):
+                     # Get the stream
+                     debug_print(f"Creating team and stream with task length {len(task_msg)}")
+                     stream = await run_analysis_stream(model_client, task_msg)
+                     
+                     messages = []
+                     msg_count = 0
+                     debug_print("Stream created. Iterating...") 
+                     
+                     # Stream messages
+                     async for message in stream:
+                         msg_count += 1
+                         messages.append(message)
+                         
+                         source = getattr(message, 'source', 'Unknown')
+                         content = getattr(message, 'content', '')
+                         debug_print(f"Stream Msg {msg_count}: {source}") 
+                         
+                         if isinstance(content, list):
+                             content = "[Multimodal Content]"
+                         elif not content:
+                             content = "[No Content]"
+                             
+                         # Evidence: Show Data (Source Content) in UI & Console
+                         if isinstance(content, str) and len(content) > 500:
+                             print(f"--- EVIDENCE ({source}) ---\n{content[:5000]}\n---------------------------")
+                             with st.expander(f"📄 Data Source Evidence ({source})", expanded=False):
+                                 st.text(content)
+                         
+                         # Update Debug UI safely
+                         placeholder.text(f"[{msg_count}] {source}: {str(content)[:150]}...")
+                         
+                         # Progress bar update
+                         if source == "Candidate_Profiler": prog_bar.progress(20)
+                         elif source == "Job_Analyst": prog_bar.progress(40)
+                         elif source == "Job_Analyst_Reviewer": prog_bar.progress(60)
+                         elif source == "Evaluator": prog_bar.progress(80)
+                         elif source == "Interview_Designer": prog_bar.progress(95)
+                     
+                     if msg_count == 0:
+                         st.error("No messages received. Check logs/console.")
+                         debug_print("Stream finished with 0 messages.")
+                     else:
+                         debug_print(f"Stream finished with {msg_count} messages.")
+
+                prog_bar.progress(100)
+                status_text.text("Analysis Complete.")
+                
+                # Generation
+                final_markdown = generate_markdown_report(messages)
+                
+                if not final_markdown.strip():
+                     final_markdown = "## Report Generation Failed\nNo structured output was found from the agent team."
+                
+                # Save to State (Persistence)
+                st.session_state.generated_report = final_markdown
+                st.session_state.generated_pdf = create_pdf(final_markdown)
+                
+            except Exception as e:
+                st.error(f"An error occurred during analysis: {e}")
+                import traceback
+                st.text(traceback.format_exc())
+                debug_print(f"Async Job Failed: {e}")
+
+        # Run the async execution
+        try:
+            import asyncio
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            try:
+                loop.run_until_complete(execute_analysis(debug_placeholder))
+            finally:
+                # Cleanup pending tasks
+                pending = asyncio.all_tasks(loop)
+                for task in pending:
+                    task.cancel()
+                if pending:
+                    loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
+                loop.close()
+        except Exception as e:
+            st.error(f"System Error: {e}")
+            import traceback
+            st.text(traceback.format_exc())
+            
+    finally:
+        # Reset analysis state at the end so user can run again
+        st.session_state.analyzing = False
+        st.rerun() 
+        
+else:
+    st.info("👈 Please fill in the details in the sidebar to get started.")
+
+# 4. Render Persistent View (Report)
+render_persistent_view()

src/interview-assistant/debug_profiler.py

@@ -0,0 +1,67 @@
+import asyncio
+import os
+import sys
+from dotenv import load_dotenv
+
+# Path setup
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+from common.utility.autogen_model_factory import AutoGenModelFactory
+from aagents.candidate_profiler import get_candidate_profiler
+
+# Load env (assuming .env in project root, but we can rely on env vars being set in shell)
+load_dotenv()
+
+async def main():
+    print("DEBUG: Starting standalone profiler test.")
+    
+    # 1. Setup Dummy Resume
+    resume_path = os.path.join(os.getcwd(), "dummy_resume.txt")
+    with open(resume_path, "w") as f:
+        f.write("Jane Doe. Experienced Software Engineer. Python, Azure, AI. 10 years experience.")
+    
+    print(f"DEBUG: Created dummy resume at {resume_path}")
+
+    # 2. Setup Agent
+    try:
+        model_client = AutoGenModelFactory.get_model(
+            provider="openai", 
+            model_name="gpt-4-turbo", 
+            model_info={"vision": False, "function_calling": True, "json_output": False}
+        )
+        profiler = get_candidate_profiler(model_client)
+        print("DEBUG: Profiler agent created.")
+    except Exception as e:
+        print(f"ERROR: Failed to create agent: {e}")
+        return
+
+    # 3. Run Agent
+    task_msg = f"Candidate Resume File Path: {resume_path} (Please use `read_local_file` to read this)."
+    
+    print(f"DEBUG: Sending task: {task_msg}")
+    
+    try:
+        # Run directly against agent usually requires a team context for proper tool loop handling in 0.4
+        # But let's try calling on_messages or similar if supported, 
+        # OR just wrap in a minimal RoundRobin team like in the app.
+        from autogen_agentchat.teams import RoundRobinGroupChat
+        from autogen_agentchat.conditions import MaxMessageTermination
+        
+        team = RoundRobinGroupChat(
+            participants=[profiler],
+            termination_condition=MaxMessageTermination(5)
+        )
+        
+        print("DEBUG: Running team stream...")
+        async for message in team.run_stream(task=task_msg):
+            source = getattr(message, 'source', 'Unknown')
+            content = getattr(message, 'content', '')
+            print(f"STREAM: {source}: {str(content)[:100]}")
+            
+    except Exception as e:
+        print(f"ERROR during execution: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    asyncio.run(main())

src/interview-assistant/teams/team.py

@@ -0,0 +1,75 @@
+import sys
+import os
+import json
+import re
+from typing import Dict, Any
+
+from autogen_agentchat.teams import RoundRobinGroupChat, SelectorGroupChat
+from autogen_agentchat.conditions import MaxMessageTermination, TextMentionTermination
+
+# Ensure we can import from parent directory if needed
+current_dir = os.path.dirname(os.path.abspath(__file__))
+parent_dir = os.path.abspath(os.path.join(current_dir, ".."))
+if parent_dir not in sys.path:
+    sys.path.append(parent_dir)
+
+# Import agents
+try:
+    from ..aagents.job_analyst import get_job_analyst
+    from ..aagents.job_analyst_reviewer import get_job_analyst_reviewer
+    from ..aagents.candidate_profiler import get_candidate_profiler
+    from ..aagents.evaluator import get_evaluator
+    from ..aagents.interview_designer import get_interview_designer
+    from ..aagents.team_lead import get_team_lead
+
+except ImportError:
+    from aagents.job_analyst import get_job_analyst
+    from aagents.job_analyst_reviewer import get_job_analyst_reviewer
+    from aagents.candidate_profiler import get_candidate_profiler
+    from aagents.evaluator import get_evaluator
+    from aagents.interview_designer import get_interview_designer
+    from aagents.team_lead import get_team_lead
+
+
+def get_interview_team(model_client):
+    """
+    Creates the Interview Team using SelectorGroupChat to enforce order.
+    The order is: Profiler -> Job Analyst -> Reviewer -> Evaluator -> Designer -> Team Lead
+    """
+    print(f"[DEBUG] Creating Interview Team")
+    
+    # 1. Initialize Agents
+    profiler = get_candidate_profiler(model_client)
+    job_analyst = get_job_analyst(model_client)
+    reviewer = get_job_analyst_reviewer(model_client)
+    evaluator = get_evaluator(model_client)
+    designer = get_interview_designer(model_client)
+    lead = get_team_lead(model_client)
+    
+    
+    # 2. Define Selector/Transition Logic (Deprecated in RoundRobin but kept for ref)
+    selector_prompt = """
+    ...
+    """
+    
+    # Use RoundRobin as requested ("Keep it simple like market-analyst")
+    # This avoids Selector logic loops. 
+    # The agents must be robust enough to handle the sequential flow.
+    print(f"[DEBUG] Using RoundRobinGroupChat")
+    team = RoundRobinGroupChat(
+        participants=[profiler, job_analyst, reviewer, evaluator, designer, lead],
+        termination_condition=TextMentionTermination("TERMINATE") | MaxMessageTermination(15)
+    )
+    print(f"[DEBUG] Team created: {team}")
+    
+    return team
+
+def extract_json(text: str) -> Dict[str, Any]:
+    """Helper to extract JSON from markdown code blocks or raw text."""
+    try:
+        match = re.search(r"```json\s*(.*?)\s*```", text, re.DOTALL)
+        if match:
+            return json.loads(match.group(1))
+        return json.loads(text)
+    except:
+        return {}