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

lumera/locks.py

@@ -0,0 +1,216 @@
+"""
+Lock management for preventing concurrent operations.
+
+Provides two types of locks:
+1. Record-level locks: Lock specific records (uses platform lm_locks table)
+2. Operation-level locks: Lock entire operations globally (requires custom collection)
+
+Available functions:
+    claim_record_locks()    - Lock specific records for processing
+    release_record_locks()  - Release previously claimed record locks
+    acquire_operation_lock() - Lock an entire operation (NOT YET IMPLEMENTED)
+    release_operation_lock() - Release operation lock (NOT YET IMPLEMENTED)
+    operation_lock()        - Context manager for operation locks (NOT YET IMPLEMENTED)
+
+Example:
+    >>> from lumera import locks
+    >>> result = locks.claim_record_locks("export", "deposits", ["dep_1", "dep_2"])
+    >>> for id in result["claimed"]:
+    ...     process(id)
+    >>> locks.release_record_locks("export", record_ids=result["claimed"])
+"""
+
+__all__ = [
+    "claim_record_locks",
+    "release_record_locks",
+    "acquire_operation_lock",
+    "release_operation_lock",
+    "operation_lock",
+]
+
+from contextlib import contextmanager
+from typing import Any, Iterator
+
+# Import platform lock primitives from the main SDK module
+from .sdk import claim_locks as _claim_locks
+from .sdk import release_locks as _release_locks
+
+
+def claim_record_locks(
+    job_type: str,
+    collection: str,
+    record_ids: list[str],
+    *,
+    ttl_seconds: int = 900,
+    job_id: str | None = None,
+) -> dict[str, Any]:
+    """Claim record-level locks (using platform lm_locks).
+
+    Prevents multiple workers from processing the same records concurrently.
+    Uses the platform's built-in lm_locks table.
+
+    Args:
+        job_type: Workflow name (e.g., "deposit_processing")
+        collection: Collection name
+        record_ids: List of record IDs to lock
+        ttl_seconds: Lock duration in seconds (default 900 = 15 minutes)
+        job_id: Optional job identifier for grouping locks
+
+    Returns:
+        {
+            "claimed": ["id1", "id2"],  # Successfully locked
+            "skipped": ["id3"],         # Already locked by another process
+            "ttl_seconds": 900
+        }
+
+    Example:
+        >>> result = claim_record_locks(
+        ...     job_type="export",
+        ...     collection="deposits",
+        ...     record_ids=["dep_1", "dep_2", "dep_3"]
+        ... )
+        >>> for dep_id in result["claimed"]:
+        ...     process(dep_id)
+        >>> # Release when done
+        >>> release_record_locks("export", record_ids=result["claimed"])
+    """
+    return _claim_locks(
+        job_type=job_type,
+        collection=collection,
+        record_ids=record_ids,
+        ttl_seconds=ttl_seconds,
+        job_id=job_id,
+    )
+
+
+def release_record_locks(
+    job_type: str,
+    *,
+    collection: str | None = None,
+    record_ids: list[str] | None = None,
+    job_id: str | None = None,
+) -> int:
+    """Release record-level locks.
+
+    Args:
+        job_type: Workflow name (required)
+        collection: Optional collection filter
+        record_ids: Optional specific records to release
+        job_id: Optional job identifier filter
+
+    Returns:
+        Number of locks released
+
+    Example:
+        >>> released = release_record_locks(
+        ...     job_type="export",
+        ...     record_ids=["dep_1", "dep_2"]
+        ... )
+        >>> print(f"Released {released} locks")
+    """
+    return _release_locks(
+        job_type=job_type, collection=collection, record_ids=record_ids, job_id=job_id
+    )
+
+
+# Operation-level locks (simple key-value locks)
+# Note: These would need a custom collection like "export_locks" to be implemented
+# For now, providing the interface that should be implemented
+
+
+def acquire_operation_lock(
+    lock_name: str, *, ttl_seconds: int = 600, wait: bool = False, wait_timeout: int = 30
+) -> bool:
+    """Acquire an operation-level lock.
+
+    For preventing concurrent execution of entire operations (like exports).
+    Uses a simple key-value lock, not tied to specific records.
+
+    Note: This requires a custom locks collection to be created.
+    See the Charter Impact export_locks collection as an example.
+
+    Args:
+        lock_name: Unique lock identifier (e.g., "csv_export")
+        ttl_seconds: Lock duration in seconds (default 600 = 10 minutes)
+        wait: If True, wait for lock to become available
+        wait_timeout: Max seconds to wait (if wait=True)
+
+    Returns:
+        True if lock acquired, False if already held (when wait=False)
+
+    Raises:
+        TimeoutError: If wait=True and timeout exceeded
+        NotImplementedError: If operation locks collection doesn't exist
+
+    Example:
+        >>> if acquire_operation_lock("csv_export"):
+        ...     try:
+        ...         perform_export()
+        ...     finally:
+        ...         release_operation_lock("csv_export")
+        ... else:
+        ...     print("Export already in progress")
+    """
+    raise NotImplementedError(
+        "Operation-level locks require a custom locks collection. "
+        "Create a collection like 'operation_locks' with fields: "
+        "lock_name (text, unique), held_by (text), acquired_at (date), expires_at (date). "
+        "Then implement acquire/release using pb.search/create/delete."
+    )
+
+
+def release_operation_lock(lock_name: str) -> bool:
+    """Release an operation-level lock.
+
+    Args:
+        lock_name: Lock identifier
+
+    Returns:
+        True if lock was released, False if wasn't held
+
+    Raises:
+        NotImplementedError: If operation locks collection doesn't exist
+
+    Example:
+        >>> release_operation_lock("csv_export")
+    """
+    raise NotImplementedError(
+        "Operation-level locks require a custom locks collection. "
+        "See acquire_operation_lock() for details."
+    )
+
+
+@contextmanager
+def operation_lock(
+    lock_name: str, *, ttl_seconds: int = 600, wait: bool = False, wait_timeout: int = 30
+) -> Iterator[None]:
+    """Context manager for operation locks.
+
+    Args:
+        lock_name: Lock identifier
+        ttl_seconds: Lock duration in seconds
+        wait: Wait for lock if held
+        wait_timeout: Max wait time in seconds
+
+    Raises:
+        NotImplementedError: If operation locks collection doesn't exist
+        TimeoutError: If wait=True and timeout exceeded
+
+    Example:
+        >>> with operation_lock("csv_export"):
+        ...     perform_export()
+        ...     # Lock automatically released on exit
+    """
+    # This would acquire the lock
+    acquired = acquire_operation_lock(
+        lock_name, ttl_seconds=ttl_seconds, wait=wait, wait_timeout=wait_timeout
+    )
+
+    if not acquired:
+        raise RuntimeError(f"Failed to acquire lock: {lock_name}")
+
+    try:
+        yield
+    finally:
+        # Always release the lock
+        release_operation_lock(lock_name)

lumera/pb.py

@@ -0,0 +1,316 @@
+"""
+Record operations for Lumera collections.
+
+This module provides a clean interface for working with Lumera collections,
+using the `pb.` namespace convention familiar from automation contexts.
+
+Available functions:
+    search()          - Query records with filters, pagination, sorting
+    get()             - Get single record by ID
+    get_by_external_id() - Get record by external_id field
+    create()          - Create new record
+    update()          - Update existing record
+    upsert()          - Create or update by external_id
+    delete()          - Delete record
+    iter_all()        - Iterate all matching records (auto-pagination)
+
+Filter Syntax:
+    Filters can be passed as dict or JSON string to search() and iter_all().
+
+    Simple equality:
+        {"status": "pending"}
+        {"external_id": "dep-001"}
+
+    Comparison operators (eq, gt, gte, lt, lte):
+        {"amount": {"gt": 1000}}
+        {"amount": {"gte": 100, "lte": 500}}
+
+    OR logic:
+        {"or": [{"status": "pending"}, {"status": "review"}]}
+
+    AND logic (implicit - multiple fields at same level):
+        {"status": "pending", "amount": {"gt": 1000}}
+
+    Combined:
+        {"status": "active", "or": [{"priority": "high"}, {"amount": {"gt": 5000}}]}
+
+Example:
+    >>> from lumera import pb
+    >>> results = pb.search("deposits", filter={"status": "pending"})
+    >>> deposit = pb.get("deposits", "rec_abc123")
+"""
+
+from typing import Any, Iterator, Mapping
+
+__all__ = [
+    "search",
+    "get",
+    "get_by_external_id",
+    "create",
+    "update",
+    "upsert",
+    "delete",
+    "iter_all",
+]
+
+# Import underlying SDK functions (prefixed with _ to indicate internal use)
+from .sdk import (
+    create_record as _create_record,
+)
+from .sdk import (
+    delete_record as _delete_record,
+)
+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_records as _list_records,
+)
+from .sdk import (
+    update_record as _update_record,
+)
+from .sdk import (
+    upsert_record as _upsert_record,
+)
+
+
+def search(
+    collection: str,
+    *,
+    filter: Mapping[str, Any] | str | None = None,
+    per_page: int = 50,
+    page: int = 1,
+    sort: str | None = None,
+    expand: str | None = None,
+) -> dict[str, Any]:
+    """Search records in a collection.
+
+    Args:
+        collection: Collection name or ID
+        filter: Filter as dict or JSON string. See module docstring for syntax.
+                Examples:
+                - {"status": "pending"} - equality
+                - {"amount": {"gt": 1000}} - comparison
+                - {"or": [{"status": "a"}, {"status": "b"}]} - OR logic
+        per_page: Results per page (max 500, default 50)
+        page: Page number, 1-indexed (default 1)
+        sort: Sort expression (e.g., "-created,name" for created DESC, name ASC)
+        expand: Comma-separated relation fields to expand (e.g., "user_id,company_id")
+
+    Returns:
+        Paginated results with structure:
+        {
+            "items": [...],      # List of records
+            "page": 1,
+            "perPage": 50,
+            "totalItems": 100,
+            "totalPages": 2
+        }
+
+    Example:
+        >>> results = pb.search("deposits",
+        ...     filter={"status": "pending", "amount": {"gt": 1000}},
+        ...     per_page=100,
+        ...     sort="-created"
+        ... )
+        >>> for deposit in results["items"]:
+        ...     print(deposit["id"], deposit["amount"])
+    """
+    # Note: _list_records handles both dict and str filters via JSON encoding
+    return _list_records(
+        collection,
+        filter=filter,
+        per_page=per_page,
+        page=page,
+        sort=sort,
+        expand=expand,
+    )
+
+
+def get(collection: str, record_id: str) -> dict[str, Any]:
+    """Get a single record by ID.
+
+    Args:
+        collection: Collection name or ID
+        record_id: Record ID (15-character alphanumeric ID)
+
+    Returns:
+        Record data with all fields
+
+    Raises:
+        LumeraAPIError: If record doesn't exist (404)
+
+    Example:
+        >>> deposit = pb.get("deposits", "dep_abc123")
+        >>> print(deposit["amount"])
+    """
+    return _get_record(collection, record_id)
+
+
+def get_by_external_id(collection: str, external_id: str) -> dict[str, Any]:
+    """Get a single record by external_id (unique field).
+
+    Args:
+        collection: Collection name or ID
+        external_id: Value of the external_id field (your business identifier)
+
+    Returns:
+        Record data
+
+    Raises:
+        LumeraAPIError: If no record with that external_id (404)
+
+    Example:
+        >>> deposit = pb.get_by_external_id("deposits", "dep-2024-001")
+    """
+    return _get_record_by_external_id(collection, external_id)
+
+
+def create(collection: str, data: dict[str, Any]) -> dict[str, Any]:
+    """Create a new record.
+
+    Args:
+        collection: Collection name or ID
+        data: Record data as dict mapping field names to values
+
+    Returns:
+        Created record with id, created, and updated timestamps
+
+    Raises:
+        LumeraAPIError: If validation fails or unique constraint violated
+
+    Example:
+        >>> deposit = pb.create("deposits", {
+        ...     "external_id": "dep-001",
+        ...     "amount": 1000,
+        ...     "status": "pending"
+        ... })
+        >>> print(deposit["id"])
+    """
+    return _create_record(collection, data)
+
+
+def update(collection: str, record_id: str, data: dict[str, Any]) -> dict[str, Any]:
+    """Update an existing record (partial update).
+
+    Args:
+        collection: Collection name or ID
+        record_id: Record ID to update
+        data: Fields to update (only include fields you want to change)
+
+    Returns:
+        Updated record
+
+    Raises:
+        LumeraAPIError: If record doesn't exist or validation fails
+
+    Example:
+        >>> deposit = pb.update("deposits", "dep_abc123", {
+        ...     "status": "processed",
+        ...     "processed_at": datetime.utcnow().isoformat()
+        ... })
+    """
+    return _update_record(collection, record_id, data)
+
+
+def upsert(collection: str, data: dict[str, Any]) -> dict[str, Any]:
+    """Create or update a record by external_id.
+
+    If a record with the given external_id exists, updates it.
+    Otherwise, creates a new record. This is useful for idempotent imports.
+
+    Args:
+        collection: Collection name or ID
+        data: Record data (MUST include "external_id" field)
+
+    Returns:
+        Created or updated record
+
+    Raises:
+        ValueError: If data doesn't contain "external_id"
+        LumeraAPIError: If validation fails
+
+    Example:
+        >>> deposit = pb.upsert("deposits", {
+        ...     "external_id": "dep-001",
+        ...     "amount": 1000,
+        ...     "status": "pending"
+        ... })
+        >>> # Second call updates the existing record
+        >>> deposit = pb.upsert("deposits", {
+        ...     "external_id": "dep-001",
+        ...     "amount": 2000
+        ... })
+    """
+    return _upsert_record(collection, data)
+
+
+def delete(collection: str, record_id: str) -> None:
+    """Delete a record.
+
+    Args:
+        collection: Collection name or ID
+        record_id: Record ID to delete
+
+    Raises:
+        LumeraAPIError: If record doesn't exist
+
+    Example:
+        >>> pb.delete("deposits", "dep_abc123")
+    """
+    _delete_record(collection, record_id)
+
+
+def iter_all(
+    collection: str,
+    *,
+    filter: Mapping[str, Any] | str | None = None,
+    sort: str | None = None,
+    expand: str | None = None,
+    batch_size: int = 500,
+) -> Iterator[dict[str, Any]]:
+    """Iterate over all matching records, handling pagination automatically.
+
+    This is a convenience function for processing large result sets without
+    manually handling pagination. Use this instead of manual page loops.
+
+    Args:
+        collection: Collection name or ID
+        filter: Optional filter as dict or JSON string (e.g., {"status": "pending"})
+        sort: Optional sort expression (e.g., "-created" for newest first)
+        expand: Optional comma-separated relation fields to expand
+        batch_size: Records per API request (max 500, default 500)
+
+    Yields:
+        Individual records
+
+    Example:
+        >>> for deposit in pb.iter_all("deposits", filter={"status": "pending"}):
+        ...     process(deposit)
+    """
+    page = 1
+    while True:
+        result = search(
+            collection,
+            filter=filter,
+            per_page=batch_size,
+            page=page,
+            sort=sort,
+            expand=expand,
+        )
+
+        items = result.get("items", [])
+        if not items:
+            break
+
+        yield from items
+
+        # Check if there are more pages
+        total_pages = result.get("totalPages", 0)
+        if page >= total_pages:
+            break
+
+        page += 1

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)