# AGENTS.md

## Purpose

Guidance for code agents working in this repository. Follow existing patterns over personal preference.

## Stack

- Python 3.13
- Package layout under `src/qimg`
- CLI built with `typer`
- Tests with `pytest`
- Optional ML/runtime deps behind extras

## Style Conventions

- Use `from __future__ import annotations` in Python modules.
- Prefer explicit typing throughout (`dict[str, Any]`, `list[str]`, unions with `|`).
- Use `@dataclass(slots=True)` for lightweight data containers; use `frozen=True` when immutable.
- Keep functions focused and deterministic where possible.
- Prefer small helper functions for repeated logic.
- Use `Path` from `pathlib` for filesystem paths.
- Use 4-space indentation and keep formatting close to current files.
- Keep comments sparse and only for non-obvious behavior.

## Error Handling

- Raise explicit exceptions with actionable messages.
- Fail early on missing config/model/data requirements.
- For optional dependencies, keep graceful fallbacks where already used.

## CLI and Output

- Route user actions through `qimg.service` instead of duplicating logic in CLI handlers.
- Keep CLI output consistent with existing modes:
  - human-readable rich output
  - `--json` for structured output
  - `--files` where applicable
- Preserve existing command names/options and backward-compatible behavior.

## Models and MCP

- Runtime model management belongs in `src/qimg/model_manager.py`.
- Model artifacts belong under `models/`; do not add new executable scripts there.
- MCP protocol/tool names live in `src/qimg/mcp/protocol.py`; keep changes backward compatible.

## Testing Expectations

- Add/update tests for behavior changes under `tests/`.
- Follow current test style: small fixtures/helpers, direct assertions, minimal mocking.
- Prefer deterministic tests that avoid network access.
- Run:
  - `uv run pytest -q`
  - or targeted tests for touched areas.

## Dependency and License Hygiene

- Keep heavy dependencies optional via extras when possible.
- Do not introduce GPL/AGPL-licensed direct dependencies without explicit approval.
- Keep metadata aligned (`pyproject.toml`, `LICENSE`, docs).

## Change Discipline

- Make minimal, scoped edits.
- Do not rename public APIs/commands without clear migration handling.
- Update docs when user-facing behavior changes.