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

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

@@ -2,6 +2,57 @@
 
 All notable changes to `imperal-sdk` are documented here.
 
+## 3.3.1 — 2026-04-29 — LLM-FU-1: gpt-5 / o-series max_completion_tokens
+
+### Fixed
+
+- `LLMProvider._call_openai` now sends `max_completion_tokens` instead of
+  the legacy `max_tokens` kwarg when the resolved config matches OpenAI
+  reasoning models — `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `o1*`, `o3*`,
+  `o4*`. OpenAI rejects `max_tokens` for these families with
+  `'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.`,
+  which surfaced after the 2026-04-29 admin LLM dropdown expansion added
+  these models. Anthropic, Gemini (OpenAI-compat), and Ollama/vLLM
+  (`openai_compatible`) keep `max_tokens` — sending the new kwarg to
+  those providers is unsafe.
+- Helper `_openai_uses_max_completion_tokens(provider, model)` gates the
+  rename; matches by model-name prefix (`gpt-5`, `o1`, `o3`, `o4`)
+  case-insensitively, scoped to `provider == "openai"` only.
+
+### Tests
+
+- `tests/test_openai_max_completion_tokens.py` — 24 parametrized cases
+  covering reasoning models, legacy OpenAI, cross-provider safety, and
+  edge cases (empty model, empty provider).
+
+## 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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imperal-sdk
-Version: 3.2.0
+Version: 3.3.1
 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.1}/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.1}/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.1}/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.1"
 
 __all__ = [
     # Core

{imperal_sdk-3.2.0 → imperal_sdk-3.3.1}/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.2.0 → imperal_sdk-3.3.1}/src/imperal_sdk/runtime/llm_provider.py

@@ -58,6 +58,20 @@ _ENV_FB_API_KEY    = os.getenv("LLM_FALLBACK_API_KEY", "")
 _ENV_FB_MODEL      = os.getenv("LLM_FALLBACK_MODEL", "")
 _ENV_FB_BASE_URL   = os.getenv("LLM_FALLBACK_BASE_URL", "")
 
+
+# OpenAI gpt-5 family + o-series reasoning models (o1/o3/o4) reject the
+# legacy `max_tokens` kwarg with "'max_tokens' is not supported with this
+# model. Use 'max_completion_tokens' instead." Other providers (Anthropic,
+# Gemini via OpenAI-compat, Ollama/vLLM via openai_compatible) keep
+# `max_tokens` — sending `max_completion_tokens` to them is unsafe.
+_OPENAI_MCT_MODEL_PREFIXES = ("gpt-5", "o1", "o3", "o4")
+
+
+def _openai_uses_max_completion_tokens(provider: str, model: str) -> bool:
+    if provider != "openai" or not model:
+        return False
+    return model.lower().startswith(_OPENAI_MCT_MODEL_PREFIXES)
+
 _GATEWAY_URL       = os.getenv("IMPERAL_GATEWAY_URL", "")
 _SERVICE_TOKEN     = os.getenv("IMPERAL_SERVICE_TOKEN", "")
 
@@ -446,9 +460,14 @@ class LLMProvider:
 
         client = self._get_client(cfg)
         oai_messages = MessageAdapter.to_openai_messages(messages, system)
+        _token_kwarg = (
+            "max_completion_tokens"
+            if _openai_uses_max_completion_tokens(cfg.provider, cfg.model)
+            else "max_tokens"
+        )
         kwargs: dict[str, Any] = {
             "model": cfg.model,
-            "max_tokens": max_tokens,
+            _token_kwarg: max_tokens,
             "messages": oai_messages,
             "temperature": temperature,
         }

imperal_sdk-3.3.1/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

imperal_sdk-3.3.1/tests/test_openai_max_completion_tokens.py

@@ -0,0 +1,52 @@
+"""Regression for LLM-FU-1 (2026-04-29).
+
+OpenAI gpt-5 family + o-series reasoning models (o1/o3/o4) reject the legacy
+`max_tokens` kwarg. The SDK runtime LLM provider must rename it to
+`max_completion_tokens` for that family only — other providers and other
+OpenAI models keep `max_tokens`.
+"""
+from __future__ import annotations
+
+import pytest
+
+from imperal_sdk.runtime.llm_provider import _openai_uses_max_completion_tokens
+
+
+@pytest.mark.parametrize(
+    "provider,model,expected",
+    [
+        # gpt-5 family — must use max_completion_tokens
+        ("openai", "gpt-5", True),
+        ("openai", "gpt-5-mini", True),
+        ("openai", "gpt-5-nano", True),
+        ("openai", "GPT-5-Mini", True),  # case-insensitive
+        # o-series reasoning models
+        ("openai", "o1", True),
+        ("openai", "o1-mini", True),
+        ("openai", "o1-preview", True),
+        ("openai", "o3", True),
+        ("openai", "o3-mini", True),
+        ("openai", "o4-mini", True),
+        # Legacy OpenAI models — must keep max_tokens
+        ("openai", "gpt-4o", False),
+        ("openai", "gpt-4o-mini", False),
+        ("openai", "gpt-4-turbo", False),
+        ("openai", "gpt-3.5-turbo", False),
+        ("openai", "gpt-4.1", False),
+        ("openai", "gpt-4.1-mini", False),
+        # Other providers — never use max_completion_tokens regardless of model name
+        ("anthropic", "claude-sonnet-4-6-20251001", False),
+        ("anthropic", "gpt-5", False),  # nonsense combo, but provider gates the rename
+        ("google", "gemini-2.5-pro", False),
+        ("google", "gpt-5", False),
+        ("openai_compatible", "gpt-5", False),  # Ollama serving misnamed model
+        ("openai_compatible", "qwen3:27b", False),
+        # Edge cases
+        ("openai", "", False),
+        ("", "gpt-5", False),
+    ],
+)
+def test_openai_uses_max_completion_tokens(
+    provider: str, model: str, expected: bool
+) -> None:
+    assert _openai_uses_max_completion_tokens(provider, model) is expected