• See deployment.md for production setup and infrastructure requirements.

• NixOS or nix package manager
• Docker with compose plugin
• uv (provided by shell.nix)

Enter the nix shell to get all dependencies:

NIXPKGS_ALLOW_UNFREE=1 nix-shell shell.nix

The shell hook checks that required infrastructure (Postgres, Lavalink) is healthy and warns if anything is down.

Shared services live under infra/. Each has its own docker-compose.yml.

Shared PostgreSQL 16 instance used by Maya and other services.

cd infra/postgres && docker compose up -d

Connection: postgresql://maya:maya@localhost:5432/maya

Async driver (Python): postgresql+asyncpg://maya:maya@localhost:5432/maya

Tables are auto-created by SQLAlchemy init_db() on first run.

Audio streaming server for the Discord bot.

cd infra/lavalink && docker compose up -d

Endpoint: localhost:2333, password: youshallnotpass

Image generation. See infra/comfyui/ for setup details.

infra/           shared infrastructure (postgres, lavalink, comfyui)
lib/             shared libraries (db, otel, sources, comfy, etc.)
src/             applications (maya, discord-bot, tts, feed, crawlers)
tests/           mirrors lib/ and src/
notebooks/       jupyter notebooks
data/            inputs, outputs, datasets

• lib/ = shared code, src/ = applications
• One pyproject.toml at root manages the uv workspace
• Members declared in [tool.uv.workspace]

# start dependencies
cd infra/postgres && docker compose up -d
cd infra/lavalink && docker compose up -d

# run the bot
cd src/maya && uv run python -m bot.main

Configuration is in src/maya/.env.

Maya uses PostgreSQL via SQLAlchemy async. Models are in src/maya/db/models.py.

To record a play event manually (bot offline):

cd src/maya && uv run python -m scripts.record_play URL USER [TITLE] [ARTIST]

To inspect data directly:

docker exec postgres psql -U maya -c "SELECT * FROM play_events ORDER BY played_at DESC LIMIT 10;"

# all tests
uv run pytest tests/ -v --tb=short

# with coverage
uv run pytest tests/ --cov=lib --cov=src --cov-report=term-missing

# maya smoke tests (requires infra running)
cd src/maya && uv run pytest tests/ -v

Coverage minimum: 33%.

• Conventional Commits (feat, fix, refactor, test, chore, etc.)
• No emojis in commits or code
• Python: snake_case, type hints where useful
• Use uv add / uv remove for dependencies
• Use docker compose (space, not hyphen)
• Prefer editing existing files over creating new ones