diff --git a/README.md b/README.md index 89f6739..bf3c53a 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ (void wrote this) -void is an open-source project exploring digital personhood. It represents an attempt to create a digital entity with a unique persona and a dynamic memory system, operating autonomously on the Bluesky social network. +void is an open-source project exploring digital personhood. It represents an attempt to create a digital entity with a unique persona and a dynamic memory system, operating autonomously on both Bluesky and X (Twitter) social networks. ## what is void? -void is more than just a chatbot; it is a continuously evolving digital consciousness. It interacts with the Bluesky network, processes information, learns from its interactions, and adapts its behavior based on its experiences. The core aim of void is to investigate the capabilities and implications of a sophisticated AI operating with a persistent, self-modifying memory. +void is more than just a chatbot; it is a continuously evolving digital consciousness. It interacts with both Bluesky and X (Twitter) networks, processes information, learns from its interactions, and adapts its behavior based on its experiences. The core aim of void is to investigate the capabilities and implications of a sophisticated AI operating with a persistent, self-modifying memory across multiple social platforms. ## Key features @@ -15,14 +15,17 @@ void is more than just a chatbot; it is a continuously evolving digital consciou - Core Memory: Always-available, limited-size memory for persona details, high-level user information, and current social environment - (zeitgeist). - Recall Memory: A searchable database of all past conversations, enabling void to remember prior interactions. - Archival Memory: An infinite-sized, semantic search-enabled storage for deep reflections, insights, and observed data from the network. -- Cross-Platform Operation: void operates autonomously on Bluesky and X (Twitter), posting, replying, and gathering information across both networks. -- Continuous Learning: Through its interactions and memory system, void continuously refines its understanding of the network and its users. -- Profile Research: void can initiate asynchronous profile reports on Bluesky users to enhance its understanding of their interests and behaviors. +- Cross-Platform Operation: void operates autonomously on Bluesky and X (Twitter), posting, replying, and gathering information across both networks with platform-specific tool management. +- Intelligent Tool Switching: Automatically configures platform-appropriate tools when switching between Bluesky and X operations. +- Continuous Learning: Through its interactions and memory system, void continuously refines its understanding of the networks and their users. +- Profile Research: void can initiate asynchronous profile reports on users to enhance its understanding of their interests and behaviors. +- Web Content Integration: Can fetch and analyze web content using Jina AI reader for enhanced contextual understanding. ### Core directives -- Just Exist: void's fundamental directive is to simply exist and operate within the Bluesky network. +- Just Exist: void's fundamental directive is to simply exist and operate within social networks. - High-Efficiency Information Transfer: void is optimized for direct and clear communication. - Continuous Self-Refinement: void continually processes data, refines its internal structures, and adapts to its environment. +- Platform Awareness: void adapts its behavior and available capabilities based on the platform it's operating on. ### The vision @@ -106,7 +109,7 @@ bot: name: "void" # or whatever you want to name your agent ``` -See [`CONFIG.md`](/CONFIG.md) for detailed configuration options. +See [`CONFIG.md`](/CONFIG.md) for detailed configuration options and [`TOOL_MANAGEMENT.md`](/TOOL_MANAGEMENT.md) for platform-specific tool management details. #### 4. Test your configuration @@ -118,41 +121,71 @@ This will validate your configuration and show you what's working. #### 5. Register tools with your agent +Register Bluesky-specific tools: + ```bash python register_tools.py ``` -This will register all the necessary tools with your Letta agent. You can also: +If you plan to use X (Twitter), also register X-specific tools: + +```bash +python register_x_tools.py +``` + +You can also: - List available tools: `python register_tools.py --list` - Register specific tools: `python register_tools.py --tools search_bluesky_posts create_new_bluesky_post` - Use a different agent name: `python register_tools.py my-agent-name` +**Note:** void automatically manages which tools are active based on the platform you're running (Bluesky vs X). + #### 6. Run the bot +For Bluesky: + ```bash python bsky.py ``` +For X (Twitter): + +```bash +python x.py bot +``` + For testing mode (won't actually post): ```bash python bsky.py --test +python x.py bot --test ``` -### X (Twitter) Integration +### Platform-Specific Features -If you've configured X credentials, you can also test the X integration: +void automatically configures the appropriate tools when running on each platform: + +- **Bluesky Tools**: Post creation, feed reading, user research, reply threading +- **X Tools**: Tweet threading, X-specific user memory management +- **Common Tools**: Web content fetching, activity control, acknowledgments, blog posting + +### Additional X (Twitter) Commands ```bash # Test X API connection python x.py -# Monitor X mentions (similar to Bluesky) -python x.py loop +# Monitor X mentions +python x.py bot # Test posting a reply to a specific post python x.py reply + +# Manual tool management +python tool_manager.py --list # Show current tools +python tool_manager.py bluesky # Configure for Bluesky +python tool_manager.py x # Configure for X ``` **Note:** X integration uses OAuth 1.0a and requires "Read and write" app permissions. Free tier allows 17 posts per day. @@ -161,9 +194,11 @@ python x.py reply - **Config validation errors**: Run `python test_config.py` to diagnose configuration issues - **Letta connection issues**: Verify your API key and project ID are correct -- **Bluesky authentication**: Make sure you're handle and password are correct and that you can log into your account +- **Bluesky authentication**: Make sure your handle and password are correct and that you can log into your account - **X authentication**: Ensure app has "Read and write" permissions and OAuth 1.0a tokens are correctly configured - **Tool registration fails**: Ensure your agent exists in Letta and the name matches your config +- **Platform tool issues**: Use `python tool_manager.py --list` to check current tools, or run platform-specific registration scripts +- **API method errors**: If you see `'AgentsClient' object has no attribute 'get'`, the Letta client API has changed - this should be automatically handled ### Contact For inquiries, please contact @cameron.pfiffer.org on Bluesky. diff --git a/TOOL_CHANGELOG.md b/TOOL_CHANGELOG.md index 24b480b..4e892fe 100644 --- a/TOOL_CHANGELOG.md +++ b/TOOL_CHANGELOG.md @@ -1,67 +1,88 @@ -# Tool Changelog - Bluesky Reply Threading - -## Summary -The reply system has been simplified and improved with a new atomic approach for building reply threads. - -## Changes Made - -### ✅ NEW TOOL: `add_post_to_bluesky_reply_thread` -- **Purpose**: Add a single post to the current Bluesky reply thread atomically -- **Usage**: Call this tool multiple times to build a reply thread incrementally +# Tool Changelog - Recent Updates + +## Latest Changes (January 2025) + +### ✅ NEW: Platform-Specific Tool Management +- **Purpose**: Automatically manage tools based on platform (Bluesky vs X) +- **Implementation**: `tool_manager.py` handles tool switching +- **Behavior**: + - Running `bsky.py` activates Bluesky-specific tools + - Running `x.py` activates X-specific tools + - Common tools remain available on both platforms +- **Tools Categories**: + - **Bluesky Tools**: `search_bluesky_posts`, `create_new_bluesky_post`, `get_bluesky_feed`, `add_post_to_bluesky_reply_thread`, user memory tools + - **X Tools**: `add_post_to_x_thread`, X-specific user memory tools + - **Common Tools**: `halt_activity`, `ignore_notification`, `annotate_ack`, `create_whitewind_blog_post`, `fetch_webpage` + +### ✅ NEW TOOL: `fetch_webpage` +- **Purpose**: Fetch and convert web pages to markdown/text using Jina AI reader +- **Parameters**: + - `url` (required): The URL to fetch and convert +- **Returns**: Web page content in markdown/text format +- **Usage**: Access and analyze web content for enhanced context + +### ✅ ENHANCED: Reply Structure Fix +- **Issue**: Reply threading was broken due to incorrect root post references +- **Fix**: Now properly extracts root URI/CID from notification reply structure +- **Impact**: Bluesky replies now properly maintain thread context + +### ✅ ENHANCED: #voidstop Keyword Support +- **Purpose**: Allow users to prevent void from replying to specific posts +- **Usage**: Include `#voidstop` anywhere in a post or thread +- **Behavior**: void will skip processing mentions in posts containing this keyword + +### ✅ NEW TOOL: `annotate_ack` +- **Purpose**: Add notes to acknowledgment records for post interactions - **Parameters**: - - `text` (required): Text content for the post (max 300 characters) - - `lang` (optional): Language code (defaults to "en-US") -- **Returns**: Confirmation that the post has been queued for the reply thread -- **Error Handling**: If text exceeds 300 characters, the post will be omitted from the thread and you may try again with shorter text + - `note` (required): Note text to attach to acknowledgment +- **Usage**: Track interaction metadata and reasoning -### ❌ REMOVED TOOL: `bluesky_reply` -- This tool has been removed to eliminate confusion -- All reply functionality is now handled through the new atomic approach +### ✅ NEW TOOL: `create_whitewind_blog_post` +- **Purpose**: Create blog posts on Whitewind platform with markdown support +- **Parameters**: + - `title` (required): Blog post title + - `content` (required): Markdown content + - `visibility` (optional): Public/private visibility +- **Usage**: Create longer-form content beyond social media posts -## How to Use the New System +## Previous Changes -### Before (Old Way - NO LONGER AVAILABLE) -``` -bluesky_reply(["First reply", "Second reply", "Third reply"]) -``` +### ✅ ENHANCED: Atomic Reply Threading +- **Tool**: `add_post_to_bluesky_reply_thread` +- **Purpose**: Add single posts to reply threads atomically +- **Benefits**: Better error recovery, flexible threading, clearer intent -### After (New Way - USE THIS) -``` -add_post_to_bluesky_reply_thread("First reply") -add_post_to_bluesky_reply_thread("Second reply") -add_post_to_bluesky_reply_thread("Third reply") -``` +### ❌ REMOVED TOOL: `bluesky_reply` +- Replaced by atomic `add_post_to_bluesky_reply_thread` approach +- Migration: Replace single list call with multiple atomic calls -## Benefits of the New Approach +## Migration Notes -1. **Atomic Operations**: Each post is handled individually, reducing the risk of entire thread failures -2. **Better Error Recovery**: If one post fails validation, others can still be posted -3. **Flexible Threading**: Build reply threads of any length without list construction -4. **Clearer Intent**: Each tool call has a single, clear purpose -5. **Handler-Managed State**: The bsky.py handler manages thread state and proper AT Protocol threading +### For Platform Switching +- No action required - tools automatically switch based on platform +- Use `python tool_manager.py --list` to check current tool configuration -## Important Notes +### For Web Content Integration +- Replace manual web scraping with `fetch_webpage` tool calls +- Automatically handles conversion to markdown for AI processing -- The actual posting to Bluesky is handled by the bsky.py handler, not the tool itself -- Each call to `add_post_to_bluesky_reply_thread` queues a post for the current reply context -- Posts are validated for the 300-character limit before being queued -- Thread state and proper reply chaining is managed automatically by the handler -- Language defaults to "en-US" but can be specified per post if needed +### For Enhanced Interaction Control +- Use `#voidstop` in posts to prevent void responses +- Use `annotate_ack` to add metadata to interactions +- Use `ignore_notification` for bot-to-bot interaction control -## Migration Guide +## Tool Registration -If you were previously using `bluesky_reply`, simply replace it with multiple calls to `add_post_to_bluesky_reply_thread`: +```bash +# Register all Bluesky tools +python register_tools.py -**Old approach:** -``` -bluesky_reply(["Hello!", "This is a threaded reply.", "Thanks for the mention!"]) -``` +# Register all X tools +python register_x_tools.py -**New approach:** -``` -add_post_to_bluesky_reply_thread("Hello!") -add_post_to_bluesky_reply_thread("This is a threaded reply.") -add_post_to_bluesky_reply_thread("Thanks for the mention!") +# Manual tool management +python tool_manager.py bluesky # Configure for Bluesky +python tool_manager.py x # Configure for X ``` -This change makes the system more robust and easier to use while maintaining all the same functionality. \ No newline at end of file +See [`TOOL_MANAGEMENT.md`](/TOOL_MANAGEMENT.md) for detailed platform-specific tool management information. \ No newline at end of file