# AI Agent Operating Guide

## Repository Map
- `app.py` — Gradio WebUI built on top of `scripts.open_provence_infer` for inference.
- `main.py` — Minimal CLI entry point (currently prints a placeholder message).
- `Makefile` — `make server` runs the local UI; `make pre-deploy` regenerates `requirements.txt`.
- `pyproject.toml` / `uv.lock` — Project dependencies and tooling; dev group includes `ruff`, `pyright`, and `tox-uv`.
- `requirements.txt` — Pinned dependency list generated via `uv export` for Hugging Face Spaces builds.
- `tox.ini` — tox-uv configuration with linting, formatting, and type-check jobs.

## Environment Setup
- Target Python 3.12 (see `.python-version` and `pyproject.toml`).
- Run `uv sync --all-extras --dev` to create the virtualenv and install CPU-friendly Torch and related deps.
- Ensure network access so Hugging Face models and tokenizers can download on first run.
- NLTK resources `punkt` / `punkt_tab` are downloaded automatically at startup; no manual step required.

## Daily Workflow
- Launch the UI locally with `make server` (invokes `uv run python app.py`).
- After dependency changes, run `make pre-deploy` so `requirements.txt` matches the locked environment before deploying to Spaces.
- Run the full CI stack with `uv run tox run-parallel -e lint,format-check,typecheck`; it executes Ruff lint/format and Pyright simultaneously via tox-uv. When asked to “run tox,” default to this command for faster feedback.
- For focused iteration, call individual jobs as needed:
  ```bash
  uv run ruff check .
  uv run ruff format --check --diff
  uv run pyright app.py main.py
  ```
- Whenever inference logic changes, manually validate via the Gradio UI by entering representative question/title/text inputs.

## Coding Standards & Tooling
- Ruff enforces 99-character lines and requires `from __future__ import annotations`; prefer `ruff check --fix` when adjusting code.
- Pyright runs in `standard` mode targeting Python 3.12, focusing on `app.py` and `main.py`.
- Add new dependencies with `uv add`; keep `pyproject.toml`, `uv.lock`, and exported `requirements.txt` in sync.

## Pre-Deploy Checklist
- Run `make pre-deploy` to regenerate `requirements.txt` from the current lockfile.
- Ensure `tox -e lint`, `tox -e format-check`, and `tox -e typecheck` succeed.
- Confirm `make server` launches and the model can load/run inside the Gradio UI.
- Update documentation (`README.md`, etc.) if behaviour or entry points changed.