{"id":25233481,"url":"https://github.com/praneethravuri/notstuck","last_synced_at":"2026-04-13T21:01:46.366Z","repository":{"id":276062041,"uuid":"928017698","full_name":"praneethravuri/notstuck","owner":"praneethravuri","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-31T23:16:16.000Z","size":6395,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-01T00:23:26.679Z","etag":null,"topics":["chatbot","chatgpt","llm","openai","pineconedb","python","question-answering","react","vector-database"],"latest_commit_sha":null,"homepage":"https://notstuck.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/praneethravuri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-05T23:19:46.000Z","updated_at":"2025-03-31T23:16:20.000Z","dependencies_parsed_at":"2025-03-06T08:19:33.615Z","dependency_job_id":"8b2b68c7-9cda-46ed-8b15-91af9dfc0b74","html_url":"https://github.com/praneethravuri/notstuck","commit_stats":null,"previous_names":["praneethravuri/notstuck"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/praneethravuri%2Fnotstuck","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/praneethravuri%2Fnotstuck/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/praneethravuri%2Fnotstuck/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/praneethravuri%2Fnotstuck/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/praneethravuri","download_url":"https://codeload.github.com/praneethravuri/notstuck/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369953,"owners_count":20927928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","chatgpt","llm","openai","pineconedb","python","question-answering","react","vector-database"],"created_at":"2025-02-11T13:57:01.971Z","updated_at":"2026-04-13T21:01:46.358Z","avatar_url":"https://github.com/praneethravuri.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NotStuck: AI-Powered Document Assistant\n\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/) [![FastAPI](https://img.shields.io/badge/FastAPI-Latest-green.svg)](https://fastapi.tiangolo.com/) [![Next.js](https://img.shields.io/badge/Next.js-15.1.6-blue.svg)](https://nextjs.org/) [![Pinecone](https://img.shields.io/badge/Pinecone-Vector%20DB-orange.svg)](https://www.pinecone.io/) [![CrewAI](https://img.shields.io/badge/CrewAI-Multi--Agent-purple.svg)](https://www.crewai.com/) [![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)\n\n---\n\n## Overview\n\n**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.\n\n\u003e **Intelligent Multi-Agent RAG System:**\n\u003e 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.\n\n## Quick Start with Docker 🐳\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/praneethravuri/notstuck.git\ncd notstuck\n\n# 2. Create backend/.env with your API keys\ncat \u003e backend/.env \u003c\u003c EOF\nOPENROUTER_API_KEY=your_openrouter_key\nOPENAI_API_KEY=your_openai_key\nPINECONE_API_KEY=your_pinecone_key\nPINECONE_INDEX_NAME=notstuck-index\nPINECONE_ENV=us-east-1\nEMBEDDING_DIMENSION=1024\nEOF\n\n# 3. Start with Docker Compose\ndocker-compose up --build\n\n# 4. Open http://localhost:3000\n```\n\nThat's it! 🎉 Upload documents and start asking questions.\n\n---\n\n## Key Features\n\n### 🚀 **Multi-Model LLM Support**\n- Choose from **10+ AI models** via OpenRouter: GPT-4o, Claude 3.5, Gemini Pro, Llama 3.1, Mistral, and more\n- Dynamic model selection in the UI\n- Model-specific optimizations for different use cases\n\n### 🤖 **Intelligent AI Agents**\n- **CrewAI-powered** multi-agent system\n- Agents decide when to use knowledge base vs. web search\n- General knowledge questions answered directly\n- Document-specific queries use RAG pipeline\n- Current information retrieved via web search with source URLs\n\n### 📄 **Smart Document Processing**\n- **Semantic-aware chunking** with configurable overlap (1000 chars, 200 overlap)\n- **Automatic text cleaning** removes unicode, escape characters, and artifacts\n- **Original filename preservation** in metadata\n- **Temporary file processing** - no local storage required\n- **Batch embedding generation** for efficiency\n\n### 🔍 **Advanced Search \u0026 Retrieval**\n- **Dense embeddings** (OpenAI text-embedding-3-large, 1024 dimensions)\n- **Pinecone vector database** with dotproduct metric\n- **Context optimization** with deduplication\n- **Web search integration** with DuckDuckGo (includes source URLs)\n\n### ⚡ **Production-Ready Features**\n- **Docker \u0026 Docker Compose** support for easy deployment\n- **Streaming responses** for real-time answer generation\n- **Health checks** and automatic restarts\n- **Full Pydantic validation** for all API endpoints\n- **Auto database reset** on startup\n- **Type-safe** throughout the entire pipeline\n\n### 💎 **Developer Experience**\n- **Interactive API docs** at `/docs`\n- **Clean, modular architecture**\n- **uv** for fast dependency management\n- **Hot reload** for rapid development\n- **Windows console UTF-8** support for emoji logs\n\n---\n\n## Tech Stack\n\n### **Backend**\n- **[FastAPI](https://fastapi.tiangolo.com/)** - High-performance async API framework\n- **[CrewAI](https://www.crewai.com/)** - Multi-agent AI framework\n- **[Pydantic](https://pydantic.dev/)** - Data validation and settings management\n- **[Pinecone](https://www.pinecone.io/)** - Vector database with cosine similarity\n- **[OpenRouter](https://openrouter.ai/)** - Unified API for 10+ LLM providers\n- **[OpenAI Embeddings](https://platform.openai.com/docs/guides/embeddings)** - text-embedding-3-large (1024 dimensions)\n- **[PyPDF](https://pypdf.readthedocs.io/)** - PDF text extraction\n- **[BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/)** - HTML parsing for web search\n- **[uv](https://github.com/astral-sh/uv)** - Ultra-fast Python package manager\n\n### **Frontend**\n- **[Next.js 15](https://nextjs.org/)** - React framework with Turbopack\n- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript\n- **[Tailwind CSS](https://tailwindcss.com/)** - Utility-first CSS framework\n- **[Shadcn/ui](https://ui.shadcn.com/)** - Re-usable component library\n- **[Axios](https://axios-http.com/)** - HTTP client for API calls\n\n### **Development Tools**\n- **[Concurrently](https://www.npmjs.com/package/concurrently)** - Run multiple dev servers\n- **[Pytest](https://pytest.org/)** - Python testing framework\n- **[NLTK](https://www.nltk.org/)** - Natural language processing\n\n---\n\n## Architecture\n\n### **Complete System Architecture**\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                    1. DOCUMENT UPLOAD                        │\n│  User uploads file → Frontend → Backend API → Temp storage  │\n│  Supported: PDF, DOCX, TXT                                  │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│                 2. DOCUMENT PROCESSING                       │\n│  ├─ Text extraction (PyPDF, python-docx)                   │\n│  ├─ Unicode \u0026 escape character cleaning                    │\n│  ├─ Semantic chunking (1000 chars, 200 overlap)           │\n│  └─ Original filename preservation in metadata             │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│                   3. EMBEDDING GENERATION                    │\n│  ├─ OpenAI text-embedding-3-large (1024 dims)              │\n│  ├─ Batch processing (100 vectors per batch)               │\n│  └─ Metadata: text, source_file, chunk_index               │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│                  4. PINECONE VECTOR STORAGE                  │\n│  ├─ Upsert vectors with metadata                           │\n│  ├─ Dotproduct metric                                       │\n│  ├─ 1024-dimensional vectors                                │\n│  └─ Auto file cleanup after processing                     │\n└─────────────────────────────────────────────────────────────┘\n\n┌─────────────────────────────────────────────────────────────┐\n│                      5. USER QUERY                           │\n│  User asks question → Model selection → CrewAI Agent        │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│                  6. CREWAI AGENT ROUTING                     │\n│  Agent analyzes question and decides:                       │\n│  ├─ General knowledge? → Direct answer                     │\n│  ├─ Document-related? → Pinecone Search Tool               │\n│  └─ Current info needed? → Web Search Tool                 │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│           7A. PINECONE SEARCH (if document query)            │\n│  ├─ Generate query embedding (1024 dims)                   │\n│  ├─ Search Pinecone (top_k=5)                               │\n│  ├─ Return context with source metadata                    │\n│  └─ Agent constructs answer with citations                 │\n└─────────────────────────────────────────────────────────────┘\n\n┌─────────────────────────────────────────────────────────────┐\n│           7B. WEB SEARCH (if current info needed)            │\n│  ├─ DuckDuckGo search via BeautifulSoup                    │\n│  ├─ Extract: Title, URL, Snippet                            │\n│  ├─ Return formatted results with URLs                     │\n│  └─ Agent constructs answer with web sources               │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│                   8. LLM GENERATION                          │\n│  ├─ CrewAI calls OpenRouter with selected model            │\n│  ├─ Model: GPT-4o, Claude 3.5, Gemini, Llama, etc.        │\n│  ├─ Context: Knowledge base or web search results          │\n│  └─ Generate comprehensive answer                          │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│               9. STREAMING RESPONSE (SSE)                    │\n│  ├─ Send sources first (document or web)                   │\n│  ├─ Stream answer in chunks (50 chars each)               │\n│  ├─ Real-time display in frontend                          │\n│  └─ Send completion signal when done                       │\n└─────────────────────────────────────────────────────────────┘\n                              ↓\n┌─────────────────────────────────────────────────────────────┐\n│                   10. FRONTEND DISPLAY                       │\n│  ├─ Render streaming answer in real-time                   │\n│  ├─ Display sources (documents or web URLs)                │\n│  └─ User sees complete answer with citations               │\n└─────────────────────────────────────────────────────────────┘\n```\n\n\n---\n\n## Installation and Setup\n\n### 1. Prerequisites\n\n#### **Option A: Docker (Recommended)**\n- **Docker** and **Docker Compose** installed\n- **Pinecone API Key** - [Sign up](https://www.pinecone.io/) and create an index (1024 dimensions, dotproduct metric)\n- **OpenRouter API Key** - [Sign up](https://openrouter.ai/) and add credits\n- **OpenAI API Key** - For embeddings\n\n#### **Option B: Local Development**\n- **Python 3.11+**\n- **Node.js 20+**\n- **Pinecone API Key** - [Sign up](https://www.pinecone.io/) and create an index (1024 dimensions, dotproduct metric)\n- **OpenRouter API Key** - [Sign up](https://openrouter.ai/) and add credits\n- **OpenAI API Key** - For embeddings\n\n### 2. Clone the Repository\n\n```bash\ngit clone https://github.com/praneethravuri/notstuck.git\ncd notstuck\n```\n\n### 3. Environment Configuration\n\nCreate a `backend/.env` file with your API keys:\n\n```bash\n# OpenRouter Configuration (for LLM models)\nOPENROUTER_API_KEY=your_openrouter_api_key_here\nOPENROUTER_BASE_URL=https://openrouter.ai/api/v1\n\n# OpenAI Configuration (for embeddings)\nOPENAI_API_KEY=your_openai_api_key_here\n\n# Pinecone Configuration\nPINECONE_API_KEY=your_pinecone_api_key_here\nPINECONE_ENV=us-east-1\nPINECONE_INDEX_NAME=notstuck-index\n\n# Model Configuration (optional - can be changed in UI)\nDEFAULT_LLM_MODEL=openai/gpt-4o\nDEFAULT_EMBEDDING_MODEL=text-embedding-3-large\nEMBEDDING_DIMENSION=1024\n```\n\nCreate a `frontend/.env.local` file:\n\n```bash\nNEXT_PUBLIC_BACKEND_URL=http://localhost:8000\n```\n\n\u003e **Note**: A `.env.example` file is provided at the root for reference. Never commit your `.env` files.\n\n### 4. Installation \u0026 Running\n\n#### **🐳 Option A: Docker (Recommended)**\n\nThe easiest way to run NotStuck is using Docker Compose:\n\n```bash\n# Build and start all services\ndocker-compose up --build\n\n# Or run in detached mode\ndocker-compose up -d --build\n\n# View logs\ndocker-compose logs -f\n\n# Stop services\ndocker-compose down\n```\n\n**What happens:**\n- ✅ Backend starts on `http://localhost:8000`\n- ✅ Frontend starts on `http://localhost:3000`\n- ✅ Automatic health checks and restart policies\n- ✅ Isolated network for service communication\n- ✅ Pinecone database is reset on backend startup\n\nVisit `http://localhost:3000` to start using NotStuck!\n\n**Docker Commands:**\n```bash\n# Rebuild specific service\ndocker-compose build backend\ndocker-compose build frontend\n\n# View service logs\ndocker-compose logs -f backend\ndocker-compose logs -f frontend\n\n# Restart services\ndocker-compose restart\n\n# Stop and remove containers\ndocker-compose down\n\n# Stop and remove containers + volumes\ndocker-compose down -v\n```\n\n#### **💻 Option B: Local Development (Without Docker)**\n\nFor local development with hot reload:\n\n```bash\n# Install root dependencies (concurrently)\nnpm install\n\n# Install frontend dependencies\ncd frontend \u0026\u0026 npm install \u0026\u0026 cd ..\n\n# Install backend dependencies (using uv - ultra fast!)\ncd backend \u0026\u0026 uv sync \u0026\u0026 cd ..\n\n# Run both backend and frontend\nnpm run dev\n```\n\nThis will:\n- Start **backend first** on `http://localhost:8000`\n- Then start **frontend** on `http://localhost:3000`\n- Auto-reload both on file changes\n\n**Individual Services:**\n\n- **Backend only:**\n  ```bash\n  npm run dev:backend\n  # or manually: cd backend \u0026\u0026 uv run uvicorn backend.api.main:app --reload\n  ```\n\n- **Frontend only:**\n  ```bash\n  npm run dev:frontend\n  # or manually: cd frontend \u0026\u0026 npm run dev\n  ```\n\n#### **First Time Setup**\n\nWhen you first run the backend (both Docker and local):\n- ✅ Pinecone database is **automatically reset** on startup\n- ✅ Required directories are created\n- ✅ API connections are validated\n- ✅ Health check endpoint available at `/health`\n\nVisit `http://localhost:3000` in your browser to start using NotStuck!\n\n---\n\n## Usage\n\n### **1. Select Your AI Model**\n- Click the model selector in the header\n- Choose from 10+ models (GPT-4o, Claude 3.5, Gemini Pro, Llama 3.1, etc.)\n- Model selection affects all subsequent queries\n\n### **2. Upload Documents**\n- Click the paperclip icon or drag \u0026 drop files\n- Supported formats: **PDF**, **DOCX**, **TXT**\n- Files are processed with:\n  - ✅ Text extraction (PyPDF, python-docx)\n  - ✅ **Unicode and escape character cleaning**\n  - ✅ **Original filename preservation**\n  - ✅ Semantic chunking (1000 chars, 200 overlap)\n  - ✅ Embedding generation (1024 dimensions)\n  - ✅ Pinecone vector storage\n- **No files saved locally** - uses temporary storage only\n- **Automatic deletion** after processing\n\n### **3. Ask Questions**\n- Type your question in the chat input\n- Press Enter or click Send\n- **Streaming response** displays answer in real-time\n\n**How the agent decides:**\n- **General knowledge** (e.g., \"What is photosynthesis?\") → Direct answer from agent\n- **Document questions** (e.g., \"What does my resume say?\") → Searches Pinecone knowledge base\n- **Current info** (e.g., \"Latest AI news?\") → Web search with DuckDuckGo\n\nBackend processing:\n  - ✅ Intelligent routing (knowledge base / web / general)\n  - ✅ Vector search with Pinecone (if document-related)\n  - ✅ Web search with URLs (if current info needed)\n  - ✅ Context optimization\n  - ✅ LLM generation with streaming\n\n### **4. View Sources**\n- **Document sources**: Filename, chunk index, and extracted text\n- **Web sources**: Title, URL, and snippet from search results\n- Sources appear in the response for transparency\n\n---\n\n## API Documentation\n\nInteractive API documentation is available when running the backend:\n\n- **Swagger UI:** `http://localhost:8000/docs`\n- **ReDoc:** `http://localhost:8000/redoc`\n\n### **Key Endpoints**\n\n```\nGET    /                        - Root endpoint with API info\nGET    /health                  - Health check endpoint\nGET    /docs                    - Interactive Swagger UI\nGET    /redoc                   - ReDoc API documentation\n\nGET    /api/models              - List available AI models\nPOST   /api/ask                 - Ask a question (streaming SSE)\nPOST   /api/upload              - Upload documents (PDF, DOCX, TXT)\n```\n\n**Example: Ask a Question**\n\n```bash\ncurl -X POST http://localhost:8000/api/ask \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"question\": \"What is machine learning?\",\n    \"modelName\": \"openai/gpt-4o\"\n  }'\n```\n\nResponse: Server-Sent Events (SSE) stream with:\n- `sources` - Document or web sources\n- `content` - Streaming answer chunks\n- `done` - Completion signal\n\n## Configuration\n\n### **Environment Variables**\n\nKey configuration options in `backend/.env`:\n\n```bash\n# Embedding Configuration\nEMBEDDING_DIMENSION=1024                    # Must match Pinecone index\nDEFAULT_EMBEDDING_MODEL=text-embedding-3-large\n\n# LLM Configuration\nDEFAULT_LLM_MODEL=openai/gpt-4o            # Can be changed in UI\n\n# Pinecone Configuration\nPINECONE_INDEX_NAME=notstuck-index\nPINECONE_ENV=us-east-1                     # Your Pinecone region\n```\n\n### **Document Processing**\n\nConfigured in `backend/src/backend/tools/document_processor.py`:\n\n```python\n# Chunking\nchunk_size = 1000           # Characters per chunk\nchunk_overlap = 200         # Overlap for continuity\nbatch_size = 100            # Vectors per batch upsert\n```\n\n### **Agent Configuration**\n\nAgents and tasks configured via YAML in `backend/src/backend/config/`:\n- `agents.yaml` - Agent roles, goals, and backstory\n- `tasks.yaml` - Task descriptions and expected outputs\n\n---\n\n## Project Structure\n\n```\nnotstuck/\n├── backend/\n│   ├── src/\n│   │   └── backend/\n│   │       ├── api/              # FastAPI application\n│   │       │   ├── routes/       # API endpoints (ask, upload, models)\n│   │       │   └── main.py       # FastAPI app entry point\n│   │       ├── clients/          # External API clients (Pinecone, OpenAI)\n│   │       ├── config/           # Agent and task configurations (YAML)\n│   │       ├── tools/            # CrewAI tools (document processor, web search, Pinecone search)\n│   │       └── crew.py           # CrewAI agent definitions\n│   ├── Dockerfile                # Backend Docker image\n│   ├── .dockerignore             # Docker ignore patterns\n│   ├── pyproject.toml            # Dependencies (uv)\n│   ├── .env                      # Environment variables (not in git)\n│   └── README.md                 # Backend docs\n├── frontend/\n│   ├── app/                      # Next.js app router\n│   │   ├── api/                  # API routes (proxy to backend)\n│   │   └── page.tsx              # Main page\n│   ├── components/               # React components\n│   │   └── common/               # Shared components (ChatMessages, ChatInput, etc.)\n│   ├── hooks/                    # Custom hooks (useChatLogic, useBackendHealth)\n│   ├── Dockerfile                # Frontend Docker image\n│   ├── .dockerignore             # Docker ignore patterns\n│   └── package.json              # Dependencies\n├── docker-compose.yml            # Docker Compose configuration\n├── .env.example                  # Example environment variables\n├── package.json                  # Root dev scripts\n└── README.md                     # This file\n```\n\n## Performance Optimizations\n\n- ✅ **Batch embedding generation** - Process multiple chunks at once\n- ✅ **Concurrent PDF processing** - ThreadPoolExecutor for parallel processing\n- ✅ **Optimized chunking** - Semantic-aware separators\n- ✅ **Adaptive filtering** - Statistical thresholds reduce noise\n- ✅ **Context deduplication** - Jaccard similarity removes redundancy\n- ✅ **Token-aware truncation** - Respects model context limits\n- ✅ **Pinecone batch upsert** - 100 vectors per batch\n- ✅ **Cosine similarity** - More accurate than dot product\n- ✅ **Manual HTTP requests** - Avoids OpenAI SDK parsing overhead\n\n## Troubleshooting\n\n### Docker Issues\n\n#### **Services won't start**\n```bash\n# Check logs\ndocker-compose logs backend\ndocker-compose logs frontend\n\n# Rebuild from scratch\ndocker-compose down -v\ndocker-compose build --no-cache\ndocker-compose up\n```\n\n#### **Backend health check failing**\n- Ensure `.env` file exists in `backend/` directory\n- Check Pinecone API key and index configuration\n- Verify OpenAI API key for embeddings\n- Wait 40 seconds for initial startup\n\n#### **Frontend can't connect to backend**\n- Check `NEXT_PUBLIC_BACKEND_URL` in docker-compose.yml\n- Ensure backend service is healthy: `docker-compose ps`\n- Check network: `docker network inspect notstuck_notstuck-network`\n\n### Local Development Issues\n\n#### **Backend won't start**\n- Check `backend/.env` file has all required variables\n- Verify Pinecone API key and index name (1024 dimensions)\n- Ensure OpenAI API key is valid (for embeddings)\n- Check Python version (3.11+)\n- Run `cd backend \u0026\u0026 uv sync` to install dependencies\n\n#### **Embeddings fail**\n- OpenAI API key must be valid (for text-embedding-3-large)\n- Check `EMBEDDING_DIMENSION=1024` in .env\n- Verify Pinecone index dimension matches (1024)\n\n#### **Upload fails**\n- Check file is PDF, DOCX, or TXT format\n- Verify Pinecone index exists with correct dimensions (1024)\n- Check backend logs for detailed error messages\n- Ensure temporary directory has write permissions\n\n#### **Model selection doesn't work**\n- Ensure backend is running first\n- Check network tab for `/api/models` call\n- Verify OpenRouter API key has access to models\n- Check for CORS issues in browser console\n\n#### **Streaming not working**\n- Clear browser cache\n- Check browser console for errors\n- Verify `/api/ask` endpoint returns `text/event-stream`\n- Ensure frontend is on latest version\n\n#### **Unicode/emoji errors in console (Windows)**\n- Fixed automatically in code via UTF-8 reconfiguration\n- If issues persist, run: `chcp 65001` in terminal\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. **Fork** the repository\n2. Create a **feature branch** (`git checkout -b feature/amazing-feature`)\n3. **Commit** changes (`git commit -m 'Add amazing feature'`)\n4. **Push** to branch (`git push origin feature/amazing-feature`)\n5. Open a **Pull Request**\n\n### Areas for Contribution\n- Additional LLM providers\n- Advanced reranking algorithms\n- UI/UX improvements\n- Performance optimizations\n- Test coverage\n- Documentation\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE). Feel free to use, modify, and distribute this project under the license terms.\n\n---\n\n## Roadmap\n\n- [x] **Streaming responses** for real-time answer generation ✅\n- [x] **Docker support** with Docker Compose ✅\n- [x] **Web search integration** with source URLs ✅\n- [x] **Intelligent agent routing** (knowledge base vs. web vs. general) ✅\n- [ ] **Multi-document conversations** with context management\n- [ ] **Advanced reranking** with cross-encoders\n- [ ] **Document management** UI (view, delete, organize)\n- [ ] **User authentication** and multi-user support\n- [ ] **Custom model configuration** per query\n- [ ] **Export conversations** as PDF/Markdown\n- [ ] **Vector database alternatives** (Qdrant, Weaviate)\n- [ ] **Image/OCR support** for scanned documents\n- [ ] **Citation linking** to original document locations\n- [ ] **Kubernetes deployment** manifests\n\n## Acknowledgments\n\nBuilt with:\n- [CrewAI](https://www.crewai.com/) for intelligent multi-agent systems\n- [FastAPI](https://fastapi.tiangolo.com/) by Sebastián Ramírez\n- [Next.js](https://nextjs.org/) by Vercel\n- [OpenRouter](https://openrouter.ai/) for multi-model API access\n- [Pinecone](https://www.pinecone.io/) for vector database\n- [uv](https://github.com/astral-sh/uv) by Astral for fast dependency management\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE). Feel free to use, modify, and distribute.\n\n## Contact \u0026 Support\n\n- **Author:** [@praneethravuri](https://github.com/praneethravuri)\n- **Issues:** [GitHub Issues](https://github.com/praneethravuri/notstuck/issues)\n- **Discussions:** [GitHub Discussions](https://github.com/praneethravuri/notstuck/discussions)\n\n---\n\n**⭐ If this project helps you, please give it a star on GitHub!**\n\nThank you for using **NotStuck** - Your AI-powered document assistant!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpraneethravuri%2Fnotstuck","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpraneethravuri%2Fnotstuck","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpraneethravuri%2Fnotstuck/lists"}