app-ai-helper — AI Pomocník (client app)¶
Status: draft v1.0 Aktualizováno: 2026-05-27 Související:
ai-helper.md(service),apps-gateway.md,main-app.md,vendor-onboarding.md
1. Cíl¶
AI Pomocník (app-ai-helper) je end-user a admin desktop aplikace která:
- Pro koncové uživatele — chat asistent s přístupem k RAG (Legal precedenty, zákony, firemní docs)
- Pro vendory — playground na testování AI Helper capabilities před implementací do vlastní app
- Pro super_admin (AVAXIS) — admin konzole pro workery, RAG corpora, quota, usage monitoring
Je to klient nad ai-helper.md service — žádná vlastní AI logika, jen UI nad API. Spuštěná z launcher2 přes IPC session token (per c376ea3 fix).
Tři persony, jeden binár¶
super_admin (Michal, AVAXIS internal)
│
│ Vidí všechno: workery (platform), quota set, usage dashboard,
│ capability registry, RAG corpora napříč všemi firmami
│
▼ subsumes
vendor (firma s is_vendor=true, např. AVAX-LEGAL dev tým)
│
│ Plus testing playground: chat / RAG / image / speech / capability
│ explorer. Vlastní workery (dev) registr.
│
▼ subsumes
end-user (zaměstnanec firmy s AI Pomocník subscription)
│
│ Chat asistent + historie konverzací + settings.
│ Žádný admin, žádný playground.
Role je čtena z JWT (system_role + company_is_vendor). UI dynamicky skryje taby co user nemá vidět.
2. Architecture overview¶
┌─────────────────────────────┐
│ launcher2 (uživatel) │
│ - login + JWT session │
│ - klik Spustit AI Pomocník │
└─────────────┬───────────────┘
│ IPC session token
▼
┌────────────────────────────────────────────────┐
│ app-ai-helper.exe (CustomTkinter, Python) │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ Role-based tab navigation │ │
│ │ (skrývá taby co user nemá vidět) │ │
│ └──────────────────────────────────────────┘ │
│ ┌─────────────┬─────────────┬─────────────┐ │
│ │ 💬 Chat │ 🗄️ RAG │ 🎨 Image │ │
│ ├─────────────┼─────────────┼─────────────┤ │
│ │ 🎤 Speech │ 🧰 Capab. │ 🛠️ Workers │ │
│ ├─────────────┼─────────────┼─────────────┤ │
│ │ 📊 Usage │ ⚙️ Settings │ 🔍 Diagnost.│ │
│ └─────────────┴─────────────┴─────────────┘ │
│ │
│ avaxis_sdk.ai (HTTP client + SSE parser) │
└────────────────────────┬───────────────────────┘
│ HTTPS (Bearer JWT)
▼
apps-gateway → AI Helper service (per ai-helper.md)
Tech stack¶
| Vrstva | Implementace |
|---|---|
| GUI | CustomTkinter (Python, jako launcher2) |
| Klient SDK | avaxis_sdk + nový _AI namespace |
| HTTP | httpx async |
| SSE parsing | sse-starlette-compatible |
| Local state | SQLite (chat history, settings) |
| Packaging | PyInstaller přes Wine cross-build (jako vendor template) |
3. Role-based tab navigation¶
Taby viditelné per role:
| Tab | end-user | vendor | super_admin |
|---|---|---|---|
| 💬 Chat | ✅ | ✅ | ✅ |
| 📚 Konverzace (historie) | ✅ | ✅ | ✅ |
| 🗄️ RAG Corpora | — | ✅ (vlastní + grants) | ✅ (vše) |
| 🎨 Image Playground | — | ✅ | ✅ |
| 🎤 Speech Playground | — | ✅ | ✅ |
| 🎬 Video Playground | — | ✅ | ✅ |
| 🧰 Capability Explorer | — | ✅ (read) | ✅ (read+write) |
| 🛠️ Workers | — | ✅ (vlastní vendor scope) | ✅ (vše) |
| 📊 Usage | ✅ (own) | ✅ (own + company) | ✅ (vše) |
| ⚙️ Settings | ✅ | ✅ | ✅ |
| 🔍 Diagnostika | ✅ (basic) | ✅ (full) | ✅ (full + audit log) |
| 🎛️ Quota / Admin | — | — | ✅ |
UI logika: po IPC session handshake on_session() callback dostane JWT claims, podle system_role + company_is_vendor se dynamicky pack() / pack_forget() taby. Default tab = 💬 Chat pro všechny role.
4. Tab specifications¶
💬 Chat¶
Pro: všechny role
Funkce:
- Vícekonverzační chat (left sidebar list konverzací, right main panel s messages)
- SSE streaming token-by-token (POST /v1/chat/stream)
- RAG toggle (☑ Použít znalostní bázi) — pokud aktivní, query přes ai.rag.query() před LLM call a chunks injektnou do system prompt
- Model picker — dropdown z caps.chat.models (super_admin vidí všechny, end-user jen default)
- Citation panel — pod každou AI message seznam [1] [2] [3] linkujících na RAG chunks
- Konverzace persistence v local SQLite + sync s server (/v1/conversations)
UI:
┌──────────────────────────────────────────────────────────┐
│ 💬 Chat [☰ Menu] │
├──────────────────┬───────────────────────────────────────┤
│ Konverzace │ ┌─ Konverzace: Daně z mezd ──────┐ │
│ │ │ │ │
│ ➕ Nová │ │ 👤 User: Jaká je sazba daně? │ │
│ 🔍 [hledat...] │ │ │ │
│ │ │ 🤖 AI: V ČR 2024 jsou sazby: │ │
│ Dnes │ │ - 15% do limitu... │ │
│ • Daně z mezd │ │ - 23% nad limit │ │
│ • Smlouvy XYZ │ │ Zdroje: [1][2] │ │
│ Včera │ │ │ │
│ • Pojištění... │ │ 👤 User: A co dohody? │ │
│ │ │ │ │
│ │ │ 🤖 AI: (streaming...) │ │
│ │ └──────────────────────────────────┘ │
│ │ ┌──────────────────────────────────┐ │
│ │ │ Napiš zprávu... [Send] │ │
│ │ │ ☑ Použít znalostní bázi │ │
│ │ │ Model: qwen3.6-27b ▼ │ │
│ │ └──────────────────────────────────┘ │
│ │ Zdroje k poslední odpovědi: │
│ │ [1] Zákon 586/1992 §16 ▶ │
│ │ [2] Daňový pokyn GFŘ D-22 ▶ │
└──────────────────┴───────────────────────────────────────┘
📚 Konverzace (historie)¶
Pro: všechny role
Funkce: - Plný list všech konverzací (delete, rename, export) - Export do Markdown / PDF - Vyhledávání full-text v messages - Filtr per model, datum, počet tokenů
🗄️ RAG Corpora¶
Pro: vendor, super_admin
Funkce:
- Seznam accessible corpora s metadata (type, owner, count documents/chunks, embedding model)
- Filter per type (global / shared / private), per company
- Create new corpus (vendor: type 'shared' nebo 'private', super_admin: i 'global')
- Index document — file picker (PDF, DOCX, TXT, MD), drag-and-drop, S3 URL
- Document status — pending/indexing/ready/failed, progress bar pro indexing
- Grant read access (owner-app perspective) — vybere reader app slug, klik Grant
- Bulk delete documents, re-index
Layout (vendor view):
┌────────────────────────────────────────────────────────────┐
│ 🗄️ RAG Corpora │
├────────────────────────────────────────────────────────────┤
│ ➕ Nový korpus Filter: [all ▼] [Search...] │
├────────────────────────────────────────────────────────────┤
│ Korpus │ Type │ Docs │ Chunks │ Actions │
│──────────────────────┼─────────┼──────┼────────┼───────────│
│ laws-cr │ global │ 1247 │ 31420 │ 🔍 Query │
│ legal-precedents │ shared │ 86 │ 3201 │ 🔍 ⚙️ │
│ ↳ readers: mzdy, │ │ │ │ │
│ finance │ │ │ │ │
│ mzdy-payroll-history │ private │ 12 │ 458 │ 🔍 ⚙️ 🗑 │
└────────────────────────────────────────────────────────────┘
Klik na korpus → detail s:
- Document list (paginated)
- Index new document button
- Grant management (pro owner)
- Embedding model + dim (read-only po create)
🎨 Image Playground¶
Pro: vendor, super_admin
Funkce:
- Text-to-image generation (
ai.image.generate) - Model picker (workers s caps
image.generate) - Parametry: width, height, steps, CFG scale, seed, negative prompt
- Job status (queued / running / done / failed) + progress bar
- Result gallery — vygenerované obrázky session, klik na detail/download
- Image-to-image (vstup existing image + prompt)
- Vision understanding (
ai.image.understand) — upload image + prompt → text description
Layout:
┌────────────────────────────────────────────────────────────┐
│ 🎨 Image Playground │
├────────────────────────────────────────────────────────────┤
│ Mode: ◉ Generate ◯ Image-to-image ◯ Understand │
│ │
│ Prompt: │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Logo firmy AVAXIS, minimalist, blue gradient │ │
│ └──────────────────────────────────────────────────────┘ │
│ Negative: (volitelné) │
│ │
│ Model: [sdxl-base ▼] Steps: [30] CFG: [7.5] │
│ Size: [1024x1024 ▼] Seed: [random] │
│ │
│ [🎨 Generate] Status: queued (worker gerry)│
│ Progress: ▓▓▓▓▓░░░ 60% │
│ │
│ ┌─── Galerie ───────────────────────────────────────────┐ │
│ │ [img1] [img2] [img3] [img4] │ │
│ │ Klik pro detail / download │ │
│ └────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
🎤 Speech Playground¶
Pro: vendor, super_admin
Funkce:
- Speech-to-text — file upload (mp3, wav, ogg) nebo mic recording → text + timestamps
- Text-to-speech — text input → audio playback + download
- Language picker (cs, en, …)
- Voice picker pro TTS (workers s caps
text.to_speechmajívoiceslist) - Live streaming variant pro STT (mic → SSE → text živě)
🎬 Video Playground¶
Pro: vendor, super_admin
Funkce:
- Text-to-video generation (model
wan2,animatediff, …) - Image-to-video (vstup image + motion prompt)
- Parametry: duration (s), fps, resolution
- Async job s longer timeouts (minuty)
- Result preview + download
🧰 Capability Explorer¶
Pro: vendor (read), super_admin (read + write)
Funkce:
- Seznam všech registered capabilities (z
ai_helper.capabilitytable) - Per capability: schema JSON, příklady payload, workers co ji deklarují
- Generic call form — vyber capability, vyplň payload (form generated z JSON schema), submit → result
- Super_admin: register new capability ID + schema
Layout:
┌────────────────────────────────────────────────────────────┐
│ 🧰 Capability Explorer │
├────────────────────────────────────────────────────────────┤
│ Filter: [all ▼] [Search...] │
├────────────────────────────────────────────────────────────┤
│ Capability │ Category │ Workers │
│─────────────────────────────────────┼──────────┼───────────│
│ chat │ core │ 2 │
│ chat.complete │ core │ 2 │
│ embed │ core │ 2 │
│ image.generate │ core │ 1 │
│ text_understanding.ner │ ext │ 1 │
│ text_understanding.summarize │ ext │ 2 │
│ custom.legal.contract_extract │ custom │ 1 │
└────────────────────────────────────────────────────────────┘
Detail (klik na řádek):
┌────────────────────────────────────────────────────────────┐
│ text_understanding.ner │
│ │
│ Description: Named Entity Recognition pro CZ/EN texty │
│ │
│ Input schema: │
│ { │
│ "text": "string (required)", │
│ "language": "cs | en (default: auto)" │
│ } │
│ │
│ Output schema: │
│ { │
│ "entities": [ │
│ {"type": "PERSON|ORG|DATE|MONEY|LAW", ...} │
│ ] │
│ } │
│ │
│ Workers: gerry (lmstudio with system prompt), bert-ner-cz │
│ │
│ ┌─── Generic call form ─────────────────────────────────┐ │
│ │ text: ┌─────────────────────────────────────────────┐│ │
│ │ │ Jan Novák podepsal smlouvu s ABC dne 12.5. ││ │
│ │ └─────────────────────────────────────────────┘│ │
│ │ language: [auto ▼] │ │
│ │ [▶ Run] │ │
│ │ │ │
│ │ Result: │ │
│ │ { │ │
│ │ "entities": [ │ │
│ │ {"type": "PERSON", "value": "Jan Novák", ...}, │ │
│ │ {"type": "ORG", "value": "ABC", ...}, │ │
│ │ {"type": "DATE", "value": "2024-05-12", ...} │ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
🛠️ Workers¶
Pro: vendor (jen vlastní scope=vendor worker), super_admin (vše)
Funkce:
- Seznam workers s metadata (kind, scope, status, VRAM, models loaded, queue depth, capabilities)
- Filter per scope (platform / vendor / company), status, environment (dev/staging/prod)
- Register new worker (formulář — name, kind, transport_class, base_url, capabilities JSON, environment)
- Health check (live ping)
- Disable / re-enable
- Detail: usage stats, recent jobs, last health checks
Super_admin vidí všechny workers napříč scopes. Vendor vidí jen scope=vendor AND owner_vendor_id=<my>.
📊 Usage¶
Pro: všechny role (scope se liší)
Funkce — read-only (MVP):
- end-user: moje usage tento měsíc (počet zpráv, tokens, latency average)
- company_admin: plus company-wide (top apps, top capabilities, denní graf)
- super_admin: plus napříč firmami, top tenants, alerts (workers down, errors spike)
Layout (super_admin):
┌────────────────────────────────────────────────────────────┐
│ 📊 Usage — Květen 2026 (do dnes) │
├────────────────────────────────────────────────────────────┤
│ Total requests: 12,485 Total tokens: 4,531,200 │
│ Active companies: 23 Active workers: 5/7 online │
│ │
│ ┌── Denní graf (last 30 days) ────────────────────────┐ │
│ │ ▁▂▃▅▆▇█▇▆▅▄▃▂▁▁▂▃▅▆▇█▇▆▅▄▃▂▁ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Top capabilities: Top apps: │
│ 1. chat.stream 42% 1. app-ai-helper 35% │
│ 2. embed 28% 2. app-legal 28% │
│ 3. text_und.* 18% 3. app-mzdy 12% │
│ 4. rag.query 8% 4. ... │
│ │
│ Top tenants (companies): │
│ 1. AVAXIS s.r.o. 42% (4.2M tokens) │
│ 2. Klient XYZ 28% (2.8M) │
│ 3. ... │
└────────────────────────────────────────────────────────────┘
⚙️ Settings¶
Pro: všechny role
Funkce:
- Default model preference per modality
- RAG default settings (top_k, threshold)
- Notification settings (job done sound, etc.)
- API key (pro vendor mode — service token pro testing)
- Reset chat history, clear local cache
🔍 Diagnostika¶
Pro: všechny role
Funkce:
- Backend URL + connectivity check (ping AI Helper /health)
- Session info (token expiry, user info, claims)
- IPC channel status (connected to launcher)
- Last 50 API calls (super_admin: all, vendor: own app, user: own user)
- Export log (pro support request)
🎛️ Quota / Admin¶
Pro: super_admin only
Funkce:
- View quotas per company / per app / per api_client
- Set quota (monthly tokens, rate limit)
- Block / unblock client
- Audit log — historie super_admin akcí
- Capability registry write — register new capability ID + schema
5. Auth + IPC integration¶
Launcher → app session handshake¶
Per apps-gateway.md § auth + launcher2 0.6.45 (commit c376ea3):
- User klik Spustit AI Pomocník v launcher2
- Launcher2
installer.launch(slug, session)spustíapp-ai-helper.exe+ IPC server - App-ai-helper přes SDK
app.connect() + app.ready() - Launcher přijme
ready→ pošle{"type": "session", "access_token": ..., user_id, ...} - SDK uloží do
app.access_token,app.user_email,app.company_id,app.system_role,app.company_is_vendor - UI dynamicky inicializuje taby per role
Token refresh¶
- Access token má 15min expiry
- SDK periodicky check (every 5 min): pokud token expiruje za <2 min, request
/auth/refreshna core-api srefresh_token - Pokud refresh selže (refresh_token vypršel), launcher dostane IPC
session_expired→ re-login prompt v launcher
Backend volání¶
Všechna volání AI Helper z UI jdou přes SDK:
URL: {platform_url}/apps/app-ai-helper/v1/* (z launcher session).
Headers:
- Authorization: Bearer {access_token}
- Content-Type: application/json
- X-Caller-App: app-ai-helper (pro AI Helper service ACL — i když caller je sám sebe, kvůli quota tracking)
6. Local state — SQLite¶
Tables¶
CREATE TABLE conversation (
id TEXT PRIMARY KEY,
title TEXT,
model TEXT,
use_rag INTEGER DEFAULT 0,
created_at TIMESTAMP,
updated_at TIMESTAMP
);
CREATE TABLE message (
id TEXT PRIMARY KEY,
conversation_id TEXT REFERENCES conversation(id),
role TEXT, -- 'user' | 'assistant' | 'system'
content TEXT,
citations TEXT, -- JSON list of chunk_ids
tokens INTEGER,
created_at TIMESTAMP
);
CREATE TABLE settings (
key TEXT PRIMARY KEY,
value TEXT
);
CREATE TABLE call_log (
id INTEGER PRIMARY KEY AUTOINCREMENT,
capability TEXT,
duration_ms INTEGER,
status_code INTEGER,
request_summary TEXT,
created_at TIMESTAMP
);
Path: %LOCALAPPDATA%/Avaxis/apps/app-ai-helper/current/data/ai-helper.db.
Optional sync s serverem (POST /v1/conversations create + GET /v1/conversations/{id}/messages) — uživatel může pokračovat z jiného PC. MVP local only, sync v 1.1.
7. Roadmap¶
MVP (1.0)¶
- ✅ Chat (SSE) s RAG toggle + model picker + citations panel (0.3.5 implementováno)
- ⏳ Konverzace historie (basic, local SQLite)
- ⏳ RAG corpora tab (list + create + index document + grant)
- ⏳ Image playground (text-to-image, async job + gallery)
- ⏳ Speech playground (STT + TTS basic)
- ⏳ Capability explorer (list + detail + generic call form)
- ⏳ Workers tab (vendor's own scope, super_admin all)
- ⏳ Usage tab (read-only, per role scope)
- ⏳ Settings (basic preferences)
- ⏳ Diagnostika (token, backend URL, IPC status)
- ⏳ Quota / Admin tab (super_admin only)
1.1 — server-side conversation sync¶
- Cross-device chat history sync
- Webhooks pro long jobs (image gen done notification)
- Voice playground live streaming (mic → SSE → text)
1.5 — UI polish¶
- Drag-and-drop document upload do RAG
- Better citations preview (popup s chunk preview, ne jen ID)
- Image gallery s ratings (👍 / 👎 pro fine-tune future signal)
- Dark/light theme sync s launcher
2.0 — advanced¶
- Multi-modal chat (image upload + text prompt v jednom messages)
- Long-term memory (persistent user preferences přes konverzace)
- Custom assistant builder (user definuje system prompt + RAG corpora preset)
- Multi-language UI (CZ/EN/SK)
8. Souvislost s AI Helper service¶
| Feature v app-ai-helper UI | Backend endpoint v AI Helper service |
|---|---|
| 💬 Chat stream | POST /v1/chat/stream (SSE) |
| 📚 Konverzace sync | GET/POST /v1/conversations |
| 🗄️ List corpora | GET /v1/rag/corpora |
| 🗄️ Create corpus | POST /v1/rag/corpora |
| 🗄️ Index document | POST /v1/rag/documents → poll job |
| 🗄️ Grant read | POST /v1/rag/corpora/{id}/grants |
| 🎨 Image generate | POST /v1/image/generate → poll job |
| 🎨 Image understand | POST /v1/image/understand (sync) |
| 🎤 STT | POST /v1/speech/to-text |
| 🎤 TTS | POST /v1/speech/from-text |
| 🎬 Video generate | POST /v1/video/generate → poll job |
| 🧰 List capabilities | GET /v1/capabilities |
| 🧰 Generic call | POST /v1/call/{capability_id} |
| 🛠️ Workers list | GET /v1/workers |
| 🛠️ Register worker | POST /v1/workers |
| 📊 Usage me | GET /v1/usage/me |
| 📊 Usage company | GET /v1/usage/company |
| 🎛️ Quota set | PUT /v1/admin/quota/{id} |
App-ai-helper je tedy thin UI client — žádná business logika v UI, jen API calls + presentation.
9. Distribuce¶
- Slug:
app-ai-helper - Repo:
git.avaxis.cz/avax-apps/app-ai-helper-app - Distribution bucket:
app-app-ai-helper - Channels: alpha (dev), beta (early access), stable (general)
- AVAXIS firma má subscription na alpha (dev test)
- Pricing tier: TBD (per-month seat? per-token?)
10. Související¶
ai-helper.md— service spec (backend co tato UI volá)apps-gateway.md— routing/apps/app-ai-helper/*per-app-container.md— backend kontejner deploymain-app.md— launcher2 IPC session protocolvendor-onboarding.md— jak vendor onboard použije AI Helper v vlastní app