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

kimi_agent_module_api/events.py

@@ -0,0 +1,140 @@
+"""Normalized core Discord events published on the module event bus.
+
+Each dataclass carries what a subscriber cannot re-fetch after the fact:
+deleted or pre-edit content, removed members' roles, role and timeout deltas,
+audit-log changes. Anything still live is fetched through a declared Discord
+action instead. Payloads never contain Discord SDK objects.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from kimi_agent_module_api.contracts import (
+    CORE_TOPIC_PREFIX,
+    AttachmentSnapshot,
+    InviteSnapshot,
+    MemberSnapshot,
+    MessageRef,
+    MessageSnapshot,
+)
+
+TOPIC_MESSAGE = f"{CORE_TOPIC_PREFIX}.message"
+TOPIC_MESSAGE_EDIT = f"{CORE_TOPIC_PREFIX}.message_edit"
+TOPIC_MESSAGE_DELETE = f"{CORE_TOPIC_PREFIX}.message_delete"
+TOPIC_MESSAGE_BULK_DELETE = f"{CORE_TOPIC_PREFIX}.message_bulk_delete"
+TOPIC_INVITE_CREATE = f"{CORE_TOPIC_PREFIX}.invite_create"
+TOPIC_INVITE_DELETE = f"{CORE_TOPIC_PREFIX}.invite_delete"
+TOPIC_MEMBER_JOIN = f"{CORE_TOPIC_PREFIX}.member_join"
+TOPIC_MEMBER_REMOVE = f"{CORE_TOPIC_PREFIX}.member_remove"
+TOPIC_MEMBER_UPDATE = f"{CORE_TOPIC_PREFIX}.member_update"
+TOPIC_AUDIT_LOG_ENTRY = f"{CORE_TOPIC_PREFIX}.audit_log_entry"
+
+CORE_TOPICS: frozenset[str] = frozenset(
+    {
+        TOPIC_MESSAGE,
+        TOPIC_MESSAGE_EDIT,
+        TOPIC_MESSAGE_DELETE,
+        TOPIC_MESSAGE_BULK_DELETE,
+        TOPIC_INVITE_CREATE,
+        TOPIC_INVITE_DELETE,
+        TOPIC_MEMBER_JOIN,
+        TOPIC_MEMBER_REMOVE,
+        TOPIC_MEMBER_UPDATE,
+        TOPIC_AUDIT_LOG_ENTRY,
+    }
+)
+
+
+@dataclass(frozen=True, slots=True)
+class MessageEvent:
+    message: MessageSnapshot
+    author_is_bot: bool
+
+
+@dataclass(frozen=True, slots=True)
+class MessageEditEvent:
+    ref: MessageRef
+    author_id: int | None
+    before_content: str | None
+    after_content: str | None
+    edited_at: float
+
+
+@dataclass(frozen=True, slots=True)
+class MessageDeleteEvent:
+    ref: MessageRef
+    author_id: int | None
+    cached_content: str | None
+    cached_attachments: tuple[AttachmentSnapshot, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class MessageBulkDeleteEvent:
+    refs: tuple[MessageRef, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class InviteCreateEvent:
+    invite: InviteSnapshot
+
+
+@dataclass(frozen=True, slots=True)
+class InviteDeleteEvent:
+    invite: InviteSnapshot
+
+
+@dataclass(frozen=True, slots=True)
+class MemberJoinEvent:
+    member: MemberSnapshot
+    account_created_at: float
+
+
+@dataclass(frozen=True, slots=True)
+class MemberRemoveEvent:
+    guild_id: int
+    user_id: int
+    roles_at_removal: tuple[int, ...]
+    display_name: str = ""
+    is_bot: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class MemberUpdateEvent:
+    guild_id: int
+    user_id: int
+    roles_added: tuple[int, ...]
+    roles_removed: tuple[int, ...]
+    timed_out_until_before: float | None
+    timed_out_until_after: float | None
+    nickname_before: str | None
+    nickname_after: str | None
+    display_name: str = ""
+    is_bot: bool = False
+    # Names for every role id in roles_added / roles_removed.
+    role_names: Mapping[int, str] = field(default_factory=dict)
+
+
+type AuditAction = Literal[
+    "ban", "unban", "kick", "timeout", "timeout_cleared", "member_update", "other"
+]
+
+
+@dataclass(frozen=True, slots=True)
+class AuditLogEntryEvent:
+    guild_id: int
+    entry_id: int
+    action: AuditAction
+    raw_action: str
+    actor_id: int | None
+    target_id: int | None
+    reason: str | None
+    changes: tuple[tuple[str, Any, Any], ...]
+    created_at: float
+    target_display_name: str | None = None
+    # Timeout expiry (unix seconds) for `timeout` actions.
+    until: float | None = None
+    # True when this bot performed the action (e.g. through a module command).
+    actor_is_self: bool = False

kimi_agent_module_api/images.py

@@ -0,0 +1,34 @@
+"""Pure image helpers that do not depend on a host runtime."""
+
+from __future__ import annotations
+
+SUPPORTED_IMAGE_MEDIA_TYPES = frozenset({"image/png", "image/jpeg", "image/gif", "image/webp"})
+IMAGE_FILENAME_SUFFIXES = (".png", ".jpg", ".jpeg", ".gif", ".webp")
+
+
+def looks_like_image_attachment(filename: str | None, content_type: str | None) -> bool:
+    """Use declared metadata as a cheap candidate filter before byte sniffing."""
+    declared = str(content_type or "").strip().lower()
+    name = str(filename or "").strip().lower()
+    return declared.startswith("image/") or name.endswith(IMAGE_FILENAME_SUFFIXES)
+
+
+def sniff_image_media_type(payload: bytes) -> str | None:
+    """Return a supported image media type from magic bytes, or None."""
+    if payload.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if payload.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if payload.startswith((b"GIF87a", b"GIF89a")):
+        return "image/gif"
+    if len(payload) >= 12 and payload[:4] == b"RIFF" and payload[8:12] == b"WEBP":
+        return "image/webp"
+    return None
+
+
+__all__ = [
+    "IMAGE_FILENAME_SUFFIXES",
+    "SUPPORTED_IMAGE_MEDIA_TYPES",
+    "looks_like_image_attachment",
+    "sniff_image_media_type",
+]

kimi_agent_module_api/py.typed

@@ -0,0 +1 @@
+

kimi_agent_module_api/settings.py

@@ -0,0 +1,33 @@
+"""Public settings declarations owned by the module API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pydantic_settings import BaseSettings
+
+
+@dataclass(frozen=True)
+class ModuleSetting:
+    """Presentation metadata for one explicitly exposed settings field."""
+
+    field: str
+    label: str
+    help: str = ""
+    choices: tuple[str, ...] = ()
+    minimum: int | float | None = None
+    multiline: bool = False
+
+
+@dataclass(frozen=True)
+class ModuleSettingsDefinition:
+    """A module's settings model and its operator-editable subset."""
+
+    name: str
+    label: str
+    model: type[BaseSettings]
+    exposed: tuple[ModuleSetting, ...]
+    environment_only: frozenset[str] = frozenset()
+
+
+__all__ = ["ModuleSetting", "ModuleSettingsDefinition"]