initial code

Dockerfile

@@ -0,0 +1,23 @@
+# Use an official Python runtime as a parent image
+FROM python:3.10-slim
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy the requirements file into the container
+COPY requirements.txt .
+
+# Install any needed packages specified in requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the current directory contents into the container at /app
+COPY . .
+
+# Expose the port FastAPI runs on
+EXPOSE 8000
+
+# Define environment variable for unbuffered logs (good for Docker)
+ENV PYTHONUNBUFFERED=1
+
+# Run the application
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

README.md

@@ -1,64 +1,127 @@
-#  Retrieval-Augmented Generation (RAG) Knowledge Search Engine
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Agentic RAG Knowledge Search</title>
+    <style>
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+            line-height: 1.6;
+            color: #333;
+            max-width: 800px;
+            margin: 0 auto;
+            padding: 20px;
+        }
+        h1, h2, h3 {
+            color: #2c3e50;
+            margin-top: 1.5em;
+        }
+        h1 {
+            border-bottom: 2px solid #eaeaea;
+            padding-bottom: 0.5em;
+        }
+        code {
+            background-color: #f6f8fa;
+            padding: 0.2em 0.4em;
+            border-radius: 3px;
+            font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace;
+            font-size: 85%;
+        }
+        pre {
+            background-color: #f6f8fa;
+            padding: 16px;
+            overflow: auto;
+            border-radius: 6px;
+            line-height: 1.45;
+        }
+        pre code {
+            background-color: transparent;
+            padding: 0;
+            font-size: 100%;
+        }
+        ul {
+            padding-left: 2em;
+        }
+        li {
+            margin-bottom: 0.5em;
+        }
+        a {
+            color: #0366d6;
+            text-decoration: none;
+        }
+        a:hover {
+            text-decoration: underline;
+        }
+    </style>
+</head>
+<body>
 
-This project implements a robust Retrieval-Augmented Generation (RAG) pipeline designed to enable reliable, context-aware question answering over custom, private documents (PDFs, DOCX, CSV, TXT). It minimizes Large Language Model (LLM) "hallucinations" by grounding all answers strictly within the retrieved source material, providing full traceability and high domain-specific accuracy.
+    <h1>Agentic RAG Knowledge Search</h1>
 
-## Features
+    <p>A production-ready AI Microservice that uses an <strong>Agentic Router</strong> to intelligently decide between retrieving answers from internal private documents (RAG) or searching the live web.</p>
 
-  * **Multi-Document Support:** Easily ingest and index documents of various formats (`.pdf`, `.txt`, `.docx`, `.csv`).
-  * **Context Grounding:** Utilizes a custom prompt that forces the LLM to use **only** the provided context, ensuring factual and traceable answers  .
-  * **Vectorization & Retrieval:** Leverages **Google Generative AI Embeddings** and the high-performance **FAISS** vector store for sub-second similarity search  .
-  * **End-to-End Pipeline:** Wires the components into a `RetrievalQA` chain for seamless question processing  .
-  * **Experiment Tracking:** Integrates **MLflow** to track key parameters (`chunk_size`, `chunk_overlap`, `session_id`) and log question/answer pairs along with source documents for model evaluation and future feedback  .
+    <p>Built with <strong>FastAPI</strong>, <strong>LangChain</strong>, <strong>Docker</strong>, and <strong>Google Gemini</strong>.</p>
 
-## Technology Stack
+    <h2> Features</h2>
+    <ul>
+        <li><strong>Agentic Routing</strong>: Uses an LLM to decide <em>where</em> to get information.</li>
+        <li><strong>Hybrid Tools</strong>:
+            <ul>
+                <li><code>lookup_internal_policy</code>: Searches local PDFs using FAISS + Embeddings.</li>
+                <li><code>search_web</code>: Searches DuckDuckGo for real-time info.</li>
+            </ul>
+        </li>
+        <li><strong>REST API</strong>: Fully documented API using FastAPI.</li>
+        <li><strong>Containerized</strong>: Docker support for easy deployment.</li>
+    </ul>
 
-| Component | Technology | Purpose |
-| :--- | :--- | :--- |
-| **Orchestration** | `LangChain` | Wires together the document processing, embedding, and LLM query steps  . |
-| **LLM/Embeddings** | `Gemini 1.5 Pro` / `GoogleGenerativeAIEmbeddings` | Generative AI model and state-of-the-art embedding generation. |
-| **Vector Database** | `FAISS (CPU)` | Efficient, in-memory index for fast similarity search during retrieval  . |
-| **Experimentation** | `MLflow` | Tracks document processing parameters and conversation history/metrics  . |
-| **Document Loaders**| `PyPDFLoader`, `UnstructuredWordDocumentLoader`, etc. | Handles ingestion of various file types  . |
+    <h2> Project Structure</h2>
+    <ul>
+        <li><code>src/rag_engine.py</code>: Handles PDF ingestion and Vector Database (FAISS).</li>
+        <li><code>src/agent.py</code>: Defines the Agent, Tools, and LangChain logic.</li>
+        <li><code>src/main.py</code>: The FastAPI server entry point.</li>
+        <li><code>data/</code>: Place your PDF documents here.</li>
+    </ul>
 
-##  RAG Pipeline Overview
+    <h2> Setup & Installation</h2>
 
-The system utilizes a standard RAG pattern to answer questions:
+    <h3>1. Prerequisites</h3>
+    <ul>
+        <li>Get a <a href="https://aistudio.google.com/">Free Google Gemini API Key</a>.</li>
+        <li>Create a <code>.env</code> file in this directory:
+            <pre><code>GOOGLE_API_KEY=AIzaSyD...your_key_here...</code></pre>
+        </li>
+    </ul>
 
-1.  **Ingestion & Chunking:** Documents are loaded and split into small, overlapping chunks (default 1,000 tokens, 200 overlap) using `RecursiveCharacterTextSplitter`.
-2.  **Embedding:** Each chunk is converted into a high-dimensional vector using **Google Generative AI Embeddings**.
-3.  **Vector Store:** The vectors are indexed in the **FAISS** library for efficient storage and retrieval.
-4.  **Retrieval:** At query time, the user's question is embedded and used to query FAISS for the Top-K (default $k=4$) most relevant document chunks.
-5.  **Generation:** The retrieved chunks are passed to the **Gemini 1.5 Pro** LLM along with a strict prompt instructing it to answer **only** based on the provided context, producing the final, grounded response.
+    <h3>2. Add Data</h3>
+    <p>Place your PDF file (e.g., policy documents, course materials) into the <code>data/</code> folder and rename it to <code>policy.pdf</code> (or update <code>src/agent.py</code> to match your filename).</p>
 
+    <h3>3. Run with Docker (Recommended)</h3>
+    <pre><code>docker build -t agentic-rag .
+docker run -p 8000:8000 --env-file .env agentic-rag</code></pre>
 
-### Prerequisites
+    <h3>4. Run Locally</h3>
+    <pre><code>pip install -r requirements.txt
+python src/main.py</code></pre>
 
-1.  **Python 3.8+**
-2.  A **Google API Key** for the Gemini models (set as an environment variable or passed to the `DocumentQASystem` class).
+    <h2> API Usage</h2>
+    <p><strong>Endpoint:</strong> <code>POST /chat</code></p>
 
-### Usage
+    <pre><code>{
+  "query": "What are the rules for termination in the policy?"
+}</code></pre>
 
-The core functionality is encapsulated in the `DocumentQASystem` class, which manages the entire RAG workflow.
+    <p><strong>Response:</strong></p>
+    <pre><code>{
+  "response": "According to the policy, termination requires...",
+  "steps": [
+    {
+      "tool": "lookup_internal_policy",
+      "tool_input": "termination rules"
+    }
+  ]
+}</code></pre>
 
-1.  **Initialize the System:**
-    ```python
-    qa_system = DocumentQASystem(api_key='YOUR_GEMINI_API_KEY')
-    ```
-2.  **Process Documents:** Place your documents (`.pdf`, `.txt`, `.docx`, `.csv`) in a directory and provide the file paths.
-    ```python
-    sample_files = ["./data/manual.pdf", "./data/report.docx"]
-    chunk_count = qa_system.process_documents(
-        file_paths=sample_files,
-        chunk_size=1000, 
-        chunk_overlap=200
-    )
-    print(f"Processed {chunk_count} document chunks.")
-    ```
-3.  **Ask Questions:**
-    ```python
-    result = qa_system.ask_question("Under what conditions can a treaty be terminated?")
-    print("Answer:", result["answer"])
-    print("Sources:", result["sources"])
-    ```
-### Contributing:
-Contributions are welcome! Please open issues or submit pull requests to suggest improvements or new features.
+</body>
+</html>

requirements.txt

@@ -0,0 +1,14 @@
+fastapi==0.109.2
+uvicorn==0.27.1
+python-dotenv==1.0.1
+langchain==0.1.9
+langchain-google-genai==0.0.9
+langchain-community==0.0.24
+faiss-cpu==1.7.4
+pypdf==4.0.2
+duckduckgo-search==4.3.1
+ragas==0.1.1
+datasets==2.17.1
+google-search-results
+pydantic==2.6.1
+requests

src/agent.py

@@ -0,0 +1,73 @@
+import os
+from langchain.agents import AgentExecutor, create_tool_calling_agent
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_core.tools import tool
+from langchain_community.tools import DuckDuckGoSearchRun
+from langchain import hub
+from dotenv import load_dotenv
+from src.rag_engine import KnowledgeBase
+
+load_dotenv()
+
+# --- Configuration ---
+PDF_PATH = os.path.join("data", "policy.pdf")
+
+# Initialize the RAG engine
+kb = KnowledgeBase(pdf_path=PDF_PATH)
+# Index documents on startup
+kb.load_and_index()
+
+# --- Define Tools ---
+
+@tool
+def lookup_internal_policy(query: str) -> str:
+    """
+    Useful for answering questions about specific internal policies, 
+    documents, laws, or the contents of the uploaded PDF file. 
+    ALWAYS use this tool first if the question implies looking up specific rules or documents.
+    """
+    return kb.retrieve(query)
+
+@tool
+def search_web(query: str) -> str:
+    """
+    Useful for finding current events, news, general knowledge, 
+    or information that is NOT contained in the internal policy documents.
+    """
+    search = DuckDuckGoSearchRun()
+    return search.run(query)
+
+# --- Initialize Agent ---
+
+def get_agent_executor():
+    """
+    Constructs the Agent with the Gemini LLM and the tools.
+    """
+    # 1. Setup the Gemini LLM
+    if not os.getenv("GOOGLE_API_KEY"):
+        raise ValueError("GOOGLE_API_KEY not found in environment variables")
+
+    llm = ChatGoogleGenerativeAI(
+        model="gemini-1.5-flash", # Or gemini-1.5-pro
+        temperature=0,
+        convert_system_message_to_human=True
+    )
+    
+    # 2. Define the Toolkit
+    tools = [lookup_internal_policy, search_web]
+    
+    # 3. Pull a standard prompt for Tool Calling from LangChain Hub
+    # This prompt tells the LLM: "You have these tools. Use them to answer."
+    prompt = hub.pull("hwchase17/openai-tools-agent")
+    
+    # 4. Construct the Agent
+    agent = create_tool_calling_agent(llm, tools, prompt)
+    
+    # 5. Create the Executor (Runtime)
+    agent_executor = AgentExecutor(
+        agent=agent, 
+        tools=tools, 
+        verbose=True, # Logs thoughts to console
+        return_intermediate_steps=True # Return the thought process
+    )
+    return agent_executor

src/main.py

@@ -0,0 +1,77 @@
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from src.agent import get_agent_executor
+import logging
+
+# Setup logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+app = FastAPI(
+    title="Agentic RAG Service",
+    description="An AI Microservice that routes between Internal Docs and Web Search.",
+    version="1.0"
+)
+
+# Initialize Agent Logic
+try:
+    agent_executor = get_agent_executor()
+except Exception as e:
+    logger.error(f"Failed to initialize agent: {e}")
+    agent_executor = None
+
+# --- API Models ---
+class QueryRequest(BaseModel):
+    query: str
+
+class StepInfo(BaseModel):
+    tool: str
+    tool_input: str
+
+class QueryResponse(BaseModel):
+    response: str
+    steps: list[StepInfo] = []
+
+# --- Routes ---
+
+@app.get("/")
+async def root():
+    return {
+        "status": "active", 
+        "service": "Agentic Knowledge Search", 
+        "docs_url": "/docs"
+    }
+
+@app.post("/chat", response_model=QueryResponse)
+async def chat(request: QueryRequest):
+    if not agent_executor:
+        raise HTTPException(status_code=500, detail="Agent not initialized (Check API Keys)")
+    
+    try:
+        logger.info(f"Received query: {request.query}")
+        
+        # Invoke the agent
+        result = agent_executor.invoke({"input": request.query})
+        
+        # Extract the 'Thought Process' (Intermediate Steps) to show the recruiter
+        # 'intermediate_steps' is a list of tuples: (AgentAction, Observation)
+        steps_data = []
+        if "intermediate_steps" in result:
+            for action, observation in result["intermediate_steps"]:
+                steps_data.append(StepInfo(
+                    tool=action.tool,
+                    tool_input=str(action.tool_input)
+                ))
+
+        return QueryResponse(
+            response=result["output"],
+            steps=steps_data
+        )
+        
+    except Exception as e:
+        logger.error(f"Error processing query: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

src/rag_engine.py

@@ -0,0 +1,56 @@
+import os
+from langchain_community.document_loaders import PyPDFLoader
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain_community.vectorstores import FAISS
+from langchain_google_genai import GoogleGenerativeAIEmbeddings
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+class KnowledgeBase:
+    """
+    Handles document loading, chunking, and vector storage.
+    """
+    def __init__(self, pdf_path: str):
+        self.pdf_path = pdf_path
+        self.vector_store = None
+        # Using Gemini Embeddings
+        self.embeddings = GoogleGenerativeAIEmbeddings(model="models/embedding-001")
+        
+    def load_and_index(self):
+        """
+        Loads the PDF, splits it into chunks, and builds the FAISS index.
+        """
+        if not os.path.exists(self.pdf_path):
+            print(f"⚠️ Warning: File not found at {self.pdf_path}. Internal search will be empty.")
+            return
+
+        print(f"📄 Loading PDF from: {self.pdf_path}...")
+        loader = PyPDFLoader(self.pdf_path)
+        docs = loader.load()
+        
+        print("✂️ Splitting text into chunks...")
+        text_splitter = RecursiveCharacterTextSplitter(
+            chunk_size=1000, 
+            chunk_overlap=200
+        )
+        chunks = text_splitter.split_documents(docs)
+        
+        print(f"💾 Indexing {len(chunks)} chunks into Vector Store...")
+        self.vector_store = FAISS.from_documents(chunks, self.embeddings)
+        print("✅ Indexing Complete.")
+
+    def retrieve(self, query: str, k: int = 4) -> str:
+        """
+        Retrieves the top-k most relevant text chunks for a query.
+        Returns a single string of context.
+        """
+        if not self.vector_store:
+            return "No internal documents have been indexed."
+            
+        docs = self.vector_store.similarity_search(query, k=k)
+        
+        # Combine the content of the retrieved docs
+        context = "\n\n".join([f"[Source: Page {d.metadata.get('page', '?')}] {d.page_content}" for d in docs])
+        return context

tests/evaluate.py

@@ -0,0 +1,72 @@
+import sys
+import os
+# Add project root to python path so we can import 'src'
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from ragas import evaluate
+from ragas.metrics import faithfulness, answer_relevance
+from datasets import Dataset
+from src.agent import get_agent_executor
+from langchain_google_genai import ChatGoogleGenerativeAI, GoogleGenerativeAIEmbeddings
+
+def run_evaluation():
+    print("🚀 Starting Evaluation Pipeline...")
+    agent = get_agent_executor()
+    
+    # 1. Define Test Data
+    # Questions that cover both Internal Docs and External Search
+    questions = [
+        "What are the specific conditions for treaty termination?", # Should use Internal Tool
+        "What is the current Prime Minister of the UK?",          # Should use Web Tool
+    ]
+    
+    # The 'Ground Truth' answers (what we expect)
+    ground_truths = [
+        ["Treaties can be terminated by consent of all parties, material breach, or fundamental change of circumstances."], 
+        ["Keir Starmer is the Prime Minister of the UK (as of late 2024)."] 
+    ]
+    
+    answers = []
+    contexts = [] 
+    
+    # 2. Run the Agent on the questions
+    for q in questions:
+        print(f"Testing Question: {q}")
+        try:
+            result = agent.invoke({"input": q})
+            answers.append(result["output"])
+            
+            # Extract retrieved context if available (simplified for this script)
+            # In a real scenario, we'd pull the actual text chunks from the tool output
+            contexts.append(["Context retrieved from agent tools..."]) 
+            
+        except Exception as e:
+            print(f"Error on question '{q}': {e}")
+            answers.append("Error")
+            contexts.append([""])
+
+    # 3. Create Ragas Dataset
+    data = {
+        "question": questions,
+        "answer": answers,
+        "contexts": contexts,
+        "ground_truth": ground_truths
+    }
+    dataset = Dataset.from_dict(data)
+    
+    # 4. Score it
+    # Note: Ragas metrics often require an LLM for judging. 
+    # Ensure your GOOGLE_API_KEY supports the models Ragas tries to call.
+    print("📊 Calculating Metrics (Faithfulness, Relevance)...")
+    
+    # Configure Ragas to use Gemini if OpenAI is not available
+    # (This part is complex in Ragas v0.1 without OpenAI, 
+    # so we print the raw results for the MVP if metrics fail)
+    print("Evaluation Results:")
+    for i, q in enumerate(questions):
+        print(f"Q: {q}")
+        print(f"A: {answers[i]}")
+        print("-" * 20)
+
+if __name__ == "__main__":
+    run_evaluation()