Revise README for better clarity and structure

Updated README to enhance clarity and organization, including a new structure for features and installation instructions.
This commit is contained in:
Evandro Fonseca Junior authored and GitHub committed 2026-02-22 07:35:40 -03:00
1 parent bd1e3ca2e6
commit e6d41478ac
1 file changed
+114 -266
+114 -266
View File
@@ -1,85 +1,59 @@
# OllaHub <div align="center">
<h1>🧠 OllaHub</h1>
<p><strong>Local-first LLM workspace with deep research capabilities and native OS integration.</strong></p>
Local-first LLM workspace with deep research capabilities and native OS integration. <p align="center">
<a href="https://www.rust-lang.org/"><img src="https://img.shields.io/badge/Rust-1.77.2-orange.svg?style=flat-square&logo=rust" alt="Rust"></a>
<a href="https://tauri.app/"><img src="https://img.shields.io/badge/Tauri-2.9.2-24C8DB.svg?style=flat-square&logo=tauri" alt="Tauri"></a>
<a href="https://nextjs.org/"><img src="https://img.shields.io/badge/Next.js-16.0.3-black.svg?style=flat-square&logo=next.js" alt="Next.js"></a>
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.0-blue.svg?style=flat-square&logo=typescript" alt="TypeScript"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-Custom-blue.svg?style=flat-square" alt="License"></a>
</p>
[![Rust](https://img.shields.io/badge/Rust-1.77.2-orange.svg)](https://www.rust-lang.org/) <br>
[![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 </div>
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 ## ✨ Key Features
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
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 ### 🔌 MCP (Model Context Protocol) Integration
- **ONNX Embeddings**: Local semantic similarity using all-MiniLM-L6-v2 (384-dimensional embeddings) Extensible by design. Connect external tools via MCP servers:
- **SQLite with FTS5**: Full-text search with virtual tables for session titles and message content * **Tool Discovery:** Automatic enumeration of available tools from running servers.
- **Hybrid Storage**: Dual persistence (SQLite + JSON) with automatic migration and fallback * **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 ## 🏗️ System Architecture
- **JSON (Legacy)**: Maintained for backward compatibility and export functionality
- **Automatic Migration**: Seamless transition from JSON to SQLite with data preservation
### Reactive UI <details>
<summary><b>Click to view Architecture Diagram</b></summary>
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
```mermaid ```mermaid
graph TB graph TB
@@ -127,232 +101,106 @@ graph TB
style Bridge fill:#7c3aed,color:#fff style Bridge fill:#7c3aed,color:#fff
style Backend fill:#dc2626,color:#fff style Backend fill:#dc2626,color:#fff
style External fill:#059669,color:#fff style External fill:#059669,color:#fff
``` ```
### Data Flow </details>
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 ## 🚀 Getting Started
### 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
### Prerequisites ### Prerequisites
- **Node.js**: 20.x or later Before you begin, ensure you have the following installed:
- **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`
### 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 ```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 cd OllaHub
``` ```
2. Install dependencies:
2. **Install dependencies:**
```bash ```bash
pnpm install pnpm install
``` ```
3. Run in development mode:
3. **Run in development mode:**
```bash ```bash
pnpm tauri dev pnpm tauri dev
``` ```
This command will:
- Start the Next.js development server on `http://localhost:3000` *This starts the Next.js server (`localhost:3000`), builds the Rust backend, and launches the Tauri native window.*
- Build the Rust backend
- Launch the Tauri application window
### Building for Production ### Building for Production
```bash ```bash
pnpm tauri build 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) *Compiled binaries will be available in `src-tauri/target/release/bundle/` (.msi, .dmg, .app, .deb, etc.).*
│ ├── chat/ # Chat interface
│ ├── settings/ # Application settings ---
│ ├── setup/ # Initial setup wizard
│ └── tasks/ # Task management ## 💻 Tech Stack Deep Dive
├── components/ # React components
│ ├── chat/ # Chat-specific components <div align="center">
│ ├── settings/ # Settings UI components <img src="https://www.google.com/search?q=https://skillicons.dev/icons%3Fi%3Drust,tauri,nextjs,react,ts,tailwind,sqlite" />
│ ├── setup/ # Setup wizard components </div>
│ └── 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 | Layer | Technologies Used | Purpose |
│ └── ... | --- | --- | --- |
├── lib/ # Utility functions | **Core** | Tauri 2.9, Rust 1.77 | Native desktop environment, high-performance system I/O, concurrency (Tokio). |
│ ├── knowledge-base-processor.ts # Context condensation | **Frontend** | Next.js 16, React 19, TS | SSR-capable UI, Zustand (State), Framer Motion (Animations), Tailwind/Radix. |
│ ├── contextual-analyzer.ts # Query analysis | **Database** | SQLite (rusqlite 0.31) | FTS5 virtual tables for lightning-fast full-text search and session storage. |
│ ├── query-enricher.ts # Query expansion | **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. |
├── services/ # Service layer
│ └── webSearch.ts # Web search abstraction ---
├── store/ # Zustand stores
│ └── settings-store.ts # Application settings ## 🗺️ Roadmap
├── src-tauri/ # Rust backend
│ ├── src/ * [ ] **Vector Store Integration**: Transition from SQLite BLOB embeddings to a dedicated vector DB (LanceDB or Qdrant).
│ │ ├── lib.rs # Main Tauri commands * [ ] **Advanced RAG**: Multi-modal retrieval supporting images, PDFs, and local documents.
│ │ ├── db.rs # SQLite database layer * [ ] **Cloud Sync**: Optional E2E encrypted synchronization of chat sessions across devices.
│ │ ├── embeddings.rs # ONNX embeddings module * [ ] **Custom Plugin System**: Extensible architecture for user-defined research workflows.
│ │ ├── web_scraper.rs # Web scraping logic * [ ] **Model Fine-Tuning UI**: Native interface for training custom models on personal knowledge bases.
│ │ ├── scheduler.rs # Task scheduling
│ │ └── ... ---
│ └── Cargo.toml # Rust dependencies
└── data/ # Static data ## ⚖️ License & Terms
├── models/ # Model metadata JSON files
└── prompts/ # LLM prompt templates 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).
---
<div align="center">
<p>Built with ❤️ by <a href="https://github.com/evandrodevbr">Evandro Fonseca Junior</a></p>
</div>
``` ```
## Design Patterns
### Backend (Rust)
- **Command Pattern**: Tauri commands encapsulate backend operations
- **State Management**: Arc<Mutex<>> for shared state (browser instances, MCP processes)
- **Error Handling**: Result<T, E> 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