Metadata-Version: 2.4
Name: motosan-chat
Version: 0.3.0
Summary: Python chatbot framework with multi-platform channels and LLM agent loop
Author: motosan-dev
License-Expression: MIT
Keywords: chatbot,agent,llm,bot,framework
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn>=0.29; extra == "web"
Requires-Dist: sse-starlette>=2.0; extra == "web"
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == "telegram"
Provides-Extra: line
Requires-Dist: line-bot-sdk>=3.0; extra == "line"
Provides-Extra: discord
Requires-Dist: discord.py>=2.3; extra == "discord"
Provides-Extra: ai
Requires-Dist: motosan-ai>=0.2.0; extra == "ai"
Provides-Extra: full
Requires-Dist: fastapi>=0.110; extra == "full"
Requires-Dist: uvicorn>=0.29; extra == "full"
Requires-Dist: sse-starlette>=2.0; extra == "full"
Requires-Dist: python-telegram-bot>=21.0; extra == "full"
Requires-Dist: line-bot-sdk>=3.0; extra == "full"
Requires-Dist: discord.py>=2.3; extra == "full"
Requires-Dist: motosan-ai>=0.2.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"

# 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

```bash
pip install motosan-chat
```

Optional extras:

```bash
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

```python
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

```python
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

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

## Publishing

Build and verify package locally:

```bash
uv build
uv publish --dry-run
```

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