AI Service API Reference¶

Version: 1.0
Status: Experimental
Base URL: /api/ai

The AI Service provides intelligent analysis and natural language querying capabilities for the HOMEPOT Client. It leverages a local LLM (Ollama) and Vector Memory (ChromaDB) to ensure data privacy.

1. Analyze Device Metrics¶

Analyze a set of device metrics to detect anomalies and receive actionable recommendations. This endpoint uses a Hybrid Approach: 1. Rule-Based Detection: Instantly flags known issues (e.g., CPU > 90%). 2. LLM Analysis: Provides context, explanation, and troubleshooting steps based on the rule-based findings.

Endpoint¶

POST /analyze

Request Body¶

{
  "device_id": "pos-terminal-01",
  "metrics": {
    "cpu_percent": 92.5,
    "memory_percent": 60.0,
    "disk_percent": 45.0,
    "error_rate": 0.05,
    "network_latency_ms": 120
  }
}

Response¶

{
  "device_id": "pos-terminal-01",
  "anomaly_score": 0.4,
  "is_anomaly": false,
  "analysis": "The CPU usage is high (92.5%), which exceeds the 90% threshold. However, memory and disk usage are within normal limits. This suggests a compute-intensive process is running. Recommendation: Check for stuck background jobs or recent software updates.",
  "status": "processed"
}

2. Set Analysis Mode¶

Switch the AI's "persona" to tailor the analysis output for different audiences.

Endpoint¶

POST /mode

Request Body¶

{
  "mode": "executive"
}

Available Modes: - maintenance (Default): Technical focus, root cause analysis, fix recommendations. - predictive: Trend analysis, failure prediction, risk assessment. - executive: High-level summaries, business impact, KPIs.

Response¶

{
  "status": "success",
  "mode": "executive"
}

3. Natural Language Query¶

Ask questions about the system, specific devices, or historical incidents. The system uses RAG (Retrieval-Augmented Generation) and Context Injection to provide accurate answers based on:

1. Real-Time Context: Current device status, health checks, and push notification stats.
2. System Knowledge: Awareness of the codebase structure and project documentation.
3. Long-Term Memory: Historical logs and similar past incidents stored in ChromaDB.
4. Short-Term Memory: The recent conversation history (last 5 messages).

Endpoint¶

POST /query

Request Body¶

{
  "query": "Why is device pos-terminal-01 failing?",
  "device_id": "pos-terminal-01",
  "history": [
    {
      "role": "user",
      "content": "Is the system healthy?"
    },
    {
      "role": "assistant",
      "content": "Yes, most devices are online, but pos-terminal-01 is reporting errors."
    }
  ]
}

Parameters: * query (string, required): The question to ask. * device_id (string, optional): If provided, fetches specific context for this device. * history (list, optional): A list of previous messages to maintain conversation context.

Response¶

{
  "response": "Based on recent logs, pos-terminal-01 is experiencing high CPU usage (92.5%) and intermittent network latency. This pattern matches a known issue with the 'v2.4.1' firmware update. I recommend rolling back to v2.4.0.",
  "context_used": {
    "long_term_memories": 3,
    "short_term_messages": 2
  }
}

4. Health Check¶

Verify that the AI Service and LLM are operational.

Endpoint¶

GET /health

Response¶

{
  "status": "healthy",
  "llm_connected": true,
  "version": "1.0.0",
  "mode": "maintenance"
}