NotStuck: AI-Powered Document Assistant

---

Overview

NotStuck is a production-ready, AI-powered RAG (Retrieval-Augmented Generation) system that helps you extract insights from your documents using cutting-edge AI models. Upload documents (PDF, DOCX, TXT), ask questions, and receive intelligent answers powered by CrewAI agents, vector search, and your choice of 10+ LLM models through OpenRouter.

Intelligent Multi-Agent RAG System: NotStuck combines CrewAI-powered intelligent routing, Pinecone vector search, streaming responses, and multi-model LLM support (GPT-4, Claude, Gemini, Llama, and more) to deliver highly accurate, context-aware answers. Agents automatically decide whether to use the knowledge base, search the web, or answer directly from their knowledge.

Quick Start with Docker 🐳

# 1. Clone the repository
git clone https://github.com/praneethravuri/notstuck.git
cd notstuck

# 2. Create backend/.env with your API keys
cat > backend/.env << EOF
OPENROUTER_API_KEY=your_openrouter_key
OPENAI_API_KEY=your_openai_key
PINECONE_API_KEY=your_pinecone_key
PINECONE_INDEX_NAME=notstuck-index
PINECONE_ENV=us-east-1
EMBEDDING_DIMENSION=1024
EOF

# 3. Start with Docker Compose
docker-compose up --build

# 4. Open http://localhost:3000

That's it! 🎉 Upload documents and start asking questions.

---

Key Features

🚀 Multi-Model LLM Support

• Choose from 10+ AI models via OpenRouter: GPT-4o, Claude 3.5, Gemini Pro, Llama 3.1, Mistral, and more
• Dynamic model selection in the UI
• Model-specific optimizations for different use cases

🤖 Intelligent AI Agents

• CrewAI-powered multi-agent system
• Agents decide when to use knowledge base vs. web search
• General knowledge questions answered directly
• Document-specific queries use RAG pipeline
• Current information retrieved via web search with source URLs

📄 Smart Document Processing

• Semantic-aware chunking with configurable overlap (1000 chars, 200 overlap)
• Automatic text cleaning removes unicode, escape characters, and artifacts
• Original filename preservation in metadata
• Temporary file processing - no local storage required
• Batch embedding generation for efficiency

🔍 Advanced Search & Retrieval

• Dense embeddings (OpenAI text-embedding-3-large, 1024 dimensions)
• Pinecone vector database with dotproduct metric
• Context optimization with deduplication
• Web search integration with DuckDuckGo (includes source URLs)

⚡ Production-Ready Features

• Docker & Docker Compose support for easy deployment
• Streaming responses for real-time answer generation
• Health checks and automatic restarts
• Full Pydantic validation for all API endpoints
• Auto database reset on startup
• Type-safe throughout the entire pipeline

💎 Developer Experience

• Interactive API docs at /docs
• Clean, modular architecture
• uv for fast dependency management
• Hot reload for rapid development
• Windows console UTF-8 support for emoji logs

---

Tech Stack

Backend

• FastAPI - High-performance async API framework
• CrewAI - Multi-agent AI framework
• Pydantic - Data validation and settings management
• Pinecone - Vector database with cosine similarity
• OpenRouter - Unified API for 10+ LLM providers
• OpenAI Embeddings - text-embedding-3-large (1024 dimensions)
• PyPDF - PDF text extraction
• BeautifulSoup4 - HTML parsing for web search
• uv - Ultra-fast Python package manager

Frontend

• Next.js 15 - React framework with Turbopack
• TypeScript - Type-safe JavaScript
• Tailwind CSS - Utility-first CSS framework
• Shadcn/ui - Re-usable component library
• Axios - HTTP client for API calls

Development Tools

• Concurrently - Run multiple dev servers
• Pytest - Python testing framework
• NLTK - Natural language processing

---

Architecture

Complete System Architecture

┌─────────────────────────────────────────────────────────────┐
│                    1. DOCUMENT UPLOAD                        │
│  User uploads file → Frontend → Backend API → Temp storage  │
│  Supported: PDF, DOCX, TXT                                  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                 2. DOCUMENT PROCESSING                       │
│  ├─ Text extraction (PyPDF, python-docx)                   │
│  ├─ Unicode & escape character cleaning                    │
│  ├─ Semantic chunking (1000 chars, 200 overlap)           │
│  └─ Original filename preservation in metadata             │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   3. EMBEDDING GENERATION                    │
│  ├─ OpenAI text-embedding-3-large (1024 dims)              │
│  ├─ Batch processing (100 vectors per batch)               │
│  └─ Metadata: text, source_file, chunk_index               │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                  4. PINECONE VECTOR STORAGE                  │
│  ├─ Upsert vectors with metadata                           │
│  ├─ Dotproduct metric                                       │
│  ├─ 1024-dimensional vectors                                │
│  └─ Auto file cleanup after processing                     │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                      5. USER QUERY                           │
│  User asks question → Model selection → CrewAI Agent        │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                  6. CREWAI AGENT ROUTING                     │
│  Agent analyzes question and decides:                       │
│  ├─ General knowledge? → Direct answer                     │
│  ├─ Document-related? → Pinecone Search Tool               │
│  └─ Current info needed? → Web Search Tool                 │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│           7A. PINECONE SEARCH (if document query)            │
│  ├─ Generate query embedding (1024 dims)                   │
│  ├─ Search Pinecone (top_k=5)                               │
│  ├─ Return context with source metadata                    │
│  └─ Agent constructs answer with citations                 │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│           7B. WEB SEARCH (if current info needed)            │
│  ├─ DuckDuckGo search via BeautifulSoup                    │
│  ├─ Extract: Title, URL, Snippet                            │
│  ├─ Return formatted results with URLs                     │
│  └─ Agent constructs answer with web sources               │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   8. LLM GENERATION                          │
│  ├─ CrewAI calls OpenRouter with selected model            │
│  ├─ Model: GPT-4o, Claude 3.5, Gemini, Llama, etc.        │
│  ├─ Context: Knowledge base or web search results          │
│  └─ Generate comprehensive answer                          │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│               9. STREAMING RESPONSE (SSE)                    │
│  ├─ Send sources first (document or web)                   │
│  ├─ Stream answer in chunks (50 chars each)               │
│  ├─ Real-time display in frontend                          │
│  └─ Send completion signal when done                       │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   10. FRONTEND DISPLAY                       │
│  ├─ Render streaming answer in real-time                   │
│  ├─ Display sources (documents or web URLs)                │
│  └─ User sees complete answer with citations               │
└─────────────────────────────────────────────────────────────┘

---

Installation and Setup

1. Prerequisites

Option A: Docker (Recommended)

• Docker and Docker Compose installed
• Pinecone API Key - Sign up and create an index (1024 dimensions, dotproduct metric)
• OpenRouter API Key - Sign up and add credits
• OpenAI API Key - For embeddings

Option B: Local Development

• Python 3.11+
• Node.js 20+
• Pinecone API Key - Sign up and create an index (1024 dimensions, dotproduct metric)
• OpenRouter API Key - Sign up and add credits
• OpenAI API Key - For embeddings

2. Clone the Repository

git clone https://github.com/praneethravuri/notstuck.git
cd notstuck

3. Environment Configuration

Create a backend/.env file with your API keys:

# OpenRouter Configuration (for LLM models)
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

# OpenAI Configuration (for embeddings)
OPENAI_API_KEY=your_openai_api_key_here

# Pinecone Configuration
PINECONE_API_KEY=your_pinecone_api_key_here
PINECONE_ENV=us-east-1
PINECONE_INDEX_NAME=notstuck-index

# Model Configuration (optional - can be changed in UI)
DEFAULT_LLM_MODEL=openai/gpt-4o
DEFAULT_EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_DIMENSION=1024

Create a frontend/.env.local file:

NEXT_PUBLIC_BACKEND_URL=http://localhost:8000

Note: A .env.example file is provided at the root for reference. Never commit your .env files.

4. Installation & Running

🐳 Option A: Docker (Recommended)

The easiest way to run NotStuck is using Docker Compose:

# Build and start all services
docker-compose up --build

# Or run in detached mode
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop services
docker-compose down

What happens:

• ✅ Backend starts on `http: