zzstoatzz.io
-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
+29
-17
README.md
+29
-17
README.md
···
2
2
3
3
A virtual person for Bluesky powered by LLMs, built with FastAPI and pydantic-ai.
4
4
5
-
> **Quick Start**: See [QUICKSTART.md](QUICKSTART.md) to get running in 5 minutes!
5
+
## Quick Start
6
6
7
-
## Setup
7
+
Get your bot running in 5 minutes:
8
8
9
-
1. Install dependencies:
10
9
```bash
11
-
just sync
10
+
# Clone and install
11
+
git clone <repo>
12
+
cd bot
13
+
uv sync
14
+
15
+
# Configure (copy .env.example and add your credentials)
16
+
cp .env.example .env
17
+
18
+
# Run the bot
19
+
just dev
12
20
```
13
21
14
-
2. Copy `.env.example` to `.env` and add your credentials:
22
+
That's it! Your bot is now listening for mentions.
23
+
24
+
## Configuration
25
+
26
+
Edit `.env` with your credentials:
15
27
- `BLUESKY_HANDLE`: Your bot's Bluesky handle
16
-
- `BLUESKY_PASSWORD`: App password from Bluesky settings
17
-
- `ANTHROPIC_API_KEY`: For AI responses (optional, falls back to placeholder)
28
+
- `BLUESKY_PASSWORD`: App password (not your main password!)
29
+
- `ANTHROPIC_API_KEY`: Your Anthropic key for AI responses
18
30
- `BOT_NAME`: Your bot's name (default: "Bot")
19
31
- `PERSONALITY_FILE`: Path to personality markdown file (default: "personalities/phi.md")
20
-
21
-
3. Test posting:
22
-
```bash
23
-
just test-post
24
-
```
25
-
26
-
4. Run the bot:
27
-
```bash
28
-
just dev
29
-
```
30
32
31
33
## Current Features
32
34
···
77
79
## Memory Architecture
78
80
79
81
See `sandbox/memory_architecture_plan.md` for the planned memory system using TurboPuffer.
82
+
83
+
## Troubleshooting
84
+
85
+
**Bot gives placeholder responses?**
86
+
- Check your `ANTHROPIC_API_KEY` is set correctly
87
+
- Restart the bot after changing `.env`
88
+
89
+
**Not seeing mentions?**
90
+
- Verify your `BLUESKY_HANDLE` and `BLUESKY_PASSWORD`
91
+
- Make sure you're using an app password, not your main password
80
92
81
93
## Reference Projects
82
94
+6
-5
STATUS.md
+6
-5
STATUS.md
···
1
1
# Project Status
2
2
3
-
## Current Phase: Placeholder Bot Complete ✅
3
+
## Current Phase: AI Bot with Thread Context Complete ✅
4
4
5
5
### Completed
6
6
- ✅ Created project directory structure (.eggs, tests, sandbox)
···
49
49
50
50
### Future Work
51
51
52
-
After thread context is working:
53
-
- TurboPuffer for vector memory (user facts, etc)
54
-
- Self-modification capabilities
55
-
- Multi-tier memory system
52
+
- TurboPuffer for vector memory (user facts, long-term memory)
53
+
- Self-modification capabilities (inspired by Penelope)
54
+
- Multi-tier memory system (core/user/archival like Void)
55
+
- Advanced personality switching
56
+
- Proactive posting based on interests
56
57
57
58
## Key Decisions to Make
58
59
- Which LLM provider to use (OpenAI, Anthropic, etc.)