diff --git a/README.md b/README.md index e42e586..e719733 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,59 @@ -# OllaHub +
+

🧠 OllaHub

+

Local-first LLM workspace with deep research capabilities and native OS integration.

-Local-first LLM workspace with deep research capabilities and native OS integration. +

+ Rust + Tauri + Next.js + TypeScript + License +

-[![Rust](https://img.shields.io/badge/Rust-1.77.2-orange.svg)](https://www.rust-lang.org/) -[![Tauri](https://img.shields.io/badge/Tauri-2.9.2-24C8DB.svg)](https://tauri.app/) -[![Next.js](https://img.shields.io/badge/Next.js-16.0.3-black.svg)](https://nextjs.org/) -[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/) -[![License](https://img.shields.io/badge/License-Custom-blue.svg)](LICENSE) -[![Version](https://img.shields.io/badge/Version-0.1.0-blue.svg)](https://github.com/evandrodevbr/OllaHub) +
-## Overview +
-OllaHub is a desktop application that orchestrates local Large Language Models (LLMs) through Ollama, providing a private, offline-capable workspace for research, analysis, and conversation. The application executes complex research workflows by decomposing queries, performing parallel web scraping, and synthesizing context from multiple sources before generating responses. +--- -The architecture prioritizes data privacy by keeping all processing local, using SQLite with full-text search for efficient storage, and integrating ONNX Runtime for semantic relevance ranking without external API dependencies. +## 🌟 Why OllaHub? -## Key Features +OllaHub is a powerful desktop application that orchestrates local Large Language Models (LLMs) through **Ollama**, providing a private, offline-capable workspace for research, analysis, and conversation. -### Deep Research Pipeline +Unlike standard chat interfaces, OllaHub executes **complex research workflows** by decomposing queries, performing parallel web scraping, and synthesizing context from multiple sources before generating responsesβ€”all while keeping your data 100% local and private. -The application implements a multi-stage research workflow: +--- -1. **Query Decomposition**: Uses LLM to break complex queries into 3-5 atomic, search-optimized sub-queries -2. **Parallel Web Scraping**: Executes multiple searches concurrently using headless Chrome and DuckDuckGo metadata API -3. **Knowledge Base Aggregation**: Collects and deduplicates content from multiple sources -4. **Context Condensation**: Applies relevance scoring and summarization to fit context within token limits -5. **Validation**: Verifies knowledge base sufficiency before response generation +## ✨ Key Features -The pipeline includes safety checks to ensure decomposed queries remain relevant to the original intent, with automatic fallback to the original query if decomposition fails. +### πŸ” Deep Research Pipeline +OllaHub doesn't just answer; it researches. Our multi-stage pipeline includes: +1. **Query Decomposition:** Uses the LLM to break complex queries into 3-5 atomic, search-optimized sub-queries. +2. **Parallel Scraping:** Executes concurrent searches using headless Chrome and the DuckDuckGo metadata API. +3. **Knowledge Aggregation:** Collects, deduplicates, and cleans content from multiple sources. +4. **Context Condensation:** Applies relevance scoring (ONNX embeddings) and summarization to fit context within token limits. +5. **Validation:** Verifies knowledge base sufficiency before response generation, with safety fallbacks. -### Local-First Architecture +### πŸ›‘οΈ Local-First & Privacy-Focused +* **Ollama Integration:** Direct subprocess management for seamless local model execution. +* **Local Semantic Search:** Powered by ONNX Runtime (`all-MiniLM-L6-v2` 384-dimensional embeddings) with no external API calls. +* **Hybrid Storage:** Blazing fast SQLite (FTS5 for full-text search) with JSON fallbacks for backward compatibility and data safety. -- **Ollama Integration**: Direct subprocess management of Ollama for model execution -- **ONNX Embeddings**: Local semantic similarity using all-MiniLM-L6-v2 (384-dimensional embeddings) -- **SQLite with FTS5**: Full-text search with virtual tables for session titles and message content -- **Hybrid Storage**: Dual persistence (SQLite + JSON) with automatic migration and fallback +### πŸ”Œ MCP (Model Context Protocol) Integration +Extensible by design. Connect external tools via MCP servers: +* **Tool Discovery:** Automatic enumeration of available tools from running servers. +* **Process Management:** Full lifecycle control (start, stop, restart) with health monitoring. +* **Tool Execution:** Runtime invocation of tools with direct result injection into the LLM context. -### Hybrid Storage System +### ⚑ Reactive & Customizable UI +Built with **React 19, Next.js 16, and Tailwind CSS**. Features smooth animations (Framer Motion), accessible primitives (Radix UI/Shadcn), resizable panels, and lightweight state management (Zustand). -The application uses SQLite as the primary storage backend with JSON as a fallback: +--- -- **SQLite (Primary)**: WAL mode for concurrent reads/writes, optimized cache settings, FTS5 virtual tables for search -- **JSON (Legacy)**: Maintained for backward compatibility and export functionality -- **Automatic Migration**: Seamless transition from JSON to SQLite with data preservation +## πŸ—οΈ System Architecture -### Reactive UI - -Built with React 19 and Next.js 16, the interface uses: - -- **Tailwind CSS**: Utility-first styling with design tokens -- **Radix UI / Shadcn**: Accessible, headless component primitives -- **Zustand**: Lightweight state management for settings and UI state -- **Framer Motion**: Smooth animations for state transitions -- **Resizable Panels**: Customizable layout with persistent preferences - -### MCP (Model Context Protocol) Integration - -Supports external tool integration through MCP servers: - -- **JSON-RPC Communication**: Bidirectional communication with MCP servers via stdin/stdout -- **Tool Discovery**: Automatic enumeration of available tools from running servers -- **Process Management**: Lifecycle management (start, stop, restart) with health monitoring -- **Tool Execution**: Runtime invocation of MCP tools with result injection into LLM context - -### System Monitoring - -Real-time hardware monitoring and resource management: - -- **GPU Detection**: NVIDIA and AMD GPU identification with utilization tracking -- **CPU/Memory Stats**: System-wide resource usage via `sysinfo` crate -- **Model Recommendations**: Hardware-aware model suggestions based on available VRAM/RAM - -### Task Scheduler - -Cron-based task execution system: - -- **Recurring Tasks**: Schedule periodic operations (e.g., knowledge base updates) -- **Task Queue**: Priority-based execution with retry logic -- **State Persistence**: Task state survives application restarts - -## Architecture +
+Click to view Architecture Diagram ```mermaid graph TB @@ -127,232 +101,106 @@ graph TB style Bridge fill:#7c3aed,color:#fff style Backend fill:#dc2626,color:#fff style External fill:#059669,color:#fff + ``` -### Data Flow +
-1. **User Query** β†’ Frontend captures input and triggers preprocessing -2. **Query Preprocessing** β†’ Intent classification, entity extraction, query enrichment -3. **Deep Research** β†’ Query decomposition β†’ Parallel search β†’ Scraping β†’ Knowledge base aggregation -4. **Context Condensation** β†’ Relevance scoring (ONNX embeddings) β†’ Summarization β†’ Token optimization -5. **LLM Generation** β†’ Ollama subprocess with streaming response -6. **Storage** β†’ SQLite persistence with FTS5 indexing for future retrieval +--- -## Tech Stack - -### Core - -| Layer | Technology | Version | Purpose | -|-------|-----------|---------|---------| -| **Desktop Framework** | Tauri | 2.9.2 | Native desktop app with Rust backend | -| **Backend Language** | Rust | 1.77.2 | System-level operations, performance-critical paths | -| **Frontend Framework** | Next.js | 16.0.3 | React-based UI with SSR capabilities | -| **UI Library** | React | 19.2.0 | Component-based interface | -| **Language** | TypeScript | 5.0 | Type-safe frontend development | - -### Frontend - -| Category | Technology | Purpose | -|----------|-----------|---------| -| **State Management** | Zustand | 5.0.8 | Settings and UI state | -| **Styling** | Tailwind CSS | 4.0 | Utility-first CSS framework | -| **Components** | Radix UI | Latest | Accessible primitives (dialogs, dropdowns, tooltips) | -| **Components** | Shadcn/ui | Custom | Pre-built component library | -| **Animations** | Framer Motion | 12.23.24 | Smooth transitions | -| **Markdown** | react-markdown | 10.1.0 | Message rendering with GFM support | -| **Syntax Highlighting** | react-syntax-highlighter | 16.1.0 | Code block rendering | - -### Backend - -| Category | Technology | Purpose | -|----------|-----------|---------| -| **Database** | SQLite (rusqlite) | 0.31 | Local data persistence with FTS5 | -| **Web Scraping** | headless_chrome | 1.0 | Browser automation for content extraction | -| **HTML Parsing** | scraper | 0.18 | DOM parsing and content extraction | -| **Text Processing** | readability | 0.3 | Main content extraction from HTML | -| **HTTP Client** | reqwest | 0.12 | API requests with streaming support | -| **Async Runtime** | tokio | 1.0 | Async I/O and concurrency | -| **Task Scheduling** | tokio-cron-scheduler | 0.9 | Cron-based task execution | -| **System Info** | sysinfo | 0.36.1 | Hardware monitoring | -| **Embeddings** | ONNX Runtime (ort) | 2.0.0-rc.10 | Local semantic similarity | -| **Tokenization** | tokenizers | 0.21 | Text tokenization for embeddings | -| **Array Operations** | ndarray | 0.16 | Numerical computations | - -### AI/ML - -| Component | Technology | Purpose | -|-----------|-----------|---------| -| **LLM Runtime** | Ollama | Local model execution | -| **Embeddings Model** | all-MiniLM-L6-v2 | 384-dim semantic embeddings | -| **Embeddings Runtime** | ONNX Runtime | Model inference | - -## Getting Started +## πŸš€ Getting Started ### Prerequisites -- **Node.js**: 20.x or later -- **Rust**: 1.77.2 or later -- **pnpm**: Latest version (`npm install -g pnpm`) -- **Ollama**: [Install Ollama](https://ollama.ai) and ensure it's running on `http://localhost:11434` +Before you begin, ensure you have the following installed: -### Installation +* **Node.js**: `v20.x` or later +* **Rust**: `v1.77.2` or later +* **pnpm**: Latest version (`npm install -g pnpm`) +* **[Ollama](https://ollama.ai)**: Must be running locally on `http://localhost:11434` -1. Clone the repository: +### Installation & Development + +1. **Clone the repository:** ```bash -git clone https://github.com/evandrodevbr/OllaHub.git +git clone [https://github.com/evandrodevbr/OllaHub.git](https://github.com/evandrodevbr/OllaHub.git) cd OllaHub + ``` -2. Install dependencies: + +2. **Install dependencies:** ```bash pnpm install + ``` -3. Run in development mode: + +3. **Run in development mode:** ```bash pnpm tauri dev + ``` -This command will: -- Start the Next.js development server on `http://localhost:3000` -- Build the Rust backend -- Launch the Tauri application window + +*This starts the Next.js server (`localhost:3000`), builds the Rust backend, and launches the Tauri native window.* ### Building for Production ```bash pnpm tauri build -``` - -The built application will be in `src-tauri/target/release/bundle/`: -- **Windows**: `.msi` installer -- **macOS**: `.dmg` or `.app` -- **Linux**: `.deb`, `.AppImage`, or `.rpm` - -### Environment Configuration - -The application uses Tauri's built-in configuration. No environment variables are required for basic operation. MCP server configurations are stored in the application data directory and managed through the UI. - -## Project Structure ``` -OllaHub/ -β”œβ”€β”€ app/ # Next.js app directory (pages) -β”‚ β”œβ”€β”€ chat/ # Chat interface -β”‚ β”œβ”€β”€ settings/ # Application settings -β”‚ β”œβ”€β”€ setup/ # Initial setup wizard -β”‚ └── tasks/ # Task management -β”œβ”€β”€ components/ # React components -β”‚ β”œβ”€β”€ chat/ # Chat-specific components -β”‚ β”œβ”€β”€ settings/ # Settings UI components -β”‚ β”œβ”€β”€ setup/ # Setup wizard components -β”‚ └── ui/ # Reusable UI primitives (Shadcn) -β”œβ”€β”€ hooks/ # React custom hooks -β”‚ β”œβ”€β”€ use-chat.ts # Chat state management -β”‚ β”œβ”€β”€ use-deep-research.ts # Research pipeline orchestration -β”‚ β”œβ”€β”€ use-mcp-servers.ts # MCP server management -β”‚ └── ... -β”œβ”€β”€ lib/ # Utility functions -β”‚ β”œβ”€β”€ knowledge-base-processor.ts # Context condensation -β”‚ β”œβ”€β”€ contextual-analyzer.ts # Query analysis -β”‚ β”œβ”€β”€ query-enricher.ts # Query expansion -β”‚ └── ... -β”œβ”€β”€ services/ # Service layer -β”‚ └── webSearch.ts # Web search abstraction -β”œβ”€β”€ store/ # Zustand stores -β”‚ └── settings-store.ts # Application settings -β”œβ”€β”€ src-tauri/ # Rust backend -β”‚ β”œβ”€β”€ src/ -β”‚ β”‚ β”œβ”€β”€ lib.rs # Main Tauri commands -β”‚ β”‚ β”œβ”€β”€ db.rs # SQLite database layer -β”‚ β”‚ β”œβ”€β”€ embeddings.rs # ONNX embeddings module -β”‚ β”‚ β”œβ”€β”€ web_scraper.rs # Web scraping logic -β”‚ β”‚ β”œβ”€β”€ scheduler.rs # Task scheduling -β”‚ β”‚ └── ... -β”‚ └── Cargo.toml # Rust dependencies -└── data/ # Static data - β”œβ”€β”€ models/ # Model metadata JSON files - └── prompts/ # LLM prompt templates + +*Compiled binaries will be available in `src-tauri/target/release/bundle/` (.msi, .dmg, .app, .deb, etc.).* + +--- + +## πŸ’» Tech Stack Deep Dive + +
+ +
+ + + + +| Layer | Technologies Used | Purpose | +| --- | --- | --- | +| **Core** | Tauri 2.9, Rust 1.77 | Native desktop environment, high-performance system I/O, concurrency (Tokio). | +| **Frontend** | Next.js 16, React 19, TS | SSR-capable UI, Zustand (State), Framer Motion (Animations), Tailwind/Radix. | +| **Database** | SQLite (rusqlite 0.31) | FTS5 virtual tables for lightning-fast full-text search and session storage. | +| **AI / ML** | Ollama, ONNX Runtime | Local LLM execution and 384-dim semantic embeddings (`all-MiniLM-L6-v2`). | +| **Scraping** | headless_chrome, scraper | Parallel web automation, DOM parsing, and readability extraction. | + +--- + +## πŸ—ΊοΈ Roadmap + +* [ ] **Vector Store Integration**: Transition from SQLite BLOB embeddings to a dedicated vector DB (LanceDB or Qdrant). +* [ ] **Advanced RAG**: Multi-modal retrieval supporting images, PDFs, and local documents. +* [ ] **Cloud Sync**: Optional E2E encrypted synchronization of chat sessions across devices. +* [ ] **Custom Plugin System**: Extensible architecture for user-defined research workflows. +* [ ] **Model Fine-Tuning UI**: Native interface for training custom models on personal knowledge bases. + +--- + +## βš–οΈ License & Terms + +OllaHub is released under a custom license combining freeware and creditware models. See the [LICENSE](https://www.google.com/search?q=LICENSE) file for full legal terms. + +**TL;DR:** + +* βœ… **You may:** Use freely for personal/educational/internal use, modify, and fork the project. +* βœ… **You must:** Give visible credit to **Evandro Fonseca Junior** and link to [evandro.dev.br](https://evandro.dev.br). Keep copyright notices intact. +* ❌ **You may not:** Sell the software, bundle it in paid products, or monetize it without explicit written permission. + +For commercial licensing inquiries, please contact me via [evandro.dev.br](https://evandro.dev.br). + +--- + +
+

Built with ❀️ by Evandro Fonseca Junior

+
+ ``` - -## Design Patterns - -### Backend (Rust) - -- **Command Pattern**: Tauri commands encapsulate backend operations -- **State Management**: Arc> for shared state (browser instances, MCP processes) -- **Error Handling**: Result with custom error types and fallback strategies -- **Async/Await**: Tokio runtime for concurrent operations (scraping, MCP communication) - -### Frontend (TypeScript) - -- **Custom Hooks**: Encapsulate complex logic (deep research, chat management) -- **State Machines**: Step-based workflows (idle β†’ planning β†’ searching β†’ aggregating) -- **Optimistic Updates**: UI updates before backend confirmation -- **Streaming**: Real-time token rendering via Tauri events - -### Data Layer - -- **Repository Pattern**: Database abstraction in `db.rs` -- **Migration Strategy**: Dual storage (SQLite + JSON) with automatic fallback -- **Full-Text Search**: FTS5 virtual tables with trigger-based synchronization - -## Roadmap - -### Planned Features - -- **Vector Store Integration**: Replace SQLite BLOB embeddings with dedicated vector database (LanceDB or Qdrant) -- **Cloud Sync**: Optional encrypted synchronization of chat sessions across devices -- **Plugin System**: Extensible architecture for custom research workflows -- **Advanced RAG**: Multi-modal retrieval with image and document support -- **Model Fine-tuning UI**: Interface for training custom models on user data -- **Collaborative Features**: Shared workspaces and team collaboration - -### Technical Improvements - -- **Performance**: Optimize SQLite queries with prepared statements caching -- **Memory Management**: Implement LRU cache for embeddings model -- **Error Recovery**: Enhanced retry logic with exponential backoff -- **Testing**: Comprehensive unit and integration test coverage -- **Documentation**: API documentation with code examples - -## Contributing - -Contributions are welcome. Please follow these guidelines: - -1. **Code Style**: Follow existing patterns (Rust: `rustfmt`, TypeScript: ESLint) -2. **Commits**: Use conventional commits (feat:, fix:, docs:, etc.) -3. **Pull Requests**: Include description of changes and test results -4. **Issues**: Use GitHub Issues for bug reports and feature requests - -## License - -OllaHub is released under a custom license that combines freeware, creditware, and non-commercial restrictions. See the [LICENSE](LICENSE) file for full terms. - -### Quick Summary - -**You may:** -- Use OllaHub freely for personal, educational, and internal professional use -- Modify and distribute the Software (with proper attribution) -- Fork the project and create derivative works (with attribution) - -**You must:** -- Give credit to **Evandro Fonseca Junior** and link to [evandro.dev.br](https://evandro.dev.br) -- Keep copyright notices and attribution intact -- Not sell the Software or charge for access without written permission - -**You may not:** -- Sell the Software or bundle it in paid products (without permission) -- Use it as a monetization mechanism -- Remove attribution or copyright notices -- Collect donations on behalf of OllaHub - -For commercial licensing inquiries, visit [evandro.dev.br](https://evandro.dev.br). - -## Acknowledgments - -- [Ollama](https://ollama.ai) for local LLM execution -- [Tauri](https://tauri.app) for desktop framework -- [Radix UI](https://www.radix-ui.com) for accessible components -- [Shadcn](https://ui.shadcn.com) for component library -- [ONNX Runtime](https://onnxruntime.ai) for embeddings inference