AI Model Provider Modules

/**
 * Generic provider autoconfiguration pattern
 * 
 * Conditional Requirements:
 * - @ConditionalOnClass: Provider-specific API class
 * - @ConditionalOnProperty: Model selection property (optional)
 * 
 * @AutoConfiguration
 * @ConditionalOnClass(ProviderApi.class)
 * @EnableConfigurationProperties({ProviderChatProperties.class, ProviderConnectionProperties.class})
 */
@AutoConfiguration
@ConditionalOnClass(ProviderApi.class)
@EnableConfigurationProperties({ProviderChatProperties.class, ProviderConnectionProperties.class})
class ProviderAutoConfiguration {
    
    /**
     * Creates provider API client
     * 
     * @Bean
     * @ConditionalOnMissingBean
     * @param properties Connection properties (API key, base URL, etc.)
     * @return Provider API client
     */
    @Bean
    @ConditionalOnMissingBean
    ProviderApi providerApi(ProviderConnectionProperties properties);
    
    /**
     * Creates chat model implementation
     * 
     * @Bean
     * @ConditionalOnMissingBean
     * @param api Provider API client
     * @param properties Chat model properties
     * @return ChatModel implementation
     */
    @Bean
    @ConditionalOnMissingBean
    ChatModel chatModel(ProviderApi api, ProviderChatProperties properties);
    
    // Similar patterns for EmbeddingModel, ImageModel, etc.
}

/**
 * Chat model interface for text generation and conversation
 * 
 * Implemented by: OpenAI, Anthropic, Azure OpenAI, Google Gemini, AWS Bedrock,
 *                 Ollama, Mistral AI, and 11 other providers
 */
org.springframework.ai.chat.model.ChatModel {
    /**
     * Generate a response for the given prompt
     * 
     * @param prompt User message or conversation prompt
     * @return Generated response text
     * @throws TransientAiException for retryable errors (rate limits, timeouts)
     * @throws NonTransientAiException for permanent errors (invalid API key, bad request)
     */
    String call(String prompt);
    
    /**
     * Generate a response with detailed options and metadata
     * 
     * @param prompt Prompt with messages and options
     * @return ChatResponse with generated content, metadata, and usage statistics
     */
    ChatResponse call(Prompt prompt);
    
    /**
     * Stream response tokens as they are generated
     * 
     * @param prompt Prompt with messages and options
     * @return Flux of ChatResponse chunks for streaming responses
     */
    Flux<ChatResponse> stream(Prompt prompt);
}

/**
 * Embedding model interface for text embeddings
 * 
 * Implemented by: OpenAI, Azure OpenAI, Google Gemini, AWS Bedrock,
 *                 Ollama, Mistral AI, and 7 other providers
 */
org.springframework.ai.embedding.EmbeddingModel {
    /**
     * Generate embeddings for text inputs
     * 
     * @param texts List of text strings to embed
     * @return EmbeddingResponse with vector embeddings and metadata
     */
    EmbeddingResponse embedForResponse(List<String> texts);
    
    /**
     * Generate embedding for a single text
     * 
     * @param text Text string to embed
     * @return List of doubles representing the embedding vector
     */
    List<Double> embed(String text);
}

/**
 * Image model interface for image generation
 * 
 * Implemented by: OpenAI (DALL-E), Azure OpenAI, Stability AI, Vertex AI
 */
org.springframework.ai.image.ImageModel {
    /**
     * Generate image from text prompt
     * 
     * @param prompt Image generation prompt with options
     * @return ImageResponse with generated image URLs or data
     */
    ImageResponse call(ImagePrompt prompt);
}

/**
 * Audio transcription model interface for speech-to-text
 * 
 * Implemented by: OpenAI (Whisper), Azure OpenAI
 */
org.springframework.ai.audio.transcription.AudioTranscriptionModel {
    /**
     * Transcribe audio to text
     * 
     * @param prompt Audio transcription prompt with audio resource
     * @return AudioTranscriptionResponse with transcribed text
     */
    AudioTranscriptionResponse call(AudioTranscriptionPrompt prompt);
}

/**
 * Audio speech model interface for text-to-speech
 * 
 * Implemented by: OpenAI (TTS), ElevenLabs
 */
org.springframework.ai.audio.speech.AudioSpeechModel {
    /**
     * Generate speech audio from text
     * 
     * @param prompt Speech generation prompt with text and voice options
     * @return SpeechResponse with audio data
     */
    SpeechResponse call(SpeechPrompt prompt);
}

/**
 * Autoconfigures Anthropic Claude chat models
 * 
 * @ConditionalOnClass: AnthropicApi
 * @ConditionalOnProperty: spring.ai.model.chat=anthropic (optional)
 * 
 * @AutoConfiguration
 */
@AutoConfiguration
class AnthropicChatAutoConfiguration {
    // Bean definitions for Anthropic
}

/**
 * Creates Anthropic API client
 * 
 * @Bean
 * @ConditionalOnMissingBean
 * @param properties Connection properties
 * @return AnthropicApi client
 */
@Bean
@ConditionalOnMissingBean
AnthropicApi anthropicApi(AnthropicConnectionProperties properties);

/**
 * Creates Anthropic chat model
 * 
 * @Bean
 * @ConditionalOnMissingBean
 * @param api Anthropic API client
 * @param properties Chat model properties
 * @return ChatModel implementation
 */
@Bean
@ConditionalOnMissingBean
ChatModel anthropicChatModel(AnthropicApi api, AnthropicChatProperties properties);

spring.ai.anthropic.api-key=your-api-key
spring.ai.anthropic.base-url=https://api.anthropic.com
spring.ai.anthropic.version=2023-06-01
spring.ai.anthropic.beta-version=tools-2024-04-04
spring.ai.anthropic.chat.options.model=claude-3-5-sonnet-20241022
spring.ai.anthropic.chat.options.temperature=0.7
spring.ai.anthropic.chat.options.max-tokens=4096

/**
 * Converts String configuration values to Anthropic ToolChoice enum
 * Registered automatically in AnthropicChatAutoConfiguration
 * 
 * @Component
 */
@Component
class StringToToolChoiceConverter implements Converter<String, AnthropicApi.ToolChoice>

# String values automatically converted to ToolChoice enum
spring.ai.anthropic.chat.options.tool-choice=auto
spring.ai.anthropic.chat.options.tool-choice=any
spring.ai.anthropic.chat.options.tool-choice=none

/**
 * Autoconfigures Azure OpenAI models (chat, embedding, image, audio)
 * 
 * @AutoConfiguration
 */
@AutoConfiguration
class AzureOpenAiChatAutoConfiguration {
    // Bean definitions for Azure OpenAI chat
}

/**
 * Creates Azure OpenAI chat model
 * 
 * @Bean
 * @ConditionalOnMissingBean
 * @param properties Azure OpenAI connection properties
 * @return ChatModel implementation
 */
@Bean
@ConditionalOnMissingBean
ChatModel azureOpenAiChatModel(AzureOpenAiConnectionProperties properties);

/**
 * Autoconfigures Azure OpenAI embedding model
 * 
 * @AutoConfiguration
 */
@AutoConfiguration
class AzureOpenAiEmbeddingAutoConfiguration {
    // Bean definitions for embeddings
}

/**
 * Creates Azure OpenAI embedding model
 * 
 * @Bean
 * @ConditionalOnMissingBean
 * @param properties Azure OpenAI connection properties
 * @return EmbeddingModel implementation
 */
@Bean
@ConditionalOnMissingBean
EmbeddingModel azureOpenAiEmbeddingModel(AzureOpenAiConnectionProperties properties);

/**
 * Autoconfigures Azure OpenAI image model
 * 
 * @AutoConfiguration
 */
@AutoConfiguration
class AzureOpenAiImageAutoConfiguration {
    // Bean definitions for image generation
}

/**
 * Creates Azure OpenAI image model
 * 
 * @Bean
 * @ConditionalOnMissingBean
 * @param properties Azure OpenAI connection properties
 * @return ImageModel implementation
 */
@Bean
@ConditionalOnMissingBean
ImageModel azureOpenAiImageModel(AzureOpenAiConnectionProperties properties);

/**
 * Autoconfigures Azure OpenAI audio transcription
 * 
 * @AutoConfiguration
 */
@AutoConfiguration
class AzureOpenAiAudioTranscriptionAutoConfiguration {
    // Bean definitions for audio transcription
}

/**
 * Creates Azure OpenAI audio transcription model
 * 
 * @Bean
 * @ConditionalOnMissingBean
 * @return AudioTranscriptionModel implementation
 */
@Bean
@ConditionalOnMissingBean
AudioTranscriptionModel azureOpenAiAudioTranscriptionModel();

# Azure OpenAI
spring.ai.azure.openai.api-key=your-azure-key
spring.ai.azure.openai.endpoint=https://your-resource.openai.azure.com
spring.ai.azure.openai.chat.options.deployment-name=gpt-4
spring.ai.azure.openai.chat.options.temperature=0.7
spring.ai.azure.openai.embedding.options.deployment-name=text-embedding-ada-002
spring.ai.azure.openai.image.options.deployment-name=dall-e-3

# Alternative: Use non-Azure OpenAI via Azure endpoint
spring.ai.azure.openai.open-ai-api-key=your-openai-key

/**
 * Functional interface for customizing Azure OpenAI client builders
 * Allows advanced configuration beyond standard properties
 * 
 * @FunctionalInterface
 */
@FunctionalInterface
interface AzureOpenAIClientBuilderCustomizer {
    /**
     * Customize the Azure OpenAI client builder
     * 
     * @param builder Client builder to customize
     */
    void customize(OpenAIClientBuilder builder);
}

@Configuration
public class AzureOpenAiCustomConfig {

    @Bean
    public AzureOpenAIClientBuilderCustomizer clientCustomizer() {
        return builder -> {
            // Add custom retry policy
            builder.retryPolicy(new CustomRetryPolicy());

            // Add custom HTTP pipeline policy
            builder.addPolicy(new CustomHttpPipelinePolicy());

            // Configure Azure AD authentication
            builder.credential(new DefaultAzureCredentialBuilder().build());
        };
    }
}

/**
 * Autoconfigures AWS Bedrock models
 * Supports multiple model providers via Bedrock Converse API
 * 
 * Conditional Requirements:
 * - @ConditionalOnBean: AwsCredentialsProvider, AwsRegionProvider
 * 
 * @AutoConfiguration
 */
@AutoConfiguration
class BedrockConverseProxyChatAutoConfiguration {
    // Bean definitions for Bedrock chat
}

/**
 * Creates Bedrock chat model
 * 
 * @Bean
 * @ConditionalOnBean({AwsCredentialsProvider.class, AwsRegionProvider.class})
 * @param credentialsProvider AWS credentials provider
 * @param regionProvider AWS region provider
 * @return ChatModel implementation
 */
@Bean
@ConditionalOnBean({AwsCredentialsProvider.class, AwsRegionProvider.class})
ChatModel bedrockChatModel(
    AwsCredentialsProvider credentialsProvider,
    AwsRegionProvider regionProvider
);

// Titan Embeddings
/**
 * Autoconfigures Bedrock Titan embedding model
 * 
 * @AutoConfiguration
 */
@AutoConfiguration
class BedrockTitanEmbeddingAutoConfiguration {
    // Bean definitions for Titan embeddings
}

/**
 * Creates Bedrock Titan embedding model
 * 
 * @Bean
 * @return EmbeddingModel implementation
 */
@Bean
EmbeddingModel bedrockTitanEmbeddingModel();

// Cohere Embeddings  
/**
 * Autoconfigures Bedrock Cohere embedding model
 * 
 * @AutoConfiguration
 */
@AutoConfiguration
class BedrockCohereEmbeddingAutoConfiguration {
    // Bean definitions for Cohere embeddings
}

/**
 * Creates Bedrock Cohere embedding model
 * 
 * @Bean
 * @return EmbeddingModel implementation
 */
@Bean
EmbeddingModel bedrockCohereEmbeddingModel();

# AWS credentials
spring.ai.bedrock.aws.region=us-east-1
spring.ai.bedrock.aws.access-key=your-access-key
spring.ai.bedrock.aws.secret-key=your-secret-key
spring.ai.bedrock.aws.session-token=optional-session-token

# Timeouts
spring.ai.bedrock.aws.timeout=5m
spring.ai.bedrock.aws.connection-timeout=5s

# Bedrock Converse (chat)
spring.ai.bedrock.converse.chat.enabled=true
spring.ai.bedrock.converse.chat.options.model=anthropic.claude-3-sonnet-20240229-v1:0
spring.ai.bedrock.converse.chat.options.temperature=0.7

# Titan Embeddings
spring.ai.bedrock.titan.embedding.model=amazon.titan-embed-image-v1
spring.ai.bedrock.titan.embedding.input-type=IMAGE

# Cohere Embeddings
spring.ai.bedrock.cohere.embedding.model=cohere.embed-multilingual-v3

/**
 * Configuration for AWS SDK connection to Bedrock
 * Handles credentials, region, and client setup
 * 
 * @Configuration
 */
@Configuration
class BedrockAwsConnectionConfiguration {
    // Bean definitions for AWS connection
}

/**
 * Connection properties for AWS Bedrock
 *
 * @ConfigurationProperties(prefix = "spring.ai.bedrock.aws")
 */
class BedrockAwsConnectionProperties {
    private String region;
    private String accessKey;
    private String secretKey;
    private String sessionToken;
    private Duration timeout;
    private Duration connectionTimeout;
}

spring.ai.deepseek.api-key=your-key
spring.ai.deepseek.base-url=https://api.deepseek.com
spring.ai.deepseek.chat.options.model=deepseek-chat
spring.ai.deepseek.chat.options.temperature=0.7

spring.ai.elevenlabs.api-key=your-key
spring.ai.elevenlabs.base-url=https://api.elevenlabs.io
spring.ai.elevenlabs.tts.options.voice-id=voice-id
spring.ai.elevenlabs.tts.options.model-id=eleven_monolingual_v1

spring.ai.google.genai.api-key=your-key
spring.ai.google.genai.base-url=https://generativelanguage.googleapis.com
spring.ai.google.genai.chat.options.model=gemini-pro
spring.ai.google.genai.chat.options.temperature=0.9
spring.ai.google.genai.chat.enable-cached-content=true
spring.ai.google.genai.embedding.options.model=embedding-001

/**
 * Cached content service for Google Gemini
 * Enables content caching for frequently used prompts and context
 *
 * Conditional Requirements:
 * - @Conditional: CachedContentServiceCondition (checks if service is available from chat model)
 * - @ConditionalOnProperty: spring.ai.google.genai.chat.enable-cached-content=true (default)
 * 
 * @Bean
 * @Conditional(CachedContentServiceCondition.class)
 * @ConditionalOnProperty(prefix = "spring.ai.google.genai.chat",
 *                        name = "enable-cached-content", havingValue = "true", matchIfMissing = true)
 * @param chatModel Google GenAI chat model
 * @return Cached content service
 */
@Bean
@Conditional(CachedContentServiceCondition.class)
@ConditionalOnProperty(prefix = "spring.ai.google.genai.chat",
                       name = "enable-cached-content", havingValue = "true", matchIfMissing = true)
GoogleGenAiCachedContentService googleGenAiCachedContentService(GoogleGenAiChatModel chatModel);

spring.ai.huggingface.api-key=your-key
spring.ai.huggingface.chat.options.model=meta-llama/Llama-2-7b-chat-hf
spring.ai.huggingface.embedding.options.model=sentence-transformers/all-MiniLM-L6-v2

spring.ai.minimax.api-key=your-key
spring.ai.minimax.base-url=https://api.minimax.chat
spring.ai.minimax.chat.options.model=abab5.5-chat
spring.ai.minimax.embedding.options.model=embo-01

spring.ai.mistral.api-key=your-key
spring.ai.mistral.base-url=https://api.mistral.ai
spring.ai.mistral.chat.options.model=mistral-large-latest
spring.ai.mistral.chat.options.temperature=0.7
spring.ai.mistral.embedding.options.model=mistral-embed

spring.ai.oci.genai.compartment-id=your-compartment
spring.ai.oci.genai.region=us-chicago-1
spring.ai.oci.genai.chat.options.model=cohere.command-r-plus
spring.ai.oci.genai.embedding.options.model=cohere.embed-english-v3.0

spring.ai.ollama.base-url=http://localhost:11434
spring.ai.ollama.chat.options.model=llama2
spring.ai.ollama.chat.options.temperature=0.8
spring.ai.ollama.embedding.options.model=nomic-embed-text

# Model initialization (automatic model pulling)
spring.ai.ollama.init.pull-model-strategy=WHEN_MISSING
spring.ai.ollama.init.timeout=5m
spring.ai.ollama.init.max-retries=3
spring.ai.ollama.init.chat.include=true
spring.ai.ollama.init.chat.additional-models=codellama,mistral
spring.ai.ollama.init.embedding.include=true
spring.ai.ollama.init.embedding.additional-models=all-minilm

/**
 * Configuration properties for Ollama model initialization
 *
 * @ConfigurationProperties(prefix = "spring.ai.ollama.init")
 */
class OllamaInitializationProperties {
    /**
     * Strategy for pulling models at startup
     * - NEVER: Never pull models automatically (default)
     * - WHEN_MISSING: Pull models only if they don't exist locally
     * - ALWAYS: Always pull models to get latest version
     */
    private PullModelStrategy pullModelStrategy = PullModelStrategy.NEVER;

    /** Timeout for model pull operations (default: 5 minutes) */
    private Duration timeout = Duration.ofMinutes(5);

    /** Maximum retries for model pull operations (default: 0) */
    private int maxRetries = 0;

    /** Chat model initialization settings */
    private ModelTypeInit chat = new ModelTypeInit();

    /** Embedding model initialization settings */
    private ModelTypeInit embedding = new ModelTypeInit();

    static class ModelTypeInit {
        /** Include this model type in initialization (default: true) */
        private boolean include = true;

        /** Additional models to pull besides configured defaults */
        private List<String> additionalModels = List.of();
    }
}

spring.ai.openai.api-key=your-key
spring.ai.openai.base-url=https://api.openai.com
spring.ai.openai.chat.options.model=gpt-4
spring.ai.openai.chat.options.temperature=0.7
spring.ai.openai.chat.options.max-tokens=2000
spring.ai.openai.embedding.options.model=text-embedding-ada-002
spring.ai.openai.image.options.model=dall-e-3
spring.ai.openai.image.options.size=1024x1024
spring.ai.openai.audio.transcription.options.model=whisper-1
spring.ai.openai.audio.speech.options.model=tts-1
spring.ai.openai.audio.speech.options.voice=alloy

/**
 * Utility for resolving OpenAI connection properties
 * Supports shared connection properties with model-specific overrides
 */
class OpenAIAutoConfigurationUtil {
    /**
     * Resolves connection properties with model-specific override pattern
     *
     * @param commonProperties Shared connection properties
     * @param modelProperties Model-specific connection properties
     * @return Resolved connection properties with model overrides applied
     */
    static ResolvedConnectionProperties resolveConnectionProperties(
        OpenAiConnectionProperties commonProperties,
        OpenAiConnectionProperties modelProperties
    );

    /**
     * Record holding resolved connection properties
     */
    record ResolvedConnectionProperties(
        String apiKey,
        String baseUrl,
        String organizationId,
        Map<String, String> headers
    ) {}
}

# Shared connection settings
spring.ai.openai.api-key=default-key
spring.ai.openai.base-url=https://api.openai.com

# Override for chat model only
spring.ai.openai.chat.api-key=chat-specific-key
spring.ai.openai.chat.base-url=https://chat.custom.com

# Embedding model uses shared settings
spring.ai.openai.embedding.options.model=text-embedding-ada-002

spring.ai.openai.sdk.api-key=your-key
spring.ai.openai.sdk.organization-id=your-org
spring.ai.openai.sdk.chat.options.model=gpt-4

# Uses existing PostgreSQL DataSource
spring.ai.postgresml.embedding.enabled=true
spring.ai.postgresml.embedding.options.transformer=distilbert-base-uncased
spring.ai.postgresml.embedding.options.kwargs.device=cpu

spring.ai.stability.api-key=your-key
spring.ai.stability.base-url=https://api.stability.ai
spring.ai.stability.image.options.model=stable-diffusion-xl-1024-v1-0
spring.ai.stability.image.options.width=1024
spring.ai.stability.image.options.height=1024

spring.ai.transformers.embedding.enabled=true
spring.ai.transformers.embedding.options.model-uri=classpath:/models/onnx-all-MiniLM-L6-v2
spring.ai.transformers.embedding.cache.enabled=true

# Connection
spring.ai.vertex.ai.project-id=your-project-id
spring.ai.vertex.ai.location=us-central1

# Chat (Gemini)
spring.ai.vertex.ai.chat.options.model=gemini-pro

# Text Embedding
spring.ai.vertex.ai.embedding.options.model=textembedding-gecko@003

# Multimodal Embedding (text + image)
spring.ai.vertex.ai.multimodal.embedding.options.model=multimodalembedding@001
spring.ai.vertex.ai.multimodal.embedding.options.dimension=1408

# Image Generation
spring.ai.vertex.ai.image.options.model=imagegeneration@005

spring.ai.zhipuai.api-key=your-key
spring.ai.zhipuai.base-url=https://open.bigmodel.cn
spring.ai.zhipuai.chat.options.model=glm-4
spring.ai.zhipuai.embedding.options.model=embedding-2

import org.springframework.ai.chat.model.ChatModel;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;

@Service
public class MultiProviderService {
    private final ChatModel primaryModel;
    private final ChatModel fallbackModel;
    
    public MultiProviderService(
            @Qualifier("openAiChatModel") ChatModel primary,
            @Qualifier("anthropicChatModel") ChatModel fallback) {
        this.primaryModel = primary;
        this.fallbackModel = fallback;
    }
    
    public String chat(String message) {
        try {
            return primaryModel.call(message);
        } catch (Exception e) {
            return fallbackModel.call(message);
        }
    }
}

import org.springframework.ai.openai.OpenAiChatOptions;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.stereotype.Service;

@Service
public class AdvancedChatService {
    private final ChatModel chatModel;
    
    public AdvancedChatService(ChatModel chatModel) {
        this.chatModel = chatModel;
    }
    
    public String chatWithCustomOptions(String message) {
        OpenAiChatOptions options = OpenAiChatOptions.builder()
            .withModel("gpt-4")
            .withTemperature(0.8)
            .withMaxTokens(1000)
            .withTopP(0.9)
            .withFrequencyPenalty(0.5)
            .withPresencePenalty(0.5)
            .build();
        
        return chatModel.call(
            new Prompt(message, options)
        );
    }
}

import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.embedding.EmbeddingResponse;
import org.springframework.stereotype.Service;

@Service
public class EmbeddingService {
    private final EmbeddingModel embeddingModel;
    
    public EmbeddingService(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }
    
    public List<Double> embed(String text) {
        EmbeddingResponse response = embeddingModel.embedForResponse(
            List.of(text)
        );
        return response.getResult().getOutput();
    }
    
    public double similarity(String text1, String text2) {
        List<Double> embedding1 = embed(text1);
        List<Double> embedding2 = embed(text2);
        return cosineSimilarity(embedding1, embedding2);
    }
    
    private double cosineSimilarity(List<Double> a, List<Double> b) {
        double dotProduct = 0.0;
        double normA = 0.0;
        double normB = 0.0;
        for (int i = 0; i < a.size(); i++) {
            dotProduct += a.get(i) * b.get(i);
            normA += Math.pow(a.get(i), 2);
            normB += Math.pow(b.get(i), 2);
        }
        return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
    }
}

# Select chat provider
spring.ai.model.chat=openai  # or anthropic, azure-openai, etc.

# Select embedding provider
spring.ai.model.embedding=openai

# Select image provider
spring.ai.model.image=stability-ai

# Connection
spring.ai.{provider}.api-key=your-key
spring.ai.{provider}.base-url=https://api.example.com

# Chat options
spring.ai.{provider}.chat.options.model=model-name
spring.ai.{provider}.chat.options.temperature=0.7
spring.ai.{provider}.chat.options.max-tokens=2000
spring.ai.{provider}.chat.options.top-p=0.9

# Embedding options
spring.ai.{provider}.embedding.options.model=embedding-model
spring.ai.{provider}.embedding.options.dimensions=1536

# Retry configuration
spring.ai.retry.max-attempts=3
spring.ai.retry.backoff.initial-interval=2s