ai_providers

🔧 Mejoras en API

• audioFormat opcional: Usuario puede elegir entre M4A (default) o MP3 para salida final
• M4A por defecto: Si no se especifica audioFormat, se usa M4A automáticamente (75% menos espacio)
• PCM interno optimizado: Providers usan PCM internamente, audioFormat solo afecta conversión final
• API simplificada: AiAudioParams() sin parámetros funciona perfectamente

🎯 Conversión de Audio Mejorada

• FFmpeg Kit integrado: Reemplaza flutter_audio_toolkit con ffmpeg_kit_flutter_new ^3.2.0
• Soporte multiplataforma: Android, iOS y macOS con conversión nativa de alta calidad
• FFmpeg nativo como fallback: Linux y Windows pueden usar FFmpeg del sistema si está instalado
• Instrucciones automáticas: Guías de instalación de FFmpeg por plataforma cuando no está disponible
• Triple fallback inteligente: FFmpeg Kit → FFmpeg nativo → WAV sin compresión

🔧 Mejoras Técnicas

• Detección automática de plataforma: _isFFmpegSupported() determina disponibilidad de FFmpeg Kit
• Comandos FFmpeg optimizados: Configuración específica por formato con sample rate 24kHz
• Logging mejorado: Trazas detalladas de conversión y fallbacks por plataforma
• Error handling robusto: Fallback automático a través de múltiples métodos
• Instrucciones contextuales: Mensajes informativos sobre instalación de FFmpeg por distro/OS

✨ Nuevas Características

• AiAudioFormat.m4a y AiAudioFormat.mp3 constantes disponibles
• Validación automática: Solo acepta 'm4a' o 'mp3', fallback a M4A si valor inválido
• Compatibilidad universal: Linux, Windows y Web completamente soportados

📚 Documentación

• Ejemplos muestran uso opcional de audioFormat
• Documentación clarifica M4A como formato recomendado por defecto
• Guías de instalación de FFmpeg incluidas

• AI.listen() ahora retorna Future<AIResponse?>
• autoStop=true (default): retorna AIResponse con transcripción
• autoStop=false: retorna null (usar AI.stopListen() para resultado)
• Actualizar README y CHANGELOG
• Más semántico que retornar AIResponse vacío

🔄 Breaking Changes - Restauración de Nombres Correctos

• AIContext → AISystemPrompt: Renombrado clase principal para reflejar correctamente que todos los providers soportan system prompts
• aiContext → systemPrompt: Renombrado parámetro en todas las APIs para consistencia
• Archivo renombrado: ai_context.dart → ai_system_prompt.dart
• Imports actualizados: Todos los imports actualizados automáticamente en lib/ y example/

🎧 NUEVA FUNCIONALIDAD: AI.listen() y AI.stopListen() con Audio Completo

• AI.listen() mejorado: Ahora devuelve AIResponse con transcripción Y audio grabado (URL + base64)
• AI.stopListen() actualizado: Cambia de Future<String?> a Future<AIResponse?> para consistencia
• Audio completo incluido:
  • response.text - Transcripción del audio
  • response.audio?.url - Ruta del archivo de audio grabado en caché
  • response.audio?.base64 - Audio en base64 para envío directo
  • response.audio?.durationMs - Duración de la grabación
  • response.audio?.transcript - Mismo contenido que text

✨ Sistema de Gestión de Voces

• AdditionalParams sealed class: Nueva abstracción type-safe para parámetros de imagen y audio
• Voice parameter: Parámetro voice añadido a sendMessage() en BaseProvider
• Jerarquía de voces: Saved voice → Config default → Hardcoded fallback
• AIProviderManager: Nuevos métodos _selectVoice() y getVoiceForRequest()
• Getters convenientes: imageParams y audioParams en AdditionalParams

🎯 Corrección de Soporte System Prompts + processHistory() Obligatorio

• xAI (Grok): Verificado soporte de role: system en messages (OpenAI compatible)
• Google Gemini: Usa systemInstruction field nativo (no en messages)
• OpenAI: Usa role: system en messages array (formato estándar)
• processHistory() abstracto: Método obligatorio en BaseProvider para manejo consistente de historial
• Documentación: Rationale actualizado - TODOS los providers soportan system prompts

🔧 Mejoras Técnicas

• Serialización explícita: profile.toJson() en lugar de pasar objetos directamente
• Prompt simple + Context poderoso: Patrón híbrido restaurado para mejor comportamiento del modelo
• Debug mejorado: JSON extraction con mejor logging y manejo de errores
• AudioTranscriptionService mejorado: Método _createAIResponseWithAudio() para generar respuestas completas

📋 Migración Requerida

// ❌ ANTES (v1.5.x)
final aiContext = AIContext(context: profile, ...);
await AI.text(prompt, aiContext);

// Para audio:
final transcript = await AI.listen(); // Solo String
final stopped = await AI.stopListen(); // Solo String?

// ✅ AHORA (v1.6.0)
final systemPrompt = AISystemPrompt(context: profile, ...);
await AI.text(prompt, systemPrompt);

// Para audio con datos completos:
final response = await AI.listen();    // AIResponse completo
print(response.text);                  // Transcripción
print(response.audio?.url);            // Archivo de audio
print(response.audio?.base64);         // Audio en base64

final stopped = await AI.stopListen(); // AIResponse? completo

🧪 Testing

• dart analyze: 0 issues en ai_providers y example
• Example actualizado: Demo de audio corregida para usar nueva API
• Tests completos: Sistema de voces y audio completamente implementado
• Pre-commit hooks: dart fix, dart format, dart doc ejecutados automáticamente

🔄 Breaking Changes - Sistema Seed Eliminado

• AiImageParams.seed → sourceImageBase64: Campo seed completamente removido y reemplazado por sourceImageBase64 para edición de imágenes
• ProviderResponse.seed eliminado: Removido campo seed de respuestas de providers
• AiImage.seed eliminado: Modelo AiImage ya no incluye campo seed
• AIProviderManager sin seed: Eliminadas todas las referencias y validaciones de seed

✨ Nuevas Características

• 🖼️ Sistema sourceImageBase64 unificado: Ambos OpenAI y Google ahora soportan edición de imágenes usando Base64 como input
• 🔄 Prompt revisado mejorado en Gemini: Sistema JSON robusto para extraer descripciones detalladas de imágenes generadas
• 🛠️ Utilidad JSON robusta: Nueva json_utils.dart con parsing inteligente de JSON, markdown y texto mixto
• 🎯 Respuestas de políticas inteligentes: Google provider detecta rechazos por finishReason (IMAGE_OTHER, SAFETY, RECITATION)

🔧 Mejoras Técnicas

• JSON estructurado: Gemini ahora responde con formato {"description": "...", "response": "..."} para mejor parsing
• Serialización AIContext mejorada: GoogleProvider usa aiContext.toJson() correctamente
• Fallbacks robustos: Sistema de parsing JSON con multiple fallbacks para máxima compatibilidad
• Manejo de errores: Detección específica de rechazos de contenido con mensajes informativos

📋 Migración Requerida

// ❌ ANTES (v1.4.x)
const params = AiImageParams(
  seed: 'resp_abc123', // Para reutilizar respuesta
  quality: AiImageQuality.high,
);

// ✅ AHORA (v1.5.0)  
const params = AiImageParams(
  sourceImageBase64: 'data:image/png;base64,...', // Para editar imagen
  quality: AiImageQuality.high,
);

🔧 Detalles Técnicos

• OpenAI: sourceImageBase64 se mapea a input_image en la API de Responses
• Gemini: sourceImageBase64 se pasa como inline_data para contexto de edición
• Parsing JSON: extractJsonBlock() con balanceado de llaves y detección de markdown
• Compatibilidad: Sistema de fallback mantiene funcionalidad si el JSON no es válido

⚡ Optimizaciones

• Menor complejidad: Sin manejo dual de seeds vs response IDs
• Mejor UX: Mensajes específicos cuando Google rechaza contenido
• Código más limpio: Eliminadas validaciones y conversiones de seed innecesarias

🔄 Breaking Changes (Estructura de Datos)

• AIResponse renovado: Cambio de propiedades planas a objetos tipados estructurados
• Nuevos modelos: AiImage y AiAudio con campos específicos y metadatos completos
• Base64 optimizado: Disponible durante el proceso, eliminado en memoria final

📦 Nuevos Modelos Exportados

• AiImage: Modelo completo para imágenes con seed, url, prompt, base64, createdAtMs
• AiAudio: Modelo completo para audio con url, transcript, base64, durationMs, isAutoTts
• AIResponse: Estructura unificada con text, image?, audio?

🔧 Migración de API

// ❌ Antes (1.4.2)
final response = await AI.image('Un gato');
final fileName = response.imageFileName;
final base64 = response.imageBase64;

// ✅ Ahora (1.4.3)
final response = await AI.image('Un gato');
final fileName = response.image?.url;
final base64 = response.image?.base64;

⚡ Mejoras de Performance

• Memoria optimizada: Base64 no se almacena permanentemente
• Estructura limpia: Separación clara entre metadatos y datos binarios
• Debug mejorado: Serialización JSON funcional para todos los objetos

📚 Documentación

• Modelos documentados: AiImage, AiAudio, AIResponse con ejemplos completos
• Casos de uso: Ejemplos para TTS, STT, generación de imágenes
• Migración: Guía clara para actualizar código existente

🐛 Bug Fixes Críticos

• Message Context Fix: El mensaje del usuario ahora se agrega correctamente al aiContext.history
• Historial completo: Los providers reciben el contexto completo incluyendo el mensaje actual
• API consistency: Flujo completo desde AI.text() hasta provider funciona correctamente

🔧 Mejoras Técnicas

• AIProviderManager: Agregado mensaje de usuario al historial antes de enviar al provider
• Type Safety: Corrección de tipos en List<Map<String, dynamic>> para history

✅ Impacto

• Conversaciones funcionales: Los mensajes del usuario ahora aparecen en las requests
• Mejor UX: Las respuestas de IA tienen el contexto completo del mensaje
• Sin breaking changes: API pública permanece inalterada

⚡ Optimizaciones de Performance

• History unificado: Eliminado parámetro history duplicado en providers
• Menos memoria: Los providers ahora usan únicamente aiContext.history
• API más limpia: Interface simplificada sin parámetros redundantes
• Cache optimizado: Keys de cache usan aiContext.history directamente

🔧 Mejoras Técnicas

• Providers actualizados: OpenAI, Google, XAI y Android Native providers simplificados
• BaseProvider mejorado: Signatura sendMessage sin parámetro history duplicado
• AIProviderManager optimizado: Eliminada construcción de history redundante
• Mejor eficiencia: Una sola fuente de verdad para el historial de conversación

✅ Compatibilidad

• Sin breaking changes: La API pública permanece igual
• Tests completos: 16/16 tests ai_providers + 63/63 tests ai_chan pasando
• Análisis limpio: 0 errores de analyzer en ambos proyectos

💥 Breaking Changes

• Modelo renombrado: AISystemPrompt → AIContext para mayor claridad conceptual
• Archivo renombrado: ai_system_prompt.dart → ai_context.dart
• Parámetros actualizados: systemPrompt → aiContext en APIs de funciones
• Import actualizado: import 'package:ai_providers/ai_providers.dart' sigue funcionando (re-exportado)

🚀 Mejoras Arquitecturales

• Concepto más claro: AIContext representa el contexto completo de conversación, no solo system prompt
• History real: AIProviderManager ahora usa aiContext.history directamente en lugar de generar historia falsa
• Naming consistency: Separación clara entre context (propiedad del modelo) y aiContext (parámetro de función)
• Flutter compatibility: Evita conflictos de nombres con BuildContext de Flutter

🔧 Mejoras Técnicas

• Mejor abstracción: AIContext encapsula contexto completo: historia, instrucciones, metadatos y contexto de aplicación
• API más intuitiva: Los nombres reflejan mejor la funcionalidad real del modelo
• Retrocompatibilidad: Aunque breaking, la migración es simple (find & replace)

📚 Migración Requerida

// ANTES (v1.3.x)
final systemPrompt = AISystemPrompt(context: profile, ...);
await AI.text(prompt, systemPrompt);

// AHORA (v1.4.0+)
final aiContext = AIContext(context: profile, ...);  
await AI.text(prompt, aiContext);

🚀 Optimizaciones de Performance

• ApiKeyManager inteligente: Elimina rotación inútil de API keys cuando solo hay una configurada
• Failover más rápido: Reduce tiempo de fallback de ~3-4 segundos a inmediato en casos de una sola key
• Mejor manejo de errores: Excepciones específicas cuando se agotan todas las API keys
• Control de flujo mejorado: markCurrentKeyFailed() y markCurrentKeyExhausted() ahora devuelven bool

🔧 Mejoras Técnicas

• base_provider.handleApiError(): Actualizado para manejar nuevos valores de retorno booleanos
• Providers actualizados: OpenAI, Google y XAI providers con mejor manejo de errores
• Logging mejorado: Mensajes más específicos para debugging de API key exhaustion

🗑️ Dependencias Removidas

• flutter_secure_storage: Eliminada dependencia innecesaria que no se usaba en el código
• Compilación mejorada: Resueltos problemas de compilación en Linux por dependencias no utilizadas
• Tamaño reducido: Menos dependencias = instalación más rápida y menor tamaño

🔧 Correcciones

• Example compilando: El proyecto example ahora compila sin problemas en todas las plataformas
• Dependencias limpias: Solo dependencias realmente necesarias

🔧 Mejoras en API

• AiAudioParams.audioFormat con valor por defecto: Ahora es String (no nullable) con valor por defecto 'pcm'
• Uso simplificado: AiAudioParams() sin parámetros funciona perfectamente para casos comunes
• PCM universal: Formato recomendado compatible con todos los proveedores

⚡ Breaking Changes Menores

• audioFormat cambió de String? a String con valor por defecto 'pcm'
• Eliminadas verificaciones de null innecesarias en providers

📚 Documentación

• Comentarios actualizados para reflejar el comportamiento por defecto
• Ejemplos simplificados sin especificar formato cuando no es necesario

🧹 Simplificación y Mejoras

• Eliminado TranscribeInstructions: Simplificamos la arquitectura de audio eliminando la clase TranscribeInstructions que tenía características no utilizadas (anti-hallucination). Ahora AI.listen() usa directamente AIContext.
• AiAudioParams clarificado: La documentación ahora especifica claramente que AiAudioParams es exclusivamente para síntesis de voz (TTS) con AI.speak(), no para transcripción.
• Demo actualizado: El ejemplo audio_demo_screen.dart ahora usa AiAudioParams en lugar de las obsoletas SynthesizeInstructions.

🔧 Cambios Técnicos

• API transcripción simplificada: AI.listen() y AI.transcribe() ahora reciben solo AIContext
• Proveedores actualizados: OpenAI y Google providers ajustados para usar AIContext directamente en transcripción
• Documentación mejorada: AiAudioParams ahora documenta correctamente solo parámetros TTS reales soportados por cada proveedor

📚 Documentación

• README actualizado para reflejar el uso correcto de AiAudioParams vs AIContext
• Comentarios de código clarificados para distinguir entre TTS y STT
• Eliminadas referencias confusas a STT en AiAudioParams

✨ Nuevas Características

• AiImageParams tipado: AI.image() ahora expone un tercer argumento opcional con constantes (AiImageAspectRatio, AiImageFormat, AiImageQuality, etc.) para configurar formato, fondo, fidelidad y seeds sin strings mágicos.
• Enriquecimiento automático de prompts: Los proveedores basados exclusivamente en texto (Gemini) convierten los parámetros en instrucciones legibles, manteniendo un comportamiento consistente.

🤖 Proveedores

• OpenAI: El aspectRatio se mapea internamente a los tamaños recomendados (1024x1024, 1024x1536, 1536x1024) y el seed reutiliza respuestas anteriores si empieza por resp_.
• Gemini: Se preserva el texto original que devuelve el modelo junto con la imagen generada.

📚 Documentación

• README actualizado con el nuevo parámetro de AI.image().
• Documentación completa de AiImageParams añadida en comentarios del código fuente
• Pre-commit hook actualizado para generar documentación automáticamente

🔥 Breaking Changes

• API getAvailableProviders() actualizada: Ahora devuelve List<AIProvider> en lugar de List<Map<String, dynamic>>
• Acceso estructurado: Las propiedades del proveedor ahora son provider.id, provider.displayName, provider.description, etc.
• Migración requerida: Código existente que use provider['id'] debe cambiar a provider.id

✨ Nuevas Características

• 🎯 Modelo AIProvider: Nueva clase simple con propiedades estructuradas para información de proveedores
• 🔧 API más limpia: Acceso directo a propiedades sin Maps, mejor intellisense y autocompletado
• ⚡ Mejor documentación: Todos los métodos y propiedades están documentados en el modelo
• 🛡️ Type Safety: Mejor seguridad de tipos con el modelo estructurado

📋 Detalles Técnicos

• AIProvider class con propiedades: id, displayName, description, capabilities, enabled
• Factory method AIProvider.fromConfig() para conversión desde configuración YAML
• Factory method AIProvider.empty() para casos de error o fallback
• Método supportsCapability() para verificar soporte de capacidades
• Compatibilidad mantenida con ProviderConfig interno (sin breaking changes en configuración YAML)

🔄 Guía de Migración

Antes (v1.2.1 y anteriores):

final providers = AI.getAvailableProviders(AICapability.textGeneration);
for (final provider in providers) {
  print('${provider['displayName']}: ${provider['description']}');
  if (provider['enabled'] == true) {
    // usar provider['id']
  }
}

Después (v1.2.2+):

final providers = AI.getAvailableProviders(AICapability.textGeneration);
for (final provider in providers) {
  print('${provider.displayName}: ${provider.description}');
  if (provider.enabled) {
    // usar provider.id
  }
}

🧪 Testing

• Todos los tests actualizados para usar el nuevo modelo AIProvider
• Ejemplos actualizados en /example con la nueva API
• Zero regressions en funcionalidad existente

🎯 Evolución de la Licencia

• ACTUALIZACIÓN A MPL-2.0: Cambio de CC BY-NC-ND 4.0 a Mozilla Public License 2.0
• Elección Tech-Forward: Licencia copyleft moderna diseñada para ecosistemas de componentes
• Amigable Comercialmente: Uso libre en aplicaciones comerciales manteniendo las modificaciones abiertas
• Estrategia de Protección: Asegura que las mejoras al package permanezcan públicamente disponibles

🌟 ¿Por qué MPL-2.0?

• Copyleft a Nivel de Archivo: Más granular que las licencias tradicionales estilo GPL
• Amigable para Desarrolladores: Diseñada por desarrolladores para componentes de software modernos
• Protección del Ecosistema: Las modificaciones deben compartirse permitiendo trabajos propietarios más grandes
• Adopción en la Industria: Usada por Firefox, ecosistema Rust y empresas tech modernas

Documentación Mejorada

• README Simplificado: Nuevo formato conciso enfocado en uso rápido
• Guía de Arquitectura: Sección sobre arquitectura modular y extensibilidad
• Métodos AI. Completos*: Tablas organizadas por categoría (inicialización, generación, audio, gestión)
• Referencias al Ejemplo: Enlaces directos a la app demo funcional

Detalles Técnicos

• Texto oficial de licencia MPL-2.0 de Mozilla Foundation
• Campo license actualizado en pubspec.yaml
• Compatibilidad perfecta con pub.dev mantenida
• Cero impacto en funcionalidad existente

🎉 Logro Mayor

• PUNTAJE PERFECTO PUB.DEV: Obtenido el máximo 160/160 puntos en análisis de pub.dev
• 100% de Aprobación: Todos los criterios de puntuación de pub.dev completamente satisfechos

🔧 Mejoras de API y Arquitectura

• Optimización de API: Superficie de API pública simplificada de 16 a 10 exports esenciales
• Exports removidos: ai_provider_config.dart, ai_provider_metadata.dart, retry_config.dart
• Mejorado: Organización de exports optimizada para mejor experiencia del desarrollador
• Mantenido: Compatibilidad total hacia atrás para métodos facade AI.*

📋 Mejoras en Puntuación Pub.dev

• Follow Dart file conventions: 30/30 (era 10/30) - Cumplimiento perfecto
• Pass static analysis: 50/50 (era 40/50) - Cero advertencias/errores
• Support up-to-date dependencies: 40/40 (era 20/40) - Compatibilidad completa
• Provide documentation: 20/20 - Documentación excelente mantenida
• Platform support: 20/20 - Soporte completo multi-plataforma

🛠️ Optimizaciones Técnicas

• Corregido: Problemas de compatibilidad de límites inferiores de dependencias
• Actualizado: Dependencias de app de ejemplo (file_picker 8.3.7 → 10.3.3)
• Corregido: Formato de código para coincidir con guías de estilo Dart
• Mejorado: Reconocimiento y cumplimiento de licencia en pub.dev

📊 Métricas de Calidad

• Calidad de Código: Cero problemas de análisis estático
• Documentación: 60.4% cobertura de API con ejemplos comprensivos
• Compatibilidad: Testing completo de downgrade/upgrade de dependencias
• Performance: Estructura de exports optimizada reduce overhead de compilación

Corregido

• Campo license explícito agregado en pubspec.yaml
• Referencias de documentación corregidas en ai_init_config.dart
• Dependencia de test actualizada a versión compatible con Flutter
• Cumplimiento mejorado de puntuación pub.dev

Agregado

• API facade unificada con AI.text(), AI.image(), AI.speak(), AI.listen()
• Soporte multi-provider: OpenAI, Google Gemini, X.AI Grok, Android Native
• Routing dinámico de providers con fallback automático
• Soporte de configuración YAML
• App de ejemplo con demos para todas las capacidades

Características

• Generación de texto (GPT-4.1-mini, Gemini 2.5 Flash, Grok-4)
• Generación de imágenes (GPT-4.1-mini, Gemini 2.5 Flash Image Preview)
• Generación y transcripción de audio (Gemini native TTS/STT, Android native, OpenAI)
• Análisis de imágenes (Gemini 2.5 Flash, GPT-4.1-mini, Grok Vision)

Agregado

• Versión inicial