Skip to content

DevOpsOfChaos/personal-ai-platform

BranchesTags

Repository files navigation

Personal AI Platform

License: MIT Python 3.12+ Home Assistant Version

Deutsch: Überblick
English: Overview

Deutsch

Was ist das?

Die Personal AI Platform ist ein persönlicher KI-Agent für Home Assistant und Telegram. Der Agent läuft als eigener Prozess, verarbeitet Telegram-Nachrichten, nutzt LLM-Modelle über OpenRouter und kann optional Home Assistant, Wetter, Kalender und weitere lokale Dienste einbinden.

Seit Phase 3B gibt es zusätzlich eine lokale Admin-Produktoberfläche unter /admin, die im echten Runtime-Prozess von python -m src.main mitläuft. Sie dient als sichtbare Produktbasis für Einstellungen, Verhalten, API-Transparenz, Planung, Projekte, Haushalt und Privacy.

Das Projekt besteht aus zwei getrennten Home-Assistant-Bausteinen:

Baustein Zweck
Home Assistant OS Add-on Startet den Agenten automatisch auf Home Assistant OS als Supervisor-verwalteten Container
HACS Integration Zeigt Statussensoren und Services in Home Assistant an; überwacht den Agenten, startet ihn aber nicht selbst

Diese Trennung ist wichtig. HACS installiert die Integration. Das Add-on betreibt den Agenten.

Architektur

Telegram
   |
   v
Personal AI Agent Add-on
   |-- /data/agent.db          persistente Agent-Datenbank
   |-- /data/agent.log         persistentes Agent-Log
   |-- /data/pai_config.yaml   generierte Runtime-Konfiguration ohne Klartext-Secrets
   |
   v
/config/pai_agent/agent.status
   |
   v
HACS Integration -> Home Assistant Sensoren und Services

Secrets wie TELEGRAM_BOT_TOKEN, OPENROUTER_API_KEY und HA_LONG_LIVED_TOKEN werden als Add-on-Optionen gesetzt. Sie werden nicht committed und nicht gepusht.

Empfohlene Installation auf Home Assistant OS

  1. Home Assistant öffnen.
  2. Einstellungen -> Add-ons -> Add-on Store.
  3. Dieses Repository als Add-on-Repository hinzufügen:
https://github.com/DevOpsOfChaos/personal-ai-platform
  1. Add-on Personal AI Agent installieren.
  2. Add-on-Optionen ausfüllen:
Option Pflicht Beschreibung
telegram_bot_token ja Bot-Token von BotFather
openrouter_api_key ja OpenRouter API-Key
telegram_user_id ja deine numerische Telegram-User-ID
ha_base_url ja lokale HA-Basis-URL, z. B. http://homeassistant.local:8123
ha_long_lived_token empfohlen Home Assistant Long-Lived Access Token
enable_home_assistant empfohlen true, wenn der Agent HA lesen oder steuern soll
enable_weather optional Wetterintegration aktivieren
openweather_api_key optional OpenWeatherMap API-Key
  1. Start on boot aktivieren.
  2. Add-on starten.

Die korrekte lokale HA-URL ist nur die Basis-URL:

http://homeassistant.local:8123

Nicht verwenden:

/home/overview
/auth/authorize?...

Das sind UI- oder Login-Pfade, keine API-Basis-URLs.

HACS Integration

Die HACS Integration ist optional, aber sinnvoll. Sie stellt in Home Assistant unter anderem diese Entitäten und Services bereit:

Element Zweck
sensor.pai_agent_status zeigt running, stopped oder unknown
sensor.pai_uptime Laufzeit des Agenten
sensor.pai_last_briefing Zeitstempel des letzten Briefings
sensor.pai_messages_today Nachrichtenanzahl des Tages
sensor.pai_llm_cost geschätzte LLM-Kosten
pai_agent.get_status Status als Service abfragen
pai_agent.send_message Nachricht an den Agenten weiterreichen

Installation:

  1. HACS -> Integrations -> Custom repositories.
  2. Repository hinzufügen:
https://github.com/DevOpsOfChaos/personal-ai-platform
  1. Kategorie: Integration.
  2. Personal AI Agent installieren.
  3. Home Assistant neu starten.
  4. Einstellungen -> Geräte & Dienste -> Integration hinzufügen -> Personal AI Agent.

Details: docs/HACS.md

Standalone-Betrieb

Für Entwicklung oder Betrieb außerhalb von Home Assistant OS:

git clone https://github.com/DevOpsOfChaos/personal-ai-platform.git
cd personal-ai-platform
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python setup_wizard.py
python -m src.main

Unter Linux kann der Agent alternativ als systemd-Service laufen. Siehe deploy/pai-agent.service.

Phase 3B Web Product Layer

Der Runtime-Start kann zusätzlich einen lokalen Admin-Webserver starten:

http://<host>:8099/admin

Wichtige Einstiegsseiten:

  • /admin
  • /admin/agent
  • /admin/api-usage
  • /admin/modules
  • /admin/home-assistant

Authentifizierung:

  • Admin-Token aus Add-on-Option admin_web_auth_token oder Env PAI_ADMIN_WEB_AUTH_TOKEN
  • Login-Form setzt einen HttpOnly-Cookie
  • Bearer-Token ist für JSON-Endpunkte ebenfalls erlaubt
  • Ohne gesetzten Token läuft die Web-UI nur im eingeschränkten Setup-Modus

Ungeschützte Admin-Zugriffe, Header-Spoofing und Secret-Anzeige sind nicht Teil dieses Stands.

Sicherheit

  • .env, config.yaml, data/ und generierte Seed-Dateien sind absichtlich ignoriert.
  • Long-Lived Tokens gehören nie in Git.
  • Das Add-on schreibt eine Runtime-Konfiguration mit ${ENV_VAR}-Referenzen statt Klartext-Secrets.
  • Agent-Datenbank und Logs liegen im persistenten Add-on-Speicher unter /data.
  • Die Statusdatei für Home Assistant liegt unter /config/pai_agent/agent.status.

Weiterführende Dokumentation

Dokument Inhalt
docs/ADDON.md Home Assistant OS Add-on
docs/HACS.md HACS Integration
docs/SETUP.md Setup außerhalb des Add-ons
docs/SETUP_GUIDE.md Phase-3B Runtime- und Web-Setup
docs/HA_SETUP.md Home Assistant Verbindung
docs/API_PROVIDERS.md LLM-Anbieter und API-Keys
docs/SECURITY_FEATURES.md Sicherheitsfunktionen
docs/PRODUCT_GAP_ANALYSIS.md ehrliche Bestandsaufnahme Phase 3B
docs/MODULES.md Produktmodule und Scope
docs/SECURITY_MODEL.md Admin-Web-Sicherheitsmodell
docs/KNOWN_LIMITATIONS.md bewusste Grenzen von Phase 3B
docs/RELEASE_NOTES.md Release-Stand Phase 3B
docs/DEVELOPER_HANDOFF.md Entwickler-Handoff

English

What is this?

Personal AI Platform is a personal AI agent for Home Assistant and Telegram. The agent runs as its own process, handles Telegram messages, uses LLM models through OpenRouter, and can optionally connect to Home Assistant, weather, calendars, and other local services.

The project has two separate Home Assistant parts:

Part Purpose
Home Assistant OS Add-on Runs the agent automatically on Home Assistant OS as a Supervisor-managed container
HACS Integration Adds sensors and services to Home Assistant; monitors the agent but does not run it

This split matters. HACS installs the integration. The add-on runs the agent.

Architecture

Telegram
   |
   v
Personal AI Agent Add-on
   |-- /data/agent.db          persistent agent database
   |-- /data/agent.log         persistent agent log
   |-- /data/pai_config.yaml   generated runtime config without plaintext secrets
   |
   v
/config/pai_agent/agent.status
   |
   v
HACS Integration -> Home Assistant sensors and services

Secrets such as TELEGRAM_BOT_TOKEN, OPENROUTER_API_KEY, and HA_LONG_LIVED_TOKEN are entered as add-on options. They are not committed or pushed.

Recommended Home Assistant OS Install

  1. Open Home Assistant.
  2. Go to Settings -> Add-ons -> Add-on Store.
  3. Add this repository as an add-on repository:
https://github.com/DevOpsOfChaos/personal-ai-platform
  1. Install the Personal AI Agent add-on.
  2. Fill the add-on options:
Option Required Description
telegram_bot_token yes BotFather Telegram bot token
openrouter_api_key yes OpenRouter API key
telegram_user_id yes your numeric Telegram user ID
ha_base_url yes local HA base URL, for example http://homeassistant.local:8123
ha_long_lived_token recommended Home Assistant Long-Lived Access Token
enable_home_assistant recommended true if the agent should read or control HA
enable_weather optional enable weather integration
openweather_api_key optional OpenWeatherMap API key
  1. Enable Start on boot.
  2. Start the add-on.

The correct local HA URL is only the base URL:

http://homeassistant.local:8123

Do not use:

/home/overview
/auth/authorize?...

Those are UI or login paths, not API base URLs.

HACS Integration

The HACS integration is optional but useful. It provides Home Assistant entities and services such as:

Element Purpose
sensor.pai_agent_status shows running, stopped, or unknown
sensor.pai_uptime agent uptime
sensor.pai_last_briefing timestamp of the last briefing
sensor.pai_messages_today messages processed today
sensor.pai_llm_cost estimated LLM cost
pai_agent.get_status query status as a service
pai_agent.send_message forward a message to the agent

Install:

  1. HACS -> Integrations -> Custom repositories.
  2. Add repository:
https://github.com/DevOpsOfChaos/personal-ai-platform
  1. Category: Integration.
  2. Install Personal AI Agent.
  3. Restart Home Assistant.
  4. Settings -> Devices & services -> Add integration -> Personal AI Agent.

Details: docs/HACS.md

Standalone Mode

For development or non-HA-OS deployments:

git clone https://github.com/DevOpsOfChaos/personal-ai-platform.git
cd personal-ai-platform
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python setup_wizard.py
python -m src.main

On Linux, the agent can also run as a systemd service. See deploy/pai-agent.service.

Security

  • .env, config.yaml, data/, and generated seed files are intentionally ignored.
  • Long-Lived Tokens must never be committed to Git.
  • The add-on writes a runtime config with ${ENV_VAR} references instead of plaintext secrets.
  • The agent database and logs live in persistent add-on storage under /data.
  • The Home Assistant readable status file is written to /config/pai_agent/agent.status.

Documentation

Document Content
docs/ADDON.md Home Assistant OS add-on
docs/HACS.md HACS integration
docs/SETUP.md Setup outside the add-on
docs/HA_SETUP.md Home Assistant connection
docs/API_PROVIDERS.md LLM providers and API keys
docs/SECURITY_FEATURES.md Security features

About

Dein persönlicher KI-Agent. Telegram-Bot mit 50+ Tools, natürlicher Sprache & optionaler Home-Assistant-Integration

Topics

python home-automation telegram-bot ai-assistant openrouter

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages