{"id":23357304,"url":"https://github.com/megagrindstone/doconvo","last_synced_at":"2025-04-10T09:15:45.879Z","repository":{"id":265618967,"uuid":"894915881","full_name":"MegaGrindStone/doconvo","owner":"MegaGrindStone","description":"A Terminal User Interface (TUI) application that enables interactive conversations with your documents using Large Language Models (LLM) and Retrieval-Augmented Generation (RAG) techniques.","archived":false,"fork":false,"pushed_at":"2024-12-11T23:44:17.000Z","size":72,"stargazers_count":11,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-04T08:08:37.309Z","etag":null,"topics":["anthropic","anthropic-claude","bubbletea","cli","go","llm","ollama","ollama-client","openai","openai-assistant-api","rag","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MegaGrindStone.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":"2024-11-27T08:29:53.000Z","updated_at":"2024-12-16T16:37:25.000Z","dependencies_parsed_at":"2024-11-30T06:49:17.483Z","dependency_job_id":"798232d6-d2a7-47d6-9b51-86bbfb356fde","html_url":"https://github.com/MegaGrindStone/doconvo","commit_stats":null,"previous_names":["megagrindstone/doconvo"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MegaGrindStone%2Fdoconvo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MegaGrindStone%2Fdoconvo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MegaGrindStone%2Fdoconvo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MegaGrindStone%2Fdoconvo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MegaGrindStone","download_url":"https://codeload.github.com/MegaGrindStone/doconvo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248190548,"owners_count":21062285,"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":["anthropic","anthropic-claude","bubbletea","cli","go","llm","ollama","ollama-client","openai","openai-assistant-api","rag","tui"],"created_at":"2024-12-21T10:20:03.137Z","updated_at":"2025-04-10T09:15:45.798Z","avatar_url":"https://github.com/MegaGrindStone.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DOConvo\n\nA Terminal User Interface (TUI) application that enables interactive conversations with your documents using Large Language Models (LLM) and Retrieval-Augmented Generation (RAG) techniques.\n\n## Demo\n\n[![asciicast](https://asciinema.org/a/694382.svg)](https://asciinema.org/a/694382)\n\nThe demo above showcases a conversation with my DevOps journey notes, where the AI assistant embodies the knowledge from the documents to provide contextual responses.\n\nThe demo uses the following LLM configuration:\n\n| Role | LLM Provider and Model |\n|---------|-------|\n| Convo | `Anthropic:claude-3-5-sonnet-20241022` |\n| Generate Title | `OpenAI:gpt-4` |\n| Embedder | `Ollama:nomic-embed-text` |\n\n## Features\n\n- Interactive TUI for natural conversations with your documents\n- RAG-powered responses using your document knowledge base\n- Support for multiple LLM providers (Ollama, Anthropic, OpenAI)\n- Contextual understanding and relevant answers\n\n## Installation\n\n### Install via Homebrew (macOS/Linux)\n\n```shell\nbrew install MegaGrindStone/tap/doconvo\n```\n\n### Install via Go\n\n```shell\ngo install github.com/MegaGrindStone/doconvo@latest\n```\n\n## Usage\n\n### Initial Setup\n\n1. Launch DOConvo by running:\n   ```shell\n   doconvo\n   ```\n\n2. On first launch, DOConvo will create a configuration directory:\n   - Linux/macOS: `~/.config/doconvo/`\n   - Windows: `%AppData%\\doconvo\\`\n   This directory stores your settings, embedded documents, and log files.\n\n3. First-time run will open the `Options` screen where you need to:\n   - Configure LLM Providers (at least one)\n   - Set up required Roles (Convo, Generate Title, and Embedder)\n\n### Document Embedding\n\n- While optional, embedding documents is recommended for meaningful conversations\n- To embed documents:\n  1. Navigate to document embedding options (available after Embedder LLM setup)\n  2. Select directories containing your documents\n  3. All files in selected directories and subdirectories will be processed (`.git` directories are ignored)\n  4. Multiple document directories can be embedded\n\n### Starting Conversations\n\n1. Return to the main screen\n2. Create a new conversation session\n3. Start interacting with your documents through natural language queries\n\nThe assistant will use the embedded documents as context to provide relevant responses based on your document content.\n\n## Configuration\n\n### Accessing Configuration\n\nPress `ctrl+o` from the main screen to access the Options menu where you can configure LLM providers and roles.\n\n### Supported LLM Providers\n\nDOConvo supports the following LLM providers:\n\n- [Ollama](https://ollama.com/)\n  - Required parameter: `Host`\n  - Default value: Uses `OLLAMA_HOST` environment variable\n- [Anthropic](https://www.anthropic.com/)\n  - Required parameter: `API Key`\n  - Default value: Uses `ANTHROPIC_API_KEY` environment variable\n- [OpenAI](https://openai.com/)\n  - Required parameter: `API Key`\n  - Default value: Uses `OPENAI_API_KEY` environment variable\n\n### Required LLM Roles\n\nThe application requires three LLM roles to be configured:\n\n1. **Convo LLM**: Handles the main conversation interactions\n2. **Generate Title LLM**: Creates titles for chat sessions\n3. **Embedder LLM**: Processes document embeddings\n\nYou can freely mix and match different LLM providers and their available models for each role based on your preferences and requirements.\n\n## Limitations\n\n### File Type Support\n- Currently supports only text-based files\n- Image files are not processed or understood\n- PDF support is limited:\n  - Simple PDF files may work\n  - Complex PDFs with mixed content may produce unreliable results\n\n### Source Code Handling\n- Source code files are processed as plain text\n- Code without sufficient comments may result in:\n  - Poor context understanding\n  - Less accurate responses\n  - Potential confusion in conversations\n\n### Document Processing\n- All files in selected directories (and subdirectories) are processed\n- No selective file processing - entire directories are embedded\n- Large directories with many files may require significant processing time\n\n## Troubleshooting\n\n### Logging\n- DOConvo automatically maintains log files in the configuration directory\n- All application errors are recorded in these logs\n- Log files can help diagnose issues and track application behavior\n\n### Debug Mode\n- Launch with debug mode: `doconvo -debug`\n- Debug mode provides additional information:\n  - LLM prompts and responses\n  - Detailed error traces\n  - System operation logs\n\n### Common Issues\n- If LLM connections fail:\n  - Verify API keys are correctly set\n  - Check network connectivity\n  - Ensure LLM provider services are available\n- For embedding issues:\n  - Confirm file permissions\n  - Check available disk space\n  - Verify file format compatibility\n\n## Acknowledgements\n\nThis project stands on the shoulders of these excellent open-source projects:\n\n- [Bubble Tea Framework](https://github.com/charmbracelet/bubbletea)\n  - Powerful Go framework for terminal user interfaces\n  - Enables smooth and responsive TUI implementation\n  - Makes terminal applications development a joy\n\n- [BBolt](https://github.com/etcd-io/bbolt)\n  - Reliable embedded key-value database\n  - Simple yet powerful storage solution\n  - Perfect for application data persistence\n\n- [Chromem-Go](https://github.com/philippgille/chromem-go)\n  - Efficient embeddable vector database\n  - Inspired the creation of this project\n  - Sparked the idea to build a RAG-based conversation tool\n\n- [CLI for ChatGPT](https://github.com/j178/chatgpt)\n  - Influenced the chat interface design\n  - Provided insights for conversation flow\n  - Inspired many UX improvements\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegagrindstone%2Fdoconvo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmegagrindstone%2Fdoconvo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegagrindstone%2Fdoconvo/lists"}