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

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

@@ -2,14 +2,52 @@
 
 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;
+existing extensions are unaffected.
+
+### Changed
+
+- `ChatExtension(tool_name=...)` no longer emits a `DeprecationWarning`. The
+  kwarg is the **canonical** chat-registration key — it groups your
+  `@chat.function` tools in the manifest, anchors the per-turn prompt, and
+  labels scope-guard audit lines. It is load-bearing and not going away; the
+  prior "removed in 5.1.0" warning was incorrect and has been removed.
+
+### Added
+
+- `ChatExtension(...)` now accepts an **optional** `tool_name`. When omitted it
+  defaults to `f"tool_{ext.app_id}_chat"`. Pass it explicitly to pin a stable
+  routing name (recommended for production extensions). `description=` is now
+  optional as well.
+
 ## 5.2.0 — 2026-05-31 — Structured Data Layer (SDL) foundation
 
 Introduces the **SDL (`imperal_sdk.sdl`)** — a typed, semantic vocabulary for the
 data an extension returns, so the platform can read an entity's id / title / kind
 and its facets directly instead of inferring them from field names. This release
 ships the SDK foundation (canonical types + the standard facet library + a schema
-marker for platform detection); the platform begins reading SDL behind a rollout
-flag in a later release. Fully **additive** — the existing API and existing
+marker for platform detection). **The platform reads SDL in production today.** Fully **additive** — the existing API and existing
 extensions are unchanged; adopting SDL is opt-in via `data_model=`.
 
 ### Added
@@ -28,8 +66,8 @@ extensions are unchanged; adopting SDL is opt-in via `data_model=`.
   - `sdl.roles_of(model)` — introspect a model's field→role map.
 
   Use it via `data_model=` on `@chat.function` (e.g.
-  `class Note(sdl.Entity): ...` → `data_model=Note`). Full platform integration
-  arrives in a later phase. Not yet wired into the platform.
+  `class Note(sdl.Entity): ...` → `data_model=Note`). **The platform reads SDL
+  entities in production today.**
 - **SDL — Standard Facet Library (Phase 2).** 123 composable facet mixins across
   17 families (Identity, Time, People, Content, Communication, Media, Quantities,
   Money, Catalog, Tasks, Location, Tech/Network, Analytics, Events, Ratings,
@@ -43,9 +81,8 @@ extensions are unchanged; adopting SDL is opt-in via `data_model=`.
 
   564 standard roles are catalogued in `sdl_roles.json`. Every facet field is
   optional; for anything not covered, use `sdl.field(role="yourapp.x")` with a
-  non-reserved namespace. Full guide: `docs/sdl-facets.md`. Still not wired into
-  the platform — extensions can adopt the types now; the platform begins reading
-  them in a later phase.
+  non-reserved namespace. Full guide: `docs/sdl-facets.md`. **Live in production** —
+  extensions adopt the types and the platform reads them today.
 - **SDL — schema marker on `Entity` / `EntityList`.** Both stamp
   `x-sdl: "entity"` / `"entity-list"` into their JSON schema so the platform can
   detect an SDL-typed result from a function's return schema alone. Inherited by

imperal_sdk-5.2.2/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: imperal-sdk
+Version: 5.2.2
+Summary: SDK for building Imperal Cloud extensions
+Author: Valentin Scerbacov, Imperal, Inc.
+License-Expression: AGPL-3.0-or-later
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyjwt[crypto]>=2.10.0
+Provides-Extra: contract
+Requires-Dist: schemathesis>=3.30.0; extra == 'contract'
+Provides-Extra: db
+Requires-Dist: aiomysql>=0.2.0; extra == 'db'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.30; extra == 'db'
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.21.0; extra == 'dev'
+Requires-Dist: openapi-spec-validator>=0.7.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Imperal SDK
+
+### Build extensions for Webbee 🐝 — the agent of Imperal Cloud, the world's first AI Cloud OS.
+
+**Write a small Python function. Webbee calls it when a user asks for it — in their own words. Ship it to the Marketplace and get paid.**
+
+[![PyPI](https://img.shields.io/pypi/v/imperal-sdk?color=blue&label=PyPI)](https://pypi.org/project/imperal-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/imperal-sdk)](https://pypi.org/project/imperal-sdk/)
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
+
+[Documentation](https://docs.imperal.io) · [Quickstart](https://docs.imperal.io/en/getting-started/quick-start/) · [PyPI](https://pypi.org/project/imperal-sdk/) · [imperal.io](https://imperal.io)
+
+</div>
+
+---
+
+## What this is
+
+**Imperal Cloud** is the world's first AI Cloud OS — a cloud you connect the contexts of your life into (mail, money, projects, servers, notes, anything) and then run entirely in your own native language. **Webbee 🐝** is the AI agent that lives inside it and does the work for you, safely.
+
+**The Imperal SDK is how you give Webbee a new skill.** You write a small, typed Python *extension*; Webbee picks it up and calls it whenever a user asks for what it does — in plain language. The platform handles the hard parts — authentication, billing, multi-tenancy, audit, recovery, LLM routing — so your code stays small.
+
+```bash
+pip install imperal-sdk
+```
+
+> Python 3.11+ · AGPL-3.0-or-later
+
+## Why build here
+
+- **Webbee calls your function directly.** Typed, structured calls — no LLM guessing your arguments, no silent write failures.
+- **The platform does the plumbing.** Auth, per-user isolation, billing, audit, retries and recovery, multi-tenant safety — handled for you.
+- **You get paid.** Publish to the Imperal Marketplace, price your extension, earn on every use.
+- **Bring any LLM.** Users connect their own model keys — Anthropic, OpenAI, Google, Ollama, any OpenAI-compatible API.
+
+## A 60-second extension
+
+```python
+from imperal_sdk import Extension, ChatExtension, ActionResult
+from pydantic import BaseModel, Field
+
+ext = Extension(
+    "hello-world",
+    version="1.0.0",
+    display_name="Hello World",
+    description="Greets people by name with a friendly message.",
+    icon="icon.svg",
+    actions_explicit=True,
+)
+
+chat = ChatExtension(ext, tool_name="hello_world", description="Friendly greetings.")
+
+
+class GreetParams(BaseModel):
+    name: str = Field(..., description="Person to greet")
+
+
+@chat.function("greet", description="Greet someone by name.", action_type="read")
+async def greet(ctx, params: GreetParams) -> ActionResult:
+    return ActionResult.success(
+        data={"message": f"Hello, {params.name}! 🐝"},
+        summary=f"Greeted {params.name}",
+    )
+```
+
+That's a real, working extension. When a user types *"say hi to Alex"*, Webbee calls `greet(name="Alex")`.
+
+→ Full walkthrough, from zero to published: **[docs.imperal.io](https://docs.imperal.io/en/getting-started/quick-start/)**
+
+## What you can build
+
+- **Chat tools** — typed `@chat.function`s Webbee calls straight from natural language.
+- **Panels** — UI surfaces rendered inside the Imperal Panel.
+- **Skeletons** — live data feeds that keep Webbee aware of a user's state.
+- **Scheduled jobs & webhooks** — act on a timer, or react to outside events.
+- **Typed entities (SDL)** — return `sdl.Entity` objects and the platform reads their meaning (id, title, kind, …) directly instead of guessing field names. Live in production.
+
+Every published extension passes the **federal contract** — the validators that let Webbee call your code safely. The SDK checks it locally before you ship.
+
+## Test without a server
+
+```python
+from imperal_sdk.testing import MockContext
+
+async def test_greet():
+    ctx = MockContext()
+    result = await greet(ctx, GreetParams(name="Alex"))
+    assert result.status == "success"
+```
+
+## Documentation
+
+The full API, the manifest schema, every validator, recipes, and the federal contract live at **[docs.imperal.io](https://docs.imperal.io)** — that's the source of truth; this README is just the doorway.
+
+| | |
+|---|---|
+| Documentation | [docs.imperal.io](https://docs.imperal.io) |
+| Quickstart | [docs.imperal.io/en/getting-started/quick-start](https://docs.imperal.io/en/getting-started/quick-start/) |
+| PyPI | [pypi.org/project/imperal-sdk](https://pypi.org/project/imperal-sdk/) |
+| Changelog | [CHANGELOG.md](CHANGELOG.md) |
+| License | [AGPL-3.0-or-later](LICENSE) |
+
+---
+
+<div align="center">
+
+**Built by [Imperal, Inc.](https://imperal.io) — Webbee 🐝 is its agent.**
+
+</div>

imperal_sdk-5.2.2/README.md

@@ -0,0 +1,111 @@
+<div align="center">
+
+# Imperal SDK
+
+### Build extensions for Webbee 🐝 — the agent of Imperal Cloud, the world's first AI Cloud OS.
+
+**Write a small Python function. Webbee calls it when a user asks for it — in their own words. Ship it to the Marketplace and get paid.**
+
+[![PyPI](https://img.shields.io/pypi/v/imperal-sdk?color=blue&label=PyPI)](https://pypi.org/project/imperal-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/imperal-sdk)](https://pypi.org/project/imperal-sdk/)
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue)](LICENSE)
+
+[Documentation](https://docs.imperal.io) · [Quickstart](https://docs.imperal.io/en/getting-started/quick-start/) · [PyPI](https://pypi.org/project/imperal-sdk/) · [imperal.io](https://imperal.io)
+
+</div>
+
+---
+
+## What this is
+
+**Imperal Cloud** is the world's first AI Cloud OS — a cloud you connect the contexts of your life into (mail, money, projects, servers, notes, anything) and then run entirely in your own native language. **Webbee 🐝** is the AI agent that lives inside it and does the work for you, safely.
+
+**The Imperal SDK is how you give Webbee a new skill.** You write a small, typed Python *extension*; Webbee picks it up and calls it whenever a user asks for what it does — in plain language. The platform handles the hard parts — authentication, billing, multi-tenancy, audit, recovery, LLM routing — so your code stays small.
+
+```bash
+pip install imperal-sdk
+```
+
+> Python 3.11+ · AGPL-3.0-or-later
+
+## Why build here
+
+- **Webbee calls your function directly.** Typed, structured calls — no LLM guessing your arguments, no silent write failures.
+- **The platform does the plumbing.** Auth, per-user isolation, billing, audit, retries and recovery, multi-tenant safety — handled for you.
+- **You get paid.** Publish to the Imperal Marketplace, price your extension, earn on every use.
+- **Bring any LLM.** Users connect their own model keys — Anthropic, OpenAI, Google, Ollama, any OpenAI-compatible API.
+
+## A 60-second extension
+
+```python
+from imperal_sdk import Extension, ChatExtension, ActionResult
+from pydantic import BaseModel, Field
+
+ext = Extension(
+    "hello-world",
+    version="1.0.0",
+    display_name="Hello World",
+    description="Greets people by name with a friendly message.",
+    icon="icon.svg",
+    actions_explicit=True,
+)
+
+chat = ChatExtension(ext, tool_name="hello_world", description="Friendly greetings.")
+
+
+class GreetParams(BaseModel):
+    name: str = Field(..., description="Person to greet")
+
+
+@chat.function("greet", description="Greet someone by name.", action_type="read")
+async def greet(ctx, params: GreetParams) -> ActionResult:
+    return ActionResult.success(
+        data={"message": f"Hello, {params.name}! 🐝"},
+        summary=f"Greeted {params.name}",
+    )
+```
+
+That's a real, working extension. When a user types *"say hi to Alex"*, Webbee calls `greet(name="Alex")`.
+
+→ Full walkthrough, from zero to published: **[docs.imperal.io](https://docs.imperal.io/en/getting-started/quick-start/)**
+
+## What you can build
+
+- **Chat tools** — typed `@chat.function`s Webbee calls straight from natural language.
+- **Panels** — UI surfaces rendered inside the Imperal Panel.
+- **Skeletons** — live data feeds that keep Webbee aware of a user's state.
+- **Scheduled jobs & webhooks** — act on a timer, or react to outside events.
+- **Typed entities (SDL)** — return `sdl.Entity` objects and the platform reads their meaning (id, title, kind, …) directly instead of guessing field names. Live in production.
+
+Every published extension passes the **federal contract** — the validators that let Webbee call your code safely. The SDK checks it locally before you ship.
+
+## Test without a server
+
+```python
+from imperal_sdk.testing import MockContext
+
+async def test_greet():
+    ctx = MockContext()
+    result = await greet(ctx, GreetParams(name="Alex"))
+    assert result.status == "success"
+```
+
+## Documentation
+
+The full API, the manifest schema, every validator, recipes, and the federal contract live at **[docs.imperal.io](https://docs.imperal.io)** — that's the source of truth; this README is just the doorway.
+
+| | |
+|---|---|
+| Documentation | [docs.imperal.io](https://docs.imperal.io) |
+| Quickstart | [docs.imperal.io/en/getting-started/quick-start](https://docs.imperal.io/en/getting-started/quick-start/) |
+| PyPI | [pypi.org/project/imperal-sdk](https://pypi.org/project/imperal-sdk/) |
+| Changelog | [CHANGELOG.md](CHANGELOG.md) |
+| License | [AGPL-3.0-or-later](LICENSE) |
+
+---
+
+<div align="center">
+
+**Built by [Imperal, Inc.](https://imperal.io) — Webbee 🐝 is its agent.**
+
+</div>

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.0 → imperal_sdk-5.2.2}/src/imperal_sdk/chat/extension.py

@@ -64,9 +64,16 @@ class FunctionDef:
 
 
 class ChatExtension:
-    def __init__(self, ext, tool_name: str, description: str, system_prompt: str = "",
+    def __init__(self, ext, tool_name: str | None = None, description: str = "",
+                 system_prompt: str = "",
                  model: "str | None" = None, max_rounds: int = 10):
         self.ext = ext
+        # tool_name is the canonical chat-registration key: it groups the
+        # extension's @chat.function tools in the manifest, anchors the per-turn
+        # system prompt, and labels scope-guard audit lines. Optional — derived
+        # from the extension app_id (``tool_<app_id>_chat``) when omitted; pass
+        # it explicitly to pin a production-stable routing name.
+        tool_name = tool_name or f"tool_{ext.app_id}_chat"
         self.tool_name = tool_name
         self.description = description
         self.system_prompt = system_prompt
@@ -94,20 +101,12 @@ class ChatExtension:
                 "Example: 'Notes module — manage user notes and folders.'"
             )
 
-        # v5.0.0: orchestrator-tool auto-registration REMOVED. ChatExtension
-        # is now purely a @chat.function bundle declaration — the platform
-        # chain executor dispatches each function directly via typed dispatch.
-        # tool_name kwarg retained for back-compat but emits DeprecationWarning.
-        # Will be removed in 5.1.0.
-        import warnings as _warnings
-        _warnings.warn(
-            f"ChatExtension(tool_name={tool_name!r}): kwarg deprecated in SDK 5.0.0 "
-            "(orchestrator-tool auto-registration removed). Move classifier-readable "
-            "text into Extension(description=...) + per-@chat.function(description=...). "
-            "Will be removed in 5.1.0.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        # v5.0.0 removed orchestrator-tool auto-registration: ChatExtension is
+        # purely a @chat.function bundle declaration, and the platform chain
+        # executor dispatches each function directly via typed dispatch — the
+        # host LLM no longer sees a single ``tool_<app_id>_chat`` umbrella tool.
+        # ``tool_name`` is retained as the canonical registration key (see the
+        # __init__ note above) — it is NOT deprecated.
         ext._chat_extensions = getattr(ext, "_chat_extensions", {})
         ext._chat_extensions[tool_name] = self
 

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