From 756ebba120786dcae87e3dbc6eb58dcc563089e9 Mon Sep 17 00:00:00 2001 From: Shawn Date: Sat, 23 May 2026 12:08:39 -0400 Subject: [PATCH] docs: update for rooms, messaging, sync modules + CLI --- Home.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 115 insertions(+), 12 deletions(-) diff --git a/Home.md b/Home.md index aa9c05f..5f81a6e 100644 --- a/Home.md +++ b/Home.md @@ -1,6 +1,7 @@ # Matrix-Hermes -Matrix bridge for Hermes Agent — provides authentication, client connectivity, and bridge utilities. +Matrix bridge for Hermes Agent — provides authentication, client connectivity, bridge utilities, +room management, messaging, and real-time sync. ## Quick Start @@ -38,23 +39,121 @@ matrix-hermes login ## CLI Commands ```bash -matrix-hermes login # Authenticate with homeserver -matrix-hermes whoami # Validate current token -matrix-hermes logout # Invalidate token + remove session -matrix-hermes check # Check config from env -matrix-hermes show-config # Show config as env vars +# Authentication +matrix-hermes login # Authenticate with homeserver +matrix-hermes whoami # Validate current token +matrix-hermes logout # Invalidate token + remove session +matrix-hermes check # Check config from env +matrix-hermes show-config # Show config as env vars + +# Rooms +matrix-hermes rooms list # List joined rooms +matrix-hermes rooms create --name "My Room" # Create a new room +matrix-hermes rooms join !room:example.org # Join a room +matrix-hermes rooms leave !room:example.org # Leave a room +matrix-hermes rooms info !room:example.org # Get room details +matrix-hermes rooms members !room:example.org # List room members +matrix-hermes rooms invite !room:example.org @user:example.org + +# Messaging +matrix-hermes send text !room:example.org "Hello Matrix!" +matrix-hermes send image !room:example.org /tmp/photo.jpg --caption "Check this" +matrix-hermes send file !room:example.org /tmp/report.pdf + +# Sync +matrix-hermes sync listen # Listen for all messages +matrix-hermes sync listen --room !room:example.org # Filter by room +matrix-hermes sync listen --filter-type m.room.message # Filter by type +matrix-hermes sync listen --show-all # Show all event types ``` +## Python API + +```python +import asyncio +from matrix_hermes import MatrixConfig, MatrixClient + +async def main(): + config = MatrixConfig.from_env() + async with MatrixClient(config) as client: + # Rooms + rooms = await client.get_joined_rooms() + ok = await client.join_room("!room:example.org") + + # Messages + result = await client.send_message("!room:example.org", "Hello from Hermes!") + + # Sync + from matrix_hermes import SyncEngine, SyncFilter + engine = SyncEngine(client._client) + + async def on_message(event): + print(f"[{event.room_id}] {event.sender}: {event.content.get('body')}") + + engine.on_event("m.room.message", on_message) + engine.start_background() + + # ... do other work ... + + await engine.stop() + +asyncio.run(main()) +``` + +## Module Reference + +| Module | Purpose | Key exports | +|--------|---------|-------------| +| `auth` | Login, token, sessions | `login`, `login_from_config`, `logout`, `save_session` | +| `config` | Env-based configuration | `MatrixConfig` | +| `client` | Async mautrix wrapper | `MatrixClient`, `MatrixMessage`, `SendResult` | +| `rooms` | Room management | `create_room`, `join_room`, `leave_room`, `get_room_info`, `get_room_members` | +| `messaging` | Send messages, media | `send_text`, `send_image`, `send_file`, `edit_message`, `send_reaction` | +| `sync` | Real-time event sync | `SyncEngine`, `SyncFilter`, `sync_once`, `extract_events`, `get_messages` | +| `cli` | CLI entry point | `main` | + +### Room Management + +- `create_room()` — create rooms with presets, visibility, invites +- `join_room()` / `leave_room()` / `forget_room()` — membership lifecycle +- `get_joined_rooms()` — list joined rooms +- `get_room_info()` — fetch room metadata (name, topic, member count, encryption) +- `get_room_members()` — list members with display names +- `invite_user()` / `kick_user()` / `ban_user()` / `unban_user()` — moderation +- `set_room_name()` / `set_room_topic()` — room settings + +### Messaging + +- `send_text()` — plain text with optional HTML, reply, thread +- `send_notice()` — m.notice (less intrusive) +- `send_emote()` — m.emote (/me style) +- `send_image()` / `send_file()` / `send_sticker()` — rich media +- `edit_message()` — m.replace edits +- `redact_message()` — message deletion +- `send_reaction()` — emoji reactions +- `send_typing()` / `send_read_receipt()` / `set_fully_read()` — presence + +### Sync Engine + +- `SyncEngine` — continuous sync with handler dispatch, exponential backoff +- `SyncFilter` — filter by event type, room, sender +- `sync_once()` — single sync call +- `extract_events()` — parse sync response into event objects +- `get_messages()` — paginated message history + ## Project Structure ``` src/matrix_hermes/ -├── __init__.py # Package init -├── auth.py # Login, token, session persistence -├── client.py # Async MatrixClient (mautrix wrapper) -├── config.py # Env-based configuration -└── cli.py # CLI entry point -tests/ # 60 unit tests +├── __init__.py # Package init, re-exports all public API +├── auth.py # Login, token, session persistence +├── client.py # Async MatrixClient (mautrix wrapper) +├── config.py # Env-based configuration +├── rooms.py # Room management (create/join/list/moderate) +├── messaging.py # Messaging (text/media/edit/react/typing) +├── sync.py # Sync engine (poll, filter, dispatch, history) +└── cli.py # CLI entry point (all commands) +tests/ # 182 unit tests ``` ## Dependencies @@ -63,3 +162,7 @@ tests/ # 60 unit tests - mautrix >= 0.20.0 - aiohttp >= 3.9 - python-dotenv >= 1.0 + +## Repository + +https://gitea.ourpad.casa/shawn/matrix-hermes