lumera 0.5.4__tar.gz → 0.7.0__tar.gz

{lumera-0.5.4 → lumera-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.5.4
+Version: 0.7.0
 Summary: SDK for building on Lumera platform
 Requires-Python: >=3.11
 Requires-Dist: requests

{lumera-0.5.4 → lumera-0.7.0}/lumera/__init__.py

@@ -5,10 +5,10 @@ This SDK provides helpers for agents running within the Lumera Notebook environm
 to interact with the Lumera API and define dynamic user interfaces.
 """
 
-__version__ = "0.5.0"
+__version__ = "0.7.0"
 
 # Import new modules (as modules, not individual functions)
-from . import exceptions, llm, locks, pb, storage
+from . import automations, exceptions, llm, locks, pb, storage
 from ._utils import (
     LumeraAPIError,
     RecordNotUniqueError,
@@ -89,6 +89,7 @@ __all__ = [
     "RecordNotFoundError",
     "LockHeldError",
     # New modules (use as lumera.pb, lumera.storage, etc.)
+    "automations",
     "pb",
     "storage",
     "llm",

lumera-0.7.0/lumera/automations.py

@@ -0,0 +1,849 @@
+"""
+Automation execution and management for Lumera.
+
+This module provides a high-level interface for running and managing Lumera
+automations (background Python scripts).
+
+Run functions:
+    run()                - Run an automation by ID
+    run_by_external_id() - Run an automation by external_id
+    get_run()            - Get a run by ID
+    list_runs()          - List runs for an automation
+
+Automation management:
+    list()               - List all automations
+    get()                - Get automation by ID
+    get_by_external_id() - Get automation by external_id
+    create()             - Create a new automation
+    update()             - Update an automation
+    upsert()             - Create or update by external_id
+
+Log streaming:
+    stream_logs()        - Stream live logs from a running automation
+
+Example:
+    >>> from lumera import automations
+    >>>
+    >>> # Run an automation
+    >>> run = automations.run("agent_id", inputs={"limit": 100})
+    >>> print(run.id, run.status)
+    >>>
+    >>> # Wait for completion
+    >>> result = run.wait(timeout=300)
+    >>>
+    >>> # Or poll manually
+    >>> while run.status in ["queued", "running"]:
+    ...     time.sleep(5)
+    ...     run.refresh()
+    >>> print(run.result)
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Iterator, Mapping
+
+__all__ = [
+    # Run operations
+    "run",
+    "run_by_external_id",
+    "get_run",
+    "list_runs",
+    # Automation management
+    "list",
+    "get",
+    "get_by_external_id",
+    "create",
+    "update",
+    "upsert",
+    # Log streaming
+    "stream_logs",
+    # Classes
+    "Run",
+    "Automation",
+]
+
+from ._utils import LumeraAPIError, _api_request
+from .sdk import get_agent_run as _get_agent_run
+from .sdk import run_agent as _run_agent
+
+# ============================================================================
+# Run Class
+# ============================================================================
+
+
+class Run:
+    """Represents an automation run with methods for polling and waiting.
+
+    Attributes:
+        id: The run ID.
+        automation_id: The automation/agent ID.
+        status: Current status (queued, running, succeeded, failed, cancelled, timeout).
+        inputs: The inputs passed to the run.
+        result: The result returned by the automation (when succeeded).
+        error: Error message (when failed).
+        created: Creation timestamp.
+        started_at: Execution start timestamp.
+        finished_at: Completion timestamp.
+        external_id: Optional correlation ID.
+        trigger: How the run was initiated (manual, webhook, schedule, assistant).
+        log_pointer: S3 location of archived logs (after completion).
+        artifacts: List of output files created during execution.
+    """
+
+    def __init__(self, data: dict[str, Any]) -> None:
+        self._data = data
+
+    @property
+    def id(self) -> str:
+        return self._data.get("id", "")
+
+    @property
+    def automation_id(self) -> str:
+        return self._data.get("agent_id", "")
+
+    @property
+    def status(self) -> str:
+        return self._data.get("status", "")
+
+    @property
+    def inputs(self) -> dict[str, Any]:
+        raw = self._data.get("inputs", "{}")
+        if isinstance(raw, str):
+            try:
+                return json.loads(raw)
+            except json.JSONDecodeError:
+                return {}
+        return raw if isinstance(raw, dict) else {}
+
+    @property
+    def result(self) -> dict[str, Any] | None:
+        return self._data.get("result")
+
+    @property
+    def error(self) -> str | None:
+        return self._data.get("error")
+
+    @property
+    def created(self) -> str | None:
+        return self._data.get("created")
+
+    @property
+    def started_at(self) -> str | None:
+        return self._data.get("started_at")
+
+    @property
+    def finished_at(self) -> str | None:
+        return self._data.get("finished_at")
+
+    @property
+    def external_id(self) -> str | None:
+        return self._data.get("external_id")
+
+    @property
+    def trigger(self) -> str | None:
+        return self._data.get("trigger")
+
+    @property
+    def log_pointer(self) -> dict[str, Any] | None:
+        return self._data.get("log_pointer")
+
+    @property
+    def artifacts(self) -> list[dict[str, Any]]:
+        return self._data.get("artifacts") or []
+
+    @property
+    def is_terminal(self) -> bool:
+        """Returns True if the run has completed (success, failure, or cancelled)."""
+        return self.status in ("succeeded", "failed", "cancelled", "timeout")
+
+    def refresh(self) -> Run:
+        """Refresh run status from the server.
+
+        Returns:
+            self (for chaining).
+        """
+        if not self.id:
+            raise ValueError("Cannot refresh run without id")
+        updated = _get_agent_run(run_id=self.id)
+        self._data = updated
+        return self
+
+    def wait(
+        self,
+        timeout: float = 300,
+        poll_interval: float = 2.0,
+    ) -> dict[str, Any] | None:
+        """Block until the run completes or timeout is reached.
+
+        Args:
+            timeout: Maximum seconds to wait (default 300 = 5 minutes).
+            poll_interval: Seconds between status checks (default 2).
+
+        Returns:
+            The result dict if succeeded, None otherwise.
+
+        Raises:
+            TimeoutError: If timeout is reached before completion.
+            RuntimeError: If the run failed.
+        """
+        start = time.monotonic()
+        while not self.is_terminal:
+            elapsed = time.monotonic() - start
+            if elapsed >= timeout:
+                raise TimeoutError(
+                    f"Run {self.id} did not complete within {timeout}s (status: {self.status})"
+                )
+            time.sleep(poll_interval)
+            self.refresh()
+
+        if self.status == "failed":
+            raise RuntimeError(f"Run {self.id} failed: {self.error}")
+        if self.status in ("cancelled", "timeout"):
+            raise RuntimeError(f"Run {self.id} was {self.status}")
+
+        return self.result
+
+    def cancel(self) -> Run:
+        """Cancel the run if it's still running.
+
+        Returns:
+            self (for chaining).
+        """
+        if not self.id:
+            raise ValueError("Cannot cancel run without id")
+        result = _api_request("POST", f"agent-runs/{self.id}/cancel")
+        if isinstance(result, dict):
+            self._data = result
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the underlying data dict."""
+        return self._data.copy()
+
+    def __repr__(self) -> str:
+        return f"Run(id={self.id!r}, status={self.status!r}, automation_id={self.automation_id!r})"
+
+
+# ============================================================================
+# Automation Class
+# ============================================================================
+
+
+class Automation:
+    """Represents an automation definition.
+
+    Attributes:
+        id: The automation ID.
+        name: Display name.
+        description: Human-readable description.
+        external_id: Stable identifier for programmatic access.
+        code: Python source code.
+        input_schema: JSON schema defining inputs.
+        status: Automation status (active, inactive, archived).
+        schedule: Cron schedule (if scheduled).
+        last_run_status: Status of the most recent run.
+    """
+
+    def __init__(self, data: dict[str, Any]) -> None:
+        self._data = data
+
+    @property
+    def id(self) -> str:
+        return self._data.get("id", "")
+
+    @property
+    def name(self) -> str:
+        return self._data.get("name", "")
+
+    @property
+    def description(self) -> str | None:
+        return self._data.get("description")
+
+    @property
+    def external_id(self) -> str | None:
+        return self._data.get("external_id")
+
+    @property
+    def code(self) -> str:
+        return self._data.get("code", "")
+
+    @property
+    def input_schema(self) -> dict[str, Any] | None:
+        raw = self._data.get("input_schema")
+        if isinstance(raw, str):
+            try:
+                return json.loads(raw)
+            except json.JSONDecodeError:
+                return None
+        return raw
+
+    @property
+    def status(self) -> str | None:
+        return self._data.get("status")
+
+    @property
+    def schedule(self) -> str | None:
+        return self._data.get("schedule")
+
+    @property
+    def last_run_status(self) -> str | None:
+        return self._data.get("last_run_status")
+
+    def run(
+        self,
+        inputs: Mapping[str, Any] | None = None,
+        *,
+        external_id: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> Run:
+        """Run this automation.
+
+        Args:
+            inputs: Input parameters for the run.
+            external_id: Optional correlation ID for idempotency.
+            metadata: Optional metadata to attach to the run.
+
+        Returns:
+            A Run object representing the execution.
+        """
+        return run(self.id, inputs=inputs, external_id=external_id, metadata=metadata)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the underlying data dict."""
+        return self._data.copy()
+
+    def __repr__(self) -> str:
+        return f"Automation(id={self.id!r}, name={self.name!r})"
+
+
+# ============================================================================
+# Run Functions
+# ============================================================================
+
+
+def run(
+    automation_id: str,
+    inputs: Mapping[str, Any] | None = None,
+    *,
+    files: Mapping[str, Any] | None = None,
+    external_id: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> Run:
+    """Run an automation by ID.
+
+    Args:
+        automation_id: The automation/agent ID to run.
+        inputs: Input parameters (dict). Types are coerced based on input_schema.
+        files: File inputs to upload (mapping of input key to file path(s)).
+        external_id: Optional correlation ID for idempotency. Repeated calls
+            with the same external_id return the existing run.
+        metadata: Optional metadata to attach to the run.
+
+    Returns:
+        A Run object for tracking execution status.
+
+    Example:
+        >>> run = automations.run("abc123", inputs={"limit": 100})
+        >>> print(run.id, run.status)
+        >>> result = run.wait(timeout=300)
+    """
+    result = _run_agent(
+        automation_id,
+        inputs=inputs,
+        files=files,
+        external_id=external_id,
+        metadata=metadata,
+    )
+    return Run(result)
+
+
+def run_by_external_id(
+    external_id: str,
+    inputs: Mapping[str, Any] | None = None,
+    *,
+    files: Mapping[str, Any] | None = None,
+    run_external_id: str | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> Run:
+    """Run an automation by its external_id (more stable than internal ID).
+
+    Args:
+        external_id: The automation's external_id (e.g., "deposit_matching:step1").
+        inputs: Input parameters (dict).
+        files: File inputs to upload.
+        run_external_id: Optional correlation ID for the run itself.
+        metadata: Optional metadata to attach to the run.
+
+    Returns:
+        A Run object for tracking execution status.
+
+    Example:
+        >>> run = automations.run_by_external_id(
+        ...     "deposit_matching:step1",
+        ...     inputs={"limit": 100}
+        ... )
+    """
+    automation = get_by_external_id(external_id)
+    return run(
+        automation.id,
+        inputs=inputs,
+        files=files,
+        external_id=run_external_id,
+        metadata=metadata,
+    )
+
+
+def get_run(run_id: str) -> Run:
+    """Get a run by its ID.
+
+    Args:
+        run_id: The run ID.
+
+    Returns:
+        A Run object with current status.
+
+    Example:
+        >>> run = automations.get_run("run_abc123")
+        >>> print(run.status, run.result)
+    """
+    result = _get_agent_run(run_id=run_id)
+    return Run(result)
+
+
+def list_runs(
+    automation_id: str | None = None,
+    *,
+    status: str | None = None,
+    limit: int = 100,
+    offset: int = 0,
+    sort: str = "created",
+    dir: str = "desc",
+) -> list[Run]:
+    """List runs, optionally filtered by automation and status.
+
+    Args:
+        automation_id: Filter by automation ID (optional).
+        status: Filter by status (queued, running, succeeded, failed, etc.).
+        limit: Maximum number of results (default 100).
+        offset: Pagination offset.
+        sort: Sort field (default "created").
+        dir: Sort direction ("asc" or "desc", default "desc").
+
+    Returns:
+        List of Run objects.
+
+    Example:
+        >>> runs = automations.list_runs("agent_id", status="succeeded", limit=10)
+        >>> for r in runs:
+        ...     print(r.id, r.created, r.status)
+    """
+    params: dict[str, Any] = {
+        "limit": limit,
+        "offset": offset,
+        "sort": sort,
+        "dir": dir,
+    }
+    if automation_id:
+        params["agent_id"] = automation_id
+    if status:
+        params["status"] = status
+
+    result = _api_request("GET", "agent-runs", params=params)
+    items = []
+    if isinstance(result, dict):
+        # API returns runs in different keys depending on context
+        items = result.get("agent_runs") or result.get("data") or []
+    return [Run(item) for item in items if isinstance(item, dict)]
+
+
+# ============================================================================
+# Automation Management Functions
+# ============================================================================
+
+
+def list(
+    *,
+    q: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    sort: str = "created",
+    dir: str = "desc",
+) -> list[Automation]:
+    """List all automations.
+
+    Args:
+        q: Search query (case-insensitive name/description search).
+        limit: Maximum number of results (default 50).
+        offset: Pagination offset.
+        sort: Sort field (default "created").
+        dir: Sort direction ("asc" or "desc", default "desc").
+
+    Returns:
+        List of Automation objects.
+
+    Example:
+        >>> all_automations = automations.list()
+        >>> for a in all_automations:
+        ...     print(a.id, a.name)
+    """
+    params: dict[str, Any] = {
+        "limit": limit,
+        "offset": offset,
+        "sort": sort,
+        "dir": dir,
+    }
+    if q:
+        params["q"] = q
+
+    result = _api_request("GET", "agents", params=params)
+    items = []
+    if isinstance(result, dict):
+        items = result.get("agents") or []
+    return [Automation(item) for item in items if isinstance(item, dict)]
+
+
+def get(automation_id: str) -> Automation:
+    """Get an automation by ID.
+
+    Args:
+        automation_id: The automation ID.
+
+    Returns:
+        An Automation object.
+
+    Example:
+        >>> agent = automations.get("abc123")
+        >>> print(agent.name, agent.input_schema)
+    """
+    automation_id = automation_id.strip()
+    if not automation_id:
+        raise ValueError("automation_id is required")
+
+    result = _api_request("GET", f"agents/{automation_id}")
+    if not isinstance(result, dict):
+        raise RuntimeError("Unexpected response")
+    return Automation(result)
+
+
+def get_by_external_id(external_id: str) -> Automation:
+    """Get an automation by its external_id.
+
+    Args:
+        external_id: The automation's external_id.
+
+    Returns:
+        An Automation object.
+
+    Raises:
+        LumeraAPIError: If no automation with that external_id exists.
+
+    Example:
+        >>> agent = automations.get_by_external_id("deposit_matching:step1")
+        >>> print(agent.id, agent.name)
+    """
+    external_id = external_id.strip()
+    if not external_id:
+        raise ValueError("external_id is required")
+
+    result = _api_request("GET", "agents", params={"external_id": external_id, "limit": 1})
+    if isinstance(result, dict):
+        items = result.get("agents") or []
+        if items and isinstance(items[0], dict):
+            return Automation(items[0])
+
+    raise LumeraAPIError(
+        404, f"Automation with external_id '{external_id}' not found", url="agents", payload=None
+    )
+
+
+def create(
+    name: str,
+    code: str,
+    *,
+    input_schema: Mapping[str, Any] | None = None,
+    description: str | None = None,
+    external_id: str | None = None,
+    expose_to_ai: bool = False,
+    schedule: str | None = None,
+    schedule_tz: str | None = None,
+) -> Automation:
+    """Create a new automation.
+
+    Args:
+        name: Display name for the automation.
+        code: Python code with the entrypoint function.
+        input_schema: JSON schema defining inputs. Should include
+            ``function.name`` and ``function.parameters``.
+        description: Human-readable description.
+        external_id: Stable identifier for programmatic access.
+        expose_to_ai: If True, makes this callable as an AI tool.
+        schedule: Cron expression for scheduled runs.
+        schedule_tz: Timezone for schedule (e.g., "America/New_York").
+
+    Returns:
+        The created Automation object.
+
+    Example:
+        >>> agent = automations.create(
+        ...     name="My Automation",
+        ...     code="def main(x): return {'result': x * 2}",
+        ...     input_schema={
+        ...         "type": "function",
+        ...         "function": {
+        ...             "name": "main",
+        ...             "parameters": {
+        ...                 "type": "object",
+        ...                 "properties": {"x": {"type": "integer"}},
+        ...                 "required": ["x"]
+        ...             }
+        ...         }
+        ...     }
+        ... )
+    """
+    payload: dict[str, Any] = {
+        "name": name,
+        "code": code,
+    }
+    if input_schema is not None:
+        payload["input_schema"] = input_schema
+    if description is not None:
+        payload["description"] = description
+    if external_id is not None:
+        payload["external_id"] = external_id
+    if expose_to_ai:
+        payload["expose_to_ai"] = True
+    if schedule is not None:
+        payload["schedule"] = schedule
+    if schedule_tz is not None:
+        payload["schedule_tz"] = schedule_tz
+
+    result = _api_request("POST", "agents", json_body=payload)
+    if not isinstance(result, dict):
+        raise RuntimeError("Unexpected response")
+    return Automation(result)
+
+
+def update(
+    automation_id: str,
+    *,
+    name: str | None = None,
+    code: str | None = None,
+    input_schema: Mapping[str, Any] | None = None,
+    description: str | None = None,
+    external_id: str | None = None,
+    expose_to_ai: bool | None = None,
+    schedule: str | None = None,
+    schedule_tz: str | None = None,
+) -> Automation:
+    """Update an existing automation.
+
+    Args:
+        automation_id: The automation ID to update.
+        name: New display name.
+        code: New Python code.
+        input_schema: New input schema.
+        description: New description.
+        external_id: New external_id.
+        expose_to_ai: Whether to expose as AI tool.
+        schedule: New cron schedule (empty string to clear).
+        schedule_tz: New schedule timezone.
+
+    Returns:
+        The updated Automation object.
+
+    Example:
+        >>> automations.update("abc123", code=new_code)
+    """
+    automation_id = automation_id.strip()
+    if not automation_id:
+        raise ValueError("automation_id is required")
+
+    payload: dict[str, Any] = {}
+    if name is not None:
+        payload["name"] = name
+    if code is not None:
+        payload["code"] = code
+    if input_schema is not None:
+        payload["input_schema"] = input_schema
+    if description is not None:
+        payload["description"] = description
+    if external_id is not None:
+        payload["external_id"] = external_id
+    if expose_to_ai is not None:
+        payload["expose_to_ai"] = expose_to_ai
+    if schedule is not None:
+        payload["schedule"] = schedule
+    if schedule_tz is not None:
+        payload["schedule_tz"] = schedule_tz
+
+    if not payload:
+        raise ValueError("At least one field to update is required")
+
+    result = _api_request("PATCH", f"agents/{automation_id}", json_body=payload)
+    if not isinstance(result, dict):
+        raise RuntimeError("Unexpected response")
+    return Automation(result)
+
+
+def upsert(
+    external_id: str,
+    *,
+    name: str,
+    code: str,
+    input_schema: Mapping[str, Any] | None = None,
+    description: str | None = None,
+    expose_to_ai: bool = False,
+    schedule: str | None = None,
+    schedule_tz: str | None = None,
+) -> Automation:
+    """Create or update an automation by external_id (idempotent deploy).
+
+    If an automation with the given external_id exists, it will be updated.
+    Otherwise, a new automation will be created.
+
+    Args:
+        external_id: Stable identifier (required for upsert).
+        name: Display name.
+        code: Python code.
+        input_schema: JSON schema defining inputs.
+        description: Human-readable description.
+        expose_to_ai: If True, makes this callable as an AI tool.
+        schedule: Cron expression for scheduled runs.
+        schedule_tz: Timezone for schedule.
+
+    Returns:
+        The created or updated Automation object.
+
+    Example:
+        >>> # Idempotent deployment
+        >>> automations.upsert(
+        ...     external_id="my_app:my_automation",
+        ...     name="My Automation",
+        ...     code=open("my_script.py").read(),
+        ...     input_schema=schema
+        ... )
+    """
+    external_id = external_id.strip()
+    if not external_id:
+        raise ValueError("external_id is required for upsert")
+
+    # Try to find existing
+    try:
+        existing = get_by_external_id(external_id)
+        # Update existing
+        return update(
+            existing.id,
+            name=name,
+            code=code,
+            input_schema=input_schema,
+            description=description,
+            expose_to_ai=expose_to_ai,
+            schedule=schedule,
+            schedule_tz=schedule_tz,
+        )
+    except LumeraAPIError as e:
+        if e.status_code != 404:
+            raise
+        # Create new
+        return create(
+            name=name,
+            code=code,
+            input_schema=input_schema,
+            description=description,
+            external_id=external_id,
+            expose_to_ai=expose_to_ai,
+            schedule=schedule,
+            schedule_tz=schedule_tz,
+        )
+
+
+def delete(automation_id: str) -> None:
+    """Delete an automation.
+
+    Args:
+        automation_id: The automation ID to delete.
+
+    Example:
+        >>> automations.delete("abc123")
+    """
+    automation_id = automation_id.strip()
+    if not automation_id:
+        raise ValueError("automation_id is required")
+
+    _api_request("DELETE", f"agents/{automation_id}")
+
+
+# ============================================================================
+# Log Streaming
+# ============================================================================
+
+
+def stream_logs(run_id: str, *, timeout: float = 30) -> Iterator[str]:
+    """Stream live logs from a running automation.
+
+    Connects to the server-sent events endpoint and yields log lines
+    as they arrive. Stops when the run completes.
+
+    Args:
+        run_id: The run ID to stream logs from.
+        timeout: HTTP connection timeout in seconds.
+
+    Yields:
+        Log lines as strings.
+
+    Example:
+        >>> for line in automations.stream_logs("run_id"):
+        ...     print(line)
+    """
+    import base64
+    import os
+
+    import requests
+
+    run_id = run_id.strip()
+    if not run_id:
+        raise ValueError("run_id is required")
+
+    base_url = os.environ.get("LUMERA_BASE_URL", "https://app.lumerahq.com/api").rstrip("/")
+    token = os.environ.get("LUMERA_TOKEN", "")
+    if not token:
+        raise ValueError("LUMERA_TOKEN environment variable is required")
+
+    url = f"{base_url}/agent-runs/{run_id}/logs/live"
+    headers = {
+        "Authorization": f"token {token}",
+        "Accept": "text/event-stream",
+    }
+
+    with requests.get(url, headers=headers, stream=True, timeout=timeout) as resp:
+        resp.raise_for_status()
+
+        current_event = ""
+        current_data = ""
+
+        for line in resp.iter_lines(decode_unicode=True):
+            if line is None:
+                continue
+
+            if line.startswith("event:"):
+                current_event = line[6:].strip()
+            elif line.startswith("data:"):
+                current_data = line[5:].strip()
+            elif line == "":
+                # End of event
+                if current_event == "chunk" and current_data:
+                    try:
+                        data = json.loads(current_data)
+                        if "data" in data:
+                            # Data is base64-encoded
+                            raw = base64.b64decode(data["data"])
+                            decoded = raw.decode("utf-8", errors="replace")
+                            yield from decoded.splitlines()
+                    except (json.JSONDecodeError, KeyError):
+                        pass
+                elif current_event == "complete":
+                    return
+                current_event = ""
+                current_data = ""

{lumera-0.5.4 → lumera-0.7.0}/lumera/pb.py

@@ -60,6 +60,11 @@ __all__ = [
     "upsert",
     "delete",
     "iter_all",
+    # Bulk operations
+    "bulk_delete",
+    "bulk_update",
+    "bulk_upsert",
+    "bulk_insert",
     # Collection operations
     "list_collections",
     "get_collection",
@@ -71,6 +76,18 @@ __all__ = [
 
 # Import underlying SDK functions (prefixed with _ to indicate internal use)
 from ._utils import LumeraAPIError
+from .sdk import (
+    bulk_delete_records as _bulk_delete_records,
+)
+from .sdk import (
+    bulk_insert_records as _bulk_insert_records,
+)
+from .sdk import (
+    bulk_update_records as _bulk_update_records,
+)
+from .sdk import (
+    bulk_upsert_records as _bulk_upsert_records,
+)
 from .sdk import (
     create_collection as _create_collection,
 )
@@ -296,6 +313,104 @@ def delete(collection: str, record_id: str) -> None:
     _delete_record(collection, record_id)
 
 
+# =============================================================================
+# Bulk Operations
+# =============================================================================
+
+
+def bulk_delete(collection: str, record_ids: Sequence[str]) -> dict[str, Any]:
+    """Delete multiple records by ID.
+
+    Args:
+        collection: Collection name or ID
+        record_ids: List of record IDs to delete (max 1000)
+
+    Returns:
+        Result with succeeded/failed counts and any errors:
+        {
+            "succeeded": 10,
+            "failed": 0,
+            "errors": []
+        }
+
+    Example:
+        >>> result = pb.bulk_delete("deposits", ["id1", "id2", "id3"])
+        >>> print(f"Deleted {result['succeeded']} records")
+    """
+    return _bulk_delete_records(collection, record_ids)
+
+
+def bulk_update(
+    collection: str,
+    record_ids: Sequence[str],
+    data: dict[str, Any],
+) -> dict[str, Any]:
+    """Update multiple records with the same data.
+
+    Args:
+        collection: Collection name or ID
+        record_ids: List of record IDs to update (max 1000)
+        data: Fields to update on all records
+
+    Returns:
+        Result with succeeded/failed counts
+
+    Example:
+        >>> result = pb.bulk_update("deposits", ["id1", "id2"], {"status": "processed"})
+        >>> print(f"Updated {result['succeeded']} records")
+    """
+    return _bulk_update_records(collection, record_ids, data)
+
+
+def bulk_upsert(collection: str, records: Sequence[dict[str, Any]]) -> dict[str, Any]:
+    """Create or update multiple records by ID.
+
+    Each record can include an "id" field. Records with matching IDs will be
+    updated; records without IDs or with non-existent IDs create new records.
+
+    Args:
+        collection: Collection name or ID
+        records: List of records (max 1000)
+
+    Returns:
+        Result with succeeded/failed counts and created record IDs
+
+    Example:
+        >>> result = pb.bulk_upsert("deposits", [
+        ...     {"id": "existing_id", "amount": 100},
+        ...     {"amount": 200},  # creates new record
+        ... ])
+    """
+    return _bulk_upsert_records(collection, records)
+
+
+def bulk_insert(collection: str, records: Sequence[dict[str, Any]]) -> dict[str, Any]:
+    """Insert multiple new records.
+
+    Args:
+        collection: Collection name or ID
+        records: List of records to create (max 1000)
+
+    Returns:
+        Result with succeeded/failed counts and created record IDs:
+        {
+            "succeeded": 2,
+            "failed": 0,
+            "errors": [],
+            "records": [{"id": "..."}, {"id": "..."}]
+        }
+
+    Example:
+        >>> result = pb.bulk_insert("deposits", [
+        ...     {"external_id": "dep-001", "amount": 100},
+        ...     {"external_id": "dep-002", "amount": 200},
+        ... ])
+        >>> for rec in result["records"]:
+        ...     print(f"Created: {rec['id']}")
+    """
+    return _bulk_insert_records(collection, records)
+
+
 def iter_all(
     collection: str,
     *,

{lumera-0.5.4 → lumera-0.7.0}/lumera/sdk.py

@@ -576,6 +576,113 @@ def delete_record(collection_id_or_name: str, record_id: str) -> None:
     _api_request("DELETE", path)
 
 
+# =============================================================================
+# Bulk Record Operations
+# =============================================================================
+
+
+def bulk_delete_records(
+    collection_id_or_name: str,
+    record_ids: Sequence[str],
+) -> dict[str, Any]:
+    """Bulk delete records by IDs.
+
+    Args:
+        collection_id_or_name: Collection name or ID
+        record_ids: List of record IDs to delete (max 1000)
+
+    Returns:
+        Result with succeeded/failed counts and any errors
+    """
+    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"
+    result = _api_request("POST", path, json_body={"ids": list(record_ids)})
+    return result if isinstance(result, dict) else {}
+
+
+def bulk_update_records(
+    collection_id_or_name: str,
+    record_ids: Sequence[str],
+    data: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Update multiple records with the same data.
+
+    Args:
+        collection_id_or_name: Collection name or ID
+        record_ids: List of record IDs to update (max 1000)
+        data: Fields to update on all records
+
+    Returns:
+        Result with succeeded/failed counts
+    """
+    if not collection_id_or_name:
+        raise ValueError("collection_id_or_name is required")
+    if not record_ids:
+        raise ValueError("record_ids is required")
+    if not data:
+        raise ValueError("data is required")
+
+    path = f"collections/{collection_id_or_name}/records/bulk/update"
+    result = _api_request(
+        "POST", path, json_body={"ids": list(record_ids), "data": dict(data)}
+    )
+    return result if isinstance(result, dict) else {}
+
+
+def bulk_upsert_records(
+    collection_id_or_name: str,
+    records: Sequence[Mapping[str, Any]],
+) -> 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.
+
+    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"
+    result = _api_request(
+        "POST", path, json_body={"records": [dict(r) for r in records]}
+    )
+    return result if isinstance(result, dict) else {}
+
+
+def bulk_insert_records(
+    collection_id_or_name: str,
+    records: Sequence[Mapping[str, Any]],
+) -> dict[str, Any]:
+    """Insert multiple new records.
+
+    Args:
+        collection_id_or_name: Collection name or ID
+        records: List of records to create (max 1000)
+
+    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"
+    result = _api_request(
+        "POST", path, json_body={"records": [dict(r) for r in records]}
+    )
+    return result if isinstance(result, dict) else {}
+
+
 def replay_hook(
     collection_id_or_name: str,
     event: str,

{lumera-0.5.4 → lumera-0.7.0}/lumera.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.5.4
+Version: 0.7.0
 Summary: SDK for building on Lumera platform
 Requires-Python: >=3.11
 Requires-Dist: requests

{lumera-0.5.4 → lumera-0.7.0}/lumera.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 pyproject.toml
 lumera/__init__.py
 lumera/_utils.py
+lumera/automations.py
 lumera/exceptions.py
 lumera/google.py
 lumera/llm.py

{lumera-0.5.4 → lumera-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lumera"
-version = "0.5.4"
+version = "0.7.0"
 description = "SDK for building on Lumera platform"
 requires-python = ">=3.11"
 dependencies = [