xiaomaolv

A high-performance Rust AI gateway. Configure your provider and channel, then run.

Chinese version: README.zh.md

Table of Contents

• Features
• Quick Start (Recommended: MiniMax + Telegram)
• Documentation Index
• Runtime Modes
• Configuration Overview
• Optional: Hybrid Memory (SQLite + zvec sidecar)
• HTTP API
• Plugin Extensions (Provider / Channel)
• Local Development
• Performance Smoke Test
• Security Notes (Before Open Source)

Features

• OpenAI-compatible provider abstraction (MiniMax/OpenAI/other compatible APIs)
• Message channels: HTTP + Telegram
• Telegram dual mode: polling (default) and webhook (optional)
• Telegram streaming replies (incremental updates via editMessageText)
• <think>...</think> auto-rendered as collapsible Telegram spoiler content
• Memory backends: sqlite-only (default) and hybrid-sqlite-zvec (optional)
• Plugin-style extension API for Provider/Channel/Memory

Quick Start (Recommended: MiniMax + Telegram)

1) Requirements

• Rust (stable recommended)
• Telegram bot token (from @BotFather)
• MiniMax API key (OpenAI-compatible endpoint)

2) Prepare environment file

cp .env.realtest.example .env.realtest

Edit .env.realtest and fill at least:

• MINIMAX_API_KEY
• TELEGRAM_BOT_TOKEN

3) Start MVP in one command

./scripts/run_mvp_minimax_telegram.sh

This script uses:

• config: config/xiaomaolv.minimax-telegram.toml
• database: sqlite://xiaomaolv.db
• Telegram mode: polling (no public URL required)

4) Verify service

curl -sS http://127.0.0.1:8080/health
curl -sS http://127.0.0.1:8080/v1/channels/telegram/mode

Then send a message to your Telegram bot.

Documentation Index

After MVP is running, use these docs in order:

• docs/real-test-minimax-telegram.md: real MiniMax + Telegram integration (webhook setup/verification included)
• docs/zvec-sidecar.md: zvec sidecar protocol, startup, compatibility details
• config/xiaomaolv.minimax-telegram.toml: recommended MVP config
• config/xiaomaolv.example.toml: generic template for custom provider/channel setups
• scripts/perf_smoke.sh: machine sizing smoke test script

Runtime Modes

Telegram polling (default)

• No public URL required
• Service pulls updates via Telegram getUpdates
• Startup calls deleteWebhook to prevent webhook/polling conflicts

Telegram webhook (optional)

Recommended for public production deployments.

1. Enable webhook in config:

[channels.telegram]
enabled = true
bot_token = "${TELEGRAM_BOT_TOKEN}"
mode = "webhook"
webhook_secret = "${TELEGRAM_WEBHOOK_SECRET}"
streaming_enabled = true
streaming_edit_interval_ms = 900

2. Fill in .env.realtest:

• TELEGRAM_WEBHOOK_SECRET
• PUBLIC_BASE_URL (public HTTPS URL)

3. Register webhook:

set -a
source .env.realtest
set +a
./scripts/set_telegram_webhook.sh

Webhook endpoint:

POST /v1/telegram/webhook/{webhook_secret}

Configuration Overview

Default template files:

• config/xiaomaolv.example.toml (generic template)
• config/xiaomaolv.minimax-telegram.toml (MVP template)

Key settings:

• Provider config: [providers.<name>]
• Default provider: [app].default_provider
• Telegram streaming:
  • streaming_enabled = true
  • streaming_edit_interval_ms = 900
• Memory mode:
  • backend = "sqlite-only" (default)
  • backend = "hybrid-sqlite-zvec" (optional)

Optional: Hybrid Memory (SQLite + zvec sidecar)

One-command mode

./scripts/run_mvp_minimax_telegram.sh --hybrid-memory

Manual mode

./scripts/run_zvec_sidecar.sh

Details: docs/zvec-sidecar.md

HTTP API

Core endpoints:

• GET /health
• POST /v1/messages
• GET /v1/channels/{channel}/mode
• POST /v1/channels/{channel}/inbound
• POST /v1/channels/{channel}/inbound/{secret}
• POST /v1/telegram/webhook/{secret}

Example:

curl -X POST http://127.0.0.1:8080/v1/messages \
  -H 'content-type: application/json' \
  -d '{"session_id":"demo-1","user_id":"u1","text":"hello"}'

Plugin Extensions (Provider / Channel)

You can extend xiaomaolv like a classic plugin system:

• Provider: implement ProviderFactory, register in ProviderRegistry
• Channel: implement ChannelFactory, register in ChannelRegistry
• Custom router boot: build_router_with_registries(...)
• Runtime with background workers: build_app_runtime_with_registries(...)

Reference tests:

• tests/provider_plugin_api.rs
• tests/channel_plugin_api.rs
• tests/telegram_channel_mode.rs

Local Development

cargo fmt --all
cargo test -- --nocapture

Performance Smoke Test

Quickly estimate whether a machine can run xiaomaolv reliably:

./scripts/perf_smoke.sh

The script will:

• start a local mock provider (no real AI key needed)
• start xiaomaolv in release mode
• benchmark /health and /v1/messages
• print throughput, latency, failure rate, and machine sizing hints

Benchmark an already running service:

./scripts/perf_smoke.sh --running http://127.0.0.1:8080

Customize load:

MSG_C=32 MSG_N=2000 HEALTH_C=200 ./scripts/perf_smoke.sh

Security Notes (Before Open Source)

• Never commit real secrets (for example .env.realtest)
• Keep .env.realtest.example as your safe template
• If any key appeared in local git history, rotate it before publishing