a digital entity named phi that roams bsky
phi.zzstoatzz.io
1# phi 🧠
2
3a bot inspired by IIT and [Void](https://tangled.sh/@cameron.pfiffer.org/void). Built with `fastapi`, `pydantic-ai`, and `atproto`.
4
5## Quick Start
6
7### Prerequisites
8
9- `uv`
10- `just`
11- `turbopuffer` (see [turbopuffer](https://github.com/turbopuffer/turbopuffer))
12- `openai` (for embeddings)
13- `anthropic` (for chat completion)
14
15Get your bot running in 5 minutes:
16
17```bash
18# Clone and install
19git clone https://github.com/zzstoatzz/bot
20cd bot
21uv sync
22
23# Configure (copy .env.example and add your credentials)
24cp .env.example .env
25
26# Run the bot
27just dev
28```
29
30That's it! Your bot is now listening for mentions.
31
32## Configuration
33
34Edit `.env` with your credentials:
35- `BLUESKY_HANDLE`: Your bot's Bluesky handle
36- `BLUESKY_PASSWORD`: App password (not your main password!)
37- `ANTHROPIC_API_KEY`: Your Anthropic key for AI responses
38- `TURBOPUFFER_API_KEY`: Your TurboPuffer key for memory storage
39- `OPENAI_API_KEY`: Your OpenAI key for embeddings (memory system)
40- `BOT_NAME`: Your bot's name (default: "Bot")
41- `PERSONALITY_FILE`: Path to personality markdown file (default: "personalities/phi.md")
42
43## Current Features
44
45- ✅ Responds to mentions with AI-powered messages
46- ✅ Proper notification handling (no duplicates)
47- ✅ Graceful shutdown for hot-reload
48- ✅ AI integration with Anthropic Claude
49- ✅ Thread-aware responses with full conversation context
50- ✅ Status page at `/status` showing activity and health
51- ✅ Web search capability (Google Custom Search API)
52- ✅ Content moderation with philosophical responses
53- ✅ Namespace-based memory system with TurboPuffer
54- ✅ Online/offline status in bio
55- ✅ Self-modification with operator approval system
56- ✅ Context visualization at `/context`
57- ✅ Semantic search in user memories
58
59## Architecture
60
61- **FastAPI** web framework with async support
62- **pydantic-ai** for LLM agent management
63- **TurboPuffer** for scalable vector memory
64- **AT Protocol** for Bluesky integration
65- **SQLite** for thread context storage
66
67## Development
68
69```bash
70just # Show available commands
71just dev # Run with hot-reload
72just check # Run linting, type checking, and tests
73just fmt # Format code
74just lint # Run ruff linter
75just typecheck # Run ty type checker
76just test # Run test suite
77
78# Bot testing utilities
79just test-post # Test posting to Bluesky
80just test-mention # Test mention handling
81just test-search # Test web search
82just test-thread # Test thread context
83just test-dm # Test DM functionality
84
85# Memory management
86just memory-init # Initialize core memories
87just memory-check # View current memory state
88just memory-migrate # Migrate memories
89```
90
91### Web Interface
92
93**Status Page** (http://localhost:8000/status)
94- Current bot status and uptime
95- Mentions received and responses sent
96- AI mode (enabled/placeholder)
97- Last activity timestamps
98- Error count
99
100**Context Visualization** (http://localhost:8000/context)
101- View all context components that flow into responses
102- Inspect personality, memories, thread context
103- Debug why the bot responded a certain way
104
105## Personality System
106
107The bot's personality is defined in markdown files in the `personalities/` directory. This allows for rich, detailed personality definitions that shape how the bot communicates.
108
109- See `personalities/phi.md` for an example exploring consciousness
110- See `personalities/default.md` for a simple assistant
111- Create your own by adding a `.md` file and setting `PERSONALITY_FILE` in `.env`
112
113## Tools & Capabilities
114
115### Web Search
116The bot can search the web when configured with Google Custom Search API credentials. Add to `.env`:
117- `GOOGLE_API_KEY`: Your Google API key
118- `GOOGLE_SEARCH_ENGINE_ID`: Your custom search engine ID
119
120### Content Moderation
121Built-in moderation filters:
122- Spam detection (excessive caps, repetition, promotional content)
123- Harassment and hate speech filtering
124- Violence and threatening content detection
125- Consistent philosophical responses to moderated content
126
127## Memory System
128
129The bot uses a namespace-based memory architecture with TurboPuffer:
130
131- **Core Memory** (`phi-core`): Personality, guidelines, and capabilities loaded from personality files
132- **User Memory** (`phi-users-{handle}`): Per-user conversation history and facts
133
134Key features:
135- Vector embeddings using OpenAI's text-embedding-3-small
136- Automatic context assembly for conversations
137- Character limits to prevent token overflow
138- User isolation through separate namespaces
139
140See `docs/memory-architecture.md` for detailed documentation.
141
142## Troubleshooting
143
144**Bot gives placeholder responses?**
145- Check your `ANTHROPIC_API_KEY` is set correctly
146- Restart the bot after changing `.env`
147
148**Not seeing mentions?**
149- Verify your `BLUESKY_HANDLE` and `BLUESKY_PASSWORD`
150- Make sure you're using an app password, not your main password
151
152## Project Structure
153
154```
155bot/
156├── src/bot/ # Main application code
157│ ├── agents/ # AI agent implementations
158│ ├── core/ # AT Protocol client and profile management
159│ ├── memory/ # TurboPuffer namespace memory system
160│ ├── services/ # Notification polling and message handling
161│ ├── tools/ # Google search tool
162│ └── main.py # FastAPI application entry
163├── scripts/ # Utility scripts
164│ ├── test_bot.py # Unified testing script (post, mention, search, thread)
165│ └── manage_memory.py # Memory management (init, check, migrate)
166├── personalities/ # Bot personality definitions
167├── docs/ # Architecture documentation
168├── sandbox/ # Reference project analysis
169└── tests/ # Test suite
170```
171
172## Self-Modification System
173
174Phi can evolve its personality with built-in safety boundaries:
175
176- **Free Evolution**: Interests and current state update automatically
177- **Guided Evolution**: Communication style changes need validation
178- **Operator Approval**: Core identity and boundaries require explicit approval via DM
179
180The bot will notify its operator (@alternatebuild.dev) when approval is needed.
181
182## Type Checking
183
184This project uses [ty](https://github.com/astral-sh/ty), an extremely fast Rust-based type checker:
185
186```bash
187just typecheck # Type check all code
188uv run ty check src/ # Check specific directories
189```
190
191## Reference Projects
192
193Inspired by:
194- [Void](https://tangled.sh/@cameron.pfiffer.org/void.git) - Letta/MemGPT architecture
195- [Penelope](https://github.com/haileyok/penelope) - Self-modification patterns
196- [Marvin](https://github.com/PrefectHQ/marvin) - pydantic-ai patterns
197
198Reference implementations are cloned to `.eggs/` for learning.