HexAi – Inteligentny
Asystent AI

Przegląd

HexAi to w pełni lokalny asystent AI, który nie wysyła żadnych danych do zewnętrznych serwerów. System składa się z czterech głównych komponentów:

Architektura

Przepływ danych – czat (streaming)

Szybki start

Instalacja w HackerOS

HexAi jest natywną aplikacją HackerOS. Instalacja jedną komendą:

hacker unpack hexai

Aby usunąć HexAi z systemu:

hacker pack hexai

Uruchomienie po instalacji

Po wykonaniu hacker unpack hexai wszystkie komponenty są gotowe do użycia:

# Backend API (wymagany dla GUI i TUI)
hexai-server

# GUI Desktop
hexai-gui

# Terminal UI
hexai-tui

# Weryfikacja działania API
curl http://localhost:8000/health

Wymagania sprzętowe

Instalacja manualna (poza HackerOS)

Możliwa na innych dystrybucjach Linuksa ze źródeł:

# Zależności
python3.12 -m venv .venv && source .venv/bin/activate
docker run -d --name hexai-redis -p 6379:6379 redis:7-alpine

# Backend
cd source-code
pip install -r requirements.txt
python main.py

# GUI (w osobnym terminalu)
cd gui && npm install && npm run tauri-dev

# TUI (w osobnym terminalu)
cd tui && go run main.go

Backend Python

Klasy główne

ModelManager

Zarządza cyklem życia modelu Transformers. Ładuje model na żądanie i zwalnia go po idle_timeout sekundach bezczynności (domyślnie 600 s = 10 min). Zapobiega wyciekaniu pamięci GPU.

AdvancedRAG

Hybrydowe wyszukiwanie: wektorowe (ChromaDB + SentenceTransformers) + BM25 (lexicalne). Wyniki są rerankowane przez CrossEncoder (ms-marco-MiniLM-L-6-v2). Parametr alpha kontroluje balans vector/BM25.

PersistentMemory

Historia rozmów przechowywana w Redis jako listy JSON. TTL: 24 h (konfigurowalny). Obsługuje get_history, add_message, clear_session, list_sessions.

UserProfiler

Automatycznie ekstrahuje fakty o użytkowniku z rozmów (regex patterns: preferencje, stos technologiczny). Fakty przechowywane 30 dni.

DockerExecutor

Bezpieczne wykonywanie kodu Python w izolowanym kontenerze. Limity: 128 MB RAM, 50% CPU, brak dostępu do sieci, timeout 10 s, uruchomienie jako nobody.

System promptów

Wywoływanie narzędzi

Model może wywoływać narzędzia przez wzorzec w odpowiedzi:

{tool:search_web query="Python async generators"}
{tool:get_weather city="Warsaw"}

GUI Desktop (Tauri)

Aplikacja desktopowa zbudowana na Tauri 2 + Next.js 14 + TypeScript. Interfejs inspirowany Claude.ai: ciemny motyw, typografia Instrument Serif, akcenty w kolorze bursztynu.

Funkcje UI

Struktura katalogów GUI

gui/
├── src/
│   ├── pages/
│   │   └── index.tsx        # Główny interfejs czatu
│   ├── lib/
│   │   └── api.ts           # Klient API (axios + fetch streaming)
│   └── styles/
│       └── globals.css      # Tailwind base
├── src-tauri/
│   ├── src/main.rs          # Tauri host (minimalny)
│   ├── tauri.conf.json      # Konfiguracja okna i CSP
│   └── Cargo.toml
├── next.config.js           # output: 'export' (static)
└── package.json

TUI (Go)

Interfejs terminalowy napisany w Go przy użyciu Bubble Tea, Bubbles i Lip Gloss. Streaming odpowiedzi w czasie rzeczywistym, piękny ciemny motyw inspirowany Claude.

Skróty klawiszowe

Architektura TUI

Aplikacja oparta na architekturze Elm (Model–Update–View) z biblioteką Bubble Tea:

• Model – niezmenny stan aplikacji (wiadomości, ustawienia, stats)
• Update – czysta funkcja reagująca na zdarzenia (klawiatura, sieć, timer)
• View – renderowanie terminala przez Lip Gloss (styled strings)
• Streaming – goroutine czyta odpowiedź chunkami i wysyła przez p.Send()
• Stats polling – tea.Tick co 5 s odpytuje /stats

Uruchomienie / kompilacja

cd tui
# Tryb deweloperski
go run main.go

# Kompilacja binarna
go build -o hexai-tui .
./hexai-tui

Builder

Narzędzie Rust do pakowania backendu Python w samodzielny, przenośny plik binarny przy użyciu PyOxidizer.

Użycie

cd builder
cargo run --release -- --source ./source-code --out ./dist

Opcje

Kroki budowania

API – Czat

// Request
{
  "session_id": "string | null",
  "message": "string",
  "stream": false         // true → StreamingResponse (text/plain)
}

// Response (stream=false)
{
  "session_id": "uuid",
  "response": "string"
}

API – Silnik & Tryb

{ "engine": "transformers" }   // GPU
{ "engine": "ollama" }         // CPU

{ "mode": "general" }
{ "mode": "programista" }

API – RAG

{ "query": "string" }

{
  "source": "https://example.com/doc.pdf",
  "chunk_size": 500,
  "chunk_overlap": 100
}

API – Media

API – Statystyki

{
  "engine": "transformers",
  "mode": "general",
  "vram_used_gb": 4.2,
  "vram_total_gb": 8.0,
  "active_sessions": 3,
  "history_len": 0,
  "model_loaded": true,
  "model_idle_seconds": 42.1
}

Konfiguracja – Modele

Transformers (GPU)

Domyślny model: mistralai/Mistral-7B-v0.1 z kwantyzacją 4-bit (NF4). Wymaga VRAM ≥ 6 GB.

Aby zmienić model, edytuj ModelManager._load_model() w main.py:

model_id = "meta-llama/Llama-3-8B-Instruct"  # przykład

Ollama (CPU)

Ollama musi być zainstalowany i uruchomiony osobno:

curl -fsSL https://ollama.ai/install.sh | sh
ollama pull llama2
ollama pull codellama:7b-instruct   # dla trybu programista

Konfiguracja – Redis

Redis jest wymagany do przechowywania historii sesji i faktów o użytkownikach.

# Docker (zalecane)
docker run -d --name hexai-redis -p 6379:6379 redis:7-alpine

# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis

Zmiana hosta/portu Redis – edytuj w main.py:

self.redis = redis.Redis(host="localhost", port=6379, ...)

Konfiguracja – Docker (sandbox)

Docker jest opcjonalny – używany tylko do bezpiecznego wykonywania kodu Python przez narzędzie run_python.

Wdrożenie produkcyjne

Systemd service

[Unit]
Description=HexAi Backend
After=network.target redis.service

[Service]
User=hexai
WorkingDirectory=/opt/hexai/source-code
Environment="PATH=/opt/hexai/.venv/bin"
ExecStart=/opt/hexai/.venv/bin/python main.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now hexai

Nginx reverse proxy

server {
    listen 80;
    server_name hexai.local;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;   # wymagane dla streamingu
        proxy_read_timeout 300s;
    }
}

Rozwiązywanie problemów

SyntaxError: 'return' with value in async generator

Naprawiono w v2.0.0. Metody generujące odpowiedzi są teraz konsekwentnie async generatorami (yield zamiast return).

Cannot connect to Redis

docker start hexai-redis
# lub sprawdź status:
redis-cli ping

CUDA out of memory

Zredukuj max_new_tokens w _generate_transformers() lub użyj silnika Ollama (CPU).

Model nie ładuje się

Upewnij się, że zaakceptowałeś warunki licencji Mistral na HuggingFace i masz token API ustawiony:

huggingface-cli login

TUI – brak połączenia z API

Upewnij się, że backend działa: curl http://localhost:8000/health