Spring AI Demos

A collection of hands-on demo applications built with Spring AI, Spring Boot 4 and Java 25, showing how to integrate LLMs (OpenAI and Ollama), build a RAG pipeline, generate images and audio, and wire models to external tools through MCP (Model Context Protocol).

Each app is an independent Spring Boot project with its own Maven wrapper, so you can run any of them on its own.

Stack

Apps

1. springai-openai — OpenAI Chat Playground

Free chat, expert personas, code generation/explanation, and structured (typed) outputs with Spring AI's ChatClient.

Key endpoints (AiController):

• GET /greeting — one-line hello
• POST /chat, POST /chat-expert — free chat, Java/Spring expert persona
• POST /generate-code, POST /explain-code — code generation and explanation
• POST /chat-format, POST /analyze — structured summaries and analysis
• GET /city-info?city=, POST /classify-typed — typed records (CityInfo, TicketClassification)
• POST /generate-code-json, POST /explain-code-json, POST /expert-architect-json — typed JSON outputs
• GET /chat-metadata?prompt= — answer plus raw ChatResponse metadata

Requires: OPENAI_API_KEY (see spring.config.import=optional:file:.env[.properties]).

2. springai-ollama — Ollama Chat Playground (local, no cloud)

The same feature set as the OpenAI app, backed by a local Ollama server with qwen3:4b. No API keys, fully offline.

Requires: Ollama running at http://localhost:11434 with qwen3:4b pulled.

3. springai-rag — RAG with PostgreSQL + pgvector

Upload a PDF, index it into pgvector using Ollama embeddings, then ask questions grounded in your own documents.

Endpoints:

• POST /index-upload/pdf — multipart PDF upload → PagePdfDocumentReader → TokenTextSplitter (chunk 800, min 350 chars) → pgvector
• POST /rag/ask — top-4 similaritySearch + grounded prompt (answers only from context)

Requires: PostgreSQL with pgvector (spring_ai_rag database, schema auto-created), Ollama with qwen3:4b and nomic-embed-text.

4. springai-image-generate — Text-to-Image

Generate a PNG from a text prompt via the OpenAI Images API.

• GET /api/images/generate?prompt= — returns inline PNG bytes (b64_json)

Requires: OPENAI_API_KEY.

5. springai-audio — Text-to-Speech

Convert text to MP3 using the OpenAI TTS API.

• GET /api/tts?text= — returns audio/mpeg bytes (gpt-4o-mini-tts, voice alloy)

Requires: OPENAI_API_KEY.

6. springai-mcp-server — MCP Server (weather tools)

A Spring AI MCP server exposing weather tools over streamable HTTP on port 8081 (endpoint /mcp).

Tools (@McpTool):

• getCurrentWeatherTemperature(city) — temperature for Santiago, Madrid, Buenos Aires, Ciudad de México (demo data)
• getWeatherRecommendation(city) — clothing advice per city

7. springai-mcp-client — MCP Client (LLM + tools)

An Ollama-backed chat client that consumes the MCP server's weather tools via tool-calling.

• GET /api/weather/ask?question= — natural-language weather question (e.g., "¿qué temperatura hace en Santiago?")

Requires: MCP server (app 6) running on http://localhost:8081/mcp, Ollama with qwen3:4b.

How to run

Each app is self-contained. From the app folder:

# OpenAI / Image / Audio apps: create a .env with your key first
echo "OPENAI_API_KEY=sk-..." > .env

# Ollama / RAG apps: make sure Ollama is running
ollama pull qwen3:4b
ollama pull nomic-embed-text   # only for RAG

# RAG: PostgreSQL with pgvector (e.g. via docker)
docker run -d --name pgvector -p 5432:5432 \
  -e POSTGRES_DB=spring_ai_rag -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres \
  pgvector/pgvector:pg17

# MCP client needs the MCP server on :8081 first, then:
./mvnw spring-boot:run

Notes

• springai-ollama intentionally mirrors the OpenAI app's controller/service structure — only the model provider changes, which makes it easy to compare cloud vs. local inference.
• Tests are @SpringBootTest context-load smoke tests (7 total).
• .env files with real API keys are gitignored — provide your own.

License

Demo material for learning purposes.