{"id":48834177,"url":"https://github.com/edwards359/rag-assistant","last_synced_at":"2026-04-14T22:05:13.525Z","repository":{"id":333376715,"uuid":"1131838841","full_name":"Edwards359/rag-assistant","owner":"Edwards359","description":"RAG‑ассистент: ответы по документам (OpenAI/GigaChat), кеш и метрики качества.","archived":false,"fork":false,"pushed_at":"2026-03-16T18:33:18.000Z","size":80,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-17T05:30:50.492Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/Edwards359.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY_CHECK.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-10T19:46:38.000Z","updated_at":"2026-03-16T18:33:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Edwards359/rag-assistant","commit_stats":null,"previous_names":["edwards359/rag-assistant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Edwards359/rag-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edwards359%2Frag-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edwards359%2Frag-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edwards359%2Frag-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edwards359%2Frag-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Edwards359","download_url":"https://codeload.github.com/Edwards359/rag-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Edwards359%2Frag-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31817138,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-04-14T22:04:35.763Z","updated_at":"2026-04-14T22:05:13.485Z","avatar_url":"https://github.com/Edwards359.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"## 🇷🇺 Обзор для заказчика\n\n**RAG Assistant** — AI‑ассистент, который отвечает на вопросы по вашим документам и базе знаний.\n\n- **Для чего:** уменьшить количество рутинных запросов к экспертам и поддержке.\n- **Что делает:** ищет нужные фрагменты в документах и формирует понятный ответ с опорой на исходный текст.\n- **Где полезен:** внутренние базы знаний, регламенты, инструкции, FAQ, обучающие материалы.\n- **Пример кейса:** сотрудник задаёт вопрос по процедуре → ассистент возвращает ответ + выдержки из актуального документа.\n\n---\n# 🤖 RAG Assistant - Dual Implementation\n\n\u003cdiv align=\"center\"\u003e\n\n![Python](https://img.shields.io/badge/Python-3.11.9-blue.svg)\n![License](https://img.shields.io/badge/License-MIT-green.svg)\n![OpenAI](https://img.shields.io/badge/OpenAI-GPT--4o--mini-412991.svg)\n![GigaChat](https://img.shields.io/badge/GigaChat-Sber-orange.svg)\n![Status](https://img.shields.io/badge/Status-Production%20Ready-success.svg)\n\n**Two production-ready RAG (Retrieval-Augmented Generation) assistants with different LLM backends**\n\n[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [Documentation](#-documentation) • [Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## 📋 Table of Contents\n\n- [About](#-about-the-project)\n- [Architecture](#-architecture)\n- [Features](#-features)\n- [Tech Stack](#-tech-stack)\n- [Installation](#-installation)\n- [Configuration](#-configuration)\n- [Usage](#-usage)\n- [Project Structure](#-project-structure)\n- [Documentation](#-documentation)\n- [Performance](#-performance)\n- [Troubleshooting](#-troubleshooting)\n- [Contributing](#-contributing)\n- [License](#-license)\n- [Acknowledgments](#-acknowledgments)\n\n---\n\n## 🎯 About The Project\n\nThis project demonstrates two complete RAG (Retrieval-Augmented Generation) implementations using different Large Language Model backends:\n\n### 🔵 OpenAI Implementation (`assistant_api`)\n- **LLM:** GPT-4o-mini\n- **Embeddings:** text-embedding-3-small\n- **Quality Evaluation:** RAGAS metrics\n- **Status:** ✅ Fully functional\n\n### 🟢 GigaChat Implementation (`assistant_giga`)\n- **LLM:** GigaChat by Sber\n- **Embeddings:** GigaChat Embeddings API (with fallback)\n- **Status:** ✅ Functional with limitations\n\nBoth implementations share:\n- **Vector Database:** ChromaDB\n- **Caching:** SQLite\n- **Smart Chunking:** Semantic text splitting with overlap\n- **Console Interface:** Interactive CLI\n\n---\n\n## 🏗️ Architecture\n\n```\n┌─────────────┐\n│ User Query  │\n└──────┬──────┘\n       │\n       ▼\n┌─────────────────┐\n│  Cache Check    │ ◄─── SQLite DB\n│  (SHA-256 hash) │\n└────────┬────────┘\n         │\n    ┌────┴────┐\n    │  Hit?   │\n    └─┬────┬──┘\n  Yes │    │ No\n      │    ▼\n      │  ┌──────────────────┐\n      │  │ Vector Search    │ ◄─── ChromaDB\n      │  │ (Top-K=3)        │\n      │  └────────┬─────────┘\n      │           │\n      │           ▼\n      │  ┌──────────────────┐\n      │  │ Context Building │\n      │  │ (Prompt + Docs)  │\n      │  └────────┬─────────┘\n      │           │\n      │           ▼\n      │  ┌──────────────────┐\n      │  │ LLM Generation   │ ◄─── OpenAI / GigaChat\n      │  │ (Temperature=0.3)│\n      │  └────────┬─────────┘\n      │           │\n      │           ▼\n      │  ┌──────────────────┐\n      │  │ Cache Storage    │\n      │  └────────┬─────────┘\n      │           │\n      └───────────┘\n              │\n              ▼\n      ┌─────────────┐\n      │   Response  │\n      └─────────────┘\n```\n\n---\n\n## ✨ Features\n\n### Core Functionality\n\n- **✅ Semantic Search** - Find relevant context using vector embeddings\n- **✅ Smart Caching** - Instant responses for repeated queries (\u003c100ms)\n- **✅ Intelligent Chunking** - Semantic text splitting with overlap\n- **✅ Dual LLM Support** - Choose between OpenAI and GigaChat\n- **✅ Quality Metrics** - RAGAS evaluation for OpenAI implementation\n- **✅ Console Interface** - User-friendly CLI with commands\n- **✅ Statistics** - Track cache hits, document counts, performance\n\n### Advanced Features\n\n- **Context Preservation** - Overlap between chunks maintains coherence\n- **Normalized Queries** - Case-insensitive, whitespace-normalized caching\n- **Automatic Retry** - OAuth token refresh for GigaChat\n- **Fallback Embeddings** - Hash-based vectors when API unavailable\n- **Detailed Logging** - Track every step of the pipeline\n\n---\n\n## 🛠️ Tech Stack\n\n### Core Technologies\n\n| Technology | Version | Purpose |\n|------------|---------|---------|\n| **Python** | 3.11.9 | Runtime environment |\n| **OpenAI API** | 2.15.0 | LLM \u0026 Embeddings (assistant_api) |\n| **GigaChat API** | - | Russian LLM (assistant_giga) |\n| **ChromaDB** | 1.4.0 | Vector database |\n| **LangChain** | 1.2.3 | LLM framework |\n| **RAGAS** | 0.4.2 | RAG quality evaluation |\n\n### Supporting Libraries\n\n```python\nsentence-transformers  # 5.2.0  - Transformer models\nnumpy                  # 2.4.1  - Numerical operations\npandas                 # 2.3.3  - Data manipulation\ntiktoken              # 0.12.0 - Token counting\npython-dotenv         # 1.2.1  - Environment management\n```\n\n---\n\n## 📥 Installation\n\n### Prerequisites\n\n- **Python 3.11+** (tested on 3.11.9)\n- **Git**\n- **OpenAI API Key** (for assistant_api)\n- **GigaChat Credentials** (for assistant_giga)\n\n### Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/rag-assistant.git\ncd rag-assistant\n\n# Create virtual environment\npy -3.11 -m venv venv_py311\n\n# Activate (Windows PowerShell)\n.\\venv_py311\\Scripts\\Activate.ps1\n\n# Activate (Windows CMD)\n.\\venv_py311\\Scripts\\activate.bat\n\n# Activate (Linux/Mac)\nsource venv_py311/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Setup environment variables\ncopy env.example .env\n# Edit .env with your API keys\n```\n\n### Alternative: Using Activation Scripts\n\n```bash\n# Windows PowerShell\n.\\activate.ps1\n\n# Windows CMD\nactivate.bat\n```\n\n---\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the project root:\n\n```env\n# OpenAI Configuration (required for assistant_api)\nOPENAI_API_KEY=sk-your-openai-api-key-here\n\n# GigaChat Configuration (required for assistant_giga)\nGIGACHAT_AUTH_KEY=your-basic-auth-token-here\nGIGACHAT_RQUID=your-request-uid-here\n```\n\n### Getting API Keys\n\n#### OpenAI\n1. Visit https://platform.openai.com/api-keys\n2. Create a new API key\n3. Copy and paste into `.env`\n\n#### GigaChat\n1. Register at https://developers.sber.ru/gigachat\n2. Get your OAuth credentials\n3. Copy AUTH_KEY and RQUID into `.env`\n\n---\n\n## 🚀 Usage\n\n### OpenAI Assistant\n\n```bash\n# Activate environment\n.\\venv_py311\\Scripts\\Activate.ps1\n\n# Navigate to OpenAI assistant\ncd assistant_api\n\n# Run\npython app.py\n```\n\n### GigaChat Assistant\n\n```bash\n# Activate environment\n.\\venv_py311\\Scripts\\Activate.ps1\n\n# Navigate to GigaChat assistant\ncd assistant_giga\n\n# Run\npython app.py\n```\n\n### Quality Evaluation (OpenAI only)\n\n```bash\ncd assistant_api\npython evaluate_ragas.py\n```\n\n### Console Commands\n\nOnce running, use these commands:\n\n| Command | Description |\n|---------|-------------|\n| `exit`, `quit`, `q` | Exit the application |\n| `stats` | Show system statistics |\n| `clear` | Clear the cache (with confirmation) |\n\n### Example Session\n\n```\n╔══════════════════════════════════════════════════════════╗\n║         RAG Ассистент (API Mode)                        ║\n║  Retrieval-Augmented Generation через OpenAI API        ║\n╚══════════════════════════════════════════════════════════╝\n\n💭 Ваш вопрос: Что такое RAG?\n\n────────────────────────────────────────────────────────────\n📝 Вопрос: Что такое RAG?\n────────────────────────────────────────────────────────────\n🌐 Источник: OpenAI API (gpt-4o-mini)\n   Использовано документов: 3\n\n💬 Ответ:\nRAG (Retrieval-Augmented Generation) - это подход, который \nкомбинирует извлечение информации из базы знаний с генерацией \nтекста языковыми моделями. RAG системы сначала находят релевантные \nдокументы, затем используют их как контекст для генерации ответа...\n\n📚 Использованный контекст:\n   1. RAG (Retrieval-Augmented Generation) - это подход...\n────────────────────────────────────────────────────────────\n```\n\n---\n\n## 📁 Project Structure\n\n```\nrag-assistant/\n│\n├── 📄 README.md                    # This file\n├── 📄 LICENSE                      # MIT License\n├── 📄 CONTRIBUTING.md              # Contribution guidelines\n├── 📄 SETUP_COMPLETE.md            # Installation log\n├── 📄 requirements.txt             # Python dependencies\n├── 📄 env.example                  # Environment template\n├── 📄 .gitignore                   # Git ignore rules\n├── 🔧 activate.ps1                 # PowerShell activation script\n├── 🔧 activate.bat                 # CMD activation script\n│\n├── 🔵 assistant_api/               # OpenAI Implementation\n│   ├── 📄 OPENAI_INFO.md          # Detailed documentation\n│   ├── 🐍 app.py                  # Main console application\n│   ├── 🐍 rag_pipeline.py         # RAG orchestration\n│   ├── 🐍 vector_store.py         # ChromaDB + OpenAI embeddings\n│   ├── 🐍 cache.py                # SQLite caching\n│   ├── 🐍 evaluate_ragas.py       # Quality evaluation\n│   └── 📁 data/\n│       └── 📄 docs.txt            # Knowledge base\n│\n└── 🟢 assistant_giga/              # GigaChat Implementation\n    ├── 📄 GIGACHAT_INFO.md        # Detailed documentation\n    ├── 🐍 app.py                  # Main console application\n    ├── 🐍 rag_pipeline.py         # RAG orchestration\n    ├── 🐍 vector_store.py         # ChromaDB + GigaChat embeddings\n    ├── 🐍 cache.py                # SQLite caching\n    ├── 🐍 gigachat_client.py      # GigaChat API client\n    └── 📁 data/\n        └── 📄 docs.txt            # Knowledge base\n```\n\n---\n\n## 📚 Documentation\n\n### Main Documents\n\n- **[SETUP_COMPLETE.md](SETUP_COMPLETE.md)** - Complete installation guide\n- **[OPENAI_INFO.md](assistant_api/OPENAI_INFO.md)** - OpenAI implementation details\n- **[GIGACHAT_INFO.md](assistant_giga/GIGACHAT_INFO.md)** - GigaChat implementation details\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute\n\n### Knowledge Base Topics\n\nThe included knowledge base covers:\n- Machine Learning fundamentals\n- Neural Networks and Deep Learning\n- NLP and Transformers\n- Word Embeddings\n- RAG Systems\n- Vector Databases\n- Prompt Engineering\n- Fine-tuning\n- LLM Quality Metrics\n- AI Caching strategies\n\n---\n\n## ⚡ Performance\n\n### Benchmarks\n\n| Operation | Time | Cost (OpenAI) |\n|-----------|------|---------------|\n| First query | 2-5 sec | ~$0.001 |\n| Cached query | \u003c100ms | $0 |\n| Document chunking | ~1 sec | ~$0.0006 |\n| Single embedding | ~0.5 sec | ~$0.00001 |\n\n### Optimization Tips\n\n1. **Use Cache** - Repeated queries are instant\n2. **Optimize Chunks** - Balance size vs. relevance\n3. **Limit max_tokens** - 500 is sufficient for most answers\n4. **Use gpt-4o-mini** - 60x cheaper than GPT-4\n\n---\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n#### \"OPENAI_API_KEY not set\"\n**Solution:** Create `.env` file with your API key\n\n#### \"ModuleNotFoundError\"\n**Solution:** Activate virtual environment:\n```bash\n.\\venv_py311\\Scripts\\Activate.ps1\n```\n\n#### GigaChat \"402 Payment Required\"\n**Solution:** This is normal for Embeddings API. System uses fallback.\n\n#### Slow responses\n**Solution:** \n- Use cache (check with `stats` command)\n- Reduce `top_k` in search\n- Decrease `max_tokens` in generation\n\n### Getting Help\n\n- 📖 Check documentation files\n- 🐛 Open an issue on GitHub\n- 💬 Ask in discussions\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Quick Start for Contributors\n\n```bash\n# Fork and clone\ngit clone https://github.com/yourusername/rag-assistant.git\n\n# Create feature branch\ngit checkout -b feature/amazing-feature\n\n# Make changes and test\n\n# Commit and push\ngit commit -m 'Add amazing feature'\ngit push origin feature/amazing-feature\n\n# Open Pull Request\n```\n\n---\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## 🙏 Acknowledgments\n\n### Technologies\n\n- **[OpenAI](https://openai.com/)** - GPT-4 and embeddings API\n- **[GigaChat](https://developers.sber.ru/gigachat)** - Russian language model\n- **[ChromaDB](https://www.trychroma.com/)** - Vector database\n- **[LangChain](https://python.langchain.com/)** - LLM framework\n- **[RAGAS](https://docs.ragas.io/)** - RAG evaluation framework\n\n### Inspiration\n\nThis project was built to demonstrate best practices in RAG implementation with different LLM backends.\n\n---\n\n## 📊 Project Status\n\n| Component | OpenAI | GigaChat |\n|-----------|--------|----------|\n| LLM API | ✅ | ✅ |\n| Embeddings | ✅ | ⚠️ Fallback |\n| Vector Search | ✅ | ✅ |\n| Caching | ✅ | ✅ |\n| Quality Metrics | ✅ | ❌ |\n| Documentation | ✅ | ✅ |\n\n**Legend:** ✅ Fully Functional | ⚠️ Limited | ❌ Not Available\n\n---\n\n## 🔮 Roadmap\n\n- [ ] Add web interface (Streamlit/Gradio)\n- [ ] Support for multiple document formats (PDF, DOCX)\n- [ ] Conversation history\n- [ ] Multi-language support\n- [ ] Docker deployment\n- [ ] REST API endpoint\n- [ ] More embedding models\n- [ ] Production deployment guide\n\n---\n\n## 📞 Contact\n\nProject Link: [https://github.com/yourusername/rag-assistant](https://github.com/yourusername/rag-assistant)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ and Python**\n\n⭐ Star this repo if you find it useful!\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedwards359%2Frag-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedwards359%2Frag-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedwards359%2Frag-assistant/lists"}