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

• 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

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

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

Ignore environment configurations and local database files:

• .env
• data/
• __pycache__/

---

Backend Service (App)

[NEW] 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

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

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.