{"id":51436915,"url":"https://github.com/dpasca/rag-demo","last_synced_at":"2026-07-05T07:30:27.129Z","repository":{"id":306279402,"uuid":"1025487648","full_name":"dpasca/rag-demo","owner":"dpasca","description":"Educational RAG (Retrieval Augmented Generation) implementation with FastAPI, ChromaDB, and GPT-4.1 Mini. Good for learning how to build RAG systems.","archived":false,"fork":false,"pushed_at":"2025-07-24T16:10:50.000Z","size":57,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-24T20:11:51.754Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dpasca.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-07-24T10:25:59.000Z","updated_at":"2025-07-24T16:10:53.000Z","dependencies_parsed_at":"2025-07-24T20:23:18.145Z","dependency_job_id":null,"html_url":"https://github.com/dpasca/rag-demo","commit_stats":null,"previous_names":["dpasca/rag-demo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dpasca/rag-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpasca%2Frag-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpasca%2Frag-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpasca%2Frag-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpasca%2Frag-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dpasca","download_url":"https://codeload.github.com/dpasca/rag-demo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpasca%2Frag-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35147199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2026-07-05T07:30:26.452Z","updated_at":"2026-07-05T07:30:27.116Z","avatar_url":"https://github.com/dpasca.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RAG Demo - Minimal Implementation\n\nA minimal RAG (Retrieval Augmented Generation) implementation for educational purposes, featuring:\n\n- 🤖 AI assistant chat interface\n- 🔍 Document search with RAG via tool-calling\n- 📚 ChromaDB vector database\n- ⚡ FastAPI backend\n- 🎨 Simple HTML/CSS/JS frontend\n- 🔧 GPT-4.1 Mini integration\n\n**Created by [Davide Pasca](https://github.com/dpasca) at [NEWTYPE K.K.](https://newtypekk.com), Japan**\n\n![RAG Demo Screenshot](assets/screenshot01.png)\n\n## Quick Setup\n\n**Option 1: Automated Setup (Recommended)**\n```bash\n# Linux/Mac\n./setup.sh\n\n# Windows\nsetup.bat\n```\n\n**Option 2: Manual Setup**\n\n1. **Create and activate a virtual environment:**\n   ```bash\n   # Create virtual environment\n   python -m venv venv\n\n   # Activate virtual environment\n   # On Linux/Mac:\n   source venv/bin/activate\n   # On Windows:\n   venv\\Scripts\\activate\n   ```\n\n2. **Install dependencies:**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Set up environment variables:**\n   - Copy `.env.example` to `.env` and add your OpenAI API key:\n   ```bash\n   cp .env.example .env\n   # Edit .env and add your OpenAI API key\n   ```\n\n4. **Initialize the RAG database:**\n   ```bash\n   python update_rag.py\n   ```\n\n5. **Start the server:**\n   ```bash\n   python main.py\n   ```\n\n6. **Open your browser:**\n   Navigate to `http://localhost:8000`\n\n\u003e **Note**: The automated setup script will create the virtual environment, install dependencies, and set up the `.env` file for you. You'll just need to add your OpenAI API key to the `.env` file.\n\n## Usage\n\n### Chat Interface\n- Ask questions in the web interface\n- The AI will automatically search documents when relevant\n- Sources are displayed when RAG is used\n\n### Adding Documents\n- Place `.txt` files in the `documents/` folder\n- Run `python update_rag.py` to update the database\n- Documents are chunked with configurable size/overlap\n\n### Configuration\nAdjust settings in `.env`:\n\n**LLM Configuration:**\n- `OPENAI_API_KEY`: Your OpenAI API key (required)\n- `OPENAI_BASE_URL`: API base URL (leave empty for OpenAI, set for other providers)\n- `LLM_MODEL`: Language model to use (default: gpt-4.1-mini)\n\n**RAG Configuration:**\n- `EMBEDDING_MODEL`: OpenAI embedding model to use (default: text-embedding-3-small)\n- `CHUNK_SIZE`: Size of text chunks (default: 1000)\n- `CHUNK_OVERLAP`: Overlap between chunks (default: 200)\n- `TOP_K_RESULTS`: Number of chunks to retrieve (default: 5)\n\n**Available models:**\n- **LLM Models**: `gpt-4.1-mini`, `gpt-4.1`, or any OpenAI-compatible model\n- **Embedding Models**: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`\n\n**Using with other providers:**\n```bash\n# For Ollama (local)\nOPENAI_BASE_URL=http://localhost:11434/v1\nLLM_MODEL=llama2\nOPENAI_API_KEY=ollama  # Can be anything for Ollama\n\n# For other OpenAI-compatible APIs\nOPENAI_BASE_URL=https://your-provider.com/v1\nLLM_MODEL=your-model-name\nOPENAI_API_KEY=your-api-key\n```\n\n## Architecture\n\n```\n├── main.py              # FastAPI app\n├── chat.py              # Chat logic with OpenAI\n├── rag.py               # RAG system with ChromaDB\n├── models.py            # Pydantic models\n├── update_rag.py        # Document processing script\n├── documents/           # Text files for RAG\n├── frontend/            # Web interface\n│   ├── index.html\n│   ├── script.js\n│   └── style.css\n└── chroma_db/          # Vector database (created automatically)\n```\n\n## Key Features\n\n- **Tool-based RAG**: Uses OpenAI function calling to trigger document search\n- **Source attribution**: Shows which documents and chunks were used\n- **Configurable chunking**: Adjust chunk size and overlap via environment variables\n- **Local storage**: ChromaDB runs locally with persistent storage\n- **Educational focus**: Clean, readable code with minimal complexity\n\n## Technical Details\n\nFor detailed technical documentation about the RAG implementation, see [TECHNICAL.md](TECHNICAL.md). It covers implementation details, design decisions, and how to extend the system.\n\n## Languages\n\n- [English README](README.md)\n- [日本語 README](README_ja.md)\n- [Italiano README](README_it.md)\n- [English Technical Docs](TECHNICAL.md)\n- [日本語技術ドキュメント](TECHNICAL_ja.md)\n- [Documentazione Tecnica Italiana](TECHNICAL_it.md)\n\n## Development\n\n### Alternative Setup with uv (Advanced)\nFor faster dependency management, you can use [uv](https://github.com/astral-sh/uv):\n```bash\n# Install uv if you haven't already\npip install uv\n\n# Create and activate virtual environment\nuv venv\nsource .venv/bin/activate  # Linux/Mac\n# .venv\\Scripts\\activate     # Windows\n\n# Install dependencies\nuv pip install -r requirements.txt\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpasca%2Frag-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdpasca%2Frag-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpasca%2Frag-demo/lists"}