Metadata-Version: 2.4
Name: maysii
Version: 1.2.0
Summary: Multi-channel AI gateway with extensible messaging integrations
Project-URL: Homepage, https://github.com/maythyai/maysii
Project-URL: Documentation, https://github.com/maythyai/maysii/tree/master/docs
Project-URL: Repository, https://github.com/maythyai/maysii
Project-URL: Issues, https://github.com/maythyai/maysii/issues
Project-URL: Changelog, https://github.com/maythyai/maysii/releases
Author-email: CHEN SAI <chensai@gmail.com>
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Keywords: agent,ai,anthropic,chatbot,gateway,llm,maysii,mcp,multi-channel,openai,skills
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: aiofiles>=24
Requires-Dist: apscheduler>=3.10
Requires-Dist: cachetools>=5.5
Requires-Dist: httpx>=0.28
Requires-Dist: json5>=0.10
Requires-Dist: jsonschema>=4.20
Requires-Dist: openai>=1.60
Requires-Dist: pydantic>=2.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13
Requires-Dist: typer>=0.15
Provides-Extra: all
Requires-Dist: aiogram>=3.17; extra == 'all'
Requires-Dist: discord-py>=2.4; extra == 'all'
Requires-Dist: edge-tts>=7; extra == 'all'
Requires-Dist: fastapi>=0.115; extra == 'all'
Requires-Dist: google-generativeai>=0.8; extra == 'all'
Requires-Dist: matrix-nio>=0.24; extra == 'all'
Requires-Dist: mss>=9; extra == 'all'
Requires-Dist: openpyxl>=3.1; extra == 'all'
Requires-Dist: pillow>=11; extra == 'all'
Requires-Dist: playwright>=1.50; extra == 'all'
Requires-Dist: pypdf>=5; extra == 'all'
Requires-Dist: python-docx>=1.1; extra == 'all'
Requires-Dist: python-pptx>=1.0; extra == 'all'
Requires-Dist: slack-bolt>=1.22; extra == 'all'
Requires-Dist: websockets>=14; extra == 'all'
Provides-Extra: channels
Requires-Dist: aiogram>=3.17; extra == 'channels'
Requires-Dist: discord-py>=2.4; extra == 'channels'
Requires-Dist: slack-bolt>=1.22; extra == 'channels'
Provides-Extra: dev
Requires-Dist: aiohttp>=3.9; extra == 'dev'
Requires-Dist: aiosqlite>=0.20; extra == 'dev'
Requires-Dist: cryptography>=42; extra == 'dev'
Requires-Dist: fastapi>=0.115; extra == 'dev'
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pyjwt>=2.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest-cov>=6; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: sqlalchemy>=2.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Requires-Dist: types-setuptools>=70; extra == 'dev'
Requires-Dist: websockets>=14; extra == 'dev'
Provides-Extra: docker
Requires-Dist: aiogram>=3.17; extra == 'docker'
Requires-Dist: discord-py>=2.4; extra == 'docker'
Requires-Dist: edge-tts>=7; extra == 'docker'
Requires-Dist: fastapi>=0.115; extra == 'docker'
Requires-Dist: google-generativeai>=0.8; extra == 'docker'
Requires-Dist: matrix-nio>=0.24; extra == 'docker'
Requires-Dist: mss>=9; extra == 'docker'
Requires-Dist: openpyxl>=3.1; extra == 'docker'
Requires-Dist: pillow>=11; extra == 'docker'
Requires-Dist: playwright>=1.50; extra == 'docker'
Requires-Dist: pypdf>=5; extra == 'docker'
Requires-Dist: python-docx>=1.1; extra == 'docker'
Requires-Dist: python-pptx>=1.0; extra == 'docker'
Requires-Dist: slack-bolt>=1.22; extra == 'docker'
Requires-Dist: websockets>=14; extra == 'docker'
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.8; extra == 'gemini'
Provides-Extra: llamacpp
Requires-Dist: huggingface-hub>=0.20; extra == 'llamacpp'
Requires-Dist: llama-cpp-python>=0.3; extra == 'llamacpp'
Provides-Extra: matrix
Requires-Dist: matrix-nio>=0.24; extra == 'matrix'
Provides-Extra: media
Requires-Dist: mss>=9; extra == 'media'
Requires-Dist: pillow>=11; extra == 'media'
Requires-Dist: playwright>=1.50; extra == 'media'
Provides-Extra: mlx
Requires-Dist: huggingface-hub>=0.20; extra == 'mlx'
Requires-Dist: mlx-lm>=0.10; extra == 'mlx'
Provides-Extra: office
Requires-Dist: openpyxl>=3.1; extra == 'office'
Requires-Dist: pypdf>=5; extra == 'office'
Requires-Dist: python-docx>=1.1; extra == 'office'
Requires-Dist: python-pptx>=1.0; extra == 'office'
Provides-Extra: perf
Requires-Dist: aiosqlite>=0.20; extra == 'perf'
Requires-Dist: uvloop>=0.21; (sys_platform != 'win32') and extra == 'perf'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Provides-Extra: saml
Requires-Dist: python3-saml>=1.16; extra == 'saml'
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == 'server'
Requires-Dist: websockets>=14; extra == 'server'
Provides-Extra: server-standard
Requires-Dist: fastapi>=0.115; extra == 'server-standard'
Requires-Dist: websockets>=14; extra == 'server-standard'
Provides-Extra: voice
Requires-Dist: edge-tts>=7; extra == 'voice'
Provides-Extra: whatsapp
Requires-Dist: neonize>=0.3.14; extra == 'whatsapp'
Description-Content-Type: text/markdown

# Maysii

[![PyPI version](https://img.shields.io/pypi/v/maysii.svg)](https://pypi.org/project/maysii/)
[![Python](https://img.shields.io/pypi/pyversions/maysii.svg)](https://pypi.org/project/maysii/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/maythyai/maysii/actions/workflows/test.yml/badge.svg)](https://github.com/maythyai/maysii/actions)

**Multi-channel AI Gateway** — Connect your AI Agent to 28+ messaging platforms through a unified gateway.

Maysii is a Python rewrite of [openclaw/openclaw](https://github.com/openclaw/openclaw), featuring MCP tool integration, 20+ built-in tools, cross-platform UI (Web/Desktop/Mobile), and an OpenAI-compatible HTTP API.

> **[Documentation](docs/README.md)** — Quick Start, Installation Guide, Configuration, Concepts, Troubleshooting.

---

## Features

### 🎛 Agent Harness Architecture (v5.0)

Six-component production-grade agent runtime based on the [Agent Harness Design Guide](docs/architecture/agent-harness-design-guide.md):

| Component | Module | Description |
|-----------|--------|-------------|
| **E** Execution Loop | `harness/loop.py` | Observe-think-act cycle with dual-mode tool resolution, provider fallback, hard termination |
| **T** Tool Registry | `harness/tool_registry.py` | 9-field ToolMetadata, JSON Schema validation, RBAC, RAG-powered ToolIndex, auto-indexing |
| **C** Context Manager | `harness/context_manager.py` | Hybrid injection, layered compression, token budget, Anthropic cache control |
| **S** State Store | `harness/state_store.py` | 3-tier storage (Working/Session/Persistent), checkpoint/recovery, execution log |
| **L** Lifecycle Hooks | `harness/hooks.py` | 6 hook points: permission, rate-limit, audit, danger-block, mask, policy |
| **V** Evaluation | `harness/evaluation.py` | Component eval, trajectory analysis, LLM-as-Judge, VerifierSubAgent |

Plus **Multi-Agent Orchestration** (5 engines), **Deep Research Engine**, **Event Bus**, **EncryptedText**, **Incremental Migrations**, and **Skills Self-Repair System**.

### 🔌 Context Engine Plugins (v5.0)

Pluggable context management architecture — swap compression strategies without touching core code:

| Plugin | Strategy | Description |
|--------|----------|-------------|
| DefaultContextPlugin | summarize + truncate | LLM-powered summarization with structured templates, truncate fallback |
| DagCompressorPlugin | 4-layer DAG | critical (keep) / important (summarize) / contextual (extract facts) / transient (drop) |

```python
from maysii.agents.context.plugins import ContextEnginePluginRegistry, DagCompressorPlugin
registry = ContextEnginePluginRegistry.get_instance()
registry.register(DagCompressorPlugin(), set_default=True)
```

See [Context Engine Plugin Guide](docs/context-engine-plugin.md) for custom plugin development.

### 🧭 Agent Routing (v5.0)

Channel-aware agent routing with 7-tier priority matching and persistent thread bindings:

```python
from maysii.routing import AgentRouter, RoutingRule
router = AgentRouter(default_agent_id="main")
router.register_rule(RoutingRule(channel_type="telegram", agent_id="telegram-bot"))
agent = router.match("telegram", sender_id="VIP123")  # → "telegram-bot"
```

| Component | Description |
|-----------|-------------|
| AgentRouter | Rule-based routing with channel/peer/guild/team priority tiers |
| ThreadBindingManager | SQLite-backed persistent agent-to-thread bindings with TTL |
| RouteAndBind | One-step resolve: check cache → router → persist binding |

### 🤖 Agent Runtime

- Multi-provider LLM streaming (OpenAI, Anthropic, Google Gemini, Ollama, and 25+ more)
- Provider resilience: dead-host cooldown, auto-fallback, shared connection pool, auto-detection
- Anthropic prompt caching with ephemeral markers — ~85% cache hit rate
- Reasoning model support: 7 thinking model patterns (Qwen3, DeepSeek-R1, DeepSeek-V3, etc.)
- 20+ built-in tools: file I/O, grep, find, exec, web search/fetch, browser, memory, cron, TTS
- MCP (Model Context Protocol) — stdio, HTTP, and Streamable HTTP transports + OAuth
- Docker sandbox for isolated tool execution (CPU/memory limits, network isolation)
- Task planner with multi-step Plan/Step decomposition
- Meta-Tool system: `invoke_skill`, `invoke_channel`, `invoke_memory`, `invoke_mcp`
- User interrupt system (cancel/append mid-generation)
- Sub-agent orchestration (spawn, steer, kill)
- SKILL.md-based skill injection
- Skills self-repair via SkillLearner teacher-escalation loop
- Deep Research engine — search→read→synthesize→report pipeline

### 🧠 Memory System

- Context compaction with LLM-based summarization
- Cross-session context recovery via ContextStore (SQLite-persisted)
- Hybrid search: SQLite FTS5 + LanceDB vector search
- Active memory with auto-recall and auto-capture hooks
- Daily summary service for session consolidation
- Wiki System (Claim/Evidence model with contradiction detection, GitLab-compatible)
- Dreaming System — 3-phase memory consolidation (LIGHT/DEEP/REM) with 6-dimensional scoring
- Recall cache with TTL-based session isolation

### 💬 28+ Messaging Channels

Telegram, Discord, Slack, WhatsApp, Signal, iMessage, Feishu/Lark, DingTalk, QQ, MS Teams, Matrix, IRC, LINE, Twitch, Nostr, X (Twitter), BlueBubbles, Google Chat, Mattermost, Nextcloud Talk, Synology Chat, Tlon/Urbit, Zalo, OneBot, Web Chat, Voice Call, and more.

Unified `ChannelPlugin` interface — each channel is a self-contained module with DM/group policy, allowFrom whitelists, mention gating, and agent routing.

### 🚪 Gateway

- FastAPI + WebSocket v3 bidirectional protocol
- OpenAI-compatible HTTP API (`/v1/chat/completions`, `/v1/responses`, `/v1/models`)
- 30+ RPC methods: chat, sessions, agents, channels, config, models, browser, cron, plan, backup, tools
- REST API for auth, devices, webhooks, usage, logs, plans, cron, skills
- Config hot-reload, channel health monitoring
- MkDocs documentation site mounted on gateway

### 🖥 Cross-Platform UI

- **Next.js 15** Web Application
- **Tauri 2.x** Desktop App — Rust shell wrapping the Web app (no native frontend; macOS, Linux, Windows)
- **Expo React Native** Mobile App (iOS, Android)
- 17+ pages: Chat, Agents, Channels, Sessions, Usage, Cron, Plans, Skills, Nodes, Voice, Logs, Debug, Config, System, Settings

### 🛡 Security

- Command exec approval rules
- Workspace sandbox boundary
- SSRF prevention
- Plaintext secret scanning
- Configuration security audit
- EncryptedText (SQLAlchemy TypeDecorator with Fernet encryption)
- Internal token authentication (loopback-only bypass)

---

## Quick Start

### Requirements

- Python >= 3.10
- An LLM API key (OpenAI, Anthropic, Google Gemini, Ollama, or any OpenAI-compatible provider)

### Install

```bash
# One-line install (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/maythyai/maysii/master/scripts/install.sh | bash

# From PyPI (recommended)
pip install maysii

# Or via pipx (isolated environment)
pipx install maysii

# macOS via Homebrew
brew install maythyai/tap/maysii

# From source (development)
pip install -e ".[dev,ui]"

# Docker
docker run -it --rm -e OPENAI_API_KEY="sk-..." ghcr.io/maythyai/maysii:latest maysii agent "Hello"
```

### Optional Extras

| Extra | What it adds |
|-------|-------------|
| `ui` | TypeScript client (Web/Desktop/Mobile) |
| `matrix` | Matrix channel (matrix-nio) |
| `whatsapp` | WhatsApp channel (neonize) |
| `voice` | Voice TTS (edge-tts) |
| `dev` | Testing + linting (pytest, ruff, mypy) |

### First Run

```bash
# 1. Interactive setup
maysii setup --wizard

# 2. Chat with the agent
maysii agent "What is the weather in Tokyo?"

# 3. Start the gateway
maysii gateway

# 4. Launch the desktop UI
maysii ui

# 5. Or launch as a web app
maysii ui --web --port 18776
```

---

## CLI Reference

### Setup & Run

| Command | Description |
|---------|-------------|
| `maysii setup --wizard` | Interactive setup wizard |
| `maysii agent <message>` | Run a single agent turn |
| `maysii gateway` | Start the gateway server |
| `maysii node` | Start a headless node host |
| `maysii status [--deep]` | Show status / probe health |
| `maysii doctor` | Run diagnostics |

### Configuration

| Command | Description |
|---------|-------------|
| `maysii config list` | Show all config |
| `maysii config get <key>` | Get a config value |
| `maysii config set <key> <value>` | Set a config value |

### Agents & Routing

| Command | Description |
|---------|-------------|
| `maysii agents list` | List agents |
| `maysii agents add <name> --model <model>` | Add an agent |
| `maysii mode status` | Show active collaboration mode |
| `maysii mode switch <mode>` | Switch orchestration mode |
| `maysii skills list` | List available skills |
| `maysii exec-policy show\|allow\|deny` | Manage tool execution policies |

### Channels & Messages

| Command | Description |
|---------|-------------|
| `maysii channels list` | List channels |
| `maysii channels status` | Connection status |
| `maysii message send <channel> <text>` | Send a message through a channel |

### Auth, MCP & Devices

| Command | Description |
|---------|-------------|
| `maysii auth login --provider <name>` | Add API key profile |
| `maysii auth status` | Show auth profiles |
| `maysii mcp status` | Show MCP servers and tools |
| `maysii mcp list-tools` | List available MCP tools |
| `maysii devices list` | List paired devices |

### Sessions & Models

| Command | Description |
|---------|-------------|
| `maysii sessions list` | List agent sessions |
| `maysii models list` | Show available models |
| `maysii import chatgpt <path>` | Import ChatGPT export |

### Security & System

| Command | Description |
|---------|-------------|
| `maysii security audit` | Run security audit |
| `maysii service install` | Install as system service |
| `maysii logs [--follow]` | Tail runtime logs |
| `maysii health` | Quick health check (Docker HEALTHCHECK) |

### Memory & Knowledge

| Command | Description |
|---------|-------------|
| `maysii active-memory on\|off` | Toggle Active Memory |
| `maysii wiki init` | Initialize Wiki Vault |
| `maysii token-aware init\|scan\|status` | Token optimization tools |

---

## Supported Channels

| Channel | Library | Type |
|---------|---------|------|
| Telegram | aiogram | Core |
| Discord | discord.py | Core |
| Slack | slack-bolt (Socket Mode) | Core |
| WhatsApp | neonize (Baileys) | Core |
| Signal | signal-cli JSON-RPC | Core |
| iMessage | imsg JSON-RPC | Core |
| X (Twitter) | X API v2 | Core |
| Web | Built-in | Core |
| Feishu / Lark | Open Platform API | Extension |
| DingTalk | Stream Mode | Extension |
| QQ | QQ Bot | Extension |
| MS Teams | Bot Framework | Extension |
| Matrix | matrix-nio | Extension |
| IRC | Native TCP/TLS | Extension |
| LINE | Messaging API | Extension |
| Twitch | IRC/TLS | Extension |
| Nostr | NIP-04 relay | Extension |
| BlueBubbles | REST webhook | Extension |
| Google Chat | OAuth webhook | Extension |
| Mattermost | REST + WebSocket | Extension |
| Nextcloud Talk | REST webhook | Extension |
| Synology Chat | Incoming webhook | Extension |
| Tlon / Urbit | HTTP API | Extension |
| Zalo | Official API | Extension |
| Voice Call | Twilio | Extension |

---

## Supported LLM Providers

### Core Providers

| Provider | Models |
|----------|--------|
| OpenAI | GPT-4o, GPT-4o-mini, o1, o3-mini |
| Anthropic | Claude Opus 4.8, Claude Sonnet, Claude Haiku |
| Google Gemini | Gemini 2.0 Flash, Gemini Pro |
| Ollama | Any locally hosted model |

### OpenAI-Compatible Providers

OpenRouter, Together AI, Groq, Fireworks AI, Perplexity, and 15+ more.

### Chinese Providers

DeepSeek, Moonshot/Kimi, Zhipu/GLM, Qwen/DashScope, Volcengine/Doubao, MiniMax, Qianfan/ERNIE.

---

## MCP (Model Context Protocol)

Connect external tool servers via [MCP](https://modelcontextprotocol.io). Config format is compatible with Claude Desktop and Cursor.

Add to `~/.maysii/maysii.json`:

```json
{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      },
      "remote-api": {
        "url": "https://example.com/mcp/",
        "transportType": "streamable-http",
        "headers": { "Authorization": "Bearer xxx" }
      }
    }
  }
}
```

Supports stdio, HTTP, and Streamable HTTP (SSE+POST) transports. Built-in MCP servers include Memory, RAG, and Image Generation.

---

## Configuration

Maysii stores its state in `~/.maysii/`:

```
~/.maysii/
├── maysii.json          # Main config (JSON5 with comments)
├── auth-profiles.json   # API keys and OAuth credentials
├── data/                # ContextStore, ThreadBindings, Webhooks (SQLite)
├── sessions/            # Agent session transcripts (JSONL)
└── workspace/           # Workspace files (AGENTS.md, HEARTBEAT.md, etc.)
```

### Example Config

```json5
{
  "models": {
    "providers": {
      "openai": { "apiKey": "sk-..." },
      "anthropic": { "apiKey": "sk-ant-..." }
    }
  },
  "agents": {
    "defaults": { "model": "claude-sonnet-4-20250514", "provider": "anthropic" }
  },
  "channels": {
    "defaults": { "agentId": "main" },
    "telegram": { "token": "123:ABC", "agentId": "assistant" },
    "discord": { "token": "xyz" }
  },
  "auth": {
    "profiles": {
      "openai-work": { "provider": "openai", "apiKey": "${OPENAI_WORK_KEY}" }
    }
  },
  "context": {
    "engine": {
      "plugin": "dag-compressor",
      "compaction": { "maxTokens": 128000, "strategy": "dag" }
    }
  },
  "routing": {
    "rules": [
      { "channel": "telegram", "sender": "VIP123", "agent": "vip-assistant" }
    ]
  }
}
```

### Environment Variables

| Variable | Description |
|----------|-------------|
| `OPENAI_API_KEY` | OpenAI API key |
| `ANTHROPIC_API_KEY` | Anthropic API key |
| `GOOGLE_API_KEY` | Google AI API key |
| `TELEGRAM_BOT_TOKEN` | Telegram bot token |
| `MAYSII_GATEWAY_PORT` | Gateway port (default: 18777) |

---

## Architecture

```
maysii/
├── src/maysii/              # Python backend (755+ files)
│   ├── agents/              # Agent runtime
│   │   ├── harness/         # Agent Harness 6-component (25 modules)
│   │   │   ├── loop.py              # E: ExecutionLoop
│   │   │   ├── tool_registry.py     # T: Tool Registry + ToolIndex
│   │   │   ├── context_manager.py   # C: Context Manager
│   │   │   ├── state_store.py       # S: State Store
│   │   │   ├── hooks.py             # L: Lifecycle Hooks
│   │   │   ├── evaluation.py        # V: Evaluation + VerifierSubAgent
│   │   │   └── verifier.py          # Independent task verification
│   │   ├── context/         # Context engines + plugins (v5.0)
│   │   │   ├── engine.py            # ContextEngine ABC
│   │   │   ├── engines/             # SummarizeEngine, TruncateEngine
│   │   │   └── plugins/             # ContextEnginePlugin ABC + Registry + DAG
│   │   └── multiagent/      # 5 engine implementations
│   │
│   ├── routing/             # Message routing (v5.0)
│   │   ├── router.py                # AgentRouter + RoutingRule
│   │   ├── thread_bindings.py       # ThreadBindingManager
│   │   ├── integration.py           # RouteAndBind + config-driven router
│   │   ├── bindings.py              # AgentBindings (7-tier priority)
│   │   └── dispatch.py              # MessageDispatcher
│   │
│   ├── channels/            # 28 messaging channels
│   │   ├── base.py                  # ChannelPlugin interface
│   │   └── ...                      # telegram/, discord/, slack/, signal/, x/, ...
│   │
│   ├── gateway/             # Gateway server (FastAPI + WebSocket v3)
│   ├── config/              # Pydantic configuration system
│   ├── memory/              # SQLite + LanceDB memory with ContextStore (v5.0)
│   ├── mcp/                 # MCP client (stdio + HTTP + Streamable HTTP + OAuth)
│   ├── security/            # Security: EncryptedText, audit, CSP
│   ├── cron/                # APScheduler + TaskChainRunner + WebhookTrigger
│   └── cli/                 # 30+ Typer commands
│
├── apps/                    # TypeScript clients
│   ├── web/                 # Next.js 15 Web app
│   ├── desktop/             # Tauri 2.x Desktop app
│   └── mobile/              # Expo React Native app
│
├── packages/                # Shared packages (types, API client, UI)
├── tests/                   # 6125 tests (6125 passed, 1 skipped)
└── docs/                    # MkDocs documentation
```

### Tech Stack

| Layer | Technology |
|-------|------------|
| Language | Python 3.10+ |
| Type checking | mypy strict (0 errors) |
| Linting | ruff (clean) |
| Web framework | FastAPI + Uvicorn |
| WebSocket | websockets |
| CLI | Typer + Rich |
| Config format | JSON5 (Pydantic v2) |
| Database | SQLite + aiosqlite (WAL mode) |
| Vector search | LanceDB |
| UI (Web) | Next.js 15 |
| UI (Desktop) | Tauri 2.x |
| UI (Mobile) | Expo React Native |
| Testing | pytest + pytest-asyncio |
| Build | Hatch |

---

## Project Stats

| Metric | Value |
|--------|-------|
| Source files | 755+ Python files |
| Tests | 6,125 (6,125 passed, 1 skipped) |
| Code coverage | 66% |
| Type safety | mypy strict: 0 errors |
| Channels | 28 |
| LLM providers | 25+ |
| Built-in tools | 20+ |
| CLI commands | 30+ |
| Gateway RPC methods | 30+ |
| MCP transports | 3 (stdio, HTTP, Streamable HTTP) |
| MCP built-in servers | 3 (Memory, RAG, Image Gen) |
| Context engine plugins | 2 builtin + custom API |
| Multi-agent engines | 5 |

---

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run specific test suites
pytest tests/maysii/routing/
pytest tests/maysii/agents/context/
pytest tests/maysii/channels/

# Type check (0 errors expected)
mypy --strict src/maysii/

# Lint & format
ruff check src/ tests/
ruff format src/ tests/
```

---

## Contributing

Pull requests welcome. The project follows standard Python conventions:

- Code style enforced by `ruff`
- Type annotations enforced by `mypy --strict`
- Async-first architecture throughout
- All new features should include tests (80%+ coverage target)
- See [CLAUDE.md](CLAUDE.md) for project conventions

---

## Documentation

| Document | Description |
|----------|-------------|
| [Quick Start](docs/quickstart.md) | Getting started guide |
| [Architecture](docs/architecture.md) | System architecture (v5.0) |
| [Configuration](docs/configuration.md) | Full config reference |
| [Context Engine Plugin](docs/context-engine-plugin.md) | Plugin development guide (v5.0) |
| [API Reference](docs/api-reference.md) | Gateway RPC + HTTP API |
| [Channel Setup](docs/channel-setup.md) | Per-channel configuration |
| [v5.1 ROADMAP](.planning/milestones/v5.1-ROADMAP.md) | Next milestone plan |

---

## Acknowledgements

This project is inspired by [Maysii](https://github.com/openclaw/openclaw) (originally built with TypeScript). Maysii is a ground-up rewrite using Python + TypeScript, with additional features including context engine plugins, agent routing, DAG compression, and mypy strict enforcement.

Thanks to [Next.js](https://nextjs.org), [Tauri](https://tauri.app), [Expo](https://expo.dev), and the open-source AI community.

---

## License

[MIT](LICENSE) — Copyright (c) 2026 CHEN SAI
