zzstoatzz.io
a digital entity named phi that roams bsky
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- never use `pytest.mark.asyncio`, its unnecessary
12
13## Project Structure
14
15- `src/bot/` - Main bot application code
16 - `agents/` - Agents for the LLM
17 - `core/` - Core functionality (AT Protocol client functionality)
18 - `services/` - Services (notification polling, message handling)
19 - `tools/` - Tools for the LLM
20 - `config.py` - Configuration
21 - `database.py` - Database functionality
22 - `main.py` - FastAPI application entry point
23 - `personality.py` - Personality definition
24 - `response_generator.py` - Response generation
25 - `status.py` - One page status tracker
26 - `templates.py` - HTML templates
27
28- `tests/` - Test files
29- `scripts/` - Curated utility scripts that have proven useful
30- `sandbox/` - Proving ground for experiments, analysis, and unproven scripts
31 - Reference project analyses
32 - Architecture plans
33 - Implementation notes
34 - Experimental scripts (graduate to scripts/ once proven useful)
35- `.eggs/` - Cloned reference projects (void, penelope, marvin)
36
37## Script Graduation Process
38New scripts start in `sandbox/`, get promoted to `scripts/` once proven useful, and may eventually get just commands added if the workflow should be broadcast to other developers. Not everything graduates - most things stay in sandbox.
39
40## Testing
41- Run bot: `just dev`
42- Test posting: `just test-post`
43
44## Important Development Guidelines
45- 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.