From 74cf27980af5324c80a6b33b9ff157f2ddc921f7 Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Wed, 17 Dec 2025 20:44:09 +0100 Subject: [PATCH] cleanup --- docs/housekeeping-api-spec.md | 317 ---------------------------------- 1 file changed, 317 deletions(-) delete mode 100644 docs/housekeeping-api-spec.md diff --git a/docs/housekeeping-api-spec.md b/docs/housekeeping-api-spec.md deleted file mode 100644 index 79dfe34..0000000 --- a/docs/housekeeping-api-spec.md +++ /dev/null @@ -1,317 +0,0 @@ -# Home Automation API Interface Specification - -## Purpose - -This document specifies the expected endpoints for a home automation abstraction layer in core-api. These endpoints will be consumed by the Tatlock Housekeeper agent and potentially other projects (scheduler, dashboards). - -The goal is to provide a simplified, domain-specific interface for home automation that abstracts away the underlying platform (initially Home Assistant, but swappable). - ---- - -## Endpoints - -### Device Discovery - -#### `GET /housekeeping/devices` - -List available devices. - -**Query Parameters:** -- `domain` (optional): Filter by device type (e.g., `light`, `switch`, `climate`, `media_player`) -- `area` (optional): Filter by area/room name - -**Response:** -```json -{ - "devices": [ - { - "entity_id": "light.living_room", - "name": "Living Room Light", - "domain": "light", - "area": "Living Room", - "state": "on", - "attributes": { - "brightness": 255, - "color_temp": 370 - } - } - ] -} -``` - ---- - -#### `GET /housekeeping/devices/{entity_id}` - -Get detailed state of a specific device. - -**Response:** -```json -{ - "entity_id": "light.living_room", - "name": "Living Room Light", - "domain": "light", - "area": "Living Room", - "state": "on", - "attributes": { - "brightness": 255, - "color_temp": 370, - "supported_features": ["brightness", "color_temp"] - }, - "last_changed": "2025-12-16T10:30:00Z" -} -``` - ---- - -#### `GET /housekeeping/areas` - -List all areas/rooms. - -**Response:** -```json -{ - "areas": [ - {"id": "living_room", "name": "Living Room"}, - {"id": "bedroom", "name": "Bedroom"}, - {"id": "kitchen", "name": "Kitchen"} - ] -} -``` - ---- - -### Device Control - -#### `POST /housekeeping/devices/{entity_id}/control` - -Control a device (turn on, turn off, toggle, or set attributes). - -**Request Body:** -```json -{ - "action": "turn_on", - "brightness": 128, - "color_temp": 400 -} -``` - -- `action` (required): One of `turn_on`, `turn_off`, `toggle` -- Additional attributes vary by device type (brightness, color_temp, rgb_color, etc.) - -**Response:** -```json -{ - "success": true, - "entity_id": "light.living_room", - "new_state": "on", - "message": "Light turned on" -} -``` - ---- - -### Scenes - -#### `GET /housekeeping/scenes` - -List available scenes. - -**Response:** -```json -{ - "scenes": [ - {"id": "scene.movie_night", "name": "Movie Night"}, - {"id": "scene.good_morning", "name": "Good Morning"}, - {"id": "scene.all_off", "name": "All Off"} - ] -} -``` - ---- - -#### `POST /housekeeping/scenes/{scene_id}/activate` - -Activate a scene. - -**Response:** -```json -{ - "success": true, - "scene_id": "scene.movie_night", - "message": "Scene activated" -} -``` - ---- - -### Scripts - -#### `GET /housekeeping/scripts` - -List available scripts/sequences. - -**Response:** -```json -{ - "scripts": [ - {"id": "script.bedtime_routine", "name": "Bedtime Routine"}, - {"id": "script.welcome_home", "name": "Welcome Home"} - ] -} -``` - ---- - -#### `POST /housekeeping/scripts/{script_id}/run` - -Execute a script with optional variables. - -**Request Body (optional):** -```json -{ - "variables": { - "brightness_level": 50, - "target_room": "bedroom" - } -} -``` - -**Response:** -```json -{ - "success": true, - "script_id": "script.bedtime_routine", - "message": "Script executed" -} -``` - ---- - -### Automations - -#### `GET /housekeeping/automations` - -List automations and their enabled/disabled status. - -**Response:** -```json -{ - "automations": [ - { - "id": "automation.motion_lights", - "name": "Motion Lights", - "enabled": true - }, - { - "id": "automation.night_mode", - "name": "Night Mode", - "enabled": false - } - ] -} -``` - ---- - -#### `POST /housekeeping/automations/{automation_id}/toggle` - -Enable or disable an automation. - -**Request Body:** -```json -{ - "enabled": true -} -``` - -**Response:** -```json -{ - "success": true, - "automation_id": "automation.motion_lights", - "enabled": true, - "message": "Automation enabled" -} -``` - ---- - -### Utility - -#### `GET /housekeeping/history` - -Get state history for a device. - -**Query Parameters:** -- `entity_id` (required): Device to get history for -- `hours` (optional, default 24): Hours of history to retrieve - -**Response:** -```json -{ - "entity_id": "light.living_room", - "history": [ - { - "state": "on", - "timestamp": "2025-12-16T10:30:00Z", - "attributes": {"brightness": 255} - }, - { - "state": "off", - "timestamp": "2025-12-16T08:00:00Z", - "attributes": {} - } - ] -} -``` - ---- - -#### `GET /housekeeping/health` - -Health check for home automation connection. - -**Response:** -```json -{ - "status": "healthy", - "connected": true, - "platform": "home_assistant", - "version": "2024.12.0" -} -``` - ---- - -## Error Responses - -All endpoints should return consistent error responses: - -```json -{ - "error": true, - "code": "DEVICE_NOT_FOUND", - "message": "Device light.nonexistent not found" -} -``` - -Common error codes: -- `DEVICE_NOT_FOUND` - Entity ID doesn't exist -- `INVALID_ACTION` - Unsupported action for device type -- `CONNECTION_ERROR` - Cannot reach home automation platform -- `UNAUTHORIZED` - Invalid or missing credentials - ---- - -## Authentication - -All endpoints require authentication via Bearer token in the `Authorization` header. - ---- - -## Consuming Client - -The Tatlock project has an existing client (`src/agents/housekeeper/client.py`) that expects these endpoints. No changes to Tatlock are needed once these endpoints are available. - -Reference: `CoreAPIClient` class in Tatlock expects these exact endpoint patterns.