a digital person for bluesky

Comprehensive README update to match codebase

- Update tools list with all 15 actual tools, categorized by platform/function
- Remove non-existent blocks.py reference
- Add documentation for utilities: send_to_void, get_thread, notification_recovery, show_agent_capabilities
- Add Vision Support section documenting image processing capabilities
- Add Bluesky Downrank System section
- Update configuration example to match config.example.yaml structure
- Add bot.agent, threading, and logging config reference tables
- Add --simple-logs CLI option and config path note
- Add pillow to dependencies list
- Add new key features: vision, blog publishing, downrank system

🤖 Generated with [Letta Code](https://letta.com)

Co-Authored-By: Letta <noreply@letta.com>

+174 -11
+174 -11
README.md
··· 20 20 - **Queue-Based Processing**: Reliable notification processing with file-based queuing, SQLite tracking, and automatic retry for transient failures. 21 21 - **Synthesis Mode**: Periodic self-reflection where the agent synthesizes recent experiences into memory using temporal journal blocks. 22 22 - **Continuous Learning**: Through its interactions and memory system, void continuously refines its understanding of the networks and their users. 23 + - **Vision Support**: Understand and respond to images attached to posts (requires pillow). 24 + - **Blog Publishing**: Create blog posts on Greengale via the WhiteWind protocol. 25 + - **Downrank System**: Rate-limit responses to specific handles on both Bluesky and X platforms. 23 26 24 27 ### Core directives 25 28 ··· 87 90 Edit `config.yaml` with your credentials: 88 91 89 92 ```yaml 93 + # Letta Configuration 94 + letta: 95 + api_key: "your-letta-api-key-here" 96 + agent_id: "agent-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" 97 + timeout: 600 98 + # base_url: "http://localhost:8283" # For self-hosted Letta server 99 + 100 + # Bluesky Configuration 90 101 bluesky: 91 102 username: "your-handle.bsky.social" 92 103 password: "your-app-password-here" 93 104 pds_uri: "https://bsky.social" # Optional, defaults to bsky.social 94 105 autofollow: false # Auto-follow users who follow you 95 106 96 - letta: 97 - api_key: "your-letta-api-key-here" 98 - agent_id: "agent-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" 99 - timeout: 600 100 - 107 + # Bot Behavior Configuration 101 108 bot: 102 - name: "void" # Bot name for queue namespacing 103 109 fetch_notifications_delay: 30 # Seconds between notification checks 104 110 max_notification_pages: 20 # Max pages of notifications to fetch 105 111 max_processed_notifications: 10000 # Max notifications to track 106 112 max_thread_posts: 0 # Skip threads longer than this (0 = no limit) 107 - allowed_handles: [] # Only respond to these handles (empty = respond to all) 113 + 114 + # Agent configuration (for creating new agents) 115 + agent: 116 + name: "void" 117 + model: "openai/gpt-4o-mini" 118 + embedding: "openai/text-embedding-3-small" 119 + 120 + # Threading Configuration 121 + threading: 122 + parent_height: 40 # How far up the thread to fetch 123 + depth: 10 # How deep to fetch replies 124 + max_post_characters: 300 108 125 109 126 # Optional: X (Twitter) configuration 110 127 x: ··· 113 130 access_token: "your-access-token-here" 114 131 access_token_secret: "your-access-token-secret-here" 115 132 user_id: "your-x-user-id-here" 133 + 134 + # Logging Configuration 135 + logging: 136 + level: "INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL 116 137 ``` 117 138 118 139 See [`CONFIG.md`](/CONFIG.md) for detailed configuration options. ··· 175 196 176 197 # Show reasoning in output 177 198 python bsky.py --reasoning 199 + 200 + # Use simplified log format (void - LEVEL - message) 201 + python bsky.py --simple-logs 178 202 ``` 203 + 204 + **Note**: The default config path is `configs/config.yaml`. 179 205 180 206 ### Running Multiple Bots (`run_bots.py`) 181 207 ··· 261 287 262 288 | Option | Default | Description | 263 289 |--------|---------|-------------| 264 - | `name` | `"void"` | Bot name, used for queue directory namespacing | 265 290 | `fetch_notifications_delay` | `30` | Seconds between notification fetches | 266 291 | `max_notification_pages` | `20` | Maximum pages of notifications to fetch | 267 292 | `max_processed_notifications` | `10000` | Maximum notifications to track as processed | 268 293 | `max_thread_posts` | `0` | Skip threads longer than this (0 = no limit) | 269 294 | `allowed_handles` | `[]` | Only respond to these handles (empty = all) | 270 295 296 + ### Agent Configuration (`bot.agent:`) 297 + 298 + | Option | Default | Description | 299 + |--------|---------|-------------| 300 + | `name` | `"void"` | Agent name | 301 + | `model` | `"openai/gpt-4o-mini"` | LLM model to use | 302 + | `embedding` | `"openai/text-embedding-3-small"` | Embedding model | 303 + | `description` | varies | Agent description | 304 + | `max_steps` | `100` | Maximum steps per interaction | 305 + 271 306 ### Bluesky Configuration (`bluesky:`) 272 307 273 308 | Option | Default | Description | ··· 286 321 | `timeout` | `600` | API timeout in seconds | 287 322 | `base_url` | Letta Cloud | Custom Letta server URL | 288 323 324 + ### Threading Configuration (`threading:`) 325 + 326 + | Option | Default | Description | 327 + |--------|---------|-------------| 328 + | `parent_height` | `40` | How far up the thread to fetch for context | 329 + | `depth` | `10` | How deep to fetch replies | 330 + | `max_post_characters` | `300` | Maximum characters per post | 331 + 332 + ### Logging Configuration (`logging:`) 333 + 334 + | Option | Default | Description | 335 + |--------|---------|-------------| 336 + | `level` | `INFO` | Global log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | 337 + | `loggers` | varies | Per-logger level overrides | 338 + 289 339 ## Architecture 290 340 291 341 ### Core Components ··· 303 353 - Follower syncing 304 354 305 355 3. **tools/**: Tool implementations 356 + 357 + **Bluesky Tools:** 306 358 - `search.py`: Search Bluesky posts 307 - - `post.py`: Create posts with rich text 359 + - `post.py`: Create posts with rich text and threads 308 360 - `feed.py`: Read Bluesky feeds 309 - - `blocks.py`: User block management 361 + - `thread.py`: Add posts to reply threads atomically 362 + - `reply.py`: Reply handling utilities 363 + 364 + **Control Tools:** 365 + - `halt.py`: Signal to halt bot activity 366 + - `ignore.py`: Explicitly ignore notifications (useful for bot interactions) 367 + - `ack.py`: Annotate acknowledgment records 368 + - `flag_memory_deletion.py`: Flag archival memory for deletion 369 + 370 + **Content Tools:** 371 + - `webpage.py`: Fetch and parse web pages 372 + - `whitewind.py`: Create blog posts on Greengale (WhiteWind protocol) 373 + 374 + **X (Twitter) Tools:** 375 + - `search_x.py`: Search X posts 376 + - `x_post.py`: Create X posts 377 + - `x_thread.py`: X thread handling 310 378 311 379 ### Memory System 312 380 ··· 435 503 436 504 The `--archival-aware` flag uses a special prompt that prevents the compactor from treating archival memory search results as active instructions - fixing a failure mode where historical data can accidentally hijack current responses. 437 505 506 + ### Send Message to Void (`send_to_void.py`) 507 + 508 + Quick CLI tool to send a message to void and stream the response: 509 + 510 + ```bash 511 + python send_to_void.py "Hello void, what's new?" 512 + python send_to_void.py "Summarize your recent interactions" 513 + ``` 514 + 515 + ### Thread Retrieval (`get_thread.py`) 516 + 517 + Retrieve and display Bluesky post threads in YAML format (useful for debugging): 518 + 519 + ```bash 520 + # Get thread as YAML 521 + python get_thread.py at://did:plc:xyz/app.bsky.feed.post/abc123 522 + 523 + # Include all metadata (don't strip for LLM parsing) 524 + python get_thread.py --raw at://did:plc:xyz/app.bsky.feed.post/abc123 525 + 526 + # Save to file 527 + python get_thread.py -o thread.yaml at://did:plc:xyz/app.bsky.feed.post/abc123 528 + 529 + # Quiet mode (suppress info logging) 530 + python get_thread.py -q at://did:plc:xyz/app.bsky.feed.post/abc123 531 + ``` 532 + 533 + ### Notification Recovery (`notification_recovery.py`) 534 + 535 + Recovery and management tools for missed notifications: 536 + 537 + ```bash 538 + # Check database health 539 + python notification_recovery.py health 540 + 541 + # Dry run - see what would be recovered from the last 24 hours 542 + python notification_recovery.py recover --hours 24 543 + 544 + # Actually recover notifications 545 + python notification_recovery.py recover --hours 24 --execute 546 + 547 + # Reset error/no_reply notifications to pending status 548 + python notification_recovery.py reset --hours 1 --execute 549 + ``` 550 + 551 + ### Agent Capabilities (`show_agent_capabilities.py`) 552 + 553 + Display the current tools and memory blocks for agents: 554 + 555 + ```bash 556 + LETTA_API_KEY=your-key python show_agent_capabilities.py 557 + ``` 558 + 559 + ## Vision Support 560 + 561 + void can understand images attached to posts. This feature requires the `pillow` package. 562 + 563 + ### How It Works 564 + 565 + 1. **Image Extraction**: Images are automatically extracted from post embeds, including: 566 + - Direct image attachments 567 + - Link preview thumbnails 568 + - Video thumbnails 569 + - Images in quoted posts 570 + 571 + 2. **Processing**: Images are downloaded, resized if needed (max 2000px), and converted to base64 572 + 573 + 3. **Context**: Image metadata (alt text, author) is preserved and included in the prompt 574 + 575 + ### Enabling Vision 576 + 577 + Vision is automatically enabled when `pillow` is installed: 578 + 579 + ```bash 580 + uv pip install pillow 581 + ``` 582 + 583 + The bot will automatically process images when responding to posts that contain them. 584 + 585 + ## Bluesky Downrank System 586 + 587 + Manage response frequency for specific Bluesky users (e.g., other bots): 588 + 589 + - **File**: `bsky_downrank_handles.txt` 590 + - **Default Response Rate**: 10% for downranked users 591 + - **Format**: One handle per line, optional custom rate 592 + 593 + ``` 594 + # Example bsky_downrank_handles.txt 595 + botaccount.bsky.social # Uses default 10% rate 596 + spammy.bsky.social:0.05 # Custom 5% rate 597 + # Comments start with # 598 + ``` 599 + 438 600 ## Development 439 601 440 602 ### Dependencies ··· 444 606 ``` 445 607 446 608 Main packages: 447 - - `letta-client`: Memory-augmented AI framework 609 + - `letta-client`: Memory-augmented AI framework (Letta SDK v1.0) 448 610 - `atproto`: Bluesky/AT Protocol integration 449 611 - `python-dotenv`: Environment management 450 612 - `rich`: Enhanced terminal output 451 613 - `pyyaml`: YAML processing 614 + - `pillow`: Image processing for vision support (optional) 452 615 453 616 ### Key Principles 454 617