lumera 0.6.0__py3-none-any.whl → 0.7.3__py3-none-any.whl

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,
@@ -34,7 +34,7 @@ from .sdk import (
     create_record,
     delete_collection,
     delete_record,
-    get_agent_run,
+    get_automation_run,
     get_collection,
     get_record,
     get_record_by_external_id,
@@ -42,8 +42,9 @@ from .sdk import (
     list_records,
     query_sql,
     replay_hook,
-    run_agent,
+    run_automation,
     save_to_lumera,
+    update_automation_run,
     update_collection,
     update_record,
     upload_lumera_file,
@@ -73,8 +74,9 @@ __all__ = [
     # Other operations
     "replay_hook",
     "query_sql",
-    "run_agent",
-    "get_agent_run",
+    "run_automation",
+    "get_automation_run",
+    "update_automation_run",
     "upload_lumera_file",
     "save_to_lumera",
     # Type definitions
@@ -89,6 +91,7 @@ __all__ = [
     "RecordNotFoundError",
     "LockHeldError",
     # New modules (use as lumera.pb, lumera.storage, etc.)
+    "automations",
     "pb",
     "storage",
     "llm",

lumera/_utils.py

@@ -117,10 +117,10 @@ def _utcnow_iso() -> str:
     )
 
 
-def _default_provenance(agent_id: str, run_id: str | None) -> dict[str, Any]:
+def _default_provenance(automation_id: str, run_id: str | None) -> dict[str, Any]:
     recorded_at = _utcnow_iso()
-    env_agent_id = os.getenv("LUMERA_AGENT_ID", "").strip()
-    agent_id = (agent_id or "").strip() or env_agent_id
+    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()
 
@@ -132,8 +132,8 @@ def _default_provenance(agent_id: str, run_id: str | None) -> dict[str, Any]:
         "recorded_at": recorded_at,
     }
 
-    if agent_id:
-        payload["agent"] = {"id": agent_id}
+    if automation_id:
+        payload["agent"] = {"id": automation_id}  # Backend still expects "agent" key
 
     if run_id:
         payload["agent_run"] = {"id": run_id}
@@ -284,7 +284,7 @@ def _ensure_mapping(payload: Mapping[str, Any] | None, *, name: str) -> dict[str
     return dict(payload)
 
 
-def _prepare_agent_inputs(
+def _prepare_automation_inputs(
     inputs: Mapping[str, Any] | str | None,
 ) -> dict[str, Any] | None:
     if inputs is None:
@@ -345,7 +345,7 @@ def _upload_file_to_presigned(upload_url: str, path: pathlib.Path, content_type:
         resp.raise_for_status()
 
 
-def _upload_agent_files(
+def _upload_automation_files(
     run_id: str | None,
     files: Mapping[str, str | os.PathLike[str] | Sequence[str | os.PathLike[str]]],
     *,
@@ -370,7 +370,7 @@ def _upload_agent_files(
             size = file_path.stat().st_size
 
             body: dict[str, Any] = {
-                "scope": "agent_run",
+                "scope": "automation_run",
                 "filename": filename,
                 "content_type": content_type,
                 "size": size,
@@ -631,7 +631,7 @@ def _upload_session_file(file_path: str, session_id: str) -> dict:
     return {"name": filename, "notebook_path": notebook_path}
 
 
-def _upload_agent_run_file(file_path: str, run_id: str) -> dict:
+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():
@@ -644,7 +644,7 @@ def _upload_agent_run_file(file_path: str, run_id: str) -> dict:
     headers = {"Authorization": f"token {token}", "Content-Type": "application/json"}
 
     resp = requests.post(
-        f"{API_BASE}/agent-runs/{run_id}/files/upload-url",
+        f"{API_BASE}/automation-runs/{run_id}/files/upload-url",
         json={"filename": filename, "content_type": mimetype, "size": size},
         headers=headers,
         timeout=30,
@@ -742,10 +742,10 @@ __all__ = [
     "_is_sequence",
     "_normalize_mount_path",
     "_pretty_size",
-    "_prepare_agent_inputs",
+    "_prepare_automation_inputs",
     "_record_mutation",
-    "_upload_agent_files",
-    "_upload_agent_run_file",
+    "_upload_automation_files",
+    "_upload_automation_run_file",
     "_upload_file_to_presigned",
     "_upload_document",
     "_upload_session_file",

lumera/automations.py

@@ -0,0 +1,835 @@
+"""
+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_automation_run as _get_automation_run
+from .sdk import run_automation as _run_automation
+
+# ============================================================================
+# 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("automation_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_automation_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"automation-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:
+        """Return the input schema as a dict. API always returns JSON object."""
+        return self._data.get("input_schema")
+
+    @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_automation(
+        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_automation_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["automation_id"] = automation_id
+    if status:
+        params["status"] = status
+
+    result = _api_request("GET", "automation-runs", params=params)
+    items = []
+    if isinstance(result, dict):
+        # API returns runs in different keys depending on context
+        items = result.get("automation_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", "automations", params=params)
+    items = []
+    if isinstance(result, dict):
+        items = result.get("automations") 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"automations/{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", "automations", params={"external_id": external_id, "limit": 1})
+    if isinstance(result, dict):
+        items = result.get("automations") 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="automations",
+        payload=None,
+    )
+
+
+def create(
+    name: str,
+    code: str,
+    *,
+    input_schema: Mapping[str, Any] | None = None,
+    description: str | None = None,
+    external_id: str | None = None,
+    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.
+        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 schedule is not None:
+        payload["schedule"] = schedule
+    if schedule_tz is not None:
+        payload["schedule_tz"] = schedule_tz
+
+    result = _api_request("POST", "automations", 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,
+    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.
+        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 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"automations/{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,
+    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.
+        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,
+            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,
+            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"automations/{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}/automation-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/pb.py

@@ -76,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,
 )
@@ -112,18 +124,6 @@ from .sdk import (
 from .sdk import (
     upsert_record as _upsert_record,
 )
-from .sdk import (
-    bulk_delete_records as _bulk_delete_records,
-)
-from .sdk import (
-    bulk_update_records as _bulk_update_records,
-)
-from .sdk import (
-    bulk_upsert_records as _bulk_upsert_records,
-)
-from .sdk import (
-    bulk_insert_records as _bulk_insert_records,
-)
 
 
 def search(

lumera/sdk.py

@@ -51,10 +51,10 @@ from ._utils import (
     _default_provenance,
     _ensure_mapping,
     _is_sequence,
-    _prepare_agent_inputs,
+    _prepare_automation_inputs,
     _record_mutation,
-    _upload_agent_files,
-    _upload_agent_run_file,
+    _upload_automation_files,
+    _upload_automation_run_file,
     _upload_document,
     _upload_lumera_file,
     _upload_session_file,
@@ -388,8 +388,8 @@ def get_record_by_external_id(collection_id_or_name: str, external_id: str) -> d
     return first
 
 
-def run_agent(
-    agent_id: str,
+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,
@@ -402,7 +402,7 @@ def run_agent(
     """Create an agent run and optionally upload files for file inputs.
 
     Args:
-        agent_id: The automation/agent to run. Required.
+        automation_id: The automation/agent 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``).
@@ -413,16 +413,18 @@ def run_agent(
         metadata: Arbitrary JSON metadata to persist with the run (e.g., callback_url).
     """
 
-    agent_id = agent_id.strip()
-    if not agent_id:
-        raise ValueError("agent_id is required")
+    automation_id = automation_id.strip()
+    if not automation_id:
+        raise ValueError("automation_id is required")
 
     run_id: str | None = None
 
-    prepared_inputs = _prepare_agent_inputs(inputs) or {}
+    prepared_inputs = _prepare_automation_inputs(inputs) or {}
 
     file_map = files or {}
-    run_id, upload_descriptors = _upload_agent_files(run_id, file_map, api_request=_api_request)
+    run_id, upload_descriptors = _upload_automation_files(
+        run_id, file_map, api_request=_api_request
+    )
 
     final_inputs = json.loads(json.dumps(prepared_inputs)) if prepared_inputs else {}
     for key, descriptors in upload_descriptors.items():
@@ -433,7 +435,7 @@ def run_agent(
 
     cleaned_status = status.strip() if isinstance(status, str) else ""
     payload: dict[str, Any] = {
-        "agent_id": agent_id,
+        "automation_id": automation_id,
         "inputs": json.dumps(final_inputs),
         "status": cleaned_status or "queued",
     }
@@ -447,24 +449,24 @@ def run_agent(
         payload["metadata"] = _ensure_mapping(metadata, name="metadata")
     payload["lm_provenance"] = _ensure_mapping(
         provenance, name="provenance"
-    ) or _default_provenance(agent_id, run_id)
+    ) or _default_provenance(automation_id, run_id)
 
-    run = _api_request("POST", "agent-runs", json_body=payload)
+    run = _api_request("POST", "automation-runs", json_body=payload)
     if not isinstance(run, dict):
         raise RuntimeError("unexpected response payload")
     return run
 
 
-def get_agent_run(
-    agent_id: str | None = None,
+def get_automation_run(
+    automation_id: str | None = None,
     *,
     run_id: str | None = None,
     external_id: str | None = None,
 ) -> dict[str, Any]:
-    """Fetch an agent run by id or by agent_id + external_id idempotency key.
+    """Fetch an agent run by id or by automation_id + external_id idempotency key.
 
     Args:
-        agent_id: Agent id for external_id lookup. Required when ``run_id`` is not provided.
+        automation_id: Agent id for external_id lookup. Required when ``run_id`` is not provided.
         run_id: Optional run id. When provided, this takes precedence over external_id lookup.
         external_id: Optional idempotency key to look up the latest run for the agent.
 
@@ -474,29 +476,33 @@ def get_agent_run(
     """
 
     if run_id:
-        return _api_request("GET", f"agent-runs/{run_id}")
+        return _api_request("GET", f"automation-runs/{run_id}")
 
-    agent_id = agent_id.strip() if isinstance(agent_id, str) else ""
+    automation_id = automation_id.strip() if isinstance(automation_id, str) else ""
     external_id = external_id.strip() if isinstance(external_id, str) else ""
-    if not agent_id:
-        raise ValueError("agent_id is required when run_id is not provided")
+    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",
-        "agent-runs",
-        params={"agent_id": agent_id, "external_id": external_id, "limit": 1},
+        "automation-runs",
+        params={
+            "automation_id": automation_id,
+            "external_id": external_id,
+            "limit": 1,
+        },
     )
-    runs = resp.get("agent_runs") if isinstance(resp, dict) else None
+    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("agent-runs")
-    raise _LumeraAPIError(404, "agent run not found", url=url, payload=None)
+    url = _api_url("automation-runs")
+    raise _LumeraAPIError(404, "automation run not found", url=url, payload=None)
 
 
-def update_agent_run(
+def update_automation_run(
     run_id: str,
     *,
     result: Mapping[str, Any] | None = None,
@@ -533,7 +539,7 @@ def update_agent_run(
     if not payload:
         raise ValueError("at least one field to update is required")
 
-    response = _api_request("PATCH", f"agent-runs/{run_id}", json_body=payload)
+    response = _api_request("PATCH", f"automation-runs/{run_id}", json_body=payload)
     if not isinstance(response, dict):
         raise RuntimeError("unexpected response payload")
     return response
@@ -627,9 +633,7 @@ def bulk_update_records(
         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)}
-    )
+    result = _api_request("POST", path, json_body={"ids": list(record_ids), "data": dict(data)})
     return result if isinstance(result, dict) else {}
 
 
@@ -652,9 +656,7 @@ def bulk_upsert_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]}
-    )
+    result = _api_request("POST", path, json_body={"records": [dict(r) for r in records]})
     return result if isinstance(result, dict) else {}
 
 
@@ -677,9 +679,7 @@ def bulk_insert_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]}
-    )
+    result = _api_request("POST", path, json_body={"records": [dict(r) for r in records]})
     return result if isinstance(result, dict) else {}
 
 
@@ -912,7 +912,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:

lumera/storage.py

@@ -116,7 +116,7 @@ def upload(
 
     # Request presigned upload URL
     resp = requests.post(
-        f"{API_BASE}/agent-runs/{run_id}/files/upload-url",
+        f"{API_BASE}/automation-runs/{run_id}/files/upload-url",
         json={"filename": filename, "content_type": content_type, "size": size},
         headers=headers,
         timeout=30,
@@ -215,7 +215,7 @@ def download_url(path: str) -> str:
     headers = {"Authorization": f"token {token}"}
 
     resp = requests.get(
-        f"{API_BASE}/agent-runs/{run_id}/files/download-url",
+        f"{API_BASE}/automation-runs/{run_id}/files/download-url",
         params={"name": filename},
         headers=headers,
         timeout=30,
@@ -257,7 +257,7 @@ def list_files(prefix: str | None = None) -> list[dict[str, Any]]:
     token = get_lumera_token()
     headers = {"Authorization": f"token {token}"}
 
-    resp = requests.get(f"{API_BASE}/agent-runs/{run_id}/files", headers=headers, timeout=30)
+    resp = requests.get(f"{API_BASE}/automation-runs/{run_id}/files", headers=headers, timeout=30)
     resp.raise_for_status()
 
     data = resp.json()

{lumera-0.6.0.dist-info → lumera-0.7.3.dist-info}/METADATA

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

lumera-0.7.3.dist-info/RECORD

@@ -0,0 +1,14 @@
+lumera/__init__.py,sha256=NuZgCTtxQNdj1HKltc76XIcx8kUuE4PKY7mUy5XCXiU,2296
+lumera/_utils.py,sha256=Ur4ZEf-khH3zFzX-aY4Y5uDqgYSWz9kJEkoR9WKy5yc,23727
+lumera/automations.py,sha256=ZHN4m1pIO7py_F3DkUTTDTsr3dbJy7Mly_-gXt3h31o,24780
+lumera/exceptions.py,sha256=bNsx4iYaroAAGsYxErfELC2B5ZJ3w5lVa1kKdIx5s9g,2173
+lumera/google.py,sha256=3IVNL1HaOtsTmunl0alnGFuUAkzQQRyCEA3CKjlPqO0,10183
+lumera/llm.py,sha256=pUTZK7t3GTK0vfxMI1PJgJwNendyuiJc5MB1pUj2vxE,14412
+lumera/locks.py,sha256=8l_qxb8nrxge7YJ-ApUTJ5MeYpIdxDeEa94Eim9O-YM,6806
+lumera/pb.py,sha256=EZABRPVbrSJ8_9Yh-BLt9cp4omkwo5r10Qs8v7wc1qc,18236
+lumera/sdk.py,sha256=GVu1Pe_r7qNPDJ5g7qeACAfW5w5TDOyK8LN3VvDwk0s,30446
+lumera/storage.py,sha256=b0W6JNSGfmhJIcmK3vrATXAwxIr_bfrj-hPuQRVLTYU,8206
+lumera-0.7.3.dist-info/METADATA,sha256=G0fM5Y0DkPMr6QsNOuUaUZPnpKiqpo25_hEMlB7T1yg,1611
+lumera-0.7.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lumera-0.7.3.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
+lumera-0.7.3.dist-info/RECORD,,

lumera-0.6.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-lumera/__init__.py,sha256=AtbfmFoPuLEIcjBS4L-XWL-ARpjUIfR370-A7PAfsC8,2188
-lumera/_utils.py,sha256=QyAaphxXGEK8XNPO0ghKLgTOYhAxcF_j3W0T8StzjxA,23610
-lumera/exceptions.py,sha256=bNsx4iYaroAAGsYxErfELC2B5ZJ3w5lVa1kKdIx5s9g,2173
-lumera/google.py,sha256=3IVNL1HaOtsTmunl0alnGFuUAkzQQRyCEA3CKjlPqO0,10183
-lumera/llm.py,sha256=pUTZK7t3GTK0vfxMI1PJgJwNendyuiJc5MB1pUj2vxE,14412
-lumera/locks.py,sha256=8l_qxb8nrxge7YJ-ApUTJ5MeYpIdxDeEa94Eim9O-YM,6806
-lumera/pb.py,sha256=oJf37awGIoJ25VA1eSA3lMUXorOtNynVC7yG30X4-lU,18236
-lumera/sdk.py,sha256=XnzVtAGonhhQ2pDMtNKEOG5ZVH1sPLK-gsyTfCfBLSA,30233
-lumera/storage.py,sha256=kQQJYVRnxcpDZQ_gB2iZy6anb3hyZN7b8a_oNuE2yYE,8191
-lumera-0.6.0.dist-info/METADATA,sha256=4rhyTGFp6Iw1Zv-ZOtDcyThUvMSljTTtyLp-EKnEyvE,1611
-lumera-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lumera-0.6.0.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
-lumera-0.6.0.dist-info/RECORD,,