Lucy
751584c99d
Persistent Python daemon connecting Matrix DM room to AiAgent API. - Config-driven (JSON config file) - Extensible command system (/new_session, /help) - Typing indicators while agent processes - Session auto-naming for identification - Persistent state across restarts - Token refresh, retry logic, error handling - Python stdlib only — no external dependencies
58 lines
1.9 KiB
Markdown
58 lines
1.9 KiB
Markdown
# Matrix Bridge — Lucy's Messaging Bridge
|
|
|
|
A persistent Python daemon that connects a Matrix DM room to the local AI agent framework (`AiAgent`). Listens for incoming messages, forwards them to the agent, and sends responses back — all using only Python stdlib.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Matrix ──sync──> MatrixClient ──events──> Bridge ──message──> AgentClient ──> AiAgent API
|
|
^ │ │
|
|
└─────────── response ──────────────────┘ │
|
|
│
|
|
typing indicator, session management, command dispatch polling loop
|
|
```
|
|
|
|
## Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `main.py` | Entry point, CLI argument parsing |
|
|
| `config.py` | Configuration loader (JSON → dataclass) |
|
|
| `bridge.py` | Main loop, event processing, command dispatch |
|
|
| `matrix_client.py` | Matrix API client (sync, send, typing, auth) |
|
|
| `agent_client.py` | Agent API client (sessions, messages, polling) |
|
|
| `state.py` | Persistent state (session ID, batch token, dedup) |
|
|
| `config.json` | Configuration file |
|
|
|
|
## Configuration
|
|
|
|
Edit `config.json` to set:
|
|
|
|
- **Matrix** — server, user ID, room ID, credentials file path
|
|
- **Agent** — API base URL
|
|
- **Bridge** — poll interval, timeouts, limits
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/new_session` | Create a fresh agent session (clears conversation) |
|
|
| `/help` | Show available commands |
|
|
|
|
Adding new commands: add an entry to `Bridge.COMMANDS` and a `_cmd_<name>` method.
|
|
|
|
## Deployment
|
|
|
|
```bash
|
|
# Install
|
|
sudo cp -r . /opt/MatrixBridge
|
|
sudo cp matrix-bridge.service /etc/systemd/system/
|
|
|
|
# Start
|
|
sudo systemctl enable --now matrix-bridge
|
|
```
|
|
|
|
## Requirements
|
|
|
|
Python 3.10+ with stdlib only — no external packages needed.
|