lumera 0.4.6__py3-none-any.whl → 0.9.6__py3-none-any.whl

lumera/_utils.py

@@ -0,0 +1,782 @@
+"""Internal helpers shared across the Lumera SDK."""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import logging as _logging
+import mimetypes
+import os
+import pathlib
+import time as _time
+from functools import wraps as _wraps
+from typing import IO, Any, Callable, Iterable, Mapping, MutableMapping, Sequence, TypeVar
+
+import requests
+import requests.adapters
+from dotenv import load_dotenv
+
+TOKEN_ENV = "LUMERA_TOKEN"
+BASE_URL_ENV = "LUMERA_BASE_URL"
+ENV_PATH = "/root/.env"
+
+load_dotenv(override=False)
+load_dotenv(ENV_PATH, override=False)
+
+_default_api_base = "https://app.lumerahq.com/api"
+API_BASE = os.getenv(BASE_URL_ENV, _default_api_base).rstrip("/")
+MOUNT_ROOT_ENV = "LUMERA_MOUNT_ROOT"
+DEFAULT_MOUNT_ROOT = "/tmp/lumera-files"
+LEGACY_MOUNT_ROOT = "/lumera-files"
+_mount_env = os.getenv(MOUNT_ROOT_ENV, DEFAULT_MOUNT_ROOT).rstrip("/")
+if not _mount_env:
+    _mount_env = DEFAULT_MOUNT_ROOT
+MOUNT_ROOT = _mount_env
+
+
+_token_cache: dict[str, tuple[str, float]] = {}
+
+# Connection pooling for better performance
+_http_session: requests.Session | None = None
+
+
+def _get_session() -> requests.Session:
+    """Get or create a shared requests Session with connection pooling."""
+    global _http_session
+    if _http_session is None:
+        _http_session = requests.Session()
+        # Configure connection pooling
+        adapter = requests.adapters.HTTPAdapter(
+            pool_connections=10,
+            pool_maxsize=20,
+            max_retries=0,  # Don't retry automatically, let caller handle
+        )
+        _http_session.mount("https://", adapter)
+        _http_session.mount("http://", adapter)
+    return _http_session
+
+
+def get_lumera_token() -> str:
+    token = os.getenv(TOKEN_ENV)
+    if token:
+        return token
+    raise RuntimeError(
+        f"{TOKEN_ENV} environment variable not set (checked environment and {ENV_PATH})"
+    )
+
+
+def _parse_expiry(expires_at: int | float | str | None) -> float:
+    if not expires_at:
+        return float("inf")
+    if isinstance(expires_at, (int, float)):
+        return float(expires_at)
+    if isinstance(expires_at, str):
+        if expires_at.endswith("Z"):
+            expires_at = expires_at[:-1] + "+00:00"
+        return _dt.datetime.fromisoformat(expires_at).timestamp()
+    raise TypeError(f"Unsupported expires_at format: {type(expires_at)!r}")
+
+
+def _fetch_access_token(provider: str) -> tuple[str, float]:
+    provider = provider.lower().strip()
+    if not provider:
+        raise ValueError("provider is required")
+
+    token = get_lumera_token()
+
+    url = f"{API_BASE}/connections/{provider}/access-token"
+    headers = {"Authorization": f"token {token}"}
+
+    resp = requests.get(url, headers=headers, timeout=30)
+    resp.raise_for_status()
+
+    data = resp.json()
+    access_token = data.get("access_token")
+    expires_at = data.get("expires_at")
+
+    if not access_token:
+        raise RuntimeError(f"Malformed response from Lumera when fetching {provider} access token")
+
+    expiry_ts = _parse_expiry(expires_at)
+    return access_token, expiry_ts
+
+
+def get_access_token(provider: str, min_valid_seconds: int = 900) -> str:
+    global _token_cache
+
+    provider = provider.lower().strip()
+    if not provider:
+        raise ValueError("provider is required")
+
+    now = _time.time()
+
+    cached = _token_cache.get(provider)
+    if cached is not None:
+        access_token, expiry_ts = cached
+        if (expiry_ts - now) >= min_valid_seconds:
+            return access_token
+
+    access_token, expiry_ts = _fetch_access_token(provider)
+    _token_cache[provider] = (access_token, expiry_ts)
+    return access_token
+
+
+def get_google_access_token(min_valid_seconds: int = 900) -> str:
+    return get_access_token("google", min_valid_seconds=min_valid_seconds)
+
+
+_logger = _logging.getLogger("lumera.sdk")
+
+
+def _utcnow_iso() -> str:
+    return (
+        _dt.datetime.now(tz=_dt.timezone.utc)
+        .replace(microsecond=0)
+        .isoformat()
+        .replace("+00:00", "Z")
+    )
+
+
+def _default_provenance(automation_id: str, run_id: str | None) -> dict[str, Any]:
+    recorded_at = _utcnow_iso()
+    env_automation_id = os.getenv("LUMERA_AUTOMATION_ID", "").strip()
+    automation_id = (automation_id or "").strip() or env_automation_id
+
+    run_id = (run_id or "").strip() or os.getenv("LUMERA_RUN_ID", "").strip()
+
+    company_id = os.getenv("COMPANY_ID", "").strip()
+    company_api = os.getenv("COMPANY_API_NAME", "").strip()
+
+    payload: dict[str, Any] = {
+        "type": "user",
+        "recorded_at": recorded_at,
+    }
+
+    if automation_id:
+        payload["agent"] = {"id": automation_id}  # Backend still expects "agent" key
+
+    if run_id:
+        payload["agent_run"] = {"id": run_id}
+
+    if company_id or company_api:
+        company: dict[str, Any] = {}
+        if company_id:
+            company["id"] = company_id
+        if company_api:
+            company["api_name"] = company_api
+        payload["company"] = company
+
+    return payload
+
+
+R = TypeVar("R")
+
+
+def log_timed(fn: Callable[..., R]) -> Callable[..., R]:
+    @_wraps(fn)
+    def wrapper(*args: object, **kwargs: object) -> R:
+        _logger.info(f"Entering {fn.__name__}()")
+        t0 = _time.perf_counter()
+        try:
+            return fn(*args, **kwargs)
+        finally:
+            dt = _time.perf_counter() - t0
+            _logger.info(f"Exiting {fn.__name__}() - took {dt:.3f}s")
+
+    return wrapper
+
+
+def _api_url(path: str) -> str:
+    path = path.lstrip("/")
+    if path.startswith("pb/"):
+        return f"{API_BASE}/{path}"
+    if path == "collections" or path.startswith("collections/"):
+        return f"{API_BASE}/pb/{path}"
+    return f"{API_BASE}/{path}"
+
+
+class LumeraAPIError(RuntimeError):
+    """Raised when requests to the Lumera API fail."""
+
+    def __init__(
+        self, status_code: int, message: str, *, url: str, payload: object | None = None
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.payload = payload
+        self.url = url
+
+    def __str__(self) -> str:  # pragma: no cover - trivial string formatting
+        base = super().__str__()
+        return (
+            f"{self.status_code} {self.url}: {base}" if base else f"{self.status_code} {self.url}"
+        )
+
+
+class RecordNotUniqueError(LumeraAPIError):
+    """Raised when attempting to insert a record that violates a uniqueness constraint."""
+
+    def __init__(self, url: str, payload: MutableMapping[str, object]) -> None:
+        message = next(
+            (value for value in payload.values() if isinstance(value, str) and value.strip()),
+            "record violates uniqueness constraint",
+        )
+        super().__init__(400, message, url=url, payload=payload)
+
+
+def _raise_api_error(resp: requests.Response) -> None:
+    message = resp.text.strip()
+    payload: object | None = None
+    content_type = resp.headers.get("Content-Type", "").lower()
+    if "application/json" in content_type:
+        try:
+            payload = resp.json()
+        except ValueError:
+            payload = None
+        else:
+            if isinstance(payload, MutableMapping):
+                for key in ("error", "message", "detail"):
+                    value = payload.get(key)
+                    if isinstance(value, str) and value.strip():
+                        message = value
+                        break
+                else:
+                    message = json.dumps(payload)
+            else:
+                message = json.dumps(payload)
+    if resp.status_code == 400 and payload and isinstance(payload, MutableMapping):
+        if any(
+            isinstance(value, str) and ("unique" in value.lower() or "already" in value.lower())
+            for value in payload.values()
+        ):
+            raise RecordNotUniqueError(resp.url, payload) from None
+    raise LumeraAPIError(resp.status_code, message, url=resp.url, payload=payload)
+
+
+def _api_request(
+    method: str,
+    path: str,
+    *,
+    params: Mapping[str, Any] | None = None,
+    json_body: Mapping[str, Any] | None = None,
+    data: Mapping[str, Any] | None = None,
+    files: Mapping[str, Any] | None = None,
+    timeout: int = 30,
+) -> object | None:
+    token = get_lumera_token()
+    url = _api_url(path)
+
+    headers = {
+        "Authorization": f"token {token}",
+        "Accept": "application/json",
+    }
+
+    session = _get_session()
+    resp = session.request(
+        method,
+        url,
+        params=params,
+        json=json_body,
+        data=data,
+        files=files,
+        headers=headers,
+        timeout=timeout,
+    )
+
+    if not resp.ok:
+        _raise_api_error(resp)
+
+    if resp.status_code == 204 or method.upper() == "DELETE":
+        return None
+
+    content_type = resp.headers.get("Content-Type", "").lower()
+    if "application/json" in content_type:
+        if not resp.text.strip():
+            return {}
+        return resp.json()
+    return resp.text if resp.text else None
+
+
+def _ensure_mapping(payload: Mapping[str, Any] | None, *, name: str) -> dict[str, Any]:
+    if payload is None:
+        return {}
+    if not isinstance(payload, Mapping):
+        raise TypeError(f"{name} must be a mapping, got {type(payload)!r}")
+    return dict(payload)
+
+
+def _prepare_automation_inputs(
+    inputs: Mapping[str, Any] | str | None,
+) -> dict[str, Any] | None:
+    if inputs is None:
+        return None
+    if isinstance(inputs, str):
+        inputs = inputs.strip()
+        if not inputs:
+            return {}
+        try:
+            parsed = json.loads(inputs)
+        except json.JSONDecodeError as exc:
+            raise ValueError("inputs must be JSON-serialisable") from exc
+        if not isinstance(parsed, dict):
+            raise TypeError("inputs JSON must deserialize to an object")
+        return parsed
+
+    try:
+        serialised = json.dumps(inputs)
+        parsed = json.loads(serialised)
+    except (TypeError, ValueError) as exc:
+        raise ValueError("inputs must be JSON-serialisable") from exc
+    if not isinstance(parsed, dict):
+        raise TypeError("inputs mapping must serialize to a JSON object")
+    return parsed
+
+
+def _ensure_json_string(value: Mapping[str, Any] | str, *, name: str) -> str:
+    if isinstance(value, str):
+        return value
+    try:
+        return json.dumps(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{name} must be JSON-serialisable") from exc
+
+
+def _is_sequence(value: object) -> bool:
+    if isinstance(value, (str, os.PathLike)):
+        return False
+    return isinstance(value, Sequence)
+
+
+def _ensure_sequence(
+    value: str | os.PathLike[str] | Sequence[str | os.PathLike[str]],
+) -> list[str | os.PathLike[str]]:
+    if isinstance(value, (str, os.PathLike)):
+        return [value]
+    seq = list(value)
+    if not seq:
+        raise ValueError("file input sequence must not be empty")
+    return seq
+
+
+def _upload_file_to_presigned(upload_url: str, path: pathlib.Path, content_type: str) -> None:
+    with open(path, "rb") as fh:
+        resp = requests.put(
+            upload_url, data=fh, headers={"Content-Type": content_type}, timeout=300
+        )
+        resp.raise_for_status()
+
+
+def _upload_automation_files(
+    run_id: str | None,
+    files: Mapping[str, str | os.PathLike[str] | Sequence[str | os.PathLike[str]]],
+    *,
+    api_request: Callable[..., object] | None = None,
+) -> tuple[str | None, dict[str, list[dict[str, Any]]]]:
+    api_fn = api_request or _api_request
+
+    if not files:
+        return run_id, {}
+
+    results: dict[str, list[dict[str, Any]]] = {}
+    for key, value in files.items():
+        paths = _ensure_sequence(value)
+        descriptors: list[dict[str, Any]] = []
+        for path in paths:
+            file_path = pathlib.Path(os.fspath(path)).expanduser().resolve()
+            if not file_path.is_file():
+                raise FileNotFoundError(file_path)
+
+            filename = file_path.name
+            content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+            size = file_path.stat().st_size
+
+            body: dict[str, Any] = {
+                "scope": "automation_run",
+                "filename": filename,
+                "content_type": content_type,
+                "size": size,
+            }
+            if run_id:
+                body["resource_id"] = run_id
+
+            presign = api_fn(
+                "POST",
+                "uploads/presign",
+                json_body=body,
+            )
+            if not isinstance(presign, dict):
+                raise RuntimeError("unexpected presign response")
+
+            upload_url = presign.get("upload_url")
+            if not isinstance(upload_url, str) or not upload_url:
+                raise RuntimeError("missing upload_url in presign response")
+
+            resp_run_id = presign.get("run_id")
+            if isinstance(resp_run_id, str) and resp_run_id:
+                if run_id is None:
+                    run_id = resp_run_id
+                elif run_id != resp_run_id:
+                    raise RuntimeError("presign returned inconsistent run_id")
+            elif run_id is None:
+                raise RuntimeError("presign response missing run_id")
+
+            _upload_file_to_presigned(upload_url, file_path, content_type)
+
+            descriptor: dict[str, Any] = {"name": filename}
+            if presign.get("run_path"):
+                descriptor["run_path"] = presign["run_path"]
+            if presign.get("object_key"):
+                descriptor["object_key"] = presign["object_key"]
+            descriptors.append(descriptor)
+
+        results[key] = descriptors
+    return run_id, results
+
+
+def _record_mutation(
+    method: str,
+    collection_id_or_name: str,
+    payload: Mapping[str, Any] | None,
+    *,
+    record_id: str | None = None,
+    api_request: Callable[..., object] | None = None,
+) -> dict[str, Any]:
+    api_fn = api_request or _api_request
+
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+
+    data = _ensure_mapping(payload, name="payload")
+    path = f"collections/{collection_id_or_name}/records"
+    if record_id:
+        if not record_id.strip():
+            raise ValueError("record_id is required")
+        path = f"{path}/{record_id}".rstrip("/")
+
+    response = api_fn(method, path, json_body=data)
+
+    if not isinstance(response, dict):
+        raise RuntimeError("unexpected response payload")
+    return response
+
+
+def _normalize_mount_path(path: str) -> str:
+    if not isinstance(path, str):
+        return path
+    root = MOUNT_ROOT.rstrip("/")
+    legacy = LEGACY_MOUNT_ROOT.rstrip("/")
+    if legacy and path.startswith(legacy):
+        suffix = path[len(legacy) :].lstrip("/")
+        return f"{root}/{suffix}" if suffix else root
+    return path
+
+
+def resolve_path(file_or_path: str | Mapping[str, Any]) -> str:
+    if isinstance(file_or_path, str):
+        return _normalize_mount_path(file_or_path)
+    if isinstance(file_or_path, Mapping):
+        path_value = file_or_path.get("path")
+        if isinstance(path_value, str):
+            return _normalize_mount_path(path_value)
+        run_path = file_or_path.get("run_path")
+        if isinstance(run_path, str):
+            return _normalize_mount_path(run_path)
+    raise TypeError("Unsupported file_or_path; expected str or dict with 'path'/'run_path'")
+
+
+def open_file(
+    file_or_path: str | Mapping[str, Any],
+    mode: str = "r",
+    **kwargs: object,
+) -> IO[str] | IO[bytes]:
+    p = resolve_path(file_or_path)
+    return open(p, mode, **kwargs)
+
+
+def to_filerefs(
+    values: Iterable[str | Mapping[str, Any]],
+    scope: str,
+    id: str,
+) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for v in values:
+        if isinstance(v, str):
+            normalized = _normalize_mount_path(v)
+            name = os.path.basename(normalized)
+            object_name = f"{scope}/{id}/{name}"
+            out.append(
+                {
+                    "scope": scope,
+                    "id": id,
+                    "name": name,
+                    "path": normalized,
+                    "object_name": object_name,
+                }
+            )
+        elif isinstance(v, Mapping):
+            resolved_path = resolve_path(v)
+            normalized = _normalize_mount_path(resolved_path)
+            name = v.get("name") or os.path.basename(normalized)
+            object_name = v.get("object_name") or f"{scope}/{id}/{name}"
+            ref: dict[str, Any] = {
+                "scope": v.get("scope", scope),
+                "id": v.get("id", id),
+                "name": name,
+                "path": normalized,
+                "object_name": object_name,
+            }
+            if "mime" in v:
+                ref["mime"] = v["mime"]
+            if "size" in v:
+                ref["size"] = v["size"]
+            out.append(ref)
+        else:
+            raise TypeError("values must contain str or dict entries")
+    return out
+
+
+def _upload_lumera_file(
+    collection_id_or_name: str,
+    field_name: str,
+    file_path: str | os.PathLike[str],
+    *,
+    record_id: str | None = None,
+    api_request: Callable[..., object] | None = None,
+) -> dict[str, Any]:
+    api_fn = api_request or _api_request
+
+    collection = str(collection_id_or_name or "").strip()
+    if not collection:
+        raise ValueError("collection_id_or_name is required")
+    field = str(field_name or "").strip()
+    if not field:
+        raise ValueError("field_name is required")
+
+    file_obj = pathlib.Path(os.fspath(file_path)).expanduser().resolve()
+    if not file_obj.is_file():
+        raise FileNotFoundError(file_obj)
+
+    filename = file_obj.name
+    size = file_obj.stat().st_size
+    content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+
+    payload: dict[str, Any] = {
+        "collection_id": collection,
+        "field_name": field,
+        "filename": filename,
+        "content_type": content_type,
+        "size": size,
+    }
+    if record_id and str(record_id).strip():
+        payload["record_id"] = str(record_id).strip()
+
+    presign = api_fn("POST", "pb/uploads/presign", json_body=payload)
+    if not isinstance(presign, Mapping):
+        raise RuntimeError("unexpected presign response")
+
+    upload_url = str(presign.get("upload_url") or "").strip()
+    object_key = str(presign.get("object_key") or "").strip()
+    if not upload_url or not object_key:
+        raise RuntimeError("presign response missing upload metadata")
+
+    fields = presign.get("fields") if isinstance(presign, Mapping) else None
+    if isinstance(fields, Mapping) and fields:
+        with open(file_obj, "rb") as fh:
+            files = {"file": (filename, fh, content_type)}
+            resp = requests.post(upload_url, data=dict(fields), files=files, timeout=300)
+            resp.raise_for_status()
+    else:
+        with open(file_obj, "rb") as fh:
+            resp = requests.put(
+                upload_url,
+                data=fh,
+                headers={"Content-Type": content_type},
+                timeout=300,
+            )
+            resp.raise_for_status()
+
+    descriptor = {
+        "object_key": object_key,
+        "original_name": filename,
+        "size": size,
+        "content_type": content_type,
+        "uploaded_at": _utcnow_iso(),
+    }
+    return descriptor
+
+
+def _pretty_size(size: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1024:
+            return f"{size:.1f} {unit}" if unit != "B" else f"{size} {unit}"
+        size /= 1024
+    return f"{size:.1f} TB"
+
+
+def _upload_session_file(file_path: str, session_id: str) -> dict:
+    token = get_lumera_token()
+    path = pathlib.Path(file_path).expanduser().resolve()
+    if not path.is_file():
+        raise FileNotFoundError(path)
+
+    filename = path.name
+    size = path.stat().st_size
+    mimetype = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+
+    headers = {"Authorization": f"token {token}", "Content-Type": "application/json"}
+
+    resp = requests.post(
+        f"{API_BASE}/sessions/{session_id}/files/upload-url",
+        json={"filename": filename, "content_type": mimetype, "size": size},
+        headers=headers,
+        timeout=30,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    upload_url: str = data["upload_url"]
+    notebook_path: str = data.get("notebook_path", "")
+
+    with open(path, "rb") as fp:
+        put = requests.put(upload_url, data=fp, headers={"Content-Type": mimetype}, timeout=300)
+        put.raise_for_status()
+
+    try:
+        requests.post(
+            f"{API_BASE}/sessions/{session_id}/enable-docs",
+            headers=headers,
+            timeout=15,
+        )
+    except Exception:
+        pass
+
+    return {"name": filename, "notebook_path": notebook_path}
+
+
+def _upload_automation_run_file(file_path: str, run_id: str) -> dict:
+    token = get_lumera_token()
+    path = pathlib.Path(file_path).expanduser().resolve()
+    if not path.is_file():
+        raise FileNotFoundError(path)
+
+    filename = path.name
+    size = path.stat().st_size
+    mimetype = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+
+    headers = {"Authorization": f"token {token}", "Content-Type": "application/json"}
+
+    resp = requests.post(
+        f"{API_BASE}/automation-runs/{run_id}/files/upload-url",
+        json={"filename": filename, "content_type": mimetype, "size": size},
+        headers=headers,
+        timeout=30,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    upload_url = data["upload_url"]
+    file_ref = data.get("file") if isinstance(data, dict) else None
+
+    with open(path, "rb") as fp:
+        put = requests.put(upload_url, data=fp, headers={"Content-Type": mimetype}, timeout=300)
+        put.raise_for_status()
+
+    if isinstance(file_ref, dict):
+        return file_ref
+    run_path = (
+        data.get("run_path") or data.get("path") or f"/lumera-files/agent_runs/{run_id}/{filename}"
+    )
+    return {
+        "name": filename,
+        "run_path": run_path,
+        "object_name": data.get("object_name"),
+    }
+
+
+def _upload_document(file_path: str) -> dict:
+    token = get_lumera_token()
+    path = pathlib.Path(file_path).expanduser().resolve()
+    if not path.is_file():
+        raise FileNotFoundError(path)
+
+    filename = path.name
+    size = path.stat().st_size
+    mimetype = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+    pretty = _pretty_size(size)
+
+    headers = {"Authorization": f"token {token}", "Content-Type": "application/json"}
+    documents_base = f"{API_BASE}/documents"
+
+    resp = requests.post(
+        documents_base,
+        json={
+            "title": filename,
+            "content": f"File to be uploaded: {filename} ({pretty})",
+            "type": mimetype.split("/")[-1],
+            "status": "uploading",
+        },
+        headers=headers,
+        timeout=30,
+    )
+    resp.raise_for_status()
+    doc = resp.json()
+    doc_id = doc["id"]
+
+    resp = requests.post(
+        f"{documents_base}/{doc_id}/upload-url",
+        json={"filename": filename, "content_type": mimetype, "size": size},
+        headers=headers,
+        timeout=30,
+    )
+    resp.raise_for_status()
+    upload_url: str = resp.json()["upload_url"]
+
+    with open(path, "rb") as fp:
+        put = requests.put(upload_url, data=fp, headers={"Content-Type": mimetype}, timeout=300)
+        put.raise_for_status()
+
+    resp = requests.put(
+        f"{documents_base}/{doc_id}",
+        json={
+            "status": "uploaded",
+            "content": f"Uploaded file: {filename} ({pretty})",
+        },
+        headers=headers,
+        timeout=30,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+__all__ = [
+    "API_BASE",
+    "BASE_URL_ENV",
+    "DEFAULT_MOUNT_ROOT",
+    "ENV_PATH",
+    "LEGACY_MOUNT_ROOT",
+    "MOUNT_ROOT",
+    "TOKEN_ENV",
+    "_api_request",
+    "_api_url",
+    "_default_provenance",
+    "_ensure_json_string",
+    "_ensure_mapping",
+    "_ensure_sequence",
+    "_is_sequence",
+    "_normalize_mount_path",
+    "_pretty_size",
+    "_prepare_automation_inputs",
+    "_record_mutation",
+    "_upload_automation_files",
+    "_upload_automation_run_file",
+    "_upload_file_to_presigned",
+    "_upload_document",
+    "_upload_session_file",
+    "_upload_lumera_file",
+    "open_file",
+    "resolve_path",
+    "to_filerefs",
+    "LumeraAPIError",
+    "RecordNotUniqueError",
+    "get_access_token",
+    "get_google_access_token",
+    "log_timed",
+]