implementation_plan.md

# Implementation Plan - RAG Web Application with LangChain & OpenRouter `owl-alpha`

Create a beautiful, fully functional Retrieval-Augmented Generation (RAG) web application using FastAPI, LangChain, and OpenRouter's `owl-alpha` model. The application will allow users to upload files (PDF, TXT, MD), scrape URLs, or paste text, embed and store them in an in-memory vector store, and chat with their knowledge base in real-time with citation inspection.

## User Review Required

> [!IMPORTANT]
> - **API Key:** We will set up the project configuration using the provided API key (`YOUR_OPENROUTER_API_KEY`) stored in a local `.env` file.
> - **Vector Database Persistence:** We are proposing using LangChain's `InMemoryVectorStore` serialized as a pickle file on disk (`data/vectorstore.pkl`). This removes external binary dependencies like C++ compilers for FAISS or SQLite configurations for Chroma, making it 100% reliable and fast on Windows.
> - **Embeddings Model:** We will use `openai/text-embedding-3-small` via OpenRouter to generate embeddings, which uses the same API key and doesn't require downloading heavy PyTorch/SentenceTransformers models (~500MB+) locally.

## Proposed Changes

We will create a new Python application inside `e:\Projects\Normal Rag`.

### Root Folder

#### [NEW] [requirements.txt](file:///e:/Projects/Normal%20Rag/requirements.txt)
List python package dependencies required for the project:
- `fastapi` & `uvicorn` (backend server)
- `python-dotenv` (environment configuration)
- `httpx` & `beautifulsoup4` (web scraping)
- `langchain` & `langchain-community` & `langchain-openai` (RAG orchestration and OpenAI API-compatible connection to OpenRouter)
- `pypdf` (pure-python PDF reader for file uploads)

#### [NEW] [.env](file:///e:/Projects/Normal%20Rag/.env)
Store configuration values:
- `OPENROUTER_API_KEY=YOUR_OPENROUTER_API_KEY`
- `OPENROUTER_MODEL=openrouter/owl-alpha`
- `EMBEDDING_MODEL=openai/text-embedding-3-small`
- `OPENROUTER_BASE_URL=https://openrouter.ai/api/v1`

#### [NEW] [.gitignore](file:///e:/Projects/Normal%20Rag/.gitignore)
Ignore environment configurations and local database files:
- `.env`
- `data/`
- `__pycache__/`

---

### Backend Service (App)

#### [NEW] [rag.py](file:///e:/Projects/Normal%20Rag/app/rag.py)
Implements all RAG logic using LangChain:
- **`RAGManager` class:**
  - Initializes LLM (`ChatOpenAI` pointing to OpenRouter's API endpoint).
  - Initializes Embeddings (`OpenAIEmbeddings` pointing to OpenRouter's API endpoint).
  - Loads/Saves the `InMemoryVectorStore` to `data/vectorstore.pkl`.
  - Parses uploaded files (handles TXT, MD, PDF via `pypdf`).
  - Scrapes URLs (fetches web pages and extracts visible text content).
  - Splitting text into semantic chunks using `RecursiveCharacterTextSplitter`.
  - Adding documents to the vector store and rebuilding indexing metadata (document title, chunk count, characters).
  - Performing similarity search and compiling a prompt with context.
  - Streaming LLM completions for chat queries with source citations.

#### [NEW] [main.py](file:///e:/Projects/Normal%20Rag/app/main.py)
FastAPI routes and SSE streaming configuration:
- `GET /` - Serves the main UI index.html.
- `GET /api/status` - Returns API connection state and database source list.
- `POST /api/upload/file` - Upload file route.
- `POST /api/upload/url` - Scrape URL route.
- `POST /api/upload/text` - Direct text entry route.
- `POST /api/chat` - Chat route streaming responses using FastAPI `StreamingResponse` (Server-Sent Events) with retrieved sources prepended or appended in the stream metadata.
- `DELETE /api/reset` - Clears the database and resets files.

---

### Frontend Service (UI)

#### [NEW] [index.html](file:///e:/Projects/Normal%20Rag/app/templates/index.html)
A premium, dark-themed, glassmorphic single-page web app layout:
- **Design:**
  - Modern fonts (Inter/Outfit), HSL gradients, glassmorphism (`backdrop-filter`).
  - Sleek sliding drawer/settings overlay for RAG chunk sizes, model parameters, custom system prompt.
- **Sidebar features:**
  - Status display ("Connected to OpenRouter / owl-alpha").
  - Upload widgets (Drag & drop file upload, URL scraper input, text paste box).
  - List of currently indexed documents with size, chunk count, and deletion actions.
- **Chat window:**
  - Clean typing bubbles with streaming text, scrolling down automatically.
  - Collapsible **"Source Citations"** widget for assistant responses. Hovering/clicking on a source highlights the match and opens a detailed modal showing the full chunk text and similarity score.
  - Glowing active border on inputs and actions.

## Verification Plan

### Automated/Manual Backend Verification
1. **Dependency Installation:** Run `pip install -r requirements.txt` to verify packages install smoothly on Windows.
2. **Key Check:** Run a quick health check validation logic.
3. **Database Check:** Test document parser with TXT and PDF uploads, confirming it splits text, embeds it, and writes the `data/vectorstore.pkl` database successfully.
4. **Scraper Check:** Test URL scraping with a public webpage (e.g. `https://example.com`), ensuring text is parsed correctly.
5. **Chat Check:** Run queries to check retrieved chunks and streaming completions.

### Manual Frontend Verification
1. Start the FastAPI development server: `uvicorn app.main:app --reload`
2. Open `http://localhost:8000` in the browser.
3. Upload a sample document and check if it appears in the sidebar list.
4. Scrape a URL and verify it indexes.
5. Ask questions relevant to the uploaded documents/URLs, check if the response streams in, and check if retrieved source citations are displayed.