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
2025-02-03 00:29:38 +01:00
parent cb6b16546b
commit f81cb1af62
1 changed files with 22 additions and 558 deletions
--- 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**
+# Build project
-```bash
+npm run build
 npx ts-node ha-analyzer-cli.ts custom
 ```
-3. **Automation Optimization**
+# Production mode
-```bash
+npm run start
 npx ts-node ha-analyzer-cli.ts optimize
 ```
-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
+For detailed API documentation, please refer to:
-
+- [API Documentation](docs/API.md) - Complete API reference
-The server exposes an MCP (Model Context Protocol) schema endpoint that describes all available tools and their parameters:
+- [SSE API Documentation](docs/SSE_API.md) - Server-Sent Events documentation
 ```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);
 }
 ```
 ## 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