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

rerankers.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, endpoint_url: str = None, labels: dict[str, str] = None, monitoring_endpoint: str = None, owner_id: str = None, provider_type: ProviderType = None, reranker_id: str = None, supported_modalities: list[Modality] = None, version: str = None) → RerankerResponse

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 the same effective provider connection and model configuration for this owner after endpoint canonicalization and provider-default resolution. Equivalent credentials participate in the comparison.

DEFAULTS: api_path defaults to '/v2/rerank' for Cohere and '/rerank' for other providers if omitted; supported_modalities defaults to [TEXT] if omitted.

OWNER DEFAULTS: Owner defaults to the authenticated principal unless owner_id is provided; CREATE_RERANKER is evaluated against the proposed reranker and owner. This operation is NOT idempotent - each request creates a new reranker record.

Parameters:

• 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. 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 reranking default.
• 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, format: uuid, optional) — Optional owner principal UUID. If omitted, defaults to the authenticated principal. CREATE_RERANKER is evaluated against the proposed reranker and owner.
• 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, 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.
• 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

Returns:

RerankerResponse — Returns the reranker 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

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

Get a reranker by ID

rerankers.get(*, id: str, include_credentials: bool = None) → RerankerResponse

Retrieves the details of a specific reranker configuration by its unique identifier. Stored credentials are omitted unless include_credentials is true and the caller also has READ_RERANKER_CREDENTIALS. Requires READ_RERANKER on the requested reranker. The service distinguishes a missing reranker from an existing reranker the caller cannot read. This is a read-only operation with no side effects and is safe to retry.

Parameters:

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

Returns:

RerankerResponse — Returns the reranker 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

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

List rerankers

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

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. Stored credentials are never included in list responses.

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_RERANKER on the GoodMem instance. Each returned reranker must also be visible through READ_RERANKER; unauthorized rerankers are filtered in PostgreSQL. The owner_id parameter filters that already-authorized result set and does not grant additional visibility.

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-reranker READ_RERANKER filtering.
• provider_type (ProviderType, optional) — Filter rerankers by provider type. Allowed values match the ProviderType schema.

Returns:

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 rr in client.rerankers.list():
    print(rr.reranker_id, rr.display_name)

Update a reranker

rerankers.update(*, id: str, request: UpdateRerankerRequest | dict) → RerankerResponse

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 and it does not count as an update by itself. Returns ALREADY_EXISTS if update would create an equivalent reranker configuration for this owner after endpoint canonicalization and provider-default resolution (HTTP 409 Conflict / ALREADY_EXISTS). Requires UPDATE_RERANKER on the requested reranker. This operation is idempotent.

Parameters:

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

Returns:

RerankerResponse — Returns the reranker configuration.

Raises:

• PermissionDeniedError — The caller lacks the permission the operation requires.
• 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

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

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

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 on the requested reranker. This operation is safe to retry - may return NOT_FOUND if already deleted.

Parameters:

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

Returns:

Raises:

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

Example

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 | None) — 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) — Stored credentials; present only when GetReranker explicitly requests them and the caller has READ_RERANKER_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 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
• dashscope_api_dialect (DashScopeApiDialect, optional) — Configured DashScope request and response API dialect; present only for DashScope configurations with a persisted dialect.

UpdateRerankerRequest

Request body for updating an existing Reranker. Only fields that should be updated need to be included. supported_modalities replaces the stored set only when the array contains at least one value; empty or omitted leaves it unchanged and does not count as an update by itself.

• 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) — Update supported modalities (if array contains >=1 elements, replaces stored set; if empty or omitted, no change and does not count as an update by itself)
• 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.