{"id":40522950,"url":"https://github.com/aramb-dev/agentkit","last_synced_at":"2026-01-20T21:09:48.911Z","repository":{"id":315079846,"uuid":"1057565273","full_name":"aramb-dev/agentkit","owner":"aramb-dev","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-10T18:58:12.000Z","size":714,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-10T19:25:11.033Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aramb-dev.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":"SECURITY_IMPROVEMENTS.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":"2025-09-15T22:55:12.000Z","updated_at":"2025-11-10T18:58:17.000Z","dependencies_parsed_at":"2025-09-16T16:38:48.904Z","dependency_job_id":"5e84844d-e813-4474-9328-3d1cc9ddaa9c","html_url":"https://github.com/aramb-dev/agentkit","commit_stats":null,"previous_names":["aramb-dev/agentkit"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aramb-dev/agentkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aramb-dev%2Fagentkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aramb-dev%2Fagentkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aramb-dev%2Fagentkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aramb-dev%2Fagentkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aramb-dev","download_url":"https://codeload.github.com/aramb-dev/agentkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aramb-dev%2Fagentkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28613779,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T18:56:40.769Z","status":"ssl_error","status_checked_at":"2026-01-20T18:54:26.653Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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-01-20T21:09:48.833Z","updated_at":"2026-01-20T21:09:48.896Z","avatar_url":"https://github.com/aramb-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgentKit - Intelligent AI Assistant with Modern Web Interface 🚀\n\n[![Test Suite](https://github.com/aramb-dev/agentkit/actions/workflows/test.yml/badge.svg)](https://github.com/aramb-dev/agentkit/actions/workflows/test.yml)\n\n**Enhanced RAG Frontend Integration Complete** ✨\n\nAgentKit is a powerful AI assistant that combines intelligent conversation with advanced document processing capabilities. The system features a modern React frontend with comprehensive RAG (Retrieval-Augmented Generation) document ingestion and multi-stage progress tracking.\n\n## ✨ Latest Enhancements - RAG Frontend Integration\n\n### 🎯 Complete Visual Progress Tracking\n- **Multi-stage progress indicators**: Real-time feedback through upload → processing → embedding → completion\n- **Stage-specific animations**: Blue spinners, orange pulsing icons, purple database indicators, green success checkmarks\n- **Real-time progress bars**: Smooth animations with percentage indicators\n- **Comprehensive error handling**: Categorized errors with actionable recovery guidance\n\n### 📁 Enhanced File Upload Experience  \n- **Drag-and-drop interface**: Intuitive file upload with visual feedback\n- **Multi-format support**: PDF, TXT, DOCX, MD, JSON files (up to 50MB each)\n- **Visual file management**: Clear indicators for upload status, processing stages, and completion\n- **Comprehensive validation**: Client-side and server-side file validation with clear error messages\n- **Error recovery**: Detailed error messages with specific resolution steps and retry logic\n\n### 🎨 Modern UI Components\n- **Progress components**: Built with @radix-ui/react-progress for smooth animations\n- **Visual design system**: Consistent color coding and iconography throughout\n- **Responsive design**: Optimized for all screen sizes and devices\n- **Accessibility**: Full keyboard navigation and screen reader support\n\nAgentKit is a comprehensive AI-powered assistant built with Google's Gemini models, featuring intelligent tool routing, real-time web search, persistent conversation history, and advanced file processing capabilities.\n\n## ✨ Key Features\n\n### 🧠 **Advanced AI Integration**\n\n- **Google Gen AI SDK**: 43+ Gemini models (1.5, 2.0, 2.5 variants)\n- **Intelligent Routing**: LLM-powered tool selection for optimal responses\n- **Dynamic Model Discovery**: Auto-detects available models with 4000 token responses\n- **Conversation Memory**: Maintains context across entire chat sessions\n\n### 🔍 **Advanced RAG Features** ✅\n\n- **Full Vector Store Integration**: Connected to ChromaDB for persistent document storage\n- **Semantic Search**: Enhanced relevance scoring for better document retrieval\n- **Citation Support**: Automatic source attribution with document references\n- **Hybrid Search**: Combines web search and document retrieval for comprehensive answers\n- **Search Modes**: Configurable search preferences (Auto, Web, Documents, Hybrid)\n- **Query Understanding**: Advanced query preprocessing for improved semantic matching\n- **Source Attribution**: Clear tracking of information sources in responses\n- **End-to-End Workflow**: Complete PDF upload → embedding → query → citation pipeline\n\n### ⚡ **Performance Optimizations (Phase 2.3 - NEW!)** 🚀\n\n- **99% Faster Cached Queries**: \u003c1ms response time for repeated queries (was 100-500ms)\n- **54% Faster Embeddings**: 23ms generation time (was 50ms)\n- **Query Result Caching**: LRU cache with 100 query capacity\n- **Configurable Models**: 3 embedding models (fast/balanced/accurate)\n- **Optimized Parameters**: Fine-tuned chunk sizes and retrieval settings\n- **Real-time Monitoring**: Performance metrics via `/monitoring/rag` endpoint\n- **Benchmarking Tools**: `benchmark_rag.py` for performance profiling\n- **Parameter Tuning**: `tune_rag_params.py` for custom optimization\n\n📚 **See [OPTIMIZATION_QUICKSTART.md](OPTIMIZATION_QUICKSTART.md) for quick start**  \n📖 **See [VECTOR_SEARCH_OPTIMIZATION.md](VECTOR_SEARCH_OPTIMIZATION.md) for complete optimization guide**  \n📋 **See [RAG_INTEGRATION.md](RAG_INTEGRATION.md) for RAG setup guide**\n\n### 🌐 **Real-Time Web Search**\n\n- **Tavily API Integration**: Current, accurate web information\n- **Smart Search Triggers**: Automatically searches when queries need current data\n- **Contextual Results**: Seamlessly integrates search results into responses\n\n### 💾 **Conversation Persistence** ✨ NEW!\n\n- **Automatic Saving**: All conversations automatically saved to SQLite database\n- **Conversation History Sidebar**: Visual history with search and filtering\n- **Full-Text Search**: Find past conversations by content or title\n- **Export Options**: Download conversations in JSON, TXT, or Markdown format\n- **Namespace Organization**: Isolate conversations by project or context\n- **Message Management**: Complete CRUD operations for conversations\n- **Real-time Updates**: History updates as you chat\n\n📖 **See [CONVERSATION_PERSISTENCE.md](CONVERSATION_PERSISTENCE.md) for complete guide**\n\n### 🖥️ **Modern React Frontend**\n\n- **Professional UI**: Built with React, TypeScript, Vite, and Shadcn/ui\n- **Markdown \u0026 Math Rendering**: Full support for formatted content with KaTeX\n- **Real-time Chat**: Responsive interface with conversation persistence\n- **File Management**: Integrated file upload and management system\n- **Model Selection**: Dynamic picker for available AI models\n\n### 📁 **Advanced File Processing \u0026 Document Management**\n\n- **Multi-format Support**: PDF, DOCX, TXT, MD, CSV, JSON\n- **Persistent Storage**: Unique file IDs with deduplication and metadata\n- **Smart Processing**: RAG integration for document question-answering\n- **File Management API**: Upload, list, delete, and cleanup operations\n- **Document Management UI**: Search, filter, select, and delete documents with ease\n- **Bulk Operations**: Select multiple documents for batch deletion\n- **Confirmation Dialogs**: Safety prompts for destructive operations\n\n### ⚡ **Production-Ready Backend**\n\n- **FastAPI Server**: Async API with CORS support and comprehensive error handling\n- **Conversation History**: Maintains chat context across requests\n- **Environment Configuration**: Secure API key management\n- **Health Monitoring**: Comprehensive logging and error tracking\n\n### 🛡️ **Error Handling \u0026 Validation (Phase 2.2 - Complete)** ✅\n\n- **Comprehensive File Validation**: Size (50MB), type, format, and path traversal checks\n- **Standardized Error Responses**: Consistent JSON format with error codes and details\n- **Retry Logic**: Automatic retry with exponential backoff for transient failures\n- **Client-Side Validation**: Pre-upload validation with instant feedback\n- **Request Tracking**: Unique request IDs for debugging and monitoring\n- **Security Features**: Path traversal protection, extension whitelisting, DoS prevention\n- **Clear Error Messages**: User-friendly messages with actionable recovery steps\n- **Extensive Testing**: 15+ automated tests covering validation scenarios\n\n📚 **See [ERROR_HANDLING.md](ERROR_HANDLING.md) for complete error handling guide**\n\n## 🏗️ Project Structure\n\n```\nagentkit/\n├── agent/                    # Core AI logic\n│   ├── agent.py             # Orchestration with conversation history\n│   ├── llm_client.py        # Google Gen AI integration\n│   ├── router.py            # Intelligent LLM-based tool selection\n│   ├── tools.py             # Web search, RAG, memory tools\n│   ├── document_processor.py # Multi-format file processing\n│   └── file_manager.py      # Persistent storage system\n├── app/\n│   └── main.py              # Enhanced FastAPI server\n├── frontend/                # Modern React application\n│   ├── src/components/      # Chat, FileUpload, FileManager\n│   ├── src/types/          # TypeScript definitions\n│   └── package.json        # Vite + React + Shadcn/ui\n├── uploads/                 # File storage directory\n│   ├── files/              # Uploaded files\n│   └── metadata/           # File metadata\n├── .env.example            # Environment template\n└── requirements.txt        # Python dependencies\n```\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.11+\n- Node.js 18+\n- Google AI API key ([Get one here](https://makersuite.google.com/app/apikey))\n- Tavily API key ([Get one here](https://tavily.com/))\n\n### 1. Environment Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/aramb-dev/agentkit.git\ncd agentkit\n\n# Copy environment template\ncp .env.example .env\n\n# Add your API keys to .env\nGOOGLE_API_KEY=your_google_api_key_here\nTAVILY_API_KEY=your_tavily_api_key_here\n```\n\n### 2. Backend Setup\n\n```bash\n# Create and activate virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install Python dependencies\npip install -r requirements.txt\n\n# Start the FastAPI server\nuvicorn app.main:app --reload\n```\n\nThe backend will be available at `http://localhost:8000`\n\n### 3. Frontend Setup\n\n```bash\n# Navigate to frontend directory\ncd frontend\n\n# Install Node.js dependencies\nnpm install\n\n# Start development server\nnpm run dev\n```\n\nThe frontend will be available at `http://localhost:5173`\n\n## 🐳 Docker Deployment\n\n### Quick Start with Docker\n\nThe fastest way to get AgentKit running is with Docker Compose:\n\n```bash\n# Clone and configure\ngit clone https://github.com/aramb-dev/agentkit.git\ncd agentkit\ncp .env.example .env\n\n# Edit .env with your API keys\nnano .env  # Add GOOGLE_API_KEY and TAVILY_API_KEY\n\n# Launch with Docker Compose\ndocker-compose up -d\n\n# Access the application\n# Frontend: http://localhost:8080\n# Backend API: http://localhost:8000\n# API Docs: http://localhost:8000/docs\n```\n\n### Production Deployment\n\nFor production deployments with optimized builds:\n\n```bash\n# Use production compose file\ndocker-compose -f docker-compose.prod.yml up -d\n\n# Check health status\ncurl http://localhost:8000/healthz\ncurl http://localhost:8000/readyz\n```\n\n### Docker Features\n\n- ✅ **Multi-stage builds**: Optimized image sizes\n- ✅ **Health checks**: Built-in liveness and readiness probes\n- ✅ **Non-root users**: Enhanced security\n- ✅ **Volume persistence**: Data, uploads, and vector store\n- ✅ **Resource limits**: CPU and memory constraints\n- ✅ **Auto-restart**: Resilient deployment\n- ✅ **Nginx frontend**: Production-ready static serving\n\n### Documentation\n\n- 📖 **[Docker Quick Start Guide](./DOCKER_QUICKSTART.md)** - Get started in minutes\n- 📖 **[Production Deployment Guide](./DEPLOYMENT.md)** - Complete production setup\n- 📖 **[Environment Variables](./ENVIRONMENT_VARIABLES.md)** - Configuration reference\n- 📖 **[CI/CD Setup](./.github/workflows/)** - Automated deployments\n\n### Health Endpoints\n\n- `/healthz` - Liveness probe (basic health check)\n- `/readyz` - Readiness probe (dependencies check)\n- `/status` - Comprehensive system status\n\n## 🎯 Usage Examples\n\n### Chat Interface\n\n- **Natural Conversations**: Ask questions, get intelligent responses\n- **Web Search**: \"What's the latest news about AI?\" (automatically searches)\n- **File Processing**: Upload documents and ask questions about their content\n- **Math \u0026 Code**: Full markdown rendering with LaTeX math support\n\n### API Endpoints\n\n- `POST /chat` - Send messages with conversation history\n- `POST /upload` - Upload files for processing\n- `GET /models` - List available AI models\n- `GET /files` - List uploaded files\n- `DELETE /files/{file_id}` - Delete specific files\n\n## 🔧 Advanced Configuration\n\n### Advanced RAG Features 🆕\n\nAgentKit now includes powerful search capabilities:\n\n#### Search Modes\n\n- **🔍 Auto Mode**: Intelligent LLM-powered routing (default)\n- **🌐 Web Mode**: Search current web information only\n- **📄 Documents Mode**: Search uploaded documents only\n- **⚡ Hybrid Mode**: Combine web and document search\n\n#### Citation Features\n\n- Automatic source attribution in responses\n- Document name and chunk references\n- Relevance scores for each source\n- Clear distinction between web and document sources\n\n#### Query Understanding\n\n- LLM-powered query preprocessing\n- Intelligent semantic enhancement\n- Context-aware filler word removal\n- Automatic concept extraction\n\n**See [ADVANCED_RAG_FEATURES.md](ADVANCED_RAG_FEATURES.md) for detailed documentation.**\n\n### Model Selection\n\nAgentKit automatically discovers available Gemini models:\n\n- **Gemini 1.5**: Fast, efficient for most tasks\n- **Gemini 2.0**: Enhanced reasoning and code generation\n- **Gemini 2.5**: Latest model with advanced capabilities\n\n### File Processing\n\nSupported formats and use cases:\n\n- **PDFs**: Extract text, answer questions about content\n- **Documents**: DOCX, TXT, MD files for RAG processing\n- **Data**: CSV, JSON for analysis and querying\n\n### Environment Variables\n\n```bash\nGOOGLE_API_KEY=your_google_api_key\nTAVILY_API_KEY=your_tavily_api_key\nMAX_FILE_SIZE=10485760  # 10MB default\nCONVERSATION_HISTORY_LIMIT=50  # Messages to keep in memory\n```\n\n## 🧪 Testing\n\nAgentKit has comprehensive test coverage for both backend and frontend components.\n\n### Running All Tests\n\n```bash\n# Run the complete test suite\n./run_tests.sh\n```\n\nThis will run:\n- Backend unit and integration tests with coverage\n- Frontend component tests with coverage\n- Generate HTML coverage reports\n\n### Running Tests Individually\n\n```bash\n# Backend tests\npython -m pytest test_*.py -v\n\n# Backend tests with coverage\npython -m pytest test_*.py --cov=agent --cov=app --cov=rag --cov-report=html\n\n# Frontend tests\ncd frontend \u0026\u0026 npm test\n\n# Frontend tests with coverage\ncd frontend \u0026\u0026 npm run test:coverage\n\n# End-to-end tests\nnpx playwright test\n```\n\n### Test Coverage\n\nCoverage reports are generated in:\n- Backend: `htmlcov/index.html`\n- Frontend: `frontend/coverage/index.html`\n\nFor detailed testing documentation, see [TESTING.md](TESTING.md)\n\n### Building for Production\n\n```bash\n# Build frontend\ncd frontend \u0026\u0026 npm run build\n\n# The built files will be in frontend/dist/\n```\n\n## 📚 API Documentation\n\nOnce the backend is running, visit:\n\n- **Interactive API Docs**: `http://localhost:8000/docs`\n- **OpenAPI Spec**: `http://localhost:8000/openapi.json`\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Commit your changes (`git commit -m 'Add amazing feature'`)\n5. Push to the branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **Google AI**: For the powerful Gemini models\n- **Tavily**: For real-time web search capabilities\n- **Shadcn/ui**: For the beautiful UI components\n- **React \u0026 Vite**: For the modern frontend framework\n\n---\n\n**AgentKit** - Where AI meets intuitive design for powerful, conversational intelligence. 🎉\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faramb-dev%2Fagentkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faramb-dev%2Fagentkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faramb-dev%2Fagentkit/lists"}