lumera 0.28.0.dev2__tar.gz → 0.31.0__tar.gz

{lumera-0.28.0.dev2 → lumera-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.28.0.dev2
+Version: 0.31.0
 Summary: SDK for building on Lumera platform
 Requires-Python: >=3.11
 Requires-Dist: requests
@@ -11,6 +11,13 @@ Requires-Dist: slack_sdk==3.35.0
 Provides-Extra: dev
 Requires-Dist: ruff; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pydantic<2.14.0,>=2.12.3; extra == "dev"
+Requires-Dist: jsonschema[format-nongpl]<5.0.0,>=4.25.0; extra == "dev"
+Provides-Extra: functions
+Requires-Dist: pydantic<2.14.0,>=2.12.3; extra == "functions"
+Requires-Dist: jsonschema[format-nongpl]<5.0.0,>=4.25.0; extra == "functions"
+Provides-Extra: release
+Requires-Dist: jsonschema[format-nongpl]<5.0.0,>=4.25.0; extra == "release"
 Provides-Extra: full
 Requires-Dist: airtable-python-wrapper==0.15.3; extra == "full"
 Requires-Dist: boto3==1.39.3; extra == "full"

{lumera-0.28.0.dev2 → lumera-0.31.0}/lumera/__init__.py

@@ -7,6 +7,26 @@ to interact with the Lumera API and define dynamic user interfaces.
 
 from importlib import import_module as _import_module
 from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # Keep the Functions authoring surface visible to static analyzers without
+    # eagerly importing it when users import the package root.
+    from .functions import (
+        ArtifactReference as ArtifactReference,
+    )
+    from .functions import (
+        FunctionContext as FunctionContext,
+    )
+    from .functions import (
+        FunctionError as FunctionError,
+    )
+    from .functions import (
+        HttpProjection as HttpProjection,
+    )
+    from .functions import (
+        function as function,
+    )
 
 try:
     __version__ = version("lumera")
@@ -89,6 +109,8 @@ _LAZY_MODULES = {
     "exceptions": ".exceptions",
     "files": ".files",
     "flags": ".flags",
+    "functions": ".functions",
+    "function_resources": ".function_resources",
     "integrations": ".integrations",
     "llm": ".llm",
     "pb": ".pb",
@@ -97,6 +119,8 @@ _LAZY_MODULES = {
     "webhooks": ".webhooks",
 }
 
+_FUNCTIONS_OPTIONAL_DEPENDENCIES = frozenset({"jsonschema", "pydantic", "pydantic_core"})
+
 _LAZY_ATTRIBUTES = {
     # ._utils
     "Credentials": ("._utils", "Credentials"),
@@ -124,6 +148,12 @@ _LAZY_ATTRIBUTES = {
     "feature_flag": (".flags", "feature_flag"),
     "feature_flags": (".flags", "feature_flags"),
     "is_feature_enabled": (".flags", "is_feature_enabled"),
+    # .functions
+    "ArtifactReference": (".functions", "ArtifactReference"),
+    "function": (".functions", "function"),
+    "FunctionContext": (".functions", "FunctionContext"),
+    "FunctionError": (".functions", "FunctionError"),
+    "HttpProjection": (".functions", "HttpProjection"),
     # .sdk
     "CollectionField": (".sdk", "CollectionField"),
     "HookReplayResult": (".sdk", "HookReplayResult"),
@@ -155,7 +185,20 @@ def __getattr__(name: str) -> object:
 
     module_name = _LAZY_MODULES.get(name)
     if module_name is not None:
-        value = _import_module(module_name, __name__)
+        try:
+            value = _import_module(module_name, __name__)
+        except ModuleNotFoundError as exc:
+            # ``functions`` is intentionally advertised for interactive
+            # discovery even though its authoring dependencies live behind an
+            # extra. Attribute-based discovery should be able to skip that
+            # optional module on a base install. Preserve every other import
+            # failure so broken installations are not mistaken for an absent
+            # optional feature.
+            if name == "functions" and exc.name in _FUNCTIONS_OPTIONAL_DEPENDENCIES:
+                raise AttributeError(
+                    f"module {__name__!r} has no available attribute {name!r}; {exc}"
+                ) from exc
+            raise
         globals()[name] = value
         return value
 

lumera-0.31.0/lumera/function_resources.py

@@ -0,0 +1,110 @@
+"""Client helpers for immutable project Function resources."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote
+
+from ._utils import _api_request
+
+
+def deploy_release(
+    project: str,
+    archive: str | Path,
+    *,
+    expected_digest: str | None = None,
+) -> dict[str, Any]:
+    """Upload and ingest a verified release without activating it."""
+
+    project_ref = _required_ref(project, "project")
+    archive_path = Path(archive).expanduser().resolve()
+    params = {"expected_digest": expected_digest} if expected_digest else None
+    with archive_path.open("rb") as stream:
+        payload = _api_request(
+            "POST",
+            f"projects/{quote(project_ref, safe='')}/runtime-releases",
+            params=params,
+            files={"release": (archive_path.name, stream, "application/gzip")},
+            timeout=600,
+        )
+    return _mapping(payload, "release deployment")
+
+
+def list_runtime_releases(
+    project: str, *, cursor: str | None = None, limit: int = 50
+) -> dict[str, Any]:
+    return _list("runtime-releases", project, cursor=cursor, limit=limit)
+
+
+def list_functions(project: str, *, cursor: str | None = None, limit: int = 50) -> dict[str, Any]:
+    return _list("functions", project, cursor=cursor, limit=limit)
+
+
+def get_function(project: str, function: str) -> dict[str, Any]:
+    project_ref = _required_ref(project, "project")
+    function_ref = _required_ref(function, "function")
+    payload = _api_request(
+        "GET",
+        f"projects/{quote(project_ref, safe='')}/functions/{quote(function_ref, safe='')}",
+    )
+    return _mapping(payload, "Function")
+
+
+def list_function_versions(
+    project: str,
+    function: str,
+    *,
+    cursor: str | None = None,
+    limit: int = 50,
+) -> dict[str, Any]:
+    project_ref = _required_ref(project, "project")
+    function_ref = _required_ref(function, "function")
+    payload = _api_request(
+        "GET",
+        f"projects/{quote(project_ref, safe='')}/functions/{quote(function_ref, safe='')}/versions",
+        params=_page_params(cursor, limit),
+    )
+    return _mapping(payload, "Function versions")
+
+
+def _list(kind: str, project: str, *, cursor: str | None, limit: int) -> dict[str, Any]:
+    project_ref = _required_ref(project, "project")
+    payload = _api_request(
+        "GET",
+        f"projects/{quote(project_ref, safe='')}/{kind}",
+        params=_page_params(cursor, limit),
+    )
+    return _mapping(payload, kind)
+
+
+def _page_params(cursor: str | None, limit: int) -> dict[str, object]:
+    if not 1 <= limit <= 100:
+        raise ValueError("limit must be between 1 and 100")
+    params: dict[str, object] = {"limit": limit}
+    if cursor:
+        params["cursor"] = cursor
+    return params
+
+
+def _required_ref(value: str, kind: str) -> str:
+    normalized = value.strip()
+    if not normalized:
+        raise ValueError(f"{kind} reference is required")
+    return normalized
+
+
+def _mapping(payload: object | None, kind: str) -> dict[str, Any]:
+    if not isinstance(payload, Mapping):
+        raise RuntimeError(f"Lumera returned an invalid {kind} response")
+    return dict(payload)
+
+
+__all__ = [
+    "deploy_release",
+    "get_function",
+    "list_function_versions",
+    "list_functions",
+    "list_runtime_releases",
+]

lumera-0.31.0/lumera/functions/__init__.py

@@ -0,0 +1,118 @@
+"""Typed Lumera Functions authoring and local-composition API."""
+
+# Keep the base SDK lightweight while making an accidental direct Functions
+# import fail with installation guidance instead of an opaque dependency name.
+try:
+    import jsonschema as _jsonschema
+    import pydantic as _pydantic
+    import pydantic_core as _pydantic_core
+except ModuleNotFoundError as exc:
+    if exc.name not in {"jsonschema", "pydantic", "pydantic_core"}:
+        raise
+    raise ModuleNotFoundError(
+        "Lumera Functions dependencies are not installed; "
+        "install them with `pip install 'lumera[functions]'`",
+        name=exc.name,
+    ) from exc
+else:
+    del _jsonschema, _pydantic, _pydantic_core
+
+from ._artifacts import ArtifactReference
+from ._context import (
+    ActorIdentity,
+    AgentIdentity,
+    CancellationToken,
+    FunctionCaller,
+    FunctionContext,
+    ScopedLumeraClient,
+    StructuredLogger,
+    TraceContext,
+)
+from ._contract import (
+    FUNCTION_MANIFEST_SCHEMA_VERSION,
+    FunctionDeclaration,
+    FunctionDefinition,
+    FunctionEffect,
+    FunctionManifest,
+    FunctionMetadata,
+    HttpProjection,
+    function,
+)
+from ._errors import (
+    DuplicateFunctionError,
+    DuplicateHttpProjectionError,
+    DurableTransportUnavailableError,
+    DurableWaitNotAllowedError,
+    FunctionCallModeError,
+    FunctionCancelledError,
+    FunctionCycleError,
+    FunctionDeadlineExceededError,
+    FunctionDefinitionError,
+    FunctionDepthExceededError,
+    FunctionDiscoveryError,
+    FunctionError,
+    FunctionInvocationError,
+    FunctionNotFoundError,
+    FunctionOutputSerializationError,
+    FunctionRuntimeClosedError,
+    FunctionsError,
+    FunctionValidationError,
+    InvalidDurableWaitError,
+    UnexpectedFunctionError,
+)
+from ._execution import (
+    DurableFunctionTransport,
+    ExecutionHandle,
+    ExecutionStatus,
+    StartedExecution,
+)
+from ._registry import FunctionRegistry, discover_modules
+from ._runtime import LocalFunctionRuntime, invoke_local
+
+__all__ = [
+    "ActorIdentity",
+    "AgentIdentity",
+    "ArtifactReference",
+    "CancellationToken",
+    "DuplicateFunctionError",
+    "DuplicateHttpProjectionError",
+    "DurableFunctionTransport",
+    "DurableTransportUnavailableError",
+    "DurableWaitNotAllowedError",
+    "ExecutionHandle",
+    "ExecutionStatus",
+    "FUNCTION_MANIFEST_SCHEMA_VERSION",
+    "FunctionCallModeError",
+    "FunctionCaller",
+    "FunctionCancelledError",
+    "FunctionContext",
+    "FunctionCycleError",
+    "FunctionDeadlineExceededError",
+    "FunctionDeclaration",
+    "FunctionDefinition",
+    "FunctionDefinitionError",
+    "FunctionDepthExceededError",
+    "FunctionDiscoveryError",
+    "FunctionEffect",
+    "FunctionError",
+    "FunctionInvocationError",
+    "FunctionManifest",
+    "FunctionMetadata",
+    "FunctionNotFoundError",
+    "FunctionOutputSerializationError",
+    "FunctionRegistry",
+    "FunctionRuntimeClosedError",
+    "FunctionsError",
+    "FunctionValidationError",
+    "HttpProjection",
+    "InvalidDurableWaitError",
+    "LocalFunctionRuntime",
+    "ScopedLumeraClient",
+    "StartedExecution",
+    "StructuredLogger",
+    "TraceContext",
+    "UnexpectedFunctionError",
+    "discover_modules",
+    "function",
+    "invoke_local",
+]

lumera-0.31.0/lumera/functions/__main__.py

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

lumera-0.31.0/lumera/functions/_artifacts.py

@@ -0,0 +1,52 @@
+"""Transport-neutral artifact references for Function boundaries."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ArtifactReference(BaseModel):
+    """An opaque, non-authoritative reference to a Lumera-managed artifact.
+
+    Function payloads carry this JSON-safe envelope across local, API, durable,
+    and sharing boundaries. Runtime adapters are responsible for authorizing
+    and materializing the referenced artifact. Local paths, object-store keys,
+    URLs, and credentials are deliberately absent from the contract.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    kind: Literal["lumera_artifact"]
+    artifact_id: str = Field(
+        min_length=1,
+        max_length=512,
+        pattern=r"^\S+$",
+        description="Opaque Lumera artifact identifier",
+    )
+    filename: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=1024,
+        description="Non-authoritative display filename",
+    )
+    content_type: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=255,
+        description="Non-authoritative media type",
+    )
+    size_bytes: int | None = Field(
+        default=None,
+        ge=0,
+        description="Non-authoritative byte size",
+    )
+    sha256: str | None = Field(
+        default=None,
+        pattern=r"^[0-9a-f]{64}$",
+        description="Optional lowercase SHA-256 content digest",
+    )
+
+
+__all__ = ["ArtifactReference"]

lumera-0.31.0/lumera/functions/_config.py

@@ -0,0 +1,110 @@
+"""Local project configuration for explicit Function module discovery."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import tomllib
+
+from ._errors import FunctionDiscoveryError
+
+_MODULE_PATTERN = re.compile(r"^[A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*$")
+
+
+@dataclass(frozen=True)
+class FunctionProjectConfig:
+    """Resolved ``[tool.lumera.functions]`` configuration."""
+
+    project_root: Path
+    source_root: Path
+    modules: tuple[str, ...]
+    test_paths: tuple[Path, ...]
+
+
+def load_project_config(
+    project_root: str | Path,
+    *,
+    module_overrides: list[str] | None = None,
+) -> FunctionProjectConfig:
+    root = Path(project_root).expanduser().resolve()
+    if not root.is_dir():
+        raise FunctionDiscoveryError(f"project root is not a directory: {root}")
+    config_path = root / "pyproject.toml"
+    if not config_path.is_file():
+        raise FunctionDiscoveryError(f"missing {config_path}; configure [tool.lumera.functions]")
+    try:
+        document = tomllib.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise FunctionDiscoveryError(f"could not read {config_path}") from exc
+
+    raw_config = _functions_config(document)
+    raw_source_root = raw_config.get("source-root", "platform")
+    if not isinstance(raw_source_root, str) or not raw_source_root.strip():
+        raise FunctionDiscoveryError("tool.lumera.functions.source-root must be a path")
+    source_root = (root / raw_source_root).resolve()
+    if not source_root.is_relative_to(root):
+        raise FunctionDiscoveryError("Function source-root must stay inside the project")
+    if not source_root.is_dir():
+        raise FunctionDiscoveryError(f"Function source-root does not exist: {source_root}")
+
+    raw_modules: Any = module_overrides if module_overrides else raw_config.get("modules", [])
+    if not isinstance(raw_modules, list) or not all(
+        isinstance(module, str) for module in raw_modules
+    ):
+        raise FunctionDiscoveryError("tool.lumera.functions.modules must be a string array")
+    modules: list[str] = []
+    for raw_module in raw_modules:
+        module = raw_module.strip()
+        if not module or not _MODULE_PATTERN.fullmatch(module):
+            raise FunctionDiscoveryError(f"invalid Function module name: {raw_module!r}")
+        _require_project_module(module, source_root)
+        if module not in modules:
+            modules.append(module)
+
+    raw_test_paths = raw_config.get("test-paths", ["tests/functions"])
+    if not isinstance(raw_test_paths, list) or not all(
+        isinstance(path, str) for path in raw_test_paths
+    ):
+        raise FunctionDiscoveryError("tool.lumera.functions.test-paths must be a string array")
+    test_paths: list[Path] = []
+    for raw_path in raw_test_paths:
+        test_path = (root / raw_path).resolve()
+        if not test_path.is_relative_to(root):
+            raise FunctionDiscoveryError("Function test paths must stay inside the project")
+        test_paths.append(test_path)
+
+    return FunctionProjectConfig(
+        project_root=root,
+        source_root=source_root,
+        modules=tuple(modules),
+        test_paths=tuple(test_paths),
+    )
+
+
+def _functions_config(document: dict[str, Any]) -> dict[str, Any]:
+    value: Any = document
+    for key in ("tool", "lumera", "functions"):
+        if not isinstance(value, dict):
+            return {}
+        value = value.get(key, {})
+    if not isinstance(value, dict):
+        raise FunctionDiscoveryError("tool.lumera.functions must be a TOML table")
+    return value
+
+
+def _require_project_module(module: str, source_root: Path) -> None:
+    """Require an explicit module to resolve to Python source under source-root."""
+
+    relative_module = Path(*module.split("."))
+    candidates = (
+        (source_root / relative_module).with_suffix(".py"),
+        source_root / relative_module / "__init__.py",
+    )
+    for candidate in candidates:
+        resolved = candidate.resolve()
+        if resolved.is_relative_to(source_root) and resolved.is_file():
+            return
+    raise FunctionDiscoveryError(f"Function module must resolve inside source-root: {module!r}")