Rerankers

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

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

Reranker management — re-scoring of retrieval hits.

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

Index

type RerankersService
type RerankerCreationRequest
type RerankerResponse
type ListRerankersResponse
type UpdateRerankerRequest

type RerankersService

type RerankersService struct{ … }

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

func (s *RerankersService) Create

func (s *RerankersService) Create(ctx context.Context, req *models.RerankerCreationRequest, apiKey string) (*models.RerankerResponse, error)

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: apiPath defaults to '/v2/rerank' for Cohere and '/rerank' for other providers if omitted; supportedModalities defaults to [TEXT] if omitted.

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

HTTP — POST /v1/rerankers

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.RerankerCreationRequest) — 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.RerankerResponse, error)

Example

reranker, err := client.Rerankers().Create(ctx, &models.RerankerCreationRequest{
	DisplayName:     "Doc Reranker",
	ModelIdentifier: "rerank-2",
	Labels:          map[string]string{"env": "docs"},
}, "voyage-key-...")
if err != nil {
	log.Fatal(err)
}
_ = reranker

func (s *RerankersService) Get

func (s *RerankersService) Get(ctx context.Context, id string, params *RerankersGetParams) (*models.RerankerResponse, error)

Retrieves the details of a specific reranker configuration by its unique identifier. Stored credentials are omitted unless includeCredentials 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.

HTTP — GET /v1/rerankers/{id}

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — The unique identifier of the reranker to retrieve
params (*RerankersGetParams, optional) — typed query parameters; pass nil for an empty filter set.

Returns — (*models.RerankerResponse, error)

Example

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

func (s *RerankersService) List

func (s *RerankersService) List(ctx context.Context, params *RerankersListParams) (*models.ListRerankersResponse, error)

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 ownerId parameter filters that already-authorized result set and does not grant additional visibility.

HTTP — GET /v1/rerankers

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
params (*RerankersListParams, optional) — typed query parameters; pass nil for an empty filter set.

Returns — (*models.ListRerankersResponse, error)

Example

resp, err := client.Rerankers().List(ctx, nil)
if err != nil {
	log.Fatal(err)
}
for _, rr := range resp.Rerankers {
	_ = rr.RerankerID
	_ = rr.DisplayName
}

func (s *RerankersService) Update

func (s *RerankersService) Update(ctx context.Context, id string, req *models.UpdateRerankerRequest) (*models.RerankerResponse, error)

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: providerType and ownerId 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.

HTTP — PUT /v1/rerankers/{id}

Parameters

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

Returns — (*models.RerankerResponse, error)

Example

updated, err := client.Rerankers().Update(ctx, "your-reranker-id", &models.UpdateRerankerRequest{
	DisplayName: goodmem.Ptr("Doc Reranker (updated)"),
	MergeLabels: map[string]string{"version": "2"},
})
if err != nil {
	log.Fatal(err)
}
_ = updated.RerankerID

func (s *RerankersService) Delete

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

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.

HTTP — DELETE /v1/rerankers/{id}

Parameters

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

Returns — error — nil on success.

Example

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

type RerankerCreationRequest

type RerankerCreationRequest struct{ … }

Request body for creating a new Reranker. A Reranker represents a configuration for reranking search results.

DisplayName (string, wire displayName) — User-facing name of the reranker
Description (string, optional, wire description) — Description of the reranker
ProviderType (models.ProviderType, wire providerType) — Type of reranking provider
EndpointURL (string, wire endpointUrl) — API endpoint URL
APIPath (string, optional, wire apiPath) — API path for reranking request (defaults: Cohere /v2/rerank, Jina /v1/rerank, others /rerank)
ModelIdentifier (string, wire modelIdentifier) — Model identifier
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 principal UUID. If omitted, defaults to the authenticated principal. CREATE_RERANKER is evaluated against the proposed reranker and owner.
RerankerID (string, optional, wire rerankerId) — Optional client-provided UUID for idempotent creation. If not provided, server generates a new UUID. Returns ALREADY_EXISTS if ID is already in use.
DashscopeAPIDialect (models.DashScopeApiDialect, optional, wire dashscopeApiDialect) — DashScope request and response API dialect. Valid only for the DASHSCOPE provider. Omit to infer the dialect from apiPath, the model catalog, or the native reranking default.

type RerankerResponse

type RerankerResponse struct{ … }

Reranker configuration information

RerankerID (string, wire rerankerId) — Unique identifier of the reranker
DisplayName (string, wire displayName) — User-facing name of the reranker
Description (string, optional, wire description) — Description of the reranker
ProviderType (models.ProviderType, wire providerType) — Type of reranking provider
EndpointURL (string, wire endpointUrl) — API endpoint URL
APIPath (string, optional, wire apiPath) — API path for reranking request
ModelIdentifier (string, wire modelIdentifier) — Model identifier
SupportedModalities ([]models.Modality, wire supportedModalities) — Supported content modalities
Credentials (models.EndpointAuthentication, optional, wire credentials) — 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 (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 reranker
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 reranker
UpdatedByID (string, wire updatedById) — ID of the user who last updated the reranker
DashscopeAPIDialect (models.DashScopeApiDialect, optional, wire dashscopeApiDialect) — Configured DashScope request and response API dialect; present only for DashScope configurations with a persisted dialect.

type ListRerankersResponse

type ListRerankersResponse struct{ … }

Response containing a list of rerankers

Rerankers ([]models.RerankerResponse, wire rerankers) — List of reranker configurations

type UpdateRerankerRequest

type UpdateRerankerRequest struct{ … }

Request body for updating an existing Reranker. Only fields that should be updated need to be included. supportedModalities 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.

DisplayName (string, optional, wire displayName) — User-facing name of the reranker
Description (string, optional, wire description) — Description of the reranker
EndpointURL (string, optional, wire endpointUrl) — API endpoint URL
APIPath (string, optional, wire apiPath) — API path for reranking request
ModelIdentifier (string, optional, wire modelIdentifier) — Model identifier
SupportedModalities ([]models.Modality, optional, wire supportedModalities) — 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 (models.EndpointAuthentication, optional, wire credentials) — Replace stored credentials. Omit this field to preserve the current credentials; a present empty payload is invalid and never clears them.
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
DashscopeAPIDialect (models.DashScopeApiDialect, optional, wire dashscopeApiDialect) — Update the DashScope request and response API dialect. Valid only for the DASHSCOPE provider. Omit to preserve the stored dialect. Changing apiPath to a recognized canonical DashScope dialect infers its matching dialect; a custom path preserves an existing dialect, while a legacy null dialect is inferred.

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

On this page