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

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

@@ -2,14 +2,33 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 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 +47,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 +62,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.1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: imperal-sdk
+Version: 5.2.1
+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.1/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.0 → imperal_sdk-5.2.1}/src/imperal_sdk/__init__.py

@@ -40,7 +40,7 @@ from imperal_sdk.secrets import (
     SecretValueTooLarge, SecretDeclarationConflict,
 )
 
-__version__ = "5.2.0"
+__version__ = "5.2.1"
 
 __all__ = [
     # Core

{imperal_sdk-5.2.0 → imperal_sdk-5.2.1}/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.0 → imperal_sdk-5.2.1}/tests/test_manifest_no_orchestrator_tool.py

@@ -8,10 +8,7 @@ from imperal_sdk.chat import ChatExtension
 def test_chat_extension_does_not_emit_orchestrator_tool():
     """Building a manifest from an ext with a ChatExtension must not include tool_<name>_chat."""
     ext = Extension(app_id="demo", description="demo ext for emitter test")
-    # Suppress the DeprecationWarning emitted by ChatExtension(tool_name=...) — covered separately.
-    with warnings.catch_warnings():
-        warnings.simplefilter("ignore", DeprecationWarning)
-        chat = ChatExtension(ext, tool_name="demo_legacy_kwarg", description="legacy")
+    chat = ChatExtension(ext, tool_name="demo_legacy_kwarg", description="legacy")
 
     @chat.function(name="list_items", description="list user items for the demo ext")
     async def list_items(ctx):
@@ -53,17 +50,37 @@ def test_chat_extension_does_not_emit_orchestrator_tool():
     )
 
 
-def test_chat_extension_tool_name_kwarg_emits_deprecation_warning():
-    """ChatExtension(tool_name=...) must emit DeprecationWarning at construction."""
+def test_chat_extension_tool_name_kwarg_does_not_warn():
+    """ChatExtension(tool_name=...) is the canonical chat-registration key — it
+    must NOT emit a DeprecationWarning.
+
+    Reversed from the transient SDK 5.0.0 stance: the kwarg is load-bearing
+    (manifest grouping key + per-turn prompt + scope guards), has no
+    replacement API, and every first-party extension passes it. A deprecation
+    warning with no migration path is cry-wolf noise, so it was removed.
+    """
     ext = Extension(app_id="demo2", description="demo ext for deprecation test")
     with warnings.catch_warnings(record=True) as caught:
         warnings.simplefilter("always")
         ChatExtension(ext, tool_name="legacy_name", description="legacy")
-    deprecation = [w for w in caught if issubclass(w.category, DeprecationWarning)]
-    assert deprecation, (
-        "ChatExtension(tool_name=...) MUST emit a DeprecationWarning in SDK 5.0.0"
+    tool_name_deprecations = [
+        w for w in caught
+        if issubclass(w.category, DeprecationWarning) and "tool_name" in str(w.message)
+    ]
+    assert not tool_name_deprecations, (
+        "ChatExtension(tool_name=...) must NOT emit a tool_name DeprecationWarning; "
+        f"got: {[str(w.message) for w in tool_name_deprecations]}"
+    )
+
+
+def test_chat_extension_tool_name_optional_defaults_to_app_id():
+    """tool_name is optional — when omitted it derives from the extension app_id
+    (``tool_<app_id>_chat``) and is used as the manifest registration key."""
+    ext = Extension(app_id="demo3", description="demo ext for default-tool-name test")
+    chat = ChatExtension(ext, description="no explicit tool_name")
+    assert chat.tool_name == "tool_demo3_chat", (
+        f"omitted tool_name must default to tool_<app_id>_chat; got {chat.tool_name!r}"
     )
-    msg = str(deprecation[0].message)
-    assert "tool_name" in msg and ("5.0.0" in msg or "5.1.0" in msg), (
-        f"DeprecationWarning message must reference tool_name and version cutoff; got: {msg}"
+    assert "tool_demo3_chat" in ext._chat_extensions, (
+        "default tool_name must be registered as the _chat_extensions key"
     )