Repository Guidelines

Project Structure & Module Organization

main.py wires the GTK Application and guards headless runs; UI widgets live in sidebar_window.py and message_widget.py.
ollama_client.py wraps streaming calls and threading helpers so GTK stays responsive.
Conversation state persists through conversation_manager.py and JSON files under data/conversations/; keep writes atomic.
Shared settings belong in config.py, styles in styles.css, and tooling defaults in pyproject.toml; prefer adding focused modules over bloating these.
Tests mirror the source tree under tests/, with fixtures in tests/fixtures/ for reusable transcripts and metadata.

python -m venv .venv && source .venv/bin/activate — creates and activates the project’s virtual environment.
pip install -r requirements.txt — installs GTK, Ollama, and tooling dependencies.
python main.py — launches the sidebar; requires a Wayland/X11 session.
AI_SIDEBAR_HEADLESS=1 python main.py — skips GTK startup for CI smoke checks.
AI_SIDEBAR_HEADLESS=1 pytest — runs the full test suite; combine with -k "conversation" for targeted checks.

Use 4-space indentation and format with black .; avoid tab characters.
Lint via ruff check . and fix violations instead of adding ignores.
Files stay snake_case; classes use PascalCase; callbacks adopt verb-based snake_case (e.g., handle_stream_chunk).
Keep GTK signal handlers thin and delegate behavior to helpers or managers.

Prefer pytest parameterized cases for conversation flows; store golden transcripts in tests/fixtures/responses/.
Name tests test_<module>_<behavior> (e.g., test_conversation_manager_persists_history).
Cover threading boundaries by mocking Ollama responses and asserting GTK updates via GLib.idle_add.
Use AI_SIDEBAR_HEADLESS=1 when exercising tests or scripts in non-GUI environments.
Run pytest --maxfail=1 before commits to catch regressions early.

Follow the Conventional Commit pattern (feat:, fix:, refactor:) to keep the changelog clean.
Keep commits scoped to a single concern and include tests or fixtures when changing behavior.
Pull requests should summarize user-facing changes, list manual test steps, and attach screenshots or recordings for UI tweaks.
Reference related issues with Closes #ID and call out follow-up tasks to keep planning clear.

When prototyping new UI flows, add exploratory scripts under experiments/ and clean them up before merging.
Document new configuration toggles in config.py docstrings and echo them in the README so users can discover them easily.