39 lines
2.8 KiB
Markdown
39 lines
2.8 KiB
Markdown
# 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.
|
||
|
||
## Build, Test, and Development Commands
|
||
- `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.
|
||
|
||
## Coding Style & Naming Conventions
|
||
- 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.
|
||
|
||
## Testing Guidelines
|
||
- 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.
|
||
|
||
## Commit & Pull Request Guidelines
|
||
- 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.
|
||
|
||
## Agent Workflow Tips
|
||
- 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.
|