Embedders

Methods on this page are called as client.embedders.<method>(...) where client is either a synchronous Goodmem or asynchronous AsyncGoodmem instance initialized below:

from goodmem import Goodmem
client = Goodmem(base_url='http://localhost:8080', api_key='gm_...')

from goodmem import AsyncGoodmem
client = AsyncGoodmem(base_url='http://localhost:8080', api_key='gm_...')

Create a new embedder

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 {owner_id, provider_type, endpoint_url, api_path, model_identifier, dimensionality, distribution_type, credentials_fingerprint} 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 api_path 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).

• display_name (str) — User-facing name of the embedder
• model_identifier (str) — The string that identifies the embedder. Usually the model identifier assigned by HuggingFace or the LLM provider, e.g., "text-embedding-3-small" by OpenAI. When a known model, auto-fills provider_type, endpoint_url, dimensionality, max_sequence_length, and supported_modalities.
• api_key (str, optional) — A convenience shorthand for credentials. Converts a plain API key string to the full EndpointAuthentication structure (i.e. {"kind": "CREDENTIAL_KIND_API_KEY", "api_key": {"inline_secret": "sk-..."}}). Most SaaS/cloud and/or proprietary providers (e.g., OpenAI, Cohere, Jina, Voyage, OpenRouter, Gemini) require an API key. At most one of api_key and credentials may be provided.
• api_path (str, optional) — API path for embeddings request (defaults: Cohere /v2/embed, TEI /embed, others /embeddings)
• credentials (EndpointAuthentication, optional) — Structured credential payload describing how to authenticate with the provider. Can also be set via the convenience shorthand api_key. At most one of api_key and credentials may be provided.
• description (str, optional) — Description of the embedder
• dimensionality (int, optional) — Output vector dimensions. Auto-inferred from model_identifier for known models (using dimensions.default from the model registry); required when model_identifier is not in the model registry.
• distribution_type (DistributionType, optional, SDK default='"DENSE"') — The distribution type of the embedder's vector output. Defaults to "DENSE" when not specified.
• embedder_id (str, optional) — Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.
• endpoint_url (str, optional) — Base URL for the embedding endpoint. Auto-inferred from provider_type for known providers.
• labels (dict[str, str], optional) — User-defined labels for categorization
• max_sequence_length (int, optional) — Maximum token length accepted by the model. Auto-inferred from model_identifier for known models; required when model_identifier is not in the registry.
• monitoring_endpoint (str, optional) — Monitoring endpoint URL
• owner_id (str, optional) — Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_EMBEDDER_ANY permission if specified.
• provider_type (ProviderType, optional) — Provider backend — one of "OPENAI", "COHERE", "VOYAGE", "JINA", "VLLM", "TEI", "LLAMA_CPP". Use "OPENAI" for OpenAI-compatible endpoints such as Anthropic, Google Gemini, or Mistral. Auto-inferred from model_identifier for known models.
• supported_modalities (list[Modality], optional, server default="['TEXT']") — Modalities supported by this embedder (e.g. ["TEXT"]). Auto-inferred from model_identifier for known models; required when model_identifier is not in the registry.
• version (str, optional) — Version information

embedder = client.embedders.create(
    display_name="Doc Embedder",
    model_identifier="text-embedding-3-small",
    api_key="sk-...",
    labels={"env": "docs"},
)

Get an embedder by ID

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.

• id (str) — The unique identifier of the embedder to retrieve

embedder = client.embedders.get(id="your-embedder-id")
print(embedder.display_name)

List embedders

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 (owner_id filter is ignored if set to another user). With LIST_EMBEDDER_ANY permission, you can see all embedders or filter by any owner_id. This is a read-only operation with no side effects.

• label (dict[str, str], optional) — Filter by label key-value pairs. Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).
• owner_id (str, optional) — Filter embedders by owner ID. With LIST_EMBEDDER_ANY permission, omitting this shows all accessible embedders; providing it filters by that owner. With LIST_EMBEDDER_OWN permission, only your own embedders are shown regardless of this parameter.
• provider_type (ProviderType, optional) — Filter embedders by provider type. Allowed values match the ProviderType schema.

for emb in client.embedders.list():
    print(emb.embedder_id, emb.display_name)

Update an embedder

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: provider_type is IMMUTABLE after creation and cannot be changed.

CRITICAL: Returns HTTP 412 Precondition Failed (FAILED_PRECONDITION) if attempting to update core fields (dimensionality, distribution_type, model_identifier) 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).

• id (str) — The unique identifier of the resource to update.
• request (UpdateEmbedderRequest | dict) — The update payload. Accepts a UpdateEmbedderRequest instance or a plain dict with the same fields. Only specified fields will be modified.

from goodmem.types import UpdateEmbedderRequest
# Option 1: typed request object
updated = client.embedders.update(id="your-embedder-id", request=UpdateEmbedderRequest(
    display_name="Doc Embedder (updated)",
    merge_labels={"version": "2"},
))
assert updated.embedder_id == "your-embedder-id"
# Option 2: plain dict (validated via pydantic)
updated = client.embedders.update(id="your-embedder-id", request={
    "display_name": "Doc Embedder (updated)",
    "merge_labels": {"version": "2"},
})
assert updated.embedder_id == "your-embedder-id"

Delete an embedder

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).

• id (str) — The unique identifier of the embedder to delete

client.embedders.delete(id="your-embedder-id")

Async usage: client.embedders exposes the same methods on AsyncGoodmem; use await / async for as needed.

Data Models

All data models are pydantic v2 models. Fields are shown with their Python attribute names; JSON responses use camelCase aliases (e.g., owner_id → ownerId).

DistributionType

String enum: "DENSE" · "SPARSE"

EmbedderResponse

Embedder configuration information

• embedder_id (str) — Unique identifier of the embedder
• display_name (str) — User-facing name of the embedder
• description (str, optional) — Description of the embedder
• provider_type (ProviderType) — Type of embedding provider
• endpoint_url (str) — API endpoint URL
• api_path (str, optional) — API path for embeddings request
• model_identifier (str) — Model identifier
• dimensionality (int) — Output vector dimensions
• distribution_type (DistributionType) — Type of embedding distribution (DENSE or SPARSE)
• max_sequence_length (int, optional) — Maximum input sequence length
• supported_modalities (list[Modality]) — Supported content modalities
• credentials (EndpointAuthentication, optional) — Structured credential payload used for upstream authentication
• labels (dict[str, str]) — User-defined labels for categorization
• version (str, optional) — Version information
• monitoring_endpoint (str, optional) — Monitoring endpoint URL
• owner_id (str) — Owner ID of the embedder
• created_at (int) — Creation timestamp (milliseconds since epoch)
• updated_at (int) — Last update timestamp (milliseconds since epoch)
• created_by_id (str) — ID of the user who created the embedder
• updated_by_id (str) — ID of the user who last updated the embedder

ListEmbeddersResponse

Response containing a list of embedders

• embedders (list[EmbedderResponse]) — List of embedder configurations

UpdateEmbedderRequest

Request body for updating an existing Embedder. Only fields that should be updated need to be included.

• display_name (str, optional) — User-facing name of the embedder
• description (str, optional) — Description of the embedder
• endpoint_url (str, optional) — API endpoint URL
• api_path (str, optional) — API path for embeddings request
• model_identifier (str, optional) — Model identifier
• dimensionality (int, optional) — Output vector dimensions
• distribution_type (DistributionType, optional) — Type of embedding distribution (DENSE or SPARSE)
• max_sequence_length (int, optional) — Maximum input sequence length
• supported_modalities (list[Modality], optional) — Supported content modalities
• credentials (EndpointAuthentication, optional) — Structured credential payload describing how to authenticate with the provider
• replace_labels (dict[str, str], optional) — Replace all existing labels with these (mutually exclusive with merge_labels)
• merge_labels (dict[str, str], optional) — Merge these labels with existing ones (mutually exclusive with replace_labels)
• version (str, optional) — Version information
• monitoring_endpoint (str, optional) — Monitoring endpoint URL