Readded Docs

Author: NEJANX

PROJECT_EXPLANATION.md

@@ -0,0 +1,49 @@
+# Project Explanation: Yuhasa History Tutor
+
+## Overview
+
+This project, "Yuhasa," is an intelligent chatbot designed to act as a history tutor. It leverages a technique called Retrieval-Augmented Generation (RAG) to answer user questions based specifically on the content of the provided "Grade 11 History Textbook" PDF. Instead of relying solely on its general knowledge, the chatbot first retrieves relevant passages from the textbook and then uses that information to generate a comprehensive and contextually accurate answer.
+
+## Core Goal
+
+The primary goal is to provide students with a tool to explore and understand their history textbook content interactively. Users can ask questions in natural language, and the chatbot will provide answers grounded in the specific information present in the document.
+
+## Key Processes and Components
+
+1.  **Data Ingestion and Processing (`pdf_chunker.py`, `faiss_store.py`):**
+    *   **Loading:** The system first reads the `grade-11-history-text-book.pdf`.
+    *   **Chunking:** The text content is broken down into smaller, manageable chunks (paragraphs or sections). This is crucial for effective retrieval.
+    *   **Embedding:** Each text chunk is converted into a numerical representation called an "embedding" using a machine learning model (likely via `gemini_utils.py` or a dedicated embedding model). Embeddings capture the semantic meaning of the text.
+    *   **Vector Store Creation:** These embeddings (vectors) and their corresponding text chunks are stored in a specialized database called a vector store. This project uses FAISS (`faiss_store.py`), which allows for very fast searching of similar vectors. The store consists of `faiss_index.index` (for the vectors) and `faiss_metadata.pkl` (linking vectors back to text and metadata). This step only needs to be done once unless the source PDF changes.
+
+2.  **User Interaction (Web: `web.py`, `templates/index.html`; CLI: `cli_chat.py`):**
+    *   Users can interact with the chatbot through either a web-based graphical interface or a simple command-line interface.
+    *   The user types a question (e.g., "What were the main causes of World War 1 according to the textbook?").
+
+3.  **Retrieval-Augmented Generation (RAG) Pipeline (`agents/` directory):**
+    *   **Query Analysis (`agents/query_analyzer.py`):** The user's query is analyzed using basic regex to extract keywords and entities.
+    *   **Query Embedding:** The user's question is also converted into an embedding using the same model as the document chunks.
+    *   **Retrieval (`agents/retriever.py`, `faiss_store.py`):** The system searches the FAISS vector store for the text chunks whose embeddings are most similar (closest in vector space) to the query embedding. These retrieved chunks are considered the most relevant context from the textbook.
+    *   **Context Expansion (`agents/context_expander.py` - potentially):** The retrieved context might be expanded or refined.
+    *   **Prompt Formulation:** A prompt is constructed for the generative AI model (Gemini). This prompt typically includes:
+        *   The original user question.
+        *   The relevant text chunks retrieved from the textbook (the "context").
+        *   The recent conversation history (to maintain context in multi-turn conversations).
+        *   Instructions for the AI (e.g., "Answer the user's question using *only* the provided context.").
+    *   **Generation (`agents/generator.py`, `gemini_utils.py`):** The constructed prompt is sent to the Google Gemini API. Gemini reads the prompt, understands the question and the provided context, and generates a natural language answer.
+    *   **Reference Tracking (`agents/reference_tracker.py` - potentially):** The system might track which parts of the retrieved context were used to generate the answer, potentially for citation purposes (though this isn't explicitly shown in the UI).
+    *   **Orchestration (`agents/orchestrator.py`):** This component manages the flow between the different agents (retriever, generator, etc.) ensuring they work together correctly.
+
+4.  **Response Delivery:**
+    *   The generated answer is sent back to the user interface (web or CLI) and displayed.
+    *   Conversation history is saved (`chats/` directory) to maintain context for future interactions within the same session.
+
+## Technology Stack
+
+*   **Language:** Python
+*   **Web Framework:** Flask (`web.py`)
+*   **Generative AI:** Google Gemini (`gemini_utils.py`)
+*   **Vector Store:** FAISS (`faiss_store.py`)
+*   **PDF Processing:** PyMuPDF (via `fitz` in `pdf_chunker.py`)
+*   **Frontend:** HTML, CSS, JavaScript (`templates/`, `static/`)
+*   **Core Dependencies:** `python-dotenv` (for environment variables), `numpy`.

README.md

@@ -1,11 +1,81 @@
-```bash
-pip3 install faiss-cpu google-generativeai python-dotenv fastapi uvicorn pydantic
-```
-
-## For Web UI
-```bash
-pip3 install flask
-```
-```bash
-python3 web.py
-```
+# Yuhasa - History Tutor Chatbot
+
+This project implements a Retrieval-Augmented Generation (RAG) chatbot focused on answering questions about a Grade 11 History textbook. It uses Google's Gemini AI for language understanding and generation, and FAISS for efficient information retrieval from the textbook content. The project intentionally uses minimal dependencies (Flask, FAISS, Gemini, PyPDF) for simplicity, speed, and maintainability.
+
+## Prerequisites
+
+*   **Python:** Version 3.10 or higher recommended.
+*   **pip:** Python package installer.
+*   **Google AI API Key:** You need an API key from Google AI Studio (or Google Cloud Vertex AI) for the Gemini models.
+*   **Git:** (Optional) If cloning the repository.
+
+## Setup
+
+1.  **Clone the Repository (if applicable):**
+    ```bash
+    git clone <repository-url>
+    cd <repository-directory>
+    ```
+
+2.  **Install Dependencies:**
+    It's recommended to use a virtual environment:
+    ```bash
+    python -m venv venv
+    # On Windows
+    .\venv\Scripts\activate
+    # On macOS/Linux
+    source venv/bin/activate
+
+    pip install -r requirements.txt
+    ```
+    *(Note: The `requirements.txt` file lists the necessary dependencies: `flask`, `google-generativeai`, `faiss-cpu`, `pypdf`, `python-dotenv`, `numpy`)*
+
+3.  **Configure API Key:**
+    *   Create a file named `.env` in the root project directory.
+    *   Add your Google AI API key to the `.env` file:
+        ```
+        GOOGLE_API_KEY=YOUR_API_KEY_HERE
+        ```
+    *   The `config.py` file likely loads this key.
+
+4.  **Process the PDF (if not already done):**
+    The project needs to process the `grade-11-history-text-book.pdf` into a vector store. There might be a script for this, or it might happen automatically on the first run. Check `main.py`, `embed_store.py`, or `pdf_chunker.py` for clues. If a specific script exists (e.g., `python embed_store.py`), run it:
+    ```bash
+    python faiss_store.py
+    ```
+    This will create the `faiss_index.index` and `faiss_metadata.pkl` files (or similar).
+
+## Running the Application
+
+There seem to be multiple ways to interact with the chatbot:
+
+1.  **Web Interface (Recommended):**
+    *   Run the Flask web server:
+        ```bash
+        python web.py
+        ```
+    *   Open your web browser and navigate to the address provided (usually `http://127.0.0.1:5000` or similar).
+
+2.  **Command-Line Interface:**
+    *   Run the CLI script:
+        ```bash
+        python cli_chat.py
+        ```
+    *   Interact with the bot directly in your terminal. Type 'exit' or 'quit' to end the session.
+
+## Project Structure Overview
+
+*   `web.py`: Runs the Flask web server for the GUI.
+*   `cli_chat.py`: Provides a command-line interface.
+*   `config.py`: Handles configuration (like API keys).
+*   `faiss_store.py`: Manages the creation and querying of the FAISS vector store.
+*   `gemini_utils.py`: Contains helper functions for interacting with the Gemini API.
+*   `pdf_chunker.py`: Responsible for reading and splitting the PDF document.
+*   `agents/`: Directory containing different components (agents) of the RAG pipeline (Retriever, Generator, Orchestrator, etc.).
+*   `templates/index.html`: The HTML structure for the web interface.
+*   `chats/`: Stores conversation history (JSON files).
+*   `grade-11-history-text-book.pdf`: The source document.
+*   `faiss_index.index`, `faiss_metadata.pkl`: The generated vector store files.
+*   `requirements.txt`: Lists the project dependencies.
+*   `README.md`: This file.
+*   `PROJECT_EXPLANATION.md`: Detailed explanation of the project architecture.

requirements.txt

@@ -0,0 +1,7 @@
+flask
+google-generativeai
+faiss-cpu
+pypdf
+python-dotenv
+numpy
+gtts