From f0b7db8c12000ae09d608f40b04729d7da81bf65 Mon Sep 17 00:00:00 2001 From: Evandro Fonseca Junior Date: Sat, 24 Oct 2026 04:54:38 -0300 Subject: [PATCH] docs(readme): redesenha o README com hero em SVG [skip ci] --- README.md | 159 ++++++++++++----------------------------- assets/readme/hero.svg | 59 +++++++++++++++ 2 files changed, 106 insertions(+), 112 deletions(-) create mode 100644 assets/readme/hero.svg diff --git a/README.md b/README.md index 36280a9..45de6f9 100644 --- a/README.md +++ b/README.md @@ -1,119 +1,44 @@
-OllaHub icon +OllaHub: desktop chat for your local Ollama models, with web search and MCP tools -# OllaHub +![Version 0.1.0](https://img.shields.io/badge/version-0.1.0-555?style=flat-square) +![Tauri 2](https://img.shields.io/badge/Tauri-2-24C8DB?style=flat-square&logo=tauri&logoColor=white) +![Next.js 16](https://img.shields.io/badge/Next.js-16.0.3-000000?style=flat-square&logo=nextdotjs&logoColor=white) +![React 19](https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=black) +![Platforms](https://img.shields.io/badge/platforms-Windows_%7C_macOS_%7C_Linux-1447e6?style=flat-square) -**A desktop chat for your local Ollama models — it scans your hardware, recommends and downloads a model, and -can enrich answers with web search, MCP tools and scheduled tasks, all driven by a Rust (Tauri) backend.** - -![Version](https://img.shields.io/badge/version-0.1.0-informational) -![Tauri](https://img.shields.io/badge/Tauri-2-informational) -![Next.js](https://img.shields.io/badge/Next.js-16.0.3-informational) - -[Features](#features) · [Install](#install) · [How it works](#how-it-works) · [Limitations](#known-limitations) · [Build](#build-and-run-locally) · [CI/CD](#cicd) +[Quick start](#quick-start) · [Docs](docs/) · [Issues](https://git.evandro.dev.br/evandro/OllaHub/issues)
-> [!NOTE] -> **Project status:** early (`0.1.0`, 47 commits from 2025-10-27 to 2025-11-27). The setup flow, chat, session -> history, model management, web search, MCP, scheduled tasks and auto-update are implemented. The repository has -> no license file and no automated test script (`package.json` only defines `dev`, `build`, `start`, `lint`, -> `generate-changelog` and `bump-version`). A few settings are placeholders — see -> [Known limitations](#known-limitations). +## What it is -> [!IMPORTANT] -> **OllaHub is a client for [Ollama](https://ollama.com), not a model runtime.** It talks to the Ollama API -> (default `http://localhost:11434`, configurable in Settings), tries to start it when it is installed but -> stopped, and can download the Ollama installer when it is missing. Chats are stored locally in a SQLite -> database (`ollahub.db` in the app data directory); web search is the part that reaches the internet. +OllaHub is a desktop chat app for the models you run with [Ollama](https://ollama.com). On first run it scans your hardware, recommends a model and downloads it. After that it chats with streaming, keeps history in a local SQLite database, and can add context from web search, MCP tools and scheduled tasks. The UI is Next.js inside a Tauri 2 window, and a Rust backend does the work. -## Features +OllaHub is a client, not a model runtime. It talks to the Ollama API (default `http://localhost:11434`, configurable in Settings), tries to start Ollama when it is installed but stopped, and can download the Ollama installer when it is missing. -| Area | What it does | -|---|---| -| **First-run setup** | Hardware scan (CPU, RAM, GPUs), GPU selector and a model recommendation for your specs, then straight into the chat | -| **Chat** | Streaming responses from the Rust backend (`chat_stream`), Markdown with syntax-highlighted code blocks, reasoning/thinking steps, source carousel, message actions, resizable sidebar | -| **Sessions** | Local history in SQLite with FTS5 full-text search, paginated loading, automatic title + emoji for new chats (model-generated, with a fallback to the first words), export of sessions or all data, delete/clear | -| **Models** | List and delete local models, pull with progress (percent, speed), install a `.gguf` file, hardware-aware recommendation | -| **Web search** | Headless Chrome scraping across Google, Bing, Yahoo, DuckDuckGo and Startpage (configurable engine order), categories and custom sites, excluded domains, concurrency/timeout/result limits, semantic query expansion (pt-BR / en / es), engine circuit breaker and failure cache, progressive fallback | -| **Relevance and context** | Local embeddings (`all-MiniLM-L6-v2` via ONNX Runtime) rank and prune scraped content, with a BM25-like fallback when the embedding model is unavailable; chunking, condensation and key-facts extraction are configurable | -| **Deep research** | Multi-step mode: planning → searching → aggregating → validating → formulating | -| **MCP** | Configure servers in a JSON editor (`mcp_config.json`), start/stop/restart them as child processes, list and call their tools from the chat | -| **Scheduled tasks** | Cron-based tasks (`tokio-cron-scheduler`) with three actions — search and summarize, plain notification, custom prompt — persisted in `tasks.json` | -| **System monitor** | CPU/RAM stats and GPU VRAM, usage and temperature dashboards (GPU detection per OS: `wmic`/`nvidia-smi` on Windows, with Linux and macOS paths) | -| **Updates** | Tauri updater with signed releases; the automatic check is on by default | -| **Desktop shell** | Custom title bar, light/dark theme, desktop notifications | +## Why use it -## Install +- **Local by default.** Prompts go to your own Ollama, and chats live in `ollahub.db` in the app data directory, with FTS5 full-text search. Besides downloads (models, the embedding model, updates), web search is what reaches the internet. +- **Web answers ranked on your machine.** Headless Chrome scrapes Google, Bing, Yahoo, DuckDuckGo and Startpage (order configurable), then local embeddings (`all-MiniLM-L6-v2` on ONNX Runtime) rank and prune the pages, with a BM25-like fallback when the embedding model is unavailable. A deep-research mode runs planning → searching → aggregating → validating → formulating. +- **More than a chat box.** MCP servers run as child processes configured in `mcp_config.json`, their tools can be called from the chat, and cron tasks (search and summarize, notification, custom prompt) keep running in the background. -Installers are produced by the [release workflow](#cicd) for Windows (`msi`), macOS (`dmg`, Apple Silicon and -Intel) and Linux (`AppImage`); see the repository's -[Releases](https://git.evandro.dev.br/evandro/OllaHub/releases). You can also -[build it locally](#build-and-run-locally). - -> [!WARNING] -> **Two things the app does on its own.** -> 1. Opening the chat page pulls the small helper model **`qwen2.5:0.5b`** if it is not installed yet (a -> "Baixando modelo de IA" progress appears) — expect an extra download on first use. -> 2. **Closing the window only hides it.** The close request is intercepted (`prevent_close`) so scheduled tasks -> keep running, but the code has no tray icon to bring the window back — the system-tray step is still listed -> as pending in [`IMPLEMENTATION_GUIDE.md`](IMPLEMENTATION_GUIDE.md). +**When not to use it:** if you want a finished, tested product (version `0.1.0`, no test suite), a model runtime of its own, or a server you can run without a desktop. ## How it works -```mermaid -flowchart LR - UI["Next.js 16 UI
static export · chat · setup · settings · tasks"] -- "Tauri invoke / events" --> RS["Tauri 2 backend (Rust)
src-tauri/src/lib.rs"] - RS --> OL["Ollama API
chat · pull · tags"] - RS --> DB[("SQLite ollahub.db
sessions · messages · FTS5")] - RS --> WEB["web_scraper.rs
headless Chrome · search engines"] - RS --> EMB["embeddings.rs
MiniLM ONNX · BM25 fallback"] - RS --> MCP["MCP servers
child processes · JSON-RPC"] - RS --> SCH["scheduler
cron tasks"] - SCH --> OL - SCH --> WEB -``` +- **Frontend** (`app/`, `components/`, `hooks/`, `lib/`, `store/`): Next.js 16 with `output: 'export'`, React 19, Tailwind 4, Radix UI and Zustand. It calls the backend through Tauri `invoke` and events. +- **Backend** (`src-tauri/src/`): `lib.rs` holds the commands for chat (`chat_stream`), models, the Ollama lifecycle, sessions, MCP, search, tasks, export and the installer. `db.rs` handles SQLite, `web_scraper.rs` the search engines, `embeddings.rs` the ranking, and `scheduler.rs` the cron tasks stored in `tasks.json`. +- **Models:** list, delete and pull with progress, install a local `.gguf` file, and get a recommendation for your hardware. +- **System monitor:** CPU and RAM stats plus GPU VRAM, usage and temperature. GPU detection uses `wmic` and `nvidia-smi` on Windows and `lspci` on Linux. +- **Updates:** the Tauri updater checks automatically. Its endpoint in `src-tauri/tauri.conf.json` points to a GitHub Releases `latest.json`. -
-Technical details +More notes: [`docs/updater-setup.md`](docs/updater-setup.md) (signing keys and updater) and [`docs/style-guide.md`](docs/style-guide.md) (UI spacing, radii, accessibility). -| Piece | Where | Notes | -|---|---|---| -| Frontend | `app/`, `components/`, `hooks/`, `lib/`, `store/` | Next.js 16 (App Router, `output: 'export'`, built with webpack), React 19, Tailwind 4, Radix UI, Zustand store persisted for settings, `react-markdown` + `remark-gfm`, Framer Motion | -| Backend | `src-tauri/src/` | `lib.rs` (commands for chat, models, Ollama lifecycle, sessions, MCP, search, tasks, export, installer), `db.rs`, `ollama_client.rs`, `web_scraper.rs`, `embeddings.rs`, `intent_classifier.rs`, `system_monitor.rs`, `scheduler.rs`, `scheduler_loop.rs`, `task_executor.rs`, `sources_config.rs` | -| Web search | `web_scraper.rs`, `services/`, `lib/web-search-fallback.ts` | Orchestrated from the frontend (query preprocessing, expansion, progressive multi-round fallback) with scraping done in Rust; `intent_classifier.rs` classifies a query as factual / conversational / technical / opinion / calculation by keyword heuristics | -| Embeddings | `embeddings.rs` | Model and tokenizer downloaded from Hugging Face; the ONNX Runtime library is downloaded automatically on Windows, elsewhere the system library path is tried | -| Persistence | app data dir | `ollahub.db` (SQLite, bundled `rusqlite`), `mcp_config.json`, `tasks.json`; browser `localStorage` for the setup-complete flag | -| Prompts | `data/prompts/` | Default response format, deep-research and prompt-generator prompts | -| Model catalog | `data/models/` | 188 JSON files describing Ollama library models (variants, sizes, context); not referenced by the app code | -| Release tooling | `scripts/` | `generate-changelog.js` (builds `data/changelog.json` from `feat`/`fix` commits), `bump-version.js` (updates `package.json`, `tauri.conf.json` and `Cargo.toml`) | +## Quick start -Further notes: [`docs/updater-setup.md`](docs/updater-setup.md) (signing keys and updater setup), -[`docs/style-guide.md`](docs/style-guide.md) (UI spacing, radii, accessibility) and -[`IMPLEMENTATION_GUIDE.md`](IMPLEMENTATION_GUIDE.md) (tray, background mode and task scheduler). -
- -## Known limitations - -- **No tray icon yet:** closing the window hides it (see the warning above). -- **"Start with the system" does nothing yet:** the setting only toggles a stored flag; the code carries a - `TODO` until `tauri-plugin-autostart` is configured. -- **RAG inside `chat_stream` is not wired:** the `enable_rag` branch is commented out as `TODO`; web context is - assembled by the frontend before the request. -- **Unused leftovers:** `src-tauri/scripts/scraper.py` (a `curl_cffi`/BeautifulSoup scraper) and the Python - bootstrap hook/component are not called by the Rust backend; scraping is done by `headless_chrome`. -- **Embeddings outside Windows:** the ONNX Runtime library is only auto-downloaded on Windows; on macOS/Linux - provide it in the app data folder or on the system path, otherwise ranking falls back to BM25-like scoring. -- **Updater endpoint:** it is configured in `src-tauri/tauri.conf.json` and points to a GitHub Releases - `latest.json`; update it if releases are published elsewhere. - -## Build and run locally - -Requirements (from the CI workflow): Node.js 20, pnpm 8, a stable Rust toolchain and the -[Tauri 2 prerequisites](https://tauri.app/start/prerequisites/). On Ubuntu the workflow installs -`libwebkit2gtk-4.1-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev patchelf`. [Ollama](https://ollama.com) -is needed at runtime. +No release is published on this repository yet, so build it locally. You need Node.js 20, pnpm 8, a stable Rust toolchain and the [Tauri 2 prerequisites](https://tauri.app/start/prerequisites/) (the versions come from the CI workflow). On Ubuntu the workflow also installs `libwebkit2gtk-4.1-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev patchelf`. Ollama is needed at runtime. ```bash git clone https://git.evandro.dev.br/evandro/OllaHub.git @@ -126,21 +51,31 @@ pnpm lint # ESLint pnpm bump-version # patch | minor | major, optional --commit ``` -## CI/CD +The workflow [`.github/workflows/release.yml`](.github/workflows/release.yml) builds `msi` (Windows), `dmg` (macOS, Apple Silicon and Intel) and `AppImage` (Linux) on pushes to `main`, `master` and `develop`, and publishes release `v` on pushes to `main` or `master`. -The workflow [`.github/workflows/release.yml`](.github/workflows/release.yml) (**Build and Release**, read by -Gitea Actions) runs on **pushes to `main`, `master` and `develop`** and on manual dispatch: +> [!WARNING] +> **Two things the app does on its own.** +> 1. Opening the chat page pulls the small helper model **`qwen2.5:0.5b`** if it is not installed yet, used for automatic chat titles. Expect an extra download on first use. +> 2. **Closing the window only hides it.** The close request is intercepted (`prevent_close`) so scheduled tasks keep running, but there is no tray icon to bring the window back yet; the tray step is still pending in [`IMPLEMENTATION_GUIDE.md`](IMPLEMENTATION_GUIDE.md). -- **`build`** — matrix on Windows (`msi`), macOS aarch64 and x86_64 (`dmg`) and Ubuntu (`appimage`): installs - pnpm 8, Node 20 and Rust, runs `pnpm install --frozen-lockfile`, generates the changelog, builds the Tauri app - and bundle (signing with the `TAURI_UPDATER_PRIVATE_KEY` secret when it is set) and uploads the installers as - artifacts (7 days). -- **`create-release`** — only on pushes to `main`/`master`: reads the version from `package.json`, builds release - notes from `data/changelog.json` and publishes release `v` with the downloaded artifacts. +## Project status -## Notices +Early: version `0.1.0`, 47 commits between 2025-10-27 and 2025-11-27, no automated tests (`package.json` defines `dev`, `build`, `start`, `lint`, `generate-changelog` and `bump-version`). Known limitations: -Built with [Tauri](https://tauri.app), [Next.js](https://nextjs.org), [Radix UI](https://www.radix-ui.com), -[Tailwind CSS](https://tailwindcss.com), [Zustand](https://zustand-demo.pmnd.rs), [Lucide](https://lucide.dev), -[headless_chrome](https://github.com/rust-headless-chrome/rust-headless-chrome), [ONNX Runtime](https://onnxruntime.ai) -and the [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) model. +- **No tray icon yet:** closing the window hides it (see the warning above). +- **"Start with the system" does nothing yet:** the setting only toggles a stored flag; the code has a `TODO` until `tauri-plugin-autostart` is configured. +- **RAG inside `chat_stream` is not wired:** the `enable_rag` branch is commented out as `TODO`; the frontend assembles web context before the request. +- **Embeddings outside Windows:** the ONNX Runtime library is downloaded automatically only on Windows. On macOS and Linux, provide it in the app data folder or on the system path, otherwise ranking falls back to BM25-like scoring. +- **Unused leftovers:** `src-tauri/scripts/scraper.py` is not called by the Rust backend, and the 188 model files in `data/models/` are not referenced by the app code. + +## License + +No published license: all rights reserved. + +Built with [Tauri](https://tauri.app), [Next.js](https://nextjs.org), [Radix UI](https://www.radix-ui.com), [Tailwind CSS](https://tailwindcss.com), [Zustand](https://zustand-demo.pmnd.rs), [Lucide](https://lucide.dev), [headless_chrome](https://github.com/rust-headless-chrome/rust-headless-chrome), [ONNX Runtime](https://onnxruntime.ai) and the [all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) model. + +
+ +Made by Evandro Fonseca Junior · git.evandro.dev.br + +
diff --git a/assets/readme/hero.svg b/assets/readme/hero.svg new file mode 100644 index 0000000..0c23cbc --- /dev/null +++ b/assets/readme/hero.svg @@ -0,0 +1,59 @@ + + OllaHub + OllaHub: a desktop window with a chat sidebar, a local Ollama model download in progress, an answer backed by numbered web sources, and Web and MCP toggles in the message box. + + + + + OllaHub + Desktop chat for your local Ollama + models, with web search and MCP. + Tauri 2 · Rust · Next.js 16 · React 19 + + + + + + OllaHub + + + + + + + + + + New chat + + + + + + qwen2.5:0.5b + + + + + + + + Sources + + + 1 + + 2 + + 3 + + + + + Web + + MCP + + + +