Backend Documentation

Backend Documentation

The AI Code Task backend is a Home Assistant custom component written in Python. It acts as the bridge between the Lovelace card and the Home Assistant core services.

🏛 Architecture Overview

The backend is structured to handle three main responsibilities:

1. AI Task Provider Management: Routing generation requests to entities in the ai_task domain (e.g., xAI Conversation).
2. File System Access: Securely reading and writing files within the Home Assistant /config directory.
3. Chat History Persistence: Managing conversation history server-side using Home Assistant's storage system.
4. Real-time Communication: Using Websockets to provide low-latency updates to the frontend.

Key Components

• __init__.py: Handles the integration setup and registration of websocket commands and Lovelace resources.
• websockets.py: Defines the websocket API handlers for file management, code generation, and history synchronization.
• config_flow.py: Manages the setup UI, allowing selection of the default AI Provider and system prompts (Advanced Mode).
• helpers/:
  • provider_manager.py: Discovers and interfaces with ai_task entities.
  • chat_history.py: Handles reading/writing chat logs to disk (.storage/ai_code_task/chat_history).
  • file_manager.py: Safe file system operations respecting exclusions.

🔌 Websocket API

The frontend communicates with the backend primarily through Home Assistant's websocket protocol.

Supported Commands

Command	Description
ai_code_task/get_config	Returns allowed file extensions and version info.
ai_code_task/get_providers	Returns a list of available AI agents (from ai_task domain).
ai_code_task/generate	Sends a prompt + context (code, files, entities) to the selected provider to generate code/text.
ai_code_task/file_list	Lists files and directories in the /config folder (respecting exclusions).
ai_code_task/file_read	Returns the content of a specific file.
ai_code_task/file_save	Saves content to a specific file (creating directories if needed).
ai_code_task/sync_history	Retrieves stored chat history for the user.
ai_code_task/clear_history	Clears the server-side chat history for the user.

🛡 Security & Permissions

File Access

The integration is restricted to the Home Assistant configuration directory (/config). It respects a list of EXCLUDED_FILES (e.g., secrets.yaml) defined in const.py to prevent sensitive data exposure.

Authentication

All websocket commands require a valid Home Assistant user session.

📦 Dependencies

• Home Assistant Core: Requires version 2024.x or higher.
• AI Task (ai_task): A required dependency that provides the standard interface for AI models (like xAI Conversation).