From f81cb1af62b3edb3a53c7d62bdb0e96bcbfd0bea Mon Sep 17 00:00:00 2001 From: jango-blockchained Date: Mon, 3 Feb 2025 00:29:38 +0100 Subject: [PATCH] Simplify README by removing detailed API and CLI documentation - Removed extensive Home Assistant Analyzer CLI section - Condensed API Reference to point to external documentation files - Simplified development commands section - Kept core sections like OpenAI Integration and Troubleshooting - Improved overall readability by reducing technical depth in README --- README.md | 580 +++--------------------------------------------------- 1 file changed, 22 insertions(+), 558 deletions(-) diff --git a/README.md b/README.md index 8a4d978..57822f8 100644 --- a/README.md +++ b/README.md @@ -54,14 +54,7 @@ See [SSE_API.md](docs/SSE_API.md) for complete documentation of the SSE system. - [Configuration](#configuration) - [Development](#development) - [API Reference](#api-reference) - - [MCP Schema](#mcp-schema-endpoint) - - [Device Control](#device-control) - - [Add-on Management](#add-on-management) - - [Package Management](#package-management) - - [Automation Management](#automation-management) - [OpenAI Integration](#openai-integration) - - [Standard Analysis](#1-standard-analysis) - - [Custom Prompt Analysis](#2-custom-prompt-analysis) - [Natural Language Integration](#natural-language-integration) - [Troubleshooting](#troubleshooting) - [Project Status](#project-status) @@ -250,511 +243,36 @@ TEST_HASS_TOKEN=test_token # Test token 2. **Production**: Copy `.env.example` to `.env.production` 3. **Testing**: Copy `.env.example` to `.env.test` -## Home Assistant Analyzer CLI +## Development -The project includes a powerful command-line tool (`ha-analyzer-cli.ts`) for analyzing and optimizing your Home Assistant setup. This tool provides comprehensive system analysis, automation optimization, and custom querying capabilities. - -### Features - -- 🔍 **System Analysis** - - Device state monitoring - - Health checks - - Configuration analysis - - Integration status - - Performance metrics - - Security assessment - -- 🤖 **Automation Analysis** - - Inefficient automation detection - - Optimization suggestions - - Blueprint recommendations - - Condition optimizations - -- ⚡ **Performance Optimization** - - Resource usage analysis - - Response time monitoring - - Configuration optimization suggestions - - Integration improvement recommendations - -- 🔐 **Security Analysis** - - Current security measures assessment - - Vulnerability detection - - Security recommendations - -- 📊 **Entity Usage Analysis** - - Most active entities tracking - - Rarely used entity detection - - Potential duplicate identification - -- 💡 **Energy Management** - - High consumption detection - - Monitoring suggestions - - Tariff optimization recommendations - -### Configuration - -The analyzer requires the following environment variables: -```env -OPENAI_API_KEY=your_openai_api_key # Required for analysis -HASS_TOKEN=your_hass_token # Home Assistant access token -MCP_SERVER=http://localhost:3000 # MCP server URL (default) -OPENAI_MODEL=gpt-4o # Default model (optional) -MAX_RETRIES=3 # Max retry attempts (optional) -ANALYSIS_TIMEOUT=30000 # Analysis timeout in ms (optional) -``` - -### Available Models - -The analyzer supports multiple language models: -- GPT-4 Models: - - `gpt-4o`: Standard GPT-4 - - `gpt-4-turbo`: GPT-4 Turbo - - `gpt-4`: Original GPT-4 -- GPT-3.5 Models: - - `gpt-3.5-turbo`: Standard GPT-3.5 - - `gpt-3.5-turbo-16k`: Extended context GPT-3.5 -- DeepSeek Models (requires DEEPSEEK_API_KEY): - - `deepseek-v3`: DeepSeek v3 - - `deepseek-r1`: DeepSeek R1 - -### Usage - -1. **Standard Analysis** ```bash -npx ts-node ha-analyzer-cli.ts analyze -``` +# Development mode with hot reload +npm run dev -2. **Custom Prompt Analysis** -```bash -npx ts-node ha-analyzer-cli.ts custom -``` +# Build project +npm run build -3. **Automation Optimization** -```bash -npx ts-node ha-analyzer-cli.ts optimize -``` +# Production mode +npm run start -The analysis results will be displayed in a structured format, organized by categories such as system overview, performance, security, optimization suggestions, and more. +# Run tests +npx jest --config=jest.config.cjs + +# Run tests with coverage +npx jest --coverage + +# Lint code +npm run lint + +# Format code +npm run format +``` ## API Reference -### MCP Schema Endpoint - -The server exposes an MCP (Model Context Protocol) schema endpoint that describes all available tools and their parameters: - -```http -GET /mcp -``` - -This endpoint returns a JSON schema describing all available tools, their parameters, and documentation resources. The schema follows the MCP specification and can be used by LLM clients to understand the server's capabilities. - -Example response: -```json -{ - "tools": [ - { - "name": "list_devices", - "description": "List all devices connected to Home Assistant", - "parameters": { - "type": "object", - "properties": { - "domain": { - "type": "string", - "enum": ["light", "climate", "alarm_control_panel", ...] - }, - "area": { "type": "string" }, - "floor": { "type": "string" } - } - } - }, - // ... other tools - ], - "prompts": [], - "resources": [ - { - "name": "Home Assistant API", - "url": "https://developers.home-assistant.io/docs/api/rest/" - } - ] -} -``` - -Note: The `/mcp` endpoint is publicly accessible and does not require authentication, as it only provides schema information. - -### Device Control - -#### Common Entity Controls -```json -{ - "tool": "control", - "command": "turn_on", // or "turn_off", "toggle" - "entity_id": "light.living_room" -} -``` - -#### Light Control -```json -{ - "tool": "control", - "command": "turn_on", - "entity_id": "light.living_room", - "brightness": 128, - "color_temp": 4000, - "rgb_color": [255, 0, 0] -} -``` - -### Add-on Management - -#### List Available Add-ons -```json -{ - "tool": "addon", - "action": "list" -} -``` - -#### Install Add-on -```json -{ - "tool": "addon", - "action": "install", - "slug": "core_configurator", - "version": "5.6.0" -} -``` - -#### Manage Add-on State -```json -{ - "tool": "addon", - "action": "start", // or "stop", "restart" - "slug": "core_configurator" -} -``` - -### Package Management - -#### List HACS Packages -```json -{ - "tool": "package", - "action": "list", - "category": "integration" // or "plugin", "theme", "python_script", "appdaemon", "netdaemon" -} -``` - -#### Install Package -```json -{ - "tool": "package", - "action": "install", - "category": "integration", - "repository": "hacs/integration", - "version": "1.32.0" -} -``` - -### Automation Management - -#### Create Automation -```json -{ - "tool": "automation_config", - "action": "create", - "config": { - "alias": "Motion Light", - "description": "Turn on light when motion detected", - "mode": "single", - "trigger": [ - { - "platform": "state", - "entity_id": "binary_sensor.motion", - "to": "on" - } - ], - "action": [ - { - "service": "light.turn_on", - "target": { - "entity_id": "light.living_room" - } - } - ] - } -} -``` - -#### Duplicate Automation -```json -{ - "tool": "automation_config", - "action": "duplicate", - "automation_id": "automation.motion_light" -} -``` - -### Core Functions - -#### State Management -```http -GET /api/state -POST /api/state -``` - -Manages the current state of the system. - -**Example Request:** -```json -POST /api/state -{ - "context": "living_room", - "state": { - "lights": "on", - "temperature": 22 - } -} -``` - -#### Context Updates -```http -POST /api/context -``` - -Updates the current context with new information. - -**Example Request:** -```json -POST /api/context -{ - "user": "john", - "location": "kitchen", - "time": "morning", - "activity": "cooking" -} -``` - -### Action Endpoints - -#### Execute Action -```http -POST /api/action -``` - -Executes a specified action with given parameters. - -**Example Request:** -```json -POST /api/action -{ - "action": "turn_on_lights", - "parameters": { - "room": "living_room", - "brightness": 80 - } -} -``` - -#### Batch Actions -```http -POST /api/actions/batch -``` - -Executes multiple actions in sequence. - -**Example Request:** -```json -POST /api/actions/batch -{ - "actions": [ - { - "action": "turn_on_lights", - "parameters": { - "room": "living_room" - } - }, - { - "action": "set_temperature", - "parameters": { - "temperature": 22 - } - } - ] -} -``` - -### Query Functions - -#### Get Available Actions -```http -GET /api/actions -``` - -Returns a list of all available actions. - -**Example Response:** -```json -{ - "actions": [ - { - "name": "turn_on_lights", - "parameters": ["room", "brightness"], - "description": "Turns on lights in specified room" - }, - { - "name": "set_temperature", - "parameters": ["temperature"], - "description": "Sets temperature in current context" - } - ] -} -``` - -#### Context Query -```http -GET /api/context?type=current -``` - -Retrieves context information. - -**Example Response:** -```json -{ - "current_context": { - "user": "john", - "location": "kitchen", - "time": "morning", - "activity": "cooking" - } -} -``` - -### WebSocket Events - -The server supports real-time updates via WebSocket connections. - -```javascript -// Client-side connection example -const ws = new WebSocket('ws://localhost:3000/ws'); - -ws.onmessage = (event) => { - const data = JSON.parse(event.data); - console.log('Received update:', data); -}; -``` - -#### Supported Events - -- `state_change`: Emitted when system state changes -- `context_update`: Emitted when context is updated -- `action_executed`: Emitted when an action is completed -- `error`: Emitted when an error occurs - -**Example Event Data:** -```json -{ - "event": "state_change", - "data": { - "previous_state": { - "lights": "off" - }, - "current_state": { - "lights": "on" - }, - "timestamp": "2024-03-20T10:30:00Z" - } -} -``` - -### Error Handling - -All endpoints return standard HTTP status codes: - -- 200: Success -- 400: Bad Request -- 401: Unauthorized -- 403: Forbidden -- 404: Not Found -- 500: Internal Server Error - -**Error Response Format:** -```json -{ - "error": { - "code": "INVALID_PARAMETERS", - "message": "Missing required parameter: room", - "details": { - "missing_fields": ["room"] - } - } -} -``` - -### Rate Limiting - -The API implements rate limiting to prevent abuse: - -- 100 requests per minute per IP for regular endpoints -- 1000 requests per minute per IP for WebSocket connections - -When rate limit is exceeded, the server returns: - -```json -{ - "error": { - "code": "RATE_LIMIT_EXCEEDED", - "message": "Too many requests", - "reset_time": "2024-03-20T10:31:00Z" - } -} -``` - -### Example Usage - -#### Using curl -```bash -# Get current state -curl -X GET \ - http://localhost:3000/api/state \ - -H 'Authorization: ApiKey your_api_key_here' - -# Execute action -curl -X POST \ - http://localhost:3000/api/action \ - -H 'Authorization: ApiKey your_api_key_here' \ - -H 'Content-Type: application/json' \ - -d '{ - "action": "turn_on_lights", - "parameters": { - "room": "living_room", - "brightness": 80 - } - }' -``` - -#### Using JavaScript -```javascript -// Execute action -async function executeAction() { - const response = await fetch('http://localhost:3000/api/action', { - method: 'POST', - headers: { - 'Authorization': 'ApiKey your_api_key_here', - 'Content-Type': 'application/json' - }, - body: JSON.stringify({ - action: 'turn_on_lights', - parameters: { - room: 'living_room', - brightness: 80 - } - }) - }); - - const data = await response.json(); - console.log('Action result:', data); -} -``` +For detailed API documentation, please refer to: +- [API Documentation](docs/API.md) - Complete API reference +- [SSE API Documentation](docs/SSE_API.md) - Server-Sent Events documentation ## OpenAI Integration @@ -789,20 +307,6 @@ npm run test:openai # Select option 2 when prompted ``` -#### Available Variables -When using custom prompts, you can use these variables: -- `{device_count}`: Total number of devices -- `{device_types}`: List of device types -- `{device_states}`: Current states of devices -- `{device_examples}`: Example devices and their states - -#### Example Custom Prompts -``` -"Show me all active lights" -"Which devices in {device_types} need maintenance?" -"Analyze my {device_count} devices and suggest automations" -``` - ### Configuration To use the OpenAI integration, you need to set up your OpenAI API key in the `.env` file: @@ -810,46 +314,6 @@ To use the OpenAI integration, you need to set up your OpenAI API key in the `.e OPENAI_API_KEY=your_openai_api_key ``` -### Features -- 🔍 Intelligent device state analysis -- 📊 System health assessment -- 🤖 Smart automation suggestions -- 🔧 Maintenance recommendations -- 💡 Custom query support -- 🔄 Real-time device state information - -### Token Usage Optimization -The analysis tool includes smart token usage optimization: -- Automatic filtering of relevant devices based on query -- Fallback to summarized data for large systems -- Intelligent attribute selection based on device types -- Automatic retry with condensed information if token limit is reached - -## Development - -```bash -# Development mode with hot reload -npm run dev - -# Build project -npm run build - -# Production mode -npm run start - -# Run tests -npx jest --config=jest.config.cjs - -# Run tests with coverage -npx jest --coverage - -# Lint code -npm run lint - -# Format code -npm run format -``` - ## Troubleshooting ### Common Issues