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.

Permissions are enforced based on ownership and granted roles:

• *_OWN permissions allow operations on rerankers owned by the authenticated user
• *_ANY permissions allow operations on rerankers owned by any user (admin-level)

CreateReranker

Summary: Creates a new neural reranking service configuration.

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: CREATE_RERANKER_OWN or CREATE_RERANKER_ANY

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 by stripping trailing slash
• api_path (OPTIONAL): API path component; defaults to "/rerank" if empty
• 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): If provided, requires CREATE_RERANKER_ANY permission

Response:

• Returns the created Reranker with all fields populated
• credentials field is omitted from response for security

Side Effects:

• Creates new reranker record in database
• Sets owner_id to authenticated user or specified value (if permitted)
• Sets created_by_id to authenticated user
• Performs duplicate detection based on {endpoint_url, api_path, model_identifier}

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

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication
• PERMISSION_DENIED: User lacks CREATE_RERANKER_OWN or CREATE_RERANKER_ANY permission
• INVALID_ARGUMENT: Required fields empty/missing; invalid URLs; label constraints violated; provider_type unspecified
• ALREADY_EXISTS: Duplicate reranker exists with same {owner_id, provider_type, endpoint_url, api_path, model_identifier, credentials_fingerprint} after URL canonicalization; credentials_fingerprint is SHA-256 hash of normalized credentials
• INTERNAL: Unexpected server error

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer <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 authorization: Bearer <api-key>

Permissions Required: READ_RERANKER_OWN or READ_RERANKER_ANY

Side Effects: None (read-only operation)

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication
• PERMISSION_DENIED: User lacks READ_RERANKER_OWN for own resources or READ_RERANKER_ANY for others
• 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 'authorization: Bearer <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 user.

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: LIST_RERANKER_OWN or LIST_RERANKER_ANY

Request Parameters:

• owner_id (optional, bytes UUID): Filter by owner; requires LIST_RERANKER_ANY if not authenticated user
• 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 user
• credentials fields omitted from all responses for security
• Results ordered by created_at descending

Side Effects: None (read-only operation)

Error Codes:

• UNAUTHENTICATED: Missing or invalid authentication
• PERMISSION_DENIED: User lacks LIST_RERANKER_OWN or specified owner_id without LIST_RERANKER_ANY
• 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 'authorization: Bearer <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 authorization: Bearer <api-key>

Permissions Required: UPDATE_RERANKER_OWN or UPDATE_RERANKER_ANY

Summary:

• Only mutable fields can be updated: display_name, description, endpoint_url, api_path, model_identifier, supported_modalities, credentials, version, monitoring_endpoint, labels
• provider_type and owner_id are immutable
• Label updates support replace (clear all, set new) or merge (upsert) strategies

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: User lacks UPDATE_RERANKER_OWN for own resources or UPDATE_RERANKER_ANY for others
• 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: Update would create duplicate with same {endpoint_url, api_path, model_identifier}
• INTERNAL: Unexpected server error

Idempotency: Idempotent with identical input; safe to retry.

Examples:

grpcurl -plaintext \
-H 'authorization: Bearer <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 authorization: Bearer <api-key>

Permissions Required: DELETE_RERANKER_OWN or DELETE_RERANKER_ANY

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: User lacks DELETE_RERANKER_OWN for own resources or DELETE_RERANKER_ANY for others
• 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 'authorization: Bearer <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 is INPUT_ONLY and is omitted from all responses.

Immutability:

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

Duplicate detection:

• Uniqueness is enforced per-owner by the combination of {owner_id, provider_type, endpoint_url, api_path, model_identifier, credentials_fingerprint} after URL canonicalization (trailing slash stripped, case-insensitive host comparison).
• Credentials are hashed (SHA-256) for uniqueness checking while remaining encrypted for storage.

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 (credentials omitted for security).

UpdateRerankerRequest

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

DeleteRerankerRequest

Request for permanently deleting a reranker configuration.