Kyber — AI-Powered Smart Home Assistant for Home Assistant

⚠️ Beta software — Kyber is production-ready for home use but still evolving rapidly. Your AI now has a key to the house. Literally.

Kyber lets an AI control your lights, thermostats, automations, scripts, and dashboards — in natural language, no confirmation required (in Autopilot Mode). It won't judge you for having 47 automations that do the same thing, but it might just clean them up if you ask. The AI can modify your Home Assistant configuration — automations, scripts, entities and dashboards. Always review proposals before executing them, keep backups, and remember we are not responsible for your living room turning into a disco at 3am.

Kyber is a local AI chat panel for Home Assistant, powered by your Ollama instance. Chat with your smart home, manage entities, edit automations, and build dashboards — all without leaving HA.

Install via HACS

1. In HACS → Integrations → ⋮ → Custom repositories
2. Add https://github.com/pgroene/kyber as an Integration
3. Find Kyber in the HACS store and install
4. Restart Home Assistant
5. Go to Settings → Devices & Services → Add Integration → search for Kyber

Or use the quick-add button:

Features

• 💬 AI Chat — ask questions and give commands in natural language; automatic language detection with locale-specific vocabulary hints (Dutch, German, French, Spanish, Italian, Portuguese)
• 📋 Proposal Cards — review changes before they're applied, with one-click Undo
• ⚡ Autopilot Mode — auto-execute proposals for hands-free operation
• ✏️ Automation & Script Editor — CodeMirror 6 YAML editor with AI assistance
• 📊 Dashboard Editor — edit Lovelace dashboards as YAML, create new dashboards
• 🔧 Slash Commands — /dashboard, /automation, /script, /blueprint, /area, /memory, /update and more — see docs/slash-commands.md
• 🏷️ Kyber Labels — tag entities with kyber:* labels (e.g. kyber:important, kyber:appliance) via /area label; Kyber uses these to prioritise context
• 🤖 AI Entity Narrator — on startup, Kyber batches all entities and generates rich descriptions and natural-language search aliases (e.g. "koffiezetapparaat" → switch.onoff_keuken_espresso). Alias quality is filtered for plausibility. See docs/narrator.md
• 📍 Proactive Area Suggestions — when you mention a room and nearby entities have no area assigned, Kyber shows a one-click assignment card. See docs/area-suggestions.md
• 🔒 100% Local — all AI inference runs on your own Ollama instance; nothing leaves your network
• ☁️ Cloud AI support — optionally route through Azure AI Foundry, OpenAI (or compatible: Groq, Mistral, OpenRouter), or Anthropic (Claude) instead of a local model
• 🔌 MCP Server — expose Kyber as an MCP tool so ChatGPT, Claude Desktop, Cursor and other AI clients can control your home. See docs/mcp.md
• 🔌 Integration Explorer — on startup Kyber automatically indexes every loaded HA integration: sensor names, entity IDs, and natural-language capability descriptions as searchable knowledge facts
• 🔬 Deep Analyzer — on-demand AI extraction of durable home facts across 8 analytical lenses: daily routines, device inventory, occupancy patterns, time/location triggers, energy usage, safety rules, entity relationships & dependencies, and automation purpose & use case
• 🧠 Hybrid memory retrieval — in-memory TF-IDF embedding with cosine similarity + keyword overlap blending; selected facts streamed to the live progress card
• 🔁 Tool-calling loop — up to 5 rounds of tool calls per turn; duplicate call detection with targeted redirect hints; tool name alias resolution
• 🗂️ Conversation sessions — named sessions with full rolling history and automatic compaction
• 🔄 Self-update — /update force installs the latest GitHub release directly, bypassing HACS. See docs/slash-commands.md
• 🐞 Kyber Debug panel — a dedicated sidebar entry (/kyber-debug) with five tabs: Memory, Last Turn, Status, Logs, Tests. See docs/debug-panel.md
• 📦 Debug bundle download — every turn produces a downloadable ZIP with the full system prompt, tool log, memory picks, and response

Quick Start

See docs/installation.md for full setup instructions.

Requirements: Home Assistant 2025.2+, Ollama with a model pulled, HA Ollama integration configured.

# Docker dev setup
docker compose -f docker-compose.dev.yml up
# then open http://localhost:8123

After install, Kyber registers two sidebar panels:

Panel	URL	Purpose
Kyber	/kyber	Main chat interface
Kyber Debug	/kyber-debug	Memory browser, last turn details, entity narrator progress, live logs

Choosing a Model

Kyber requires an Ollama model configured through the HA Ollama integration. Not all models perform equally — smaller models often fail to produce the structured plan blocks Kyber needs for action requests.

Based on the May 2026 eval report (5 runs × 3 real-home scenarios):

Model	Score	Notes
mistral-nemo:latest	🥇 14/15 (93%)	Recommended — reliable plan output, handles Dutch, 1-round answers from memory
qwen2.5:latest	✅ check	Not yet in the formal eval; community reports suggest strong structured output — worth trying if mistral-nemo is too slow on your hardware
qwen3:4b-instruct	🥈 10/15 (67%)	Good for read-only queries; fails action plans in Dutch
llama3.2:latest	🥉 4/15 (27%)	Unpredictable token usage; often skips plan blocks entirely

Recommendation: use mistral-nemo:latest. It reliably emits structured plan blocks, bridges Dutch entity name gaps via tool calls, and answers location queries in a single round. 3B–4B class models work for questions but are not reliable for executing actions.

See docs/eval-report-2026-05.md for full methodology, timing data, and failure analysis.

Entity Narrator Model

The background entity narrator uses a separate model call that only needs to produce short structured aliases — not full plan blocks. A smaller, faster model is ideal here.

Based on the May 2026 narrator bench (19 models, batch sizes 1 and 10, warmup-corrected):

Model	Quality@10	Batch 10 time	Notes
llama3.2:3b	✅ 100%	3.7s	🏆 Recommended — 12× faster than mistral-nemo, 1.9 GB
phi3:mini	✅ 95%	9.1s	Strong backup — slightly larger at 2.3 GB
llama3:latest	✅ 100%	11.0s	Reliable but slower
mistral-nemo:latest	✅ 100%	44.0s	Former recommendation — still works, just slow for narration
qwen3:*, deepseek-r1:7b	❌ 0%	—	Reasoning/thinking models — format not compatible

Recommendation: use llama3.2:3b for narration. See docs/narrator-bench-report-2026-05.md for the full breakdown.

Doc	Contents
docs/installation.md	Prerequisites, manual install, Docker dev setup, version bumping, tests
docs/settings.md	All settings — config flow, options sections, Debug Status tab; ASCII screen sketches
docs/chat-and-ai.md	Chat basics, proposal cards, autopilot, conversation history, entity autocomplete
docs/slash-commands.md	All slash commands: /dashboard, /automation, /script, /blueprint, /area
docs/editor.md	Automation/script editor, dashboard editor, Lovelace card type reference
docs/pipeline.md	End-to-end request pipeline — context build, hybrid memory retrieval (TF-IDF embeddings), tool loop, response cleanup, per-turn snapshot, debug bundle, debug-mode flag
docs/architecture.md	Frontend, backend endpoints, context building, plan/action system
docs/eval-report-2026-05.md	📊 May 2026 eval report — building the real-home prompt eval harness, what we fixed, and model comparison (mistral-nemo vs llama3.2 vs qwen3)
docs/narrator-bench-report-2026-05.md	📊 May 2026 narrator bench — 19 small models tested for entity narration quality and speed; llama3.2:3b wins (12× faster than mistral-nemo, same quality)

Architecture at a Glance

Layer	Technology
AI provider	HA Ollama integration via ai_task.async_generate_data() (HA 2025.2+)
Backend	Modular Python custom component — 14+ modules covering context building, tool execution, knowledge store, session management, debug diagnostics, integration explorer, and deep analysis
Frontend	Shadow DOM web component with CodeMirror 6 YAML editor

Backend modules

Module	Responsibility
http_api.py	Main AI request handler — prompt assembly, tool-call loop, intent classification, mode rules
action_execution.py	Plan action executor — service calls, area/label assignments, undo tracking
knowledge.py	TF-IDF knowledge store — add, search, rate, purge facts
knowledge_integration.py	Knowledge HTTP views — CRUD, shallow & deep analyze, feedback, purge
integration_explorer.py	Startup integration indexer — sensors, entity IDs, capability facts for all platforms
deep_analyzer.py	AI-powered automation/script/blueprint fact extractor (8 analytical lenses)
session_and_storage.py	Chat session management — multi-session store, history, summarization
debug_and_diagnostics.py	Per-turn debug snapshots, bundle ZIP builder, bug report, debug-mode flag
intent_and_context.py	Intent classification, quick-intents, home-state context builder
tool_execution.py	Tool handler dispatch, alias resolution, domain priority ranking
language_hints.py	Language detection and locale-specific vocabulary hints (Dutch + extensible)
domain_docs.py	Per-domain documentation injected into tool context
response_processing.py	Response cleanup — strip tool echoes, narration, rewrap action blocks
source.py	Raw YAML readers for automations, scripts, blueprints + content-hash memos

API endpoints

Endpoint	Purpose
POST /api/kyber/complete	Prompt + history + HA context → AI response + plan
POST /api/kyber/execute	Execute plan actions (service calls, area/label/entity management)
POST /api/kyber/parse_yaml	YAML string → JSON config (used before saving via HA API)
POST /api/kyber/summarize	Compact conversation history into a summary
GET /api/kyber/progress	Live progress events (polled by the frontend during AI turns)
GET /api/kyber/history	Retrieve chat history for the active session
GET /api/kyber/sessions	List all named sessions
POST /api/kyber/sessions/name	Rename a session
GET /api/kyber/knowledge	List knowledge store entries
POST /api/kyber/knowledge	Add or update a knowledge entry
POST /api/kyber/knowledge/analyze	Shallow automation analysis → knowledge facts
POST /api/kyber/knowledge/analyze_deep	Deep AI-driven analysis across all 8 lenses
POST /api/kyber/knowledge/feedback	Rate knowledge entries (👍/👎)
POST /api/kyber/knowledge/purge	Delete knowledge entries by filter
GET /api/kyber/debug/last_turn	Last-turn debug snapshot (system prompt, tool log, knowledge used)
GET /api/kyber/debug/tool_history	Ring buffer of recent tool calls
GET /api/kyber/debug/status	Integration status + entity/area counts
GET /api/kyber/debug/bundle	Download per-turn debug ZIP by request_id
GET /api/kyber/debug/bug-report	Download sanitised bug report ZIP
GET/POST /api/kyber/debug/mode	Read or toggle debug-mode flag

License

MIT — see LICENSE