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

lumera/sdk.py

@@ -1,451 +1,998 @@
-import datetime as _dt
-import logging as _logging
-import mimetypes
-import os
-import pathlib
-import time as _time
-from functools import wraps as _wraps
-from typing import IO, Iterable, TypedDict
-
-import requests
-from dotenv import load_dotenv
-
-# ---------------------------------------------------------------------------
-# Environment variables inside the kernel VM
-# ---------------------------------------------------------------------------
-
-TOKEN_ENV = "LUMERA_TOKEN"
-BASE_URL_ENV = "LUMERA_BASE_URL"
-ENV_PATH = "/root/.env"
-
-# Load variables from /root/.env if it exists (and also current dir .env)
-load_dotenv(override=False)  # Local .env (no-op in prod)
-load_dotenv(ENV_PATH, override=False)
+"""
+Low-level SDK implementation - prefer high-level modules instead.
 
+For most use cases, import from these modules instead of sdk.py:
 
-# Determine API base URL ------------------------------------------------------
+    from lumera import pb       # Record operations (pb.search, pb.create, pb.update, etc.)
+    from lumera import storage  # File uploads (storage.upload, storage.upload_file)
+    from lumera import llm      # LLM completions (llm.complete, llm.chat, llm.embed)
+    from lumera import locks    # Locking (locks.claim_record_locks, locks.release_record_locks)
 
-_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 = "/lumera-files"  # backward compatible default
-MOUNT_ROOT = os.getenv(MOUNT_ROOT_ENV, DEFAULT_MOUNT_ROOT)
+Example:
+    # Instead of:
+    from lumera.sdk import list_records, create_record
+    result = list_records("deposits", filter={"status": "pending"})
 
+    # Use:
+    from lumera import pb
+    result = pb.search("deposits", filter={"status": "pending"})
 
-# ---------------------------------------------------------------------------
-# Internal helpers
-# ---------------------------------------------------------------------------
-
-
-def _ensure_token() -> str:
-    """Return the personal Lumera token, loading /root/.env if necessary."""
+The functions in this module are used internally by the high-level modules.
+Direct usage is discouraged unless you need low-level control.
+"""
 
-    token = os.getenv(TOKEN_ENV)
-    if token:
-        return token
+import json
+import os
+import warnings
+from typing import Any, Iterable, Mapping, MutableMapping, Sequence, TypedDict
+
+import requests as _requests
+
+from ._utils import (
+    API_BASE as _API_BASE,
+)
+from ._utils import (
+    LEGACY_MOUNT_ROOT as _LEGACY_MOUNT_ROOT,
+)
+from ._utils import (
+    MOUNT_ROOT as _MOUNT_ROOT,
+)
+from ._utils import (
+    TOKEN_ENV as _TOKEN_ENV,
+)
+from ._utils import (
+    LumeraAPIError as _LumeraAPIError,
+)
+from ._utils import (
+    RecordNotUniqueError as _RecordNotUniqueError,
+)
+from ._utils import (
+    _api_request,
+    _api_url,
+    _default_provenance,
+    _ensure_mapping,
+    _is_sequence,
+    _prepare_automation_inputs,
+    _record_mutation,
+    _upload_automation_files,
+    _upload_automation_run_file,
+    _upload_document,
+    _upload_lumera_file,
+    _upload_session_file,
+)
+from ._utils import (
+    get_access_token as _get_access_token,
+)
+from ._utils import (
+    get_google_access_token as _get_google_access_token,
+)
+from ._utils import (
+    get_lumera_token as _get_lumera_token,
+)
+from ._utils import (
+    log_timed as _log_timed,
+)
+from ._utils import (
+    open_file as _open_file,
+)
+from ._utils import (
+    resolve_path as _resolve_path,
+)
+from ._utils import (
+    to_filerefs as _to_filerefs,
+)
+
+# Expose shared symbols for backwards-compatible imports.
+requests = _requests
+API_BASE = _API_BASE
+MOUNT_ROOT = _MOUNT_ROOT
+LEGACY_MOUNT_ROOT = _LEGACY_MOUNT_ROOT
+TOKEN_ENV = _TOKEN_ENV
+LumeraAPIError = _LumeraAPIError
+RecordNotUniqueError = _RecordNotUniqueError
+get_access_token = _get_access_token
+get_google_access_token = _get_google_access_token
+get_lumera_token = _get_lumera_token
+log_timed = _log_timed
+open_file = _open_file
+resolve_path = _resolve_path
+to_filerefs = _to_filerefs
+
+
+def upload_lumera_file(
+    collection_id_or_name: str,
+    field_name: str,
+    file_path: str | os.PathLike[str],
+    *,
+    record_id: str | None = None,
+) -> dict[str, Any]:
+    """Upload a file to a ``lumera_file`` field and return its descriptor.
+
+    The returned descriptor can be assigned directly in ``create_record`` or
+    ``update_record`` payloads (single file or appended to a list for
+    multi-select fields).
+
+    Example::
+
+        descriptor = upload_lumera_file("projects", "attachments", "~/report.pdf")
+        create_record("projects", {"attachments": [descriptor]})
+    """
 
-    raise RuntimeError(
-        f"{TOKEN_ENV} environment variable not set (checked environment and {ENV_PATH})"
+    return _upload_lumera_file(
+        collection_id_or_name,
+        field_name,
+        file_path,
+        record_id=record_id,
+        api_request=_api_request,
     )
 
 
 # ---------------------------------------------------------------------------
-# Provider-agnostic access-token retrieval
+# Unified FileRef helpers
 # ---------------------------------------------------------------------------
 
 
-# _token_cache maps provider
-# without an explicit expiry (e.g. API keys) we store `float('+inf')` so that
-# they are never considered stale.
-# Map provider -> (token, expiry)
-_token_cache: dict[str, tuple[str, float]] = {}
-
-# ``expires_at`` originates from the Lumera API and may be one of several
-# formats: epoch seconds (``int``/``float``), an RFC 3339 / ISO-8601 string, or
-# even ``None``. We therefore accept ``Any`` and normalise it internally.
-
-
-# Accept multiple formats returned by the API (epoch seconds or ISO-8601), or
-# ``None`` when the token never expires.
+class FileRef(TypedDict, total=False):
+    scope: str
+    id: str
+    name: str
+    path: str
+    run_path: str
+    object_name: str
+    mime: str
+    size: int
 
 
-def _parse_expiry(expires_at: int | float | str | None) -> float:
-    """Convert `expires_at` from the API (may be ISO8601 or epoch) to epoch seconds.
+class CollectionField(TypedDict, total=False):
+    id: str
+    name: str
+    type: str
+    system: bool
+    required: bool
+    presentable: bool
+    hidden: bool
+    options: dict[str, Any]
+
+
+class HookReplayResult(TypedDict, total=False):
+    hook_id: str
+    hook_name: str
+    status: str
+    error: str
+    event_log_id: str
+    replay_id: str
+
+
+_UNSET = object()
+
+
+def list_collections() -> dict[str, Any]:
+    """Return all PocketBase collections visible to the current tenant."""
+
+    return _api_request("GET", "collections")
+
+
+def get_collection(collection_id_or_name: str) -> dict[str, Any]:
+    """Retrieve a single PocketBase collection by name or id."""
+
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+    return _api_request("GET", f"collections/{collection_id_or_name}")
+
+
+def ensure_collection(
+    name: str,
+    *,
+    collection_type: str = "base",
+    schema: Iterable[CollectionField] | object = _UNSET,
+    id: str | None = None,
+    indexes: Iterable[str] | object = _UNSET,
+) -> dict[str, Any]:
+    """Ensure a collection exists with the given schema and indexes.
+
+    This is an idempotent operation - it creates the collection if it doesn't exist,
+    or updates it if it does. Safe to call multiple times with the same arguments.
+
+    The `schema` field should contain ONLY user-defined fields. System fields
+    (id, created, updated, created_by, updated_by, external_id, lm_provenance)
+    are automatically managed by Lumera and should not be included.
+
+    The `indexes` field should contain ONLY user-defined indexes. System indexes
+    (external_id unique index, updated index) are automatically managed.
+
+    Args:
+        name: Collection name (display name, can be renamed later).
+        collection_type: Collection type, defaults to "base".
+        schema: List of field definitions. If provided, replaces all user fields.
+                If omitted, existing fields are preserved.
+        id: Optional stable identifier. If provided on creation, this ID will be
+            used instead of an auto-generated one. The ID remains stable even if
+            the collection is renamed. Must be alphanumeric with underscores only.
+            Cannot be changed after creation.
+        indexes: List of index DDL statements. If provided, replaces all user indexes.
+                 If omitted, existing indexes are preserved.
+
+    Returns:
+        The collection data including:
+        - id: The collection's stable identifier
+        - name: The collection's display name
+        - schema: User-defined fields only
+        - indexes: User-defined indexes only
+        - systemInfo: Object with system-managed fields and indexes (read-only)
+
+    Example:
+        # Create with stable ID for automations
+        coll = ensure_collection(
+            "Customer Orders Q1",
+            schema=[
+                {"name": "amount", "type": "number", "required": True},
+            ],
+            id="orders",  # stable reference
+        )
 
-    Returns +inf if `expires_at` is falsy/None.
+        # Later, rename collection but ID stays "orders"
+        # Automations using search("orders", ...) still work!
     """
+    if not name or not name.strip():
+        raise ValueError("name is required")
 
-    if not expires_at:
-        return float("inf")
-
-    if isinstance(expires_at, (int, float)):
-        return float(expires_at)
-
-    # Assume RFC 3339 / ISO 8601 string.
-    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]:
-    """Call the Lumera API to obtain a valid access token for *provider*."""
+    name = name.strip()
+    payload: dict[str, Any] = {}
 
-    provider = provider.lower().strip()
-    if not provider:
-        raise ValueError("provider is required")
+    if collection_type:
+        payload["type"] = collection_type
 
-    token = _ensure_token()
+    if id is not None and id.strip():
+        payload["id"] = id.strip()
 
-    url = f"{API_BASE}/connections/{provider}/access-token"
-    headers = {"Authorization": f"token {token}"}
+    if schema is not _UNSET:
+        if schema is None:
+            raise ValueError("schema cannot be None; provide an iterable of fields or omit")
+        payload["schema"] = [dict(field) for field in schema]
 
-    resp = requests.get(url, headers=headers, timeout=30)
-    resp.raise_for_status()
+    if indexes is not _UNSET:
+        payload["indexes"] = list(indexes) if indexes is not None else []
 
-    data = resp.json()
-    access_token = data.get("access_token")
-    expires_at = data.get("expires_at")
+    return _api_request("PUT", f"collections/{name}", json_body=payload)
 
-    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
+# Backwards compatibility aliases
+def create_collection(
+    name: str,
+    *,
+    collection_type: str = "base",
+    schema: Iterable[CollectionField] | None = None,
+    indexes: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Create a new PocketBase collection.
 
-
-def get_access_token(provider: str, min_valid_seconds: int = 900) -> str:
-    """Return a cached access token for *provider* valid
-    *min_valid_seconds*.
-
-       Automatically refreshes tokens via the Lumera API when they are missing or
-       close to expiry.  For tokens without an expiry (API keys) the first value
-       is cached indefinitely.
+    .. deprecated::
+        Use :func:`ensure_collection` instead, which handles both create and update.
     """
+    warnings.warn(
+        "create_collection() is deprecated, use ensure_collection() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return ensure_collection(
+        name,
+        collection_type=collection_type,
+        schema=schema if schema is not None else [],
+        indexes=indexes if indexes is not None else [],
+    )
 
-    global _token_cache
 
-    provider = provider.lower().strip()
-    if not provider:
-        raise ValueError("provider is required")
+def update_collection(
+    collection_id_or_name: str,
+    *,
+    name: str | None | object = _UNSET,
+    collection_type: str | None | object = _UNSET,
+    schema: Iterable[CollectionField] | object = _UNSET,
+    indexes: Iterable[str] | object = _UNSET,
+) -> dict[str, Any]:
+    """Update a PocketBase collection.
 
-    now = _time.time()
+    .. deprecated::
+        Use :func:`ensure_collection` instead, which handles both create and update.
+        Note: The 'name' parameter for renaming is no longer supported.
+    """
+    warnings.warn(
+        "update_collection() is deprecated, use ensure_collection() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if name is not _UNSET and name != collection_id_or_name:
+        raise ValueError("Renaming collections via 'name' parameter is no longer supported")
+
+    return ensure_collection(
+        collection_id_or_name,
+        collection_type=collection_type if collection_type is not _UNSET else "base",
+        schema=schema,
+        indexes=indexes,
+    )
 
-    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
 
-    # (Re)fetch from server
-    access_token, expiry_ts = _fetch_access_token(provider)
-    _token_cache[provider] = (access_token, expiry_ts)
-    return access_token
+def delete_collection(collection_id_or_name: str) -> None:
+    """Delete a PocketBase collection by name or id."""
+
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+    _api_request("DELETE", f"collections/{collection_id_or_name}")
+
+
+def list_records(
+    collection_id_or_name: str,
+    *,
+    page: int | None = None,
+    per_page: int | None = None,
+    limit: int | None = None,
+    offset: int | None = None,
+    sort: str | None = None,
+    filter: Mapping[str, Any] | Sequence[Any] | None = None,
+    expand: str | None = None,
+) -> dict[str, Any]:
+    """List records for the given collection.
+
+    Args:
+        collection_id_or_name: Collection name or ID. Required.
+        page: 1-based page index for paginated queries (mutually exclusive
+            with ``offset``/``limit``).
+        per_page: Page size (max 200). Only used when ``page`` is provided.
+        limit: Alternative to ``per_page`` for cursor-style queries.
+        offset: Starting offset for cursor-style queries.
+        sort: Optional sort expression (e.g. ``"-created"``).
+        filter: Filter as dict (JSON object). String filters are NOT supported.
+            Use dict syntax with optional comparison operators:
+
+            * Simple equality: ``{"status": "pending"}``
+            * Comparison: ``{"amount": {"gt": 1000}}`` (gt, gte, lt, lte, eq)
+            * OR logic: ``{"or": [{"status": "a"}, {"status": "b"}]}``
+            * AND (implicit): ``{"status": "active", "amount": {"gt": 100}}``
+
+            The SDK JSON-encodes the filter for the API.
+        expand: Optional comma-separated list of relation fields to expand.
+            Expanded relations are included inline in the record response.
+            Example: ``"user_id,company_id"`` or ``"line_items_via_deposit_id"``
+
+    Returns:
+        The raw response from ``GET /collections/{id}/records`` including
+        ``items``, ``page``/``perPage`` metadata, etc.
+    """
 
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+
+    params: dict[str, Any] = {}
+    if page is not None:
+        params["page"] = page
+    if per_page is not None:
+        params["perPage"] = per_page
+    if limit is not None:
+        params["limit"] = limit
+    if offset is not None:
+        params["offset"] = offset
+    if sort is not None:
+        params["sort"] = sort
+    if filter is not None:
+        params["filter"] = json.dumps(filter)
+    if expand is not None:
+        params["expand"] = expand
+
+    path = f"collections/{collection_id_or_name}/records"
+    return _api_request("GET", path, params=params or None)
+
+
+def query_sql(
+    sql: str,
+    *,
+    params: Mapping[str, Any] | None = None,
+    args: Sequence[Any] | None = None,
+) -> dict[str, Any]:
+    """Execute a read-only PocketBase SQL query via ``POST /pb/sql``.
+
+    Args:
+        sql: The SQL statement to execute. Must be a SELECT/read-only
+            query; write operations are rejected by the API.
+        params: Optional dict of named parameters referenced in the SQL via
+            ``{{param}}`` placeholders. Mutually exclusive with ``args``.
+        args: Optional sequence of positional parameters for ``?``
+            placeholders. Mutually exclusive with ``params``.
+
+    Returns:
+        The JSON response from ``/pb/sql`` including ``columns`` and
+        ``rows`` (when applicable), ``rowsAffected``/``lastInsertId`` (for
+        compatible statements), and ``durationMs``.
+    """
 
-# Backwards-compatibility wrapper ------------------------------------------------
+    sql_text = (sql or "").strip()
+    if not sql_text:
+        raise ValueError("sql is required")
+    if params and args:
+        raise ValueError("provide either params or args, not both")
 
+    payload: dict[str, Any] = {"sql": sql_text}
+    if params is not None:
+        if not isinstance(params, Mapping):
+            raise TypeError("params must be a mapping")
+        payload["params"] = dict(params)
+    if args is not None:
+        if isinstance(args, (str, bytes)):
+            raise TypeError("args must be a sequence of values, not a string")
+        payload["args"] = list(args)
 
-def get_google_access_token(min_valid_seconds: int = 900) -> str:
-    """Legacy helper kept for old notebooks
-    delegates to get_access_token."""
+    response = _api_request("POST", "pb/sql", json_body=payload)
+    if isinstance(response, MutableMapping):
+        return dict(response)
+    raise RuntimeError("unexpected response payload")
 
-    return get_access_token("google", min_valid_seconds=min_valid_seconds)
 
+def get_record(collection_id_or_name: str, record_id: str) -> dict[str, Any]:
+    """Retrieve a single record by id."""
 
-# ---------------------------------------------------------------------------
-# Function timing decorator
-# ---------------------------------------------------------------------------
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+    if not record_id:
+        raise ValueError("record_id is required")
 
+    path = f"collections/{collection_id_or_name}/records/{record_id}"
+    return _api_request("GET", path)
 
-_logger = _logging.getLogger(__name__)
 
+def get_record_by_external_id(collection_id_or_name: str, external_id: str) -> dict[str, Any]:
+    """Retrieve a record by its unique external_id."""
 
-def log_timed(fn):
-    """Decorator that logs entry/exit and wall time for function calls.
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+    if not external_id:
+        raise ValueError("external_id is required")
 
-    Logs at INFO level using a module-level logger named after this module.
+    response = list_records(
+        collection_id_or_name,
+        per_page=1,
+        filter={"external_id": external_id},
+    )
+    items = response.get("items") if isinstance(response, dict) else None
+    if not items:
+        url = _api_url(f"collections/{collection_id_or_name}/records")
+        raise LumeraAPIError(404, "record not found", url=url, payload=None)
+    first = items[0]
+    if not isinstance(first, dict):
+        raise RuntimeError("unexpected response payload")
+    return first
+
+
+def run_automation(
+    automation_id: str,
+    *,
+    inputs: Mapping[str, Any] | str | None = None,
+    files: Mapping[str, str | os.PathLike[str] | Sequence[str | os.PathLike[str]]] | None = None,
+    status: str | None = None,
+    error: str | None = None,
+    provenance: Mapping[str, Any] | None = None,
+    external_id: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Create an automation run and optionally upload files for file inputs.
+
+    Args:
+        automation_id: The automation to run. Required.
+        inputs: Inputs payload (dict or JSON string). File refs are resolved automatically.
+        files: Mapping of input key -> path(s) to upload before run creation.
+        status: Optional initial status (defaults to ``queued``).
+        error: Optional error string to store alongside the initial status.
+        provenance: Custom provenance payload; falls back to environment-derived provenance.
+        external_id: Stable idempotency key. If provided, repeated calls with the same value
+            will return the existing run (server-side idempotency).
+        metadata: Arbitrary JSON metadata to persist with the run (e.g., callback_url).
     """
 
-    @_wraps(fn)
-    def wrapper(*args, **kwargs):
-        _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
+    automation_id = automation_id.strip()
+    if not automation_id:
+        raise ValueError("automation_id is required")
 
+    run_id: str | None = None
 
-# ---------------------------------------------------------------------------
-# Unified FileRef helpers
-# ---------------------------------------------------------------------------
-
-
-class FileRef(TypedDict, total=False):
-    scope: str
-    id: str
-    name: str
-    path: str
-    run_path: str
-    object_name: str
-    mime: str
-    size: int
+    prepared_inputs = _prepare_automation_inputs(inputs) or {}
 
+    file_map = files or {}
+    run_id, upload_descriptors = _upload_automation_files(
+        run_id, file_map, api_request=_api_request
+    )
 
-def resolve_path(file_or_path: str | FileRef) -> str:
-    """Return an absolute path string for a FileRef or path-like input.
+    final_inputs = json.loads(json.dumps(prepared_inputs)) if prepared_inputs else {}
+    for key, descriptors in upload_descriptors.items():
+        if len(descriptors) == 1 and not _is_sequence(file_map.get(key)):
+            final_inputs[key] = descriptors[0]
+        else:
+            final_inputs[key] = descriptors
 
-    Accepts:
-      - str paths (returned as-is)
-      - dicts with keys like {"path": "/..."} or {"run_path": "/..."}
+    cleaned_status = status.strip() if isinstance(status, str) else ""
+    payload: dict[str, Any] = {
+        "automation_id": automation_id,
+        "inputs": json.dumps(final_inputs),
+        "status": cleaned_status or "queued",
+    }
+    if run_id:
+        payload["id"] = run_id
+    if error is not None:
+        payload["error"] = error
+    if external_id:
+        payload["external_id"] = external_id.strip()
+    if metadata is not None:
+        payload["metadata"] = _ensure_mapping(metadata, name="metadata")
+    payload["lm_provenance"] = _ensure_mapping(
+        provenance, name="provenance"
+    ) or _default_provenance(automation_id, run_id)
+
+    run = _api_request("POST", "automation-runs", json_body=payload)
+    if not isinstance(run, dict):
+        raise RuntimeError("unexpected response payload")
+    return run
+
+
+def get_automation_run(
+    automation_id: str | None = None,
+    *,
+    run_id: str | None = None,
+    external_id: str | None = None,
+) -> dict[str, Any]:
+    """Fetch an automation run by id or by automation_id + external_id idempotency key.
+
+    Args:
+        automation_id: Automation id for external_id lookup.
+            Required when ``run_id`` is not provided.
+        run_id: Optional run id. When provided, takes precedence over external_id.
+        external_id: Optional idempotency key to look up the latest run for the automation.
+
+    Raises:
+        ValueError: If required identifiers are missing.
+        LumeraAPIError: If no matching run is found.
     """
 
-    if isinstance(file_or_path, str):
-        return file_or_path
-    if isinstance(file_or_path, dict):
-        if "path" in file_or_path and isinstance(file_or_path["path"], str):
-            return file_or_path["path"]
-        if "run_path" in file_or_path and isinstance(file_or_path["run_path"], str):
-            return file_or_path["run_path"]
-    raise TypeError("Unsupported file_or_path; expected str or dict with 'path'/'run_path'")
-
-
-def open_file(
-    file_or_path: str | FileRef,
-    mode: str = "r",
-    **kwargs: object,
-) -> IO[str] | IO[bytes]:
-    """Open a file from a FileRef or absolute path inside the mount root.
-
-    Usage:
-        with open_file(file_ref, 'r') as f:
-            data = f.read()
+    if run_id:
+        return _api_request("GET", f"automation-runs/{run_id}")
+
+    automation_id = automation_id.strip() if isinstance(automation_id, str) else ""
+    external_id = external_id.strip() if isinstance(external_id, str) else ""
+    if not automation_id:
+        raise ValueError("automation_id is required when run_id is not provided")
+    if not external_id:
+        raise ValueError("external_id is required when run_id is not provided")
+
+    resp = _api_request(
+        "GET",
+        "automation-runs",
+        params={
+            "automation_id": automation_id,
+            "external_id": external_id,
+            "limit": 1,
+        },
+    )
+    runs = resp.get("data") if isinstance(resp, dict) else None  # Backend returns "data" key
+    if runs and isinstance(runs, list) and runs and isinstance(runs[0], dict):
+        return runs[0]
+
+    url = _api_url("automation-runs")
+    raise _LumeraAPIError(404, "automation run not found", url=url, payload=None)
+
+
+def update_automation_run(
+    run_id: str,
+    *,
+    result: Mapping[str, Any] | None = None,
+    status: str | None = None,
+    error: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Update an automation run with result, status, or other fields.
+
+    Args:
+        run_id: The run id to update. Required.
+        result: Optional result payload to store (max 20KB).
+        status: Optional status update.
+        error: Optional error string.
+        metadata: Optional metadata update.
+
+    Returns:
+        The updated automation run record.
     """
+    run_id = run_id.strip() if isinstance(run_id, str) else ""
+    if not run_id:
+        raise ValueError("run_id is required")
+
+    payload: dict[str, Any] = {}
+    if result is not None:
+        payload["result"] = _ensure_mapping(result, name="result")
+    if status is not None:
+        payload["status"] = status.strip()
+    if error is not None:
+        payload["error"] = error
+    if metadata is not None:
+        payload["metadata"] = _ensure_mapping(metadata, name="metadata")
+
+    if not payload:
+        raise ValueError("at least one field to update is required")
+
+    response = _api_request("PATCH", f"automation-runs/{run_id}", json_body=payload)
+    if not isinstance(response, dict):
+        raise RuntimeError("unexpected response payload")
+    return response
+
+
+def create_record(
+    collection_id_or_name: str,
+    payload: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Create a record in the specified collection."""
+
+    return _record_mutation("POST", collection_id_or_name, payload, api_request=_api_request)
+
+
+def update_record(
+    collection_id_or_name: str,
+    record_id: str,
+    payload: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Update an existing record."""
+
+    return _record_mutation(
+        "PATCH",
+        collection_id_or_name,
+        payload,
+        record_id=record_id,
+        api_request=_api_request,
+    )
 
-    p = resolve_path(file_or_path)
-    return open(p, mode, **kwargs)
 
+def delete_record(collection_id_or_name: str, record_id: str) -> None:
+    """Delete a record from the specified collection."""
 
-def to_filerefs(
-    values: Iterable[str | FileRef],
-    scope: str,
-    id: str,
-) -> list[FileRef]:
-    """Convert a list of strings or partial dicts into FileRef-like dicts.
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+    if not record_id:
+        raise ValueError("record_id is required")
 
-    This is a helper for tests/fixtures; it does not perform storage lookups.
-    If a value is a string, it is assumed to be an absolute path under the mount root.
-    """
+    path = f"collections/{collection_id_or_name}/records/{record_id}"
+    _api_request("DELETE", path)
 
-    out: list[FileRef] = []
-    for v in values:
-        if isinstance(v, str):
-            name = os.path.basename(v)
-            object_name = f"{scope}/{id}/{name}"
-            out.append(
-                {
-                    "scope": scope,
-                    "id": id,
-                    "name": name,
-                    "path": v,
-                    "object_name": object_name,
-                }
-            )
-        elif isinstance(v, dict):
-            # Fill minimal fields if missing
-            name = v.get("name") or os.path.basename(v.get("path") or v.get("run_path") or "")
-            path = v.get("path") or v.get("run_path") or ""
-            object_name = v.get("object_name") or f"{scope}/{id}/{name}"
-            out.append(
-                {
-                    "scope": v.get("scope", scope),
-                    "id": v.get("id", id),
-                    "name": name,
-                    "path": path,
-                    "object_name": object_name,
-                    **{k: v[k] for k in ("mime", "size") if k in v},
-                }
-            )
-        else:
-            raise TypeError("values must contain str or dict entries")
-    return out
 
+# =============================================================================
+# Bulk Record Operations
+# =============================================================================
 
-# ---------------------------------------------------------------------------
-# Document upload helper (unchanged apart from minor refactoring)
-# ---------------------------------------------------------------------------
 
+def bulk_delete_records(
+    collection_id_or_name: str,
+    record_ids: Sequence[str],
+    *,
+    transaction: bool = False,
+) -> dict[str, Any]:
+    """Bulk delete records by IDs.
 
-def _pretty_size(size: int) -> str:
-    """Return *size* in bytes as a human-readable string (e.g. "1.2 MB").
+    Args:
+        collection_id_or_name: Collection name or ID
+        record_ids: List of record IDs to delete (max 1000)
+        transaction: If True, use all-or-nothing semantics (rollback on any failure)
 
-    Iteratively divides by 1024 and appends the appropriate unit all the way up
-    to terabytes.
+    Returns:
+        Result with succeeded/failed counts and any errors
     """
-
-    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:
-    """Upload file into the current Playground session's file space."""
-
-    token = _ensure_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"}
-
-    # 1) Get signed upload URL
-    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", "")
-
-    # 2) Upload bytes
-    with open(path, "rb") as fp:
-        put = requests.put(upload_url, data=fp, headers={"Content-Type": mimetype}, timeout=300)
-        put.raise_for_status()
-
-    # 3) Optionally enable docs (idempotent; ignore errors)
-    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_agent_run_file(file_path: str, run_id: str) -> dict:
-    """Upload file into the current Agent Run's file space."""
-
-    token = _ensure_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"}
-
-    # 1) Get signed upload URL for the agent run
-    resp = requests.post(
-        f"{API_BASE}/agent-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"]
-
-    # Prefer returning the structured FileRef if available
-    file_ref = data.get("file") if isinstance(data, dict) else None
-
-    # 2) Upload bytes
-    with open(path, "rb") as fp:
-        put = requests.put(upload_url, data=fp, headers={"Content-Type": mimetype}, timeout=300)
-        put.raise_for_status()
-
-    # 3) Return a minimal record, preferring the backend-provided FileRef
-    if isinstance(file_ref, dict):
-        return file_ref
-    # Fallback to a compact shape similar to session uploads
-    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"),
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+    if not record_ids:
+        raise ValueError("record_ids is required")
+
+    path = f"collections/{collection_id_or_name}/records/bulk/delete"
+    body: dict[str, Any] = {"ids": list(record_ids)}
+    if transaction:
+        body["transaction"] = True
+    result = _api_request("POST", path, json_body=body)
+    return result if isinstance(result, dict) else {}
+
+
+def bulk_update_records(
+    collection_id_or_name: str,
+    records: Sequence[Mapping[str, Any]],
+    *,
+    transaction: bool = False,
+) -> dict[str, Any]:
+    """Update multiple records with individual data per record.
+
+    Args:
+        collection_id_or_name: Collection name or ID
+        records: List of records to update (max 1000). Each record must have an 'id' field.
+        transaction: If True, use all-or-nothing semantics (rollback on any failure)
+
+    Returns:
+        Result with succeeded/failed counts
+    """
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+    if not records:
+        raise ValueError("records is required")
+
+    path = f"collections/{collection_id_or_name}/records/bulk/update"
+    body: dict[str, Any] = {"records": [dict(r) for r in records]}
+    if transaction:
+        body["transaction"] = True
+    result = _api_request("POST", path, json_body=body)
+    return result if isinstance(result, dict) else {}
+
+
+def bulk_upsert_records(
+    collection_id_or_name: str,
+    records: Sequence[Mapping[str, Any]],
+    *,
+    transaction: bool = False,
+) -> dict[str, Any]:
+    """Upsert multiple records (create or update by ID).
+
+    Args:
+        collection_id_or_name: Collection name or ID
+        records: List of records (max 1000). Include 'id' field to update existing.
+        transaction: If True, use all-or-nothing semantics (rollback on any failure)
+
+    Returns:
+        Result with succeeded/failed counts and created record IDs
+    """
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+    if not records:
+        raise ValueError("records is required")
+
+    path = f"collections/{collection_id_or_name}/records/bulk/upsert"
+    body: dict[str, Any] = {"records": [dict(r) for r in records]}
+    if transaction:
+        body["transaction"] = True
+    result = _api_request("POST", path, json_body=body)
+    return result if isinstance(result, dict) else {}
+
+
+def bulk_insert_records(
+    collection_id_or_name: str,
+    records: Sequence[Mapping[str, Any]],
+    *,
+    transaction: bool = False,
+) -> dict[str, Any]:
+    """Insert multiple new records.
+
+    Args:
+        collection_id_or_name: Collection name or ID
+        records: List of records to create (max 1000)
+        transaction: If True, use all-or-nothing semantics (rollback on any failure)
+
+    Returns:
+        Result with succeeded/failed counts and created record IDs
+    """
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+    if not records:
+        raise ValueError("records is required")
+
+    path = f"collections/{collection_id_or_name}/records/bulk/insert"
+    body: dict[str, Any] = {"records": [dict(r) for r in records]}
+    if transaction:
+        body["transaction"] = True
+    result = _api_request("POST", path, json_body=body)
+    return result if isinstance(result, dict) else {}
+
+
+def replay_hook(
+    collection_id_or_name: str,
+    event: str,
+    record_id: str,
+    *,
+    hook_ids: Sequence[str] | None = None,
+    original_event_id: str | None = None,
+) -> list[HookReplayResult]:
+    """Trigger PocketBase hooks for a record and return execution results."""
+
+    collection = collection_id_or_name.strip()
+    hook_event = event.strip()
+    record = record_id.strip()
+    if not collection:
+        raise ValueError("collection_id_or_name is required")
+    if not hook_event:
+        raise ValueError("event is required")
+    if not record:
+        raise ValueError("record_id is required")
+
+    payload: dict[str, Any] = {
+        "collection": collection,
+        "event": hook_event,
+        "record_id": record,
     }
 
+    if hook_ids:
+        trimmed = [value.strip() for value in hook_ids if isinstance(value, str) and value.strip()]
+        if trimmed:
+            payload["hook_ids"] = trimmed
+
+    if original_event_id and original_event_id.strip():
+        payload["original_event_id"] = original_event_id.strip()
+
+    response = _api_request("POST", "hooks/replay", json_body=payload)
+    if not isinstance(response, Mapping):
+        return []
+
+    raw_results = response.get("results")
+    if not isinstance(raw_results, list):
+        return []
+
+    results: list[HookReplayResult] = []
+    for item in raw_results:
+        if not isinstance(item, Mapping):
+            continue
+        result: HookReplayResult = {}
+        for key in (
+            "hook_id",
+            "hook_name",
+            "status",
+            "error",
+            "event_log_id",
+            "replay_id",
+        ):
+            value = item.get(key)
+            if isinstance(value, str):
+                result[key] = value
+        results.append(result)
+    return results
+
+
+def claim_locks(
+    *,
+    job_type: str,
+    collection: str,
+    record_ids: Sequence[str],
+    job_id: str | None = None,
+    claimed_by: str | None = None,
+    ttl_seconds: int | None = None,
+    provenance: Mapping[str, Any] | None = None,
+) -> Mapping[str, Any]:
+    """Claim one or more records (or logical resources) in ``lm_locks``.
+
+    Args:
+        job_type: Logical workflow name (e.g. ``exports.ar``). Required.
+        collection: Namespace for the resource family. This is usually a
+            Lumera collection but it can be any identifier (e.g.
+            ``"cron:billing"``) as long as the combination of
+            ``collection`` + ``record_id`` is stable.
+        record_ids: Iterable of record/resource identifiers to lease. Each
+            entry is trimmed and empty values are ignored.
+        job_id: Optional run identifier. When supplied, releases and
+            reclaims can target the locks owned by this specific run without
+            disturbing other workers using the same ``job_type``.
+        claimed_by: Optional worker identifier recorded in the lock row.
+        ttl_seconds: Optional lease duration; defaults to the server TTL
+            (15 minutes) when omitted or non-positive.
+        provenance: Optional structured payload describing the actor/run. If
+            omitted we fall back to :func:`_default_provenance` using the
+            derived ``claimed_by`` and ``job_id`` inputs.
+
+    Returns:
+        The JSON body returned by ``/locks/claim`` describing the claim
+        outcome (typically the ``claimed``/``skipped`` ids and TTL).
+    """
 
-def _upload_document(file_path: str) -> dict:
-    """Fallback: Upload file into global Documents collection."""
-
-    token = _ensure_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"
-
-    # 1) Create
-    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"]
-
-    # 2) Signed URL
-    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"]
-
-    # 3) PUT bytes
-    with open(path, "rb") as fp:
-        put = requests.put(upload_url, data=fp, headers={"Content-Type": mimetype}, timeout=300)
-        put.raise_for_status()
-
-    # 4) Finalize
-    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()
+    jt = job_type.strip()
+    coll = collection.strip()
+    if not jt:
+        raise ValueError("job_type is required")
+    if not coll:
+        raise ValueError("collection is required")
+    trimmed = [value.strip() for value in record_ids if isinstance(value, str) and value.strip()]
+    if not trimmed:
+        raise ValueError("record_ids must include at least one value")
+    body: dict[str, Any] = {"job_type": jt, "collection": coll, "record_ids": trimmed}
+    job_ref = job_id.strip() if isinstance(job_id, str) else ""
+    if job_ref:
+        body["job_id"] = job_ref
+
+    claimed_by_ref = claimed_by.strip() if isinstance(claimed_by, str) else ""
+    if claimed_by_ref:
+        body["claimed_by"] = claimed_by_ref
+    if ttl_seconds and ttl_seconds > 0:
+        body["ttl_seconds"] = ttl_seconds
+
+    if provenance is not None:
+        body["provenance"] = _ensure_mapping(provenance, name="provenance")
+    else:
+        body["provenance"] = _default_provenance(claimed_by_ref, job_ref or None)
+
+    response = _api_request("POST", "locks/claim", json_body=body)
+    if isinstance(response, MutableMapping):
+        return response
+    raise RuntimeError("unexpected response payload")
+
+
+def release_locks(
+    *,
+    job_type: str,
+    record_ids: Sequence[str] | None = None,
+    job_id: str | None = None,
+    collection: str | None = None,
+) -> int:
+    """Release previously claimed locks.
+
+    Provide whatever context you used when claiming (``job_type`` plus
+    optional ``job_id``/``collection``/``record_ids``) to target a subset of
+    locks for deletion. When only ``job_type`` is specified, every lock of
+    that type is released for the company; add finer filters to avoid
+    dropping other workers' leases.
+    """
+    jt = job_type.strip()
+    if not jt:
+        raise ValueError("job_type is required")
+    body: dict[str, Any] = {"job_type": jt}
+    if job_id and job_id.strip():
+        body["job_id"] = job_id.strip()
+    if collection and collection.strip():
+        body["collection"] = collection.strip()
+    if record_ids:
+        trimmed = [
+            value.strip() for value in record_ids if isinstance(value, str) and value.strip()
+        ]
+        if trimmed:
+            body["record_ids"] = trimmed
+
+    response = _api_request("POST", "locks/release", json_body=body)
+    if isinstance(response, MutableMapping):
+        released = response.get("released")
+        if isinstance(released, int):
+            return released
+    raise RuntimeError("unexpected response payload")
+
+
+def reclaim_locks(
+    *,
+    job_type: str,
+    collection: str | None = None,
+    ttl_seconds: int | None = None,
+) -> int:
+    """Delete stale locks whose leases have expired.
+
+    Typically run periodically (or before a new batch starts) to evict
+    locks older than ``ttl_seconds``. If ``collection`` is supplied only
+    that namespace is scanned, otherwise every lock for ``job_type`` is
+    considered.
+    """
+    jt = job_type.strip()
+    if not jt:
+        raise ValueError("job_type is required")
+    body: dict[str, Any] = {"job_type": jt}
+    if collection and collection.strip():
+        body["collection"] = collection.strip()
+    if ttl_seconds and ttl_seconds > 0:
+        body["ttl_seconds"] = ttl_seconds
+    response = _api_request("POST", "locks/reclaim", json_body=body)
+    if isinstance(response, MutableMapping):
+        reclaimed = response.get("reclaimed")
+        if isinstance(reclaimed, int):
+            return reclaimed
+    raise RuntimeError("unexpected response payload")
+
+
+def upsert_record(
+    collection_id_or_name: str,
+    payload: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Create or update a record identified by external_id."""
+
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+
+    data = _ensure_mapping(payload, name="payload")
+    external_id = str(data.get("external_id", "")).strip()
+    if not external_id:
+        raise ValueError("payload.external_id is required for upsert")
+    data["external_id"] = external_id
+
+    path = f"collections/{collection_id_or_name}/records/upsert"
+    response = _api_request("POST", path, json_body=data)
+
+    if not isinstance(response, dict):
+        raise RuntimeError("unexpected response payload")
+    return response
 
 
 def save_to_lumera(file_path: str) -> dict:
@@ -459,7 +1006,7 @@ def save_to_lumera(file_path: str) -> dict:
 
     run_id = os.getenv("LUMERA_RUN_ID", "").strip()
     if run_id:
-        return _upload_agent_run_file(file_path, run_id)
+        return _upload_automation_run_file(file_path, run_id)
 
     session_id = os.getenv("LUMERA_SESSION_ID", "").strip()
     if session_id: