Rerankers

Methods on this page are called as client.rerankers.<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 reranker

Creates a new reranker configuration for ranking search results. Rerankers represent connections to different reranking API services (like TEI, OpenAI, etc.) and include all the necessary configuration to use them for result ranking.

DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if another reranker exists with identical {owner_id, provider_type, endpoint_url, api_path, model_identifier, 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.

DEFAULTS: api_path defaults to '/v2/rerank' for Cohere and '/rerank' for other providers if omitted; supported_modalities defaults to [TEXT] if omitted. Requires CREATE_RERANKER_OWN permission (or CREATE_RERANKER_ANY for admin users). This operation is NOT idempotent - each request creates a new reranker record.

• display_name (str) — User-facing name of the reranker
• model_identifier (str) — When a known model, auto-fills provider_type, endpoint_url, 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-..."}}). At most one of api_key and credentials may be provided.
• api_path (str, optional) — API path for reranking request (defaults: Cohere /v2/rerank, Jina /v1/rerank, others /rerank).
• 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 reranker
• endpoint_url (str, optional) — Base URL for the reranking endpoint. Auto-inferred from provider_type for known providers; required when model_identifier is not in the registry.
• labels (dict[str, str], optional) — User-defined labels for categorization
• monitoring_endpoint (str, optional) — Monitoring endpoint URL
• owner_id (str, optional) — Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_RERANKER_ANY permission if specified.
• provider_type (ProviderType, optional) — Provider backend (e.g. "COHERE", "JINA"). Auto-inferred from model_identifier for known models; required when model_identifier is not in the registry.
• reranker_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.
• supported_modalities (list[Modality], optional, server default="['TEXT']") — Modalities supported by this reranker (e.g. ["TEXT"]). Auto-inferred from model_identifier for known models; defaults to ["TEXT"] on the server if omitted.
• version (str, optional) — Version information

reranker = client.rerankers.create(
    display_name="Doc Reranker",
    model_identifier="rerank-2",
    api_key="voyage-key-...",
    labels={"env": "docs"},
)

Get a reranker by ID

Retrieves the details of a specific reranker configuration by its unique identifier. Response payloads include stored credentials, matching gRPC response semantics. Requires READ_RERANKER_OWN permission for rerankers you own (or READ_RERANKER_ANY for admin users). This is a read-only operation with no side effects and is safe to retry.

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

reranker = client.rerankers.get(id="your-reranker-id")
print(reranker.display_name)

List rerankers

Retrieves a list of reranker configurations accessible to the caller, with optional filtering.

IMPORTANT: Pagination is NOT supported - all matching results are returned. Results are ordered by created_at descending. Responses include stored credentials, matching gRPC response semantics.

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_RERANKER_OWN permission, only your own rerankers are shown. With LIST_RERANKER_ANY permission, you can see all rerankers or filter by any owner_id. Specifying owner_id without LIST_RERANKER_ANY permission returns PERMISSION_DENIED.

• 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 rerankers by owner ID. With LIST_RERANKER_ANY permission, omitting this shows all accessible rerankers; providing it filters by that owner. With LIST_RERANKER_OWN permission, only your own rerankers are shown regardless of this parameter (PERMISSION_DENIED if set to another user).
• provider_type (ProviderType, optional) — Filter rerankers by provider type. Allowed values match the ProviderType schema.

for rr in client.rerankers.list():
    print(rr.reranker_id, rr.display_name)

Update a reranker

Updates an existing reranker configuration including display information, endpoint configuration, model parameters, credentials, and labels. All fields are optional - only specified fields will be updated.

IMMUTABLE FIELDS: provider_type and owner_id cannot be changed after creation. SUPPORTED_MODALITIES UPDATE: If the array contains ≥1 elements, it replaces the stored set; if empty or omitted, no change occurs. Returns ALREADY_EXISTS if update would create duplicate with same {owner_id, provider_type, endpoint_url, api_path, model_identifier, credentials_fingerprint} after URL canonicalization (HTTP 409 Conflict / ALREADY_EXISTS). Requires UPDATE_RERANKER_OWN permission for rerankers you own (or UPDATE_RERANKER_ANY for admin users). This operation is idempotent.

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

from goodmem.types import UpdateRerankerRequest
# Option 1: typed request object
updated = client.rerankers.update(id="your-reranker-id", request=UpdateRerankerRequest(
    display_name="Doc Reranker (updated)",
    merge_labels={"version": "2"},
))
assert updated.reranker_id == "your-reranker-id"
# Option 2: plain dict (validated via pydantic)
updated = client.rerankers.update(id="your-reranker-id", request={
    "display_name": "Doc Reranker (updated)",
    "merge_labels": {"version": "2"},
})
assert updated.reranker_id == "your-reranker-id"

Delete a reranker

Permanently deletes a reranker configuration. This operation cannot be undone and immediately removes the reranker record from the database.

SIDE EFFECTS: Invalidates any cached references to this reranker; does not affect historical usage data or audit logs. Requires DELETE_RERANKER_OWN permission for rerankers you own (or DELETE_RERANKER_ANY for admin users). This operation is safe to retry - may return NOT_FOUND if already deleted.

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

client.rerankers.delete(id="your-reranker-id")

Async usage: client.rerankers 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).

RerankerResponse

Reranker configuration information

• reranker_id (str) — Unique identifier of the reranker
• display_name (str) — User-facing name of the reranker
• description (str, optional) — Description of the reranker
• provider_type (ProviderType) — Type of reranking provider
• endpoint_url (str) — API endpoint URL
• api_path (str, optional) — API path for reranking request
• model_identifier (str) — Model identifier
• 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 reranker
• 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 reranker
• updated_by_id (str) — ID of the user who last updated the reranker

ListRerankersResponse

Response containing a list of rerankers

• rerankers (list[RerankerResponse]) — List of reranker configurations

UpdateRerankerRequest

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

• display_name (str, optional) — User-facing name of the reranker
• description (str, optional) — Description of the reranker
• endpoint_url (str, optional) — API endpoint URL
• api_path (str, optional) — API path for reranking request
• model_identifier (str, optional) — Model identifier
• supported_modalities (list[Modality], optional) — Supported content modalities
• credentials (EndpointAuthentication, optional) — Structured credential payload describing how to authenticate with the provider. Omit to keep existing credentials.
• 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