TGM Manager provides a multi-provider AI integration system that allows you to leverage various AI services for chat completions, with analytics and cost tracking via InfluxDB.

Overview¶

The AI system supports:

• Multiple AI Providers - OpenAI, Google Gemini, Anthropic Claude, Azure OpenAI, Ollama (local)
• Model Selection - Choose specific models per request
• Conversation Logging - Track all AI interactions in InfluxDB
• Cost Analytics - Monitor AI usage costs by provider, user, and time period
• Health Monitoring - Check provider availability and service health

Supported Providers¶

REST API¶

Chat Completion¶

Send a chat request to an AI provider.

POST /api/ai/chat
Content-Type: application/json

{
  "provider": "openai",
  "model": "gpt-4",
  "messages": [
    {
      "role": "user",
      "content": "What are the best practices for preventive maintenance?"
    }
  ],
  "systemPrompt": "You are a maintenance management expert.",
  "temperature": 0.7,
  "maxTokens": 1000,
  "conversationId": "conv-123",
  "stream": false
}

Parameters:

Message Object:

Response:

{
  "data": {
    "content": "For effective preventive maintenance...",
    "provider": "openai",
    "model": "gpt-4",
    "inputTokens": 45,
    "outputTokens": 250,
    "totalTokens": 295,
    "estimatedCost": 0.0089,
    "latencyMs": 1250
  }
}

Provider Information¶

List All Providers¶

GET /api/ai/providers

Response:

{
  "data": {
    "providers": [
      {
        "provider": "OPENAI",
        "available": true,
        "defaultModel": "gpt-3.5-turbo",
        "availableModels": ["gpt-4", "gpt-4-turbo", "gpt-3.5-turbo"]
      },
      {
        "provider": "GEMINI",
        "available": true,
        "defaultModel": "gemini-pro",
        "availableModels": ["gemini-pro", "gemini-pro-vision"]
      }
    ],
    "availableProviders": ["OPENAI", "GEMINI"],
    "loggingEnabled": true
  }
}

Get Specific Provider Info¶

GET /api/ai/providers/{providerCode}

Response:

{
  "data": {
    "provider": "OPENAI",
    "available": true,
    "defaultModel": "gpt-3.5-turbo",
    "availableModels": ["gpt-4", "gpt-4-turbo", "gpt-3.5-turbo"]
  }
}

Analytics¶

Analytics endpoints require InfluxDB logging to be enabled.

Get Usage Statistics¶

GET /api/ai/stats

Parameters: - startTime (optional) - ISO 8601 datetime (default: 30 days ago) - endTime (optional) - ISO 8601 datetime (default: now)

Response:

{
  "data": {
    "startTime": "2024-01-01T00:00:00",
    "endTime": "2024-01-31T23:59:59",
    "statsByProvider": {
      "openai": { "count": 150, "totalTokens": 45000 },
      "gemini": { "count": 75, "totalTokens": 22000 }
    },
    "statsByModel": {
      "gpt-4": { "count": 50, "totalTokens": 15000 },
      "gpt-3.5-turbo": { "count": 100, "totalTokens": 30000 }
    },
    "latencyByModel": {
      "gpt-4": { "avgMs": 2500, "p95Ms": 4000 },
      "gpt-3.5-turbo": { "avgMs": 800, "p95Ms": 1500 }
    }
  }
}

Get Cost Analytics¶

GET /api/ai/stats/costs

Parameters: - startTime (optional) - ISO 8601 datetime - endTime (optional) - ISO 8601 datetime - windowSize (optional) - Aggregation window (default: "1d") - userLimit (optional) - Max users to return (default: 10)

Response:

{
  "data": {
    "startTime": "2024-01-01T00:00:00",
    "endTime": "2024-01-31T23:59:59",
    "costOverTime": [
      { "time": "2024-01-01", "cost": 12.50 },
      { "time": "2024-01-02", "cost": 15.75 }
    ],
    "costByProvider": {
      "openai": 125.00,
      "gemini": 45.50
    },
    "costByUser": [
      { "username": "john.doe", "cost": 50.25 },
      { "username": "jane.smith", "cost": 35.00 }
    ]
  }
}

Get Conversation Statistics¶

GET /api/ai/stats/conversations

Parameters: - startTime (optional) - ISO 8601 datetime - endTime (optional) - ISO 8601 datetime (default: 7 days) - windowSize (optional) - Aggregation window (default: "1h")

Get User Conversations¶

GET /api/ai/stats/user/{username}

Parameters: - startTime (optional) - ISO 8601 datetime - endTime (optional) - ISO 8601 datetime - limit (optional) - Max conversations to return (default: 50)

Health Check¶

GET /api/ai/health

Response:

{
  "data": {
    "status": "healthy",
    "availableProviders": ["OPENAI", "GEMINI"],
    "providerCount": 2,
    "loggingEnabled": true
  }
}

Configuration¶

Environment Variables¶

Configure AI providers in application.yml:

ai:
  openai:
    api-key: ${OPENAI_API_KEY}
    default-model: gpt-3.5-turbo
  gemini:
    api-key: ${GEMINI_API_KEY}
    default-model: gemini-pro
  anthropic:
    api-key: ${ANTHROPIC_API_KEY}
    default-model: claude-3-sonnet
  azure-openai:
    endpoint: ${AZURE_OPENAI_ENDPOINT}
    api-key: ${AZURE_OPENAI_API_KEY}
    deployment: ${AZURE_OPENAI_DEPLOYMENT}
  ollama:
    base-url: http://localhost:11434
    default-model: llama2

  logging:
    enabled: true
    influxdb:
      url: ${INFLUXDB_URL}
      token: ${INFLUXDB_TOKEN}
      org: ${INFLUXDB_ORG}
      bucket: ai_conversations

Usage Examples¶

Basic Chat¶

curl -X POST http://localhost:1337/api/ai/chat \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "messages": [
      {"role": "user", "content": "Explain MTBF in maintenance management"}
    ]
  }'

Multi-Turn Conversation¶

curl -X POST http://localhost:1337/api/ai/chat \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "conversationId": "maint-analysis-001",
    "systemPrompt": "You are a maintenance analysis expert. Provide concise, actionable advice.",
    "messages": [
      {"role": "user", "content": "We have a pump failing every 2 months"},
      {"role": "assistant", "content": "That failure frequency suggests a systematic issue. What type of pump is it and what are the failure symptoms?"},
      {"role": "user", "content": "Centrifugal pump, bearing failures each time"}
    ]
  }'

Using Different Providers¶

# Use Gemini for a specific query
curl -X POST http://localhost:1337/api/ai/chat \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gemini",
    "model": "gemini-pro",
    "messages": [
      {"role": "user", "content": "Generate a maintenance checklist for HVAC systems"}
    ],
    "temperature": 0.5
  }'

Getting Analytics¶

# Get cost breakdown for last month
curl -X GET "http://localhost:1337/api/ai/stats/costs?windowSize=1w" \
  -H "Authorization: Bearer $JWT"

# Get usage by specific user
curl -X GET "http://localhost:1337/api/ai/stats/user/john.doe?limit=20" \
  -H "Authorization: Bearer $JWT"

Best Practices¶

1. Use appropriate models - Use GPT-4 for complex analysis, GPT-3.5 for simple queries
2. Set system prompts - Define the AI's role for better responses
3. Track conversation IDs - Link related messages for context
4. Monitor costs - Use analytics to optimize usage
5. Handle errors gracefully - Providers may be temporarily unavailable

Error Codes¶