lumera 0.9.4__tar.gz → 0.9.6__tar.gz

{lumera-0.9.4 → lumera-0.9.6}/PKG-INFO

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

{lumera-0.9.4 → lumera-0.9.6}/lumera/__init__.py

@@ -5,7 +5,7 @@ This SDK provides helpers for automations running within the Lumera environment
 to interact with the Lumera API and define dynamic user interfaces.
 """
 
-from importlib.metadata import version, PackageNotFoundError
+from importlib.metadata import PackageNotFoundError, version
 
 try:
     __version__ = version("lumera")
@@ -31,6 +31,9 @@ from .exceptions import (
     ValidationError,
 )
 
+# Import file types for Pydantic automation inputs
+from .files import LumeraFile, LumeraFiles
+
 # Import key SDK helpers to expose them at the package root.
 from .sdk import (
     CollectionField,
@@ -87,6 +90,8 @@ __all__ = [
     # Type definitions
     "CollectionField",
     "HookReplayResult",
+    "LumeraFile",
+    "LumeraFiles",
     # Exceptions
     "LumeraAPIError",
     "RecordNotUniqueError",

lumera-0.9.6/lumera/files.py

@@ -0,0 +1,97 @@
+"""
+File input types for Lumera automations.
+
+These types are used with Pydantic models to define file inputs for automations.
+They generate the correct JSON schema format that the frontend recognizes for
+file picker UI.
+
+Example:
+    from pydantic import BaseModel, Field
+    from lumera import LumeraFile, LumeraFiles
+
+    class ProcessInputs(BaseModel):
+        report: LumeraFile = Field(..., description="Excel report to process")
+        attachments: LumeraFiles = Field(default=[], description="Additional files")
+
+    def main(inputs: ProcessInputs):
+        # inputs.report is a string path like "/tmp/lumera-files/report.xlsx"
+        with open(inputs.report) as f:
+            ...
+"""
+
+from typing import Annotated, Any
+
+# Check if Pydantic is available
+try:
+    from pydantic import GetJsonSchemaHandler
+    from pydantic.json_schema import JsonSchemaValue
+    from pydantic_core import CoreSchema
+
+    _HAS_PYDANTIC = True
+except ImportError:
+    _HAS_PYDANTIC = False
+
+
+if _HAS_PYDANTIC:
+
+    class _LumeraFileSchema:
+        """
+        Pydantic JSON schema handler for single file inputs.
+
+        Generates: {"type": "string", "format": "file"}
+
+        The frontend recognizes this schema and renders a file picker.
+        At runtime, the value is a string path to the downloaded file.
+        """
+
+        @classmethod
+        def __get_pydantic_json_schema__(
+            cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler
+        ) -> JsonSchemaValue:
+            return {"type": "string", "format": "file"}
+
+    class _LumeraFilesSchema:
+        """
+        Pydantic JSON schema handler for multiple file inputs.
+
+        Generates: {"type": "array", "items": {"type": "string", "format": "file"}}
+
+        The frontend recognizes this schema and renders a multi-file picker.
+        At runtime, the value is a list of string paths to downloaded files.
+        """
+
+        @classmethod
+        def __get_pydantic_json_schema__(
+            cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler
+        ) -> JsonSchemaValue:
+            return {"type": "array", "items": {"type": "string", "format": "file"}}
+
+    # Public types using Annotated to attach schema handlers
+    LumeraFile: Any = Annotated[str, _LumeraFileSchema()]
+    """
+    Type for single file input in Pydantic models.
+
+    At runtime, this is a string containing the local file path.
+    In JSON schema, generates {"type": "string", "format": "file"}.
+
+    Example:
+        class Inputs(BaseModel):
+            document: LumeraFile = Field(..., description="PDF to process")
+    """
+
+    LumeraFiles: Any = Annotated[list[str], _LumeraFilesSchema()]
+    """
+    Type for multiple file inputs in Pydantic models.
+
+    At runtime, this is a list of strings containing local file paths.
+    In JSON schema, generates {"type": "array", "items": {"type": "string", "format": "file"}}.
+
+    Example:
+        class Inputs(BaseModel):
+            documents: LumeraFiles = Field(default=[], description="PDFs to merge")
+    """
+
+else:
+    # Fallback when Pydantic is not installed - types are just aliases
+    LumeraFile: Any = str
+    LumeraFiles: Any = list

{lumera-0.9.4 → lumera-0.9.6}/lumera/pb.py

@@ -510,7 +510,8 @@ def iter_all(
         yield from items
 
         # Check if there are more pages
-        total_pages = result.get("totalPages", 0)
+        # Use `or 0` instead of default to handle None values
+        total_pages = result.get("totalPages") or 0
         if page >= total_pages:
             break
 
@@ -563,6 +564,7 @@ def ensure_collection(
     name: str,
     schema: Sequence[dict[str, Any]] | None = None,
     *,
+    id: str | None = None,
     indexes: Sequence[str] | None = None,
 ) -> dict[str, Any]:
     """Ensure a collection exists with the given schema (idempotent).
@@ -579,7 +581,7 @@ def ensure_collection(
     If you omit schema or indexes, existing values are preserved.
 
     Args:
-        name: Collection name (must not start with '_')
+        name: Collection name (can be renamed later in UI)
         schema: List of field definitions. If provided, replaces all user fields.
                 Each field is a dict with:
                 - name: Field name (required)
@@ -587,33 +589,40 @@ def ensure_collection(
                         relation, select, editor, lumera_file
                 - required: Whether field is required (default False)
                 - options: Type-specific options (e.g., collectionId for relations)
+        id: Optional stable identifier for the collection. If provided on creation,
+            this ID will be used instead of an auto-generated one. The ID remains
+            stable even if the collection is renamed, making it ideal for use in
+            automations and hooks. Must be alphanumeric with underscores only.
+            Cannot be changed after creation.
         indexes: Optional list of user index DDL statements. If provided,
                 replaces all user indexes.
 
     Returns:
         Collection object with:
+        - id: The collection's stable identifier
+        - name: The collection's display name
         - schema: User-defined fields only (what you can modify)
         - indexes: User-defined indexes only (what you can modify)
         - systemInfo: Read-only system fields and indexes (automatically managed)
 
     Example:
-        >>> # Create or update a collection
-        >>> col = pb.ensure_collection("deposits", [
-        ...     {"name": "amount", "type": "number", "required": True},
-        ...     {"name": "status", "type": "text"},
-        ... ])
+        >>> # Create with stable ID for use in automations
+        >>> col = pb.ensure_collection(
+        ...     "Customer Orders Q1",
+        ...     schema=[
+        ...         {"name": "amount", "type": "number", "required": True},
+        ...         {"name": "status", "type": "text"},
+        ...     ],
+        ...     id="orders",  # stable reference
+        ... )
         >>>
-        >>> # Add a field using copy-modify-send pattern
-        >>> col = pb.get_collection("deposits")
-        >>> col["schema"].append({"name": "notes", "type": "text"})
-        >>> pb.ensure_collection("deposits", col["schema"])
+        >>> # Later, collection can be renamed but ID stays "orders"
+        >>> # Automations using pb.search("orders", ...) still work!
         >>>
-        >>> # Add an index
-        >>> pb.ensure_collection("deposits", indexes=[
-        ...     "CREATE INDEX idx_status ON deposits (status)"
-        ... ])
+        >>> # Create without custom ID (auto-generated)
+        >>> col = pb.ensure_collection("deposits", [...])
     """
-    return _ensure_collection(name, schema=schema, indexes=indexes)
+    return _ensure_collection(name, schema=schema, id=id, indexes=indexes)
 
 
 def delete_collection(name: str) -> None:

{lumera-0.9.4 → lumera-0.9.6}/lumera/sdk.py

@@ -185,6 +185,7 @@ def ensure_collection(
     *,
     collection_type: str = "base",
     schema: Iterable[CollectionField] | object = _UNSET,
+    id: str | None = None,
     indexes: Iterable[str] | object = _UNSET,
 ) -> dict[str, Any]:
     """Ensure a collection exists with the given schema and indexes.
@@ -200,34 +201,37 @@ def ensure_collection(
     (external_id unique index, updated index) are automatically managed.
 
     Args:
-        name: Collection name. Required.
+        name: Collection name (display name, can be renamed later).
         collection_type: Collection type, defaults to "base".
         schema: List of field definitions. If provided, replaces all user fields.
                 If omitted, existing fields are preserved.
+        id: Optional stable identifier. If provided on creation, this ID will be
+            used instead of an auto-generated one. The ID remains stable even if
+            the collection is renamed. Must be alphanumeric with underscores only.
+            Cannot be changed after creation.
         indexes: List of index DDL statements. If provided, replaces all user indexes.
                  If omitted, existing indexes are preserved.
 
     Returns:
         The collection data including:
+        - id: The collection's stable identifier
+        - name: The collection's display name
         - schema: User-defined fields only
         - indexes: User-defined indexes only
         - systemInfo: Object with system-managed fields and indexes (read-only)
 
     Example:
-        # Create or update a collection
+        # Create with stable ID for automations
         coll = ensure_collection(
-            "customers",
+            "Customer Orders Q1",
             schema=[
-                {"name": "title", "type": "text", "required": True},
-                {"name": "email", "type": "text"},
+                {"name": "amount", "type": "number", "required": True},
             ],
-            indexes=["CREATE INDEX idx_email ON customers (email)"]
+            id="orders",  # stable reference
         )
 
-        # Add a field (copy-modify-send pattern)
-        coll = get_collection("customers")
-        coll["schema"].append({"name": "phone", "type": "text"})
-        ensure_collection("customers", schema=coll["schema"])
+        # Later, rename collection but ID stays "orders"
+        # Automations using search("orders", ...) still work!
     """
     if not name or not name.strip():
         raise ValueError("name is required")
@@ -238,6 +242,9 @@ def ensure_collection(
     if collection_type:
         payload["type"] = collection_type
 
+    if id is not None and id.strip():
+        payload["id"] = id.strip()
+
     if schema is not _UNSET:
         if schema is None:
             raise ValueError("schema cannot be None; provide an iterable of fields or omit")

{lumera-0.9.4 → lumera-0.9.6}/lumera.egg-info/PKG-INFO

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

{lumera-0.9.4 → lumera-0.9.6}/lumera.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ lumera/__init__.py
 lumera/_utils.py
 lumera/automations.py
 lumera/exceptions.py
+lumera/files.py
 lumera/google.py
 lumera/llm.py
 lumera/locks.py

{lumera-0.9.4 → lumera-0.9.6}/pyproject.toml

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

{lumera-0.9.4 → lumera-0.9.6}/tests/test_sdk.py

@@ -196,7 +196,7 @@ def test_create_collection_uses_ensure(monkeypatch: pytest.MonkeyPatch) -> None:
 
     captured: dict[str, object] = {}
 
-    def fake_request(method: str, url: str, **kwargs: object) -> DummyResponse:
+    def fake_request(method: str, url: str, **_kwargs: object) -> DummyResponse:
         captured["method"] = method
         captured["url"] = url
         return DummyResponse(status_code=200, json_data={"id": "new"})