Embedders

package goodmem // import "fury.io/pairsys/goodmem"

Embedder management — provider configuration + lifecycle.

Methods are called as client.Embedders().<Method>(ctx, ...) on a *goodmem.Client. Service: EmbeddersService.

Index

type EmbeddersService
type EmbedderCreationRequest
type DistributionType
type EmbedderResponse
type ListEmbeddersResponse
type UpdateEmbedderRequest

type EmbeddersService

type EmbeddersService struct{ … }

Access this service as client.Embedders() on a *goodmem.Client. Its methods follow.

func (s *EmbeddersService) Create

func (s *EmbeddersService) Create(ctx context.Context, req *models.EmbedderCreationRequest, apiKey string) (*models.EmbedderResponse, error)

Creates a new embedder configuration for vectorizing content. Embedders represent connections to different embedding API services (like OpenAI, vLLM, etc.) and include all the necessary configuration to use them with memory spaces. DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if another embedder exists with identical {ownerId, providerType, endpointUrl, apiPath, modelIdentifier, dimensionality, distributionType, credentialsFingerprint} after URL canonicalization. Uniqueness is enforced per-owner, allowing different users to have identical configurations. Credentials are hashed (SHA-256) for uniqueness while remaining encrypted. The apiPath field defaults to '/v2/embed' for Cohere, '/embed' for TEI, and '/embeddings' for other providers when omitted. Requires CREATE_EMBEDDER_OWN permission (or CREATE_EMBEDDER_ANY for admin users).

HTTP — POST /v1/embedders

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.EmbedderCreationRequest) — the request payload. The linked type documents every field and its JSON wire name.
apiKey (string) — bare provider API key. The convenience layer auto-fills provider / endpoint / dimensionality from the bundled model registry (keyed by the request's model identifier) and converts the key to structured credentials. Pass "" to keep any credentials already set on req.

Returns — (*models.EmbedderResponse, error)

Example

embedder, err := client.Embedders().Create(ctx, &models.EmbedderCreationRequest{
	DisplayName:     "Doc Embedder",
	ModelIdentifier: "text-embedding-3-small",
	Labels:          map[string]string{"env": "docs"},
}, "sk-...")
if err != nil {
	log.Fatal(err)
}
_ = embedder

func (s *EmbeddersService) Get

func (s *EmbeddersService) Get(ctx context.Context, id string) (*models.EmbedderResponse, error)

Retrieves the details of a specific embedder configuration by its unique identifier. Requires READ_EMBEDDER_OWN permission for embedders you own (or READ_EMBEDDER_ANY for admin users to view any user's embedders). This is a read-only operation with no side effects.

HTTP — GET /v1/embedders/{id}

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — The unique identifier of the embedder to retrieve

Returns — (*models.EmbedderResponse, error)

Example

embedder, err := client.Embedders().Get(ctx, "your-embedder-id")
if err != nil {
	log.Fatal(err)
}
_ = embedder.DisplayName

func (s *EmbeddersService) List

func (s *EmbeddersService) List(ctx context.Context, params *EmbeddersListParams) (*models.ListEmbeddersResponse, error)

Retrieves a list of embedder configurations accessible to the caller, with optional filtering. LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production). PERMISSION-BASED FILTERING: With LIST_EMBEDDER_OWN permission, you can only see your own embedders (ownerId filter is ignored if set to another user). With LIST_EMBEDDER_ANY permission, you can see all embedders or filter by any ownerId. This is a read-only operation with no side effects.

HTTP — GET /v1/embedders

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
params (*EmbeddersListParams, optional) — typed query parameters; pass nil for an empty filter set. The linked pkg.go.dev page lists every field.

Returns — (*models.ListEmbeddersResponse, error)

Example

resp, err := client.Embedders().List(ctx, nil)
if err != nil {
	log.Fatal(err)
}
for _, emb := range resp.Embedders {
	_ = emb.EmbedderID
	_ = emb.DisplayName
}

func (s *EmbeddersService) Update

func (s *EmbeddersService) Update(ctx context.Context, id string, req *models.UpdateEmbedderRequest) (*models.EmbedderResponse, error)

Updates an existing embedder configuration including display information, endpoint configuration, model parameters, credentials, and labels. All fields are optional - only specified fields will be updated. IMPORTANT: providerType is IMMUTABLE after creation and cannot be changed. CRITICAL: Returns HTTP 412 Precondition Failed (FAILED_PRECONDITION) if attempting to update core fields (dimensionality, distributionType, modelIdentifier) while the embedder is actively referenced by spaces or ingestion jobs. DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if the update would create a duplicate embedder with the same provider, endpoint, model, dimensionality, distribution, and credentials for this owner. Requires UPDATE_EMBEDDER_OWN permission for embedders you own (or UPDATE_EMBEDDER_ANY for admin users).

HTTP — PUT /v1/embedders/{id}

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — The unique identifier of the embedder to update
req (*models.UpdateEmbedderRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.EmbedderResponse, error)

Example

updated, err := client.Embedders().Update(ctx, "your-embedder-id", &models.UpdateEmbedderRequest{
	DisplayName: goodmem.Ptr("Doc Embedder (updated)"),
	MergeLabels: map[string]string{"version": "2"},
})
if err != nil {
	log.Fatal(err)
}
_ = updated.EmbedderID

func (s *EmbeddersService) Delete

func (s *EmbeddersService) Delete(ctx context.Context, id string) error

Permanently deletes an embedder configuration. This operation cannot be undone and removes the embedder record and securely deletes stored credentials. IMPORTANT: This does NOT invalidate or delete embeddings previously created with this embedder - existing embeddings remain accessible. CONFLICT: Returns HTTP 409 Conflict if the embedder is still referenced by a space. Requires DELETE_EMBEDDER_OWN permission for embedders you own (or DELETE_EMBEDDER_ANY for admin users).

HTTP — DELETE /v1/embedders/{id}

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — The unique identifier of the embedder to delete

Returns — error — nil on success.

Example

err := client.Embedders().Delete(ctx, "your-embedder-id")
if err != nil {
	log.Fatal(err)
}

type EmbedderCreationRequest

type EmbedderCreationRequest struct{ … }

Request body for creating a new Embedder. An Embedder represents a configuration for vectorizing content.

DisplayName (string, wire displayName) — User-facing name of the embedder
Description (string, optional, wire description) — Description of the embedder
ProviderType (models.ProviderType, wire providerType) — Type of embedding provider
EndpointURL (string, wire endpointUrl) — API endpoint URL
APIPath (string, optional, wire apiPath) — API path for embeddings request (defaults: Cohere /v2/embed, TEI /embed, others /embeddings)
ModelIdentifier (string, wire modelIdentifier) — Model identifier
Dimensionality (int32, wire dimensionality) — Output vector dimensions
DistributionType (models.DistributionType, wire distributionType) — Type of embedding distribution (DENSE or SPARSE)
MaxSequenceLength (int32, optional, wire maxSequenceLength) — Maximum input sequence length
SupportedModalities ([]models.Modality, optional, wire supportedModalities) — Supported content modalities (defaults to TEXT if not provided)
Credentials (models.EndpointAuthentication, optional, wire credentials) — Structured credential payload describing how to authenticate with the provider. Required for SaaS providers; optional for local or proxy providers.
Labels (map[string]string, optional, wire labels) — User-defined labels for categorization
Version (string, optional, wire version) — Version information
MonitoringEndpoint (string, optional, wire monitoringEndpoint) — Monitoring endpoint URL
OwnerID (string, optional, wire ownerId) — Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_EMBEDDER_ANY permission if specified.
EmbedderID (string, optional, wire embedderId) — Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.

type DistributionType

type DistributionType string

Type of embedding distribution produced by the embedder

String enum (type DistributionType string): "DENSE" · "SPARSE"

type EmbedderResponse

type EmbedderResponse struct{ … }

Embedder configuration information

EmbedderID (string, wire embedderId) — Unique identifier of the embedder
DisplayName (string, wire displayName) — User-facing name of the embedder
Description (string, optional, wire description) — Description of the embedder
ProviderType (models.ProviderType, wire providerType) — Type of embedding provider
EndpointURL (string, wire endpointUrl) — API endpoint URL
APIPath (string, optional, wire apiPath) — API path for embeddings request
ModelIdentifier (string, wire modelIdentifier) — Model identifier
Dimensionality (int32, wire dimensionality) — Output vector dimensions
DistributionType (models.DistributionType, wire distributionType) — Type of embedding distribution (DENSE or SPARSE)
MaxSequenceLength (int32, optional, wire maxSequenceLength) — Maximum input sequence length
SupportedModalities ([]models.Modality, wire supportedModalities) — Supported content modalities
Credentials (models.EndpointAuthentication, optional, wire credentials) — Structured credential payload used for upstream authentication
Labels (map[string]string, wire labels) — User-defined labels for categorization
Version (string, optional, wire version) — Version information
MonitoringEndpoint (string, optional, wire monitoringEndpoint) — Monitoring endpoint URL
OwnerID (string, wire ownerId) — Owner ID of the embedder
CreatedAt (int64, wire createdAt) — Creation timestamp (milliseconds since epoch)
UpdatedAt (int64, wire updatedAt) — Last update timestamp (milliseconds since epoch)
CreatedByID (string, wire createdById) — ID of the user who created the embedder
UpdatedByID (string, wire updatedById) — ID of the user who last updated the embedder

type ListEmbeddersResponse

type ListEmbeddersResponse struct{ … }

Response containing a list of embedders

Embedders ([]models.EmbedderResponse, wire embedders) — List of embedder configurations

type UpdateEmbedderRequest

type UpdateEmbedderRequest struct{ … }

Request body for updating an existing Embedder. Only fields that should be updated need to be included. supportedModalities is creation-time only and cannot be changed here.

DisplayName (string, optional, wire displayName) — User-facing name of the embedder
Description (string, optional, wire description) — Description of the embedder
EndpointURL (string, optional, wire endpointUrl) — API endpoint URL
APIPath (string, optional, wire apiPath) — API path for embeddings request
ModelIdentifier (string, optional, wire modelIdentifier) — Model identifier
Dimensionality (int32, optional, wire dimensionality) — Output vector dimensions
DistributionType (models.DistributionType, optional, wire distributionType) — Type of embedding distribution (DENSE or SPARSE)
MaxSequenceLength (int32, optional, wire maxSequenceLength) — Maximum input sequence length
Credentials (models.EndpointAuthentication, optional, wire credentials) — Structured credential payload describing how to authenticate with the provider
ReplaceLabels (map[string]string, optional, wire replaceLabels) — Replace all existing labels with these (mutually exclusive with mergeLabels)
MergeLabels (map[string]string, optional, wire mergeLabels) — Merge these labels with existing ones (mutually exclusive with replaceLabels)
Version (string, optional, wire version) — Version information
MonitoringEndpoint (string, optional, wire monitoringEndpoint) — Monitoring endpoint URL

Embedders

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

On this page