# DO NOT EDIT — generated by _client_gen/convenience_emitter.py from convenience.json.
# Regenerate with: cd clients/v2 && python -c "from _client_gen.convenience_emitter import generate_convenience; generate_convenience()"

"""Rerankers API namespace — generated from convenience.json."""

from __future__ import annotations

from typing import Any

from goodmem._api_base.rerankers import RerankersAPIBase, AsyncRerankersAPIBase


# --- Convenience imports ---
from goodmem._transforms import apply_convenience_transforms
from goodmem.models.endpoint_authentication import EndpointAuthentication
from goodmem.models.modality import Modality
from goodmem.models.provider_type import ProviderType
from goodmem.models.reranker_response import RerankerResponse


class RerankersAPI(RerankersAPIBase):
    def create(self, *, display_name: str, model_identifier: str, api_key: str | None = None, api_path: str | None = None, credentials: EndpointAuthentication | None = None, description: str | None = None, endpoint_url: str | None = None, labels: dict[str, str] | None = None, monitoring_endpoint: str | None = None, owner_id: str | None = None, provider_type: ProviderType | None = None, reranker_id: str | None = None, supported_modalities: list[Modality] | None = None, version: str | None = None) -> RerankerResponse:
        """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.

        Args:
            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` for 16 registered models.
            api_key (str, optional): Converts a plain API key string to the full `EndpointAuthentication` structure (i.e. `{"kind": "CREDENTIAL_KIND_API_KEY", "api_key": {"inline_secret": "sk-..."}}`).
            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.
            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

        Returns:
            RerankerResponse
        """
        _kw: dict[str, Any] = {"display_name": display_name, "model_identifier": model_identifier}
        if api_key is not None: _kw["api_key"] = api_key
        if api_path is not None: _kw["api_path"] = api_path
        if credentials is not None: _kw["credentials"] = credentials
        if description is not None: _kw["description"] = description
        if endpoint_url is not None: _kw["endpoint_url"] = endpoint_url
        if labels is not None: _kw["labels"] = labels
        if monitoring_endpoint is not None: _kw["monitoring_endpoint"] = monitoring_endpoint
        if owner_id is not None: _kw["owner_id"] = owner_id
        if provider_type is not None: _kw["provider_type"] = provider_type
        if reranker_id is not None: _kw["reranker_id"] = reranker_id
        if supported_modalities is not None: _kw["supported_modalities"] = supported_modalities
        if version is not None: _kw["version"] = version
        apply_convenience_transforms(("rerankers", "create"), _kw)
        return super().create(**_kw)

    def list(self, *, label: dict[str, str] | None = None, owner_id: str | None = None, provider_type: ProviderType | None = None) -> list[RerankerResponse]:
        """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.

        Args:
            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.

        Returns:
            list[RerankerResponse]
        """
        _kw: dict[str, Any] = {}
        if label is not None: _kw["label"] = label
        if owner_id is not None: _kw["owner_id"] = owner_id
        if provider_type is not None: _kw["provider_type"] = provider_type
        return super().list(**_kw)



class AsyncRerankersAPI(AsyncRerankersAPIBase):
    async def create(self, *, display_name: str, model_identifier: str, api_key: str | None = None, api_path: str | None = None, credentials: EndpointAuthentication | None = None, description: str | None = None, endpoint_url: str | None = None, labels: dict[str, str] | None = None, monitoring_endpoint: str | None = None, owner_id: str | None = None, provider_type: ProviderType | None = None, reranker_id: str | None = None, supported_modalities: list[Modality] | None = None, version: str | None = None) -> RerankerResponse:
        """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.

        Args:
            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` for 16 registered models.
            api_key (str, optional): Converts a plain API key string to the full `EndpointAuthentication` structure (i.e. `{"kind": "CREDENTIAL_KIND_API_KEY", "api_key": {"inline_secret": "sk-..."}}`).
            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.
            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

        Returns:
            RerankerResponse
        """
        _kw: dict[str, Any] = {"display_name": display_name, "model_identifier": model_identifier}
        if api_key is not None: _kw["api_key"] = api_key
        if api_path is not None: _kw["api_path"] = api_path
        if credentials is not None: _kw["credentials"] = credentials
        if description is not None: _kw["description"] = description
        if endpoint_url is not None: _kw["endpoint_url"] = endpoint_url
        if labels is not None: _kw["labels"] = labels
        if monitoring_endpoint is not None: _kw["monitoring_endpoint"] = monitoring_endpoint
        if owner_id is not None: _kw["owner_id"] = owner_id
        if provider_type is not None: _kw["provider_type"] = provider_type
        if reranker_id is not None: _kw["reranker_id"] = reranker_id
        if supported_modalities is not None: _kw["supported_modalities"] = supported_modalities
        if version is not None: _kw["version"] = version
        apply_convenience_transforms(("rerankers", "create"), _kw)
        return await super().create(**_kw)

    async def list(self, *, label: dict[str, str] | None = None, owner_id: str | None = None, provider_type: ProviderType | None = None) -> list[RerankerResponse]:
        """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.

        Args:
            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.

        Returns:
            list[RerankerResponse]
        """
        _kw: dict[str, Any] = {}
        if label is not None: _kw["label"] = label
        if owner_id is not None: _kw["owner_id"] = owner_id
        if provider_type is not None: _kw["provider_type"] = provider_type
        return await super().list(**_kw)

