lumera 0.5.1__py3-none-any.whl → 0.5.3__py3-none-any.whl

lumera/pb.py

@@ -1,10 +1,10 @@
 """
-Record operations for Lumera collections.
+Record and collection operations for Lumera.
 
 This module provides a clean interface for working with Lumera collections,
 using the `pb.` namespace convention familiar from automation contexts.
 
-Available functions:
+Record functions:
     search()          - Query records with filters, pagination, sorting
     get()             - Get single record by ID
     get_by_external_id() - Get record by external_id field
@@ -14,6 +14,14 @@ Available functions:
     delete()          - Delete record
     iter_all()        - Iterate all matching records (auto-pagination)
 
+Collection functions:
+    list_collections()    - List all collections
+    get_collection()      - Get collection by name
+    ensure_collection()   - Create or update collection (idempotent)
+    create_collection()   - Create new collection
+    update_collection()   - Update collection schema
+    delete_collection()   - Delete collection
+
 Filter Syntax:
     Filters can be passed as dict or JSON string to search() and iter_all().
 
@@ -40,9 +48,10 @@ Example:
     >>> deposit = pb.get("deposits", "rec_abc123")
 """
 
-from typing import Any, Iterator, Mapping
+from typing import Any, Iterator, Mapping, Sequence
 
 __all__ = [
+    # Record operations
     "search",
     "get",
     "get_by_external_id",
@@ -51,24 +60,47 @@ __all__ = [
     "upsert",
     "delete",
     "iter_all",
+    # Collection operations
+    "list_collections",
+    "get_collection",
+    "ensure_collection",
+    "create_collection",
+    "update_collection",
+    "delete_collection",
 ]
 
 # Import underlying SDK functions (prefixed with _ to indicate internal use)
+from .exceptions import LumeraAPIError
+from .sdk import (
+    create_collection as _create_collection,
+)
 from .sdk import (
     create_record as _create_record,
 )
+from .sdk import (
+    delete_collection as _delete_collection,
+)
 from .sdk import (
     delete_record as _delete_record,
 )
+from .sdk import (
+    get_collection as _get_collection,
+)
 from .sdk import (
     get_record as _get_record,
 )
 from .sdk import (
     get_record_by_external_id as _get_record_by_external_id,
 )
+from .sdk import (
+    list_collections as _list_collections,
+)
 from .sdk import (
     list_records as _list_records,
 )
+from .sdk import (
+    update_collection as _update_collection,
+)
 from .sdk import (
     update_record as _update_record,
 )
@@ -314,3 +346,173 @@ def iter_all(
             break
 
         page += 1
+
+
+# =============================================================================
+# Collection Management Functions
+# =============================================================================
+
+
+def list_collections() -> list[dict[str, Any]]:
+    """List all collections.
+
+    Returns:
+        List of collection objects with id, name, schema, etc.
+
+    Example:
+        >>> collections = pb.list_collections()
+        >>> for col in collections:
+        ...     print(col["name"])
+    """
+    result = _list_collections()
+    return result.get("items", [])
+
+
+def get_collection(name: str) -> dict[str, Any] | None:
+    """Get a collection by name.
+
+    Args:
+        name: Collection name
+
+    Returns:
+        Collection object if found, None if not found
+
+    Example:
+        >>> col = pb.get_collection("deposits")
+        >>> if col:
+        ...     print(col["schema"])
+    """
+    try:
+        return _get_collection(name)
+    except LumeraAPIError as e:
+        if e.status_code == 404:
+            return None
+        raise
+
+
+def create_collection(
+    name: str,
+    schema: Sequence[dict[str, Any]],
+    *,
+    indexes: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Create a new collection.
+
+    Args:
+        name: Collection name (must not start with '_')
+        schema: List of field definitions. Each field is a dict with:
+            - name: Field name (required)
+            - type: Field type (required): text, number, bool, date, json,
+                    relation, select, editor, lumera_file
+            - required: Whether field is required (default False)
+            - options: Type-specific options (e.g., collectionId for relations)
+        indexes: Optional list of index definitions
+
+    Returns:
+        Created collection object
+
+    Example:
+        >>> col = pb.create_collection("deposits", [
+        ...     {"name": "amount", "type": "number", "required": True},
+        ...     {"name": "status", "type": "text"},
+        ...     {"name": "account_id", "type": "relation",
+        ...      "options": {"collectionId": "accounts"}}
+        ... ])
+    """
+    return _create_collection(name, schema=schema, indexes=indexes)
+
+
+def update_collection(
+    name: str,
+    schema: Sequence[dict[str, Any]],
+    *,
+    indexes: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Update a collection's schema.
+
+    Args:
+        name: Collection name
+        schema: New schema (replaces existing user fields)
+        indexes: Optional new indexes
+
+    Returns:
+        Updated collection object
+
+    Example:
+        >>> col = pb.update_collection("deposits", [
+        ...     {"name": "amount", "type": "number", "required": True},
+        ...     {"name": "status", "type": "text"},
+        ...     {"name": "notes", "type": "text"}  # New field
+        ... ])
+    """
+    return _update_collection(name, schema=schema, indexes=indexes)
+
+
+def delete_collection(name: str) -> None:
+    """Delete a collection.
+
+    Args:
+        name: Collection name to delete
+
+    Raises:
+        LumeraAPIError: If collection doesn't exist or is protected
+
+    Example:
+        >>> pb.delete_collection("old_deposits")
+    """
+    _delete_collection(name)
+
+
+def ensure_collection(
+    name: str,
+    schema: Sequence[dict[str, Any]],
+    *,
+    update_schema: bool = False,
+    indexes: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Ensure a collection exists with the given schema (idempotent).
+
+    This is the recommended way to set up collections in automation scripts.
+    Safe to call multiple times - will not fail if collection already exists.
+
+    Args:
+        name: Collection name
+        schema: List of field definitions
+        update_schema: If True, update existing collection's schema.
+                      If False (default), leave existing collection unchanged.
+        indexes: Optional list of index definitions
+
+    Returns:
+        Collection object (created, updated, or existing)
+
+    Behavior:
+        - Collection doesn't exist → create it
+        - Collection exists, update_schema=False → return existing (no-op)
+        - Collection exists, update_schema=True → update schema
+
+    Example:
+        >>> # Safe to run multiple times
+        >>> col = pb.ensure_collection("deposits", [
+        ...     {"name": "amount", "type": "number", "required": True},
+        ...     {"name": "status", "type": "text"},
+        ... ])
+        >>>
+        >>> # Update schema if collection exists
+        >>> col = pb.ensure_collection("deposits", [
+        ...     {"name": "amount", "type": "number", "required": True},
+        ...     {"name": "status", "type": "text"},
+        ...     {"name": "notes", "type": "text"},  # Add new field
+        ... ], update_schema=True)
+    """
+    existing = get_collection(name)
+
+    if existing is None:
+        # Collection doesn't exist, create it
+        return create_collection(name, schema, indexes=indexes)
+
+    if update_schema:
+        # Update existing collection's schema
+        return update_collection(name, schema, indexes=indexes)
+
+    # Collection exists and update_schema=False, return as-is
+    return existing

lumera/sdk.py

@@ -268,15 +268,15 @@ 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 filter string (e.g.
-            ``"status = 'ok'"``) or a structured filter encoded as a mapping/
-            sequence. Structured filters mirror the Page Builder helpers, e.g.:
+        filter: Filter as dict (JSON object). String filters are NOT supported.
+            Use dict syntax with optional comparison operators:
 
-            * ``{"and": [{"status": {"eq": "active"}}, {"owner_id": user_id}]}``
-            * ``{"or": [{"created": {"gt": "2024-01-01"}}, {"stage": "new"}]}``
+            * Simple equality: ``{"status": "pending"}``
+            * Comparison: ``{"amount": {"gt": 1000}}`` (gt, gte, lt, lte, eq)
+            * OR logic: ``{"or": [{"status": "a"}, {"status": "b"}]}``
+            * AND (implicit): ``{"status": "active", "amount": {"gt": 100}}``
 
-            The SDK JSON-encodes structured filters so the API can build
-            tenant-aware expressions automatically.
+            The SDK JSON-encodes the filter for the API.
         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"``

{lumera-0.5.1.dist-info → lumera-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.5.1
+Version: 0.5.3
 Summary: SDK for building on Lumera platform
 Requires-Python: >=3.11
 Requires-Dist: requests
@@ -26,7 +26,7 @@ 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"
-Requires-Dist: pydantic==2.11.7; extra == "full"
+Requires-Dist: pydantic<3.0.0,>=2.12.3; extra == "full"
 Requires-Dist: PyGithub==2.6.1; extra == "full"
 Requires-Dist: python-dotenv==1.1.0; extra == "full"
 Requires-Dist: pyzmq; extra == "full"

{lumera-0.5.1.dist-info → lumera-0.5.3.dist-info}/RECORD

@@ -4,10 +4,10 @@ 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/pb.py,sha256=E8TRw7mQ9i0vpmC46azwT7O7EP2w7w4O5ZgcrQyInyI,14915
+lumera/sdk.py,sha256=6Vw0f5MX-yjmy7KBZzEYNdjtXk2P4Oxibpa_UpcM7bs,26859
 lumera/storage.py,sha256=kQQJYVRnxcpDZQ_gB2iZy6anb3hyZN7b8a_oNuE2yYE,8191
-lumera-0.5.1.dist-info/METADATA,sha256=TpymAeIKBpQKRYq_lPAHZPfgb3g61L_fGgBG-W_A_1w,1604
-lumera-0.5.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lumera-0.5.1.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
-lumera-0.5.1.dist-info/RECORD,,
+lumera-0.5.3.dist-info/METADATA,sha256=6aLRahUomaWUUSfqSzj2_8fwTSLt08nW3BrERVVnf-Q,1611
+lumera-0.5.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lumera-0.5.3.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
+lumera-0.5.3.dist-info/RECORD,,