iamai

A compact Python + Rust runtime for cross-platform messaging, plugins, and auditable AI agents.

English · 中文

What Is iamai

iamai is an open-source runtime for chatbots, event-driven applications, and lightweight AI agents. It keeps platform protocols at the edge and lets business logic stay in ordinary async Python plugins.

Adapters normalize terminal, WebSocket, HTTP, Telegram, and OneBot payloads into stable Event, Message, and Context objects. The runtime then handles discovery, lifecycle, dispatch, rules, permissions, dependency injection, middleware, state, sessions, and observability. Selected message and normalization primitives run in a Rust extension through PyO3.

iamai is deliberately a runtime, not an all-in-one agent platform. You can use the built-in agent primitives, replace them, or run without an LLM at all.

How It Works

external platform
  -> Adapter validates and normalizes a payload
  -> Runtime matches handlers and evaluates Rule + Permission + DI
  -> Plugin executes inside event-scoped Context
  -> Context.reply() delegates the response back to the Adapter

The complete lifecycle, including admission, middleware, reload, and shutdown semantics, is documented in the architecture guide.

Features

• Protocol-neutral plugins: write against Event, Message, and Context, not platform payloads.
• Explicit extension model: load plugins and adapters by import path or standard Python entry points.
• Structured dispatch: commands, message handlers, event handlers, composable rules, permissions, DI, and middleware.
• Stateful workflows: memory, JSON, and SQLite state stores plus event-scoped session waiters.
• Operational controls: configuration validation, versioned JSON Schema, health and metrics views, audit events, and management commands.
• Safe development loop: plugin/config hot reload with rollback when the replacement fails.
• Agent building blocks: OpenAI-compatible model calls, tool metadata, approval hooks, traces, and output guardrails.
• Stable contracts: versioned serialization, lifecycle, configuration, deprecation, and extension conformance rules.

Quick Start

Install the latest stable package

python -m pip install iamai

The dev branch may be ahead of the latest PyPI release. To run the repository examples against the current source:

git clone https://github.com/retrofor/iamai.git
cd iamai
uv sync --locked --all-packages --group dev

# Validate the complete runtime configuration before starting it.
uv run --package echo-runtime iamai \
  --config examples/echo-runtime/config.terminal.toml config-check

# Start the local TerminalAdapter example.
uv run --package echo-runtime iamai \
  --config examples/echo-runtime/config.terminal.toml

At the prompt, enter:

/echo hello iamai

Write a plugin

from iamai import Context, Plugin, command


class HelloPlugin(Plugin):
    name = "hello"

    @command("hello")
    async def hello(self, ctx: Context) -> None:
        await ctx.reply("Hello from iamai.")

Add the plugin import path to [runtime].plugins, run config-check, and restart the runtime. The quickstart follows this path from configuration to the first reply.

Adapters

Adapters own the network and trust boundary. The adapter guide covers authentication, payload normalization, outbound calls, and production constraints.

Agent Building Blocks

iamai includes small, composable primitives for agent-style plugins. They are optional and do not change the core runtime model.

Runnable patterns live in the repository:

See the agent runtime guide for dependency and security boundaries.

Extensions and Contracts

Third-party packages can publish iamai.plugins and iamai.adapters entry points. The runtime provides deterministic discovery errors, versioned configuration schemas, secret annotations, and conformance helpers for independently distributed extensions.

The 1.x compatibility surface is documented rather than implied:

• Extension packaging and discovery
• Serialization contract
• Lifecycle contract
• Public API conformance matrix
• 0.3 to 1.0 migration guide

Examples and Documentation

Development

uv sync --locked --all-packages --group dev --group docs
uv run ruff check .
uv run python -m mypy
uv run pytest
cargo test --no-default-features
bash scripts/check_example_configs.sh
uv run sphinx-build -W --keep-going -b html docs docs/_build/html

Open pull requests against dev. Keep runtime behavior covered by tests and update the relevant contract documentation when changing a public boundary. See GitHub Issues and Discussions for active work.

License

MIT © iamai contributors

Acknowledgments

iamai draws lessons from NoneBot, Koishi, and AliceBot. Its agent examples are informed by the ReAct paper and the wider agent-runtime community.