lumera 0.27.0__tar.gz → 0.28.0.dev1__tar.gz

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

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.27.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.27.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 (
@@ -63,11 +65,11 @@ from .sdk import (
     get_record_by_external_id,
     list_collections,
     list_records,
-    search_records,
     query_sql,
     replay_hook,
     run_automation,
     save_to_lumera,
+    search_records,
     update_automation_run,
     update_collection,
     update_record,
@@ -89,6 +91,8 @@ __all__ = [
     "feature_flag",
     "feature_flags",
     "is_feature_enabled",
+    # Callable Function authoring
+    "function",
     # Collections (low-level API)
     "list_collections",
     "get_collection",
@@ -133,6 +137,7 @@ __all__ = [
     "storage",
     "llm",
     "exceptions",
+    "functions",
     "webhooks",
     "integrations",
 ]

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

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

@@ -0,0 +1,382 @@
+"""Local authoring and invocation primitives for Lumera Functions."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import json
+import re
+from collections.abc import Awaitable, Callable, Mapping, Sequence
+from copy import deepcopy
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, ParamSpec, TypeVar, cast, get_type_hints
+
+from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError, create_model
+from pydantic_core import PydanticSerializationError
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+FUNCTION_MANIFEST_SCHEMA_VERSION = 1
+FUNCTION_METADATA_ATTRIBUTE = "__lumera_function__"
+
+_FUNCTION_ID_PATTERN = re.compile(r"^[a-z][a-z0-9]*(?:[._:-][a-z0-9]+)*$")
+_FUNCTIONS: dict[str, FunctionDefinition] = {}
+
+
+class FunctionEffect(str, Enum):
+    """The externally visible effect category of a Function."""
+
+    READ = "read"
+    WRITE = "write"
+    EXTERNAL_WRITE = "external_write"
+
+
+class FunctionConfirmation(str, Enum):
+    """The confirmation policy requested when a Function is projected as a tool."""
+
+    NEVER = "never"
+    REQUIRED_FOR_AGENTS = "required_for_agents"
+    ALWAYS = "always"
+
+
+class FunctionError(Exception):
+    """Base class for local Function definition and invocation errors."""
+
+
+class FunctionDefinitionError(FunctionError):
+    """Raised when a decorated Function does not define a valid contract."""
+
+
+class DuplicateFunctionError(FunctionDefinitionError):
+    """Raised when two callables export the same stable Function ID."""
+
+
+class FunctionDiscoveryError(FunctionError):
+    """Raised when an explicitly configured Function module cannot be imported."""
+
+
+class FunctionNotFoundError(FunctionError):
+    """Raised when a caller asks for an unknown Function ID."""
+
+
+class FunctionValidationError(FunctionError):
+    """Raised when Function input or output does not satisfy its declared schema."""
+
+    def __init__(
+        self,
+        function_id: str,
+        phase: str,
+        validation_error: ValidationError,
+    ) -> None:
+        self.function_id = function_id
+        self.phase = phase
+        self.details = cast(
+            list[dict[str, Any]],
+            json.loads(validation_error.json(include_url=False)),
+        )
+        super().__init__(f"{phase} validation failed for Function {function_id!r}")
+
+
+class FunctionExecutionError(FunctionError):
+    """Raised when user Function code fails during a runner invocation."""
+
+    def __init__(self, function_id: str, cause: Exception) -> None:
+        self.function_id = function_id
+        self.cause_type = type(cause).__name__
+        super().__init__(f"Function {function_id!r} failed: {cause}")
+
+
+class FunctionOutputSerializationError(FunctionError):
+    """Raised when a validated Function result cannot be encoded as JSON."""
+
+    def __init__(self, function_id: str, cause: Exception) -> None:
+        self.function_id = function_id
+        self.cause_type = type(cause).__name__
+        super().__init__(f"Function {function_id!r} returned a non-JSON result: {cause}")
+
+
+@dataclass(frozen=True)
+class FunctionMetadata:
+    """Serializable metadata derived from a decorated Python callable."""
+
+    id: str
+    description: str
+    effect: FunctionEffect
+    confirmation: FunctionConfirmation
+    module: str
+    qualname: str
+    input_schema: dict[str, Any]
+    output_schema: dict[str, Any]
+    is_async: bool
+
+    def to_manifest_entry(self) -> dict[str, Any]:
+        """Return a detached JSON-serializable manifest entry."""
+
+        return {
+            "id": self.id,
+            "description": self.description,
+            "effect": self.effect.value,
+            "confirmation": self.confirmation.value,
+            "module": self.module,
+            "qualname": self.qualname,
+            "input_schema": deepcopy(self.input_schema),
+            "output_schema": deepcopy(self.output_schema),
+            "is_async": self.is_async,
+        }
+
+
+@dataclass(frozen=True)
+class FunctionDefinition:
+    """Runtime definition used to validate and invoke an exported Function."""
+
+    metadata: FunctionMetadata
+    callable: Callable[..., Any]
+    input_model: type[BaseModel]
+    output_adapter: TypeAdapter[Any]
+
+    async def invoke(self, inputs: Mapping[str, Any]) -> object:
+        """Validate JSON-compatible input, invoke the callable, and validate output."""
+
+        try:
+            validated_input = self.input_model.model_validate(dict(inputs))
+        except ValidationError as exc:
+            raise FunctionValidationError(self.metadata.id, "input", exc) from exc
+
+        kwargs = {
+            parameter_name: getattr(validated_input, parameter_name)
+            for parameter_name in self.input_model.model_fields
+        }
+        try:
+            result = self.callable(**kwargs)
+            if inspect.isawaitable(result):
+                result = await cast(Awaitable[Any], result)
+        except Exception as exc:
+            raise FunctionExecutionError(self.metadata.id, exc) from exc
+
+        try:
+            validated_output = self.output_adapter.validate_python(result)
+        except ValidationError as exc:
+            raise FunctionValidationError(self.metadata.id, "output", exc) from exc
+        try:
+            return json.loads(self.output_adapter.dump_json(validated_output))
+        except PydanticSerializationError as exc:
+            raise FunctionOutputSerializationError(self.metadata.id, exc) from exc
+
+
+def function(
+    *,
+    id: str,
+    description: str | None = None,
+    effect: FunctionEffect | str = FunctionEffect.READ,
+    confirmation: FunctionConfirmation | str | None = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Mark an ordinary Python callable as an externally callable Lumera Function."""
+
+    def decorate(callable_: Callable[P, R]) -> Callable[P, R]:
+        definition = _build_definition(
+            callable_,
+            function_id=id,
+            description=description,
+            effect=effect,
+            confirmation=confirmation,
+        )
+        _register(definition)
+        setattr(callable_, FUNCTION_METADATA_ATTRIBUTE, definition.metadata)
+        return callable_
+
+    return decorate
+
+
+def discover_modules(module_names: Sequence[str]) -> tuple[FunctionDefinition, ...]:
+    """Import explicit Function modules and return all registered definitions."""
+
+    if not module_names:
+        raise FunctionDiscoveryError("at least one Function module is required")
+    for raw_module_name in module_names:
+        module_name = raw_module_name.strip()
+        if not module_name:
+            raise FunctionDiscoveryError("Function module names cannot be empty")
+        try:
+            importlib.import_module(module_name)
+        except FunctionError:
+            raise
+        except Exception as exc:
+            raise FunctionDiscoveryError(
+                f"failed to import Function module {module_name!r}: {exc}"
+            ) from exc
+    return list_function_definitions()
+
+
+def list_function_definitions() -> tuple[FunctionDefinition, ...]:
+    """Return registered Function definitions sorted by stable ID."""
+
+    return tuple(_FUNCTIONS[function_id] for function_id in sorted(_FUNCTIONS))
+
+
+def get_function_definition(function_id: str) -> FunctionDefinition:
+    """Return one registered Function definition by stable ID."""
+
+    try:
+        return _FUNCTIONS[function_id]
+    except KeyError as exc:
+        raise FunctionNotFoundError(f"Function {function_id!r} is not registered") from exc
+
+
+def build_manifest() -> dict[str, Any]:
+    """Build the deterministic local registry artifact."""
+
+    return {
+        "schema_version": FUNCTION_MANIFEST_SCHEMA_VERSION,
+        "functions": [
+            definition.metadata.to_manifest_entry() for definition in list_function_definitions()
+        ],
+    }
+
+
+async def invoke_function(function_id: str, inputs: Mapping[str, Any]) -> object:
+    """Invoke one registered Function through its typed remote-call boundary."""
+
+    return await get_function_definition(function_id).invoke(inputs)
+
+
+def _build_definition(
+    callable_: Callable[..., Any],
+    *,
+    function_id: str,
+    description: str | None,
+    effect: FunctionEffect | str,
+    confirmation: FunctionConfirmation | str | None,
+) -> FunctionDefinition:
+    normalized_id = _validate_function_id(function_id)
+    normalized_effect = _enum_value(FunctionEffect, effect, "effect")
+    normalized_confirmation = _confirmation_value(confirmation, normalized_effect)
+    normalized_description = (description or inspect.getdoc(callable_) or "").strip()
+    if not normalized_description:
+        raise FunctionDefinitionError(
+            f"Function {normalized_id!r} requires a description or docstring"
+        )
+
+    signature = inspect.signature(callable_)
+    try:
+        type_hints = get_type_hints(callable_, include_extras=True)
+    except Exception as exc:
+        raise FunctionDefinitionError(
+            f"could not resolve annotations for Function {normalized_id!r}: {exc}"
+        ) from exc
+
+    fields: dict[str, tuple[Any, Any]] = {}
+    for parameter_name, parameter in signature.parameters.items():
+        if parameter.kind in {
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        }:
+            raise FunctionDefinitionError(
+                f"Function {normalized_id!r} parameter {parameter_name!r} "
+                "must be addressable as a named JSON field"
+            )
+        annotation = type_hints.get(parameter_name, parameter.annotation)
+        if annotation is inspect.Parameter.empty:
+            raise FunctionDefinitionError(
+                f"Function {normalized_id!r} parameter {parameter_name!r} "
+                "requires a type annotation"
+            )
+        default = ... if parameter.default is inspect.Parameter.empty else parameter.default
+        fields[parameter_name] = (annotation, default)
+
+    return_annotation = type_hints.get("return", signature.return_annotation)
+    if return_annotation is inspect.Signature.empty:
+        raise FunctionDefinitionError(
+            f"Function {normalized_id!r} requires a return type annotation"
+        )
+
+    model_name = "_LumeraInput_" + re.sub(r"[^a-zA-Z0-9_]", "_", normalized_id)
+    try:
+        input_model = create_model(
+            model_name,
+            __config__=ConfigDict(extra="forbid"),
+            **fields,
+        )
+        output_adapter = TypeAdapter(return_annotation)
+        input_schema = input_model.model_json_schema()
+        output_schema = output_adapter.json_schema()
+    except Exception as exc:
+        raise FunctionDefinitionError(
+            f"could not build schemas for Function {normalized_id!r}: {exc}"
+        ) from exc
+
+    metadata = FunctionMetadata(
+        id=normalized_id,
+        description=normalized_description,
+        effect=normalized_effect,
+        confirmation=normalized_confirmation,
+        module=callable_.__module__,
+        qualname=callable_.__qualname__,
+        input_schema=input_schema,
+        output_schema=output_schema,
+        is_async=inspect.iscoroutinefunction(callable_),
+    )
+    return FunctionDefinition(
+        metadata=metadata,
+        callable=callable_,
+        input_model=input_model,
+        output_adapter=output_adapter,
+    )
+
+
+def _validate_function_id(function_id: str) -> str:
+    normalized_id = function_id.strip()
+    if not _FUNCTION_ID_PATTERN.fullmatch(normalized_id):
+        raise FunctionDefinitionError(
+            "Function IDs must start with a lowercase letter and contain only "
+            "lowercase letters, numbers, '.', '_', ':', or '-' separated by "
+            f"alphanumeric segments; got {function_id!r}"
+        )
+    return normalized_id
+
+
+def _enum_value(
+    enum_type: type[FunctionEffect],
+    value: FunctionEffect | str,
+    field_name: str,
+) -> FunctionEffect:
+    try:
+        return enum_type(value)
+    except ValueError as exc:
+        allowed = ", ".join(item.value for item in enum_type)
+        raise FunctionDefinitionError(
+            f"invalid Function {field_name} {value!r}; expected one of: {allowed}"
+        ) from exc
+
+
+def _confirmation_value(
+    value: FunctionConfirmation | str | None,
+    effect: FunctionEffect,
+) -> FunctionConfirmation:
+    if value is None:
+        if effect is FunctionEffect.READ:
+            return FunctionConfirmation.NEVER
+        return FunctionConfirmation.REQUIRED_FOR_AGENTS
+    try:
+        return FunctionConfirmation(value)
+    except ValueError as exc:
+        allowed = ", ".join(item.value for item in FunctionConfirmation)
+        raise FunctionDefinitionError(
+            f"invalid Function confirmation {value!r}; expected one of: {allowed}"
+        ) from exc
+
+
+def _register(definition: FunctionDefinition) -> None:
+    existing = _FUNCTIONS.get(definition.metadata.id)
+    if existing is not None:
+        raise DuplicateFunctionError(
+            f"Function ID {definition.metadata.id!r} is already exported by "
+            f"{existing.metadata.module}.{existing.metadata.qualname}"
+        )
+    _FUNCTIONS[definition.metadata.id] = definition
+
+
+def _clear_registry_for_testing() -> None:
+    _FUNCTIONS.clear()