AnukulChandra/Mini-AI_Assistant

1 2---3title: Mini AI Assistant4emoji: 🤖5colorFrom: indigo6colorTo: purple7sdk: docker8app_port: 78609pinned: false10---11 12 13# Mini AI Assistant 🤖14 15A lightweight **RAG (Retrieval-Augmented Generation)** API built with FastAPI. Upload documents, ask questions, and get answers powered by your preferred LLM — all through a clean REST API.16 17---18 19## Overview 📋20 21Mini AI Assistant lets you:22 23- Upload PDF, TXT, and Markdown documents24- Automatically chunk and index them into a FAISS vector store25- Ask questions about the uploaded documents26- Retrieve the most relevant chunks and generate answers via an LLM27- Look up orders and products from local JSON files via smart tool routing28- Keep conversation history across turns29 30---31 32## Features ✨33 34| Feature | Description |35|---|---|36| **Document Ingestion** | Upload `.pdf`, `.txt`, or `.md` files — automatically validated, read, chunked, and indexed |37| **Vector Search** | FAISS-powered similarity search over document chunks |38| **Multi-Provider LLM** | Switch between OpenAI, Google Gemini, Hugging Face, and Groq via an environment variable |39| **RAG Pipeline** | Retrieves the most relevant context before generating answers |40| **Tool Routing** | Detects order IDs (`ORD-1001`) and product IDs (`PRD-1001`) in questions and returns structured JSON data |41| **Conversation Memory** | Remembers the last 10 question-answer pairs and includes them in context |42| **Error Handling** | Graceful error messages with proper HTTP status codes and logging |43 44---45 46## Architecture 🏗️47 48```mermaid49graph TD50    User -->|Question| Frontend51    Frontend -->|POST /chat/ask| FastAPI52    FastAPI --> Memory[Conversation Memory]53 54    Memory --> Intent[Intent Detection]55    Intent -->|Knowledge| FAISS[(FAISS Vector Store)]56    Intent -->|Order| Orders[(orders.json)]57    Intent -->|Product| Products[(products.json)]58    Intent -->|Direct| LLM[Groq LLM]59 60    FAISS --> Context[Retrieved Context + Memory + Tool Output]61    Orders --> Context62    Products --> Context63    Context --> Prompt[Prompt Builder]64 65    Prompt --> LLM66    LLM --> Response67    Response --> Frontend68```69 70**Document ingestion flow:** `POST /upload/document` → validate → read → split_text → create_vector_store → save to disk.71 72---73 74## AI Pipeline 🧠75 761. **User uploads a document** — Upload a PDF, TXT, or Markdown file via the frontend.772. **Document validation** — The file extension and content are validated against allowed types.783. **Text extraction** — Text is extracted from PDFs using PyPDF or read directly from plain-text files.794. **Chunking** — Extracted text is split into overlapping chunks using `RecursiveCharacterTextSplitter`.805. **Embedding generation** — Each chunk is converted into a vector embedding using `sentence-transformers/all-MiniLM-L6-v2`.816. **FAISS indexing** — Embeddings are indexed in a FAISS vector store and persisted to disk.827. **User asks a question** — The question is submitted through the chat interface.838. **Load conversation memory** — Previous question-answer pairs are loaded from in-memory history.849. **Intent detection** — The system classifies the question as Knowledge, Order, Product, or Direct LLM.8510. **Route to:**86    - **Knowledge Retrieval** — Perform similarity search over the FAISS index for relevant chunks.87    - **Order Tool** — Look up order status from `orders.json`.88    - **Product Tool** — Search product details in `products.json`.8911. **Build prompt** — Retrieved context, tool output, and conversation history are assembled into a structured prompt.9012. **Generate answer using Groq** — The prompt is sent to the Groq LLM (`llama-3.3-70b-versatile`) for response generation.9113. **Return response** — The answer is sent back to the frontend and displayed to the user.92 93---94 95## Prompt Design 📝96 97The system prompt instructs the assistant to answer only using the provided information. Conversation history is included when available so follow-up questions maintain context. Tool results (order status, product details) are injected directly into the response without querying the vector store.98 99- **Knowledge questions** — Retrieved document chunks are placed in the prompt as context. The assistant must answer from those chunks alone.100- **Memory questions** — Previous conversation turns are prepended so the assistant can reference past exchanges.101- **Tool queries** — The tool result is formatted into a natural-language answer and returned immediately without LLM generation.102 103If the answer cannot be found in the uploaded documents, the assistant replies:104 105> *"I couldn't find that information in the uploaded documents."*106 107---108 109## Screenshots 📸110 111| Interface | Preview |112|---|---|113| **Home Interface** | `![Home Interface](screenshots/home.png)` |114| **Upload Document** | `![Upload Document](screenshots/upload.png)` |115| **Chat Example** | `![Chat Example](screenshots/chat.png)` |116| **Order Tool** | `![Order Tool](screenshots/order-tool.png)` |117| **Product Tool** | `![Product Tool](screenshots/product-tool.png)` |118 119---120 121## Project Structure 📁122 123```124Mini-Ai-Assistant/125├── api/126│   ├── chat.py            # POST /chat/ask endpoint127│   └── upload.py          # POST /upload/document endpoint128├── services/129│   ├── chunking.py        # Text splitting130│   ├── embeddings.py      # HuggingFace embedding model131│   ├── ingestion.py       # File validation & text extraction132│   ├── llm.py             # Multi-provider LLM dispatch133│   ├── memory.py          # In-memory conversation history134│   ├── prompt_builder.py  # RAG prompt construction135│   ├── retrieval.py       # FAISS vector search136│   ├── tools.py           # Order/product lookup tools137│   └── vector_store.py    # FAISS create/save/load138├── data/139│   ├── orders.json        # Sample order data140│   ├── products.json      # Sample product data141│   └── vector_store/      # Persisted FAISS index142├── main.py                # FastAPI entry point143├── .env.example           # Environment template144├── requirements.txt       # Python dependencies145└── README.md              # This file146```147 148---149 150## Installation 🛠️151 152### Prerequisites153 154- Python 3.10+155- pip156 157### Steps158 159```bash160# Clone the repository161git clone https://github.com/Anukul-Chandra/Mini-Ai-Assistant.git162cd Mini-Ai-Assistant163 164# Create and activate a virtual environment165python -m venv .venv166source .venv/bin/activate    # Linux/macOS167.venv\Scripts\activate       # Windows168 169# Install dependencies170pip install -r requirements.txt171```172 173---174 175## Environment Variables 🔐176 177Copy `.env.example` to `.env` and fill in your API keys:178 179```bash180cp .env.example .env181```182 183| Variable | Description | Default |184|---|---|---|185| `LLM_PROVIDER` | Active LLM backend | `openai`, `gemini`, `huggingface`, or `groq` |186| `OPENAI_API_KEY` | OpenAI API key | — |187| `GEMINI_API_KEY` | Google Gemini API key | — |188| `GROQ_API_KEY` | Groq API key | — |189| `HF_API_KEY` | Hugging Face Inference API key | — |190| `HF_TOKEN` | Hugging Face token (for embedding model) | — |191 192> Set `LLM_PROVIDER` to your chosen backend. Only the corresponding API key is required — the rest can be left blank.193 194---195 196## Running the Project 🚀197 198```bash199uvicorn main:app --reload200```201 202The API will be available at **http://localhost:8000**.203 204Interactive API docs: **http://localhost:8000/docs** (Swagger UI)205 206---207 208## API Endpoints 📡209 210### `GET /`211 212Health check.213 214**Response:**215```json216{217  "message": "Mini AI Assistant API is running"218}219```220 221---222 223### `POST /upload/document`224 225Upload a document for indexing.226 227| Parameter | Type | Description |228|---|---|---|229| `file` | `multipart/form-data` | PDF, TXT, or Markdown file |230 231**Response `200`:**232```json233{234  "filename": "report.pdf",235  "chunks": 12,236  "message": "Document processed and indexed successfully."237}238```239 240**Response `400`:** Invalid file type or unreadable document.241 242---243 244### `POST /chat/ask`245 246Ask a question about your documents.247 248**Request:**249```json250{251  "question": "What is this document about?"252}253```254 255**Response `200` (RAG):**256```json257{258  "question": "What is this document about?",259  "answer": "The document discusses quarterly sales performance...",260  "retrieved_chunks": 3261}262```263 264**Response `200` (Tool):**265```json266{267  "source": "tool",268  "answer": {269    "order_id": "ORD-1001",270    "status": "shipped",271    "total": 245.99272  }273}274```275 276**Response `400`:** No document uploaded or LLM configuration error.277 278---279 280## Supported LLM Providers 🧠281 282| Provider | Env Value | Model | SDK |283|---|---|---|---|284| **OpenAI** | `openai` | `gpt-4o-mini` | `openai` |285| **Google Gemini** | `gemini` | `gemini-2.0-flash` | `google-generativeai` |286| **Hugging Face** | `huggingface` | `microsoft/Phi-3.5-mini-instruct` | `huggingface-hub` |287| **Groq** | `groq` | `llama-3.3-70b-versatile` | `groq` |288 289Switch between them by changing the `LLM_PROVIDER` environment variable.290 291---292 293## Example Requests 💻294 295### Upload a document296 297```bash298curl -X POST http://localhost:8000/upload/document \299  -F "file=@document.pdf"300```301 302### Ask a question (RAG)303 304```bash305curl -X POST http://localhost:8000/chat/ask \306  -H "Content-Type: application/json" \307  -d '{"question": "What are the key findings?"}'308```309 310### Ask about an order (tool routing)311 312```bash313curl -X POST http://localhost:8000/chat/ask \314  -H "Content-Type: application/json" \315  -d '{"question": "Show me order ORD-1001"}'316```317 318---319 320## Example Responses 📤321 322**RAG answer:**323```json324{325  "question": "What is the revenue for Q3?",326  "answer": "Based on the uploaded document, the revenue for Q3 was $1.2 million, representing a 15% increase over Q2.",327  "retrieved_chunks": 3328}329```330 331**Tool lookup:**332```json333{334  "source": "tool",335  "answer": {336    "order_id": "ORD-1001",337    "customer": "John Doe",338    "status": "delivered",339    "items": ["Laptop", "Mouse"],340    "total": 1249.99341  }342}343```344 345**Error:**346```json347{348  "detail": "No vector store found. Please upload a document first."349}350```351 352---353 354## Technology Stack 🛠️355 356| Category | Technology |357|---|---|358| **Framework** | FastAPI |359| **Server** | Uvicorn |360| **Embeddings** | sentence-transformers (`all-MiniLM-L6-v2`) |361| **Vector Store** | FAISS (CPU) |362| **PDF Parsing** | PyPDF |363| **LLM SDKs** | OpenAI, Google Generative AI, Hugging Face Hub, Groq |364| **Environment** | python-dotenv |365 366---367 368## Future Improvements 🚧369 370- [ ] Authentication and API key management371- [ ] Persistent conversation storage (SQLite / PostgreSQL)372- [ ] Multi-document upload and per-document scoping373- [ ] Streaming responses via Server-Sent Events374- [ ] Document deletion and re-indexing375- [ ] Evaluation metrics for RAG quality (faithfulness, relevance)376- [ ] Docker image for one-command deployment377 378---379 380## License 📄381 382This project is licensed under the MIT License.383