kimi-agent-module-api 1.0.0__tar.gz → 1.2.0__tar.gz

{kimi_agent_module_api-1.0.0/src/kimi_agent_module_api.egg-info → kimi_agent_module_api-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kimi-agent-module-api
-Version: 1.0.0
+Version: 1.2.0
 Summary: Stable contracts for community-built assistant modules
 Author: Webhead
 License-Expression: MIT
@@ -48,4 +48,14 @@ my_module = "my_module_package:SPEC"
 The [module guide](https://github.com/webhead2oo9/kimi-agent/blob/main/docs/modules.md)
 documents installation, declarations, lifecycle, and every runtime port. The
 [reference module](https://github.com/webhead2oo9/kimi-agent/tree/main/bot/modules/example)
-is a complete, commented example that exercises every port; start there.
+is a complete, commented example that exercises most ports; start there.
+
+Guild-scoped live command replacement was added in 1.1. Modules using
+`InteractionRouter.replace_guild_commands()` should depend on
+`kimi-agent-module-api>=1.1,<2` and require the host capability
+`discord.guild_commands.v1`.
+
+Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once a response uses
+that layout model, Discord requires every later edit of the same message to remain a layout.
+Modules using them should depend on `kimi-agent-module-api>=1.2,<2` and require
+`discord.modals.v1` and/or `discord.components_v2.v1`.

{kimi_agent_module_api-1.0.0 → kimi_agent_module_api-1.2.0}/README.md

@@ -31,4 +31,14 @@ my_module = "my_module_package:SPEC"
 The [module guide](https://github.com/webhead2oo9/kimi-agent/blob/main/docs/modules.md)
 documents installation, declarations, lifecycle, and every runtime port. The
 [reference module](https://github.com/webhead2oo9/kimi-agent/tree/main/bot/modules/example)
-is a complete, commented example that exercises every port; start there.
+is a complete, commented example that exercises most ports; start there.
+
+Guild-scoped live command replacement was added in 1.1. Modules using
+`InteractionRouter.replace_guild_commands()` should depend on
+`kimi-agent-module-api>=1.1,<2` and require the host capability
+`discord.guild_commands.v1`.
+
+Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once a response uses
+that layout model, Discord requires every later edit of the same message to remain a layout.
+Modules using them should depend on `kimi-agent-module-api>=1.2,<2` and require
+`discord.modals.v1` and/or `discord.components_v2.v1`.

{kimi_agent_module_api-1.0.0 → kimi_agent_module_api-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kimi-agent-module-api"
-version = "1.0.0"
+version = "1.2.0"
 description = "Stable contracts for community-built assistant modules"
 requires-python = ">=3.14"
 authors = [{ name = "Webhead" }]

{kimi_agent_module_api-1.0.0 → kimi_agent_module_api-1.2.0}/src/kimi_agent_module_api/__init__.py

@@ -20,9 +20,17 @@ from kimi_agent_module_api.contracts import (
     HealthReporter,
     InviteSnapshot,
     InteractionRouter,
+    LayoutGallery,
+    LayoutItem,
+    LayoutSection,
+    LayoutSeparator,
+    LayoutSeparatorSpacing,
+    LayoutText,
+    ModalSpec,
     ModuleHttp,
     ModulePermissions,
     ModuleStorage,
+    OutgoingLayout,
     ScopedModuleMigration,
     ProposalActor,
     ProposalError,
@@ -34,6 +42,8 @@ from kimi_agent_module_api.contracts import (
     ServiceRegistry,
     ServiceRequirement,
     TrustLookup,
+    TextInputSpec,
+    TextInputStyle,
 )
 from kimi_agent_module_api.settings import ModuleSetting, ModuleSettingsDefinition
 from kimi_agent_module_api.tools import (
@@ -151,6 +161,13 @@ __all__ = [
     "ConfigSnapshot",
     "GuildSettingsSchema",
     "InviteSnapshot",
+    "LayoutGallery",
+    "LayoutItem",
+    "LayoutSection",
+    "LayoutSeparator",
+    "LayoutSeparatorSpacing",
+    "LayoutText",
+    "ModalSpec",
     "ModuleCapabilities",
     "ModuleLoadContext",
     "ModulePermissions",
@@ -161,6 +178,7 @@ __all__ = [
     "ModuleToolContext",
     "ModuleToolHandler",
     "ModuleToolRegistry",
+    "OutgoingLayout",
     "ProposalActor",
     "ProposalError",
     "ProposalRef",
@@ -170,6 +188,8 @@ __all__ = [
     "ScopedModuleMigration",
     "ServiceDeclaration",
     "ServiceRequirement",
+    "TextInputSpec",
+    "TextInputStyle",
     "TrustTier",
     "render_guild_settings",
 ]

{kimi_agent_module_api-1.0.0 → kimi_agent_module_api-1.2.0}/src/kimi_agent_module_api/contracts.py

@@ -52,6 +52,10 @@ class ServiceUnavailable(RuntimeError):
     """Raised through a service proxy after its provider module closed."""
 
 
+class CommandSyncError(RuntimeError):
+    """Discord did not accept a live guild-command synchronization."""
+
+
 # --------------------------------------------------------------------------
 # Declarations carried on ModuleSpec
 # --------------------------------------------------------------------------
@@ -815,6 +819,82 @@ class OutgoingEmbed:
     timestamp: bool = False
 
 
+@dataclass(frozen=True, slots=True)
+class LayoutText:
+    content: str
+
+
+type LayoutSeparatorSpacing = Literal["small", "large"]
+
+
+@dataclass(frozen=True, slots=True)
+class LayoutSeparator:
+    visible: bool = True
+    spacing: LayoutSeparatorSpacing = "small"
+
+
+@dataclass(frozen=True, slots=True)
+class LayoutGallery:
+    urls: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class LayoutSection:
+    texts: tuple[str, ...]
+    thumbnail_url: str
+
+
+type LayoutItem = LayoutText | LayoutSeparator | LayoutGallery | LayoutSection
+
+
+@dataclass(frozen=True, slots=True)
+class OutgoingLayout:
+    """One Components V2 container, optionally followed by interactive controls."""
+
+    items: tuple[LayoutItem, ...]
+    accent_color: int | None = None
+
+
+def validate_outgoing_layout(layout: OutgoingLayout) -> None:
+    """Validate the Discord hard limits represented by ``OutgoingLayout``."""
+    if not 1 <= len(layout.items) <= 40:
+        raise ModuleContractError("a layout must contain between one and 40 items")
+    if layout.accent_color is not None and (
+        isinstance(layout.accent_color, bool) or not 0 <= layout.accent_color <= 0xFFFFFF
+    ):
+        raise ModuleContractError("layout accent_color must be between 0 and 0xFFFFFF")
+
+    def validate_text(text: Any, label: str) -> None:
+        if not isinstance(text, str) or not 1 <= len(text) <= 4_000:
+            raise ModuleContractError(f"{label} must contain between one and 4000 characters")
+
+    text_length = 0
+    for item in layout.items:
+        if isinstance(item, LayoutText):
+            validate_text(item.content, "layout text")
+            text_length += len(item.content)
+        elif isinstance(item, LayoutSeparator):
+            if item.spacing not in ("small", "large"):
+                raise ModuleContractError(f"invalid layout separator spacing {item.spacing!r}")
+        elif isinstance(item, LayoutGallery):
+            if not 1 <= len(item.urls) <= 10:
+                raise ModuleContractError("a layout gallery must contain between one and 10 URLs")
+            if any(not isinstance(url, str) or not url for url in item.urls):
+                raise ModuleContractError("layout gallery URLs must be non-empty strings")
+        elif isinstance(item, LayoutSection):
+            if not 1 <= len(item.texts) <= 3:
+                raise ModuleContractError("a layout section must contain between one and 3 texts")
+            for text in item.texts:
+                validate_text(text, "layout section text")
+                text_length += len(text)
+            if not isinstance(item.thumbnail_url, str) or not item.thumbnail_url:
+                raise ModuleContractError("a layout section thumbnail URL must be non-empty")
+        else:
+            raise ModuleContractError(f"unsupported layout item {item!r}")
+    if text_length > 4_000:
+        raise ModuleContractError("layout text cannot exceed 4000 characters in total")
+
+
 class DiscordActions(Protocol):
     """Declared Discord operations on stable IDs.
 
@@ -953,6 +1033,9 @@ class ModuleInteraction(Protocol):
     @property
     def values(self) -> tuple[str, ...]: ...
 
+    @property
+    def text_values(self) -> Mapping[str, str]: ...
+
     @property
     def message(self) -> MessageRef | None:
         """The message a button or select lives on; ``None`` for slash commands."""
@@ -963,17 +1046,21 @@ class ModuleInteraction(Protocol):
         content: str | None = None,
         *,
         embed: OutgoingEmbed | None = None,
+        layout: OutgoingLayout | None = None,
         ephemeral: bool = False,
         components: Sequence[Any] = (),
     ) -> None: ...
 
     async def defer(self, *, ephemeral: bool = False) -> None: ...
 
+    async def show_modal(self, modal: ModalSpec) -> None: ...
+
     async def edit_original(
         self,
         content: str | None = None,
         *,
         embed: OutgoingEmbed | None = None,
+        layout: OutgoingLayout | None = None,
         components: Sequence[Any] = (),
     ) -> None: ...
 
@@ -1009,11 +1096,123 @@ class SelectSpec:
     max_values: int = 1
 
 
+def validate_layout_components(
+    components: Sequence[Any], *, layout: OutgoingLayout | None = None
+) -> None:
+    """Validate control rows and the full Components V2 descendant limit."""
+    rows = 0
+    buttons_in_row = 0
+    for component in components:
+        if isinstance(component, ButtonSpec):
+            if buttons_in_row == 0:
+                rows += 1
+            buttons_in_row = (buttons_in_row + 1) % 5
+        elif isinstance(component, SelectSpec):
+            buttons_in_row = 0
+            rows += 1
+        else:
+            raise ModuleContractError(f"unsupported component {component!r}")
+    if rows > 5:
+        raise ModuleContractError("layout controls cannot require more than five action rows")
+    if layout is not None:
+        descendants = 1 + rows + len(components)
+        for item in layout.items:
+            descendants += len(item.texts) + 2 if isinstance(item, LayoutSection) else 1
+        if descendants > 40:
+            raise ModuleContractError("a layout cannot exceed 40 components in total")
+
+
+type TextInputStyle = Literal["short", "paragraph"]
+
+
+@dataclass(frozen=True, slots=True)
+class TextInputSpec:
+    key: str
+    label: str
+    style: TextInputStyle = "short"
+    default: str | None = None
+    placeholder: str | None = None
+    required: bool = True
+    min_length: int | None = None
+    max_length: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ModalSpec:
+    """A modal whose submit handler is registered under ``key``."""
+
+    key: str
+    title: str
+    inputs: tuple[TextInputSpec, ...]
+    parts: tuple[str, ...] = ()
+
+
+def validate_modal_spec(modal: ModalSpec) -> None:
+    """Validate Discord's hard modal and text-input limits."""
+    if not isinstance(modal.key, str) or not _TOPIC_SEGMENT_RE.fullmatch(modal.key):
+        raise ModuleContractError(f"invalid modal key {modal.key!r}")
+    if any(not isinstance(part, str) or ":" in part for part in modal.parts):
+        raise ModuleContractError("modal custom_id parts must be strings without ':'")
+    if not isinstance(modal.title, str) or not 1 <= len(modal.title) <= 45:
+        raise ModuleContractError("a modal title must contain between one and 45 characters")
+    if not 1 <= len(modal.inputs) <= 5:
+        raise ModuleContractError("a modal must contain between one and five text inputs")
+
+    keys: set[str] = set()
+    for input_spec in modal.inputs:
+        if not isinstance(input_spec.key, str) or not _TOPIC_SEGMENT_RE.fullmatch(input_spec.key):
+            raise ModuleContractError(f"invalid modal text input key {input_spec.key!r}")
+        if input_spec.key in keys:
+            raise ModuleContractError("modal text input keys must be unique")
+        keys.add(input_spec.key)
+        if not isinstance(input_spec.label, str) or not 1 <= len(input_spec.label) <= 45:
+            raise ModuleContractError(
+                "a modal text input label must contain between one and 45 characters"
+            )
+        if input_spec.style not in ("short", "paragraph"):
+            raise ModuleContractError(f"invalid modal text input style {input_spec.style!r}")
+        if input_spec.placeholder is not None and (
+            not isinstance(input_spec.placeholder, str) or len(input_spec.placeholder) > 100
+        ):
+            raise ModuleContractError("a modal text input placeholder cannot exceed 100 characters")
+        if input_spec.default is not None and (
+            not isinstance(input_spec.default, str) or len(input_spec.default) > 4_000
+        ):
+            raise ModuleContractError("a modal text input default cannot exceed 4000 characters")
+        if input_spec.min_length is not None and (
+            isinstance(input_spec.min_length, bool)
+            or not isinstance(input_spec.min_length, int)
+            or not 0 <= input_spec.min_length <= 4_000
+        ):
+            raise ModuleContractError("modal text input min_length must be between 0 and 4000")
+        if input_spec.max_length is not None and (
+            isinstance(input_spec.max_length, bool)
+            or not isinstance(input_spec.max_length, int)
+            or not 1 <= input_spec.max_length <= 4_000
+        ):
+            raise ModuleContractError("modal text input max_length must be between 1 and 4000")
+        if (
+            input_spec.min_length is not None
+            and input_spec.max_length is not None
+            and input_spec.min_length > input_spec.max_length
+        ):
+            raise ModuleContractError("modal text input min_length cannot exceed max_length")
+
+
 type CommandHandler = Callable[[ModuleInteraction], Awaitable[None]]
 type AutocompleteHandler = Callable[
     [ModuleInteraction, str, str], Awaitable[Sequence[tuple[str, str | int]]]
 ]
-type ComponentKind = Literal["button", "select"]
+type ComponentKind = Literal["button", "select", "modal"]
+
+
+@dataclass(frozen=True, slots=True)
+class GuildCommand:
+    """One command in a module's desired command set for a guild."""
+
+    spec: CommandSpec
+    handler: CommandHandler
+    autocomplete: AutocompleteHandler | None = None
 
 
 class Registration(Protocol):
@@ -1029,6 +1228,14 @@ class InteractionRouter(Protocol):
         autocomplete: AutocompleteHandler | None = None,
     ) -> Registration: ...
 
+    async def replace_guild_commands(
+        self,
+        guild_id: int,
+        commands: Sequence[GuildCommand],
+    ) -> None:
+        """Replace this module's complete command set for one guild."""
+        ...
+
     def register_component(
         self,
         kind: ComponentKind,

{kimi_agent_module_api-1.0.0 → kimi_agent_module_api-1.2.0}/src/kimi_agent_module_api/testing.py

@@ -29,6 +29,7 @@ from kimi_agent_module_api.contracts import (
     Backoff,
     ChannelSnapshot,
     CommandSpec,
+    GuildCommand,
     ConfigSnapshot,
     Event,
     EventHandler,
@@ -44,11 +45,13 @@ from kimi_agent_module_api.contracts import (
     MessagePage,
     MessageRef,
     MessageSnapshot,
+    ModalSpec,
     TABLE_NAME_RE,
     MigrationContext,
     ModuleContractError,
     ModuleHealth,
     OutgoingEmbed,
+    OutgoingLayout,
     ProposalActor,
     ProposalError,
     ProposalRef,
@@ -59,6 +62,9 @@ from kimi_agent_module_api.contracts import (
     TrustTierName,
     UndeclaredDiscordAction,
     build_custom_id,
+    validate_modal_spec,
+    validate_layout_components,
+    validate_outgoing_layout,
     validate_publish_topic,
 )
 from kimi_agent_module_api.tools import ModuleToolHandler
@@ -567,6 +573,7 @@ class FakeResponse:
     ephemeral: bool
     components: tuple[Any, ...]
     kind: str
+    layout: OutgoingLayout | None = None
 
 
 class FakeInteraction:
@@ -579,8 +586,10 @@ class FakeInteraction:
         options: Mapping[str, Any] | None = None,
         custom_id: str | None = None,
         values: Sequence[str] = (),
+        text_values: Mapping[str, str] | None = None,
         guild_name: str | None = "Test Guild",
         message: MessageRef | None = None,
+        message_uses_layout: bool = False,
     ) -> None:
         self._message = message
         self._guild_name = guild_name
@@ -590,8 +599,11 @@ class FakeInteraction:
         self._options = dict(options or {})
         self._custom_id = custom_id
         self._values = tuple(values)
+        self._text_values = dict(text_values or {})
         self.responses: list[FakeResponse] = []
+        self.shown_modals: list[ModalSpec] = []
         self.deferred: bool | None = None
+        self._original_uses_layout = message_uses_layout
 
     @property
     def guild_id(self) -> int:
@@ -621,6 +633,10 @@ class FakeInteraction:
     def values(self) -> tuple[str, ...]:
         return self._values
 
+    @property
+    def text_values(self) -> Mapping[str, str]:
+        return self._text_values
+
     @property
     def message(self) -> MessageRef | None:
         return self._message
@@ -630,22 +646,49 @@ class FakeInteraction:
         content: str | None = None,
         *,
         embed: OutgoingEmbed | None = None,
+        layout: OutgoingLayout | None = None,
         ephemeral: bool = False,
         components: Sequence[Any] = (),
     ) -> None:
-        self.responses.append(FakeResponse(content, embed, ephemeral, tuple(components), "respond"))
+        if layout is not None and (content is not None or embed is not None):
+            raise ModuleContractError("layout cannot be combined with content or embed")
+        if layout is not None:
+            validate_outgoing_layout(layout)
+            validate_layout_components(components, layout=layout)
+        self.responses.append(
+            FakeResponse(content, embed, ephemeral, tuple(components), "respond", layout=layout)
+        )
+        self._original_uses_layout = layout is not None
 
     async def defer(self, *, ephemeral: bool = False) -> None:
         self.deferred = ephemeral
 
+    async def show_modal(self, modal: ModalSpec) -> None:
+        validate_modal_spec(modal)
+        self.shown_modals.append(modal)
+
     async def edit_original(
         self,
         content: str | None = None,
         *,
         embed: OutgoingEmbed | None = None,
+        layout: OutgoingLayout | None = None,
         components: Sequence[Any] = (),
     ) -> None:
-        self.responses.append(FakeResponse(content, embed, False, tuple(components), "edit"))
+        if self._original_uses_layout and layout is None:
+            raise ModuleContractError(
+                "a Components V2 message must continue to use layout when edited"
+            )
+        if layout is not None and (content is not None or embed is not None):
+            raise ModuleContractError("layout cannot be combined with content or embed")
+        if layout is not None:
+            validate_outgoing_layout(layout)
+            validate_layout_components(components, layout=layout)
+        self.responses.append(
+            FakeResponse(content, embed, False, tuple(components), "edit", layout=layout)
+        )
+        if layout is not None:
+            self._original_uses_layout = True
 
     async def follow_up(
         self, content: str, *, embed: OutgoingEmbed | None = None, ephemeral: bool = False
@@ -663,6 +706,8 @@ class FakeInteractions:
     def __init__(self, module_name: str) -> None:
         self.module_name = module_name
         self.commands: dict[str, tuple[CommandSpec, Callable[..., Any]]] = {}
+        self.guild_commands: dict[int, dict[str, tuple[CommandSpec, Callable[..., Any]]]] = {}
+        self.guild_autocompletes: dict[int, dict[str, Callable[..., Any]]] = {}
         self.components: dict[tuple[str, str], Callable[..., Any]] = {}
         self.component_min_tiers: dict[tuple[str, str], TrustTierName] = {}
         self.autocompletes: dict[str, Callable[..., Any]] = {}
@@ -686,6 +731,50 @@ class FakeInteractions:
             lambda: (self.commands.pop(qualified, None), self.autocompletes.pop(qualified, None))
         )
 
+    async def replace_guild_commands(
+        self,
+        guild_id: int,
+        commands: Sequence[GuildCommand],
+    ) -> None:
+        if guild_id <= 0:
+            raise ModuleContractError("guild_id must be a positive Discord snowflake")
+        desired: dict[str, tuple[CommandSpec, Callable[..., Any]]] = {}
+        autocompletes: dict[str, Callable[..., Any]] = {}
+        top_kinds: dict[str, str] = {}
+        for command in commands:
+            top_name = command.spec.group or command.spec.name
+            kind = "group" if command.spec.group else "command"
+            if top_name in self.commands:
+                raise ModuleContractError(
+                    f"module {self.module_name!r} guild command {top_name!r} "
+                    "would shadow a global command"
+                )
+            previous_kind = top_kinds.setdefault(top_name, kind)
+            if previous_kind != kind:
+                raise ModuleContractError(
+                    f"module {self.module_name!r} guild command {top_name!r} "
+                    "is both a command and a group"
+                )
+            qualified = (
+                f"{command.spec.group}.{command.spec.name}"
+                if command.spec.group
+                else command.spec.name
+            )
+            if qualified in desired:
+                raise ModuleContractError(
+                    f"module {self.module_name!r} guild command {qualified!r} "
+                    "is registered more than once"
+                )
+            desired[qualified] = (command.spec, command.handler)
+            if command.autocomplete is not None:
+                autocompletes[qualified] = command.autocomplete
+        if desired:
+            self.guild_commands[guild_id] = desired
+            self.guild_autocompletes[guild_id] = autocompletes
+        else:
+            self.guild_commands.pop(guild_id, None)
+            self.guild_autocompletes.pop(guild_id, None)
+
     def register_component(
         self,
         kind: str,
@@ -695,7 +784,7 @@ class FakeInteractions:
         expires_after_seconds: float | None = None,
         min_tier: TrustTierName = "member",
     ) -> _Closable:
-        if kind not in ("button", "select"):
+        if kind not in ("button", "select", "modal"):
             raise ModuleContractError(f"unsupported component kind {kind!r}")
         build_custom_id(self.module_name, key)
         identity = (kind, key)

{kimi_agent_module_api-1.0.0 → kimi_agent_module_api-1.2.0/src/kimi_agent_module_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kimi-agent-module-api
-Version: 1.0.0
+Version: 1.2.0
 Summary: Stable contracts for community-built assistant modules
 Author: Webhead
 License-Expression: MIT
@@ -48,4 +48,14 @@ my_module = "my_module_package:SPEC"
 The [module guide](https://github.com/webhead2oo9/kimi-agent/blob/main/docs/modules.md)
 documents installation, declarations, lifecycle, and every runtime port. The
 [reference module](https://github.com/webhead2oo9/kimi-agent/tree/main/bot/modules/example)
-is a complete, commented example that exercises every port; start there.
+is a complete, commented example that exercises most ports; start there.
+
+Guild-scoped live command replacement was added in 1.1. Modules using
+`InteractionRouter.replace_guild_commands()` should depend on
+`kimi-agent-module-api>=1.1,<2` and require the host capability
+`discord.guild_commands.v1`.
+
+Version 1.2 adds typed modal forms and a narrow Components V2 layout model. Once a response uses
+that layout model, Discord requires every later edit of the same message to remain a layout.
+Modules using them should depend on `kimi-agent-module-api>=1.2,<2` and require
+`discord.modals.v1` and/or `discord.components_v2.v1`.