Metadata-Version: 2.4
Name: kimi-agent-module-api
Version: 1.3.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 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`.

Version 1.3 adds cached author classification to message-deletion events:
`MessageDeleteEvent.author_is_bot` and `MessageBulkDeleteEvent.bot_message_ids`.
The values remain unknown for messages that were absent from Discord's cache.

## Testing the SDK

From this package directory, run its tests without installing the Kimi application:

```console
uv run --isolated --group test python -m pytest -q
```
