motosan-chat (Python)

motosan-chat is a Python chatbot framework with a unified event model, channel adapters, and an LLM agent loop with tool-calling support.

This package mirrors the Rust-side architecture and provides a Python-first developer experience for building multi-platform chatbots.

Features

• Core runtime: Bot, Thread, IncomingEvent, and Channel protocol
• Agent runtime: AgentLoop, LlmClient, message/tool-call chain model
• Tool system: ToolDef, ToolResult, ToolContext, @tool decorator
• Channels:
  • Web (FastAPI + SSE)
  • Telegram (polling adapter)
  • LINE (webhook adapter)
  • Discord (gateway adapter)
• AI adapter: MotosanAiClient for motosan-ai

Installation

pip install motosan-chat

Optional extras:

pip install "motosan-chat[web]"
pip install "motosan-chat[telegram]"
pip install "motosan-chat[line]"
pip install "motosan-chat[discord]"
pip install "motosan-chat[ai]"
pip install "motosan-chat[full]"

Quick Start

from motosan_chat import Bot
from motosan_chat.channels import WebChannel


async def handler(thread):
    await thread.send(f"echo: {thread.event.content}")


channel = WebChannel()
bot = Bot.builder().channel(channel).handler(handler).build()
await bot.run()

Agent + Tools

from motosan_chat import AgentLoop, Message, ToolContext, ToolResult, tool


@tool(
    name="get_weather",
    description="Get weather by city",
    schema={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
)
async def get_weather(args: dict, ctx: ToolContext) -> ToolResult:
    return ToolResult.text(f"Sunny in {args['city']}")


loop_ = AgentLoop(tools=[get_weather])
# result = await loop_.run(llm_client, thread, [Message.user("weather in Tokyo?")])

Development

uv sync --extra full --extra dev
uv run ruff check motosan_chat/ tests/
uv run pytest tests/ -v

Publishing

Build and verify package locally:

uv build
uv publish --dry-run

GitHub Actions publish workflow is triggered by tags that match python-v*.