Skip to main content

​
AI (Anthropic)

Modulo global que proporciona integracion con la API de Anthropic (Claude) para generacion de texto. Actualmente utilizado para insights automaticos en el modulo de encuestas.

​
Configuracion

Variable de entornoRequeridaDescripcion
ANTHROPIC_API_KEYSiAPI key de Anthropic
AI_DEFAULT_MODELNoModelo por defecto. Default: claude-sonnet-4-20250514
El modulo es global — disponible en toda la aplicacion sin necesidad de importarlo. Si ANTHROPIC_API_KEY no esta configurada, el servicio retorna null silenciosamente (graceful degradation).

​
Servicio

AiService expone un unico metodo: 
generateText(options: {
  systemPrompt: string
  userPrompt: string
  model?: string        // default: claude-sonnet-4-20250514
  maxTokens?: number    // default: 1024
  temperature?: number  // default: 0.3
}): Promise<{
  text: string
  model: string
  inputTokens: number
  outputTokens: number
} | null>
Timeout: 30 segundos por request.

​
Survey Insights

La principal aplicacion del modulo AI es la generacion de insights para encuestas.

​
Tabla survey_insights

CampoTipoDescripcion
idUUIDPrimary key
survey_idUUIDFK a surveys
scope_typestringglobal, property, user
scope_idstringID del scope (o __global__)
sectionstringsummary, trends, recommendations
insights_dataJSONB{ main: string, questions: Record<string, string> }
modelstringModelo usado
input_tokensintegerTokens de input
output_tokensintegerTokens de output
total_responsesintegerRespuestas al momento de generacion
daily_generation_countintegerGeneraciones hoy
generation_count_datedateFecha para reset diario
Unique constraint: (survey_id, scope_type, scope_id, section)

​
Cache e invalidacion

  • Los insights se cachean en la tabla survey_insights
  • Se invalidan automaticamente cuando total_responses actual difiere del cacheado (nuevas respuestas)
  • La regeneracion es fire-and-forget (no bloquea el request del usuario)
  • Deduplicacion de requests en vuelo (prevencion de thundering herd)

​
Rate limiting

  • Maximo 3 generaciones por dia por combinacion survey_id + scope_type + scope_id + section
  • Cuando se alcanza el limite, se sirve el cache existente (aunque sea stale)
  • El contador se resetea diariamente

​
Prompts

Los prompts estan en espanol y analizan:
  • Distribucion de respuestas por pregunta
  • Tendencias y patrones
  • Recomendaciones accionables

​
Estructura de modulo

apps/backend/src/shared/ai/
  ai.module.ts          # Global module
  ai.service.ts         # Anthropic SDK wrapper
  ai.types.ts           # TypeScript interfaces

apps/backend/src/surveys/insights/
  survey-insights.service.ts   # Cache, rate limiting, insight generation