lumera 0.4.20__py3-none-any.whl → 0.4.22__py3-none-any.whl

lumera/__init__.py

@@ -21,6 +21,7 @@ from .sdk import (
     create_record,
     delete_collection,
     delete_record,
+    get_agent_run,
     get_collection,
     get_record,
     get_record_by_external_id,
@@ -28,6 +29,7 @@ from .sdk import (
     list_records,
     query_sql,
     replay_hook,
+    run_agent,
     save_to_lumera,
     update_collection,
     update_record,
@@ -52,6 +54,7 @@ __all__ = [
     "replay_hook",
     "query_sql",
     "run_agent",
+    "get_agent_run",
     "upload_lumera_file",
     "create_record",
     "update_record",

lumera/sdk.py

@@ -367,8 +367,22 @@ def run_agent(
     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 agent run and optionally upload files for file inputs."""
+    """Create an agent run and optionally upload files for file inputs.
+
+    Args:
+        agent_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``).
+        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).
+    """
 
     agent_id = agent_id.strip()
     if not agent_id:
@@ -398,6 +412,10 @@ def run_agent(
         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(agent_id, run_id)
@@ -408,6 +426,90 @@ def run_agent(
     return run
 
 
+def get_agent_run(
+    agent_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.
+
+    Args:
+        agent_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.
+
+    Raises:
+        ValueError: If required identifiers are missing.
+        LumeraAPIError: If no matching run is found.
+    """
+
+    if run_id:
+        return _api_request("GET", f"agent-runs/{run_id}")
+
+    agent_id = agent_id.strip() if isinstance(agent_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 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},
+    )
+    runs = resp.get("agent_runs") if isinstance(resp, dict) else None
+    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)
+
+
+def update_agent_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 agent 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 agent 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"agent-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,

{lumera-0.4.20.dist-info → lumera-0.4.22.dist-info}/METADATA

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

lumera-0.4.22.dist-info/RECORD

@@ -0,0 +1,8 @@
+lumera/__init__.py,sha256=p8lX2fW4iFo3quxQCtRs8Gm3WxNmjEY8wLOqLAYWwXI,1467
+lumera/_utils.py,sha256=QyAaphxXGEK8XNPO0ghKLgTOYhAxcF_j3W0T8StzjxA,23610
+lumera/google.py,sha256=3IVNL1HaOtsTmunl0alnGFuUAkzQQRyCEA3CKjlPqO0,10183
+lumera/sdk.py,sha256=oW3e8X-1kpDE4lm9uFyRDiF9mBM-0XK-9aB7pm2XgOE,25677
+lumera-0.4.22.dist-info/METADATA,sha256=1I7AeCvgTT2i50zU9kguHMuAb4ihA1XZ4SV9Fl0tksw,1576
+lumera-0.4.22.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lumera-0.4.22.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
+lumera-0.4.22.dist-info/RECORD,,

lumera-0.4.20.dist-info/RECORD

@@ -1,8 +0,0 @@
-lumera/__init__.py,sha256=wiSDU8oEsyLWPx4aKjrOdRuG9xRCU2hx-2tl-0usQCI,1412
-lumera/_utils.py,sha256=QyAaphxXGEK8XNPO0ghKLgTOYhAxcF_j3W0T8StzjxA,23610
-lumera/google.py,sha256=3IVNL1HaOtsTmunl0alnGFuUAkzQQRyCEA3CKjlPqO0,10183
-lumera/sdk.py,sha256=ULWrBjRggaXtesmeBxq_eXM5a9hQMhZ9_f6-sOj4gKs,21827
-lumera-0.4.20.dist-info/METADATA,sha256=-oZpdGCUinqh6dvdK803pLbiL1a_e4SLk75wou7utH8,1576
-lumera-0.4.20.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lumera-0.4.20.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
-lumera-0.4.20.dist-info/RECORD,,