a digital person for bluesky
cameron.stream
1# Configuration Guide
2
3### Option 1: Migrate from existing `.env` file (if you have one)
4```bash
5python migrate_config.py
6```
7
8### Option 2: Start fresh with example
91. **Copy the example configuration:**
10 ```bash
11 cp config.yaml.example config.yaml
12 ```
13
142. **Edit `config.yaml` with your credentials:**
15 ```yaml
16 # Required: Letta API configuration
17 letta:
18 api_key: "your-letta-api-key-here"
19 project_id: "project-id-here"
20
21 # Required: Bluesky credentials
22 bluesky:
23 username: "your-handle.bsky.social"
24 password: "your-app-password"
25 ```
26
273. **Run the configuration test:**
28 ```bash
29 python test_config.py
30 ```
31
32## Configuration Structure
33
34### Letta Configuration
35```yaml
36letta:
37 api_key: "your-letta-api-key-here" # Required
38 timeout: 600 # API timeout in seconds
39 project_id: "your-project-id" # Required: Your Letta project ID
40```
41
42### Bluesky Configuration
43```yaml
44bluesky:
45 username: "handle.bsky.social" # Required: Your Bluesky handle
46 password: "your-app-password" # Required: Your Bluesky app password
47 pds_uri: "https://bsky.social" # Optional: PDS URI (defaults to bsky.social)
48```
49
50### Bot Behavior
51```yaml
52bot:
53 fetch_notifications_delay: 30 # Seconds between notification checks
54 max_processed_notifications: 10000 # Max notifications to track
55 max_notification_pages: 20 # Max pages to fetch per cycle
56
57 agent:
58 name: "void" # Agent name
59 model: "openai/gpt-4o-mini" # LLM model to use
60 embedding: "openai/text-embedding-3-small" # Embedding model
61 description: "A social media agent trapped in the void."
62 max_steps: 100 # Max steps per agent interaction
63
64 # Memory blocks configuration
65 blocks:
66 zeitgeist:
67 label: "zeitgeist"
68 value: "I don't currently know anything about what is happening right now."
69 description: "A block to store your understanding of the current social environment."
70 # ... more blocks
71```
72
73### Queue Configuration
74```yaml
75queue:
76 priority_users: # Users whose messages get priority
77 - "cameron.pfiffer.org"
78 base_dir: "queue" # Queue directory
79 error_dir: "queue/errors" # Failed notifications
80 no_reply_dir: "queue/no_reply" # No-reply notifications
81 processed_file: "queue/processed_notifications.json"
82```
83
84### Threading Configuration
85```yaml
86threading:
87 parent_height: 40 # Thread context depth
88 depth: 10 # Thread context width
89 max_post_characters: 300 # Max characters per post
90```
91
92### Logging Configuration
93```yaml
94logging:
95 level: "INFO" # Root logging level
96 loggers:
97 void_bot: "INFO" # Main bot logger
98 void_bot_prompts: "WARNING" # Prompt logger (set to DEBUG to see prompts)
99 httpx: "CRITICAL" # HTTP client logger
100```
101
102## Environment Variable Fallback
103
104The configuration system still supports environment variables as a fallback:
105
106- `LETTA_API_KEY` - Letta API key
107- `BSKY_USERNAME` - Bluesky username
108- `BSKY_PASSWORD` - Bluesky password
109- `PDS_URI` - Bluesky PDS URI
110
111If both config file and environment variables are present, environment variables take precedence.
112
113## Migration from Environment Variables
114
115If you're currently using environment variables (`.env` file), you can easily migrate to YAML using the automated migration script:
116
117### Automated Migration (Recommended)
118
119```bash
120python migrate_config.py
121```
122
123The migration script will:
124- ✅ Read your existing `.env` file
125- ✅ Merge with any existing `config.yaml`
126- ✅ Create automatic backups
127- ✅ Test the new configuration
128- ✅ Provide clear next steps
129
130### Manual Migration
131
132Alternatively, you can migrate manually:
133
1341. Copy your current values from `.env` to `config.yaml`
1352. Test with `python test_config.py`
1363. Optionally remove the `.env` file (it will still work as fallback)
137
138## Security Notes
139
140- `config.yaml` is automatically added to `.gitignore` to prevent accidental commits
141- Store sensitive credentials securely and never commit them to version control
142- Consider using environment variables for production deployments
143- The configuration loader will warn if it can't find `config.yaml` and falls back to environment variables
144
145## Advanced Configuration
146
147You can programmatically access configuration in your code:
148
149```python
150from config_loader import get_letta_config, get_bluesky_config
151
152# Get configuration sections
153letta_config = get_letta_config()
154bluesky_config = get_bluesky_config()
155
156# Access individual values
157api_key = letta_config['api_key']
158username = bluesky_config['username']
159```