imperal-sdk 5.2.1__tar.gz → 5.2.2__tar.gz

{imperal_sdk-5.2.1 → imperal_sdk-5.2.2}/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 5.2.2 — 2026-06-11 — Import-light package root
+
+Performance / robustness release. **Zero API changes** — every public name,
+submodule attribute, star-import and `dir()` entry resolves exactly as before
+(verified by an eager-parity test over the whole surface).
+
+### Changed
+
+- **The package root is now import-light (PEP 562 lazy surface).**
+  `import imperal_sdk` — and importing transport-free helpers such as
+  `imperal_sdk.chat.filters` or `imperal_sdk.chat.error_codes` — no longer
+  loads the HTTP client stack. Heavy dependencies load on first use of the
+  names that actually need them (`Context`, the service clients,
+  `get_llm_provider`, …). Benefits: faster cold imports, and helper modules
+  are now safe to import from restricted/sandboxed execution contexts that
+  forbid network-stack loading.
+
+Nothing to migrate — rebuild against `imperal-sdk>=5.2.2` at your convenience.
+
 ## 5.2.1 — 2026-06-01 — ChatExtension ergonomics & honest deprecations
 
 Small, fully backward-compatible cleanup of `ChatExtension`. No API removals;

{imperal_sdk-5.2.1 → imperal_sdk-5.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imperal-sdk
-Version: 5.2.1
+Version: 5.2.2
 Summary: SDK for building Imperal Cloud extensions
 Author: Valentin Scerbacov, Imperal, Inc.
 License-Expression: AGPL-3.0-or-later

imperal_sdk-5.2.2/src/imperal_sdk/__init__.py

@@ -0,0 +1,188 @@
+"""Imperal Cloud SDK — build extensions for the Imperal platform."""
+from typing import TYPE_CHECKING
+
+__version__ = "5.2.2"
+
+# 5.2.2 (2026-06-11): the package root resolves its public surface lazily
+# (PEP 562). The eager imports pulled the HTTP transport (Context / client
+# modules -> httpx) into EVERY consumer of ANY submodule — including
+# Temporal workflow code that lazily imports transport-free helpers such as
+# ``imperal_sdk.chat.filters`` (httpx subclasses urllib.request.Request,
+# which the workflow sandbox restricts; kernel federal
+# I-SANDBOX-SAFE-LAZY-IMPORTS, live incident 2026-06-10). The public
+# surface is unchanged: every name resolves to the same object, star-import
+# honors __all__, and resolved names are cached back into module globals.
+
+# name -> defining module (resolved on first attribute access)
+_LAZY_ATTRS = {
+    # Core
+    "Extension": "imperal_sdk.extension",
+    "ToolDef": "imperal_sdk.extension",
+    "SignalDef": "imperal_sdk.extension",
+    "ScheduleDef": "imperal_sdk.extension",
+    "LifecycleHook": "imperal_sdk.extension",
+    "HealthCheckDef": "imperal_sdk.extension",
+    "WebhookDef": "imperal_sdk.extension",
+    "EventHandlerDef": "imperal_sdk.extension",
+    "ExposedMethod": "imperal_sdk.extension",
+    "TrayDef": "imperal_sdk.extension",
+    "Context": "imperal_sdk.context",
+    "ImperalAuth": "imperal_sdk.auth",
+    "AuthError": "imperal_sdk.auth",
+    "User": "imperal_sdk.types.identity",
+    "UserContext": "imperal_sdk.types.identity",
+    "Tenant": "imperal_sdk.types.identity",
+    "TenantContext": "imperal_sdk.types.identity",
+    "generate_manifest": "imperal_sdk.manifest",
+    "save_manifest": "imperal_sdk.manifest",
+    "ChatExtension": "imperal_sdk.chat",
+    "ActionResult": "imperal_sdk.chat.action_result",
+    # LLM
+    "get_llm_provider": "imperal_sdk.runtime.llm_provider",
+    "LLMProvider": "imperal_sdk.runtime.llm_provider",
+    "LLMConfig": "imperal_sdk.runtime.llm_provider",
+    "LLMUsage": "imperal_sdk.runtime.llm_provider",
+    "MessageAdapter": "imperal_sdk.runtime.message_adapter",
+    # IPC
+    "ExtensionsClient": "imperal_sdk.extensions.client",
+    "CircularCallError": "imperal_sdk.extensions.client",
+    # Errors
+    "ImperalError": "imperal_sdk.errors",
+    "APIError": "imperal_sdk.errors",
+    "NotFoundError": "imperal_sdk.errors",
+    "RateLimitError": "imperal_sdk.errors",
+    "ValidationError": "imperal_sdk.errors",
+    "ExtensionError": "imperal_sdk.errors",
+    "QuotaExceededError": "imperal_sdk.errors",
+    "SkeletonAccessForbidden": "imperal_sdk.errors",
+    # Types
+    "Page": "imperal_sdk.types",
+    "ChatResult": "imperal_sdk.types",
+    "FunctionCall": "imperal_sdk.types",
+    "Document": "imperal_sdk.types",
+    "CompletionResult": "imperal_sdk.types",
+    "LimitsResult": "imperal_sdk.types",
+    "SubscriptionInfo": "imperal_sdk.types",
+    "BalanceInfo": "imperal_sdk.types",
+    "FileInfo": "imperal_sdk.types",
+    "HTTPResponse": "imperal_sdk.types",
+    "Event": "imperal_sdk.types",
+    "WebhookRequest": "imperal_sdk.types",
+    "WebhookResponse": "imperal_sdk.types",
+    "HealthStatus": "imperal_sdk.types",
+    # Protocol + Validator
+    "ExtensionProtocol": "imperal_sdk.protocols",
+    "validate_extension": "imperal_sdk.validator",
+    "ValidationReport": "imperal_sdk.validator",
+    "ValidationIssue": "imperal_sdk.validator",
+    "validate_source_tree": "imperal_sdk.validator_v1_6_0",
+    "validate_manifest_v1_6_0": "imperal_sdk.validator_v1_6_0",
+    # Secrets (importable from the root since 5.1.0; not in __all__ —
+    # preserved as-is)
+    "SecretSpec": "imperal_sdk.secrets",
+    "SecretClient": "imperal_sdk.secrets",
+    "SecretStatus": "imperal_sdk.secrets",
+    "SecretNotDeclaredError": "imperal_sdk.secrets",
+    "SecretWriteForbidden": "imperal_sdk.secrets",
+    "SecretVaultUnavailable": "imperal_sdk.secrets",
+    "SecretValueTooLarge": "imperal_sdk.secrets",
+    "SecretDeclarationConflict": "imperal_sdk.secrets",
+}
+
+# Any imperal_sdk submodule also resolves as a root attribute (the eager
+# imports used to expose chat/context/errors/ui/sdl/... as side effects;
+# the generic fallback in __getattr__ preserves that surface).
+
+if TYPE_CHECKING:  # pragma: no cover — IDE / type-checker surface only
+    from imperal_sdk.extension import (
+        Extension, ToolDef, SignalDef, ScheduleDef,
+        LifecycleHook, HealthCheckDef, WebhookDef, EventHandlerDef, ExposedMethod, TrayDef,
+    )
+    from imperal_sdk.context import Context
+    from imperal_sdk.auth import ImperalAuth, AuthError
+    from imperal_sdk.types.identity import User, UserContext, Tenant, TenantContext
+    from imperal_sdk.manifest import generate_manifest, save_manifest
+    from imperal_sdk.chat import ChatExtension
+    from imperal_sdk.chat.action_result import ActionResult
+    from imperal_sdk import ui
+    from imperal_sdk import sdl
+    from imperal_sdk.runtime.llm_provider import get_llm_provider, LLMProvider, LLMConfig, LLMUsage
+    from imperal_sdk.runtime.message_adapter import MessageAdapter
+    from imperal_sdk.extensions.client import ExtensionsClient, CircularCallError
+    from imperal_sdk.errors import (
+        ImperalError, APIError, NotFoundError, RateLimitError,
+        ValidationError, ExtensionError, QuotaExceededError,
+        SkeletonAccessForbidden,
+    )
+    from imperal_sdk.types import (
+        Page, ChatResult, FunctionCall,
+        Document, CompletionResult, LimitsResult, SubscriptionInfo,
+        BalanceInfo, FileInfo, HTTPResponse,
+        Event, WebhookRequest, WebhookResponse, HealthStatus,
+    )
+    from imperal_sdk.protocols import ExtensionProtocol
+    from imperal_sdk.validator import validate_extension, ValidationReport, ValidationIssue
+    from imperal_sdk.validator_v1_6_0 import (
+        validate_source_tree,
+        validate_manifest_v1_6_0,
+    )
+    from imperal_sdk.secrets import (
+        SecretSpec, SecretClient, SecretStatus,
+        SecretNotDeclaredError, SecretWriteForbidden, SecretVaultUnavailable,
+        SecretValueTooLarge, SecretDeclarationConflict,
+    )
+
+
+def __getattr__(name: str):
+    import importlib
+
+    src = _LAZY_ATTRS.get(name)
+    if src is not None:
+        obj = getattr(importlib.import_module(src), name)
+        globals()[name] = obj
+        return obj
+    if name.startswith("_"):
+        raise AttributeError(f"module 'imperal_sdk' has no attribute {name!r}")
+    try:
+        mod = importlib.import_module(f"imperal_sdk.{name}")
+    except ImportError:
+        raise AttributeError(
+            f"module 'imperal_sdk' has no attribute {name!r}"
+        ) from None
+    globals()[name] = mod
+    return mod
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_ATTRS) | {"ui", "sdl"})
+
+
+__all__ = [
+    # Core
+    "Extension", "ToolDef", "SignalDef", "ScheduleDef",
+    "LifecycleHook", "HealthCheckDef", "WebhookDef", "EventHandlerDef", "ExposedMethod", "TrayDef",
+    "Context", "ImperalAuth", "AuthError",
+    "User", "UserContext", "Tenant", "TenantContext",
+    "ChatExtension", "ActionResult",
+    "generate_manifest", "save_manifest",
+    # IPC
+    "ExtensionsClient", "CircularCallError",
+    # LLM
+    "get_llm_provider", "LLMProvider", "LLMConfig", "LLMUsage", "MessageAdapter",
+    # Errors
+    "ImperalError", "APIError", "NotFoundError", "RateLimitError",
+    "ValidationError", "ExtensionError", "QuotaExceededError",
+    "SkeletonAccessForbidden",
+    # Types
+    "Page", "ChatResult", "FunctionCall",
+    "Document", "CompletionResult", "LimitsResult", "SubscriptionInfo",
+    "BalanceInfo", "FileInfo", "HTTPResponse",
+    "Event", "WebhookRequest", "WebhookResponse", "HealthStatus",
+    # Protocol + Validator
+    "ExtensionProtocol", "validate_extension", "ValidationReport", "ValidationIssue",
+    "validate_source_tree", "validate_manifest_v1_6_0",
+    # UI
+    "ui",
+    # SDL — Structured Data Layer
+    "sdl",
+]

imperal_sdk-5.2.2/tests/test_import_light.py

@@ -0,0 +1,103 @@
+# -*- coding: utf-8 -*-
+"""5.2.2 — the package root is import-light (PEP 562 lazy surface).
+
+Kernel federal I-SANDBOX-SAFE-LAZY-IMPORTS (live incident 2026-06-10): the
+eager root imports pulled httpx (Context / client modules) into EVERY
+consumer of ANY submodule — including Temporal workflow code lazily
+importing transport-free helpers like ``imperal_sdk.chat.filters``
+(httpx._models subclasses urllib.request.Request, restricted inside the
+workflow sandbox -> RestrictedWorkflowAccessError -> whole chat turns
+crashed).
+
+Contracts:
+  1. ``import imperal_sdk`` and ``import imperal_sdk.chat.filters`` must NOT
+     load httpx.
+  2. The public surface is unchanged: every ``__all__`` name (and the
+     root-importable secrets names) resolves lazily to the SAME object the
+     defining module exports; submodules stay reachable as root attributes;
+     star-import works; unknown names raise AttributeError.
+"""
+import subprocess
+import sys
+
+import imperal_sdk
+
+
+def _probe(code: str) -> str:
+    r = subprocess.run(
+        [sys.executable, "-c", code],
+        capture_output=True, text=True, timeout=120,
+    )
+    out = (r.stdout or "").strip()
+    if r.returncode != 0 and not out:
+        out = "PROBE_ERROR: " + (r.stderr or "").strip()[-400:]
+    return out
+
+
+def test_root_import_is_transport_free():
+    out = _probe(
+        "import imperal_sdk, sys; "
+        "print('HTTPX' if 'httpx' in sys.modules else 'CLEAN')"
+    )
+    assert out == "CLEAN"
+
+
+def test_chat_filters_import_is_transport_free():
+    out = _probe(
+        "from imperal_sdk.chat.filters import enforce_os_identity, enforce_response_style; "
+        "import sys; print('HTTPX' if 'httpx' in sys.modules else 'CLEAN')"
+    )
+    assert out == "CLEAN"
+
+
+def test_version():
+    assert imperal_sdk.__version__ == "5.2.2"
+
+
+_SECRETS_NAMES = [
+    "SecretSpec", "SecretClient", "SecretStatus",
+    "SecretNotDeclaredError", "SecretWriteForbidden", "SecretVaultUnavailable",
+    "SecretValueTooLarge", "SecretDeclarationConflict",
+]
+
+
+def test_every_public_name_resolves_to_the_defining_object():
+    import importlib
+
+    from imperal_sdk import _LAZY_ATTRS
+
+    for name in list(imperal_sdk.__all__) + _SECRETS_NAMES:
+        obj = getattr(imperal_sdk, name)
+        if name in ("ui", "sdl"):
+            assert obj is importlib.import_module(f"imperal_sdk.{name}")
+            continue
+        src = _LAZY_ATTRS[name]
+        assert obj is getattr(importlib.import_module(src), name), name
+
+
+def test_submodules_reachable_as_root_attributes():
+    for sub in ("chat", "context", "errors", "types", "ui", "sdl", "manifest"):
+        mod = getattr(imperal_sdk, sub)
+        assert mod.__name__ == f"imperal_sdk.{sub}"
+
+
+def test_star_import_covers_all():
+    ns: dict = {}
+    exec("from imperal_sdk import *", ns)  # noqa: S102 — surface test
+    missing = [n for n in imperal_sdk.__all__ if n not in ns]
+    assert not missing, missing
+
+
+def test_unknown_attribute_raises_attribute_error():
+    try:
+        imperal_sdk.definitely_not_a_real_name
+    except AttributeError:
+        pass
+    else:
+        raise AssertionError("expected AttributeError")
+
+
+def test_dir_lists_the_surface():
+    d = dir(imperal_sdk)
+    for name in ("ChatExtension", "Context", "ui", "sdl", "SecretClient"):
+        assert name in d

imperal_sdk-5.2.1/src/imperal_sdk/__init__.py

@@ -1,73 +0,0 @@
-"""Imperal Cloud SDK — build extensions for the Imperal platform."""
-from imperal_sdk.extension import (
-    Extension, ToolDef, SignalDef, ScheduleDef,
-    LifecycleHook, HealthCheckDef, WebhookDef, EventHandlerDef, ExposedMethod, TrayDef,
-)
-from imperal_sdk.context import Context
-from imperal_sdk.auth import ImperalAuth, AuthError
-from imperal_sdk.types.identity import User, UserContext, Tenant, TenantContext
-from imperal_sdk.manifest import generate_manifest, save_manifest
-from imperal_sdk.chat import ChatExtension
-from imperal_sdk.chat.action_result import ActionResult
-from imperal_sdk import ui
-from imperal_sdk import sdl
-from imperal_sdk.runtime.llm_provider import get_llm_provider, LLMProvider, LLMConfig, LLMUsage
-from imperal_sdk.runtime.message_adapter import MessageAdapter
-from imperal_sdk.extensions.client import ExtensionsClient, CircularCallError
-
-# v1.0.0 types
-from imperal_sdk.errors import (
-    ImperalError, APIError, NotFoundError, RateLimitError,
-    ValidationError, ExtensionError, QuotaExceededError,
-    SkeletonAccessForbidden,
-)
-from imperal_sdk.types import (
-    Page, ChatResult, FunctionCall,
-    Document, CompletionResult, LimitsResult, SubscriptionInfo,
-    BalanceInfo, FileInfo, HTTPResponse,
-    Event, WebhookRequest, WebhookResponse, HealthStatus,
-)
-from imperal_sdk.protocols import ExtensionProtocol
-from imperal_sdk.validator import validate_extension, ValidationReport, ValidationIssue
-from imperal_sdk.validator_v1_6_0 import (
-    validate_source_tree,
-    validate_manifest_v1_6_0,
-)
-
-from imperal_sdk.secrets import (
-    SecretSpec, SecretClient, SecretStatus,
-    SecretNotDeclaredError, SecretWriteForbidden, SecretVaultUnavailable,
-    SecretValueTooLarge, SecretDeclarationConflict,
-)
-
-__version__ = "5.2.1"
-
-__all__ = [
-    # Core
-    "Extension", "ToolDef", "SignalDef", "ScheduleDef",
-    "LifecycleHook", "HealthCheckDef", "WebhookDef", "EventHandlerDef", "ExposedMethod", "TrayDef",
-    "Context", "ImperalAuth", "AuthError",
-    "User", "UserContext", "Tenant", "TenantContext",
-    "ChatExtension", "ActionResult",
-    "generate_manifest", "save_manifest",
-    # IPC
-    "ExtensionsClient", "CircularCallError",
-    # LLM
-    "get_llm_provider", "LLMProvider", "LLMConfig", "LLMUsage", "MessageAdapter",
-    # Errors
-    "ImperalError", "APIError", "NotFoundError", "RateLimitError",
-    "ValidationError", "ExtensionError", "QuotaExceededError",
-    "SkeletonAccessForbidden",
-    # Types
-    "Page", "ChatResult", "FunctionCall",
-    "Document", "CompletionResult", "LimitsResult", "SubscriptionInfo",
-    "BalanceInfo", "FileInfo", "HTTPResponse",
-    "Event", "WebhookRequest", "WebhookResponse", "HealthStatus",
-    # Protocol + Validator
-    "ExtensionProtocol", "validate_extension", "ValidationReport", "ValidationIssue",
-    "validate_source_tree", "validate_manifest_v1_6_0",
-    # UI
-    "ui",
-    # SDL — Structured Data Layer
-    "sdl",
-]