zzstoatzz.io
a digital entity named phi that roams bsky
phi.zzstoatzz.io
1This is the repository for a bluesky virtual person powered by LLMs and exposed to the web.
2
3This is a python project that uses `uv` as python package manager, `fastapi` and is inspired by `https://tangled.sh/@cameron.pfiffer.org/void`, `https://github.com/haileyok/penelope`, and `https://github.com/PrefectHQ/marvin/tree/main/examples/slackbot` (tangled is github on atproto, you can git clone tangled.sh repos). These projects should be cloned to the `.eggs` directory, along with any other resources that are useful but not worth checking into the repo. We should simply common commands and communicate dev workflows by using a `justfile`.
4
5Work from repo root whenever possible.
6
7## Python style
8- 3.10+ and complete typing (T | None preferred over Optional[T] and list[T] over typing.List[T])
9- use prefer functional over OOP
10- keep implementation details private and functions pure
11
12## Project Structure
13
14- `src/bot/` - Main bot application code
15 - `agents/` - Agents for the LLM
16 - `core/` - Core functionality (AT Protocol client functionality)
17 - `services/` - Services (notification polling, message handling)
18 - `tools/` - Tools for the LLM
19 - `config.py` - Configuration
20 - `database.py` - Database functionality
21 - `main.py` - FastAPI application entry point
22 - `personality.py` - Personality definition
23 - `response_generator.py` - Response generation
24 - `status.py` - One page status tracker
25 - `templates.py` - HTML templates
26
27- `tests/` - Test files
28- `scripts/` - Utility scripts (test_post.py, test_mention.py)
29- `sandbox/` - Documentation and analysis
30 - Reference project analyses
31 - Architecture plans
32 - Implementation notes
33- `.eggs/` - Cloned reference projects (void, penelope, marvin)
34
35## Testing
36- Run bot: `just dev`
37- Test posting: `just test-post`
38
39## Important Development Guidelines
40- STOP DEFERRING IMPORTS. Put all imports at the top of the file unless there's a legitimate circular dependency issue. Deferred imports make code harder to understand and debug.