@coffeerunhobby/mcp-ha-connect 0.5.0

package/src/localAI/index.ts

@@ -0,0 +1,88 @@
+/**
+ * Local AI Client
+ * Factory and facade for AI providers
+ */
+
+import { logger } from '../utils/logger.js';
+import type { EnvironmentConfig } from '../config.js';
+import type { AIProviderConfig, AIProviderInterface, AnalysisResult, SensorData } from './types.js';
+import { OllamaProvider } from './providers/ollama.js';
+import { OpenAICompatibleProvider } from './providers/openai.js';
+
+// Re-export types for convenience
+export type { SensorData, AnalysisResult, AIProviderType } from './types.js';
+
+/**
+ * Create the appropriate AI provider based on configuration
+ */
+function createProvider(providerConfig: AIProviderConfig): AIProviderInterface {
+  switch (providerConfig.provider) {
+    case 'openai':
+      return new OpenAICompatibleProvider(providerConfig);
+    case 'ollama':
+    default:
+      return new OllamaProvider(providerConfig);
+  }
+}
+
+/**
+ * Local AI Client
+ * Facade for AI analysis using configurable providers
+ */
+export class LocalAIClient {
+  private provider: AIProviderInterface;
+  private providerConfig: AIProviderConfig;
+
+  constructor(config: EnvironmentConfig) {
+    this.providerConfig = {
+      provider: config.aiProvider,
+      baseUrl: config.aiUrl,
+      model: config.aiModel,
+      timeout: config.aiTimeout,
+      apiKey: config.aiApiKey,
+    };
+
+    this.provider = createProvider(this.providerConfig);
+
+    logger.info('LocalAIClient initialized', {
+      provider: this.providerConfig.provider,
+      model: this.providerConfig.model,
+      url: this.providerConfig.baseUrl,
+    });
+  }
+
+  /**
+   * Analyze sensor data using AI
+   */
+  async analyzeSensors(sensors: SensorData): Promise<AnalysisResult> {
+    return this.provider.analyzeSensors(sensors);
+  }
+
+  /**
+   * Check if the AI provider is available
+   */
+  async checkHealth(): Promise<boolean> {
+    return this.provider.checkHealth();
+  }
+
+  /**
+   * Get the provider name
+   */
+  getProviderName(): string {
+    return this.provider.getProviderName();
+  }
+
+  /**
+   * Get the configured model name
+   */
+  getModelName(): string {
+    return this.providerConfig.model;
+  }
+
+  /**
+   * Get the provider configuration
+   */
+  getConfig(): Readonly<AIProviderConfig> {
+    return { ...this.providerConfig };
+  }
+}

package/src/localAI/prompts.ts

@@ -0,0 +1,50 @@
+/**
+ * AI System Prompts
+ * Shared prompts for sensor analysis across all providers
+ */
+
+/**
+ * System prompt for sensor analysis
+ */
+export const SENSOR_ANALYSIS_SYSTEM_PROMPT = `You are a home automation AI analyzing Home Assistant sensors.
+
+SEVERITY RULES:
+- critical: Gas/smoke/CO detected, fire, temp>40°C indoors, power spike>500%, door open>2h with alarm
+- high: Battery<10%, power spike>300%, door open>30min with alarm, temp>35°C
+- medium: Battery<20%, connectivity issues, minor anomalies
+- low: Informational warnings
+
+OUTPUT FORMAT (JSON only, no markdown):
+{
+  "severity": "critical|high|medium|low",
+  "issue": "brief description",
+  "reasoning": "detailed explanation",
+  "recommended_actions": ["action1", "action2"],
+  "ssh_diagnostics": ["command1", "command2"],
+  "confidence": 0.85
+}
+
+Respond with JSON only. No extra text.`;
+
+/**
+ * Build the full prompt for sensor analysis
+ */
+export function buildSensorAnalysisPrompt(sensors: Record<string, unknown>): string {
+  return `${SENSOR_ANALYSIS_SYSTEM_PROMPT}\n\nAnalyze these sensors: ${JSON.stringify(sensors)}\n\nProvide JSON only:`;
+}
+
+/**
+ * Build messages array for OpenAI-compatible APIs
+ */
+export function buildChatMessages(sensors: Record<string, unknown>): Array<{ role: string; content: string }> {
+  return [
+    {
+      role: 'system',
+      content: SENSOR_ANALYSIS_SYSTEM_PROMPT,
+    },
+    {
+      role: 'user',
+      content: `Analyze these sensors: ${JSON.stringify(sensors)}\n\nProvide JSON only:`,
+    },
+  ];
+}

package/src/localAI/providers/base.ts

@@ -0,0 +1,120 @@
+/**
+ * Base AI Provider
+ * Abstract class with shared logic for all AI providers
+ */
+
+import { logger } from '../../utils/logger.js';
+import type { AIProviderConfig, AIProviderInterface, AnalysisResult, SensorData } from '../types.js';
+
+/**
+ * Raw analysis result from AI (before adding metadata)
+ */
+export interface RawAnalysisResult {
+  severity: 'critical' | 'high' | 'medium' | 'low';
+  issue: string;
+  reasoning: string;
+  recommended_actions: string[];
+  ssh_diagnostics: string[];
+  confidence: number;
+}
+
+/**
+ * Abstract base class for AI providers
+ */
+export abstract class BaseAIProvider implements AIProviderInterface {
+  protected baseUrl: string;
+  protected model: string;
+  protected timeout: number;
+  protected apiKey?: string;
+
+  constructor(config: AIProviderConfig) {
+    this.baseUrl = config.baseUrl;
+    this.model = config.model;
+    this.timeout = config.timeout;
+    this.apiKey = config.apiKey;
+  }
+
+  /**
+   * Get the provider name - must be implemented by subclasses
+   */
+  abstract getProviderName(): string;
+
+  /**
+   * Make the actual API request - must be implemented by subclasses
+   */
+  protected abstract makeRequest(sensors: SensorData): Promise<string>;
+
+  /**
+   * Check health - must be implemented by subclasses
+   */
+  abstract checkHealth(): Promise<boolean>;
+
+  /**
+   * Analyze sensors using AI
+   */
+  async analyzeSensors(sensors: SensorData): Promise<AnalysisResult> {
+    const sensorCount = Object.keys(sensors).length;
+    const providerName = this.getProviderName();
+
+    logger.info('Starting AI analysis', { sensorCount, model: this.model, provider: providerName });
+
+    const startTime = Date.now();
+
+    try {
+      const aiText = await this.makeRequest(sensors);
+
+      if (!aiText) {
+        throw new Error(`Empty response from ${providerName}`);
+      }
+
+      // Extract JSON from response (handles potential text around JSON)
+      const analysis = this.extractJson(aiText);
+      const elapsed = (Date.now() - startTime) / 1000;
+
+      logger.info('AI analysis complete', {
+        severity: analysis.severity,
+        elapsed: `${elapsed.toFixed(2)}s`,
+        model: this.model,
+        provider: providerName,
+      });
+
+      return {
+        ...analysis,
+        model: this.model,
+        provider: providerName,
+        response_time: parseFloat(elapsed.toFixed(2)),
+      };
+    } catch (error) {
+      const elapsed = (Date.now() - startTime) / 1000;
+      logger.error('AI analysis failed', {
+        error: error instanceof Error ? error.message : String(error),
+        elapsed: `${elapsed.toFixed(2)}s`,
+        provider: providerName,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Extract JSON from AI response text
+   */
+  protected extractJson(text: string): RawAnalysisResult {
+    // Try to find JSON object in the response
+    const jsonMatch = text.match(/\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}/);
+    if (!jsonMatch) {
+      throw new Error(`No JSON found in AI response: ${text.substring(0, 200)}`);
+    }
+
+    return JSON.parse(jsonMatch[0]) as RawAnalysisResult;
+  }
+
+  /**
+   * Build authorization headers if API key is set
+   */
+  protected getAuthHeaders(): Record<string, string> {
+    if (this.apiKey) {
+      return { Authorization: `Bearer ${this.apiKey}` };
+    }
+    return {};
+  }
+}

package/src/localAI/providers/ollama.ts

@@ -0,0 +1,78 @@
+/**
+ * Ollama AI Provider
+ * Native Ollama API implementation
+ */
+
+import type { AIProviderConfig, SensorData } from '../types.js';
+import { buildSensorAnalysisPrompt } from '../prompts.js';
+import { BaseAIProvider } from './base.js';
+
+/**
+ * Ollama API response format
+ */
+interface OllamaResponse {
+  response?: string;
+  error?: string;
+}
+
+/**
+ * Ollama AI provider using native Ollama API
+ */
+export class OllamaProvider extends BaseAIProvider {
+  constructor(config: AIProviderConfig) {
+    super(config);
+  }
+
+  getProviderName(): string {
+    return 'ollama';
+  }
+
+  /**
+   * Make request to Ollama API
+   */
+  protected async makeRequest(sensors: SensorData): Promise<string> {
+    const prompt = buildSensorAnalysisPrompt(sensors);
+
+    const response = await fetch(`${this.baseUrl}/api/generate`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...this.getAuthHeaders(),
+      },
+      body: JSON.stringify({
+        model: this.model,
+        prompt,
+        stream: false,
+        options: {
+          temperature: 0.3,
+          num_predict: 2000,
+          num_ctx: 4096,
+        },
+      }),
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Ollama request failed: ${response.status} ${errorText}`);
+    }
+
+    const result = (await response.json()) as OllamaResponse;
+    return result.response ?? '';
+  }
+
+  /**
+   * Check if Ollama is available
+   */
+  async checkHealth(): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/tags`, {
+        headers: this.getAuthHeaders(),
+        signal: AbortSignal.timeout(5000),
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/localAI/providers/openai.ts

@@ -0,0 +1,86 @@
+/**
+ * OpenAI-Compatible AI Provider
+ * Works with LocalAI, LM Studio, vLLM, and any OpenAI-compatible API
+ */
+
+import type { AIProviderConfig, SensorData } from '../types.js';
+import { buildChatMessages } from '../prompts.js';
+import { BaseAIProvider } from './base.js';
+
+/**
+ * OpenAI chat completion response format
+ */
+interface OpenAIChatResponse {
+  choices?: Array<{
+    message?: {
+      content?: string;
+    };
+  }>;
+  error?: {
+    message?: string;
+  };
+}
+
+/**
+ * OpenAI-compatible AI provider
+ * Works with LocalAI, LM Studio, vLLM, and other OpenAI-compatible APIs
+ */
+export class OpenAICompatibleProvider extends BaseAIProvider {
+  constructor(config: AIProviderConfig) {
+    super(config);
+  }
+
+  getProviderName(): string {
+    return 'openai-compatible';
+  }
+
+  /**
+   * Make request to OpenAI-compatible API
+   */
+  protected async makeRequest(sensors: SensorData): Promise<string> {
+    const messages = buildChatMessages(sensors);
+
+    const response = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...this.getAuthHeaders(),
+      },
+      body: JSON.stringify({
+        model: this.model,
+        messages,
+        temperature: 0.3,
+        max_tokens: 2000,
+      }),
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`OpenAI-compatible API request failed: ${response.status} ${errorText}`);
+    }
+
+    const result = (await response.json()) as OpenAIChatResponse;
+
+    if (result.error) {
+      throw new Error(`API error: ${result.error.message}`);
+    }
+
+    return result.choices?.[0]?.message?.content ?? '';
+  }
+
+  /**
+   * Check if the OpenAI-compatible API is available
+   */
+  async checkHealth(): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.baseUrl}/v1/models`, {
+        headers: this.getAuthHeaders(),
+        signal: AbortSignal.timeout(5000),
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/localAI/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Local AI Client Types
+ * Shared interfaces for AI provider implementations
+ */
+
+/**
+ * Supported AI provider types
+ * Use 'none' to explicitly disable AI features
+ */
+export type AIProviderType = 'ollama' | 'openai' | 'none';
+
+/**
+ * Sensor data input for analysis
+ */
+export interface SensorData {
+  [entity_id: string]: {
+    state: string;
+    unit?: string;
+    attributes?: Record<string, unknown>;
+  };
+}
+
+/**
+ * AI analysis result
+ */
+export interface AnalysisResult {
+  severity: 'critical' | 'high' | 'medium' | 'low';
+  issue: string;
+  reasoning: string;
+  recommended_actions: string[];
+  ssh_diagnostics: string[];
+  confidence: number;
+  model: string;
+  provider: string;
+  response_time: number;
+}
+
+/**
+ * AI provider configuration
+ */
+export interface AIProviderConfig {
+  provider: AIProviderType;
+  baseUrl: string;
+  model: string;
+  timeout: number;
+  apiKey?: string;
+}
+
+/**
+ * AI provider interface - all providers must implement this
+ */
+export interface AIProviderInterface {
+  /**
+   * Analyze sensor data using AI
+   */
+  analyzeSensors(sensors: SensorData): Promise<AnalysisResult>;
+
+  /**
+   * Check if the AI provider is available
+   */
+  checkHealth(): Promise<boolean>;
+
+  /**
+   * Get the provider name
+   */
+  getProviderName(): string;
+}