kimi-agent-module-api 1.0.0__py3-none-any.whl

kimi_agent_module_api/tools.py

@@ -0,0 +1,63 @@
+"""The LLM-tool surface: what a module registers at load and what a handler receives."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Coroutine, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+from kimi_agent_module_api.trust import TrustTier
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleToolContext:
+    """Who is calling a module tool, and from where.
+
+    Ids are Discord snowflakes as ``int``, matching every other SDK type.
+    ``guild_id`` is ``None`` only for a tool registered with
+    ``guild_only=False`` and called from a DM or personal chat; the host hides
+    guild-only tools there. When ``guild_id`` is set, the host has already
+    confirmed the module is active in that guild. ``channel_id`` is ``None``
+    in personal chat, which is a slash interaction rather than a channel.
+    """
+
+    user_id: int
+    user_name: str
+    guild_id: int | None
+    channel_id: int | None
+    thread_id: int | None
+    trust_tier: TrustTier
+    # Operator per-tool configuration from ``<CONFIG_DIR>/tools/<tool>.md``.
+    tool_configs: Mapping[str, Mapping[str, Any]] = field(default_factory=dict)
+
+
+type ModuleToolHandler = Callable[[dict[str, Any], ModuleToolContext], Coroutine[Any, Any, str]]
+
+
+class ModuleToolRegistry(Protocol):
+    """Tool registration supported by every compatible host.
+
+    Valid only inside ``ModuleSpec.create``; the host seals it afterwards.
+    ``searchable`` tools stay hidden until the model activates them with
+    ``browse_tools``. A tool is visible only where its module is active; with
+    ``guild_only`` (the default) it is also hidden from DMs and personal chat,
+    so its handler always sees a guild. ``guild_ids`` further scopes a tool to
+    specific guilds (``None`` is everywhere; an empty set is nowhere).
+    """
+
+    def register(
+        self,
+        name: str,
+        description: str,
+        parameters: dict[str, Any],
+        handler: ModuleToolHandler,
+        *,
+        min_tier: TrustTier = TrustTier.MEMBER,
+        searchable: bool = False,
+        owner_only: bool = False,
+        guild_only: bool = True,
+        guild_ids: frozenset[int] | None = None,
+    ) -> None: ...
+
+
+__all__ = ["ModuleToolContext", "ModuleToolHandler", "ModuleToolRegistry"]

kimi_agent_module_api/trust.py

@@ -0,0 +1,36 @@
+"""Trust tiers shared by module declarations and the host runtime."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+_TIER_ORDER = {"member": 0, "regular": 1, "staff": 2}
+
+
+class TrustTier(Enum):
+    STAFF = "staff"
+    REGULAR = "regular"
+    MEMBER = "member"
+
+    def __ge__(self, other: object) -> bool:
+        if not isinstance(other, TrustTier):
+            return NotImplemented
+        return _TIER_ORDER[self.value] >= _TIER_ORDER[other.value]
+
+    def __gt__(self, other: object) -> bool:
+        if not isinstance(other, TrustTier):
+            return NotImplemented
+        return _TIER_ORDER[self.value] > _TIER_ORDER[other.value]
+
+    def __le__(self, other: object) -> bool:
+        if not isinstance(other, TrustTier):
+            return NotImplemented
+        return _TIER_ORDER[self.value] <= _TIER_ORDER[other.value]
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, TrustTier):
+            return NotImplemented
+        return _TIER_ORDER[self.value] < _TIER_ORDER[other.value]
+
+
+__all__ = ["TrustTier"]

kimi_agent_module_api-1.0.0.dist-info/METADATA

@@ -0,0 +1,51 @@
+Metadata-Version: 2.4
+Name: kimi-agent-module-api
+Version: 1.0.0
+Summary: Stable contracts for community-built assistant modules
+Author: Webhead
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/webhead2oo9/kimi-agent/blob/main/docs/modules.md
+Project-URL: Issues, https://github.com/webhead2oo9/kimi-agent/issues
+Project-URL: Repository, https://github.com/webhead2oo9/kimi-agent
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic-settings>=2.14.2
+Provides-Extra: testing
+Requires-Dist: aiosqlite; extra == "testing"
+Dynamic: license-file
+
+# Kimi Agent Module API
+
+The stable, host-independent contracts for building Kimi application modules:
+separately installed packages that add commands, LLM tools, background jobs,
+event handlers, per-guild settings, and durable data to a Kimi deployment.
+
+This package contains no bot runtime, Discord client, database
+implementation, or module loader. It exports:
+
+- `ModuleSpec`, `ModuleLoadContext`, `ModuleRuntimeContext`: the declaration a
+  module publishes and the two contexts the host hands it.
+- `kimi_agent_module_api.contracts`: every runtime port as a `typing.Protocol`
+  (storage, scheduler, events, Discord actions, interactions, HTTP, services,
+  trust, proposals, health) plus the validators the host runs at preflight.
+- `kimi_agent_module_api.events`: the normalized `discord.*` event payloads.
+- `kimi_agent_module_api.testing`: a fake for every port, `load_context()` for
+  exercising `create()`, and `MemoryStorage` (install the `testing` extra) so a
+  module can unit test itself with only this package installed.
+
+A module exposes a `ModuleSpec` through the `kimi_agent.modules` entry-point
+group:
+
+```toml
+[project]
+dependencies = ["kimi-agent-module-api>=1,<2"]
+
+[project.entry-points."kimi_agent.modules"]
+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.

kimi_agent_module_api-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+kimi_agent_module_api/__init__.py,sha256=SnlPlbkJGhLInzqnTZGO-j-WfI8GCHo1fDviNZAnd5o,5435
+kimi_agent_module_api/contracts.py,sha256=y-Epb_IivNO7DbCQuAoenjK59y5rkzQNVch3P5hQ7DI,36247
+kimi_agent_module_api/events.py,sha256=0O6KyXgO3Pt-lLczySnfH7Oz0NS-wcD73UIQItgYUWk,3835
+kimi_agent_module_api/images.py,sha256=eC-HYBxL-3oTSQFtCY9suaacCMdKeY0SIhIjXviXJmU,1256
+kimi_agent_module_api/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+kimi_agent_module_api/settings.py,sha256=B_C8erjC3xiVAt-Dsa_pzJup0sdH6crukRPoI0Dy3AA,784
+kimi_agent_module_api/testing.py,sha256=3xm71UNapomQcnl7yoeWCrO5n5CcbdnwzAdJG6WoqTQ,34142
+kimi_agent_module_api/tools.py,sha256=IrhxJCY1G78-82Rqr45m2GypdDy_yFNlaUUR4yKRQ0I,2288
+kimi_agent_module_api/trust.py,sha256=JbIwBy6c1osBkdLT0si3hjsjfnLfhaZwlacsI_-xuS8,1067
+kimi_agent_module_api-1.0.0.dist-info/licenses/LICENSE,sha256=uYrNYbmEjOZrEU64qvFgrljmosb1-bUKnE9fa9pMuSY,1064
+kimi_agent_module_api-1.0.0.dist-info/METADATA,sha256=-X5pYh8Tro6Hg36XfcOQyywCR09U4CiBIdKo48On9yo,2226
+kimi_agent_module_api-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+kimi_agent_module_api-1.0.0.dist-info/top_level.txt,sha256=kOf2Pv96Xa3yE4NUlKxGvvEVKw_-b_ARe9e7OVk-_j0,22
+kimi_agent_module_api-1.0.0.dist-info/RECORD,,

kimi_agent_module_api-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kimi_agent_module_api-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Webhead
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kimi_agent_module_api-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+kimi_agent_module_api