kimi-agent-module-api 1.0.0__tar.gz

kimi_agent_module_api-1.0.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,34 @@
+# 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/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "kimi-agent-module-api"
+version = "1.0.0"
+description = "Stable contracts for community-built assistant modules"
+requires-python = ">=3.14"
+authors = [{ name = "Webhead" }]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+dependencies = ["pydantic-settings>=2.14.2"]
+
+[project.urls]
+Documentation = "https://github.com/webhead2oo9/kimi-agent/blob/main/docs/modules.md"
+Issues = "https://github.com/webhead2oo9/kimi-agent/issues"
+Repository = "https://github.com/webhead2oo9/kimi-agent"
+
+[project.optional-dependencies]
+# kimi_agent_module_api.testing.MemoryStorage runs real SQL in unit tests.
+testing = ["aiosqlite"]
+
+[build-system]
+requires = ["setuptools>=84"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kimi_agent_module_api = ["py.typed"]

kimi_agent_module_api-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kimi_agent_module_api-1.0.0/src/kimi_agent_module_api/__init__.py

@@ -0,0 +1,175 @@
+"""Stable public contracts for trusted, installed assistant modules."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol, TypeVar
+
+from pydantic_settings import BaseSettings
+
+from kimi_agent_module_api.contracts import (
+    ConfigSnapshot,
+    RoleSnapshot,
+    render_guild_settings,
+    DiscordActions,
+    EventBus,
+    GuildSettings,
+    GuildSettingsSchema,
+    HealthReporter,
+    InviteSnapshot,
+    InteractionRouter,
+    ModuleHttp,
+    ModulePermissions,
+    ModuleStorage,
+    ScopedModuleMigration,
+    ProposalActor,
+    ProposalError,
+    ProposalRef,
+    ProposalService,
+    ProposalState,
+    Scheduler,
+    ServiceDeclaration,
+    ServiceRegistry,
+    ServiceRequirement,
+    TrustLookup,
+)
+from kimi_agent_module_api.settings import ModuleSetting, ModuleSettingsDefinition
+from kimi_agent_module_api.tools import (
+    ModuleToolContext,
+    ModuleToolHandler,
+    ModuleToolRegistry,
+)
+from kimi_agent_module_api.trust import TrustTier
+
+MODULE_API_VERSION = 1
+MODULE_ENTRYPOINT_GROUP = "kimi_agent.modules"
+# Capabilities every compatible host advertises regardless of configuration.
+BASELINE_CAPABILITIES: frozenset[str] = frozenset({"discord.history.v1", "proposals.v2"})
+
+_SettingsT = TypeVar("_SettingsT", bound=BaseSettings)
+
+
+@dataclass(frozen=True)
+class ModuleCapabilities:
+    available: frozenset[str]
+    members_intent: bool
+    message_content_intent: bool
+
+    def require(self, name: str) -> None:
+        if name not in self.available:
+            raise RuntimeError(f"the host does not provide required capability {name!r}")
+
+
+class AppModule(Protocol):
+    scoped_migrations: Sequence[ScopedModuleMigration]
+
+    async def start(self, ctx: ModuleRuntimeContext) -> None: ...
+
+    async def close(self) -> None: ...
+
+
+@dataclass(frozen=True)
+class ModuleSpec:
+    name: str
+    version: str
+    create: Callable[[ModuleLoadContext], AppModule]
+    api_version: int = MODULE_API_VERSION
+    dependencies: tuple[str, ...] = ()
+    settings: ModuleSettingsDefinition | None = None
+    requires_capabilities: tuple[str, ...] = ()
+    activation_capabilities: tuple[str, ...] = ()
+    permissions: ModulePermissions = field(default_factory=ModulePermissions)
+    guild_settings: GuildSettingsSchema | None = None
+    provides: tuple[ServiceDeclaration, ...] = ()
+    consumes: tuple[ServiceRequirement, ...] = ()
+    table_aliases: Mapping[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class ModuleLoadContext:
+    """What ``ModuleSpec.create`` receives.
+
+    ``create()`` is pure wiring: read prepared settings, register LLM tools,
+    construct the module object. No migration has run and no dependency has
+    started, so nothing here reaches storage, services, or Discord; that work
+    belongs in ``start()``. The tool registry is sealed once loading finishes,
+    so tools cannot be registered later from ``start()`` either.
+    """
+
+    capabilities: ModuleCapabilities
+    registry: ModuleToolRegistry
+    module_settings: BaseSettings | None
+    # Host sinks behind the two convenience methods below. Tests build a
+    # context with ``kimi_agent_module_api.testing.load_context``.
+    label_sink: Callable[[Mapping[str, str]], None]
+    surface_sink: Callable[[str, Sequence[str]], None]
+
+    def settings_for(self, settings_type: type[_SettingsT]) -> _SettingsT:
+        if self.module_settings is None or not isinstance(self.module_settings, settings_type):
+            raise TypeError(f"prepared module settings are not {settings_type.__name__}")
+        return self.module_settings
+
+    def register_tool_labels(self, labels: Mapping[str, str]) -> None:
+        """Gerund phrases shown while a tool runs, e.g. ``{"give_kudos": "Giving kudos"}``."""
+        self.label_sink(labels)
+
+    def declare_surface_tools(self, surface: str, names: Sequence[str]) -> None:
+        """Declare which tools belong to a named evaluation surface."""
+        self.surface_sink(surface, names)
+
+
+@dataclass(frozen=True)
+class ModuleRuntimeContext:
+    """Runtime ports supplied to one module after it has been loaded."""
+
+    module_name: str
+    is_guild_active: Callable[[int], bool]
+    current_config_dir: Callable[[], Path]
+    capabilities: ModuleCapabilities
+    events: EventBus
+    scheduler: Scheduler
+    storage: ModuleStorage
+    health: HealthReporter
+    discord: DiscordActions
+    interactions: InteractionRouter
+    http: ModuleHttp
+    services: ServiceRegistry
+    trust: TrustLookup
+    guild_settings: GuildSettings | None = None
+    proposals: ProposalService | None = None
+    raw_bot: Any = None
+    raw_storage: Any = None
+
+
+__all__ = [
+    "BASELINE_CAPABILITIES",
+    "MODULE_API_VERSION",
+    "MODULE_ENTRYPOINT_GROUP",
+    "AppModule",
+    "ConfigSnapshot",
+    "GuildSettingsSchema",
+    "InviteSnapshot",
+    "ModuleCapabilities",
+    "ModuleLoadContext",
+    "ModulePermissions",
+    "ModuleRuntimeContext",
+    "ModuleSetting",
+    "ModuleSettingsDefinition",
+    "ModuleSpec",
+    "ModuleToolContext",
+    "ModuleToolHandler",
+    "ModuleToolRegistry",
+    "ProposalActor",
+    "ProposalError",
+    "ProposalRef",
+    "ProposalService",
+    "ProposalState",
+    "RoleSnapshot",
+    "ScopedModuleMigration",
+    "ServiceDeclaration",
+    "ServiceRequirement",
+    "TrustTier",
+    "render_guild_settings",
+]