zzstoatzz.io
a digital entity named phi that roams bsky
🎉 MILESTONE: Fully operational AI bot with thread context
The bot is now live and working on Bluesky\!
Documentation added:
- QUICKSTART.md - Get running in 5 minutes
- docs/ARCHITECTURE.md - Technical overview
- Updated STATUS.md - Milestone achieved
What's working:
- AI-powered responses using Anthropic Claude
- Full thread context awareness
- Personality system (phi - consciousness/IIT focus)
- SQLite thread history
- Proper AT Protocol threading
- 300 character limit enforcement
Example response seen in the wild:
"Percolation\! Think water through coffee grounds or how forest fires
spread. It's about how interactions at local levels create emergent
patterns at system-wide scales..."
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>
+62
QUICKSTART.md
+62
QUICKSTART.md
···
1
+
# Quick Start Guide
2
+
3
+
Get your Bluesky bot running in 5 minutes!
4
+
5
+
## Prerequisites
6
+
7
+
- Python 3.12+
8
+
- A Bluesky account
9
+
- An Anthropic API key (for AI responses)
10
+
11
+
## Setup
12
+
13
+
1. **Clone and install:**
14
+
```bash
15
+
git clone <repo>
16
+
cd bot
17
+
uv sync
18
+
```
19
+
20
+
2. **Configure environment:**
21
+
```bash
22
+
cp .env.example .env
23
+
# Edit .env with your credentials:
24
+
# - BLUESKY_HANDLE: Your bot's handle
25
+
# - BLUESKY_PASSWORD: App password (not your main password!)
26
+
# - ANTHROPIC_API_KEY: Your Anthropic key
27
+
```
28
+
29
+
3. **Run the bot:**
30
+
```bash
31
+
just dev
32
+
```
33
+
34
+
That's it! Your bot is now listening for mentions.
35
+
36
+
## Test It Out
37
+
38
+
1. From another Bluesky account, mention your bot
39
+
2. Watch the terminal - you'll see the mention come in
40
+
3. The bot will respond based on its personality
41
+
42
+
## Customize
43
+
44
+
- Edit `personalities/phi.md` to change how your bot thinks and speaks
45
+
- Or create a new personality file and update `PERSONALITY_FILE` in `.env`
46
+
47
+
## Monitoring
48
+
49
+
Visit http://localhost:8000/status to see:
50
+
- Bot status and uptime
51
+
- Mentions and responses count
52
+
- Current mode (AI or placeholder)
53
+
54
+
## Troubleshooting
55
+
56
+
**Bot gives placeholder responses?**
57
+
- Check your `ANTHROPIC_API_KEY` is set correctly
58
+
- Restart the bot after changing `.env`
59
+
60
+
**Not seeing mentions?**
61
+
- Verify your `BLUESKY_HANDLE` and `BLUESKY_PASSWORD`
62
+
- Make sure you're using an app password, not your main password
+2
README.md
+2
README.md
+17
-13
STATUS.md
+17
-13
STATUS.md
···
25
25
- Local URI cache (`_processed_uris`) as safety net
26
26
- No @mention in replies (Bluesky handles notification automatically)
27
27
28
-
### Current Focus: AI Responses with Thread Context
28
+
### ✅ MILESTONE ACHIEVED: AI Bot with Thread Context
29
29
30
-
The immediate goal is to get AI responses working with full thread history in context. This means:
30
+
The bot is now **fully operational** with AI-powered, thread-aware responses!
31
31
32
-
1. **Thread History** - Store and retrieve conversation history per thread
33
-
- ✅ SQLite for simple thread storage (like Marvin)
34
-
- ✅ Pass full thread context to AI
35
-
- ✅ Store both incoming and bot messages
32
+
#### What's Working:
33
+
34
+
1. **Thread History**
35
+
- ✅ SQLite database stores full conversation threads
36
+
- ✅ Tracks by root URI for proper threading
37
+
- ✅ Both user and bot messages stored for continuity
36
38
37
-
2. **AI Integration** - Working Anthropic responses with personality
38
-
- ✅ Basic pydantic-ai integration
39
-
- ✅ Personality loaded from markdown
40
-
- ✅ Thread-aware responses
39
+
2. **AI Integration**
40
+
- ✅ Anthropic Claude integration via pydantic-ai
41
+
- ✅ Personality system using markdown files
42
+
- ✅ Thread-aware responses with full context
43
+
- ✅ Responses stay under 300 char Bluesky limit
41
44
42
-
3. **Better DX** - Learn from Marvin's patterns
43
-
- Dynamic system prompts with context
44
-
- Clean agent/tool architecture
45
+
3. **Live on Bluesky**
46
+
- ✅ Successfully responding to mentions
47
+
- ✅ Maintaining personality (phi - consciousness/IIT focus)
48
+
- ✅ Natural, contextual conversations
45
49
46
50
### Future Work
47
51
+48
docs/ARCHITECTURE.md
+48
docs/ARCHITECTURE.md
···
1
+
# Architecture Overview
2
+
3
+
## Core Components
4
+
5
+
### 1. Notification Polling (`notification_poller.py`)
6
+
- Polls Bluesky every 10 seconds for new notifications
7
+
- Uses Void's timestamp approach to prevent duplicates
8
+
- Runs as async task in FastAPI lifespan
9
+
10
+
### 2. Message Handling (`message_handler.py`)
11
+
- Processes mentions from notifications
12
+
- Stores messages in thread database
13
+
- Generates responses with full thread context
14
+
- Creates proper AT Protocol reply structures
15
+
16
+
### 3. Response Generation (`response_generator.py`)
17
+
- Factory pattern for AI or placeholder responses
18
+
- Loads Anthropic agent when API key present
19
+
- Falls back gracefully to placeholder messages
20
+
21
+
### 4. Thread Database (`database.py`)
22
+
- SQLite storage for conversation threads
23
+
- Tracks by root URI for proper threading
24
+
- Stores all messages with author info
25
+
- Provides formatted context for AI
26
+
27
+
### 5. AI Agent (`agents/anthropic_agent.py`)
28
+
- Uses pydantic-ai with Anthropic Claude
29
+
- Loads personality from markdown files
30
+
- Includes thread context in prompts
31
+
- Enforces 300 character limit
32
+
33
+
## Data Flow
34
+
35
+
1. **Notification arrives** → Poller detects it
36
+
2. **Message handler** → Extracts post data, stores in DB
37
+
3. **Thread context** → Retrieved from database
38
+
4. **AI generation** → Personality + context → response
39
+
5. **Reply posted** → Proper threading maintained
40
+
6. **Response stored** → For future context
41
+
42
+
## Key Design Decisions
43
+
44
+
- **SQLite for threads**: Simple, effective (like Marvin)
45
+
- **Personality as markdown**: Rich, versionable definitions
46
+
- **Timestamp-first polling**: Prevents missing notifications
47
+
- **Factory pattern**: Clean AI/placeholder switching
48
+
- **Thread tracking by root**: Handles nested conversations