Types Reference

data class LlmOptions @JvmOverloads constructor(
    var modelSelectionCriteria: ModelSelectionCriteria? = null,
    var model: String? = null,
    var role: String? = null,
    override var temperature: Double? = null,
    override var frequencyPenalty: Double? = null,
    override var maxTokens: Int? = null,
    override var presencePenalty: Double? = null,
    override var topK: Int? = null,
    override var topP: Double? = null,
    var thinking: Thinking? = null,
    var timeout: Duration? = null
) : LlmHyperparameters, HasInfoString

sealed interface ModelSelectionCriteria

data class ByNameModelSelectionCriteria(val name: String) : ModelSelectionCriteria
data class ByRoleModelSelectionCriteria(val role: String) : ModelSelectionCriteria
data class RandomByNameModelSelectionCriteria(val names: List<String>) : ModelSelectionCriteria
data class FallbackByNameModelSelectionCriteria(val names: List<String>) : ModelSelectionCriteria
object AutoModelSelectionCriteria : ModelSelectionCriteria
object DefaultModelSelectionCriteria : ModelSelectionCriteria

class Thinking private constructor(
    val enabled: Boolean = false,
    val tokenBudget: Int? = null,
    val extractThinking: Boolean = false
)

interface LlmHyperparameters {
    val temperature: Double?
    val frequencyPenalty: Double?
    val maxTokens: Int?
    val presencePenalty: Double?
    val topK: Int?
    val topP: Double?
}

interface ModelMetadata {
    val name: String
    val provider: String
    val type: ModelType
}

enum class ModelType {
    LLM,
    EMBEDDING
}

interface LlmMetadata : ModelMetadata {
    val knowledgeCutoffDate: LocalDate?
    val pricingModel: PricingModel?
}

interface EmbeddingServiceMetadata : ModelMetadata

data class EmbeddingServiceMetadataImpl(
    override val name: String,
    override val provider: String
) : EmbeddingServiceMetadata

interface AiModel<M> : ModelMetadata, HasInfoString {
    val model: M
    fun infoString(verbose: Boolean?, indent: Int): String
}

open class JacksonOutputConverter<T>(
    clazz: Class<T>,
    objectMapper: ObjectMapper
) : StructuredOutputConverter<T> {
    val objectMapper: ObjectMapper
    val jsonSchema: String
    fun convert(text: String): T?
    fun getFormat(): String
    protected open fun postProcessSchema(jsonNode: JsonNode)
}

open class FilteringJacksonOutputConverter<T>(
    clazz: Class<T>,
    objectMapper: ObjectMapper,
    propertyFilter: Predicate<String>
) : JacksonOutputConverter<T>

interface StructuredOutputConverter<T> {
    fun convert(text: String): T?
    fun getFormat(): String
}

fun interface OptionsConverter<O : ChatOptions> {
    fun convertOptions(options: LlmOptions): O
}

object DefaultOptionsConverter : OptionsConverter<ChatOptions> {
    override fun convertOptions(options: LlmOptions): ChatOptions
}

class StreamingJacksonOutputConverter<T>(
    clazz: Class<T>,
    objectMapper: ObjectMapper,
    propertyFilter: Predicate<String> = Predicate { true }
) : FilteringJacksonOutputConverter<T> {
    fun convertStream(jsonlContent: String): Flux<T>
    fun convertStreamWithThinking(text: String): Flux<StreamingEvent<T>>
    override fun getFormat(): String
}

sealed interface StreamingEvent<T> {
    data class Object<T>(val item: T) : StreamingEvent<T>
    data class Thinking(
        val content: String,
        val state: ThinkingState
    ) : StreamingEvent<Nothing>
}

enum class ThinkingState {
    NONE,
    START,
    END,
    BOTH,
    CONTINUATION
}

interface PricingModel {
    fun usdPerInputToken(): Double
    fun usdPerOutputToken(): Double
    fun costOf(inputTokens: Int, outputTokens: Int): Double
    fun costOf(usage: Usage): Double
}

class PerTokenPricingModel(
    val usdPer1mInputTokens: Double,
    val usdPer1mOutputTokens: Double
) : PricingModel

const val ONE_MILLION = 1000000.0

interface PromptContributor : PromptElement {
    fun promptContribution(): PromptContribution
    fun contribution(): String
}

data class PromptContribution(
    val content: String,
    val location: PromptContributionLocation,
    val role: String?
) {
    companion object {
        const val KNOWLEDGE_CUTOFF_ROLE = "knowledge_cutoff"
        const val CURRENT_DATE_ROLE = "current_date"
    }
}

enum class PromptContributionLocation {
    BEGINNING,
    END
}

interface PromptElement {
    val role: String?
    val promptContributionLocation: PromptContributionLocation
}

interface PromptContributorConsumer {
    val promptContributors: List<PromptContributor>
}

class CurrentDate(
    val formatter: DateTimeFormatter = DateTimeFormatter.ofPattern("yyyy-MM-dd")
) : PromptContributor {
    override val role: String
    override val promptContributionLocation: PromptContributionLocation
}

class KnowledgeCutoffDate(
    val date: LocalDate,
    val formatter: DateTimeFormatter = DateTimeFormatter.ofPattern("yyyy-MM")
) : PromptContributor {
    override val role: String
    override val promptContributionLocation: PromptContributionLocation
}

abstract class AbstractYamlModelLoader<T : LlmAutoConfigProvider<*>>(
    private val resourceLoader: ResourceLoader = DefaultResourceLoader(),
    private val configPath: String
) : LlmAutoConfigMetadataLoader<T> {
    protected val logger: Logger
    protected val yamlMapper: ObjectMapper
    override fun loadAutoConfigMetadata(): T
    protected abstract fun getProviderClass(): kotlin.reflect.KClass<T>
    protected abstract fun createEmptyProvider(): T
    protected abstract fun getProviderName(): String
    protected abstract fun validateModels(provider: T)
    protected fun validateCommonFields(model: LlmAutoConfigMetadata)
}

interface LlmAutoConfigMetadata {
    val name: String
    val modelId: String
    val displayName: String?
    val knowledgeCutoffDate: LocalDate?
    val pricingModel: PerTokenPricingModel?
}

interface LlmAutoConfigProvider<T : LlmAutoConfigMetadata> {
    val models: List<T>
}

interface LlmAutoConfigMetadataLoader<T> {
    fun loadAutoConfigMetadata(): T
}

data class ProviderInitialization(
    val provider: String,
    val registeredLlms: List<RegisteredModel>,
    val registeredEmbeddings: List<RegisteredModel>,
    val initializedAt: Instant
) {
    val totalLlms: Int
    val totalEmbeddings: Int
    fun summary(): String
}

data class RegisteredModel(
    val beanName: String,
    val modelId: String
)

interface EmbeddingService : AiModel<Any>, EmbeddingServiceMetadata {
    val dimensions: Int
    fun embed(text: String): FloatArray
    fun embed(texts: List<String>): List<FloatArray>
}

data class SpringAiEmbeddingService(
    override val name: String,
    override val provider: String,
    override val model: EmbeddingModel
) : EmbeddingService {
    override val type: ModelType
    override val dimensions: Int
}

class NoSuitableModelException(
    criteria: ModelSelectionCriteria,
    modelNames: List<String>
) : RuntimeException {
    companion object {
        @JvmStatic
        fun forModels(
            criteria: ModelSelectionCriteria,
            models: List<AiModel<*>>
        ): NoSuitableModelException
    }
}

object ObjectProviders {
    fun <T> empty(): ObjectProvider<T>
}

interface HasInfoString {
    fun infoString(verbose: Boolean?, indent: Int): String
}

LlmOptions (data class)
├── implements LlmHyperparameters
├── implements HasInfoString
├── contains ModelSelectionCriteria
└── contains Thinking

ModelSelectionCriteria (sealed interface)
├── ByNameModelSelectionCriteria
├── ByRoleModelSelectionCriteria
├── RandomByNameModelSelectionCriteria
├── FallbackByNameModelSelectionCriteria
├── AutoModelSelectionCriteria
└── DefaultModelSelectionCriteria

ModelMetadata (interface)
├── LlmMetadata (interface)
│   └── contains PricingModel
└── EmbeddingServiceMetadata (interface)
    └── EmbeddingServiceMetadataImpl (data class)

AiModel<M> (interface)
├── implements ModelMetadata
├── implements HasInfoString
└── wraps model instance

StructuredOutputConverter<T> (interface)
└── JacksonOutputConverter<T> (open class)
    └── FilteringJacksonOutputConverter<T> (open class)
        └── StreamingJacksonOutputConverter<T> (class)

PromptElement (interface)
└── PromptContributor (interface)
    ├── CurrentDate (class)
    └── KnowledgeCutoffDate (class)

PromptContributorConsumer (interface)
└── contains List<PromptContributor>

PricingModel (interface)
└── PerTokenPricingModel (class)

LlmAutoConfigMetadataLoader<T> (interface)
└── AbstractYamlModelLoader<T> (abstract class)
    └── [Provider-specific loaders]

LlmAutoConfigProvider<T> (interface)
└── contains List<T : LlmAutoConfigMetadata>

StreamingEvent<T> (sealed interface)
├── StreamingEvent.Object<T> (data class)
└── StreamingEvent.Thinking (data class)
    └── contains ThinkingState (enum)

EmbeddingServiceMetadata (interface)
└── EmbeddingService (interface)
    ├── implements AiModel<Any>
    └── SpringAiEmbeddingService (data class)

com.embabel.common.ai
├── model
│   ├── LlmOptions
│   ├── ModelSelectionCriteria
│   ├── Thinking
│   ├── ModelMetadata
│   ├── LlmMetadata
│   ├── EmbeddingServiceMetadata
│   ├── EmbeddingService
│   ├── SpringAiEmbeddingService
│   ├── AiModel
│   ├── ModelType
│   └── NoSuitableModelException
├── converters
│   ├── StructuredOutputConverter
│   ├── JacksonOutputConverter
│   ├── FilteringJacksonOutputConverter
│   ├── OptionsConverter
│   └── DefaultOptionsConverter
├── converters.streaming
│   ├── StreamingJacksonOutputConverter
│   ├── StreamingEvent (from embabel-common-core)
│   └── ThinkingState (from embabel-common-core)
├── prompt
│   ├── PromptContributor
│   ├── PromptContribution
│   ├── PromptContributionLocation
│   ├── PromptElement
│   ├── PromptContributorConsumer
│   ├── CurrentDate
│   └── KnowledgeCutoffDate
└── autoconfig
    ├── AbstractYamlModelLoader
    ├── LlmAutoConfigMetadata
    ├── LlmAutoConfigProvider
    ├── LlmAutoConfigMetadataLoader
    ├── ProviderInitialization
    └── RegisteredModel