lumera 0.28.0.dev1__py3-none-any.whl → 0.28.0.dev2__py3-none-any.whl

lumera/__init__.py

@@ -5,79 +5,17 @@ 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
 
 try:
     __version__ = version("lumera")
 except PackageNotFoundError:
-    __version__ = "unknown"  # Not installed (e.g., running from source)
+    __version__ = "unknown"  # Not installed (e.g. running from source)
 
-# Import new modules (as modules, not individual functions)
-from . import (
-    agents,
-    automations,
-    email,
-    exceptions,
-    functions,
-    integrations,
-    llm,
-    pb,
-    storage,
-    webhooks,
-)
-from ._utils import (
-    Credentials,
-    IntegrationNotEnabledForProjectError,
-    LumeraAPIError,
-    RecordNotUniqueError,
-    get_access_token,
-    get_credentials,
-    get_google_access_token,
-    list_integration_connections,
-    list_integrations,
-    log_timed,
-)
-
-# Import specific exceptions for convenience
-from .exceptions import (
-    LumeraError,
-    RecordNotFoundError,
-    UniqueConstraintError,
-    ValidationError,
-)
-
-# 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 (
-    CollectionField,
-    HookReplayResult,
-    create_collection,
-    create_record,
-    delete_collection,
-    delete_record,
-    get_automation_run,
-    get_collection,
-    get_record,
-    get_record_by_external_id,
-    list_collections,
-    list_records,
-    query_sql,
-    replay_hook,
-    run_automation,
-    save_to_lumera,
-    search_records,
-    update_automation_run,
-    update_collection,
-    update_record,
-    upload_lumera_file,
-    upsert_record,
-)
-
-# Define what `from lumera import *` imports.
+# 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",
@@ -91,8 +29,6 @@ __all__ = [
     "feature_flag",
     "feature_flags",
     "is_feature_enabled",
-    # Callable Function authoring
-    "function",
     # Collections (low-level API)
     "list_collections",
     "get_collection",
@@ -129,7 +65,7 @@ __all__ = [
     "ValidationError",
     "UniqueConstraintError",
     "RecordNotFoundError",
-    # New modules (use as lumera.pb, lumera.storage, etc.)
+    # High-level modules (use as lumera.pb, lumera.storage, etc.)
     "agents",
     "automations",
     "email",
@@ -137,7 +73,103 @@ __all__ = [
     "storage",
     "llm",
     "exceptions",
-    "functions",
     "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",
+    "integrations": ".integrations",
+    "llm": ".llm",
+    "pb": ".pb",
+    "sdk": ".sdk",
+    "storage": ".storage",
+    "webhooks": ".webhooks",
+}
+
+_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"),
+    # .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:
+        value = _import_module(module_name, __name__)
+        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/integrations/netsuite.py

@@ -3,9 +3,9 @@ Lumera NetSuite Integration
 
 Provides two NetSuite clients:
 
-* :class:`NetSuiteProxyClient` is recommended for new code. It routes requests
-  through Lumera's integration proxy, so NetSuite credentials stay inside the
-  Lumera backend.
+* :class:`NetSuiteProxyClient` is recommended for new code. It routes SuiteQL,
+  REST records, and RESTlets through Lumera's integration proxy, so NetSuite
+  credentials stay inside the Lumera backend.
 * :class:`NetSuiteClient` preserves the existing direct-call behavior for
   backward compatibility. It downloads the NetSuite access token into the
   automation process and calls SuiteTalk directly.
@@ -99,6 +99,10 @@ def _base_url(account_id: str) -> str:
     return f"https://{account_id.lower()}.suitetalk.api.netsuite.com"
 
 
+def _restlet_base_url(account_id: str) -> str:
+    return f"https://{account_id.lower()}.restlets.api.netsuite.com"
+
+
 def _fetch_account_id(api_name: str) -> str:
     """Resolve the NetSuite account ID from connection metadata (no secrets)."""
     cached = _account_id_cache.get(api_name)
@@ -417,6 +421,39 @@ class NetSuiteProxyClient:
             timeout=self._timeout,
         )
 
+    def call_restlet(
+        self,
+        script_id: str | int,
+        deployment_id: str | int,
+        *,
+        method: str = "POST",
+        body: dict[str, Any] | list[Any] | str | None = None,
+        headers: dict[str, str] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> requests.Response:
+        """Call a deployed RESTlet through Lumera's integration proxy.
+
+        RESTlet access must first be enabled for the NetSuite connection in
+        Lumera. The raw response is returned so callers can handle each
+        RESTlet's custom response format.
+        """
+        query: dict[str, Any] = {
+            "script": script_id,
+            "deploy": deployment_id,
+        }
+        for key, value in (params or {}).items():
+            if key not in query:
+                query[key] = value
+        url = f"{_restlet_base_url(self.account_id)}/app/site/hosting/restlet.nl?{urlencode(query)}"
+        return _proxy_request(
+            self._api_name,
+            method.upper(),
+            url,
+            body=body,
+            headers=headers,
+            timeout=self._timeout,
+        )
+
     # ── SuiteQL ──────────────────────────────────────────────────────────
 
     def suiteql(

{lumera-0.28.0.dev1.dist-info → lumera-0.28.0.dev2.dist-info}/METADATA

@@ -1,12 +1,11 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.28.0.dev1
+Version: 0.28.0.dev2
 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
@@ -29,6 +28,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.28.0.dev1.dist-info → lumera-0.28.0.dev2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-lumera/__init__.py,sha256=ednyPgTBleMeFC9Zi8YLv8qjRXGbTFCOS5iEYaR2qvo,3312
+lumera/__init__.py,sha256=-KrO86tPsjRGUn0FVyxGCnOcTR74DkQupocVE4eQjzA,5860
 lumera/_live.py,sha256=OAB0gQIeALdDf5QZjIA6jtXl11f8cYpJv_FcEUcKGWI,31707
 lumera/_utils.py,sha256=OoNJh0K-Wqze_m6234LMN3tvzV6znteHa4bXX7mxUI0,42498
 lumera/agents.py,sha256=MTKaRoBtWIVCH-_Km0yg4ZX8GlNaVXPMfdHLE3cr2vo,20720
@@ -13,18 +13,13 @@ lumera/pb.py,sha256=jlAxWoxvt0iBlHmK-ugSwn3SOpLSkTST3qc13-VFXh8,22053
 lumera/sdk.py,sha256=ZmoZ6h3ndMmHRiww4hg96zLOfhCiE1Tk8HhlGq82PGU,30481
 lumera/storage.py,sha256=kmkRmpmc1CfA--2Y5rJvKTHEv5VIAXFyWMeajr-mUwM,10305
 lumera/webhooks.py,sha256=0glrf_9UwPcF1g-h-uJwr_TEM0v0OdCNg7Kd2svbvvo,9419
-lumera/functions/__init__.py,sha256=nekNrs-MDSuOdRC4X2R9lIj9N0GxxB5h86bVIOaULcQ,1378
-lumera/functions/__main__.py,sha256=RNkrl16scYCPi5aKEOTYZ1d5s1_Fwp8kl6pqhvPHYEM,111
-lumera/functions/_bundle.py,sha256=CqZX8vQHAv23jC3thF4FvESBsA-_U9GTXCg3_p0XaS8,5719
-lumera/functions/_core.py,sha256=1qEw2FocZXu1960NOefHYQVdpJ7LAt90R1xqvePTwRs,13228
-lumera/functions/_runner.py,sha256=p0At9oHzCWReefAXHL_bXHtN5IsLOSlu9z8gx7K8k-0,5224
 lumera/integrations/__init__.py,sha256=PFUEtmJyMYRJla_a_kXSdWqKUvoD-C4y04gDtjXAQcc,2418
 lumera/integrations/bill.py,sha256=FWRCVu9JP7Wm4dilCbga6hG4e2pVfnIj6omWiAUKc-k,4298
 lumera/integrations/google.py,sha256=QkbBbbDh3I_OToPDFqcivU6sWy2UieHBxZ_TPv5rqK0,11862
-lumera/integrations/netsuite.py,sha256=QLHU4rbm4I_1TpWMVDwyeTDLDQcHd7Z_ZRib0M7-ys0,16225
+lumera/integrations/netsuite.py,sha256=acbwP_NwKFnX46h39-_oJ9EOUQbDdsBVWDBqXsLVeTc,17503
 lumera/integrations/salesforce.py,sha256=THn8YHW4FBWuhCoyNsGnLtfHM_JaUGPM1ylFF2z819g,1915
 lumera/integrations/slack.py,sha256=iHmb1Ryc7E5CRb7Kqb-UoZvhNGICpdRu3FzXCDh-jt4,3471
-lumera-0.28.0.dev1.dist-info/METADATA,sha256=r4LazrF3gKajgfEUDBP8jVwEPhAr4G1PltQwDtU85jg,1674
-lumera-0.28.0.dev1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-lumera-0.28.0.dev1.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
-lumera-0.28.0.dev1.dist-info/RECORD,,
+lumera-0.28.0.dev2.dist-info/METADATA,sha256=SEeFf40VTfJJgy8BF9eACPZq_fhtd_eg0u03SAgGFHM,1691
+lumera-0.28.0.dev2.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+lumera-0.28.0.dev2.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
+lumera-0.28.0.dev2.dist-info/RECORD,,

lumera/functions/__init__.py

@@ -1,55 +0,0 @@
-"""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/functions/__main__.py

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

lumera/functions/_bundle.py

@@ -1,194 +0,0 @@
-"""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/functions/_core.py

@@ -1,382 +0,0 @@
-"""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()

lumera/functions/_runner.py

@@ -1,163 +0,0 @@
-"""Machine-readable local runner for discovered Lumera Functions."""
-
-from __future__ import annotations
-
-import argparse
-import asyncio
-import json
-import sys
-from collections.abc import Sequence
-from contextlib import redirect_stdout
-from typing import Any
-
-from ._bundle import build_bundle
-from ._core import (
-    FunctionDefinitionError,
-    FunctionDiscoveryError,
-    FunctionExecutionError,
-    FunctionNotFoundError,
-    FunctionOutputSerializationError,
-    FunctionValidationError,
-    build_manifest,
-    discover_modules,
-    invoke_function,
-)
-
-
-def main(argv: Sequence[str] | None = None) -> int:
-    """Run the local Function protocol and emit exactly one JSON result envelope."""
-
-    parser = _build_parser()
-    try:
-        args = parser.parse_args(argv)
-        with redirect_stdout(sys.stderr):
-            if args.command == "bundle":
-                bundle = build_bundle(args.project_root, args.modules, args.output)
-                payload = {"ok": True, "bundle": bundle.to_dict()}
-            else:
-                discover_modules(args.modules)
-            if args.command == "list":
-                payload = {"ok": True, "manifest": build_manifest()}
-            elif args.command == "invoke":
-                inputs = _load_inputs(args.input)
-                result = asyncio.run(invoke_function(args.function_id, inputs))
-                payload = {
-                    "ok": True,
-                    "function_id": args.function_id,
-                    "result": result,
-                }
-    except FunctionValidationError as exc:
-        payload = _error_payload(
-            f"{exc.phase}_validation_error",
-            str(exc),
-            details=exc.details,
-            function_id=exc.function_id,
-        )
-    except FunctionNotFoundError as exc:
-        payload = _error_payload("function_not_found", str(exc))
-    except FunctionExecutionError as exc:
-        payload = _error_payload(
-            "function_execution_error",
-            str(exc),
-            function_id=exc.function_id,
-            cause_type=exc.cause_type,
-        )
-    except FunctionOutputSerializationError as exc:
-        payload = _error_payload(
-            "output_serialization_error",
-            str(exc),
-            function_id=exc.function_id,
-            cause_type=exc.cause_type,
-        )
-    except FunctionDiscoveryError as exc:
-        payload = _error_payload("function_discovery_error", str(exc))
-    except FunctionDefinitionError as exc:
-        payload = _error_payload("function_definition_error", str(exc))
-    except (json.JSONDecodeError, ValueError) as exc:
-        payload = _error_payload("invalid_input_json", str(exc))
-    except Exception as exc:
-        payload = _error_payload(
-            "runner_error",
-            str(exc),
-            cause_type=type(exc).__name__,
-        )
-
-    _emit(payload)
-    return 0 if payload["ok"] else 1
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = _ProtocolArgumentParser(prog="python -m lumera.functions")
-    subparsers = parser.add_subparsers(dest="command", required=True)
-
-    list_parser = subparsers.add_parser("list", help="discover and list Function metadata")
-    _add_modules_argument(list_parser)
-
-    invoke_parser = subparsers.add_parser("invoke", help="invoke one discovered Function")
-    _add_modules_argument(invoke_parser)
-    invoke_parser.add_argument("--function-id", required=True)
-    invoke_parser.add_argument(
-        "--input",
-        help="JSON object input; when omitted, read the JSON object from stdin",
-    )
-
-    bundle_parser = subparsers.add_parser(
-        "bundle",
-        help="build a deterministic deployment bundle",
-    )
-    _add_modules_argument(bundle_parser)
-    bundle_parser.add_argument(
-        "--project-root",
-        required=True,
-        help="root containing Function source packages",
-    )
-    bundle_parser.add_argument(
-        "--output",
-        required=True,
-        help="output path for the .tar.gz bundle",
-    )
-    return parser
-
-
-class _ProtocolArgumentParser(argparse.ArgumentParser):
-    def error(self, message: str) -> None:
-        raise ValueError(message)
-
-
-def _add_modules_argument(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument(
-        "--module",
-        dest="modules",
-        action="append",
-        required=True,
-        help="explicit import path containing decorated Functions; may be repeated",
-    )
-
-
-def _load_inputs(raw_input: str | None) -> dict[str, Any]:
-    if raw_input is None:
-        raw_input = sys.stdin.read()
-    if not raw_input.strip():
-        raw_input = "{}"
-    decoded = json.loads(raw_input)
-    if not isinstance(decoded, dict):
-        raise ValueError("Function input must be a JSON object")
-    return decoded
-
-
-def _error_payload(error_type: str, message: str, **extra: object) -> dict[str, Any]:
-    error: dict[str, object] = {"type": error_type, "message": message}
-    error.update(extra)
-    return {"ok": False, "error": error}
-
-
-def _emit(payload: dict[str, Any]) -> None:
-    sys.stdout.write(
-        json.dumps(
-            payload,
-            ensure_ascii=False,
-            separators=(",", ":"),
-            sort_keys=True,
-        )
-        + "\n"
-    )