evandro/OllaHub
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Revise README for better clarity and structure

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+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/)
[![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)
<br>
## 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
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
<details>
<summary><b>Click to view Architecture Diagram</b></summary>
```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
</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
### 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
<div align="center">
<img src="https://www.google.com/search?q=https://skillicons.dev/icons%3Fi%3Drust,tauri,nextjs,react,ts,tailwind,sqlite" />
</div>
| 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).
---
<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