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

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.22.dist-info → lumera-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.4.22
+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.22.dist-info/RECORD

@@ -1,8 +0,0 @@
-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,,