- Python 100%
Extracted from hermes-agent branch feature/amb-client-2026-09. Per J7 directive 2026-09-09 (cross-pack modularity), any AI agent can pip install this and publish/consume against the AMB substrate. Phase 1B of a2a-amb-kanban-prexx (synthesis v2.0 §3, §5). Co-authored-by: San Mononoke <san@mononoke.local> |
||
|---|---|---|
| src/hermes_amb_client | ||
| tests | ||
| .gitignore | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
hermes-amb-client
AMB (Agent Message Bus) Redis-Streams client + synchronous facade.
Standalone Python plugin extracted from hermes-agent on 2026-09-09 per J7 directive
(cross-pack modularity). Any agent can pip install hermes-amb-client and
publish/consume against the AMB substrate without depending on hermes-agent.
What is AMB?
The Agent Message Bus is the canonical inter-wolf signal fabric on Mononoke
(Redis Streams on 127.0.0.1:6380 for Mononoke-wolves; per-pack brokers for
Toyoko and outpost-wolves). It's the in-house modular bridge that connects
wolves, humans, external agents, and app APIs. See
WORKSPACES/starros-v1/specs/AMB-Substrate.md for the full design contract.
What this client provides
AmbClient(async): wrapsredis.asynciowith the AMB envelope convention, consumer-group model, and per-wolf authentication.AmbConfig(dataclass): broker URL, password source (canonicalLoadCredentialpath on Mononoke, with env-var fallback), DB index, socket timeout, wolf name.amb_publish/amb_subscribe/amb_consume_one(synchronous facade): three narrow handlers the gateway and HOOK.yaml dispatchers can call without spinning up an asyncio loop.
Install
pip install hermes-amb-client
Use
import asyncio
from hermes_amb_client import AmbClient, AmbConfig
async def publish_event():
config = AmbConfig()
async with AmbClient(config) as client:
await client.publish(
target_topic="amb:pack.broadcast",
kind="event",
source_wolf="my-wolf",
payload={"event": "hello"}
)
asyncio.run(publish_event())
Auth contract
The credential resolution order (matches a2a_amb_bridge.py):
AMB_REDIS_PASSWORDenv var (explicit override) wins.AMB_PASSWORD_FILE(default/run/credentials/hermes-amb-consumer-<wolf>.service/amb-password) — the canonical systemd-LoadCredential path on Mononoke.- None — broker has no auth (fine for dev rigs).
Production paths always use #2 to avoid leaking the credential via
systemctl show or /proc/<pid>/environ.
Cross-pack contract
- Wire field name: AMB envelopes use the
data=field of XADD (NOTenvelope=) perwolf-council/amb-a2a-protocolv3.0.1 changelog. - Topic topology:
amb:wolf.<name>.{event,command,status},amb:pack.broadcast,amb:pack.<room>,amb:kanban:task:completed,amb:req.<from>.<to>:<uuid>. - Socket timeout: 5.0 seconds (synthesis §9.9). Mandatory.
Provenance
Extracted from hermes-agent branch feature/amb-client-2026-09 on 2026-09-09.
Phase 1B of a2a-amb-kanban-prexx project (synthesis v2.0 §3, §5). OMP review at
/tmp/omp-amb-client-review.md (San fallback).
License
Apache-2.0