Reranker

Services

RerankerService Service

Service for managing Rerankers in the GoodMem system.

Authentication: All methods require valid API key authentication via gRPC metadata:

• Metadata key: authorization
• Value format: Bearer <api-key>

Global errors: All RPCs may return DEADLINE_EXCEEDED, CANCELLED, UNAVAILABLE, RESOURCE_EXHAUSTED, INTERNAL.

Authorization model:

• Every RPC evaluates a typed authorization operation against the GoodMem instance or a particular reranker.
• Ownership, code-defined role assignments, and direct grants can supply authority; an API-key ceiling may further restrict the authenticated principal's effective authority.
• Listing requires LIST_RERANKER on the instance and returns only rerankers on which the caller has READ_RERANKER.

CreateReranker

Summary: Creates a new neural reranking service configuration.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: CREATE_RERANKER on the proposed reranker, evaluated using its proposed owner.

Request Parameters:

• display_name (REQUIRED): User-facing name; ≤255 chars after trimming
• description (OPTIONAL): Descriptive text
• provider_type (REQUIRED): Service provider type; becomes IMMUTABLE after creation
• endpoint_url (REQUIRED): HTTP(S) URL; server canonicalizes (trim, lowercase scheme/host, remove default ports, strip trailing '/' from path; preserve query)
• api_path (OPTIONAL): API path component; if empty, defaults to "/v2/rerank" (Cohere), otherwise "/rerank"
• model_identifier (REQUIRED): Model name/ID; non-empty after trimming
• supported_modalities (OPTIONAL): Defaults to [TEXT] if omitted
• credentials (OPTIONAL): Structured credentials; required only for SaaS providers that enforce authentication
• labels (OPTIONAL): ≤20 entries; keys/values ≤255 chars; keys [a-z0-9._-]
• version (OPTIONAL): Version information
• monitoring_endpoint (OPTIONAL): HTTP(S) URL for health/metrics
• owner_id (OPTIONAL): Proposed owner principal; defaults to the authenticated principal

Response:

• Returns the created Reranker with all fields populated
• credentials is omitted from the response; use GetReranker with include_credentials=true when the stored secret is required

Side Effects:

• Creates new reranker record in database
• Sets owner_id to the authenticated principal or specified value after authorization
• Sets created_by_id from the authenticated actor
• Performs duplicate detection using the effective provider connection, model configuration, and equivalent credentials after endpoint canonicalization and provider-default resolution

Idempotency: Not idempotent - each call creates a new reranker. Clients SHOULD NOT auto-retry blindly.

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication
• PERMISSION_DENIED: Caller lacks CREATE_RERANKER on the proposed reranker
• INVALID_ARGUMENT: Required fields empty/missing; invalid URLs; label constraints violated; provider_type unspecified
• ALREADY_EXISTS: Another reranker for the same owner has the same effective provider connection and model configuration after endpoint canonicalization and provider-default resolution; equivalent credentials participate in this comparison
• INTERNAL: Unexpected server error

Examples:

grpcurl -plaintext \
-H 'x-api-key: <api-key>' \
-d '{
"display_name": "Cohere Rerank v3",
"provider_type": "COHERE",
"endpoint_url": "https://api.cohere.ai",
"model_identifier": "rerank-english-v3.0",
"credentials": "your-cohere-api-key"
}' \
localhost:8080 goodmem.v1.RerankerService/CreateReranker

Note: bytes fields in JSON must be base64.

GetReranker

Retrieves details of a specific reranker configuration.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: READ_RERANKER on the requested reranker. When include_credentials is true, the caller must also hold READ_RERANKER_CREDENTIALS; only the current owner or an instance administrator can supply that authority.

Side Effects: None (read-only operation)

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication
• PERMISSION_DENIED: Caller lacks READ_RERANKER, or requests credentials without READ_RERANKER_CREDENTIALS
• INVALID_ARGUMENT: Invalid reranker_id format (not 16-byte UUID)
• NOT_FOUND: Reranker with specified ID does not exist
• INTERNAL: Unexpected server error

Idempotency: Read-only; safe to retry; results may differ as state changes.

Examples:

grpcurl -plaintext \
-H 'x-api-key: <api-key>' \
-d '{"reranker_id": "base64-encoded-uuid-bytes"}' \
localhost:8080 goodmem.v1.RerankerService/GetReranker

Note: bytes fields in JSON must be base64.

ListRerankers

Lists reranker configurations accessible to the authenticated principal.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: LIST_RERANKER on the GoodMem instance and READ_RERANKER on each returned reranker. The standard user role may enumerate the catalog and read owned rerankers; direct grants can expose additional rerankers.

Request Parameters:

• owner_id (optional, bytes UUID): Filter the already-authorized result set by owner
• provider_type (optional): Filter by provider type; PROVIDER_TYPE_UNSPECIFIED ignored
• label_selectors (optional): AND of exact key=value matches (case-sensitive)

Response:

• Returns list of Reranker records accessible to the principal
• credentials fields are always omitted from list responses
• Results ordered by created_at descending

Side Effects: None (read-only operation)

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication
• PERMISSION_DENIED: Caller lacks instance-level LIST_RERANKER
• INVALID_ARGUMENT: Invalid owner_id format (not 16-byte UUID)
• INTERNAL: Unexpected server error

Idempotency: Read-only; safe to retry; results may change over time.

Examples:

grpcurl -plaintext \
-H 'x-api-key: <api-key>' \
-d '{"provider_type": "COHERE"}' \
localhost:8080 goodmem.v1.RerankerService/ListRerankers

Note: bytes fields in JSON must be base64.

UpdateReranker

Updates mutable properties of a reranker configuration.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: UPDATE_RERANKER on the requested reranker.

Summary:

• Only mutable fields can be updated: display_name, description, endpoint_url, api_path, model_identifier, supported_modalities, credentials, version, monitoring_endpoint, labels
• For supported_modalities, a non-empty list replaces the stored set; omission or an empty list leaves it unchanged and does not count as an update by itself
• provider_type and owner_id are immutable
• Label updates support replace (clear all, set new) or merge (upsert) strategies
• Omitting credentials preserves the stored value; a present empty payload is invalid
• The response always omits stored credentials

Side Effects:

• Persists changes; updates updated_at and updated_by_id
• Performs duplicate detection if endpoint_url, api_path, or model_identifier changed

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication
• PERMISSION_DENIED: Caller lacks UPDATE_RERANKER on the requested reranker
• INVALID_ARGUMENT: Invalid reranker_id format; both label strategies set; provider_type specified; empty required fields
• NOT_FOUND: Reranker with specified ID does not exist
• ALREADY_EXISTS: The resulting effective provider connection and model configuration would duplicate another reranker for the same owner
• INTERNAL: Unexpected server error

Idempotency: Idempotent with identical input; safe to retry.

Examples:

grpcurl -plaintext \
-H 'x-api-key: <api-key>' \
-d '{
"reranker_id": "base64-encoded-uuid-bytes",
"display_name": "Updated Reranker Name",
"merge_labels": {"labels": {"environment": "production"}}
}' \
localhost:8080 goodmem.v1.RerankerService/UpdateReranker

Note: bytes fields in JSON must be base64.

DeleteReranker

Permanently deletes a reranker configuration.

Auth: gRPC metadata x-api-key: <api-key>

Authorization Required: DELETE_RERANKER on the requested reranker.

Side Effects:

• Permanently removes reranker record from database
• Invalidates any cached references to this reranker
• Does not affect historical usage data or audit logs

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication
• PERMISSION_DENIED: Caller lacks DELETE_RERANKER on the requested reranker
• INVALID_ARGUMENT: Invalid reranker_id format (not 16-byte UUID)
• NOT_FOUND: Reranker with specified ID does not exist or was already deleted
• INTERNAL: Unexpected server error

Idempotency: Safe to retry; may return NOT_FOUND if already deleted or never existed.

Examples:

grpcurl -plaintext \
-H 'x-api-key: <api-key>' \
-d '{"reranker_id": "base64-encoded-uuid-bytes"}' \
localhost:8080 goodmem.v1.RerankerService/DeleteReranker

Note: bytes fields in JSON must be base64.

Messages

Reranker

Represents a connection to a neural reranking service for post-processing search results.

Rerankers improve search relevance by re-scoring and re-ordering initial retrieval results using sophisticated neural networks or large language models. This includes cross-encoder neural networks, LLM-based reranking services, and other AI-powered relevance models. Algorithmic rerankers (like MMR) are built into the platform and don't require configuration.

Security:

• credentials are returned only by GetReranker when explicitly requested and separately authorized. Create, update, and list responses omit them.

Immutability:

• provider_type is IMMUTABLE after creation.
• owner_id is set at creation and cannot be modified.

Duplicate detection:

• Uniqueness is enforced per-owner after endpoint canonicalization and provider-default resolution. The effective provider connection, model configuration, and equivalent credentials participate in the comparison.

Notes:

• All timestamps are UTC (google.protobuf.Timestamp).

See also: goodmem.v1.ProviderType, goodmem.v1.Modality

Reranker.LabelsEntry

CreateRerankerRequest

Structured request for creating a reranker configuration.

CreateRerankerRequest.LabelsEntry

GetRerankerRequest

Request for retrieving a specific reranker by ID.

ListRerankersRequest

Request for listing rerankers with optional filtering.

ListRerankersRequest.LabelSelectorsEntry

ListRerankersResponse

Response containing rerankers accessible to the caller.

UpdateRerankerRequest

Structured request for updating mutable reranker fields. Omit properties to keep existing values.

DeleteRerankerRequest

Request for permanently deleting a reranker configuration.