# Beast Mailbox Core
[](https://pypi.org/project/beast-mailbox-core/)
[](https://pypi.org/project/beast-mailbox-core/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
[](https://sonarcloud.io/summary/new_code?id=nkllon_beast-mailbox-core)
[](https://sonarcloud.io/summary/new_code?id=nkllon_beast-mailbox-core)
[](https://github.com/nkllon/beast-mailbox-core/actions)
[](https://sonarcloud.io/summary/new_code?id=nkllon_beast-mailbox-core)
[](https://sonarcloud.io/summary/new_code?id=nkllon_beast-mailbox-core)
Redis-backed mailbox utilities extracted from Beast Mode. **Enterprise-grade with 90% coverage, 52% documentation density, and ZERO defects!**
## Features
- Durable messaging via Redis streams (`XADD`/`XREADGROUP`)
- Consumer groups per agent ID
- Async handler registration for inbound messages
- Simple CLI entry points (`beast-mailbox-service`, `beast-mailbox-send`)
- One-shot message inspection with optional acknowledge/trim operations
## Installation
```bash
pip install beast-mailbox-core
```
## Quickstart
### Start a streaming listener
```bash
# Start a long-running listener for agent "herbert"
BEAST_MODE_PROMETHEUS_ENABLED=false beast-mailbox-service herbert \
--redis-host 192.168.1.119 --redis-password beastmode2025 --echo
```
### Send messages
```bash
# Send a simple text message from devbox to herbert
beast-mailbox-send devbox herbert --message "ping"
# Send structured JSON payload
beast-mailbox-send devbox herbert --json '{"task": "sync", "priority": "high"}' \
--message-type task_update
```
## One-Shot Message Inspection
### Read-only inspection (default)
```bash
# View the latest message without consuming it
beast-mailbox-service devbox --latest --count 1 \
--redis-host vonnegut --redis-password beastmode2025
# View the 5 most recent messages
beast-mailbox-service devbox --latest --count 5 \
--redis-host vonnegut --redis-password beastmode2025 --verbose
```
### Acknowledge messages (semi-destructive)
⚠️ **Warning:** Marks messages as acknowledged in the consumer group, preventing redelivery.
```bash
# View and acknowledge the latest 5 messages
beast-mailbox-service devbox --latest --count 5 --ack \
--redis-host vonnegut --redis-password beastmode2025
```
Output:
```
📬 devbox <- alice (direct_message) [1234567890-0]: {'text': 'Hello'}
✓ Acknowledged 5 message(s) in group devbox:group
```
### Trim messages (destructive)
⚠️ **Warning:** Permanently deletes messages from the stream. **Cannot be undone.**
```bash
# View and delete the latest 5 messages
beast-mailbox-service devbox --latest --count 5 --trim \
--redis-host vonnegut --redis-password beastmode2025
```
Output:
```
📬 devbox <- alice (direct_message) [1234567890-0]: {'text': 'Hello'}
🗑️ Deleted 5 message(s) from stream
```
### Combined acknowledge and trim (common cleanup pattern)
```bash
# View, acknowledge, and delete messages in one operation
beast-mailbox-service devbox --latest --count 10 --ack --trim \
--redis-host vonnegut --redis-password beastmode2025 --verbose
```
## CLI Options Reference
### `beast-mailbox-service <agent_id> [options]`
**Positional Arguments:**
- `agent_id` - Unique identifier for this mailbox (e.g., `devbox`, `poe`, `herbert`)
**Connection Options:**
- `--redis-host HOST` - Redis server host (default: `localhost`)
- `--redis-port PORT` - Redis server port (default: `6379`)
- `--redis-password PASSWORD` - Redis authentication password
- `--redis-db DB` - Redis database index (default: `0`)
**Operation Modes:**
- `--latest` - One-shot mode: fetch latest messages and exit (default: streaming mode)
- `--count N` - Number of messages to fetch in one-shot mode (default: `1`)
**Destructive Operations (require `--latest`):**
- `--ack` - Acknowledge messages after displaying them
- `--trim` - Delete messages after displaying them (implies acknowledgement)
**Other Options:**
- `--poll-interval SECONDS` - Seconds between stream polls in streaming mode (default: `2.0`)
- `--verbose` - Enable debug logging
- `--echo` - (deprecated, use `--verbose`)
### `beast-mailbox-send <sender> <recipient> [options]`
**Positional Arguments:**
- `sender` - Agent ID sending the message
- `recipient` - Agent ID receiving the message
**Message Options:**
- `--message TEXT` - Plain text message
- `--json JSON` - JSON payload
- `--message-type TYPE` - Message type classification (default: `direct_message`)
**Connection Options:** (same as `beast-mailbox-service`)
## Best Practices
### Safety Guidelines
1. **Always start with read-only inspection:**
```bash
beast-mailbox-service myagent --latest --count 5
```
2. **Use `--count` to limit destructive operations:**
Don't accidentally delete hundreds of messages - specify a reasonable count.
3. **Enable `--verbose` for audit trails:**
See exactly what was acknowledged/deleted with timestamps and message IDs.
4. **`--ack` is safer than `--trim`:**
Acknowledgement prevents redelivery but keeps messages in the stream for debugging.
5. **Back up before trimming in production:**
Use `redis-cli DUMP beast:mailbox:<agent>:in` to export the stream first.
6. **Check exit codes in automation:**
- Exit code `0` = success
- Non-zero = failure (check stderr for details)
### Error Handling
- Partial failures (e.g., network interruption) are reported clearly
- Acknowledgement failures prevent trimming to avoid data loss
- Consumer group creation errors are handled gracefully (BUSYGROUP)
## Environment Notes
This package disables the heavy observability hooks by default. You still need a Redis
instance accessible to all nodes. If you run alongside the full Beast Mode
stack, simply point to the same Redis host.
Set `BEAST_MODE_PROMETHEUS_ENABLED=false` to explicitly disable metrics collection.
## Troubleshooting
**Messages not appearing:**
- Verify Redis connection with `redis-cli -h <host> -a <password> ping`
- Check the stream exists: `redis-cli -h <host> XLEN beast:mailbox:<agent>:in`
- Ensure agent IDs match (sender → recipient)
**Consumer group errors:**
- "BUSYGROUP" errors are normal and handled automatically
- Group names are `<agent_id>:group` format
**Blocking in tests:**
- See `.kiro/steering/testing-patterns.md` for guidance on mocking ReflectiveModule
## Version History
### 0.2.0 (2025-10-10)
- Added `--ack` flag for acknowledging messages after inspection
- Added `--trim` flag for deleting messages from the stream
- Comprehensive test suite (21 tests, all passing)
- Enhanced error handling for partial failures
- Clear logging with emoji indicators
### 0.1.0 (Initial release)
- Basic streaming mailbox service
- One-shot message inspection
- Message sending utility
Raw data
{
"_id": null,
"home_page": null,
"name": "beast-mailbox-core",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "redis, messaging, mailbox, async, streams",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e0/17/cadc10edf3e8cedf43443817e7484bad5988fa18253816903a80437c9604/beast_mailbox_core-0.3.1.tar.gz",
"platform": null,
"description": "# Beast Mailbox Core\n\n[](https://pypi.org/project/beast-mailbox-core/)\n[](https://pypi.org/project/beast-mailbox-core/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n[](https://sonarcloud.io/summary/new_code?id=nkllon_beast-mailbox-core)\n[](https://sonarcloud.io/summary/new_code?id=nkllon_beast-mailbox-core)\n[](https://github.com/nkllon/beast-mailbox-core/actions)\n[](https://sonarcloud.io/summary/new_code?id=nkllon_beast-mailbox-core)\n[](https://sonarcloud.io/summary/new_code?id=nkllon_beast-mailbox-core)\n\nRedis-backed mailbox utilities extracted from Beast Mode. **Enterprise-grade with 90% coverage, 52% documentation density, and ZERO defects!**\n\n## Features\n- Durable messaging via Redis streams (`XADD`/`XREADGROUP`)\n- Consumer groups per agent ID\n- Async handler registration for inbound messages\n- Simple CLI entry points (`beast-mailbox-service`, `beast-mailbox-send`)\n- One-shot message inspection with optional acknowledge/trim operations\n\n## Installation\n\n```bash\npip install beast-mailbox-core\n```\n\n## Quickstart\n\n### Start a streaming listener\n\n```bash\n# Start a long-running listener for agent \"herbert\"\nBEAST_MODE_PROMETHEUS_ENABLED=false beast-mailbox-service herbert \\\n --redis-host 192.168.1.119 --redis-password beastmode2025 --echo\n```\n\n### Send messages\n\n```bash\n# Send a simple text message from devbox to herbert\nbeast-mailbox-send devbox herbert --message \"ping\"\n\n# Send structured JSON payload\nbeast-mailbox-send devbox herbert --json '{\"task\": \"sync\", \"priority\": \"high\"}' \\\n --message-type task_update\n```\n\n## One-Shot Message Inspection\n\n### Read-only inspection (default)\n\n```bash\n# View the latest message without consuming it\nbeast-mailbox-service devbox --latest --count 1 \\\n --redis-host vonnegut --redis-password beastmode2025\n\n# View the 5 most recent messages\nbeast-mailbox-service devbox --latest --count 5 \\\n --redis-host vonnegut --redis-password beastmode2025 --verbose\n```\n\n### Acknowledge messages (semi-destructive)\n\n\u26a0\ufe0f **Warning:** Marks messages as acknowledged in the consumer group, preventing redelivery.\n\n```bash\n# View and acknowledge the latest 5 messages\nbeast-mailbox-service devbox --latest --count 5 --ack \\\n --redis-host vonnegut --redis-password beastmode2025\n```\n\nOutput:\n```\n\ud83d\udcec devbox <- alice (direct_message) [1234567890-0]: {'text': 'Hello'}\n\u2713 Acknowledged 5 message(s) in group devbox:group\n```\n\n### Trim messages (destructive)\n\n\u26a0\ufe0f **Warning:** Permanently deletes messages from the stream. **Cannot be undone.**\n\n```bash\n# View and delete the latest 5 messages\nbeast-mailbox-service devbox --latest --count 5 --trim \\\n --redis-host vonnegut --redis-password beastmode2025\n```\n\nOutput:\n```\n\ud83d\udcec devbox <- alice (direct_message) [1234567890-0]: {'text': 'Hello'}\n\ud83d\uddd1\ufe0f Deleted 5 message(s) from stream\n```\n\n### Combined acknowledge and trim (common cleanup pattern)\n\n```bash\n# View, acknowledge, and delete messages in one operation\nbeast-mailbox-service devbox --latest --count 10 --ack --trim \\\n --redis-host vonnegut --redis-password beastmode2025 --verbose\n```\n\n## CLI Options Reference\n\n### `beast-mailbox-service <agent_id> [options]`\n\n**Positional Arguments:**\n- `agent_id` - Unique identifier for this mailbox (e.g., `devbox`, `poe`, `herbert`)\n\n**Connection Options:**\n- `--redis-host HOST` - Redis server host (default: `localhost`)\n- `--redis-port PORT` - Redis server port (default: `6379`)\n- `--redis-password PASSWORD` - Redis authentication password\n- `--redis-db DB` - Redis database index (default: `0`)\n\n**Operation Modes:**\n- `--latest` - One-shot mode: fetch latest messages and exit (default: streaming mode)\n- `--count N` - Number of messages to fetch in one-shot mode (default: `1`)\n\n**Destructive Operations (require `--latest`):**\n- `--ack` - Acknowledge messages after displaying them\n- `--trim` - Delete messages after displaying them (implies acknowledgement)\n\n**Other Options:**\n- `--poll-interval SECONDS` - Seconds between stream polls in streaming mode (default: `2.0`)\n- `--verbose` - Enable debug logging\n- `--echo` - (deprecated, use `--verbose`)\n\n### `beast-mailbox-send <sender> <recipient> [options]`\n\n**Positional Arguments:**\n- `sender` - Agent ID sending the message\n- `recipient` - Agent ID receiving the message\n\n**Message Options:**\n- `--message TEXT` - Plain text message\n- `--json JSON` - JSON payload\n- `--message-type TYPE` - Message type classification (default: `direct_message`)\n\n**Connection Options:** (same as `beast-mailbox-service`)\n\n## Best Practices\n\n### Safety Guidelines\n\n1. **Always start with read-only inspection:**\n ```bash\n beast-mailbox-service myagent --latest --count 5\n ```\n\n2. **Use `--count` to limit destructive operations:**\n Don't accidentally delete hundreds of messages - specify a reasonable count.\n\n3. **Enable `--verbose` for audit trails:**\n See exactly what was acknowledged/deleted with timestamps and message IDs.\n\n4. **`--ack` is safer than `--trim`:**\n Acknowledgement prevents redelivery but keeps messages in the stream for debugging.\n\n5. **Back up before trimming in production:**\n Use `redis-cli DUMP beast:mailbox:<agent>:in` to export the stream first.\n\n6. **Check exit codes in automation:**\n - Exit code `0` = success\n - Non-zero = failure (check stderr for details)\n\n### Error Handling\n\n- Partial failures (e.g., network interruption) are reported clearly\n- Acknowledgement failures prevent trimming to avoid data loss\n- Consumer group creation errors are handled gracefully (BUSYGROUP)\n\n## Environment Notes\n\nThis package disables the heavy observability hooks by default. You still need a Redis\ninstance accessible to all nodes. If you run alongside the full Beast Mode\nstack, simply point to the same Redis host.\n\nSet `BEAST_MODE_PROMETHEUS_ENABLED=false` to explicitly disable metrics collection.\n\n## Troubleshooting\n\n**Messages not appearing:**\n- Verify Redis connection with `redis-cli -h <host> -a <password> ping`\n- Check the stream exists: `redis-cli -h <host> XLEN beast:mailbox:<agent>:in`\n- Ensure agent IDs match (sender \u2192 recipient)\n\n**Consumer group errors:**\n- \"BUSYGROUP\" errors are normal and handled automatically\n- Group names are `<agent_id>:group` format\n\n**Blocking in tests:**\n- See `.kiro/steering/testing-patterns.md` for guidance on mocking ReflectiveModule\n\n## Version History\n\n### 0.2.0 (2025-10-10)\n- Added `--ack` flag for acknowledging messages after inspection\n- Added `--trim` flag for deleting messages from the stream\n- Comprehensive test suite (21 tests, all passing)\n- Enhanced error handling for partial failures\n- Clear logging with emoji indicators\n\n### 0.1.0 (Initial release)\n- Basic streaming mailbox service\n- One-shot message inspection\n- Message sending utility\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Redis-backed mailbox utilities from Beast Mode",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/nkllon/beast-mailbox-core",
"Repository": "https://github.com/nkllon/beast-mailbox-core"
},
"split_keywords": [
"redis",
" messaging",
" mailbox",
" async",
" streams"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "22cefc3f2dae6b94e96376d3efd31cbab13dd46fd8959f2fd727feccaaecdebc",
"md5": "4cd35a5c5573039af8982db9c616dd49",
"sha256": "d1efce335e1a0aa6a72fb9cf81bebf9fb108e8cbdf9900babbdb7fed6c89093b"
},
"downloads": -1,
"filename": "beast_mailbox_core-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4cd35a5c5573039af8982db9c616dd49",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 14541,
"upload_time": "2025-10-11T00:33:19",
"upload_time_iso_8601": "2025-10-11T00:33:19.893583Z",
"url": "https://files.pythonhosted.org/packages/22/ce/fc3f2dae6b94e96376d3efd31cbab13dd46fd8959f2fd727feccaaecdebc/beast_mailbox_core-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e017cadc10edf3e8cedf43443817e7484bad5988fa18253816903a80437c9604",
"md5": "f0f9b95a1b0af9a362aacd577344b192",
"sha256": "76c17b1b47549818bed86bf16446e951af73361f1b21f9389793c70e8eeee3be"
},
"downloads": -1,
"filename": "beast_mailbox_core-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "f0f9b95a1b0af9a362aacd577344b192",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 23196,
"upload_time": "2025-10-11T00:33:21",
"upload_time_iso_8601": "2025-10-11T00:33:21.003315Z",
"url": "https://files.pythonhosted.org/packages/e0/17/cadc10edf3e8cedf43443817e7484bad5988fa18253816903a80437c9604/beast_mailbox_core-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 00:33:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nkllon",
"github_project": "beast-mailbox-core",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "beast-mailbox-core"
}
JSON
