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

In HACS → Integrations → ⋮ → Custom repositories
Add https://github.com/pgroene/kyber as an Integration
Find Kyber in the HACS store and install
Restart Home Assistant
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

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

In HACS → Integrations → ⋮ → Custom repositories
Add https://github.com/pgroene/kyber as an Integration
Find Kyber in the HACS store and install
Restart Home Assistant
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

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

In HACS → Integrations → ⋮ → Custom repositories
Add https://github.com/pgroene/kyber as an Integration
Find Kyber in the HACS store and install
Restart Home Assistant
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

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

In HACS → Integrations → ⋮ → Custom repositories
Add https://github.com/pgroene/kyber as an Integration
Find Kyber in the HACS store and install
Restart Home Assistant
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

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

In HACS → Integrations → ⋮ → Custom repositories
Add https://github.com/pgroene/kyber as an Integration
Find Kyber in the HACS store and install
Restart Home Assistant
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

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

In HACS → Integrations → ⋮ → Custom repositories
Add https://github.com/pgroene/kyber as an Integration
Find Kyber in the HACS store and install
Restart Home Assistant
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

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

In HACS → Integrations → ⋮ → Custom repositories
Add https://github.com/pgroene/kyber as an Integration
Find Kyber in the HACS store and install
Restart Home Assistant
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

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

In HACS → Integrations → ⋮ → Custom repositories
Add https://github.com/pgroene/kyber as an Integration
Find Kyber in the HACS store and install
Restart Home Assistant
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

Name		Name	Last commit message	Last commit date
.github		.github
.vite/vitest		.vite/vitest
custom_components/kyber		custom_components/kyber
docs		docs
hacs-default-fork		hacs-default-fork
node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709		node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709
scripts		scripts
tests		tests
www/kyber		www/kyber
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
hacs.json		hacs.json
icon.png		icon.png
info.md		info.md
logo.png		logo.png
pytest.ini		pytest.ini
requirements-test.txt		requirements-test.txt

Name		Name	Last commit message	Last commit date
.github		.github
.vite/vitest		.vite/vitest
custom_components/kyber		custom_components/kyber
docs		docs
hacs-default-fork		hacs-default-fork
node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709		node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709
scripts		scripts
tests		tests
www/kyber		www/kyber
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
hacs.json		hacs.json
icon.png		icon.png
info.md		info.md
logo.png		logo.png
pytest.ini		pytest.ini
requirements-test.txt		requirements-test.txt

Name		Name	Last commit message	Last commit date
.github		.github
.vite/vitest		.vite/vitest
custom_components/kyber		custom_components/kyber
docs		docs
hacs-default-fork		hacs-default-fork
node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709		node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709
scripts		scripts
tests		tests
www/kyber		www/kyber
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
hacs.json		hacs.json
icon.png		icon.png
info.md		info.md
logo.png		logo.png
pytest.ini		pytest.ini
requirements-test.txt		requirements-test.txt

Name		Name	Last commit message	Last commit date
.github		.github
.vite/vitest		.vite/vitest
custom_components/kyber		custom_components/kyber
docs		docs
hacs-default-fork		hacs-default-fork
node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709		node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709
scripts		scripts
tests		tests
www/kyber		www/kyber
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
hacs.json		hacs.json
icon.png		icon.png
info.md		info.md
logo.png		logo.png
pytest.ini		pytest.ini
requirements-test.txt		requirements-test.txt

Name		Name	Last commit message	Last commit date
.github		.github
.vite/vitest		.vite/vitest
custom_components/kyber		custom_components/kyber
docs		docs
hacs-default-fork		hacs-default-fork
node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709		node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709
scripts		scripts
tests		tests
www/kyber		www/kyber
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
hacs.json		hacs.json
icon.png		icon.png
info.md		info.md
logo.png		logo.png
pytest.ini		pytest.ini
requirements-test.txt		requirements-test.txt

Latest commit

History

Folders and files

Repository files navigation

Kyber — AI-Powered Smart Home Assistant for Home Assistant

Install via HACS

Features

Quick Start

Choosing a Model

Entity Narrator Model

Architecture at a Glance

Backend modules

API endpoints

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Kyber — AI-Powered Smart Home Assistant for Home Assistant

Install via HACS

Features

Quick Start

Choosing a Model

Entity Narrator Model

Architecture at a Glance

Backend modules

API endpoints

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Kyber — AI-Powered Smart Home Assistant for Home Assistant

Install via HACS

Features

Quick Start

Choosing a Model

Entity Narrator Model

Architecture at a Glance

Backend modules

API endpoints

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Latest commit

History