lumera 0.28.0.dev1__tar.gz → 0.29.0__tar.gz

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

@@ -1,17 +1,21 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.28.0.dev1
+Version: 0.29.0
 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
 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: full
 Requires-Dist: airtable-python-wrapper==0.15.3; extra == "full"
 Requires-Dist: boto3==1.39.3; extra == "full"
@@ -29,6 +33,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<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.29.0/lumera/__init__.py

@@ -0,0 +1,217 @@
+"""
+Lumera Agent SDK
+
+This SDK provides helpers for automations running within the Lumera environment
+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")
+except PackageNotFoundError:
+    __version__ = "unknown"  # Not installed (e.g. running from source)
+
+# Define what ``from lumera import *`` imports. Keep this list stable: callers
+# have historically imported these modules, helpers, types, and exceptions from
+# the package root.
+__all__ = [
+    # Authentication & utilities
+    "Credentials",
+    "get_access_token",
+    "get_credentials",
+    "get_google_access_token",  # Kept for backwards compatibility
+    "list_integration_connections",
+    "list_integrations",
+    "log_timed",
+    # Feature flags (read the sandbox snapshot)
+    "feature_flag",
+    "feature_flags",
+    "is_feature_enabled",
+    # Collections (low-level API)
+    "list_collections",
+    "get_collection",
+    "create_collection",
+    "update_collection",
+    "delete_collection",
+    # Records (low-level API)
+    "list_records",
+    "search_records",
+    "get_record",
+    "get_record_by_external_id",
+    "create_record",
+    "update_record",
+    "upsert_record",
+    "delete_record",
+    # Other operations
+    "replay_hook",
+    "query_sql",
+    "run_automation",
+    "get_automation_run",
+    "update_automation_run",
+    "upload_lumera_file",
+    "save_to_lumera",
+    # Type definitions
+    "CollectionField",
+    "HookReplayResult",
+    "LumeraFile",
+    "LumeraFiles",
+    # Exceptions
+    "LumeraAPIError",
+    "RecordNotUniqueError",
+    "IntegrationNotEnabledForProjectError",
+    "LumeraError",
+    "ValidationError",
+    "UniqueConstraintError",
+    "RecordNotFoundError",
+    # High-level modules (use as lumera.pb, lumera.storage, etc.)
+    "agents",
+    "automations",
+    "email",
+    "pb",
+    "storage",
+    "llm",
+    "exceptions",
+    "webhooks",
+    "integrations",
+]
+
+# Importing the package root used to import every SDK module, including all
+# feature-specific integration clients. Resolve the same public API on first
+# access so existing import statements retain their behavior without paying
+# that cost when the corresponding feature is unused.
+_LAZY_MODULES = {
+    "_utils": "._utils",
+    "agents": ".agents",
+    "automations": ".automations",
+    "email": ".email",
+    "exceptions": ".exceptions",
+    "files": ".files",
+    "flags": ".flags",
+    "functions": ".functions",
+    "integrations": ".integrations",
+    "llm": ".llm",
+    "pb": ".pb",
+    "sdk": ".sdk",
+    "storage": ".storage",
+    "webhooks": ".webhooks",
+}
+
+_FUNCTIONS_OPTIONAL_DEPENDENCIES = frozenset({"jsonschema", "pydantic", "pydantic_core"})
+
+_LAZY_ATTRIBUTES = {
+    # ._utils
+    "Credentials": ("._utils", "Credentials"),
+    "IntegrationNotEnabledForProjectError": (
+        "._utils",
+        "IntegrationNotEnabledForProjectError",
+    ),
+    "LumeraAPIError": ("._utils", "LumeraAPIError"),
+    "RecordNotUniqueError": ("._utils", "RecordNotUniqueError"),
+    "get_access_token": ("._utils", "get_access_token"),
+    "get_credentials": ("._utils", "get_credentials"),
+    "get_google_access_token": ("._utils", "get_google_access_token"),
+    "list_integration_connections": ("._utils", "list_integration_connections"),
+    "list_integrations": ("._utils", "list_integrations"),
+    "log_timed": ("._utils", "log_timed"),
+    # .exceptions
+    "LumeraError": (".exceptions", "LumeraError"),
+    "RecordNotFoundError": (".exceptions", "RecordNotFoundError"),
+    "UniqueConstraintError": (".exceptions", "UniqueConstraintError"),
+    "ValidationError": (".exceptions", "ValidationError"),
+    # .files
+    "LumeraFile": (".files", "LumeraFile"),
+    "LumeraFiles": (".files", "LumeraFiles"),
+    # .flags
+    "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"),
+    "create_collection": (".sdk", "create_collection"),
+    "create_record": (".sdk", "create_record"),
+    "delete_collection": (".sdk", "delete_collection"),
+    "delete_record": (".sdk", "delete_record"),
+    "get_automation_run": (".sdk", "get_automation_run"),
+    "get_collection": (".sdk", "get_collection"),
+    "get_record": (".sdk", "get_record"),
+    "get_record_by_external_id": (".sdk", "get_record_by_external_id"),
+    "list_collections": (".sdk", "list_collections"),
+    "list_records": (".sdk", "list_records"),
+    "query_sql": (".sdk", "query_sql"),
+    "replay_hook": (".sdk", "replay_hook"),
+    "run_automation": (".sdk", "run_automation"),
+    "save_to_lumera": (".sdk", "save_to_lumera"),
+    "search_records": (".sdk", "search_records"),
+    "update_automation_run": (".sdk", "update_automation_run"),
+    "update_collection": (".sdk", "update_collection"),
+    "update_record": (".sdk", "update_record"),
+    "upload_lumera_file": (".sdk", "upload_lumera_file"),
+    "upsert_record": (".sdk", "upsert_record"),
+}
+
+
+def __getattr__(name: str) -> object:
+    """Load a root SDK export the first time it is requested."""
+
+    module_name = _LAZY_MODULES.get(name)
+    if module_name is not None:
+        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
+
+    attribute = _LAZY_ATTRIBUTES.get(name)
+    if attribute is not None:
+        module_name, attribute_name = attribute
+        value = getattr(_import_module(module_name, __name__), attribute_name)
+        globals()[name] = value
+        return value
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Include lazily available exports in interactive discovery."""
+
+    return sorted(set(globals()) | set(__all__) | set(_LAZY_MODULES))

lumera-0.29.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.29.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.29.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.29.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}")