{"id":30240456,"url":"https://github.com/krey-yon/cliven","last_synced_at":"2025-08-15T04:57:20.527Z","repository":{"id":296412965,"uuid":"993004656","full_name":"krey-yon/Cliven","owner":"krey-yon","description":"Chat with your PDFs using local AI models  Process PDF documents and have interactive conversations with their content. Everything runs locally - no data leaves your machine.","archived":false,"fork":false,"pushed_at":"2025-06-07T14:35:35.000Z","size":53,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-08T12:48:06.900Z","etag":null,"topics":["chat-application","cli","pdf","python3","rag"],"latest_commit_sha":null,"homepage":"https://cliven.kreyon.in/","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/krey-yon.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,"zenodo":null}},"created_at":"2025-05-30T03:58:30.000Z","updated_at":"2025-06-07T15:04:15.000Z","dependencies_parsed_at":"2025-05-30T20:44:43.966Z","dependency_job_id":"9446690a-14b9-48f8-9cb6-5d4b9f4fa698","html_url":"https://github.com/krey-yon/Cliven","commit_stats":null,"previous_names":["krey-yon/cliven"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/krey-yon/Cliven","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krey-yon%2FCliven","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krey-yon%2FCliven/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krey-yon%2FCliven/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krey-yon%2FCliven/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krey-yon","download_url":"https://codeload.github.com/krey-yon/Cliven/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krey-yon%2FCliven/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270524606,"owners_count":24600205,"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","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"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":["chat-application","cli","pdf","python3","rag"],"created_at":"2025-08-15T04:57:16.353Z","updated_at":"2025-08-15T04:57:20.512Z","avatar_url":"https://github.com/krey-yon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cliven 🤖\n\n**Chat with your PDFs using local AI models!**\n\nCliven is a command-line tool that allows you to process PDF documents and have interactive conversations with their content using local AI models. No data leaves your machine - everything runs locally using ChromaDB for vector storage and Ollama for AI inference.\n\n## Features ✨\n\n- 📄 **PDF Processing**: Extract and chunk text from PDF documents\n- 🔍 **Vector Search**: Find relevant content using semantic similarity\n- 🤖 **Local AI Chat**: Chat with your documents using Ollama models\n- 🐳 **Docker Ready**: Easy setup with Docker Compose\n- 💾 **Local Storage**: All data stays on your machine\n- 🎯 **Simple CLI**: Easy-to-use command-line interface\n- 🚀 **Model Selection**: Support for both lightweight (Gemma2) and high-performance (Gemma3) models\n- 📊 **Rich UI**: Beautiful terminal interface with progress indicators\n\n## Quick Start 🚀\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/krey-yon/cliven.git\ncd cliven\n```\n\n### 2. Install Dependencies\n\n```bash\npip install -e .\n```\n\n### 3. Or, alternatively, install directly using pip \n\n```bash\npip install cliven\n```\n\n### 4. Start Services with Docker\n\n```bash\n# Start with lightweight model (tinyllama:chat)\ncliven docker start\n\n# OR start with high-performance model (gemma3:4b)\ncliven docker start --BP\n# or\ncliven docker start --better-performance\n```\n\nThis will:\n\n- Start ChromaDB on port 8000\n- Start Ollama on port 11434\n- Pull the `gemma2:2b` model (default) or `gemma3:4b` model (with --BP flag)\n- May take several minutes depending on model and connection speed\n\n### 4. Process Your First PDF\n\n```bash\ncliven ingest \"path/to/your/document.pdf\"\n```\n\n### 5. Start Chatting\n\n```bash\n# Chat with existing documents\ncliven chat\n\n# OR specify a model\ncliven chat --model gemma3:2b\n```\n\n## Usage 📖\n\n### Available Commands\n\n```bash\n# Show welcome message and commands\ncliven\n\n# Process and store a PDF\ncliven ingest \u003cpdf_path\u003e [--chunk-size SIZE] [--overlap SIZE]\n\n# Start interactive chat with existing documents\ncliven chat [--model MODEL_NAME] [--max-results COUNT]\n\n# Process PDF and start chat immediately\ncliven chat --repl \u003cpdf_path\u003e [--model MODEL_NAME]\n\n# List all processed documents\ncliven list\n\n# Delete a specific document\ncliven delete \u003cdoc_id\u003e\n\n# Clear all documents\ncliven clear [--confirm]\n\n# Check system status\ncliven status\n\n# Manage Docker services\ncliven docker start [--BP | --better-performance]  # Start services\ncliven docker stop                                 # Stop services\ncliven docker logs                                 # View logs\n```\n\n### Examples\n\n```bash\n# Process a manual with custom chunking\ncliven ingest ./documents/user-manual.pdf --chunk-size 1500 --overlap 300\n\n# Start chatting with all processed documents\ncliven chat\n\n# Chat with specific model\ncliven chat --model gemma3:4b\n\n# Process and chat with a specific PDF using high-performance model\ncliven chat --repl ./research-paper.pdf --model gemma3:4b\n\n# Check what documents are stored\ncliven list\n\n# Check if services are running\ncliven status\n\n# Clear all documents without confirmation\ncliven clear --confirm\n\n# Start services with better performance model\ncliven docker start --BP\n```\n\n### Model Options\n\nCliven supports multiple AI models:\n\n- **gemma2:2b**: Lightweight, fast responses (~1GB model)\n- **gemma3:4b**: High-performance, better quality responses (~4GB model)\n\nThe system automatically selects the best available model, or you can specify one:\n\n```bash\n# Auto-select best available model\ncliven chat\n\n# Use specific model\ncliven chat --model gemma3:4b\ncliven chat --model gemma2:2b\n```\n\n## Architecture 🏗️\n\nCliven uses a modern RAG (Retrieval-Augmented Generation) architecture:\n\n1. **PDF Parser**: Extracts text from PDFs using `pdfplumber`\n2. **Text Chunker**: Splits documents into overlapping chunks using LangChain\n3. **Embedder**: Creates embeddings using `BAAI/bge-small-en-v1.5`\n4. **Vector Database**: Stores embeddings in ChromaDB\n5. **Chat Engine**: Handles queries and generates responses with Ollama\n\n## Components 🔧\n\n### Core Services\n\n- **ChromaDB**: Vector database for storing document embeddings\n- **Ollama**: Local LLM inference server\n- **Gemma2:2b**: Lightweight chat model for fast responses\n- **Gemma3:4b**: High-performance model for better quality responses\n\n### Key Files\n\n- `main/cliven.py`: Main CLI application with argument parsing\n- `main/chat.py`: Chat engine with RAG functionality and model management\n- `utils/parser.py`: PDF text extraction and chunking\n- `utils/embedder.py`: Text embedding generation using sentence transformers\n- `utils/vectordb.py`: ChromaDB operations and vector storage\n- `utils/chunker.py`: Text chunking utilities\n- `docker-compose.yml`: Service orchestration configuration\n\n## System Requirements 📋\n\n### Software Requirements\n\n- Python 3.8+\n- Docker \u0026 Docker Compose\n- 2GB+ RAM (for Gemma2 model)\n- 8GB+ RAM (for Gemma3 4B model)\n- 4GB+ disk space\n\n### Python Dependencies\n\n- `typer\u003e=0.9.0` - CLI framework\n- `rich\u003e=13.0.0` - Beautiful terminal output\n- `pdfplumber\u003e=0.7.0` - PDF text extraction\n- `sentence-transformers\u003e=2.2.0` - Text embeddings\n- `chromadb\u003e=0.4.0` - Vector database\n- `langchain\u003e=0.0.300` - Text processing\n- `requests\u003e=2.28.0` - HTTP client\n\n## Installation Options 🛠️\n\n### Option 1: Local Development\n\n```bash\n# Clone repository\ngit clone https://github.com/krey-yon/cliven.git\ncd cliven\n\n# Create virtual environment\npython -m venv .venv\n.venv\\Scripts\\activate\n\n# Install dependencies\npip install -e .\n\n# Start services\ncliven docker start\n```\n\n### Option 2: Production Install\n\n```bash\npip install git+https://github.com/krey-yon/cliven.git\n```\n\n## Configuration ⚙️\n\n### Environment Variables\n\n```bash\n# ChromaDB settings\nCHROMA_HOST=localhost\nCHROMA_PORT=8000\n\n# Ollama settings\nOLLAMA_HOST=localhost\nOLLAMA_PORT=11434\n```\n\n### Customization\n\n```bash\n# Use different chunk sizes\ncliven ingest document.pdf --chunk-size 1500 --overlap 300\n\n# Use different model\ncliven chat --model gemma3:4b\n\n# Adjust context window\ncliven chat --max-results 10\n\n# Skip confirmation for clearing\ncliven clear --confirm\n```\n\n### Model Management\n\n```bash\n# Check available models\ncliven status\n\n# Manually pull models\ndocker exec -it cliven_ollama ollama pull gemma3:4b\ndocker exec -it cliven_ollama ollama pull gemma2:2b\n\n# List downloaded models\ndocker exec -it cliven_ollama ollama list\n```\n\n## Troubleshooting 🔧\n\n### Common Issues\n\n1. **Docker services not starting**\n\n   ```bash\n   # Check Docker daemon\n   docker info\n\n   # View service logs\n   cliven docker logs\n\n   # Restart services\n   cliven docker stop\n   cliven docker start\n   ```\n\n2. **Model not found**\n\n   ```bash\n   # Check available models\n   cliven status\n\n   # Manually pull model\n   docker exec -it cliven_ollama ollama pull gemma3:4b\n   docker exec -it cliven_ollama ollama pull gemma2:2b\n   ```\n\n3. **ChromaDB connection failed**\n\n   ```bash\n   # Check service status\n   cliven status\n\n   # Restart services\n   cliven docker stop\n   cliven docker start\n\n   # Check logs\n   cliven docker logs\n   ```\n\n4. **PDF processing errors**\n\n   ```bash\n   # Check file path and permissions\n   dir path\\to\\file.pdf\n\n   # Try with different chunk size\n   cliven ingest file.pdf --chunk-size 500\n\n   # Check for PDF corruption\n   cliven ingest file.pdf --chunk-size 2000 --overlap 100\n   ```\n\n5. **Model performance issues**\n\n   ```bash\n   # Switch to lightweight model\n   cliven chat --model gemma2:2b\n\n   # Or use high-performance model\n   cliven chat --model gemma3:4b\n\n   # Check system resources\n   cliven status\n   ```\n\n### Performance Tips\n\n- Use `gemma2:2b` for faster responses on limited hardware\n- Use `gemma3:4b` for better quality responses with sufficient RAM\n- Use smaller chunk sizes for better context precision\n- Increase overlap for better continuity\n- Monitor RAM usage with large PDFs\n- Use SSD storage for better ChromaDB performance\n\n\n## Contributing 🤝\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License 📄\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments 🙏\n\n- [ChromaDB](https://www.trychroma.com/) for vector storage\n- [Ollama](https://ollama.ai/) for local LLM inference\n- [Sentence Transformers](https://www.sbert.net/) for embeddings\n- [LangChain](https://langchain.com/) for text processing\n- [Rich](https://rich.readthedocs.io/) for beautiful terminal output\n- [PDFplumber](https://github.com/jsvine/pdfplumber) for PDF text extraction\n\n## Support 💬\n\n- 📧 Email: vikaskumar783588@gmail.com\n- 🐛 Issues: [GitHub Issues](https://github.com/krey-yon/cliven/issues)\n- 💡 Discussions: [GitHub Discussions](https://github.com/krey-yon/cliven/discussions)\n\n---\n\n**Made with ❤️ by [Kreyon](https://github.com/krey-yon)**\n\n_Chat with your PDFs locally and securely!_\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrey-yon%2Fcliven","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrey-yon%2Fcliven","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrey-yon%2Fcliven/lists"}