Package dev.agenor.core.knowledge

Interface EmbeddingProvider

All Known Implementing Classes:
OllamaEmbeddingProvider, OpenAIEmbeddingProvider
public interface EmbeddingProvider
Provider-agnostic interface for generating text embeddings.

Follows the same pattern as LLMProvider: this interface lives in agenor-core with no external dependencies; concrete implementations (OpenAI, Ollama) live in agenor-adapters and are instantiated via EmbeddingProviderFactory.

Example usage: 


 EmbeddingProvider provider = EmbeddingProviderFactory.openAI(System.getenv("OPENAI_API_KEY"));
 float[] vector = provider.embed("What is the return policy?").join();

All operations return CompletableFuture to allow non-blocking I/O in virtual-thread or reactive contexts.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    dimensions()
    Returns the dimensionality of the vectors produced by this provider.
    CompletableFuture<float[]>
    embed(String text)
    Generates a dense embedding vector for the given text.
    default CompletableFuture<List<float[]>>
    embedAll(List<String> texts)
    Generates embedding vectors for a batch of texts.
    String
    modelId()
    Returns the model identifier used by this provider instance.

  • Method Details

    • embed

      CompletableFuture<float[]> embed(String text)
      Generates a dense embedding vector for the given text.
      Parameters:
      text - input text (non-null, non-blank)
      Returns:
      a CompletableFuture that resolves to the embedding vector; the array length equals dimensions()
      Throws:
      EmbeddingException - (wrapped in the future) on provider errors

    • embedAll

      default CompletableFuture<List<float[]>> embedAll(List<String> texts)
      Generates embedding vectors for a batch of texts.

      The default implementation delegates to embed(String) for each element sequentially. Provider implementations should override this method to use a single batched HTTP request where the API supports it (e.g. OpenAI /v1/embeddings with an array input).

      Parameters:
      texts - list of input texts (non-null, non-empty)
      Returns:
      a CompletableFuture resolving to an ordered list of embedding vectors, one per input text
      Throws:
      EmbeddingException - (wrapped in the future) on provider errors

    • dimensions

      int dimensions()
      Returns the dimensionality of the vectors produced by this provider.

      All vectors returned by embed(java.lang.String) and embedAll(java.util.List<java.lang.String>) have exactly this many elements. Callers must use this value when allocating vector stores or computing similarity scores.

      Returns:
      positive integer (e.g. 1536 for text-embedding-3-small)

    • modelId

      String modelId()
      Returns the model identifier used by this provider instance.

      The format is provider-specific (e.g. "text-embedding-3-small" for OpenAI, "nomic-embed-text" for Ollama).

      Returns:
      non-null, non-blank model identifier