homeassistant-mcp/docs/nlp.md

Natural Language Processing Guide 🤖

Overview

My MCP Server includes powerful Natural Language Processing (NLP) capabilities powered by various AI models. This enables intelligent automation analysis, natural language control, and context-aware interactions with your Home Assistant setup.

Available Models 🎯

OpenAI Models

• GPT-4

  • Best for complex automation analysis
  • Natural language understanding
  • Context window: 8k-32k tokens
  • Recommended for: Automation analysis, complex queries

• GPT-3.5-Turbo

  • Faster response times
  • More cost-effective
  • Context window: 4k tokens
  • Recommended for: Quick commands, basic analysis

Claude Models

• Claude 2
  • Excellent code analysis
  • Large context window (100k tokens)
  • Strong system understanding
  • Recommended for: Deep automation analysis

DeepSeek Models

• DeepSeek-Coder
  • Specialized in code understanding
  • Efficient for automation rules
  • Context window: 8k tokens
  • Recommended for: Code generation, rule analysis

Configuration ⚙️

# AI Model Configuration
PROCESSOR_TYPE=openai          # openai, claude, or deepseek
OPENAI_MODEL=gpt-3.5-turbo    # or gpt-4, gpt-4-32k
OPENAI_API_KEY=your_key_here

# Optional: DeepSeek Configuration
DEEPSEEK_API_KEY=your_key_here
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1

# Analysis Settings
ANALYSIS_TIMEOUT=30000         # Timeout in milliseconds
MAX_RETRIES=3                 # Number of retries on failure

Usage Examples 💡

1. Automation Analysis

# Analyze an automation rule
bun run analyze-automation path/to/automation.yaml

# Example output:
# "This automation triggers on motion detection and turns on lights.
#  Potential issues:
#  - No timeout for light turn-off
#  - Missing condition for ambient light level"

2. Natural Language Commands

// Send a natural language command
const response = await fetch('http://localhost:3000/api/nlp/command', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    command: "Turn on the living room lights and set them to warm white"
  })
});

3. Context-Aware Queries

// Query with context
const response = await fetch('http://localhost:3000/api/nlp/query', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    query: "What's the temperature trend in the bedroom?",
    context: {
      timeframe: "last_24h",
      include_humidity: true
    }
  })
});

Custom Prompts 📝

You can customize the AI's behavior by creating custom prompts. See Custom Prompts Guide for details.

Example custom prompt:

name: energy_analysis
description: Analyze home energy usage patterns
prompt: |
  Analyze the following energy usage data and provide:
  1. Peak usage patterns
  2. Potential optimizations
  3. Comparison with typical usage
  4. Cost-saving recommendations
  
  Context: {context}
  Data: {data}

Best Practices 🎯

1. Model Selection

   • Use GPT-3.5-Turbo for quick queries
   • Use GPT-4 for complex analysis
   • Use Claude for large context analysis
   • Use DeepSeek for code-heavy tasks

2. Performance Optimization

   • Cache frequent queries
   • Use streaming for long responses
   • Implement retry logic for API calls

3. Cost Management

   • Monitor API usage
   • Implement rate limiting
   • Cache responses where appropriate

4. Error Handling

   • Implement fallback models
   • Handle API timeouts gracefully
   • Log failed queries for analysis

Advanced Features 🚀

1. Chain of Thought Analysis

const result = await analyzeWithCoT({
  query: "Optimize my morning routine automation",
  steps: ["Parse current automation", "Analyze patterns", "Suggest improvements"]
});

2. Multi-Model Analysis

const results = await analyzeWithMultiModel({
  query: "Security system optimization",
  models: ["gpt-4", "claude-2"],
  compareResults: true
});

3. Contextual Memory

const memory = new ContextualMemory({
  timeframe: "24h",
  maxItems: 100
});

await memory.add("User typically arrives home at 17:30");

Troubleshooting 🔧

Common Issues

1. Slow Response Times

   • Check model selection
   • Verify API rate limits
   • Consider caching

2. Poor Analysis Quality

   • Review prompt design
   • Check context window limits
   • Consider using a more capable model

3. API Errors

   • Verify API keys
   • Check network connectivity
   • Review rate limits

API Reference 📚

See API Documentation for detailed endpoint specifications.