cortexctl 0.1.0.dev20260811135705__py3-none-any.whl

cortex_cli/client.py

@@ -0,0 +1,1222 @@
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import secrets
+from collections.abc import Callable, Iterator
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urlparse
+from urllib.request import Request, urlopen
+
+DEFAULT_REQUEST_TIMEOUT_SECONDS = 30
+MULTIPART_READ_CHUNK_SIZE = 1024 * 1024
+
+
+class MultipartBody:
+    """Repeatable multipart body that streams the file from disk."""
+
+    def __init__(
+        self,
+        *,
+        prefix: bytes,
+        path: Path,
+        suffix: bytes,
+    ) -> None:
+        self.prefix = prefix
+        self.path = path
+        self.suffix = suffix
+        self.file_size = path.stat().st_size
+        self.content_length = len(prefix) + self.file_size + len(suffix)
+
+    def __iter__(self) -> Iterator[bytes]:
+        yield self.prefix
+        with self.path.open("rb") as fileobj:
+            while chunk := fileobj.read(MULTIPART_READ_CHUNK_SIZE):
+                yield chunk
+        yield self.suffix
+
+
+class CliAPIError(Exception):
+    def __init__(
+        self,
+        *,
+        code: str,
+        message: str,
+        status_code: int,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.details = details or {}
+
+
+class CortexClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        access_token: str | None = None,
+        refresh_token: str | None = None,
+        token_updater: Callable[[dict[str, Any]], None] | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.access_token = access_token
+        self.refresh_token = refresh_token
+        self.token_updater = token_updater
+
+    def debug_login(
+        self,
+        *,
+        email: str,
+        password: str | None,
+        display_name: str | None,
+    ) -> dict[str, Any]:
+        return self.post(
+            "/auth/login",
+            {
+                "email": email,
+                "password": password,
+                "display_name": display_name,
+            },
+            authenticated=False,
+        )
+
+    def feishu_cli_authorize(
+        self,
+        *,
+        cli_redirect_uri: str,
+        state: str,
+        code_challenge: str,
+    ) -> dict[str, Any]:
+        return self.post(
+            "/auth/feishu/cli/authorize",
+            {
+                "cli_redirect_uri": cli_redirect_uri,
+                "state": state,
+                "code_challenge": code_challenge,
+            },
+            authenticated=False,
+        )
+
+    def feishu_cli_token(
+        self,
+        *,
+        cli_auth_code: str,
+        code_verifier: str,
+    ) -> dict[str, Any]:
+        return self.post(
+            "/auth/feishu/cli/token",
+            {
+                "cli_auth_code": cli_auth_code,
+                "code_verifier": code_verifier,
+            },
+            authenticated=False,
+        )
+
+    def device_login_start(self) -> dict[str, Any]:
+        return self.post("/auth/device/start", {}, authenticated=False)
+
+    def device_login_token(self, *, device_code: str) -> dict[str, Any]:
+        return self.post(
+            "/auth/device/token",
+            {"device_code": device_code},
+            authenticated=False,
+        )
+
+    def me(self) -> dict[str, Any]:
+        return self.get("/me")
+
+    def health(self) -> dict[str, Any]:
+        return self.get("/health", authenticated=False)
+
+    def ready(self) -> dict[str, Any]:
+        return self.get("/ready", authenticated=False)
+
+    def workspace_panel(self) -> dict[str, Any]:
+        return self.get("/me/workspace-panel")
+
+    def create_workspace(self, *, name: str, description: str | None) -> dict[str, Any]:
+        return self.post("/workspaces", {"name": name, "description": description})
+
+    def get_workspace(self, workspace_id: str) -> dict[str, Any]:
+        return self.get(f"/workspaces/{workspace_id}")
+
+    def update_workspace(
+        self,
+        workspace_id: str,
+        *,
+        name: str | None,
+        description: str | None,
+    ) -> dict[str, Any]:
+        return self.patch(
+            f"/workspaces/{workspace_id}",
+            {"name": name, "description": description},
+        )
+
+    def delete_workspace(self, workspace_id: str) -> None:
+        self.delete(f"/workspaces/{workspace_id}")
+
+    def list_invites(
+        self,
+        workspace_id: str,
+        *,
+        page: int,
+        page_size: int,
+        query: str | None,
+        status: str | None,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/invites",
+            query=compact_query(
+                {
+                    "page": page,
+                    "page_size": page_size,
+                    "query": query,
+                    "status": status,
+                }
+            ),
+        )
+
+    def create_invite(
+        self,
+        workspace_id: str,
+        *,
+        email: str,
+        role: str,
+    ) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/invites",
+            {"invite_email": email, "role": role},
+        )
+
+    def revoke_invite(self, workspace_id: str, invite_id: str) -> None:
+        self.delete(f"/workspaces/{workspace_id}/invites/{invite_id}")
+
+    def enter_invite(self, invite_id: str) -> dict[str, Any]:
+        return self.post(f"/workspace-invites/{invite_id}/enter", {})
+
+    def reject_invite(self, invite_id: str) -> dict[str, Any]:
+        return self.post(f"/workspace-invites/{invite_id}/reject", {})
+
+    def list_invite_links(
+        self,
+        workspace_id: str,
+        *,
+        page: int,
+        page_size: int,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/invite-links",
+            query=compact_query({"page": page, "page_size": page_size}),
+        )
+
+    def create_invite_link(self, workspace_id: str, *, name: str) -> dict[str, Any]:
+        return self.post(f"/workspaces/{workspace_id}/invite-links", {"name": name})
+
+    def revoke_invite_link(self, workspace_id: str, link_id: str) -> None:
+        self.delete(f"/workspaces/{workspace_id}/invite-links/{link_id}")
+
+    def preview_invite_link(self, token_or_url: str) -> dict[str, Any]:
+        token = invite_link_token_from_value(token_or_url)
+        return self.get(f"/workspace-invite-links/{token}/preview", authenticated=False)
+
+    def enter_invite_link(self, token_or_url: str) -> dict[str, Any]:
+        token = invite_link_token_from_value(token_or_url)
+        return self.post(f"/workspace-invite-links/{token}/enter", {})
+
+    def list_members(
+        self,
+        workspace_id: str,
+        *,
+        page: int,
+        page_size: int,
+        query: str | None,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/members",
+            query=compact_query({"page": page, "page_size": page_size, "query": query}),
+        )
+
+    def update_member_role(
+        self,
+        workspace_id: str,
+        user_id: str,
+        *,
+        role: str,
+    ) -> dict[str, Any]:
+        return self.patch(
+            f"/workspaces/{workspace_id}/members/{user_id}",
+            {"role": role},
+        )
+
+    def remove_member(self, workspace_id: str, user_id: str) -> None:
+        self.delete(f"/workspaces/{workspace_id}/members/{user_id}")
+
+    def leave_workspace(self, workspace_id: str) -> None:
+        self.post(f"/workspaces/{workspace_id}/leave", {})
+
+    def transfer_owner(
+        self,
+        workspace_id: str,
+        *,
+        new_owner_id: str,
+    ) -> list[dict[str, Any]]:
+        return self.post(
+            f"/workspaces/{workspace_id}/transfer-owner",
+            {"new_owner_id": new_owner_id},
+        )
+
+    def list_knowledge_bases(
+        self,
+        workspace_id: str,
+        *,
+        page: int,
+        page_size: int,
+        query: str | None,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/knowledge-bases",
+            query=compact_query({"page": page, "page_size": page_size, "query": query}),
+        )
+
+    def create_knowledge_base(
+        self,
+        workspace_id: str,
+        *,
+        name: str,
+        description: str | None,
+        pipeline_id: str | None,
+    ) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/knowledge-bases",
+            {
+                "name": name,
+                "description": description,
+                "pipeline_id": pipeline_id,
+            },
+        )
+
+    def get_knowledge_base(self, workspace_id: str, kb_id: str) -> dict[str, Any]:
+        return self.get(f"/workspaces/{workspace_id}/knowledge-bases/{kb_id}")
+
+    def update_knowledge_base(
+        self,
+        workspace_id: str,
+        kb_id: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        return self.patch(
+            f"/workspaces/{workspace_id}/knowledge-bases/{kb_id}",
+            payload,
+        )
+
+    def delete_knowledge_base(self, workspace_id: str, kb_id: str) -> None:
+        self.delete(f"/workspaces/{workspace_id}/knowledge-bases/{kb_id}")
+
+    def update_knowledge_base_order(
+        self,
+        workspace_id: str,
+        items: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        return self.put(
+            f"/workspaces/{workspace_id}/knowledge-bases/order",
+            {"items": items},
+        )
+
+    def get_knowledge_base_permissions(
+        self,
+        workspace_id: str,
+        kb_id: str,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/knowledge-bases/{kb_id}/permissions"
+        )
+
+    def update_knowledge_base_permissions(
+        self,
+        workspace_id: str,
+        kb_id: str,
+        *,
+        edit_policy: str,
+        editor_user_ids: list[str],
+    ) -> dict[str, Any]:
+        return self.put(
+            f"/workspaces/{workspace_id}/knowledge-bases/{kb_id}/permissions",
+            {
+                "edit_policy": edit_policy,
+                "editor_user_ids": editor_user_ids,
+            },
+        )
+
+    def get_folder_tree(self, workspace_id: str, kb_id: str) -> list[dict[str, Any]]:
+        return self.get(
+            f"/workspaces/{workspace_id}/knowledge-bases/{kb_id}/folders/tree"
+        )
+
+    def create_folder(
+        self,
+        workspace_id: str,
+        kb_id: str,
+        *,
+        name: str,
+        parent_id: str | None,
+    ) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/knowledge-bases/{kb_id}/folders",
+            {"name": name, "parent_id": parent_id},
+        )
+
+    def update_folder(
+        self,
+        workspace_id: str,
+        kb_id: str,
+        folder_id: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        return self.patch(
+            f"/workspaces/{workspace_id}/knowledge-bases/{kb_id}/folders/{folder_id}",
+            payload,
+        )
+
+    def delete_folder(self, workspace_id: str, kb_id: str, folder_id: str) -> None:
+        self.delete(
+            f"/workspaces/{workspace_id}/knowledge-bases/{kb_id}/folders/{folder_id}"
+        )
+
+    def list_items(
+        self,
+        workspace_id: str,
+        *,
+        page: int,
+        page_size: int,
+        query: str | None,
+        is_available: bool | None,
+        is_locked: bool | None,
+        kb_id: str | None,
+        folder_id: str | None,
+        unclassified: bool,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/knowledge-items",
+            query=compact_query(
+                {
+                    "page": page,
+                    "page_size": page_size,
+                    "query": query,
+                    "is_available": is_available,
+                    "is_locked": is_locked,
+                    "kb_id": kb_id,
+                    "folder_id": folder_id,
+                    "unclassified": unclassified if unclassified else None,
+                }
+            ),
+        )
+
+    def create_item(
+        self,
+        workspace_id: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        return self.post(f"/workspaces/{workspace_id}/knowledge-items", payload)
+
+    def get_item(self, workspace_id: str, item_id: str) -> dict[str, Any]:
+        return self.get(f"/workspaces/{workspace_id}/knowledge-items/{item_id}")
+
+    def update_item(
+        self,
+        workspace_id: str,
+        item_id: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        return self.patch(
+            f"/workspaces/{workspace_id}/knowledge-items/{item_id}",
+            payload,
+        )
+
+    def delete_item(self, workspace_id: str, item_id: str) -> None:
+        self.delete(f"/workspaces/{workspace_id}/knowledge-items/{item_id}")
+
+    def replace_item_metadata(
+        self,
+        workspace_id: str,
+        item_id: str,
+        metadata: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        return self.put(
+            f"/workspaces/{workspace_id}/knowledge-items/{item_id}/metadata",
+            {"metadata": metadata},
+        )
+
+    def create_item_mount(
+        self,
+        workspace_id: str,
+        item_id: str,
+        *,
+        kb_id: str,
+        folder_id: str | None,
+    ) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/knowledge-items/{item_id}/mounts",
+            {"kb_id": kb_id, "folder_id": folder_id},
+        )
+
+    def delete_item_mount(
+        self,
+        workspace_id: str,
+        item_id: str,
+        *,
+        kb_id: str,
+        folder_id: str | None,
+    ) -> dict[str, Any]:
+        return self.delete_with_payload(
+            f"/workspaces/{workspace_id}/knowledge-items/{item_id}/mounts",
+            {"kb_id": kb_id, "folder_id": folder_id},
+        )
+
+    def list_trash_entries(
+        self,
+        workspace_id: str,
+        *,
+        page: int,
+        page_size: int,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/trash",
+            query=compact_query({"page": page, "page_size": page_size}),
+        )
+
+    def restore_trash_entry(
+        self,
+        workspace_id: str,
+        entry_id: str,
+        *,
+        target: dict[str, Any],
+    ) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/trash/{entry_id}/restore",
+            {"target": target},
+        )
+
+    def purge_trash_entry(self, workspace_id: str, entry_id: str) -> None:
+        self.delete(f"/workspaces/{workspace_id}/trash/{entry_id}")
+
+    def discard_trash_entry(self, workspace_id: str, entry_id: str) -> None:
+        self.purge_trash_entry(workspace_id, entry_id)
+
+    def upload_knowledge_item(
+        self,
+        workspace_id: str,
+        *,
+        path: Path,
+        title: str | None,
+        kb_id: str | None,
+        folder_id: str | None,
+        relation_type: str,
+        pipeline_id: str | None,
+        metadata: list[dict[str, Any]],
+        idempotency_key: str | None,
+    ) -> dict[str, Any]:
+        fields: dict[str, Any] = {
+            "title": title,
+            "kb_id": kb_id,
+            "folder_id": folder_id,
+            "relation_type": relation_type,
+            "pipeline_id": pipeline_id,
+            "metadata": json.dumps(metadata) if metadata else None,
+        }
+        return require_json_payload(
+            self.multipart_post(
+                f"/workspaces/{workspace_id}/uploads/knowledge-item",
+                fields=compact_query(fields),
+                file_field="file",
+                file_path=path,
+                idempotency_key=idempotency_key,
+            ),
+            operation="file.upload",
+        )
+
+    def add_file(
+        self,
+        workspace_id: str,
+        item_id: str,
+        *,
+        path: Path,
+        relation_type: str,
+        idempotency_key: str | None,
+    ) -> dict[str, Any]:
+        return require_json_payload(
+            self.multipart_post(
+                f"/workspaces/{workspace_id}/knowledge-items/{item_id}/files",
+                fields={"relation_type": relation_type},
+                file_field="file",
+                file_path=path,
+                idempotency_key=idempotency_key,
+            ),
+            operation="file.add",
+        )
+
+    def list_files(self, workspace_id: str, item_id: str) -> list[dict[str, Any]]:
+        return self.get(f"/workspaces/{workspace_id}/knowledge-items/{item_id}/files")
+
+    def download_file(self, workspace_id: str, file_id: str) -> bytes:
+        return self.request(
+            "GET",
+            f"/workspaces/{workspace_id}/files/{file_id}/download",
+            parse_json=False,
+        )
+
+    def preview_file(self, workspace_id: str, file_id: str) -> dict[str, Any]:
+        return self.get(f"/workspaces/{workspace_id}/files/{file_id}/preview")
+
+    def read_file(
+        self,
+        workspace_id: str,
+        file_id: str,
+        *,
+        format_: str,
+        range_: str | None,
+        source: str,
+        max_chars: int | None,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/files/{file_id}/read",
+            query=compact_query(
+                {
+                    "format": format_,
+                    "range": range_,
+                    "source": source,
+                    "max_chars": max_chars,
+                }
+            ),
+        )
+
+    def delete_file(self, workspace_id: str, item_id: str, file_id: str) -> None:
+        self.delete(
+            f"/workspaces/{workspace_id}/knowledge-items/{item_id}/files/{file_id}"
+        )
+
+    def list_pipelines(self, workspace_id: str) -> list[dict[str, Any]]:
+        return self.get(f"/workspaces/{workspace_id}/processing-pipelines")
+
+    def create_pipeline(
+        self,
+        workspace_id: str,
+        *,
+        name: str,
+        goal: str,
+        config: dict[str, Any],
+        is_default: bool,
+    ) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/processing-pipelines",
+            {
+                "name": name,
+                "goal": goal,
+                "config": config,
+                "is_default": is_default,
+            },
+        )
+
+    def get_pipeline(self, workspace_id: str, pipeline_id: str) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/processing-pipelines/{pipeline_id}"
+        )
+
+    def update_pipeline(
+        self,
+        workspace_id: str,
+        pipeline_id: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        return self.patch(
+            f"/workspaces/{workspace_id}/processing-pipelines/{pipeline_id}",
+            payload,
+        )
+
+    def delete_pipeline(self, workspace_id: str, pipeline_id: str) -> None:
+        self.delete(f"/workspaces/{workspace_id}/processing-pipelines/{pipeline_id}")
+
+    def trigger_processing(
+        self,
+        workspace_id: str,
+        item_id: str,
+        *,
+        pipeline_id: str | None,
+        reason: str,
+        idempotency_key: str | None,
+    ) -> dict[str, Any]:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self.request(
+            "POST",
+            f"/workspaces/{workspace_id}/knowledge-items/{item_id}/processing-runs",
+            payload={"pipeline_id": pipeline_id, "reason": reason},
+            extra_headers=headers,
+        )
+
+    def list_processing_runs(
+        self,
+        workspace_id: str,
+        item_id: str,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/knowledge-items/{item_id}/processing-runs"
+        )
+
+    def get_processing_run(self, workspace_id: str, run_id: str) -> dict[str, Any]:
+        return self.get(f"/workspaces/{workspace_id}/processing-runs/{run_id}")
+
+    def retry_processing_run(self, workspace_id: str, run_id: str) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/processing-runs/{run_id}/retry",
+            {},
+        )
+
+    def cancel_processing_run(self, workspace_id: str, run_id: str) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/processing-runs/{run_id}/cancel",
+            {},
+        )
+
+    def reconcile_processing_runs(
+        self,
+        workspace_id: str,
+        *,
+        status: list[str] | None,
+    ) -> list[dict[str, Any]]:
+        return self.post(
+            f"/workspaces/{workspace_id}/processing-runs/reconcile",
+            {"status": status},
+        )
+
+    def search_grep(
+        self,
+        workspace_id: str,
+        *,
+        query: str,
+        page: int,
+        page_size: int,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/search",
+            query=compact_query({"query": query, "page": page, "page_size": page_size}),
+        )
+
+    def search_advanced(
+        self,
+        workspace_id: str,
+        *,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        return self.post(f"/workspaces/{workspace_id}/search/advanced", payload)
+
+    def search_semantic(
+        self,
+        workspace_id: str,
+        *,
+        query: str,
+        kb_ids: list[str] | None,
+        top_k: int,
+        recall: bool = False,
+    ) -> list[dict[str, Any]]:
+        path = "recall" if recall else "search/semantic"
+        return self.post(
+            f"/workspaces/{workspace_id}/{path}",
+            {"query": query, "kb_ids": kb_ids, "top_k": top_k},
+        )
+
+    def get_chunk(
+        self,
+        workspace_id: str,
+        file_id: str,
+        chunk_idx: int,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/files/{file_id}/chunks/{chunk_idx}"
+        )
+
+    def get_chunk_context(
+        self,
+        workspace_id: str,
+        file_id: str,
+        chunk_idx: int,
+        *,
+        window: int,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/files/{file_id}/chunks/{chunk_idx}/context",
+            query=compact_query({"window": window}),
+        )
+
+    def locate_source(
+        self,
+        workspace_id: str,
+        file_id: str,
+        chunk_idx: int,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/files/{file_id}/chunks/{chunk_idx}/source"
+        )
+
+    def expand_source(
+        self,
+        workspace_id: str,
+        file_id: str,
+        chunk_idx: int,
+        *,
+        mode: str,
+        window: int,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/files/{file_id}/chunks/"
+            f"{chunk_idx}/source/expand",
+            query=compact_query({"mode": mode, "window": window}),
+        )
+
+    def read_source_page(
+        self,
+        workspace_id: str,
+        file_id: str,
+        page_index: int,
+        *,
+        include_image: bool,
+        max_width: int,
+        include_bytes: bool = False,
+    ) -> dict[str, Any]:
+        return self.get(
+            f"/workspaces/{workspace_id}/files/{file_id}/source/pages/{page_index}",
+            query=compact_query(
+                {
+                    "include_image": include_image or include_bytes,
+                    "include_bytes": include_bytes,
+                    "max_width": max_width,
+                }
+            ),
+        )
+
+    def read_region_image(
+        self,
+        workspace_id: str,
+        file_id: str,
+        *,
+        page_index: int,
+        bbox: list[float],
+        max_width: int,
+        include_bytes: bool = False,
+    ) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/files/{file_id}/source/region-image",
+            {
+                "page_index": page_index,
+                "bbox": bbox,
+                "coordinate_space": "pdf_points",
+                "max_width": max_width,
+                "include_bytes": include_bytes,
+            },
+        )
+
+    def list_mcp_interfaces(self, workspace_id: str) -> list[dict[str, Any]]:
+        return self.get(f"/workspaces/{workspace_id}/mcp-interfaces")
+
+    def create_mcp_interface(
+        self,
+        workspace_id: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        return self.post(f"/workspaces/{workspace_id}/mcp-interfaces", payload)
+
+    def get_mcp_interface(self, workspace_id: str, mcp_id: str) -> dict[str, Any]:
+        return self.get(f"/workspaces/{workspace_id}/mcp-interfaces/{mcp_id}")
+
+    def update_mcp_interface(
+        self,
+        workspace_id: str,
+        mcp_id: str,
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        return self.patch(
+            f"/workspaces/{workspace_id}/mcp-interfaces/{mcp_id}",
+            payload,
+        )
+
+    def enable_mcp_interface(self, workspace_id: str, mcp_id: str) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/mcp-interfaces/{mcp_id}/enable",
+            {},
+        )
+
+    def disable_mcp_interface(self, workspace_id: str, mcp_id: str) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/mcp-interfaces/{mcp_id}/disable",
+            {},
+        )
+
+    def delete_mcp_interface(self, workspace_id: str, mcp_id: str) -> None:
+        self.delete(f"/workspaces/{workspace_id}/mcp-interfaces/{mcp_id}")
+
+    def list_mcp_api_keys(
+        self,
+        workspace_id: str,
+        mcp_id: str,
+    ) -> list[dict[str, Any]]:
+        return self.get(f"/workspaces/{workspace_id}/mcp-interfaces/{mcp_id}/api-keys")
+
+    def create_mcp_api_key(
+        self,
+        workspace_id: str,
+        mcp_id: str,
+        *,
+        name: str | None,
+    ) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/mcp-interfaces/{mcp_id}/api-keys",
+            {"name": name},
+        )
+
+    def revoke_mcp_api_key(
+        self,
+        workspace_id: str,
+        mcp_id: str,
+        key_id: str,
+    ) -> None:
+        self.delete(
+            f"/workspaces/{workspace_id}/mcp-interfaces/{mcp_id}/api-keys/{key_id}"
+        )
+
+    def gc_workspace(
+        self,
+        workspace_id: str,
+        *,
+        dry_run: bool,
+        include_vectors: bool,
+    ) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/gc/workspace",
+            {"dry_run": dry_run, "include_vectors": include_vectors},
+        )
+
+    def gc_workspaces_deleted_before(
+        self,
+        *,
+        deleted_before: str,
+        dry_run: bool,
+        include_vectors: bool,
+    ) -> dict[str, Any]:
+        return self.post(
+            "/gc/workspaces",
+            {
+                "deleted_before": deleted_before,
+                "dry_run": dry_run,
+                "include_vectors": include_vectors,
+            },
+        )
+
+    def gc_item(
+        self,
+        workspace_id: str,
+        item_id: str,
+        *,
+        dry_run: bool,
+        include_vectors: bool,
+    ) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/gc/items/{item_id}",
+            {"dry_run": dry_run, "include_vectors": include_vectors},
+        )
+
+    def gc_mcp_call_logs(
+        self,
+        *,
+        deleted_before: str,
+        dry_run: bool,
+        workspace_id: str | None = None,
+    ) -> dict[str, Any]:
+        return self.post(
+            "/gc/mcp-call-logs",
+            {
+                "deleted_before": deleted_before,
+                "dry_run": dry_run,
+                "workspace_id": workspace_id,
+            },
+        )
+
+    def get_vector_index_status(self, workspace_id: str) -> dict[str, Any]:
+        payload = self.get(f"/workspaces/{workspace_id}/vector-index")
+        status = str(
+            payload.get("status") or payload.get("vector_index_status") or "unknown"
+        )
+        return {
+            **payload,
+            "workspace_id": payload.get("workspace_id") or workspace_id,
+            "vector_index_status": status,
+            "needs_rebuild": status == "needs_rebuild",
+            "vector_index_error": payload.get("error")
+            or payload.get("vector_index_error"),
+            "vector_index_rebuild_requested_at": payload.get("rebuild_requested_at")
+            or payload.get(
+                "vector_index_rebuild_requested_at",
+            ),
+        }
+
+    def rebuild_vector_index(
+        self,
+        workspace_id: str,
+        *,
+        dry_run: bool,
+    ) -> dict[str, Any]:
+        return self.post(
+            f"/workspaces/{workspace_id}/vector-index/rebuild",
+            {"dry_run": dry_run},
+        )
+
+    def revoke(self, refresh_token: str) -> None:
+        self.post(
+            "/auth/revoke",
+            {"refresh_token": refresh_token},
+            authenticated=False,
+        )
+
+    def refresh(self, refresh_token: str) -> dict[str, Any]:
+        return self.post(
+            "/auth/refresh",
+            {"refresh_token": refresh_token},
+            authenticated=False,
+        )
+
+    def get(
+        self,
+        path: str,
+        query: dict[str, Any] | None = None,
+        *,
+        authenticated: bool = True,
+    ) -> Any:
+        return self.request("GET", path, query=query, authenticated=authenticated)
+
+    def post(
+        self,
+        path: str,
+        payload: dict[str, Any],
+        *,
+        authenticated: bool = True,
+    ) -> Any:
+        return self.request("POST", path, payload=payload, authenticated=authenticated)
+
+    def patch(self, path: str, payload: dict[str, Any]) -> Any:
+        return self.request("PATCH", path, payload=payload)
+
+    def put(self, path: str, payload: dict[str, Any]) -> Any:
+        return self.request("PUT", path, payload=payload)
+
+    def delete(self, path: str) -> Any:
+        return self.request("DELETE", path)
+
+    def delete_with_payload(self, path: str, payload: dict[str, Any]) -> Any:
+        return self.request("DELETE", path, payload=payload)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        payload: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+        authenticated: bool = True,
+        retry_on_unauthorized: bool = True,
+        raw_body: bytes | MultipartBody | None = None,
+        content_type: str | None = None,
+        extra_headers: dict[str, str] | None = None,
+        parse_json: bool = True,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        if query:
+            url = f"{url}?{urlencode(query)}"
+
+        headers = {
+            "Accept": "application/json",
+            "X-Request-ID": secrets.token_hex(16),
+        }
+        body = None
+        if payload is not None:
+            body = json.dumps(payload).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if raw_body is not None:
+            body = raw_body
+            if content_type is not None:
+                headers["Content-Type"] = content_type
+            if isinstance(raw_body, MultipartBody):
+                headers["Content-Length"] = str(raw_body.content_length)
+        if extra_headers:
+            headers.update(extra_headers)
+        if authenticated:
+            if not self.access_token:
+                raise CliAPIError(
+                    code="auth.unauthorized",
+                    message="Not logged in. Run `cortex auth login`.",
+                    status_code=401,
+                )
+            headers["Authorization"] = f"Bearer {self.access_token}"
+
+        request = Request(url, data=body, headers=headers, method=method)
+        try:
+            with urlopen(request, timeout=request_timeout_seconds()) as response:
+                content = response.read()
+                if not parse_json:
+                    return content
+                if not content:
+                    return None
+                return json.loads(content.decode("utf-8"))
+        except HTTPError as exc:
+            error = parse_http_error(exc)
+            if (
+                authenticated
+                and retry_on_unauthorized
+                and error.status_code == 401
+                and self.refresh_token
+            ):
+                self.refresh_access_token()
+                return self.request(
+                    method,
+                    path,
+                    payload=payload,
+                    query=query,
+                    authenticated=authenticated,
+                    retry_on_unauthorized=False,
+                    raw_body=raw_body,
+                    content_type=content_type,
+                    extra_headers=extra_headers,
+                    parse_json=parse_json,
+                )
+            raise error from exc
+        except URLError as exc:
+            raise CliAPIError(
+                code="network.error",
+                message=str(exc.reason),
+                status_code=0,
+            ) from exc
+
+    def multipart_post(
+        self,
+        endpoint_path: str,
+        *,
+        fields: dict[str, Any],
+        file_field: str,
+        file_path: Path,
+        idempotency_key: str | None,
+    ) -> Any:
+        body, content_type = encode_multipart(
+            fields=fields,
+            file_field=file_field,
+            path=file_path,
+        )
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self.request(
+            "POST",
+            endpoint_path,
+            raw_body=body,
+            content_type=content_type,
+            extra_headers=headers,
+        )
+
+    def refresh_access_token(self) -> None:
+        if not self.refresh_token:
+            raise CliAPIError(
+                code="auth.unauthorized",
+                message="Not logged in. Run `cortex auth login`.",
+                status_code=401,
+            )
+        payload = self.refresh(self.refresh_token)
+        self.access_token = payload["access_token"]
+        self.refresh_token = payload["refresh_token"]
+        if self.token_updater is not None:
+            self.token_updater(payload)
+
+
+def parse_http_error(exc: HTTPError) -> CliAPIError:
+    try:
+        payload = json.loads(exc.read().decode("utf-8"))
+        error = payload.get("error", {})
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        error = {}
+
+    return CliAPIError(
+        code=str(error.get("code") or "http.error"),
+        message=str(error.get("message") or exc.reason),
+        status_code=exc.code,
+        details=error.get("details") or {},
+    )
+
+
+def request_timeout_seconds() -> int:
+    raw = os.environ.get("CORTEX_CLI_REQUEST_TIMEOUT_SECONDS")
+    if raw is None:
+        return DEFAULT_REQUEST_TIMEOUT_SECONDS
+    try:
+        value = int(raw)
+    except ValueError:
+        return DEFAULT_REQUEST_TIMEOUT_SECONDS
+    if value <= 0:
+        return DEFAULT_REQUEST_TIMEOUT_SECONDS
+    return value
+
+
+def compact_query(query: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in query.items() if value is not None}
+
+
+def invite_link_token_from_value(value: str) -> str:
+    raw = value.strip()
+    parsed = urlparse(raw)
+    if parsed.scheme and parsed.netloc:
+        path_token = parsed.path.rstrip("/").rsplit("/", 1)[-1]
+        return path_token or raw
+    return raw
+
+
+def require_json_payload(payload: Any, *, operation: str) -> dict[str, Any]:
+    if isinstance(payload, dict):
+        return payload
+    raise CliAPIError(
+        code="api.empty_response",
+        message=f"{operation} expected a JSON response body.",
+        status_code=502,
+    )
+
+
+def encode_multipart(
+    *,
+    fields: dict[str, Any],
+    file_field: str,
+    path: Path,
+) -> tuple[MultipartBody, str]:
+    boundary = f"----cortex-{secrets.token_hex(16)}"
+    chunks: list[bytes] = []
+    for name, value in fields.items():
+        chunks.extend(
+            [
+                f"--{boundary}\r\n".encode(),
+                f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode(),
+                str(value).encode(),
+                b"\r\n",
+            ]
+        )
+    filename = path.name
+    mime_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+    chunks.extend(
+        [
+            f"--{boundary}\r\n".encode(),
+            (
+                f'Content-Disposition: form-data; name="{file_field}"; '
+                f'filename="{filename}"\r\n'
+            ).encode(),
+            f"Content-Type: {mime_type}\r\n\r\n".encode(),
+        ]
+    )
+    body = MultipartBody(
+        prefix=b"".join(chunks),
+        path=path,
+        suffix=b"\r\n" + f"--{boundary}--\r\n".encode(),
+    )
+    return body, f"multipart/form-data; boundary={boundary}"