imperal-sdk 3.2.0__tar.gz → 3.3.0__tar.gz

{imperal_sdk-3.2.0 → imperal_sdk-3.3.0}/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 3.3.0 — 2026-04-28 — UI extensions + deprecation (Sprint 2)
+
+### Deprecated
+
+- `ChatExtension(model=...)` constructor parameter is now deprecated.
+  Default changes from `"claude-haiku-4-5-20251001"` → `None`. When
+  explicitly passed, emits a class-level WARN-once log:
+  > `ChatExtension(tool_name=...): the model= parameter is deprecated
+  > since SDK 3.3.0. LLM model resolution moved to kernel ctx-injection
+  > (see ctx._llm_configs). Will be removed in SDK 4.0.0.`
+- Backward compat preserved until SDK 4.0.0 — out-of-tree extensions
+  passing `model=` continue to work; in-tree extensions cleaned of the
+  parameter as part of this sprint.
+
+### Federal
+
+- `_model_deprecation_warned` flag is class-level (not instance-level)
+  so 11 in-tree extensions don't each warn at boot during transition
+  state. After they migrate, the warn fires only for external
+  out-of-tree extensions until they update.
+- Companion: Admin > LLM Config UI gains `chain_narrative_model` +
+  `judge_model` Select rows (admin extension change shipped in
+  `/opt/extensions` monorepo + 7 inner-git extensions per Developer
+  Portal convention).
+- Documentation: SDK docs `extension-guidelines.md` + `tools.md`
+  ChatExtension examples updated to omit `model=`. External
+  developers reading docs do not propagate the deprecated pattern.
+
 ## 3.2.0 — 2026-04-28 — Architectural cleanup (Sprint 1.2)
 
 ### Changed (BREAKING-internal — public API preserved with shim)

{imperal_sdk-3.2.0 → imperal_sdk-3.3.0}/PKG-INFO

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

{imperal_sdk-3.2.0 → imperal_sdk-3.3.0}/docs/extension-guidelines.md

@@ -50,8 +50,13 @@ chat = ChatExtension(
     tool_name="tool_myapp_chat",
     description="Clear description of ALL capabilities for embedding search",
     system_prompt="You are the My App assistant. You handle X, Y, Z.",
-    model="claude-haiku-4-5-20251001",
 )
+# NOTE (SDK 3.3.0+): the `model=` constructor parameter is DEPRECATED
+# and will be removed in SDK 4.0.0. LLM model resolution moved to
+# kernel ctx-injection (Sprint 1.2): ctx._llm_configs[purpose] is
+# pre-resolved by kernel context_factory based on Admin > LLM Config.
+# Out-of-tree extensions still passing `model=` continue to work but
+# emit a class-level WARN-once at boot.
 
 class DoXParams(BaseModel):
     input: str

{imperal_sdk-3.2.0 → imperal_sdk-3.3.0}/docs/tools.md

@@ -153,8 +153,11 @@ chat_ext = ChatExtension(
     tool_name="tool_notes_chat",
     description="Notes management — create, list, update, delete notes",
     system_prompt="You manage the user's notes. Call functions for all note operations.",
-    model="claude-haiku-4-5-20251001",
 )
+# SDK 3.3.0+: do not pass `model=` — it's deprecated.
+# LLM resolution happens via kernel ctx-injection
+# (ctx._llm_configs[purpose]). Admin > LLM Config controls
+# the model centrally for all extensions.
 
 @chat_ext.function("list_notes", action_type="read",
     description="List all notes", params={"folder": {"type": "string", "description": "Filter by folder", "default": None}})

{imperal_sdk-3.2.0 → imperal_sdk-3.3.0}/src/imperal_sdk/__init__.py

@@ -33,7 +33,7 @@ from imperal_sdk.validator_v1_6_0 import (
     validate_manifest_v1_6_0,
 )
 
-__version__ = "3.2.0"
+__version__ = "3.3.0"
 
 __all__ = [
     # Core

{imperal_sdk-3.2.0 → imperal_sdk-3.3.0}/src/imperal_sdk/chat/extension.py

@@ -39,12 +39,31 @@ class FunctionDef:
 
 class ChatExtension:
     def __init__(self, ext, tool_name: str, description: str, system_prompt: str = "",
-                 model: str = "claude-haiku-4-5-20251001", max_rounds: int = 10):
+                 model: "str | None" = None, max_rounds: int = 10):
         self.ext = ext
         self.tool_name = tool_name
         self.description = description
         self.system_prompt = system_prompt
-        self.model = model
+        # Sprint 2 (2026-04-28): the `model=` parameter is deprecated.
+        # LLM resolution moved to kernel ctx-injection (see ctx._llm_configs)
+        # in Sprint 1.2. Removing the constructor argument entirely is
+        # scheduled for SDK 4.0.0 — until then we keep it for backward
+        # compat but emit a class-level WARN-once when it's explicitly
+        # passed. The flag is on the CLASS (not instance) so 11
+        # extensions don't each warn at boot.
+        if model is not None:
+            if not getattr(ChatExtension, "_model_deprecation_warned", False):
+                log.warning(
+                    f"ChatExtension(tool_name={tool_name!r}, model=...): "
+                    "the `model=` parameter is deprecated since SDK 3.3.0. "
+                    "LLM model resolution moved to kernel ctx-injection (see "
+                    "ctx._llm_configs). Will be removed in SDK 4.0.0. "
+                    "Remove `model=` from extension app.py."
+                )
+                ChatExtension._model_deprecation_warned = True
+            self.model = model
+        else:
+            self.model = ""  # historical default no longer meaningful
         self.max_rounds = max_rounds
         self._functions: dict[str, FunctionDef] = {}
         _self = self

imperal_sdk-3.3.0/tests/test_chat_extension_deprecation.py

@@ -0,0 +1,61 @@
+"""Tests for ChatExtension(model=...) deprecation (Sprint 2).
+
+After Sprint 2:
+- model default → None (was "claude-haiku-4-5-20251001")
+- self.model defaults to "" when no model= passed
+- WARN-once class-level fires when model explicitly passed
+"""
+import logging
+import pytest
+
+from imperal_sdk import Extension
+from imperal_sdk.chat import ChatExtension
+
+
+@pytest.fixture(autouse=True)
+def reset_warned_flag():
+    """Reset class-level warn-once flag between tests for isolation."""
+    if hasattr(ChatExtension, "_model_deprecation_warned"):
+        delattr(ChatExtension, "_model_deprecation_warned")
+    yield
+    if hasattr(ChatExtension, "_model_deprecation_warned"):
+        delattr(ChatExtension, "_model_deprecation_warned")
+
+
+def test_chat_extension_no_model_default_is_empty():
+    """ChatExtension(...) without model= → chat_ext.model is empty string."""
+    ext = Extension("test-ext", version="1.0.0")
+    chat_ext = ChatExtension(ext=ext, tool_name="t1", description="d1")
+    assert chat_ext.model == "", (
+        f"expected empty model when omitted; got {chat_ext.model!r}"
+    )
+
+
+def test_chat_extension_passing_model_warns_once(caplog):
+    """Two ChatExtension(model=) calls → exactly 1 DEPRECATION warn."""
+    ext1 = Extension("test1", version="1.0.0")
+    ext2 = Extension("test2", version="1.0.0")
+    with caplog.at_level(logging.WARNING, logger="imperal_sdk.chat.extension"):
+        ChatExtension(ext=ext1, tool_name="t1", description="d1", model="x")
+        ChatExtension(ext=ext2, tool_name="t2", description="d2", model="y")
+
+    deprecation_warns = [
+        r for r in caplog.records
+        if r.levelname == "WARNING" and "deprecated" in r.message.lower()
+    ]
+    assert len(deprecation_warns) == 1, (
+        f"expected 1 DEPRECATION warn (class-level once); got {len(deprecation_warns)}"
+    )
+
+
+def test_chat_extension_no_warn_when_model_omitted(caplog):
+    """ChatExtension(...) without model= MUST NOT trigger DEPRECATION."""
+    ext = Extension("test-ext", version="1.0.0")
+    with caplog.at_level(logging.WARNING, logger="imperal_sdk.chat.extension"):
+        ChatExtension(ext=ext, tool_name="t1", description="d1")
+
+    deprecation_warns = [
+        r for r in caplog.records
+        if r.levelname == "WARNING" and "deprecated" in r.message.lower()
+    ]
+    assert len(deprecation_warns) == 0