openccb/docs/TOKEN_USAGE_TRACKING.md

📊 Token Usage Tracking - Implementación Completa

✅ Lo Que Se Implementó

1. Base de Datos ✅

• Tabla ai_usage_logs para registrar cada llamada a IA
• Función log_ai_usage() para logging fácil
• Vista ai_usage_daily para reportes
• Índices para queries rápidos

2. Función count_tokens() ✅

fn count_tokens(text: &str) -> i32 {
    // Aproximación: 1 token ≈ 4 caracteres
    let char_count = text.len();
    ((char_count as f64) / 4.0).ceil() as i32
}

Precisión:

• ✅ Suficiente para estimaciones de costo
• ✅ Rápida (no requiere librerías externas)
• ✅ Funciona para inglés y español

3. Endpoints con Tracking ✅

generate_quiz

// Calcular tokens
let input_tokens = count_tokens(&system_prompt) + count_tokens(&content_text);
let output_tokens = count_tokens(&response_json.to_string());
let total_tokens = input_tokens + output_tokens;

// Loguear
let _ = sqlx::query("SELECT log_ai_usage($1, $2, $3, $4, $5, $6, $7, $8, $9)")
    .bind(claims.sub)
    .bind(org_ctx.id)
    .bind(total_tokens)
    .bind(input_tokens)
    .bind(output_tokens)
    .bind("/lessons/generate-quiz")
    .bind(&model)
    .bind("quiz-generation")
    .bind(&json!({ "lesson_id": id, "quiz_type": quiz_req.quiz_type }))
    .execute(&pool)
    .await;

4. Endpoint Admin ✅

• /admin/token-usage - Ver uso por usuario
• Muestra:
  • Total tokens por usuario
  • Input vs output tokens
  • Número de requests
  • Costo estimado en USD
  • Última actividad

5. UI Dashboard ✅

• Página /admin/token-usage
• Stats cards con:
  • Total tokens
  • Requests IA
  • Costo estimado
  • Usuarios activos
• Tabla filtrable por rol
• Alertas de alto consumo (>1M tokens)

📊 Esquema de la Tabla

CREATE TABLE ai_usage_logs (
    id UUID,
    user_id UUID,
    organization_id UUID,
    tokens_used INTEGER,
    input_tokens INTEGER,
    output_tokens INTEGER,
    endpoint VARCHAR(255),
    model VARCHAR(100),
    request_type VARCHAR(50),
    request_metadata JSONB,
    estimated_cost_usd NUMERIC(10, 6),
    created_at TIMESTAMPTZ
);

💰 Cálculo de Costos

Fórmula (OpenAI-like pricing):

v_cost := (input_tokens * 0.000001) + (output_tokens * 0.000003);
// $1 por 1M input tokens
// $3 por 1M output tokens

Ejemplos:

Endpoint	Input	Output	Total	Costo
generate_quiz	500	800	1,300	$0.0029
transcribe (1 min)	0	150	150	$0.00045
chat (pregunta)	200	300	500	$0.0011

🎯 Endpoints a Implementar

Para tracking completo, agregar en:

1. generate_summary_with_ollama

// Al final de la función
let input_tokens = count_tokens(&text);
let output_tokens = count_tokens(&summary);
let _ = sqlx::query("SELECT log_ai_usage(...)")
    .bind(...)
    .execute(&pool)
    .await;

2. chat con lesson tutor

// En handlers.rs, función de chat
let input_tokens = count_tokens(&conversation_history);
let output_tokens = count_tokens(&ai_response);
// Log...

3. generate_feedback

// Similar a generate_quiz

📈 Dashboard de Admin

Stats en Tiempo Real

┌──────────────┬──────────────┬──────────────┬──────────────┐
│ Total Tokens │ Requests IA  │ Costo USD    │ Usuarios     │
│   5,234,567  │    1,234     │   $15.67     │     345      │
└──────────────┴──────────────┴──────────────┴──────────────┘

Filtros Disponibles

• Por rol (student/instructor/admin)
• Por fecha (daily view)
• Por endpoint
• Por tipo de request

Alertas Automáticas

⚠️ Usuarios con alto consumo detectado
5 usuario(s) han superado 1M de tokens.
Considere implementar límites de uso.

🔧 Límites Sugeridos

Estudiantes

{
  "daily_tokens": 50000,
  "monthly_tokens": 1000000,
  "max_requests_per_day": 100
}

Instructores

{
  "daily_tokens": 200000,
  "monthly_tokens": 5000000,
  "max_requests_per_day": 500
}

Admins

{
  "daily_tokens": 1000000,
  "monthly_tokens": 20000000,
  "max_requests_per_day": 2000
}

📝 Implementación de Límites (Opcional)

// Middleware o check antes de llamada a IA
async fn check_token_limit(
    pool: &PgPool,
    user_id: Uuid,
    daily_limit: i32,
) -> Result<(), StatusCode> {
    let today_usage: i64 = sqlx::query_scalar(
        "SELECT COALESCE(SUM(tokens_used), 0) FROM ai_usage_logs 
         WHERE user_id = $1 AND DATE(created_at) = CURRENT_DATE"
    )
    .bind(user_id)
    .fetch_one(pool)
    .await?;
    
    if today_usage > daily_limit as i64 {
        return Err(StatusCode::TOO_MANY_REQUESTS);
    }
    
    Ok(())
}

🎯 Métricas Clave

Por Usuario

• Total tokens (lifetime)
• Tokens hoy
• Requests hoy
• Costo acumulado

Por Organización

• Total tokens (todos los usuarios)
• Top users
• Costo mensual
• Growth trend

Por Endpoint

• Most used endpoints
• Average tokens per request
• Error rates

📖 Uso del Dashboard

1. Ver uso general

   • Ve a /admin/token-usage
   • Revisa stats cards

2. Filtrar por rol

   • Selecciona "Estudiantes" o "Instructores"
   • Ordena por "Total Tokens"

3. Identificar power users

   • Ordena por "Total Tokens"
   • Revisa usuarios > 1M tokens

4. Monitorear costos

   • Revisa "Costo USD"
   • Proyecta uso mensual

5. Detectar anomalías

   • Alertas automáticas > 1M tokens
   • Picos de uso inusuales

🚀 Próximos Pasos

Corto Plazo

• Agregar logging en todos los endpoints de IA
• Implementar límites suaves (warnings)
• Exportar CSV de usage

Mediano Plazo

• Límites duros (block requests)
• Notificaciones email (80% del límite)
• Gráficos de tendencia

Largo Plazo

• Budget por organización
• Alertas de costo
• Integration con sistemas de billing

📁 Archivos Modificados

services/cms-service/migrations/20260316000002_ai_usage_tracking.sql
services/cms-service/src/handlers.rs
  + count_tokens() function
  + Token logging in generate_quiz
services/cms-service/src/handlers_admin.rs (NUEVO)
  + get_token_usage endpoint
services/cms-service/src/main.rs
  + /admin/token-usage route
shared/common/src/models.rs
  + TokenUsage models
web/studio/src/app/admin/token-usage/page.tsx (NUEVO)
  + Admin dashboard UI
web/studio/src/app/admin/page.tsx
  + Link a Token Usage

✅ Estado

Componente	Estado
DB Schema	✅ 100%
Logging Function	✅ 100%
generate_quiz Tracking	✅ 100%
Admin Endpoint	✅ 100%
Admin Dashboard UI	✅ 100%
Límites	⏸️ Listo para implementar
Otros Endpoints	⏳ Pendiente agregar

Progreso Total: 80% 🎉