embedcontracts

README

go-embed-contracts

Shared text-embedding interface for Go. Contracts only — no provider implementations, no runtime dependencies beyond the Go standard library.

This module exists so that libraries which produce embeddings and libraries which consume them can depend on the same interface without pulling in each other's transitive dependencies.

Status: pre-1.0. The API is small and stable in intent, but minor-version bumps may still adjust shapes until v1.0.0.

Install

go get github.com/hollis-labs/go-embed-contracts

Quickstart

Implement the Embedder interface on your provider type:

package mine

import (
    "context"

    embedcontracts "github.com/hollis-labs/go-embed-contracts"
)

type MyEmbedder struct{ /* client, config, etc. */ }

func (e *MyEmbedder) Embed(ctx context.Context, text, model string) (*embedcontracts.EmbeddingResult, error) {
    // call your provider, return one vector
    return &embedcontracts.EmbeddingResult{Embedding: vec, TokenCount: tokens}, nil
}

func (e *MyEmbedder) EmbedBatch(ctx context.Context, texts []string, model string) ([]embedcontracts.EmbeddingResult, error) {
    // single API call when the provider supports native batching;
    // otherwise loop over Embed.
}

func (e *MyEmbedder) EmbeddingDimensions(model string) int {
    // synchronous, no I/O. Return 0 for unknown models.
    return 1536
}

A complete runnable example lives in examples/inmemory.

Surface

• Embedder interface — Embed, EmbedBatch, EmbeddingDimensions
• EmbeddingResult struct — vector + token count

See the godoc for the contractual guarantees implementers commit to.

Companion module

Chat-model contracts and rate-budget primitives live in github.com/hollis-labs/go-llm-contracts.

Contributing

Issues and pull requests welcome. The interface is intentionally minimal; proposed additions should be motivated by a real consumer need and should not introduce dependencies beyond the standard library.

License

MIT — see LICENSE.

Documentation

Overview

Package embedcontracts defines shared text-embedding contracts used across the hollis-labs portfolio. This module contains interfaces and data shapes only; it provides no provider implementations.

Index

• type Embedder
• type EmbeddingResult

Types

type Embedder

type Embedder interface {
	Embed(ctx context.Context, text string, model string) (*EmbeddingResult, error)
	EmbedBatch(ctx context.Context, texts []string, model string) ([]EmbeddingResult, error)
	EmbeddingDimensions(model string) int
}

Embedder is implemented by providers that produce text embeddings.

Implementers commit to:

• Single-input Embed: one round-trip per call, returning a single vector.
• EmbedBatch: a single API call when the underlying provider supports native batching; otherwise an internal loop over Embed (callers should not assume the batch path is faster than single by default).
• EmbeddingDimensions: synchronous lookup with no I/O. Returns 0 when the model is unknown to the implementer.

Consumers type-assert when needed; not every Provider in the portfolio supports embedding.

type EmbeddingResult

type EmbeddingResult struct {
	// Embedding is the vector representation of the input text.
	Embedding []float32
	// TokenCount is the number of tokens consumed (for billing/rate tracking).
	TokenCount int
}

EmbeddingResult holds the output of an embedding request.