Spring AI Project - Demo

Este proyecto es una demostración de una aplicación construida con Spring Boot 4 y Spring AI 2.0, utilizando las últimas versiones disponibles a Enero de 2026.

🧩 Implementaciones de Referencia

Este template ha sido utilizado como base para implementar diversos patrones de agentes y arquitecturas avanzadas. Puedes consultar los siguientes repositorios de ejemplo desarrollados por la comunidad:

• Spring AI Async Agent: Implementación de agentes asíncronos.
• Spring AI Human-in-the-Loop Agent: Patrón que integra aprobación humana en el flujo de ejecución.
• Spring AI React Agent: Implementación del patrón de razonamiento y acción (ReAct).
• Spring AI Reflexion Agent: Agente con capacidades de auto-reflexión y mejora iterativa.
• Spring AI Reflection Agent: Variante enfocada en patrones reflexivos.

🔮 Próximamente (Roadmap)

Basado en las tendencias actuales de ingeniería de IA y cursos de especialización avanzados, se planean desarrollar las siguientes implementaciones de referencia:

• Spring AI Knowledge Graph RAG: Integración avanzada de Retrieval-Augmented Generation utilizando Grafos de Conocimiento (Neo4j) para mejorar la precisión factográfica.
• Spring AI Multimodal RAG: Sistema de búsqueda y recuperación híbrida utilizando modelos multimodales (texto, imágenes y embeddings) con GPT-4V/Gemini y Vector Stores.
• Spring AI SQL Agent: Agente autonómo capaz de interactuar, explorar y consultar bases de datos relacionales (Text-to-SQL) de forma segura.
• Spring AI Long-Term Memory: Implementación de memoria episódica y semántica persistente para agentes, simulando "recuerdo experencial" a largo plazo.
• Spring AI MCP (Model Context Protocol): Implementación de Clientes y Servidores MCP para estandarizar la conexión del agente con herramientas externas y sistemas operativos.
• Spring AI Trust & Safety: Pipeline de seguridad para detección de jailbreaks, anonimización de PII y evaluación de riesgos en tiempo real.

🚀 Versiones Utilizadas

Este proyecto utiliza el stack tecnológico más reciente del ecosistema Spring:

• Java: 21 (LTS)
• Spring Boot: 4.0.1
• Spring AI: 2.0.0-M1 (Milestone 1)

Nota: Al utilizar una versión Milestone (M1), es necesario configurar repositorios adicionales de Spring (spring-milestones) en el pom.xml, ya que estas versiones no están en Maven Central estándar.

🛠️ Cómo crear este proyecto

Para recrear este proyecto desde cero, sigue estos pasos:

1. Generar el proyecto base: Puedes usar Spring Initializr o curl. Dado que Spring Boot 4 es muy reciente, generamos un proyecto web básico primero:

   curl -G https://start.spring.io/starter.zip \
       -d dependencies=web \
       -d type=maven-project \
       -d javaVersion=21 \
       -d bootVersion=3.4.1 \
       -o project.zip
   unzip project.zip

   (Nota: Si Spring Boot 4 no se puede seleccionar directamente, edita el pom.xml tras generar).

2. Configurar pom.xml:

   • Actualizar versión padre: Cambiar spring-boot-starter-parent a 4.0.1.
   • Añadir Repositorio Milestone:

     <repositories>
         <repository>
             <id>spring-milestones</id>
             <name>Spring Milestones</name>
             <url>https://repo.spring.io/milestone</url>
             <snapshots>
                 <enabled>false</enabled>
             </snapshots>
         </repository>
     </repositories>

   • Configurar BOM (Bill of Materials) de Spring AI:

     <dependencyManagement>
         <dependencies>
             <dependency>
                 <groupId>org.springframework.ai</groupId>
                 <artifactId>spring-ai-bom</artifactId>
                 <version>2.0.0-M1</version>
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
         </dependencies>
     </dependencyManagement>

   • Añadir Dependencias:

     <dependency>
         <groupId>org.springframework.ai</groupId>
         <artifactId>spring-ai-starter-model-openai</artifactId>
     </dependency>

🌟 Capacidades de Spring AI (Actualizado 2026)

Spring AI ofrece una API portable y unificada para interactuar con diversos modelos de IA. Las capacidades actuales incluyen:

1. Modelos de IA (Model Client API)

• Chat Models: Interfaz unificada para OpenAI, Azure OpenAI, Amazon Bedrock, Google Vertex AI, Ollama, Anthropic Claude, etc.
• Image Generation: Generación de imágenes (DALL-E, Stability AI).
• Audio: Transcripción (Speech-to-Text) y Texto a Voz (Text-to-Speech) usando modelos como Whisper.
• Embeddings: Conversión de texto a vectores para búsqueda semántica.

2. RAG (Retrieval Augmented Generation)

• Vector Stores: Abstracción para bases de datos vectoriales. Actualmente soporta:
  • PGVector (PostgreSQL)
  • Redis
  • Neo4j
  • MongoDB Atlas
  • Chroma, Weaviate, Milvus, Qdrant, etc.
• Document Readers: Utilidades para leer PDFs, JSON, Texto, Markdown.
• Document Transformers: División de documentos (TokenTextSplitter) para indexación.

3. Herramientas Avanzadas

• Function Calling: Permite a los modelos de IA invocar funciones Java propias (ej. consultar tu base de datos o API externa) de forma transparente.
• Chat Memory: Gestión del historial de conversación para mantener el contexto.
• Evaluation: Framework para evaluar la calidad de las respuestas de la IA.

⚙️ Configuración

Para ejecutar este proyecto, necesitas configurar tu API Key (en este caso para OpenAI) en src/main/resources/application.properties:

spring.ai.openai.api-key=${OPENAI_API_KEY}

O exportarla como variable de entorno:

export SPRING_AI_OPENAI_API_KEY=tu-clave-aqui

📖 Guía de Aprendizaje y Filosofía del Proyecto

Este proyecto es una plantilla técnica diseñada para construir sistemas de producción robustos en Java desde el inicio. Es la opción recomendada cuando la integración empresarial, la escalabilidad y la mantenibilidad a largo plazo son requisitos críticos del caso de uso. A continuación, se resume la hoja de ruta para que desarrolladores se capaciten y comprendan las decisiones de diseño.

🏛️ Filosofía: Colaboración entre Ecosistemas

Este proyecto reconoce el valor inmenso de Python en ciencia de datos y entrenamiento de modelos (Heavy AI).

Aunque el ecosistema Java evoluciona rápidamente integrando capacidades avanzadas (como visión y multimodalidad), Python sigue siendo una herramienta excelente para exploración, entrenamiento y casos de uso "bleeding edge" donde las herramientas JVM aún puedan estar madurando.

Nuestro objetivo es ofrecer un estándar robusto para la IA empresarial, donde Java destaca por su integración con sistemas legacy, concurrencia masiva y tipado fuerte, complementando la agilidad creativa de otros ecosistemas.

Concepto	Enfoque Dinámico (Python)	Enfoque Empresarial (Java/Este Proyecto)
Prompting	F-strings (Rápido y flexible)	Templates versionados (Gobernable y escalable).
Salidas	Diccionarios dinámicos	Tipado Fuerte con Records (Seguridad en tiempo de compilación).
RAG	Ideal para experimentación rápida	ETL Robusto con Apache Tika y Bases de Datos Vectoriales gestionadas.
Agentes	Frameworks de alto nivel (AutoGen)	Patrones Composables (Control granular del flujo).
Orquestación	LangGraph (Potente para grafos)	Spring AI Alibaba Graph (Grafos de estado y persistencia) / Temporal.io.

Nota de Arquitectura: Siguiendo las instrucciones del proyecto, para aquellos casos que ameriten orquestación agéntica avanzada (bucles, memoria persistente de grafo o Human-in-the-loop), se utilizará Spring AI Alibaba Graph como solución estándar, proporcionando una paridad funcional con LangGraph en el ecosistema Java.

🎓 Ruta de Aprendizaje Recomendada (2026)

Para dominar el stack tecnológico de este proyecto, se recomienda la siguiente progresión de recursos educativos:

1. Fundamentos de Spring AI:

   • Curso: "Spring AI: Beginner to Guru" (John Thompson en Udemy).
   • Objetivo: Asentar bases de ChatClient, inyección de dependencias y conexión básica con LLMs.

2. Ingeniería de Datos y RAG:

   • Curso: "Mastering Spring AI: Build AI with Java" (Pritesh Mistry en Udemy).
   • Objetivo: Profundizar en ingestión de documentos, bases de datos vectoriales y transformación de consultas.

3. Arquitectura Avanzada e Interoperabilidad:

   • Curso: "Build AI Apps with Spring AI... MCP, AI Testing" (Madan Reddy en Udemy).
   • Objetivo: Aprender Model Context Protocol (MCP) para conectar herramientas y Testing automatizado de IA.

4. Teoría de Agentes:

   • Curso: "AI Agents in Java..." (Vanderbilt University en Coursera).
   • Objetivo: Comprender la arquitectura cognitiva de los agentes (Planificación, Memoria) más allá del código.

🤖 Asistente de GitHub Copilot

Este repositorio incluye instrucciones especializadas para el agente, ubicadas en .github/instructions/springai.instructions.md.

Estas pautas aseguran que cualquier código generado por la IA respete la arquitectura de referencia:

• Enfoque Java-Nativo: Preferencia por tipado fuerte (Records, POJOs) y conversión estructurada (BeanOutputConverter) frente a JSON crudo.
• Arquitectura Spring AI: Uso de ChatClient fluente, Advisors recursivos y abstracciones oficiales en lugar de ports directos de librerías de Python.
• Calidad de Ingeniería: Integración obligatoria de Testcontainers y Evaluators para pruebas robustas.

📚 Documentación Oficial

Para más detalles, consulta la documentación oficial, que se actualiza constantemente con nuevas integraciones:

• Documentación de Referencia de Spring AI
• Repositorio de GitHub
• Spring AI Alibaba