API Reference

/**
 * Generic support for OpenAI compatible models.
 *
 * @param baseUrl The base URL of the OpenAI API. Null for OpenAI default (https://api.openai.com).
 * @param apiKey The API key for the OpenAI compatible provider, or null for no authentication.
 * @param completionsPath Custom path for completions endpoint (optional, null uses provider default)
 * @param embeddingsPath Custom path for embeddings endpoint (optional, null uses provider default)
 * @param observationRegistry Micrometer observation registry for observability
 * @param requestFactory Optional HTTP request factory provider (defaults to empty)
 */
open class OpenAiCompatibleModelFactory(
    val baseUrl: String?,
    private val apiKey: String?,
    private val completionsPath: String?,
    private val embeddingsPath: String?,
    private val observationRegistry: ObservationRegistry,
    private val requestFactory: ObjectProvider<ClientHttpRequestFactory> = ObjectProviders.empty()
)

/**
 * Creates an LLM service for OpenAI-compatible models
 *
 * @param model Model name/identifier (e.g., "gpt-4", "gpt-3.5-turbo", "llama-3-70b")
 * @param pricingModel Pricing model for cost tracking (use PricingModel.usdPer1MTokens or PricingModel.ALL_YOU_CAN_EAT)
 * @param provider Provider name (e.g., "OpenAI", "Azure OpenAI", "Ollama", "Custom Provider")
 * @param knowledgeCutoffDate Knowledge cutoff date (optional, null if unknown)
 * @param optionsConverter Options converter (defaults to OpenAiChatOptionsConverter)
 * @param retryTemplate Retry template for resilience (defaults to Spring AI default)
 * @return LlmService configured with the specified model
 */
@JvmOverloads
fun openAiCompatibleLlm(
    model: String,
    pricingModel: PricingModel,
    provider: String,
    knowledgeCutoffDate: LocalDate?,
    optionsConverter: OptionsConverter<*> = OpenAiChatOptionsConverter,
    retryTemplate: RetryTemplate = RetryUtils.DEFAULT_RETRY_TEMPLATE
): LlmService<*>

val service = factory.openAiCompatibleLlm(
    model = "gpt-4-turbo",
    pricingModel = PricingModel.usdPer1MTokens(10.0, 30.0),
    provider = "OpenAI",
    knowledgeCutoffDate = LocalDate.of(2023, 12, 1),
    optionsConverter = StandardOpenAiOptionsConverter
)

/**
 * Creates an embedding service for OpenAI-compatible models
 *
 * @param model Embedding model name/identifier (e.g., "text-embedding-3-small", "text-embedding-3-large")
 * @param provider Provider name (e.g., "OpenAI", "Azure OpenAI")
 * @return EmbeddingService configured with the specified model
 */
fun openAiCompatibleEmbeddingService(
    model: String,
    provider: String
): EmbeddingService

val service = factory.openAiCompatibleEmbeddingService(
    model = "text-embedding-3-large",
    provider = "OpenAI"
)

/**
 * Logger instance for the factory class
 */
protected val logger: Logger

/**
 * The configured OpenAI API instance
 */
protected val openAiApi: OpenAiApi

/**
 * Creates a Spring AI ChatModel with the configured API
 *
 * @param model Model name/identifier
 * @param retryTemplate Retry template for resilience
 * @return ChatModel configured with the specified model
 */
protected fun chatModelOf(
    model: String,
    retryTemplate: RetryTemplate
): ChatModel

/**
 * Interface for converting portable LlmOptions to provider-specific ChatOptions
 */
fun interface OptionsConverter<O : ChatOptions> {
    fun convertOptions(options: LlmOptions): O
}

/**
 * Default options converter for OpenAI models.
 * Safe default that works with most OpenAI models.
 * Some models may not support all options.
 */
object OpenAiChatOptionsConverter : OptionsConverter<OpenAiChatOptions> {
    override fun convertOptions(options: LlmOptions): OpenAiChatOptions
}

/**
 * Options converter for OpenAI models that support all parameters.
 * Explicitly supports: temperature, topP, maxTokens, presencePenalty, frequencyPenalty.
 */
object StandardOpenAiOptionsConverter : OptionsConverter<OpenAiChatOptions> {
    override fun convertOptions(options: LlmOptions): OpenAiChatOptions
}

/**
 * Options converter for GPT-5 models that don't support temperature adjustment.
 * Logs a warning if temperature is set to a non-default value (anything other than 1.0).
 * Supports: topP, maxTokens, presencePenalty, frequencyPenalty.
 * Does NOT support: temperature
 */
object Gpt5ChatOptionsConverter : OptionsConverter<OpenAiChatOptions> {
    override fun convertOptions(options: LlmOptions): OpenAiChatOptions
}

/**
 * LLM service interface
 */
interface LlmService<THIS : LlmService<THIS>> {
    fun createMessageSender(options: LlmOptions): LlmMessageSender
    fun withKnowledgeCutoffDate(date: LocalDate): THIS
    fun withPromptContributor(promptContributor: PromptContributor): THIS
}

/**
 * Embedding service interface
 */
interface EmbeddingService {
    fun embed(text: String): FloatArray
    fun embed(texts: List<String>): List<FloatArray>
    val dimensions: Int
}

/**
 * Factory methods for creating pricing models
 */
object PricingModel {
    /**
     * Per-million-tokens pricing
     *
     * @param usdPer1mInputTokens Cost in USD per 1 million input tokens
     * @param usdPer1mOutputTokens Cost in USD per 1 million output tokens
     * @return PricingModel instance
     */
    fun usdPer1MTokens(usdPer1mInputTokens: Double, usdPer1mOutputTokens: Double): PricingModel

    /**
     * All-you-can-eat pricing (free or fixed cost, no per-token tracking)
     */
    val ALL_YOU_CAN_EAT: PricingModel
}

// GPT-4 pricing
val gpt4Pricing = PricingModel.usdPer1MTokens(30.0, 60.0)

// Free local model
val freePricing = PricingModel.ALL_YOU_CAN_EAT