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

lumera/sdk.py

@@ -1,3 +1,26 @@
+"""
+Low-level SDK implementation - prefer high-level modules instead.
+
+For most use cases, import from these modules instead of sdk.py:
+
+    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)
+
+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"})
+
+The functions in this module are used internally by the high-level modules.
+Direct usage is discouraged unless you need low-level control.
+"""
+
 import json
 import os
 from typing import Any, Iterable, Mapping, MutableMapping, Sequence, TypedDict
@@ -233,8 +256,9 @@ def list_records(
     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 PocketBase collection.
+    """List records for the given collection.
 
     Args:
         collection_id_or_name: Collection name or ID. Required.
@@ -244,7 +268,7 @@ def list_records(
         limit: Alternative to ``per_page`` for cursor-style queries.
         offset: Starting offset for cursor-style queries.
         sort: Optional sort expression (e.g. ``"-created"``).
-        filter: Accepts either a raw PocketBase filter string (e.g.
+        filter: Accepts either a raw filter string (e.g.
             ``"status = 'ok'"``) or a structured filter encoded as a mapping/
             sequence. Structured filters mirror the Page Builder helpers, e.g.:
 
@@ -253,6 +277,9 @@ def list_records(
 
             The SDK JSON-encodes structured filters so the API can build
             tenant-aware expressions automatically.
+        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
@@ -275,6 +302,8 @@ def list_records(
         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)
@@ -367,8 +396,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 +441,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 +455,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/storage.py

@@ -0,0 +1,269 @@
+"""
+Storage operations for uploading and managing files.
+
+Files are automatically namespaced by the current automation run:
+    /agent_runs/{run_id}/{path}
+
+This prevents collisions between different runs while allowing logical
+organization within a run.
+
+Available functions:
+    upload()       - Upload bytes/string content to storage
+    upload_file()  - Upload a local file to storage
+    download_url() - Get download URL for an uploaded file
+    list_files()   - List files uploaded in current run
+
+Environment requirements:
+    LUMERA_RUN_ID  - Set automatically when running in automation context
+    LUMERA_TOKEN   - API authentication token
+
+Example:
+    >>> from lumera import storage
+    >>> result = storage.upload("exports/report.csv", csv_data, content_type="text/csv")
+    >>> print(result["url"])
+"""
+
+__all__ = ["upload", "upload_file", "download_url", "list_files", "UploadResult"]
+
+import mimetypes
+import os
+import pathlib
+from typing import Any, Required, TypedDict
+
+import requests
+
+from ._utils import API_BASE, get_lumera_token
+
+
+class UploadResult(TypedDict, total=False):
+    """Result of file upload.
+
+    Required fields (always present):
+        url: Public download URL
+        path: Relative path within run namespace
+        size: File size in bytes
+        content_type: MIME type
+
+    Optional fields:
+        object_key: Storage object key (platform implementation detail)
+    """
+
+    url: Required[str]  # Public download URL (always present)
+    path: Required[str]  # Relative path within run namespace (always present)
+    size: Required[int]  # File size in bytes (always present)
+    content_type: Required[str]  # MIME type (always present)
+    object_key: str  # Storage object key (optional, platform detail)
+
+
+def upload(
+    path: str,
+    content: bytes | str,
+    *,
+    content_type: str,
+    metadata: dict[str, Any] | None = None,  # noqa: ARG001 - Reserved for future use
+) -> UploadResult:
+    """Upload content to storage.
+
+    Files are automatically namespaced by the current automation run.
+    Storage location: /agent_runs/{run_id}/{path}
+
+    Args:
+        path: Relative path within this run's namespace (e.g., "exports/daily.csv")
+              Can include subfolders for organization
+        content: File content as bytes or string (strings will be encoded as UTF-8)
+        content_type: MIME type (e.g., "text/csv", "application/json")
+        metadata: Optional searchable metadata (reserved for future use)
+
+    Returns:
+        Upload result with URL and metadata
+
+    Raises:
+        ValueError: If path or content_type is empty
+        RuntimeError: If LUMERA_RUN_ID environment variable is not set
+        requests.HTTPError: If upload fails
+
+    Example:
+        >>> result = storage.upload(
+        ...     path="exports/report.csv",
+        ...     content=csv_data.encode("utf-8"),
+        ...     content_type="text/csv"
+        ... )
+        >>> print(result["url"])
+        https://storage.lumerahq.com/download/abc123
+    """
+    if not path or not path.strip():
+        raise ValueError("path is required and cannot be empty")
+    if not content_type or not content_type.strip():
+        raise ValueError("content_type is required and cannot be empty")
+
+    # Get current run ID from environment
+    run_id = os.getenv("LUMERA_RUN_ID", "").strip()
+    if not run_id:
+        raise RuntimeError(
+            "LUMERA_RUN_ID environment variable not set. "
+            "This function must be called from within an automation run."
+        )
+
+    # Convert string content to bytes
+    if isinstance(content, str):
+        content = content.encode("utf-8")
+
+    filename = os.path.basename(path)
+    size = len(content)
+
+    token = get_lumera_token()
+    headers = {"Authorization": f"token {token}", "Content-Type": "application/json"}
+
+    # Request presigned upload URL
+    resp = requests.post(
+        f"{API_BASE}/agent-runs/{run_id}/files/upload-url",
+        json={"filename": filename, "content_type": content_type, "size": size},
+        headers=headers,
+        timeout=30,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+
+    upload_url = data["upload_url"]
+
+    # Upload content to presigned URL
+    put_resp = requests.put(
+        upload_url, data=content, headers={"Content-Type": content_type}, timeout=300
+    )
+    put_resp.raise_for_status()
+
+    # Construct result
+    result: UploadResult = {
+        "url": data.get("download_url", ""),
+        "object_key": data.get("object_key", ""),
+        "path": path,
+        "size": size,
+        "content_type": content_type,
+    }
+
+    return result
+
+
+def upload_file(
+    path: str,
+    file_path: str,
+    *,
+    content_type: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> UploadResult:
+    """Upload a file from disk.
+
+    Args:
+        path: Relative path in run namespace (e.g., "exports/report.pdf")
+        file_path: Local file path to upload
+        content_type: MIME type (auto-detected from extension if not provided)
+        metadata: Optional searchable metadata (reserved for future use)
+
+    Returns:
+        Upload result with URL and metadata
+
+    Raises:
+        FileNotFoundError: If file_path doesn't exist
+        ValueError: If path is empty
+
+    Example:
+        >>> result = storage.upload_file(
+        ...     path="exports/report.pdf",
+        ...     file_path="/tmp/generated_report.pdf"
+        ... )
+    """
+    file_path_obj = pathlib.Path(file_path).expanduser().resolve()
+    if not file_path_obj.is_file():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    # Auto-detect content type if not provided
+    if not content_type:
+        content_type = mimetypes.guess_type(file_path)[0] or "application/octet-stream"
+
+    # Read file content
+    with open(file_path_obj, "rb") as f:
+        content = f.read()
+
+    return upload(path, content, content_type=content_type, metadata=metadata)
+
+
+def download_url(path: str) -> str:
+    """Get download URL for a file uploaded in this run.
+
+    Args:
+        path: Relative path within this run (same as used in upload)
+
+    Returns:
+        Download URL
+
+    Raises:
+        RuntimeError: If LUMERA_RUN_ID not set
+        requests.HTTPError: If file doesn't exist
+
+    Example:
+        >>> url = storage.download_url("exports/report.csv")
+    """
+    run_id = os.getenv("LUMERA_RUN_ID", "").strip()
+    if not run_id:
+        raise RuntimeError(
+            "LUMERA_RUN_ID environment variable not set. "
+            "This function must be called from within an automation run."
+        )
+
+    filename = os.path.basename(path)
+    token = get_lumera_token()
+    headers = {"Authorization": f"token {token}"}
+
+    resp = requests.get(
+        f"{API_BASE}/agent-runs/{run_id}/files/download-url",
+        params={"name": filename},
+        headers=headers,
+        timeout=30,
+    )
+    resp.raise_for_status()
+
+    data = resp.json()
+    return data.get("download_url", "")
+
+
+def list_files(prefix: str | None = None) -> list[dict[str, Any]]:
+    """List files uploaded in this run.
+
+    Args:
+        prefix: Optional path prefix filter (e.g., "exports/")
+
+    Returns:
+        List of file metadata dicts with keys:
+        - name: filename
+        - size: size in bytes
+        - content_type: MIME type
+        - created: creation timestamp
+
+    Raises:
+        RuntimeError: If LUMERA_RUN_ID not set
+
+    Example:
+        >>> files = storage.list_files(prefix="exports/")
+        >>> for file in files:
+        ...     print(file["name"], file["size"])
+    """
+    run_id = os.getenv("LUMERA_RUN_ID", "").strip()
+    if not run_id:
+        raise RuntimeError(
+            "LUMERA_RUN_ID environment variable not set. "
+            "This function must be called from within an automation run."
+        )
+
+    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.raise_for_status()
+
+    files = resp.json()
+
+    # Filter by prefix if provided
+    if prefix:
+        files = [f for f in files if f.get("name", "").startswith(prefix)]
+
+    return files

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.4.20
+Version: 0.5.0
 Summary: SDK for building on Lumera platform
 Requires-Python: >=3.11
 Requires-Dist: requests
@@ -21,8 +21,8 @@ Requires-Dist: matplotlib==3.10.3; extra == "full"
 Requires-Dist: notion-client==2.4.0; extra == "full"
 Requires-Dist: numpy==2.3.0; extra == "full"
 Requires-Dist: office365-rest-python-client; extra == "full"
-Requires-Dist: openai; extra == "full"
-Requires-Dist: openai-agents; extra == "full"
+Requires-Dist: openai<3.0.0,>=2.15.0; extra == "full"
+Requires-Dist: openai-agents<1.0.0,>=0.6.5; extra == "full"
 Requires-Dist: openpyxl==3.1.5; extra == "full"
 Requires-Dist: pandas==2.3.0; extra == "full"
 Requires-Dist: pdfplumber; extra == "full"

lumera-0.5.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+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=nYD8veZWUxPK3pKImoP72VZMBkBQvCLbJErxRBPVykk,8858
+lumera/sdk.py,sha256=ibkf85HFMUQPaFyhCaV4DZf0IwZf1yrEW9XFPjsGZOY,26875
+lumera/storage.py,sha256=Eo4HrasZ0DKt-qVHT8UsrtfbD7hNQUU13oosjto7C-k,8157
+lumera-0.5.0.dist-info/METADATA,sha256=wFXpJ082TIaPLR_Q1Kday5DL_i4fMx_IpmqN74_Jm0A,1604
+lumera-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lumera-0.5.0.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
+lumera-0.5.0.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,,