# 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()"

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

from __future__ import annotations

from typing import Any

from goodmem._api_base.embedders import EmbeddersAPIBase, AsyncEmbeddersAPIBase


# --- Convenience imports ---
from goodmem._transforms import apply_convenience_transforms
from goodmem.models.distribution_type import DistributionType
from goodmem.models.embedder_response import EmbedderResponse
from goodmem.models.endpoint_authentication import EndpointAuthentication
from goodmem.models.modality import Modality
from goodmem.models.provider_type import ProviderType


class EmbeddersAPI(EmbeddersAPIBase):
    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, dimensionality: int | None = None, distribution_type: DistributionType | None = "DENSE", embedder_id: str | None = None, endpoint_url: str | None = None, labels: dict[str, str] | None = None, max_sequence_length: int | None = None, monitoring_endpoint: str | None = None, owner_id: str | None = None, provider_type: ProviderType | None = None, supported_modalities: list[Modality] | None = None, version: str | None = None) -> EmbedderResponse:
        """Create a new embedder

        Creates a new embedder configuration for vectorizing content. Embedders represent connections to different embedding API services (like OpenAI, vLLM, etc.) and include all the necessary configuration to use them with memory spaces. DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if another embedder exists with identical {owner_id, provider_type, endpoint_url, api_path, model_identifier, dimensionality, distribution_type, 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. The api_path field defaults to '/v2/embed' for Cohere, '/embed' for TEI, and '/embeddings' for other providers when omitted. Requires CREATE_EMBEDDER_OWN permission (or CREATE_EMBEDDER_ANY for admin users).

        Args:
            display_name (str): User-facing name of the embedder
            model_identifier (str): The string that identifies the embedder. Usually the model identifier assigned by HuggingFace or the LLM provider, e.g., `"text-embedding-3-small"` by OpenAI. When a known model, auto-fills `provider_type`, `endpoint_url`, `dimensionality`, `max_sequence_length`, and `supported_modalities` for 29 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-..."}}`). Most SaaS/cloud and/or proprietary providers (e.g., OpenAI, Cohere, Jina, Voyage, OpenRouter, Gemini) require an API key.
            api_path (str, optional): API path for embeddings request (defaults: Cohere /v2/embed, TEI /embed, others /embeddings)
            credentials (EndpointAuthentication, optional): Structured credential payload describing how to authenticate with the provider.
            description (str, optional): Description of the embedder
            dimensionality (int, optional): Output vector dimensions. Auto-inferred from `model_identifier` for known models (using `dimensions.default` from the model registry); required when `model_identifier` is not in the model registry.
            distribution_type (DistributionType, optional, SDK default='"DENSE"'): The distribution type of the embedder's vector output. Defaults to `"DENSE"` when not specified.
            embedder_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.
            endpoint_url (str, optional): Base URL for the embedding endpoint. Auto-inferred from `provider_type` for known providers.
            labels (dict[str, str], optional): User-defined labels for categorization
            max_sequence_length (int, optional): Maximum token length accepted by the model. Auto-inferred from `model_identifier` for known models; required when `model_identifier` is not in the registry.
            monitoring_endpoint (str, optional): Monitoring endpoint URL
            owner_id (str, optional): Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_EMBEDDER_ANY permission if specified.
            provider_type (ProviderType, optional): Provider backend — one of `"OPENAI"`, `"COHERE"`, `"VOYAGE"`, `"JINA"`, `"VLLM"`, `"TEI"`, `"LLAMA_CPP"`. Use `"OPENAI"` for OpenAI-compatible endpoints such as Anthropic, Google Gemini, or Mistral. Auto-inferred from `model_identifier` for known models.
            supported_modalities (list[Modality], optional, server default="['TEXT']"): Modalities supported by this embedder (e.g. `["TEXT"]`). Auto-inferred from `model_identifier` for known models; required when `model_identifier` is not in the registry.
            version (str, optional): Version information

        Returns:
            EmbedderResponse
        """
        _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 dimensionality is not None: _kw["dimensionality"] = dimensionality
        if distribution_type is not None: _kw["distribution_type"] = distribution_type
        if embedder_id is not None: _kw["embedder_id"] = embedder_id
        if endpoint_url is not None: _kw["endpoint_url"] = endpoint_url
        if labels is not None: _kw["labels"] = labels
        if max_sequence_length is not None: _kw["max_sequence_length"] = max_sequence_length
        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 supported_modalities is not None: _kw["supported_modalities"] = supported_modalities
        if version is not None: _kw["version"] = version
        apply_convenience_transforms(("embedders", "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[EmbedderResponse]:
        """List embedders

        Retrieves a list of embedder configurations accessible to the caller, with optional filtering. 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_EMBEDDER_OWN permission, you can only see your own embedders (owner_id filter is ignored if set to another user). With LIST_EMBEDDER_ANY permission, you can see all embedders or filter by any owner_id. This is a read-only operation with no side effects.

        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 embedders by owner ID. With LIST_EMBEDDER_ANY permission, omitting this shows all accessible embedders; providing it filters by that owner. With LIST_EMBEDDER_OWN permission, only your own embedders are shown regardless of this parameter.
            provider_type (ProviderType, optional): Filter embedders by provider type. Allowed values match the ProviderType schema.

        Returns:
            list[EmbedderResponse]
        """
        _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 AsyncEmbeddersAPI(AsyncEmbeddersAPIBase):
    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, dimensionality: int | None = None, distribution_type: DistributionType | None = "DENSE", embedder_id: str | None = None, endpoint_url: str | None = None, labels: dict[str, str] | None = None, max_sequence_length: int | None = None, monitoring_endpoint: str | None = None, owner_id: str | None = None, provider_type: ProviderType | None = None, supported_modalities: list[Modality] | None = None, version: str | None = None) -> EmbedderResponse:
        """Create a new embedder

        Creates a new embedder configuration for vectorizing content. Embedders represent connections to different embedding API services (like OpenAI, vLLM, etc.) and include all the necessary configuration to use them with memory spaces. DUPLICATE DETECTION: Returns HTTP 409 Conflict (ALREADY_EXISTS) if another embedder exists with identical {owner_id, provider_type, endpoint_url, api_path, model_identifier, dimensionality, distribution_type, 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. The api_path field defaults to '/v2/embed' for Cohere, '/embed' for TEI, and '/embeddings' for other providers when omitted. Requires CREATE_EMBEDDER_OWN permission (or CREATE_EMBEDDER_ANY for admin users).

        Args:
            display_name (str): User-facing name of the embedder
            model_identifier (str): The string that identifies the embedder. Usually the model identifier assigned by HuggingFace or the LLM provider, e.g., `"text-embedding-3-small"` by OpenAI. When a known model, auto-fills `provider_type`, `endpoint_url`, `dimensionality`, `max_sequence_length`, and `supported_modalities` for 29 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-..."}}`). Most SaaS/cloud and/or proprietary providers (e.g., OpenAI, Cohere, Jina, Voyage, OpenRouter, Gemini) require an API key.
            api_path (str, optional): API path for embeddings request (defaults: Cohere /v2/embed, TEI /embed, others /embeddings)
            credentials (EndpointAuthentication, optional): Structured credential payload describing how to authenticate with the provider.
            description (str, optional): Description of the embedder
            dimensionality (int, optional): Output vector dimensions. Auto-inferred from `model_identifier` for known models (using `dimensions.default` from the model registry); required when `model_identifier` is not in the model registry.
            distribution_type (DistributionType, optional, SDK default='"DENSE"'): The distribution type of the embedder's vector output. Defaults to `"DENSE"` when not specified.
            embedder_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.
            endpoint_url (str, optional): Base URL for the embedding endpoint. Auto-inferred from `provider_type` for known providers.
            labels (dict[str, str], optional): User-defined labels for categorization
            max_sequence_length (int, optional): Maximum token length accepted by the model. Auto-inferred from `model_identifier` for known models; required when `model_identifier` is not in the registry.
            monitoring_endpoint (str, optional): Monitoring endpoint URL
            owner_id (str, optional): Optional owner ID. If not provided, derived from the authentication context. Requires CREATE_EMBEDDER_ANY permission if specified.
            provider_type (ProviderType, optional): Provider backend — one of `"OPENAI"`, `"COHERE"`, `"VOYAGE"`, `"JINA"`, `"VLLM"`, `"TEI"`, `"LLAMA_CPP"`. Use `"OPENAI"` for OpenAI-compatible endpoints such as Anthropic, Google Gemini, or Mistral. Auto-inferred from `model_identifier` for known models.
            supported_modalities (list[Modality], optional, server default="['TEXT']"): Modalities supported by this embedder (e.g. `["TEXT"]`). Auto-inferred from `model_identifier` for known models; required when `model_identifier` is not in the registry.
            version (str, optional): Version information

        Returns:
            EmbedderResponse
        """
        _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 dimensionality is not None: _kw["dimensionality"] = dimensionality
        if distribution_type is not None: _kw["distribution_type"] = distribution_type
        if embedder_id is not None: _kw["embedder_id"] = embedder_id
        if endpoint_url is not None: _kw["endpoint_url"] = endpoint_url
        if labels is not None: _kw["labels"] = labels
        if max_sequence_length is not None: _kw["max_sequence_length"] = max_sequence_length
        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 supported_modalities is not None: _kw["supported_modalities"] = supported_modalities
        if version is not None: _kw["version"] = version
        apply_convenience_transforms(("embedders", "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[EmbedderResponse]:
        """List embedders

        Retrieves a list of embedder configurations accessible to the caller, with optional filtering. 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_EMBEDDER_OWN permission, you can only see your own embedders (owner_id filter is ignored if set to another user). With LIST_EMBEDDER_ANY permission, you can see all embedders or filter by any owner_id. This is a read-only operation with no side effects.

        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 embedders by owner ID. With LIST_EMBEDDER_ANY permission, omitting this shows all accessible embedders; providing it filters by that owner. With LIST_EMBEDDER_OWN permission, only your own embedders are shown regardless of this parameter.
            provider_type (ProviderType, optional): Filter embedders by provider type. Allowed values match the ProviderType schema.

        Returns:
            list[EmbedderResponse]
        """
        _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)

