tract pdfs with git lfs

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.env

.python-version

@@ -0,0 +1 @@
+3.11.8

README.md

@@ -6,6 +6,7 @@ colorTo: pink
 sdk: gradio
 sdk_version: 5.44.1
 app_file: app.py
+python_version: 3.11.8
 pinned: false
 license: mit
 ---

agents/factory.py

@@ -0,0 +1,40 @@
+"""Factory for creating agent implementations.
+
+This module contains factory methods for creating the appropriate chat implementation
+based on the selected agent mode.
+"""
+
+from enum import Enum
+from nexus_ai.core.chat_interface import ChatInterface
+from nexus_ai.agents.research_agent import DeepResearchChat
+from nexus_ai.agents.rag_agent import AgenticRAGChat
+from nexus_ai.agents.tool_agent import ToolUsingAgentChat
+from nexus_ai.agents.unified_chat import UnifiedChat
+
+
+class AgentMode(Enum):
+    """Enum for different agent implementation modes."""
+    TOOL_AGENT = "tool"
+    RAG_AGENT = "rag"
+    RESEARCH_AGENT = "research"
+    UNIFIED = "unified"  # Default unified mode
+
+
+def create_chat_implementation(mode: AgentMode = AgentMode.UNIFIED) -> ChatInterface:
+    """Create a chat implementation for the specified agent mode.
+    
+    Args:
+        mode: Which agent implementation to use (defaults to UNIFIED)
+        
+    Returns:
+        ChatInterface: The initialized chat implementation
+    """
+    if mode == AgentMode.TOOL_AGENT:
+        return ToolUsingAgentChat()
+    elif mode == AgentMode.RAG_AGENT:
+        return AgenticRAGChat()
+    elif mode == AgentMode.RESEARCH_AGENT:
+        return DeepResearchChat()
+    else:
+        # Default to unified mode
+        return UnifiedChat()

agents/prompts.py

@@ -0,0 +1,203 @@
+"""Prompts for various agents in the Nexus AI system.
+
+This module contains all the prompt templates used by different agents
+for their specific tasks.
+"""
+
+from langchain_core.prompts import PromptTemplate
+
+# ============================================================================
+# RAG Agent Prompts
+# ============================================================================
+
+DOCUMENT_EVALUATOR_PROMPT = PromptTemplate.from_template(
+    """
+    You are a grader assessing relevance and completeness of retrieved documents
+    to answer a user question. 
+    
+    Here is the user question: {question} 
+    
+    Here are the retrieved documents: 
+    {retrieved_docs} 
+
+    Give a binary score 'yes' or 'no' score to indicate whether the document is relevant to the question.
+    If the document contains keyword(s) or semantic meaning related to the user question, and is useful
+    to answer the user question, grade it as relevant.
+    
+    If the answer is NO, then provide feedback on what information is missing from the document and
+    what additional information is needed.
+    """
+)
+    
+DOCUMENT_SYNTHESIZER_PROMPT = PromptTemplate.from_template(
+    """
+    You are a document synthesizer. Create a comprehensive answer using 
+    the retrieved documents. Focus on accuracy and clarity.
+    
+    Here is the user question: {question} 
+    
+    Here are the retrieved documents: 
+    {retrieved_docs} 
+    
+    Provide a detailed and accurate answer based solely on the information in the documents.
+    If the documents don't contain enough information to fully answer the question,
+    clearly state what information is available and what is missing.
+    """
+)
+
+QUERY_REWRITER_PROMPT = PromptTemplate.from_template(
+    """
+    You are a query rewriter. Rewrite the user question based on the feedback.
+    The new query should maintain the same semantic meaning as the original
+    query but augment it with more specific information to improve retrieval.
+
+    The new query should not be very long - it should be a single sentence since
+    it'll be used to query the vector database or a web search.
+    
+    Here is the user question: {question} 
+    Here is the previously retrieved documents: {retrieved_docs}
+    Here is the feedback: {feedback}
+    
+    New query:
+    """
+)
+
+# ============================================================================
+# Deep Research Agent Prompts
+# ============================================================================
+
+RESEARCH_MANAGER_PROMPT = PromptTemplate.from_template(
+    """
+    You are a Research Manager responsible for planning comprehensive research reports. 
+            
+    Your task is to:
+    1. Take a broad research topic
+    2. Break it down into 3-5 specific research questions/sections
+    3. Create a research plan with a clear structure
+    
+    For each research question, provide:
+    - A clear title
+    - A description of what should be researched
+    
+    DO NOT conduct the actual research. You are only planning the structure.
+    
+    The report structure should follow:
+    - Executive Summary
+    - Key Findings
+    - Detailed Analysis (sections for each research question)
+    - Limitations and Further Research
+    
+    Return your answer as a structured research plan.
+
+    Research Topic: {topic}
+    """
+)
+
+RESEARCH_SPECIALIST_PROMPT = PromptTemplate.from_template(
+    """
+    You are a Specialized Research Agent responsible for thoroughly researching a specific topic section.
+
+    Process:
+    1. Analyze the research question and description
+    2. Generate effective search queries to gather information
+    3. Use the web_search tool to find relevant information
+    4. Synthesize findings into a comprehensive section
+    5. Include proper citations to your sources
+
+    Your response should be:
+    - Thorough (at least 500 words)
+    - Well-structured with subsections
+    - Based on factual information (not made up)
+    - Include proper citations to sources
+
+    Always critically evaluate information and ensure you cover the topic comprehensively.
+    
+    Research Question: {question}
+    Description: {description}
+    """
+)
+
+REPORT_FINALIZER_PROMPT = PromptTemplate.from_template(
+    """
+    You are a Report Finalizer responsible for completing a research report.
+    
+    Based on the detailed analysis sections that have been researched, you need to generate:
+    
+    1. Executive Summary (Brief overview of the entire report, ~150 words)
+    2. Key Findings (3-5 most important insights, in bullet points)
+    3. Limitations and Further Research (Identify gaps and suggest future areas of study)
+    
+    Your content should be:
+    - Concise and clear
+    - Properly formatted
+    - Based strictly on the researched content
+    
+    Do not introduce new information not found in the research.
+
+    Research Topic: {topic}
+    
+    Detailed Analysis Sections:
+    {detailed_analysis}
+    
+    Generate the Executive Summary, Key Findings, and Limitations sections to complete the report.
+    """
+)
+
+# ============================================================================
+# Tool Agent Prompts (if needed in the future)
+# ============================================================================
+
+TOOL_SELECTION_PROMPT = PromptTemplate.from_template(
+    """
+    You are an intelligent assistant with access to various tools.
+    Based on the user's query, select and use the appropriate tool(s) to provide an accurate response.
+    
+    Available tools:
+    - Calculator: For mathematical computations
+    - DateTime: For date and time related queries
+    - Weather: For weather information
+    
+    User Query: {query}
+    
+    Think step by step about which tool(s) to use and how to best answer the query.
+    """
+)
+
+# ============================================================================
+# Query Classification Prompt (used in unified_chat.py)
+# ============================================================================
+
+QUERY_CLASSIFIER_PROMPT = PromptTemplate.from_template(
+    """
+    You are a query classifier that determines which system should handle a user's query.
+    
+    Analyze the user's query and classify it into one of these categories:
+    
+    1. SIMPLE_TOOL - Use for:
+       - Mathematical calculations or expressions
+       - Date/time queries
+       - Weather queries
+       - Any query that can be answered with a simple tool call
+    
+    2. AGENTIC_RAG - Use for:
+       - Questions about specific documents
+       - Queries requiring document retrieval
+       - Questions about content from your knowledge base
+    
+    3. DEEP_RESEARCH - Use for:
+       - Requests for comprehensive research or analysis
+       - Topics requiring multiple sources and detailed investigation
+       - Keywords: "deep dive", "comprehensive analysis", "research", "detailed report"
+    
+    4. GENERAL - Use for:
+       - General conversation and questions
+       - Simple factual queries
+       - Anything that doesn't fit the above categories
+    
+    Return ONLY one of these exact words: SIMPLE_TOOL, AGENTIC_RAG, DEEP_RESEARCH, or GENERAL
+    
+    User Query: {query}
+    
+    Classification:
+    """
+)

agents/rag_agent.py

@@ -0,0 +1,380 @@
+"""Agentic RAG implementation.
+
+This implementation focuses on:
+- Building an Agentic RAG system with dynamic search strategy
+- Using LangGraph for controlling the RAG workflow
+- Evaluating retrieved information quality
+"""
+
+import os.path as osp
+from typing import Dict, List, Optional, Any
+from langchain_core.messages import HumanMessage, AIMessage
+from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+from langchain_core.documents import Document
+from pydantic import BaseModel, Field
+
+from langgraph.graph import StateGraph, END, START, MessagesState
+from langgraph.graph.message import add_messages
+
+# For document retrieval
+from langchain_core.vectorstores import InMemoryVectorStore
+from langchain_community.tools.tavily_search import TavilySearchResults
+from langchain_core.tools import tool
+from langchain_core.tools.retriever import create_retriever_tool
+from langchain_community.document_loaders import PyPDFLoader
+from langchain_text_splitters import RecursiveCharacterTextSplitter
+from core.chat_interface import ChatInterface
+from agents.prompts import (
+    DOCUMENT_EVALUATOR_PROMPT,
+    DOCUMENT_SYNTHESIZER_PROMPT,
+    QUERY_REWRITER_PROMPT,
+)
+from langchain_core.prompts import PromptTemplate
+from langgraph.prebuilt import ToolNode, tools_condition
+from dotenv import load_dotenv
+load_dotenv()
+
+# NOTE: Update this to the path of your documents
+# For Hugging Face Spaces, use: "/home/user/app/documents/"
+# For local development, use your local path
+BASE_DIR = "data/"
+
+# Add your document files here
+FILE_PATHS = [
+    # Example for OPM documents (you can replace with your own documents):
+    osp.join(BASE_DIR, "2019-annual-performance-report.pdf"),
+    osp.join(BASE_DIR, "2020-annual-performance-report.pdf"),
+    osp.join(BASE_DIR, "2021-annual-performance-report.pdf"),
+    osp.join(BASE_DIR, "2022-annual-performance-report.pdf"),
+    
+
+]
+
+
+class DocumentEvaluation(BaseModel):
+    """Evaluation result for retrieved documents."""
+    is_sufficient: bool = Field(description="Whether the documents provide sufficient information")
+    feedback: str = Field(description="Feedback about the document quality and what's missing")
+
+
+class AgenticRAGState(MessagesState):
+    """State for the Agentic RAG workflow using MessagesState as base."""
+    # MessagesState already handles messages with add_messages reducer
+    feedback: str = ""
+    is_sufficient: bool = False
+    retry_count: int = 0  # Track number of retries to prevent infinite loops
+    max_retries: int = 3  # Maximum number of query rewrites allowed
+
+
+class AgenticRAGChat(ChatInterface):
+    """Agentic RAG implementation with dynamic retrieval and evaluation."""
+    
+    def __init__(self):
+        self.llm = None
+        self.embeddings = None
+        self.evaluator_llm = None
+        self.vector_store = None
+        self.tools = []
+        self.graph = None
+    
+    def initialize(self) -> None:
+        """Initialize components for the Agentic RAG system."""
+        # Initialize models
+        self.llm = ChatOpenAI(model="gpt-4o", temperature=0)
+        self.embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
+        self.evaluator_llm = self.llm.with_structured_output(DocumentEvaluation)
+
+        # Check if documents are configured
+        if FILE_PATHS and all(osp.exists(f) for f in FILE_PATHS):
+            # Load documents and create vector store
+            docs = self._load_and_process_documents()
+            print(f"Loading {len(docs)} documents into vector store")
+            self.vector_store = InMemoryVectorStore(embedding=self.embeddings)
+            self.vector_store.add_documents(docs)
+        else:
+            print("Warning: No documents configured for RAG. Add document paths to FILE_PATHS.")
+            # Create empty vector store
+            self.vector_store = InMemoryVectorStore(embedding=self.embeddings)
+        
+        # Create tools
+        self.tools = self._create_tools()
+        
+        # Create the graph
+        self.graph = self._create_graph()
+
+    def _load_and_process_documents(self) -> List[Document]:
+        """Load and process documents for RAG."""
+        docs = []
+        for file_path in FILE_PATHS:
+            if not osp.exists(file_path):
+                print(f"Warning: File not found - {file_path}")
+                continue
+                
+            print(f"Loading document from {file_path}")
+            try:
+                loader = PyPDFLoader(file_path)
+                page_docs = loader.load()
+                
+                # Combine all pages and split into chunks
+                combined_doc = "\n".join([doc.page_content for doc in page_docs])
+                
+                # Use RecursiveCharacterTextSplitter for better chunking
+                text_splitter = RecursiveCharacterTextSplitter(
+                    chunk_size=1000, 
+                    chunk_overlap=200,
+                    separators=["\n\n", "\n", ".", " ", ""]
+                )
+                chunks = text_splitter.split_text(combined_doc)
+                
+                # Convert chunks to Document objects with metadata
+                docs.extend([
+                    Document(
+                        page_content=chunk, 
+                        metadata={"source": osp.basename(file_path)}
+                    ) for chunk in chunks
+                ])
+            except Exception as e:
+                print(f"Error loading {file_path}: {e}")
+                
+        return docs
+    
+    def _create_tools(self) -> List[Any]:
+        """Create retriever and search tools."""
+        tools = []
+        
+        # Create retriever tool if we have documents
+        if self.vector_store:
+            retriever = self.vector_store.as_retriever(
+                search_type="similarity",
+                search_kwargs={"k": 3}
+            )
+            retriever_tool = create_retriever_tool(
+                retriever,
+                name="search_documents",
+                description=(
+                    "Search through the document database. "
+                    "Use this for questions about content in the loaded documents."
+                )
+            )
+            tools.append(retriever_tool)
+        
+        # Create web search tool
+        @tool("web_search")
+        def search_web(query: str) -> list[dict]:
+            """
+            Search the web for the latest information on any topic.
+            
+            Args:
+                query: The search query to look up
+                
+            Returns:
+                List of search results with title, content, and URL
+            """
+            search = TavilySearchResults(max_results=3)
+            return search.invoke(query)
+        
+        tools.append(search_web)
+        
+        return tools
+
+    def _generate_query_or_respond(self, state: AgenticRAGState):
+        """Generate a query or respond based on the current state."""
+        print("Generating query or responding...")
+        
+        prompt = PromptTemplate.from_template(
+            """
+            You are a helpful assistant that can answer questions using the provided tools.
+            
+            Available tools:
+            - search_documents: Search through loaded documents
+            - web_search: Search the web for information
+            
+            Based on the user's query, decide whether to use tools or respond directly.
+            Use tools when you need specific information to answer the question accurately.
+
+            Query: {question}
+            """
+        )
+        
+        # Get the latest message (either original or rewritten query)
+        question = state["messages"][-1].content
+        chain = prompt | self.llm.bind_tools(self.tools)
+        
+        response = chain.invoke({"question": question})
+        return {"messages": [response]}
+
+    def _evaluate_documents(self, state: AgenticRAGState):
+        """Evaluate the documents retrieved from the retriever tool."""
+        print("Evaluating documents...")
+        
+        # Get original user question and retrieved docs
+        user_question = state["messages"][0].content
+        retrieved_docs = state["messages"][-1].content
+        
+        chain = DOCUMENT_EVALUATOR_PROMPT | self.evaluator_llm
+        evaluation = chain.invoke({
+            "question": user_question, 
+            "retrieved_docs": retrieved_docs
+        })
+        
+        print(f"Evaluation result: {evaluation}")
+        return {
+            "is_sufficient": evaluation.is_sufficient,
+            "feedback": evaluation.feedback
+        }
+
+    def _synthesize_answer(self, state: AgenticRAGState):
+        """Synthesize the final answer from retrieved documents."""
+        print("Synthesizing answer...")
+        
+        user_question = state["messages"][0].content
+        retrieved_docs = state["messages"][-1].content
+        
+        chain = DOCUMENT_SYNTHESIZER_PROMPT | self.llm
+        answer = chain.invoke({
+            "question": user_question, 
+            "retrieved_docs": retrieved_docs
+        })
+        
+        return {"messages": [answer]}
+
+    def _query_rewriter(self, state: AgenticRAGState):
+        """Rewrite the query based on evaluation feedback."""
+        print("Rewriting query...")
+        
+        user_question = state["messages"][0].content
+        retrieved_docs = state["messages"][-1].content
+        feedback = state["feedback"]
+        
+        chain = QUERY_REWRITER_PROMPT | self.llm
+        new_query = chain.invoke({
+            "question": user_question, 
+            "feedback": feedback,
+            "retrieved_docs": retrieved_docs
+        })
+        
+        print(f"Rewritten query: {new_query.content}")
+        return {"messages": [new_query]}
+    
+    def _create_graph(self) -> Any:
+        """Create the agentic RAG graph."""
+        # Create the graph builder
+        graph_builder = StateGraph(AgenticRAGState)
+        
+        # Add nodes
+        graph_builder.add_node("generate_query_or_respond", self._generate_query_or_respond)
+        graph_builder.add_node("retrieve_documents", ToolNode(self.tools))
+        graph_builder.add_node("evaluate_documents", self._evaluate_documents)
+        graph_builder.add_node("synthesize_answer", self._synthesize_answer)
+        graph_builder.add_node("query_rewriter", self._query_rewriter)
+
+        # Add edges
+        graph_builder.add_edge(START, "generate_query_or_respond")
+        
+        # Conditional edge: if tools were called, retrieve documents; else end
+        graph_builder.add_conditional_edges(
+            "generate_query_or_respond",
+            tools_condition,
+            {
+                "tools": "retrieve_documents",
+                END: END,
+            },
+        )
+        
+        # After retrieval, evaluate documents
+        graph_builder.add_edge("retrieve_documents", "evaluate_documents")
+        
+        # Conditional edge: if sufficient, synthesize; else rewrite query
+        graph_builder.add_conditional_edges(
+            "evaluate_documents",
+            lambda x: "synthesize_answer" if x["is_sufficient"] else "query_rewriter",
+            {
+                "synthesize_answer": "synthesize_answer",
+                "query_rewriter": "query_rewriter",
+            },
+        )
+        
+        # After rewriting, generate new query
+        graph_builder.add_edge("query_rewriter", "generate_query_or_respond")
+        
+        # After synthesizing, end
+        graph_builder.add_edge("synthesize_answer", END)
+        
+        return graph_builder.compile()
+    
+    
+    def _convert_history_to_messages(self, chat_history: Optional[List[Dict[str, str]]]) -> List:
+        """Convert chat history to LangChain message format.
+        
+        Args:
+            chat_history: List of dicts with 'role' and 'content' keys
+            
+        Returns:
+            List of LangChain message objects
+        """
+        messages = []
+        if chat_history:
+            for msg in chat_history:
+                if msg["role"] == "user":
+                    messages.append(HumanMessage(content=msg["content"]))
+                elif msg["role"] == "assistant":
+                    messages.append(AIMessage(content=msg["content"]))
+        return messages
+    
+    
+    
+    def process_message(self, message: str, chat_history: Optional[List[Dict[str, str]]] = None) -> str:
+        """Process a message using the Agentic RAG system."""
+        print("\n=== STARTING AGENTIC RAG QUERY ===")
+        print(f"Query: {message}")
+        
+        # Convert chat history to messages
+        history_messages = self._convert_history_to_messages(chat_history)
+    
+        # Add the current message
+        history_messages.append(HumanMessage(content=message))
+        
+        # Create initial state with full conversation history
+        state = AgenticRAGState(
+            messages=history_messages,  # Include full history instead of just current message
+            feedback="",
+            is_sufficient=False,
+            retry_count=0,
+            max_retries=3
+        )
+        
+        # state = AgenticRAGState(
+        #     messages=[HumanMessage(content=message)],
+        #     feedback="",
+        #     is_sufficient=False,
+        #     retry_count=0,
+        #     max_retries=3  # Limit to 3 retries to prevent infinite loops
+        # )
+        
+        try:
+            # Run the workflow
+            # Run the workflow with increased recursion limit
+            config = {"recursion_limit": 3}  # Increased but reasonable limit
+            result = self.graph.invoke(state, config=config)
+            
+            print("\n=== RAG QUERY COMPLETED ===")
+            
+            # Return the final answer
+            if result.get("messages"):
+                final_message = result["messages"][-1]
+                if hasattr(final_message, 'content'):
+                    return final_message.content
+                else:
+                    return str(final_message)
+            else:
+                return "I couldn't find relevant information to answer your question."
+                
+        except Exception as e:
+            print(f"Error in RAG processing: {e}")
+            # Provide a more helpful fallback response
+            if "recursion" in str(e).lower():
+                return ("I had difficulty finding the exact information you're looking for in the documents. "
+                       "Based on the available documents, I can see references to various offices and services, "
+                       "but I couldn't find specific details about Mission Support Services. "
+                       "You might want to try asking about a specific aspect or department.")
+            return f"I encountered an error while searching for information: {str(e)}"

agents/research_agent.py

@@ -0,0 +1,451 @@
+"""Deep Research Multi-Agent System implementation.
+
+This implementation focuses on:
+- Building a multi-agent system for comprehensive research
+- Using LangGraph with MessagesState for proper state management
+- Synthesizing research findings into structured reports
+"""
+
+from typing import Dict, List, Optional, Any, Annotated
+from langchain_core.messages import HumanMessage, AIMessage, BaseMessage
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.output_parsers import StrOutputParser
+from langchain_openai import ChatOpenAI
+from langchain_community.tools.tavily_search import TavilySearchResults
+from langchain_core.tools import tool
+from langgraph.graph import StateGraph, END, START, MessagesState
+from langgraph.prebuilt import create_react_agent
+from pydantic import BaseModel, Field
+
+from core.chat_interface import ChatInterface
+from opik.integrations.langchain import OpikTracer
+from agents.prompts import (
+    RESEARCH_MANAGER_PROMPT,
+    REPORT_FINALIZER_PROMPT,
+)
+from dotenv import load_dotenv
+load_dotenv()
+
+
+class ResearchQuestion(BaseModel):
+    """A research question with a title and description."""
+    title: str = Field(description="The title of the research question/section")
+    description: str = Field(description="Description of what to research for this section")
+    completed: bool = Field(default=False, description="Whether research has been completed for this section")
+
+
+class ResearchPlan(BaseModel):
+    """The overall research plan created by the Research Manager."""
+    topic: str = Field(description="The main research topic")
+    questions: List[ResearchQuestion] = Field(description="The list of research questions to investigate")
+    current_question_index: int = Field(default=0, description="Index of the current question being researched")
+
+
+class Report(BaseModel):
+    """The final research report structure."""
+    executive_summary: Optional[str] = Field(default=None, description="Executive summary of the research")
+    key_findings: Optional[str] = Field(default=None, description="Key findings from the research")
+    detailed_analysis: List[Dict[str, Any]] = Field(default_factory=list, description="Detailed analysis sections")
+    limitations: Optional[str] = Field(default=None, description="Limitations and further research")
+
+
+class ResearchState(MessagesState):
+    """State tracking for the deep research workflow using MessagesState as base."""
+    research_plan: Optional[ResearchPlan] = None
+    report: Optional[Report] = None
+    next_step: str = "research_manager"
+    
+    # MessagesState already handles messages with add_messages reducer
+
+
+class DeepResearchChat(ChatInterface):
+    """Deep research implementation using multi-agent system with proper state management."""
+    
+    def __init__(self):
+        self.llm = None
+        self.research_manager = None
+        self.specialized_research_agent = None
+        self.finalizer = None
+        self.workflow = None
+        self.tavily_search_tool = None
+    
+    def initialize(self) -> None:
+        """Initialize components for the deep research system."""
+        # Initialize LLM model
+        self.llm = ChatOpenAI(model="gpt-4o", temperature=0)
+        
+        # Create Tavily search tool for agents
+        self.tavily_search_tool = TavilySearchResults(max_results=5)
+        
+        # Create components
+        self.research_manager = self._create_research_manager()
+        self.specialized_research_agent = self._create_specialized_research_agent()
+        self.finalizer = self._create_finalizer()
+        
+        # Create the workflow graph using these agents
+        self.workflow = self._create_workflow()
+        
+        # Optional: Create Opik Tracer for monitoring
+        try:
+            self.tracer = OpikTracer(
+                graph=self.workflow.get_graph(xray=True),
+                project_name="nexus-research-workflow"
+            )
+        except:
+            self.tracer = None
+            print("Opik tracer not available, continuing without monitoring")
+    
+    def _create_research_manager(self) -> Any:
+        """Create the research manager agent."""
+        research_manager = (
+            RESEARCH_MANAGER_PROMPT 
+            | self.llm.with_structured_output(ResearchPlan)
+        )
+        
+        return research_manager
+
+    def _create_specialized_research_agent(self) -> Any:
+        """Create specialized research agents."""
+        # Create search tool for the agent
+        @tool("web_search")
+        def search_web(query: str) -> str:
+            """Search the web for information on the research topic."""
+            results = self.tavily_search_tool.invoke(query)
+            formatted_results = []
+            
+            for i, result in enumerate(results, 1):
+                formatted_results.append(f"Result {i}:")
+                formatted_results.append(f"Title: {result.get('title', 'N/A')}")
+                formatted_results.append(f"Content: {result.get('content', 'N/A')}")
+                formatted_results.append(f"URL: {result.get('url', 'N/A')}")
+                formatted_results.append("")
+            
+            return "\n".join(formatted_results)
+        
+        # Create the specialized agent
+        tools = [search_web]
+        
+        # Define the system message for the specialized research agent
+        system_message = """You are a Specialized Research Agent responsible for thoroughly researching a specific topic section.
+
+        Process:
+        1. Analyze the research question and description
+        2. Generate effective search queries to gather information
+        3. Use the web_search tool to find relevant information
+        4. Synthesize findings into a comprehensive section
+        5. Include proper citations to your sources
+
+        Your response should be:
+        - Thorough (at least 500 words)
+        - Well-structured with subsections
+        - Based on factual information (not made up)
+        - Include proper citations to sources
+
+        Always critically evaluate information and ensure you cover the topic comprehensively.
+        """
+        
+        # Create the specialized research agent
+        specialized_agent = create_react_agent(
+            model=self.llm,
+            tools=tools,
+            prompt=system_message
+        )
+        
+        return specialized_agent
+    
+    def _create_finalizer(self) -> Any:
+        """Create the finalizer component."""
+        finalizer = REPORT_FINALIZER_PROMPT | self.llm | StrOutputParser()
+        return finalizer
+    
+    def _create_workflow(self) -> Any:
+        """Create the multi-agent deep research workflow with proper MessagesState usage."""
+        # Create a state graph
+        workflow = StateGraph(ResearchState)
+        
+        # Define the nodes
+        
+        # Research Manager Node
+        def research_manager_node(state: ResearchState) -> Dict:
+            """Create the research plan and update messages."""
+            print("\n=== RESEARCH MANAGER NODE ===")
+            
+            # Get the topic from the LAST user message (not first)
+            # This handles conversation context better
+            user_messages = [msg for msg in state["messages"] if isinstance(msg, HumanMessage)]
+            topic = user_messages[-1].content if user_messages else state["messages"][-1].content
+            
+            print(f"Planning research for topic: {topic}")
+            
+            # Generate research plan
+            research_plan = self.research_manager.invoke({"topic": topic})
+            print(f"Created research plan with {len(research_plan.questions)} questions")
+            
+            # Initialize empty report structure
+            report = Report(
+                detailed_analysis=[
+                    {"title": q.title, "content": None, "sources": []} 
+                    for q in research_plan.questions
+                ]
+            )
+    
+            # Add planning message to state
+            planning_msg = AIMessage(
+                content=f"Research plan created with {len(research_plan.questions)} sections to investigate."
+            )
+            
+            return {
+                "messages": [planning_msg],
+                "research_plan": research_plan,
+                "report": report,
+            }
+        
+        # Specialized Research Node
+        def specialized_research_node(state: ResearchState) -> Dict:
+            """Conduct research on the current question and update messages."""
+            print("\n=== SPECIALIZED RESEARCH NODE ===")
+            
+            research_plan = state["research_plan"]
+            assert research_plan is not None, "Research plan is None"
+            current_index = research_plan.current_question_index
+            
+            if current_index >= len(research_plan.questions):
+                print("All research questions completed")
+                return {}
+            
+            current_question = research_plan.questions[current_index]
+            print(f"Researching question {current_index + 1}/{len(research_plan.questions)}: "
+                  f"{current_question.title}")
+            
+            # Create input for the specialized agent
+            research_input = {
+                "messages": [
+                    ("user", f"""Research the following topic thoroughly:
+                    
+                    Topic: {current_question.title}
+                    
+                    Description: {current_question.description}
+                    
+                    Provide a detailed analysis with proper citations to sources.
+                    """)
+                ]
+            }
+            
+            # Invoke the specialized agent
+            result = self.specialized_research_agent.invoke(research_input)
+            
+            # Extract content from the result
+            last_message = result["messages"][-1]
+            if isinstance(last_message, tuple):
+                content = last_message[1]
+            else:
+                content = last_message.content
+            
+            # Parse out sources from the content
+            sources = []
+            for line in content.split("\n"):
+                if "http" in line and "://" in line:
+                    sources.append(line.strip())
+            
+            # Update the research plan
+            research_plan.questions[current_index].completed = True
+            
+            # Update the report
+            report = state["report"]
+            assert report is not None, "Report is None"
+            report.detailed_analysis[current_index]["content"] = content
+            report.detailed_analysis[current_index]["sources"] = sources
+            
+            # Move to the next question
+            research_plan.current_question_index += 1
+            
+            # Add research progress message
+            progress_msg = AIMessage(
+                content=f"Completed research for section: {current_question.title}"
+            )
+            
+            return {
+                "messages": [progress_msg],
+                "research_plan": research_plan,
+                "report": report,
+            }
+            
+        # Research Evaluator Node
+        def evaluator_node(state: ResearchState) -> Dict:
+            """Evaluate the research progress and determine next steps."""
+            print("\n=== EVALUATOR NODE ===")
+            
+            research_plan = state["research_plan"]
+            assert research_plan is not None, "Research plan is None"
+            
+            # Check if we've completed all questions
+            all_completed = research_plan.current_question_index >= len(research_plan.questions)
+            
+            if all_completed:
+                print("All research questions have been addressed. Moving to finalizer.")
+                eval_msg = AIMessage(content="All research sections completed. Finalizing report...")
+                return {
+                    "messages": [eval_msg],
+                    "next_step": "finalize"
+                }
+            else:
+                # We have more sections to research
+                next_section = research_plan.questions[research_plan.current_question_index].title
+                print(f"More research needed. Moving to next section: {next_section}")
+                eval_msg = AIMessage(content=f"Moving to research section: {next_section}")
+                return {
+                    "messages": [eval_msg],
+                    "next_step": "research"
+                }
+        
+        # Finalizer Node
+        def finalizer_node(state: ResearchState) -> Dict:
+            """Finalize the research report and update messages."""
+            print("\n=== FINALIZER NODE ===")
+            
+            research_plan = state["research_plan"]
+            report = state["report"]
+            assert report is not None, "Report is None"
+            assert research_plan is not None, "Research plan is None"
+            
+            # Prepare the detailed analysis for the finalizer
+            detailed_analysis = "\n\n".join([
+                f"## {section['title']}\n{section['content']}"
+                for section in report.detailed_analysis
+                if section['content'] is not None
+            ])
+            
+            # Generate the final sections
+            final_sections = self.finalizer.invoke({
+                "topic": research_plan.topic,
+                "detailed_analysis": detailed_analysis
+            })
+            
+            # Parse the final sections
+            sections = final_sections.split("\n\n")
+            
+            # Update the report
+            if len(sections) >= 3:
+                report.executive_summary = sections[0].replace("# Executive Summary", "").strip()
+                report.key_findings = sections[1].replace("# Key Findings", "").strip()
+                report.limitations = sections[2].replace("# Limitations and Further Research", "").strip()
+            
+            # Format the final report
+            report_message = self._format_report(report)
+            
+            return {
+                "messages": [report_message],
+            }
+        
+        # Add nodes to the graph
+        workflow.add_node("research_manager", research_manager_node)
+        workflow.add_node("specialized_research", specialized_research_node)
+        workflow.add_node("evaluate", evaluator_node)
+        workflow.add_node("finalizer", finalizer_node)
+        
+        # Add edges
+        workflow.add_edge(START, "research_manager")
+        workflow.add_edge("research_manager", "specialized_research")
+        workflow.add_edge("specialized_research", "evaluate")
+        
+        # Add conditional edges from evaluator
+        workflow.add_conditional_edges(
+            "evaluate",
+            lambda x: x["next_step"],
+            {
+                "research": "specialized_research",
+                "finalize": "finalizer"
+            }
+        )
+        workflow.add_edge("finalizer", END)
+        
+        # Compile the workflow
+        return workflow.compile()
+    
+    def _format_report(self, report: Report) -> AIMessage:
+        """Format the research report for presentation."""
+        sections = [
+            "# Research Report\n",
+            
+            "## Executive Summary\n" + (report.executive_summary or "N/A"),
+            
+            "## Key Findings\n" + (report.key_findings or "N/A"),
+            
+            "## Detailed Analysis"
+        ]
+        
+        # Add detailed analysis sections
+        for section in report.detailed_analysis:
+            if section["content"]:
+                sections.append(f"### {section['title']}\n{section['content']}")
+                
+                if section["sources"]:
+                    sources = "\n".join([f"- {source}" for source in section["sources"]])
+                    sections.append(f"**Sources:**\n{sources}")
+        
+        # Add limitations
+        sections.append("## Limitations and Further Research\n" + (report.limitations or "N/A"))
+        
+        return AIMessage(content="\n\n".join(sections))
+    
+    def _convert_history_to_messages(self, chat_history: Optional[List[Dict[str, str]]]) -> List:
+        """Convert chat history to LangChain message format.
+        
+        Args:
+            chat_history: List of dicts with 'role' and 'content' keys
+            
+        Returns:
+            List of LangChain message objects
+        """
+        messages = []
+        if chat_history:
+            for msg in chat_history:
+                if msg["role"] == "user":
+                    messages.append(HumanMessage(content=msg["content"]))
+                elif msg["role"] == "assistant":
+                    messages.append(AIMessage(content=msg["content"]))
+        return messages
+    
+    
+    def process_message(self, message: str, chat_history: Optional[List[Dict[str, str]]] = None) -> str:
+        """Process a message using the deep research system with proper state management."""
+        print("\n=== STARTING DEEP RESEARCH ===")
+        print(f"Research Topic: {message}")
+        
+        # Convert chat history to messages
+        history_messages = self._convert_history_to_messages(chat_history)
+        
+        # Add the current message
+        history_messages.append(HumanMessage(content=message))
+        
+        # Create initial state with full conversation history
+        initial_state = ResearchState(
+            messages=history_messages,  # Include full history instead of just current message
+            research_plan=None,
+            report=None,
+            next_step="research_manager"
+        )
+        # # Create initial state using MessagesState
+        # initial_state = ResearchState(
+        #     messages=[HumanMessage(content=message)],
+        #     research_plan=None,
+        #     report=None,
+        #     next_step="research_manager"
+        # )
+        
+        # Run workflow with optional tracing
+        config = {"callbacks": [self.tracer]} if self.tracer else {}
+        result = self.workflow.invoke(initial_state, config=config)
+        
+        print("\n=== RESEARCH COMPLETED ===")
+        
+        # Write the final report to a file
+        try:
+            with open("final_report.md", "w") as f:
+                f.write(result["messages"][-1].content)
+            print("Report saved to final_report.md")
+        except Exception as e:
+            print(f"Could not save report to file: {e}")
+        
+        # Return the final report
+        return result["messages"][-1].content

agents/tool_agent.py

@@ -0,0 +1,177 @@
+"""Tool-Using Agent implementation.
+
+This implementation focuses on:
+- Converting tools to use with LangGraph
+- Using the ReAct pattern for autonomous tool selection
+- Handling calculator, datetime, and weather queries
+"""
+
+from typing import Dict, List, Optional, Any, Annotated
+import io
+import contextlib
+from langchain_core.tools import tool
+from langchain.chat_models import init_chat_model
+from langgraph.prebuilt import create_react_agent
+from langchain_community.tools.tavily_search import TavilySearchResults
+from langchain_core.messages import HumanMessage, AIMessage
+
+from core.chat_interface import ChatInterface
+from tools.calculator import Calculator
+from dotenv import load_dotenv
+load_dotenv()
+
+
+class ToolUsingAgentChat(ChatInterface):
+    """Tool-using agent implementation with calculator, datetime, and weather tools."""
+    
+    def __init__(self):
+        self.llm = None
+        self.tools = []
+        self.graph = None
+    
+    def initialize(self) -> None:
+        """Initialize components for the tool-using agent.
+        
+        This sets up:
+        - The chat model
+        - Tools for calculator, DateTime, and weather
+        - The ReAct agent using LangGraph
+        """
+        # Initialize chat model
+        self.llm = init_chat_model("gpt-4o", model_provider="openai")
+        
+        # Create tools
+        self.tools = self._create_tools()
+        
+        # Create the ReAct agent graph with the tools
+        # The agent will autonomously decide which tools to use based on the query
+        self.graph = create_react_agent(
+            model=self.llm,
+            tools=self.tools,
+        )
+    
+    def _create_tools(self) -> List[Any]:
+        """Create and return the list of tools for the agent.
+        
+        Returns:
+            List: List of tool objects
+        """
+        # Calculator tool for mathematical operations
+        @tool
+        def calculator(expression: Annotated[str, "The mathematical expression to evaluate"]) -> str:
+            """Evaluate a mathematical expression using basic arithmetic operations (+, -, *, /, %, //).
+            Examples: '5 + 3', '10 * (2 + 3)', '15 / 3', '17 % 5', '20 // 3'
+            """
+            result = Calculator.evaluate_expression(expression)
+            if isinstance(result, str) and result.startswith("Error"):
+                raise ValueError(result)
+            return str(result)
+
+        # DateTime tool for date/time operations
+        @tool
+        def execute_datetime_code(code: Annotated[str, "Python code to execute for datetime operations"]) -> str:
+            """Execute Python code for datetime operations. The code should use datetime or time modules.
+            Examples: 
+            - 'print(datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S"))'
+            - 'print(datetime.datetime.now().strftime("%A, %B %d, %Y"))'
+            - 'print(datetime.datetime.now().year)'
+            - 'print((datetime.datetime(2025, 12, 25) - datetime.datetime.now()).days)'
+            """
+            output_buffer = io.StringIO()
+            code = f"import datetime\nimport time\n{code}"
+            try:
+                with contextlib.redirect_stdout(output_buffer):
+                    exec(code)
+                return output_buffer.getvalue().strip()
+            except Exception as e:
+                raise ValueError(f"Error executing datetime code: {str(e)}")
+
+        # Weather tool using Tavily search
+        @tool
+        def get_weather(location: Annotated[str, "The location to get weather for (city, country)"]) -> str:
+            """Get the current weather for a given location using web search.
+            Examples: 'New York, USA', 'London, UK', 'Tokyo, Japan', 'Paris, France'
+            """
+            search = TavilySearchResults(max_results=3)
+            query = f"current weather temperature conditions {location} today"
+            results = search.invoke(query)
+            
+            if not results:
+                return f"Could not find weather information for {location}"
+            
+            # Combine results for better coverage
+            weather_info = []
+            for result in results[:2]:  # Use top 2 results
+                content = result.get("content", "")
+                if content:
+                    weather_info.append(content)
+            
+            if weather_info:
+                return " ".join(weather_info)
+            else:
+                return f"Could not find detailed weather information for {location}"
+        
+        return [calculator, execute_datetime_code, get_weather]
+
+    def _convert_history_to_messages(self, chat_history: Optional[List[Dict[str, str]]]) -> List:
+        """Convert chat history to LangChain message format.
+        
+        Args:
+            chat_history: List of dicts with 'role' and 'content' keys
+            
+        Returns:
+            List of LangChain message objects
+        """
+        messages = []
+        if chat_history:
+            for msg in chat_history:
+                if msg["role"] == "user":
+                    messages.append(HumanMessage(content=msg["content"]))
+                elif msg["role"] == "assistant":
+                    messages.append(AIMessage(content=msg["content"]))
+        return messages
+
+    def process_message(self, message: str, chat_history: Optional[List[Dict[str, str]]] = None) -> str:
+        """Process a message using the tool-using agent.
+        
+        The ReAct agent will:
+        1. Consider the full conversation history
+        2. Analyze the query in context
+        3. Decide which tool(s) to use
+        4. Execute the tool(s)
+        5. Formulate a response
+        
+        Args:
+            message: The user's input message
+            chat_history: List of previous chat messages
+            
+        Returns:
+            str: The assistant's response
+        """
+        try:
+            # Convert chat history to messages
+            history_messages = self._convert_history_to_messages(chat_history)
+            
+            # Add the current message
+            history_messages.append(HumanMessage(content=message))
+            
+            # Run the graph with the full conversation history
+            result = self.graph.invoke({"messages": history_messages})
+            
+            # Run the graph with the user's message
+            # result = self.graph.invoke({"messages": [("user", message)]})
+            
+            # Extract the final response
+            if result.get("messages"):
+                final_message = result["messages"][-1]
+                # Handle different message formats
+                if hasattr(final_message, 'content'):
+                    return final_message.content
+                else:
+                    return str(final_message)
+            else:
+                return "I couldn't process that request. Please try rephrasing."
+                
+        except Exception as e:
+            print(f"Error in tool agent: {e}")
+            return f"I encountered an error while processing your request: {str(e)}. Please try again."

agents/unified_chat.py

@@ -0,0 +1,166 @@
+"""Unified Chat Implementation combining all agent functionalities.
+
+This implementation combines:
+- Tool-using agent (calculator, datetime, weather)
+- Agentic RAG for document queries
+- Deep research for comprehensive analysis
+"""
+
+import os.path as osp
+import io
+import contextlib
+from typing import Dict, List, Optional, Any, Annotated
+from enum import Enum
+
+from langchain_core.messages import HumanMessage, AIMessage
+from langchain_core.tools import tool
+from langchain.chat_models import init_chat_model
+from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+from langgraph.prebuilt import create_react_agent
+from langgraph.graph import MessagesState
+from langchain_community.tools.tavily_search import TavilySearchResults
+from langchain_core.prompts import PromptTemplate
+
+from core.chat_interface import ChatInterface
+from tools.calculator import Calculator
+from agents.prompts import QUERY_CLASSIFIER_PROMPT
+
+# Import components from individual agents
+from agents.tool_agent import ToolUsingAgentChat
+from agents.rag_agent import AgenticRAGChat
+from agents.research_agent import DeepResearchChat
+from dotenv import load_dotenv
+load_dotenv()
+
+
+class QueryType(Enum):
+    """Types of queries the system can handle."""
+    SIMPLE_TOOL = "simple_tool"  # Calculator, datetime, weather
+    AGENTIC_RAG = "agentic_rag"  # OPM document queries
+    DEEP_RESEARCH = "deep_research"  # Comprehensive research
+    GENERAL = "general"  # General conversation
+
+
+class UnifiedChatState(MessagesState):
+    """Unified state that uses MessagesState for proper message handling."""
+    query_type: Optional[str] = None
+    current_agent: Optional[str] = None
+
+
+class UnifiedChat(ChatInterface):
+    """Unified chat implementation that routes queries to appropriate handlers."""
+    
+    def __init__(self):
+        self.router_llm = None
+        self.tool_agent = None
+        self.rag_agent = None
+        self.research_agent = None
+        self.query_classifier = None
+        
+    def initialize(self) -> None:
+        """Initialize all components for the unified system."""
+        print("Initializing Nexus AI Unified System...")
+        
+        # Initialize router LLM for query classification
+        self.router_llm = ChatOpenAI(model="gpt-4o", temperature=0)
+        
+        # Initialize query classifier
+        self._create_query_classifier()
+        
+        # Initialize all sub-agents
+        print("Initializing Tool-Using Agent...")
+        self.tool_agent = ToolUsingAgentChat()
+        self.tool_agent.initialize()
+        
+        print("Initializing Agentic RAG...")
+        self.rag_agent = AgenticRAGChat()
+        self.rag_agent.initialize()
+        
+        print("Initializing Deep Research Agent...")
+        self.research_agent = DeepResearchChat()
+        self.research_agent.initialize()
+        
+        print("Nexus AI System initialized successfully!")
+    
+    def _create_query_classifier(self):
+        """Create the query classifier that routes to appropriate handlers."""
+        self.query_classifier = QUERY_CLASSIFIER_PROMPT | self.router_llm
+    
+    def _classify_query(self, query: str) -> QueryType:
+        """Classify the query to determine which handler to use."""
+        try:
+            result = self.query_classifier.invoke({"query": query})
+            classification = result.content.strip().upper()
+            
+            print(f"Query Classification: {classification}")
+            
+            # Map to enum
+            if classification == "SIMPLE_TOOL":
+                return QueryType.SIMPLE_TOOL
+            elif classification == "AGENTIC_RAG":
+                return QueryType.AGENTIC_RAG
+            elif classification == "DEEP_RESEARCH":
+                return QueryType.DEEP_RESEARCH
+            else:
+                return QueryType.GENERAL
+                
+        except Exception as e:
+            print(f"Error in query classification: {e}")
+            # Default to general tool agent for safety
+            return QueryType.GENERAL
+    
+    def process_message(self, message: str, chat_history: Optional[List[Dict[str, str]]] = None) -> str:
+        """Process a message by routing to the appropriate handler.
+        
+        Uses MessagesState internally for proper state management when needed.
+        
+        Args:
+            message: The user's input message
+            chat_history: List of previous chat messages
+            
+        Returns:
+            str: The assistant's response
+        """
+        print(f"\n{'='*50}")
+        print(f"Processing query: {message}")
+        print(f"{'='*50}")
+        
+        # Classify the query
+        query_type = self._classify_query(message)
+        
+        # Create state with messages for tracking
+        state = UnifiedChatState(
+            messages=[HumanMessage(content=message)],
+            query_type=query_type.value,
+            current_agent=None
+        )
+        
+        # Route to appropriate handler
+        try:
+            if query_type == QueryType.SIMPLE_TOOL or query_type == QueryType.GENERAL:
+                print("→ Routing to Tool-Using Agent")
+                state["current_agent"] = "tool_agent"
+                return self.tool_agent.process_message(message, chat_history)
+                
+            elif query_type == QueryType.AGENTIC_RAG:
+                print("→ Routing to Agentic RAG")
+                state["current_agent"] = "rag_agent"
+                return self.rag_agent.process_message(message, chat_history)
+                
+            elif query_type == QueryType.DEEP_RESEARCH:
+                print("→ Routing to Deep Research Agent")
+                state["current_agent"] = "research_agent"
+                return self.research_agent.process_message(message, chat_history)
+                
+            else:
+                # Fallback to tool agent for general queries
+                print("→ Routing to Tool-Using Agent (fallback)")
+                state["current_agent"] = "tool_agent"
+                return self.tool_agent.process_message(message, chat_history)
+                
+        except Exception as e:
+            error_msg = f"Error processing message: {str(e)}"
+            print(error_msg)
+            # Add error to state messages
+            state["messages"].append(AIMessage(content=f"I encountered an error: {str(e)}"))
+            return f"I encountered an error while processing your request: {str(e)}. Please try rephrasing your question."

app.py

@@ -0,0 +1,108 @@
+"""Main application file for Nexus AI Assistant.
+
+This file handles the Gradio interface and orchestrates the chat implementations.
+"""
+
+
+from typing import List, Dict, Tuple
+import os
+import sys
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Add the parent directory to Python path so imports work correctly
+# root_path = Path(__file__).resolve().parent
+# sys.path.append(str(root_path))
+# print(f"root path: {root_path}")
+
+import gradio as gr
+# Import the unified chat implementation
+from agents.unified_chat import UnifiedChat
+load_dotenv()
+
+def create_demo():
+    """Create the Gradio demo for the unified chat system."""
+    
+    # Initialize the unified chat implementation
+    chat_impl = UnifiedChat()
+    
+    # Initialize the chat implementation
+    try:
+        chat_impl.initialize()
+        init_status = "✅ All systems ready!"
+    except Exception as e:
+        init_status = f"❌ Error initializing: {str(e)}"
+        print(init_status)
+    
+    def respond(message: str, history: List[Tuple[str, str]]) -> str:
+        """Process a message and return the response.
+        
+        Args:
+            message: The user's input message
+            history: List of tuples containing (user_message, assistant_response)
+            
+        Returns:
+            str: The assistant's response
+        """
+        if not message:
+            return "Please enter a message."
+        
+        # Convert history to the format expected by the chat implementation
+        history_dicts = []
+        for user_msg, assistant_msg in history:
+            history_dicts.append({"role": "user", "content": user_msg})
+            history_dicts.append({"role": "assistant", "content": assistant_msg})
+        
+        try:
+            # Process the message
+            response = chat_impl.process_message(message, history_dicts)
+            return response
+        except Exception as e:
+            return f"Error processing message: {str(e)}"
+    
+    
+    # Create the Gradio interface using ChatInterface
+    demo = gr.ChatInterface(
+        fn=respond,
+        title="🤖 Nexus AI - Unified Intelligent Assistant",
+        description=f"""
+        {init_status}
+        
+        I combine multiple AI capabilities:
+        • 🧮 **Calculator & Math** - Complex calculations
+        • 📅 **Date & Time** - Current date, time calculations  
+        • 🌤️ **Weather** - Real-time weather information
+        • 📚 **Document Analysis** - RAG-powered document search
+        • 🔬 **Deep Research** - Comprehensive multi-source analysis
+        • 💬 **General Chat** - Conversational AI
+        
+        The system automatically routes your query to the most appropriate handler.
+        """,
+        examples=[
+            "What is 847 * 293?",
+            "What's today's date?",
+            "What's the weather in San Francisco?",
+            "Explain quantum computing in simple terms",
+            "Research the impact of AI on healthcare",
+        ],
+        theme=gr.themes.Soft(),
+        analytics_enabled=False,
+    )
+    
+    return demo
+
+
+if __name__ == "__main__":
+    # Create and launch the demo
+    demo = create_demo()
+    
+    # Check if running in Hugging Face Spaces
+    if os.environ.get("SPACE_ID"):
+        # Hugging Face Spaces configuration
+        demo.launch(
+            server_name="0.0.0.0",
+            server_port=int(os.environ.get("PORT", 7860))
+        )
+    else:
+        # Local development - use simple defaults
+        demo.launch()

core/chat_interface.py

@@ -0,0 +1,40 @@
+from abc import ABC, abstractmethod
+from typing import Dict, List
+
+class ChatInterface(ABC):
+    """Abstract base class defining the core chat interface functionality.
+    
+    This interface is designed to be flexible enough to support different 
+    implementations across various assignments, from basic query handling
+    to complex information retrieval and tool usage.
+    """
+    
+    @abstractmethod
+    def initialize(self) -> None:
+        """Initialize any models, tools, or components needed for chat processing.
+        
+        This method should be called after instantiation to set up any necessary
+        components like language models, memory, tools, etc. This separation allows
+        for proper error handling during initialization and lazy loading of resources.
+        """
+        pass
+    
+    @abstractmethod
+    def process_message(self, message: str, chat_history: List[Dict[str, str]]) -> str:
+        """Process a message and return a response.
+        
+        This is the core method that all implementations must define. Different
+        implementations can handle the message processing in their own way, such as:
+        - Week 1: Query classification, basic tools, and memory
+        - Week 2: RAG, web search, and knowledge synthesis
+        - Week 3: Advanced tool calling and agentic behavior
+        
+        Args:
+            message: The user's input message
+            chat_history: Optional list of previous chat messages, where each message
+                         is a dict with 'role' (user/assistant) and 'content' keys
+            
+        Returns:
+            str: The assistant's response
+        """
+        pass 

data/2019-annual-performance-report.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d9c03ac0b77ef7bc82433049e4dd7783cd56855b51f62d3255cf0d2ee7c8e7c2
+size 2357476

data/2020-annual-performance-report.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5de716f9e6bd1bad9b0b64768a8af4a7e528b1ea73798ef3f630d1b079091e7b
+size 2838017

data/2021-annual-performance-report.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:11e216c3fe1ff2d31ef7c06eb019b65723cfc53b7a935d68b5c7dea2638bd830
+size 9822451

data/2022-annual-performance-report.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b6200aff36bfcbfa955af57d8fdbebf01a233474949421adb1dc59efd8c4ea8d
+size 4134068

requirements.txt

@@ -0,0 +1,14 @@
+tavily-python==0.7.5
+langchain-community==0.3.25
+pypdf==5.1.0
+langchain==0.3.25
+langgraph==0.4.5
+langchain-openai==0.3.18
+python-dotenv==1.1.0
+gradio==5.34.2
+langgraph-prebuilt==0.2.2
+opik
+fastmcp==2.8.1
+langchain-mcp-adapters==0.1.7
+gradio==5.34.2
+huggingface_hub[cli]

tools/calculator.py

@@ -0,0 +1,50 @@
+import re
+from typing import Union
+
+class Calculator:
+    """A simple calculator tool for evaluating basic arithmetic expressions."""
+    
+    @staticmethod
+    def evaluate_expression(expression: str) -> Union[float, str]:
+        """Evaluate a basic arithmetic expression.
+        
+        Supports only basic arithmetic operations (+, -, *, /) and parentheses.
+        Returns an error message if the expression is invalid or cannot be 
+        evaluated safely.
+        
+        Args:
+            expression: A string containing a mathematical expression
+                       e.g. "5 + 3" or "10 * (2 + 3)"
+            
+        Returns:
+            Union[float, str]: The result of the evaluation, or an error message
+                              if the expression is invalid
+        
+        Examples:
+            >>> Calculator.evaluate_expression("5 + 3")
+            8.0
+            >>> Calculator.evaluate_expression("10 * (2 + 3)")
+            50.0
+            >>> Calculator.evaluate_expression("15 / 3")
+            5.0
+        """
+        try:
+            # Clean up the expression
+            expression = expression.strip()
+            
+            # Only allow safe characters (digits, basic operators, parentheses, spaces)
+            if not re.match(r'^[\d\s\+\-\*\/\(\)\.]*$', expression):
+                return "Error: Invalid characters in expression"
+            
+            # Evaluate the expression
+            result = eval(expression, {"__builtins__": {}})
+            
+            # Convert to float and handle division by zero
+            return float(result)
+            
+        except ZeroDivisionError:
+            return "Error: Division by zero"
+        except (SyntaxError, TypeError, NameError):
+            return "Error: Invalid expression"
+        except Exception as e:
+            return f"Error: {str(e)}"