Skip to main content

​
Overview

The AI Services module provides specialized services that extend BaseAIService to generate domain-specific content using GROQ AI models. Each service handles a specific task type with optimized prompts, caching, and error handling.

​
Available Services

Checklist AI

Generate maintenance checklists

Activity Summary

Professional activity summaries

Work Order Closeout

Closeout notes generation

​
Common Features

All AI services share these capabilities:
  • Caching: Redis-backed caching to reduce API calls
  • Retry Logic: Exponential backoff with configurable retries
  • Validation: Zod schema validation for inputs/outputs
  • Timeout Management: Configurable timeouts per service
  • Error Handling: Typed error responses
  • Logging: Structured logging for debugging

​
Checklist AI Service

Generates maintenance checklists based on asset and task types.

​
Class Definition

export class ChecklistAIService extends BaseAIService {
  constructor()
  async generateChecklist(
    request: ChecklistGenerationRequest
  ): Promise<ChecklistGenerationResult>
}

​
Configuration

  • Model: llama-3.1-70b-versatile (GROQ)
  • Timeout: 30 seconds
  • Max Retries: 3
  • Cache TTL: 7 days (604800s)

​
generateChecklist()

Generates a maintenance checklist with AI. 
async generateChecklist(
  request: ChecklistGenerationRequest
): Promise<ChecklistGenerationResult>

​
Parameters

​
request
ChecklistGenerationRequest
required

​
Returns

​
result
ChecklistGenerationResult

​
Example

import { ChecklistAIService } from '@/app/lib/services/checklist-ai-service';

const service = new ChecklistAIService();

const result = await service.generateChecklist({
  assetType: 'bomba',
  taskType: 'preventivo',
  customInstructions: 'Incluir verificación de temperatura y vibración',
});

if (result.success && result.checklist) {
  console.log(result.checklist.title);
  console.log(result.checklist.items); // ChecklistItem[]
  console.log(result.cached);          // true if from cache
}

​
Checklist Structure

interface Checklist {
  id: string;
  title: string;
  description: string;
  assetType: AssetType;
  taskType: TaskType;
  items: ChecklistItem[];
  createdAt: Date;
  isTemplate: boolean;
  metadata: {
    generatedBy: 'ai';
    version: string;
  };
}

interface ChecklistItem {
  id: string;
  description: string;
  category: 'seguridad' | 'operacional' | 'mecanico' | 'electrico' | 'documentacion';
  order: number;
  required: boolean;
  notes?: string;
}

​
Activity Summary AI Service

Generates professional summaries of maintenance activities.

​
Class Definition

export class ActivitySummaryAIService extends BaseAIService {
  constructor()
  async generateSummary(
    request: ActivitySummaryRequest
  ): Promise<SummaryGenerationResult>
}

​
Configuration

  • Model: llama-3.1-70b-versatile (GROQ)
  • Timeout: 30 seconds
  • Max Retries: 3
  • Cache TTL: 1 hour (3600s)

​
generateSummary()

Generates a professional activity summary with AI. 
async generateSummary(
  request: ActivitySummaryRequest
): Promise<SummaryGenerationResult>

​
Parameters

​
request
ActivitySummaryRequest
required

​
Returns

​
result
SummaryGenerationResult

​
Example

import { ActivitySummaryAIService } from '@/app/lib/services/activity-summary-ai-service';

const service = new ActivitySummaryAIService();

const result = await service.generateSummary({
  assetType: 'bomba',
  taskType: 'preventivo',
  activities: `
    - Revisión de rodamientos
    - Cambio de aceite lubricante
    - Inspección de sellos mecánicos
    - Medición de vibración
  `,
  style: 'technical',
  detailLevel: 'normal',
});

if (result.success && result.summary) {
  console.log(result.summary.title);
  console.log(result.summary.executive);   // Executive summary
  console.log(result.summary.sections);     // Detailed sections
  console.log(result.summary.metadata.wordCount);
  console.log(result.summary.metadata.readingTime); // minutes
}

​
Summary Structure

interface ActivitySummary {
  id: string;
  title: string;
  executive: string;              // Brief executive summary
  sections: SummarySection[];
  assetType: string;
  taskType: string;
  style: 'executive' | 'technical' | 'detailed';
  detailLevel: 'brief' | 'normal' | 'comprehensive';
  createdAt: Date;
  metadata: {
    wordCount: number;
    readingTime: number;          // minutes
    generatedBy: 'ai';
    version: string;
  };
}

interface SummarySection {
  title: string;
  content: string;
  order: number;
}

​
Work Order Closeout AI Service

Generates professional closeout notes for completed work orders.

​
Class Definition

export class WorkOrderCloseoutAIService extends BaseAIService {
  constructor()
  async generateCloseoutNotes(
    request: CloseoutNotesRequest
  ): Promise<CloseoutGenerationResult>
}

​
Configuration

  • Model: llama-3.1-70b-versatile (GROQ)
  • Timeout: 30 seconds
  • Max Retries: 3
  • Cache TTL: 30 minutes (1800s)

​
generateCloseoutNotes()

Generates professional closeout notes for a work order. 
async generateCloseoutNotes(
  request: CloseoutNotesRequest
): Promise<CloseoutGenerationResult>

​
Parameters

​
request
CloseoutNotesRequest
required

​
Returns

​
result
CloseoutGenerationResult

​
Example

import { WorkOrderCloseoutAIService } from '@/app/lib/services/work-order-closeout-ai-service';

const service = new WorkOrderCloseoutAIService();

const result = await service.generateCloseoutNotes({
  workOrderId: 'WO-2024-001',
  workOrderData: {
    title: 'Mantenimiento preventivo bomba B-101',
    description: 'Mantenimiento trimestral programado',
    assetType: 'bomba',
    taskType: 'preventivo',
    priority: 'normal',
    activities: [
      'Cambio de rodamientos',
      'Reemplazo de sellos',
      'Lubricación',
    ],
    materialsUsed: [
      { name: 'Rodamiento 6308', quantity: 2 },
      { name: 'Sello mecánico', quantity: 1 },
    ],
    timeSpent: { preparation: 30, execution: 120, testing: 30 },
    issues: [],
  },
  style: 'formal',
  includeRecommendations: true,
});

if (result.success && result.notes) {
  console.log(result.notes.summary);
  console.log(result.notes.workPerformed);
  console.log(result.notes.recommendations);
}

​
Closeout Notes Structure

interface CloseoutNotes {
  id: string;
  workOrderId: string;
  summary: string;                    // Executive summary
  workPerformed: string;              // Detailed work description
  findings: string;                   // Findings and observations
  recommendations: string | null;     // Future recommendations
  materialsUsed: string;              // Materials summary
  timeBreakdown: string;              // Time analysis
  nextActions: string | null;         // Follow-up actions
  style: 'formal' | 'concise' | 'detailed';
  createdAt: Date;
  metadata: {
    wordCount: number;
    generatedBy: 'ai';
    version: string;
  };
}

​
Base AI Service

All AI services extend BaseAIService which provides:

​
Core Features

class BaseAIService {
  // Retry with exponential backoff
  protected async executeWithRetry<T>(
    fn: () => Promise<T>
  ): Promise<T>

  // Cache management
  protected async checkCache<T>(key: string): Promise<T | null>
  protected async setCache<T>(key: string, value: T): Promise<void>
  protected buildCacheKey(parts: string[]): string

  // Validation
  protected validate<T>(schema: z.ZodType<T>, data: unknown): T
}

​
Configuration

interface BaseAIServiceConfig {
  serviceName: string;      // Service identifier for logging
  timeoutMs: number;        // Request timeout
  maxRetries: number;       // Max retry attempts
  enableCaching: boolean;   // Enable Redis caching
  cacheTTL: number;         // Cache TTL in seconds
}

​
Error Handling

All services return result objects instead of throwing errors: 
if (!result.success) {
  console.error(result.error);
  // Handle error gracefully
}
Common error scenarios:
  • Validation errors: Invalid input parameters
  • AI errors: Model failures, malformed responses
  • Timeout errors: Request exceeded timeout
  • Network errors: Connection issues

​
Performance Optimization

​
Caching Strategy

  • Checklist: 7 days (templates rarely change)
  • Activity Summary: 1 hour (activities may evolve)
  • Closeout Notes: 30 minutes (work orders in progress)

​
Cache Keys

Generated from request parameters: 
// Checklist
`checklist:${assetType}:${taskType}:${customInstructions}`

// Activity Summary
`summary:${assetType}:${taskType}:${style}:${detailLevel}:${activities.slice(0,100)}`

// Closeout
`closeout:${workOrderId}:${style}:${includeRecs}:${activities.slice(0,2).join(':')}`

​
Retry Logic

Exponential backoff for transient failures: 
Attempt 1: immediate
Attempt 2: 1s delay
Attempt 3: 2s delay
Attempt 4: 4s delay (if maxRetries = 3)

​
Usage in Server Actions

'use server';

import { ChecklistAIService } from '@/app/lib/services/checklist-ai-service';

export async function generateChecklistAction(
  assetType: string,
  taskType: string
) {
  const service = new ChecklistAIService();
  
  const result = await service.generateChecklist({
    assetType: assetType as any,
    taskType: taskType as any,
  });

  if (!result.success) {
    return { error: result.error };
  }

  return { checklist: result.checklist };
}

​
Testing

All services support dependency injection for testing: 
import { ChecklistAIService } from '@/app/lib/services/checklist-ai-service';
import { vi } from 'vitest';

// Mock BaseAIService dependencies
const mockLogger = { info: vi.fn(), error: vi.fn() };
const mockCache = { get: vi.fn(), set: vi.fn() };

const service = new ChecklistAIService();
// Override deps via protected properties in tests

Chat Service

Main chat service orchestration

AI Constants

Model configurations and timeouts

Schemas

Request/response validation schemas

Base AI Service

Shared AI service functionality

Build docs developers (and LLMs) love

Get started for freeTalk to us