GoodMemGoodMem
ReferenceClient SDKsPython

Embedders

Python SDK reference for embedder configurations: creation, lookup, listing, updates, and deletion.

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

embedders.create(*, display_name: str, model_identifier: str, api_key: str = None, api_path: str = None, credentials: EndpointAuthentication = None, dashscope_api_dialect: DashScopeApiDialect = None, description: str = None, dimensionality: int = None, distribution_type: DistributionType = "DENSE", embedder_id: str = None, endpoint_url: str = None, gemini_endpoint_config: GeminiEndpointConfig = None, labels: dict[str, str] = None, max_sequence_length: int = None, monitoring_endpoint: str = None, owner_id: str = None, provider_type: ProviderType = None, supported_modalities: list[Modality] = None, version: str = None) → EmbedderResponse

Creates an embedder configuration for use with memory spaces. If owner_id is omitted, the authenticated principal becomes the owner; CREATE_EMBEDDER is evaluated against that proposed embedder and owner. Returns 409 when an equivalent embedder configuration already exists for the owner. See the embedder provider guide for provider-specific configuration.

Parameters:

  • 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-..."}}). Use this for providers configured with API-key authentication. Gemini also supports ADC, which must be supplied through credentials instead. At most one of api_key and credentials may be provided.
  • api_path (str, optional) — Provider-relative request path. Omit or send blank to use the provider default. For Gemini, this is an API version: /v1beta for Developer and /v1 for Google Cloud.
  • credentials (EndpointAuthentication, optional) — Structured credential payload describing how to authenticate with the provider. Required for SaaS providers; optional for local or proxy providers. Can also be set via the convenience shorthand api_key. At most one of api_key and credentials may be provided.
  • dashscope_api_dialect (DashScopeApiDialect, optional) — DashScope request and response API dialect. Valid only for the DASHSCOPE provider. Omit to infer the dialect from api_path, the model catalog, or the native text default.
  • description (str, optional) — Description of the embedder
  • dimensionality (int, format: int32, 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, format: uuid, 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 providers with one canonical base URL. Gemini has distinct Developer and Google Cloud endpoints, so supply the URL that matches gemini_endpoint_config.
  • gemini_endpoint_config (GeminiEndpointConfig, optional) — Gemini backend routing. Valid only for the GEMINI provider. Omit to use the Developer API; when present, backend is required and the gRPC service validates the backend-specific project_id and location contract.
  • labels (dict[str, str], optional) — User-defined labels for categorization
  • max_sequence_length (int, format: int32, 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, format: uuid, optional) — Optional owner principal UUID. If omitted, defaults to the authenticated principal. CREATE_EMBEDDER is evaluated against the proposed embedder and owner.
  • provider_type (ProviderType, optional) — Provider backend — one of "OPENAI", "VLLM", "TEI", "LLAMA_CPP", "VOYAGE", "COHERE", "JINA", "DASHSCOPE", or "GEMINI". Use "GEMINI" for the native Gemini embedding provider and select its API surface with gemini_endpoint_config. Auto-inferred from model_identifier for known catalog 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

Returns:

EmbedderResponse — Returns the embedder configuration.

Raises:

  • ConflictError — The resource already exists or conflicts with existing state.
  • APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

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

embedders.get(*, id: str, include_credentials: bool = None) → EmbedderResponse

Retrieves the details of a specific embedder configuration by its unique identifier. Requires READ_EMBEDDER on the requested embedder. The service distinguishes a missing embedder from an existing embedder the caller cannot read. This is a read-only operation with no side effects.

Parameters:

  • id (str) — The unique identifier of the embedder to retrieve
  • include_credentials (bool, optional, server default=False) — Whether to return stored credentials. Also accepts include_credentials. Requires READ_EMBEDDER_CREDENTIALS in addition to READ_EMBEDDER.

Returns:

EmbedderResponse — Returns the embedder configuration.

Raises:

  • PermissionDeniedError — The caller lacks the permission the operation requires.
  • APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

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

List embedders

embedders.list(*, label: dict[str, str] = None, owner_id: str = None, provider_type: ProviderType = None) → list[EmbedderResponse]

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

AUTHORIZATION: Requires LIST_EMBEDDER on the GoodMem instance. Each returned embedder must also be visible through READ_EMBEDDER; unauthorized embedders are filtered in PostgreSQL. The owner_id parameter filters that already-authorized result set and does not grant additional visibility. This is a read-only operation with no side effects.

Parameters:

  • 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 the already-authorized result set by owner principal UUID. Omitting this parameter does not bypass per-embedder READ_EMBEDDER filtering.
  • provider_type (ProviderType, optional) — Filter embedders by provider type. Allowed values match the ProviderType schema.

Returns:

list[EmbedderResponse]

Raises:

  • PermissionDeniedError — The caller lacks the permission the operation requires.
  • APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

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

Update an embedder

embedders.update(*, id: str, request: UpdateEmbedderRequest | dict) → EmbedderResponse

Updates explicitly supplied embedder fields; at least one mutable field is required. Field omission and reset semantics are defined by the request schema, and provider_type cannot be changed. Returns 409 if the resulting configuration duplicates another embedder for the owner, and 412 when model-defining fields are changed while the embedder is in use. Requires UPDATE_EMBEDDER on the requested embedder. See the embedder provider guide for provider-specific configuration.

Parameters:

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

Returns:

EmbedderResponse — Returns the embedder configuration.

Raises:

  • PermissionDeniedError — The caller lacks the permission the operation requires.
  • APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

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

embedders.delete(*, id: str) → None

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 on the requested embedder.

Parameters:

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

Returns:

None

Raises:

  • PermissionDeniedError — The caller lacks the permission the operation requires.
  • APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

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"

GeminiEndpointConfig

Gemini backend routing. DEVELOPER does not use project_id or location; GOOGLE_CLOUD requires project_id and defaults an omitted location to global.

  • backend (GeminiApiBackend | None) — Google API surface. UNSPECIFIED is invalid when this configuration is supplied on a write.
  • project_id (str, optional) — Google Cloud resource project. Required for GOOGLE_CLOUD and unused for DEVELOPER; this is distinct from the ADC quota project.
  • location (str, optional) — Google Cloud location. Valid only for GOOGLE_CLOUD; omission defaults to global.

GeminiApiBackend

String enum: "UNSPECIFIED" · "DEVELOPER" · "GOOGLE_CLOUD"

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 | None) — Type of embedding provider
  • endpoint_url (str) — Canonical base HTTP(S) endpoint used for provider requests.
  • api_path (str, optional) — Configured provider-relative request path. For Gemini, this is the selected API version: /v1beta for Developer or /v1 for Google Cloud.
  • model_identifier (str) — Model identifier
  • dimensionality (int) — Output vector dimensions
  • distribution_type (DistributionType | None) — 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) — Stored credentials; present only when GetEmbedder explicitly requests them and the caller has READ_EMBEDDER_CREDENTIALS. Always omitted from create, update, and list responses.
  • 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
  • dashscope_api_dialect (DashScopeApiDialect, optional) — Configured DashScope request and response API dialect; present only for DashScope configurations with a persisted dialect.
  • gemini_endpoint_config (GeminiEndpointConfig, optional) — Persisted Gemini backend routing; present only for Gemini embedder resources.

UpdateEmbedderRequest

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

  • display_name (str, optional) — User-facing name of the embedder
  • description (str, optional) — Description of the embedder
  • endpoint_url (str, optional) — Replacement base HTTP(S) endpoint. Omit to preserve the stored value. Gemini endpoint URLs must not contain query parameters.
  • api_path (str, optional) — Replacement provider-relative request path. Omit to preserve the stored value, except that changing the Gemini backend without api_path selects that backend's default; send blank to restore the provider default. For Gemini, this is an API version: /v1beta for Developer and /v1 for Google Cloud.
  • 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
  • credentials (EndpointAuthentication, optional) — Replace stored credentials. Omit this field to preserve the current credentials; a present empty payload is invalid and never clears them.
  • 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
  • dashscope_api_dialect (DashScopeApiDialect, optional) — Update the DashScope request and response API dialect. Valid only for the DASHSCOPE provider. Omit to preserve the stored dialect. Changing api_path to a recognized canonical DashScope dialect infers its matching dialect; a custom path preserves an existing dialect, while a legacy null dialect is inferred.
  • gemini_endpoint_config (GeminiEndpointConfig, optional) — When present, atomically replaces the complete Gemini backend routing configuration. Valid only for a GEMINI embedder. Omit to preserve the stored configuration; the gRPC service validates the backend-specific project_id and location contract.

Python SDK

Install and configure the GoodMem Python SDK. Reference synchronous and asynchronous clients, resource methods, errors, and shared data models.

Rerankers

Python SDK reference for reranker configurations: creation, lookup, listing, updates, and deletion.

On this page

Create a new embedderGet an embedder by IDList embeddersUpdate an embedderDelete an embedderData ModelsDistributionTypeGeminiEndpointConfigGeminiApiBackendEmbedderResponseUpdateEmbedderRequest