TramAI - governed AI workflows for Java and Kotlin

tramai-embedding

Version: 0.6.0
Status: Preview (published)
Role: Text embedding generation.

Purpose

The tramai-embedding module converts raw text into numerical vector arrays (embeddings). These embeddings power semantic search and clustering, forming the translation layer between plain text and the tramai-vectorstore-spi modules.

EmbeddingModelRegistry holds named EmbeddingModel configurations when you need to route between several embedding backends; the individual models are directly usable on their own.

Core Concepts

EmbeddingModel

The core SPI interface. Translates text into vectors:

  • suspend embed(text: String): FloatArray
  • suspend embedAll(texts: List<String>): List<FloatArray>
  • providerId(): String
  • dimensions(): Int

This module bundles two implementations:

  • OpenAI embeddings — OpenAiEmbeddingModel(apiKey, model = "text-embedding-3-small")
  • Ollama embeddings — OllamaEmbeddingModel(baseUrl = "http://localhost:11434", model = "nomic-embed-text")

Both opt in to the experimental transport API (@OptIn(ExperimentalProviderTransportApi::class)), so they sit outside the stable compatibility promise.

Dependencies

// build.gradle.kts
dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-embedding")
}

Quick Start

import dev.tramai.embedding.OpenAiEmbeddingModel

val model = OpenAiEmbeddingModel(apiKey = System.getenv("OPENAI_API_KEY"))

// Generate vectors
val embeddings = model.embedAll(listOf(
    "What is the capital of France?",
    "How do I sort an array in Kotlin?",
))

println("Vector dimensions: ${embeddings[0].size}")

When to use this module

  • You are configuring a RAG pipeline.
  • You need to calculate document similarity, cluster text, or perform semantic search.

When NOT to use this module

  • You are strictly generating text (chat/completions) without any vector search components.
Previous
Next