docforge-sdk 0.28.0__tar.gz → 0.30.0__tar.gz

{docforge_sdk-0.28.0 → docforge_sdk-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docforge-sdk
-Version: 0.28.0
+Version: 0.30.0
 Summary: Typed async + sync Python client for the DocForge REST API (standalone, zero server deps).
 Project-URL: Homepage, https://github.com/Florian-BARRE/docforge
 Project-URL: Repository, https://github.com/Florian-BARRE/docforge

{docforge_sdk-0.28.0 → docforge_sdk-0.30.0}/docforge_sdk/__init__.py

@@ -24,6 +24,7 @@ from .models._shared import (
     FieldScope,
     FieldType,
     KeyPermissions,
+    KeyProfile,
     SourceKind,
 )
 
@@ -39,6 +40,13 @@ from .models.blobs import BlobContent
 # ------------------- Capabilities models ------------------- #
 from .models.capabilities import CapabilitiesResponse, CapabilityMatrix, ServiceInfo
 
+# ------------------- Collection alias models ------------------- #
+from .models.collection_aliases import (
+    CollectionAliasModel,
+    SetCollectionAliasRequest,
+    SetCollectionAliasResponse,
+)
+
 # ------------------- Collections models ------------------- #
 from .models.collections import (
     BulkReingestAccepted,
@@ -189,6 +197,7 @@ __all__ = [
     # Shared vocabulary
     "Capability",
     "KeyPermissions",
+    "KeyProfile",
     "FieldType",
     "FieldOrigin",
     "FieldScope",
@@ -206,6 +215,10 @@ __all__ = [
     "KeyInfo",
     # Health
     "HealthStatus",
+    # Collection aliases
+    "CollectionAliasModel",
+    "SetCollectionAliasRequest",
+    "SetCollectionAliasResponse",
     # Collections
     "FieldSpec",
     "CollectionModel",

{docforge_sdk-0.28.0 → docforge_sdk-0.30.0}/docforge_sdk/_version.py

@@ -2,4 +2,4 @@
 # Single source of truth for the package version. Hatchling reads ``__version__`` from this file to
 # populate the distribution metadata (see ``[tool.hatch.version]`` in pyproject.toml).
 
-__version__ = "0.28.0"
+__version__ = "0.30.0"

{docforge_sdk-0.28.0 → docforge_sdk-0.30.0}/docforge_sdk/client.py

@@ -13,7 +13,9 @@ from .resources.audit import AsyncAudit, SyncAudit
 from .resources.auth import AsyncAuth, SyncAuth
 from .resources.blobs import AsyncBlobs, SyncBlobs
 from .resources.capabilities import AsyncCapabilities, SyncCapabilities
+from .resources.collection_aliases import AsyncCollectionAliases, SyncCollectionAliases
 from .resources.collections import AsyncCollections, SyncCollections
+from .resources.config_versions import AsyncConfigVersions, SyncConfigVersions
 from .resources.corpus import AsyncCorpus, SyncCorpus
 from .resources.documents import AsyncDocuments, SyncDocuments
 from .resources.explorer import AsyncExplorer, SyncExplorer
@@ -42,6 +44,8 @@ class AsyncClient:
         pipelines (AsyncPipelines): Pipeline discovery + design.
         transfers (AsyncTransfers): Collection export/import.
         snippets (AsyncSnippets): Granular collection-config snippet export/apply.
+        config_versions (AsyncConfigVersions): Collection config history (list/get/diff/restore).
+        collection_aliases (AsyncCollectionAliases): Stable collection names (list/set/delete).
         audit (AsyncAudit): Root-only audit-trail reads.
         corpus (AsyncCorpus): Server-side document grid — query + bulk delete/enable/reingest.
     """
@@ -69,6 +73,8 @@ class AsyncClient:
         self.pipelines = AsyncPipelines(self._transport)
         self.transfers = AsyncTransfers(self._transport)
         self.snippets = AsyncSnippets(self._transport)
+        self.config_versions = AsyncConfigVersions(self._transport)
+        self.collection_aliases = AsyncCollectionAliases(self._transport)
         self.corpus = AsyncCorpus(self._transport)
 
     async def __aenter__(self) -> "AsyncClient":
@@ -106,6 +112,8 @@ class Client:
         pipelines (SyncPipelines): Pipeline discovery + design.
         transfers (SyncTransfers): Collection export/import.
         snippets (SyncSnippets): Granular collection-config snippet export/apply.
+        config_versions (SyncConfigVersions): Collection config history (list/get/diff/restore).
+        collection_aliases (SyncCollectionAliases): Stable collection names (list/set/delete).
         audit (SyncAudit): Root-only audit-trail reads.
         corpus (SyncCorpus): Server-side document grid — query + bulk delete/enable/reingest.
     """
@@ -133,6 +141,8 @@ class Client:
         self.pipelines = SyncPipelines(self._transport)
         self.transfers = SyncTransfers(self._transport)
         self.snippets = SyncSnippets(self._transport)
+        self.config_versions = SyncConfigVersions(self._transport)
+        self.collection_aliases = SyncCollectionAliases(self._transport)
         self.corpus = SyncCorpus(self._transport)
 
     def __enter__(self) -> "Client":

{docforge_sdk-0.28.0 → docforge_sdk-0.30.0}/docforge_sdk/models/__init__.py

@@ -8,6 +8,7 @@ from ._shared import (
     FieldScope,
     FieldType,
     KeyPermissions,
+    KeyProfile,
     SourceKind,
 )
 
@@ -23,6 +24,13 @@ from .blobs import BlobContent
 # ------------------- Capabilities models ------------------- #
 from .capabilities import CapabilitiesResponse, CapabilityMatrix, ServiceInfo
 
+# ------------------- Collection alias models ------------------- #
+from .collection_aliases import (
+    CollectionAliasModel,
+    SetCollectionAliasRequest,
+    SetCollectionAliasResponse,
+)
+
 # ------------------- Collections models ------------------- #
 from .collections import (
     BulkReingestAccepted,
@@ -40,6 +48,16 @@ from .collections import (
     UpdateCollectionResponse,
 )
 
+# ------------------- Config history models ------------------- #
+from .config_versions import (
+    ConfigDiffEntry,
+    ConfigVersionDetail,
+    ConfigVersionDiffResponse,
+    ConfigVersionListResponse,
+    ConfigVersionRestoreResponse,
+    ConfigVersionSummary,
+)
+
 # ------------------- Corpus filter + grid models ------------------- #
 from .corpus import (
     BulkDeleteResponse,
@@ -225,6 +243,7 @@ __all__ = [
     # Shared vocabulary
     "Capability",
     "KeyPermissions",
+    "KeyProfile",
     "FieldType",
     "FieldOrigin",
     "FieldScope",
@@ -277,6 +296,16 @@ __all__ = [
     "MetadataValuesPatch",
     "MetadataUpdateResponse",
     "DocumentView",
+    # Config history
+    "ConfigDiffEntry",
+    "CollectionAliasModel",
+    "SetCollectionAliasRequest",
+    "SetCollectionAliasResponse",
+    "ConfigVersionDetail",
+    "ConfigVersionDiffResponse",
+    "ConfigVersionListResponse",
+    "ConfigVersionRestoreResponse",
+    "ConfigVersionSummary",
     # Snippets
     "SNIPPET_FILE_EXTENSION",
     "SnippetKind",

{docforge_sdk-0.28.0 → docforge_sdk-0.30.0}/docforge_sdk/models/_shared.py

@@ -12,15 +12,31 @@ from pydantic import BaseModel, Field
 
 
 class Capability(StrEnum):
-    """A coarse action class an endpoint requires of the calling key."""
+    """
+    A coarse action class an endpoint requires of the calling key.
+
+    ``READ`` is the legacy pre-split alias: the server normalizes it to ``READ_TEXT`` +
+    ``READ_TECHNICAL`` and never returns it.
+    """
 
     READ = "read"
+    READ_TEXT = "read_text"
+    READ_TECHNICAL = "read_technical"
     WRITE = "write"
     SEARCH = "search"
     CREATE = "create"
     ADMIN = "admin"
 
 
+class KeyProfile(StrEnum):
+    """A named capability preset offered at key creation."""
+
+    AGENT_READER = "agent_reader"
+    AGENT_SEARCHER = "agent_searcher"
+    OPERATOR = "operator"
+    ADMIN = "admin"
+
+
 class FieldType(StrEnum):
     """Data type of a metadata field — drives validation and storage."""
 
@@ -99,18 +115,29 @@ class KeyPermissions(BaseModel):
             that can authenticate but is authorized for nothing).
         collections (list[str]): Either ``["*"]`` (every collection) or an explicit list of
             collection UUID strings the key is scoped to.
+        profile (KeyProfile | None): A named preset — give it INSTEAD of ``capabilities`` and the
+            server expands it to the preset's explicit list (stored for display).
     """
 
     capabilities: list[Capability] = Field(
-        description="The action classes this key grants (READ / WRITE / SEARCH / ADMIN)."
+        default_factory=list,
+        description="The action classes this key grants (read_text / read_technical / write / "
+        "search / create / admin; the legacy 'read' = read_text + read_technical). May be omitted "
+        "when 'profile' is given.",
     )
     collections: list[str] = Field(
         description="Collection scope: ['*'] for all, else explicit collection UUID strings."
     )
+    profile: KeyProfile | None = Field(
+        default=None,
+        description="Named capability preset (agent_reader / agent_searcher / operator / admin). "
+        "Given instead of 'capabilities', it expands to the preset; stored for display only.",
+    )
 
 
 __all__ = [
     "Capability",
+    "KeyProfile",
     "FieldType",
     "FieldOrigin",
     "FieldScope",

{docforge_sdk-0.28.0 → docforge_sdk-0.30.0}/docforge_sdk/models/auth.py

@@ -11,7 +11,7 @@ from typing import Any
 from pydantic import BaseModel, Field
 
 # ====== Local Project Imports ======
-from ._shared import KeyPermissions
+from ._shared import KeyPermissions, KeyProfile
 
 
 class CreateKeyRequest(BaseModel):
@@ -28,7 +28,8 @@ class CreateKeyRequest(BaseModel):
     name: str = Field(min_length=1, description="Human-readable label for the key.")
     permissions: KeyPermissions | None = Field(
         default=None,
-        description="Per-key capability + collection scope; null = full access (root).",
+        description="Per-key capability + collection scope; null = full access (root). Give "
+        "'profile' instead of 'capabilities' to apply a named preset.",
     )
     expires_at: datetime | None = Field(
         default=None,
@@ -128,16 +129,22 @@ class KeyInfo(BaseModel):
 
 
 class WhoAmI(BaseModel):
-    """The calling token's own access — capabilities + collection scope, for self-introspection."""
+    """The calling token's own access — capabilities, collection scope and usage profile."""
 
     authenticated: bool = Field(description="Always true for a resolved principal.")
     root: bool = Field(description="Full, unscoped access (auth off, or a NULL-permissions key).")
     capabilities: list[str] = Field(
-        description="Action classes this token grants (read / write / search / create / admin)."
+        description="Action classes this token grants (read_text / read_technical / write / search "
+        "/ create / admin)."
     )
     collections: list[str] = Field(
         description="Collection scope: ['*'] for all, else explicit collection UUID strings."
     )
+    profile: KeyProfile | None = Field(
+        default=None,
+        description="Named preset matching the capabilities (agent_reader / agent_searcher / "
+        "operator / admin); null for root or a custom capability set.",
+    )
 
 
 __all__ = ["CreateKeyRequest", "RotateKeyRequest", "CreatedKey", "KeyInfo", "WhoAmI"]

docforge_sdk-0.30.0/docforge_sdk/models/collection_aliases.py

@@ -0,0 +1,43 @@
+# ====== Code Summary ======
+# Models of the collection-alias surface, mirrored field-for-field from the DocForge backend
+# (app/backend/routers/collection_aliases/models.py): an alias and its current target, the PUT body
+# (the target collection), and the PUT outcome (the alias now + where it pointed before). A collection
+# alias is a stable deployment-level name for one collection, usable wherever a collection id is taken.
+
+# ====== Standard Library Imports ======
+from datetime import datetime
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CollectionAliasModel(BaseModel):
+    """One collection alias and the collection it currently targets."""
+
+    name: str = Field(description="The alias name (a slug: lowercase, digits, '-', '_').")
+    collection_id: str = Field(description="The UUID of the collection it points at.")
+    collection_name: str = Field(description="The name of the collection it points at.")
+    created_at: datetime = Field(description="When the alias was created.")
+    updated_at: datetime = Field(description="When the alias was last (re-)pointed.")
+
+
+class SetCollectionAliasRequest(BaseModel):
+    """The body of PUT /collection-aliases/{name}: the collection the alias must point at."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    collection_id: str = Field(description="The UUID of the target collection.")
+
+
+class SetCollectionAliasResponse(CollectionAliasModel):
+    """The alias after a create / re-point, plus where it pointed before."""
+
+    previous_collection_id: str | None = Field(
+        default=None,
+        description="The collection the alias pointed at before this call (null = it was created; "
+        "equal to collection_id = a no-op re-point).",
+    )
+    created: bool = Field(description="True when this call created the alias.")
+
+
+__all__ = ["CollectionAliasModel", "SetCollectionAliasRequest", "SetCollectionAliasResponse"]

{docforge_sdk-0.28.0 → docforge_sdk-0.30.0}/docforge_sdk/models/collections.py

@@ -33,6 +33,7 @@ class CollectionModel(BaseModel):
         needs_reindex (bool): True when a config change requires reindexing.
         missing_vectors (list[str] | None): Named vectors the schema's semantic/lexical fields need
             but the vector store does not declare (an index rebuild is required); None on list rows.
+        aliases (list[str] | None): The collection aliases targeting it (single read only).
         created_at (datetime | None): Creation timestamp.
         title_field (str | None): Document-scope field used as the display title (None = parsed).
         pipeline (dict[str, Any]): The ingestion pipeline blob (the graph).
@@ -76,15 +77,25 @@ class CollectionModel(BaseModel):
         "on the single-collection read and the PATCH response ([] = aligned or never ingested); "
         "null on the fleet list, which never reads the vector store.",
     )
+    aliases: list[str] | None = Field(
+        default=None,
+        description="The collection aliases pointing at this collection (each usable in place of the "
+        "UUID in every collection route and as an 'alias:<name>' key scope). Computed on the "
+        "single-collection read (GET /collections/{id}); null on the other payloads.",
+    )
     created_at: datetime | None = Field(default=None, description="Creation timestamp.")
     title_field: str | None = Field(
         default=None,
         description="Document-scope field whose value is each document's display title (None = the "
         "parser-derived title).",
     )
-    pipeline: dict[str, Any] = Field(description="The ingestion pipeline blob (the graph).")
-    search: dict[str, Any] = Field(
-        description="The search pipeline graph blob ({} = use the stock default)."
+    pipeline: dict[str, Any] | None = Field(
+        description="The ingestion pipeline blob (the graph); null when the calling key lacks the "
+        "read_technical capability (withheld, not refused)."
+    )
+    search: dict[str, Any] | None = Field(
+        description="The search pipeline graph blob ({} = use the stock default); null when the "
+        "calling key lacks the read_technical capability (withheld, not refused)."
     )
     fields: list[FieldSpec] = Field(default_factory=list, description="The metadata schema.")
     estimate_overrides: EstimateOverrides | None = Field(
@@ -281,6 +292,8 @@ class BulkReingestRequest(BaseModel):
             in the collection. An empty list is rejected by the API (an ambiguous no-op).
         force (bool): Bypass the stage cache and recompute every stage from scratch (no cache
             read/write). Use to rebuild after a code change that did not bump a node's CACHE_VERSION.
+        replay_from (str | None): Replay from this post-IR stage (no re-parse); None = full re-run.
+        confirm_estimate (bool): Acknowledge the estimate of a reingest above the confirm threshold.
     """
 
     document_ids: list[str] | None = Field(
@@ -292,6 +305,18 @@ class BulkReingestRequest(BaseModel):
         description="Bypass the stage cache and recompute every stage from scratch (no cache "
         "read/write). Use to rebuild after a code change that did not bump a node's CACHE_VERSION.",
     )
+    replay_from: str | None = Field(
+        default=None,
+        description="Replay only this post-IR stage and its downstream from each document's PERSISTED "
+        "IR (no re-parse): one of enrich, chunk, metagen_chunk, metagen_document, embed — as the "
+        "collection's pipeline allows (422 lists the allowed stages). Omit for a full re-run.",
+    )
+    confirm_estimate: bool = Field(
+        default=False,
+        description="Acknowledge the cost estimate of a LARGE reingest (above the server's confirm "
+        "threshold). Without it such a call is refused 409 estimate_required carrying the estimate "
+        "summary; review it and resend with true.",
+    )
 
 
 class BulkReingestAccepted(BaseModel):
@@ -324,6 +349,10 @@ class BulkReingestAccepted(BaseModel):
         default=0,
         description="Documents skipped because an ingestion job was already active for them.",
     )
+    skipped_not_replayable: int = Field(
+        default=0,
+        description="Documents skipped by a replay_from run because they have no persisted IR.",
+    )
     jobs: list[ReingestJobHandle] = Field(description="One handle per enqueued run.")
 
 

docforge_sdk-0.30.0/docforge_sdk/models/config_versions.py

@@ -0,0 +1,83 @@
+# ====== Code Summary ======
+# Response models of the versioned collection config history, mirrored field-for-field from the
+# DocForge backend (app/backend/routers/config_history/models.py): the paginated version list (author +
+# change summary), one masked snapshot, the structured masked diff, and a restore outcome.
+
+# ====== Standard Library Imports ======
+from datetime import datetime
+from typing import Any, Literal
+
+# ====== Third-Party Library Imports ======
+from pydantic import BaseModel, Field
+
+
+class ConfigVersionSummary(BaseModel):
+    """One entry of a collection's config history (no config body)."""
+
+    version: int = Field(description="Per-collection version number (1 = creation).")
+    created_at: datetime = Field(description="When this version was written.")
+    note: str | None = Field(default=None, description="The note stored with the version.")
+    author_label: str | None = Field(
+        default=None,
+        description='Who wrote it: "<key name> (<key prefix>)" (the root token reads "root (df_…)"), '
+        'or "anonymous" (auth off); null = '
+        "unknown (written before authorship was recorded, or a system write such as an import).",
+    )
+    author_key_id: str | None = Field(
+        default=None, description="The authoring API key id (null once that key is deleted)."
+    )
+    changes: list[str] = Field(
+        default_factory=list,
+        description='What changed vs the previous version: "pipeline:<node id>", "pipeline:(graph)" '
+        '(transitions/bindings), "search". Empty for version 1 or a no-op write.',
+    )
+
+
+class ConfigVersionListResponse(BaseModel):
+    """One newest-first page of a collection's config history."""
+
+    collection_id: str
+    total: int = Field(description="Number of versions in the whole history.")
+    limit: int
+    offset: int
+    items: list[ConfigVersionSummary]
+
+
+class ConfigVersionDetail(ConfigVersionSummary):
+    """One config version with its {pipeline, search} snapshot — every provider secret masked."""
+
+    config: dict[str, Any] = Field(
+        description="The snapshot {pipeline, search}; secrets replaced by the mask marker."
+    )
+
+
+class ConfigDiffEntry(BaseModel):
+    """One changed path between two versions (values masked)."""
+
+    path: str = Field(
+        description="JSON-pointer style path; graph nodes are keyed by id, e.g. "
+        '"/pipeline/nodes/parse/config/max_pages".',
+    )
+    op: Literal["added", "removed", "changed"]
+    before: Any = Field(default=None, description="The masked value in `from` (absent → null).")
+    after: Any = Field(default=None, description="The masked value in `to` (absent → null).")
+
+
+class ConfigVersionDiffResponse(BaseModel):
+    """The structured diff from one config version to another (secrets always masked)."""
+
+    collection_id: str
+    from_version: int
+    to_version: int
+    changes: list[ConfigDiffEntry]
+
+
+class ConfigVersionRestoreResponse(BaseModel):
+    """The outcome of restoring a config version (always a NEW version, never a history rewrite)."""
+
+    collection_id: str
+    restored_from: int = Field(description="The version whose config was re-applied.")
+    version: int = Field(description='The new version written (note "restore of v{N}").')
+    needs_reindex: bool = Field(
+        description="The collection's derived reindex flag after the restore."
+    )

{docforge_sdk-0.28.0 → docforge_sdk-0.30.0}/docforge_sdk/models/corpus.py

@@ -208,6 +208,10 @@ class BulkReingestResponse(BaseModel):
         default=0,
         description="Documents skipped because an ingestion job was already active for them.",
     )
+    skipped_not_replayable: int = Field(
+        default=0,
+        description="Documents skipped by a replay_from run because they have no persisted IR.",
+    )
     jobs: list[ReingestJobHandle] = Field(description="One handle per enqueued run.")
 
 

{docforge_sdk-0.28.0 → docforge_sdk-0.30.0}/docforge_sdk/models/jobs.py

@@ -30,6 +30,7 @@ class JobStatus(BaseModel):
         collection_name (str | None): The collection's name, joined at read (None if the
             collection is gone).
         status (str): queued / running / done / failed / cancelled.
+        replay_from (str | None): The stage an ingest job replays from (None = a full run).
         cancel_requested (bool): A cooperative stop has been requested; the running job stops at
             its next stage boundary (still 'running' until it does).
         progress (int): 0–100 (completed pipeline nodes over total).
@@ -83,6 +84,11 @@ class JobStatus(BaseModel):
         "'rebuild_index' (a collection-level vector-store rebuild — document_id is null). "
         "Lets a client render a side-job distinctly from a full ingestion."
     )
+    replay_from: str | None = Field(
+        default=None,
+        description="The stage an ingest job replays from on the persisted IR (no re-parse); null "
+        "for a full run.",
+    )
     cancel_requested: bool = Field(
         default=False,
         description="A cooperative stop has been requested; the running job stops at its next "

{docforge_sdk-0.28.0 → docforge_sdk-0.30.0}/docforge_sdk/resources/__init__.py

@@ -13,6 +13,9 @@ from .blobs import AsyncBlobs, SyncBlobs
 # ------------------- Capabilities resource ------------------- #
 from .capabilities import AsyncCapabilities, SyncCapabilities
 
+# ------------------- Collection aliases resource ------------------- #
+from .collection_aliases import AsyncCollectionAliases, SyncCollectionAliases
+
 # ------------------- Collections resource ------------------- #
 from .collections import AsyncCollections, SyncCollections
 
@@ -47,6 +50,8 @@ __all__ = [
     "SyncAuth",
     "AsyncHealth",
     "SyncHealth",
+    "AsyncCollectionAliases",
+    "SyncCollectionAliases",
     "AsyncCollections",
     "SyncCollections",
     "AsyncDocuments",

docforge_sdk-0.30.0/docforge_sdk/resources/collection_aliases.py

@@ -0,0 +1,91 @@
+# ====== Code Summary ======
+# The collection-alias resource — list the aliases (name → current target), create or atomically
+# re-point one (the "switch": every key scoped `alias:<name>` and every client addressing the alias
+# follow it on the next request), and delete one. URL logic lives once in the pure
+# _CollectionAliasesSpecs mixin so the async/sync shells differ ONLY by ``await``.
+
+# ====== Local Project Imports ======
+from .._requestspec import RequestSpec
+from ..models.collection_aliases import (
+    CollectionAliasModel,
+    SetCollectionAliasRequest,
+    SetCollectionAliasResponse,
+)
+from ._base import AsyncResource, SyncResource, _ResourceMixin
+
+
+class _CollectionAliasesSpecs(_ResourceMixin):
+    """Pure ``RequestSpec`` builders for the collection-alias endpoints."""
+
+    _BASE = "/collection-aliases"
+
+    def _list_spec(self) -> RequestSpec:
+        """A GET of every alias the caller may see."""
+        return RequestSpec("GET", self._BASE)
+
+    def _set_spec(self, name: str, collection_id: str) -> RequestSpec:
+        """A PUT creating / re-pointing ``name`` to ``collection_id``."""
+        body = SetCollectionAliasRequest(collection_id=collection_id)
+        return RequestSpec("PUT", f"{self._BASE}/{name}", json=body.model_dump(mode="json"))
+
+    def _delete_spec(self, name: str) -> RequestSpec:
+        """A DELETE of one alias."""
+        return RequestSpec("DELETE", f"{self._BASE}/{name}")
+
+
+class AsyncCollectionAliases(AsyncResource, _CollectionAliasesSpecs):
+    """Asynchronous collection aliases."""
+
+    async def list(self) -> list[CollectionAliasModel]:
+        """
+        List the collection aliases whose target the caller may see, by name.
+
+        Returns:
+            list[CollectionAliasModel]: Each alias with its current target (id + name).
+        """
+        return await self._transport.request(self._list_spec(), list[CollectionAliasModel])
+
+    async def set(self, name: str, collection_id: str) -> SetCollectionAliasResponse:
+        """
+        Create the alias, or atomically re-point it to another collection (the "switch").
+
+        Args:
+            name (str): The alias slug (lowercase letters, digits, '-', '_').
+            collection_id (str): The UUID of the collection the alias must target.
+
+        Returns:
+            SetCollectionAliasResponse: The alias now + its previous target (None = created).
+        """
+        return await self._transport.request(
+            self._set_spec(name, collection_id), SetCollectionAliasResponse
+        )
+
+    async def delete(self, name: str) -> None:
+        """
+        Delete a collection alias (keys scoped ``alias:<name>`` then grant nothing through it).
+
+        Args:
+            name (str): The alias name.
+        """
+        await self._transport.request(self._delete_spec(name), type(None))
+
+
+class SyncCollectionAliases(SyncResource, _CollectionAliasesSpecs):
+    """Synchronous collection aliases."""
+
+    def list(self) -> list[CollectionAliasModel]:
+        """List the collection aliases (see the async twin)."""
+        return self._transport.request(self._list_spec(), list[CollectionAliasModel])
+
+    def set(self, name: str, collection_id: str) -> SetCollectionAliasResponse:
+        """Create or atomically re-point an alias (see the async twin)."""
+        return self._transport.request(
+            self._set_spec(name, collection_id), SetCollectionAliasResponse
+        )
+
+    def delete(self, name: str) -> None:
+        """Delete a collection alias (see the async twin)."""
+        self._transport.request(self._delete_spec(name), type(None))
+
+
+__all__ = ["AsyncCollectionAliases", "SyncCollectionAliases"]