lumera 0.26.0__tar.gz → 0.28.0.dev1__tar.gz

{lumera-0.26.0 → lumera-0.28.0.dev1}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.26.0
+Version: 0.28.0.dev1
 Summary: SDK for building on Lumera platform
 Requires-Python: >=3.11
 Requires-Dist: requests
 Requires-Dist: python-dotenv
 Requires-Dist: google-api-python-client==2.173.0
+Requires-Dist: pydantic<3.0.0,>=2.12.3
 Requires-Dist: simple-salesforce==1.12.6
 Requires-Dist: slack_sdk==3.35.0
 Provides-Extra: dev
@@ -28,7 +29,6 @@ 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<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.26.0 → lumera-0.28.0.dev1}/lumera/__init__.py

@@ -18,6 +18,7 @@ from . import (
     automations,
     email,
     exceptions,
+    functions,
     integrations,
     llm,
     pb,
@@ -48,6 +49,7 @@ from .exceptions import (
 # Import file types for Pydantic automation inputs
 from .files import LumeraFile, LumeraFiles
 from .flags import feature_flag, feature_flags, is_feature_enabled
+from .functions import function
 
 # Import key SDK helpers to expose them at the package root.
 from .sdk import (
@@ -67,6 +69,7 @@ from .sdk import (
     replay_hook,
     run_automation,
     save_to_lumera,
+    search_records,
     update_automation_run,
     update_collection,
     update_record,
@@ -88,6 +91,8 @@ __all__ = [
     "feature_flag",
     "feature_flags",
     "is_feature_enabled",
+    # Callable Function authoring
+    "function",
     # Collections (low-level API)
     "list_collections",
     "get_collection",
@@ -96,6 +101,7 @@ __all__ = [
     "delete_collection",
     # Records (low-level API)
     "list_records",
+    "search_records",
     "get_record",
     "get_record_by_external_id",
     "create_record",
@@ -131,6 +137,7 @@ __all__ = [
     "storage",
     "llm",
     "exceptions",
+    "functions",
     "webhooks",
     "integrations",
 ]

{lumera-0.26.0 → lumera-0.28.0.dev1}/lumera/_utils.py

@@ -20,12 +20,18 @@ from dotenv import load_dotenv
 
 TOKEN_ENV = "LUMERA_TOKEN"
 BASE_URL_ENV = "LUMERA_BASE_URL"
+CREDENTIALS_PATH_ENV = "LUMERA_CREDENTIALS_PATH"
 EXPECTED_TEST_ERROR_ENV = "LUMERA_EXPECTED_TEST_ERROR"
 EXPECTED_TEST_HEADER = "X-Lumera-Expected-Test"
 ENV_PATH = "/root/.env"
 LOCAL_CREDS_PATH = ".lumera/credentials.json"
 GLOBAL_CREDS_PATH = os.path.join(os.path.expanduser("~"), ".config", "lumera", "credentials.json")
 
+
+def _credentials_paths() -> tuple[str, ...]:
+    explicit = os.getenv(CREDENTIALS_PATH_ENV, "").strip()
+    return tuple(dict.fromkeys(path for path in (explicit, LOCAL_CREDS_PATH, GLOBAL_CREDS_PATH) if path))
+
 load_dotenv(override=False)
 load_dotenv(ENV_PATH, override=False)
 
@@ -37,7 +43,7 @@ def _resolve_api_base() -> str:
 
     Priority:
     1. LUMERA_BASE_URL environment variable
-    2. base_url from credentials file (project-local then global)
+    2. base_url from credentials file (explicit runtime, project-local, global)
     3. Default (https://app.lumerahq.com/api)
     """
     # 1. Environment variable
@@ -47,7 +53,7 @@ def _resolve_api_base() -> str:
         return base if base.endswith("/api") else base + "/api"
 
     # 2. Credentials file
-    for path in (LOCAL_CREDS_PATH, GLOBAL_CREDS_PATH):
+    for path in _credentials_paths():
         try:
             if os.path.exists(path):
                 with open(path) as f:
@@ -112,30 +118,27 @@ def get_lumera_token() -> str:
 
     Priority:
     1. LUMERA_TOKEN environment variable
-    2. .lumera/credentials.json (project-local, from CLI login --local)
-    3. ~/.config/lumera/credentials.json (global, from CLI login)
-    4. /root/.env (legacy, for automations in sandbox)
+    2. LUMERA_CREDENTIALS_PATH (sandbox runtime credentials)
+    3. .lumera/credentials.json (project-local, from CLI login --local)
+    4. ~/.config/lumera/credentials.json (global, from CLI login)
+    5. /root/.env (legacy, for automations in sandbox)
     """
     # 1. Check environment variable (highest priority)
     token = os.getenv(TOKEN_ENV)
     if token:
         return token
 
-    # 2. Check project-local credentials
-    token = _read_token_from_creds_file(LOCAL_CREDS_PATH)
-    if token:
-        return token
-
-    # 3. Check global credentials
-    token = _read_token_from_creds_file(GLOBAL_CREDS_PATH)
-    if token:
-        return token
+    # 2-4. Check explicit runtime, project-local, then global credentials.
+    for path in _credentials_paths():
+        token = _read_token_from_creds_file(path)
+        if token:
+            return token
 
-    # 4. /root/.env is already loaded via dotenv at module load time
+    # 5. /root/.env is already loaded via dotenv at module load time
     # so if we get here, no token was found anywhere
     raise RuntimeError(
-        f"{TOKEN_ENV} not found. Checked: environment, {LOCAL_CREDS_PATH}, "
-        f"{GLOBAL_CREDS_PATH}, {ENV_PATH}. "
+        f"{TOKEN_ENV} not found. Checked: environment, {_credentials_paths()}, "
+        f"{ENV_PATH}. "
         f"Run `lumera login` to authenticate."
     )
 

{lumera-0.26.0 → lumera-0.28.0.dev1}/lumera/flags.py

@@ -4,7 +4,7 @@ Feature flags inside Lumera sandboxes.
 The Lumera backend resolves the company's feature flags at sandbox warm and
 writes a typed JSON snapshot to a well-known path (pointed to by the
 ``LUMERA_FEATURE_FLAGS_PATH`` env var, default
-``/opt/lumera/feature-flags/flags.json``).
+``/lumera_state/feature-flags/flags.json``).
 This module reads that snapshot so sandbox code can gate behavior on a flag.
 
 Values are stored in their native type (booleans, numbers, JSON objects), so
@@ -35,7 +35,7 @@ _logger = logging.getLogger("lumera.sdk")
 
 # Keep in sync with backend sandboximage.FeatureFlagsPath / FeatureFlagsPathEnv.
 _ENV_PATH = "LUMERA_FEATURE_FLAGS_PATH"
-_DEFAULT_PATH = "/opt/lumera/feature-flags/flags.json"
+_DEFAULT_PATH = "/lumera_state/feature-flags/flags.json"
 
 _lock = threading.Lock()
 # Cache entry: (cache_key, flags). cache_key is (path, mtime_ns) so a refreshed

lumera-0.28.0.dev1/lumera/functions/__init__.py

@@ -0,0 +1,55 @@
+"""Define, discover, inspect, and locally invoke typed Lumera Functions."""
+
+from ._bundle import (
+    FUNCTION_BUNDLE_FORMAT_VERSION,
+    FUNCTION_BUNDLE_RUNTIME,
+    FunctionBundle,
+    build_bundle,
+)
+from ._core import (
+    FUNCTION_MANIFEST_SCHEMA_VERSION,
+    DuplicateFunctionError,
+    FunctionConfirmation,
+    FunctionDefinition,
+    FunctionDefinitionError,
+    FunctionDiscoveryError,
+    FunctionEffect,
+    FunctionError,
+    FunctionExecutionError,
+    FunctionMetadata,
+    FunctionNotFoundError,
+    FunctionOutputSerializationError,
+    FunctionValidationError,
+    build_manifest,
+    discover_modules,
+    function,
+    get_function_definition,
+    invoke_function,
+    list_function_definitions,
+)
+
+__all__ = [
+    "FUNCTION_BUNDLE_FORMAT_VERSION",
+    "FUNCTION_BUNDLE_RUNTIME",
+    "FUNCTION_MANIFEST_SCHEMA_VERSION",
+    "DuplicateFunctionError",
+    "FunctionConfirmation",
+    "FunctionDefinition",
+    "FunctionDefinitionError",
+    "FunctionDiscoveryError",
+    "FunctionEffect",
+    "FunctionError",
+    "FunctionExecutionError",
+    "FunctionBundle",
+    "FunctionMetadata",
+    "FunctionNotFoundError",
+    "FunctionOutputSerializationError",
+    "FunctionValidationError",
+    "build_manifest",
+    "build_bundle",
+    "discover_modules",
+    "function",
+    "get_function_definition",
+    "invoke_function",
+    "list_function_definitions",
+]

lumera-0.28.0.dev1/lumera/functions/__main__.py

@@ -0,0 +1,5 @@
+"""CLI entry point for ``python -m lumera.functions``."""
+
+from ._runner import main
+
+raise SystemExit(main())

lumera-0.28.0.dev1/lumera/functions/_bundle.py

@@ -0,0 +1,194 @@
+"""Build immutable, deterministic deployment bundles for Lumera Functions."""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import io
+import json
+import os
+import sys
+import tarfile
+from collections.abc import Iterator, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from ._core import build_manifest, discover_modules
+
+FUNCTION_BUNDLE_FORMAT_VERSION = 1
+FUNCTION_BUNDLE_RUNTIME = "python3.13"
+
+_SOURCE_FILENAMES = {
+    "pyproject.toml",
+    "requirements.txt",
+    "requirements.lock",
+    "uv.lock",
+}
+_EXCLUDED_DIRECTORY_NAMES = {
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "__pycache__",
+    "node_modules",
+}
+
+
+@dataclass(frozen=True)
+class FunctionBundle:
+    """Metadata for one built Function deployment bundle."""
+
+    path: Path
+    sha256: str
+    size_bytes: int
+    manifest: dict[str, Any]
+    modules: tuple[str, ...]
+    source_files: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable build result."""
+
+        return {
+            "path": str(self.path),
+            "sha256": self.sha256,
+            "size_bytes": self.size_bytes,
+            "manifest": self.manifest,
+            "modules": list(self.modules),
+            "source_files": list(self.source_files),
+        }
+
+
+def build_bundle(
+    project_root: str | os.PathLike[str],
+    module_names: Sequence[str],
+    output_path: str | os.PathLike[str],
+) -> FunctionBundle:
+    """Build a deterministic ``tar.gz`` containing source and Function metadata."""
+
+    root = Path(project_root).expanduser().resolve()
+    if not root.is_dir():
+        raise ValueError(f"Function project root is not a directory: {root}")
+
+    modules = _normalize_modules(module_names)
+    output = Path(output_path).expanduser().resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    with _prepend_sys_path(root):
+        discover_modules(modules)
+        manifest = build_manifest()
+
+    source_entries = _collect_source_entries(root)
+    manifest_bytes = _canonical_json_bytes(manifest)
+    build_metadata = {
+        "format_version": FUNCTION_BUNDLE_FORMAT_VERSION,
+        "runtime": FUNCTION_BUNDLE_RUNTIME,
+        "modules": list(modules),
+        "manifest_sha256": hashlib.sha256(manifest_bytes).hexdigest(),
+        "source_files": [
+            {
+                "path": relative_path,
+                "sha256": hashlib.sha256(content).hexdigest(),
+                "size_bytes": len(content),
+            }
+            for relative_path, content in source_entries
+        ],
+    }
+
+    archive_bytes = _build_archive(
+        manifest_bytes=manifest_bytes,
+        build_bytes=_canonical_json_bytes(build_metadata),
+        source_entries=source_entries,
+    )
+    output.write_bytes(archive_bytes)
+
+    return FunctionBundle(
+        path=output,
+        sha256=hashlib.sha256(archive_bytes).hexdigest(),
+        size_bytes=len(archive_bytes),
+        manifest=manifest,
+        modules=modules,
+        source_files=tuple(relative_path for relative_path, _ in source_entries),
+    )
+
+
+def _normalize_modules(module_names: Sequence[str]) -> tuple[str, ...]:
+    modules = tuple(dict.fromkeys(name.strip() for name in module_names if name.strip()))
+    if not modules:
+        raise ValueError("at least one Function module is required")
+    return modules
+
+
+def _collect_source_entries(root: Path) -> list[tuple[str, bytes]]:
+    entries: list[tuple[str, bytes]] = []
+    for candidate in sorted(root.rglob("*")):
+        relative = candidate.relative_to(root)
+        if any(part in _EXCLUDED_DIRECTORY_NAMES for part in relative.parts):
+            continue
+        if candidate.is_symlink() or not candidate.is_file():
+            continue
+        if candidate.suffix != ".py" and candidate.name not in _SOURCE_FILENAMES:
+            continue
+        relative_path = PurePosixPath(*relative.parts).as_posix()
+        entries.append((relative_path, candidate.read_bytes()))
+    if not entries:
+        raise ValueError(f"Function project contains no Python source files: {root}")
+    return entries
+
+
+def _build_archive(
+    *,
+    manifest_bytes: bytes,
+    build_bytes: bytes,
+    source_entries: Sequence[tuple[str, bytes]],
+) -> bytes:
+    tar_buffer = io.BytesIO()
+    with tarfile.open(fileobj=tar_buffer, mode="w", format=tarfile.PAX_FORMAT) as archive:
+        _add_tar_file(archive, "manifest.json", manifest_bytes)
+        _add_tar_file(archive, "build.json", build_bytes)
+        for relative_path, content in source_entries:
+            _add_tar_file(archive, f"source/{relative_path}", content)
+
+    gzip_buffer = io.BytesIO()
+    with gzip.GzipFile(fileobj=gzip_buffer, mode="wb", filename="", mtime=0) as compressed:
+        compressed.write(tar_buffer.getvalue())
+    return gzip_buffer.getvalue()
+
+
+def _add_tar_file(archive: tarfile.TarFile, name: str, content: bytes) -> None:
+    info = tarfile.TarInfo(name)
+    info.size = len(content)
+    info.mode = 0o644
+    info.mtime = 0
+    info.uid = 0
+    info.gid = 0
+    info.uname = ""
+    info.gname = ""
+    archive.addfile(info, io.BytesIO(content))
+
+
+def _canonical_json_bytes(value: object) -> bytes:
+    return (
+        json.dumps(
+            value,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        )
+        + "\n"
+    ).encode()
+
+
+@contextmanager
+def _prepend_sys_path(root: Path) -> Iterator[None]:
+    root_value = str(root)
+    sys.path.insert(0, root_value)
+    try:
+        yield
+    finally:
+        try:
+            sys.path.remove(root_value)
+        except ValueError:
+            pass