AGENTS.md

# AGENTS.md

## Project Goal
Build a Gradio-based OpenBMB Local AI Workbench for the Build Small Hackathon.
The app should run locally first, deploy as a Hugging Face Space, and document the
small-model choices clearly.

## Project Memory
- Start with `docs/README.md`.
- Use `docs/TASKS.md` as the task checklist.
- Use `docs/IMPLEMENTATION_STATUS.md` to decide whether something is really done.
- Use `docs/PRD_IMPLEMENTATION_MATRIX.md` before claiming PRD or extension PRD completion.
- Use `docs/ACCEPTANCE_CRITERIA.md` before marking work complete.
- Use `docs/ROADMAP.md` to prioritize hackathon work over stretch work.
- Use `docs/ROADMAP_V2_CRITICAL_IMPROVEMENT_PLAN.md` for hard judge-oriented prioritization.
- Use `docs/TEMPLATE_HOWTO.md` before creating a new domain app from the template.
- Use `docs/PLANT_DISCOVERY_APP_PLAN.md` before changing the Plant Discovery reference app.
- Use `docs/PLANT_MODEL_AND_TRAINING_HOWTO.md` before changing Plant Discovery model or training behavior.
- Use `docs/ARCHITECTURE.md` before changing app structure.
- Use `docs/EXTENDING.md` before adding models, tabs, services, or training.
- Main PRD: `HF_PRD_v1.md`.
- Extension PRD: `HF_PRD_ext.md`.

## Hackathon Constraints
- Use Gradio as the app surface.
- Keep all model choices at or below 32B parameters.
- Prefer local/offline inference paths when practical.
- Avoid cloud APIs unless the user explicitly approves them.
- Make the README useful for judges: goal, setup, model choice, local run, Space deployment, demo flow.

## Current MVP Scope
- Start with a working Gradio app and deterministic placeholder service.
- Add real inference incrementally through Ollama, llama.cpp, Transformers, or SGLang.
- Keep training, GGUF export, Trackio, MCP, and agent functionality as documented extension points until implemented.
- Never claim the full PRD is done while placeholders or unchecked PRD tasks remain.

## Commands
- Create venv: `python -m venv .venv`
- Activate venv: `.venv\Scripts\Activate.ps1`
- Install: `python -m pip install -r requirements.txt`
- Install dev tools: `python -m pip install -r requirements-dev.txt`
- Run locally: `python app.py`
- Run tests: `.\scripts\run_tests.ps1`
- Run performance tests: `.\scripts\run_performance.ps1`
- Run quality checks: `.\scripts\run_quality.ps1`

## Code Style
- Prefer small modules with clear responsibilities.
- Keep model IDs in `config/models.yaml`; avoid hardcoding them in UI logic.
- Keep user-facing text concise and demo-oriented.
- Do not download model weights automatically on app startup.

## Verification
- Before claiming the app runs, verify `python app.py` starts locally.
- If Python or dependencies are missing, say exactly what is missing.
- Keep generated caches, model weights, exports, and virtualenvs out of git.
- After implementing a task, update `docs/TASKS.md` and `docs/IMPLEMENTATION_STATUS.md`.
- Every feature needs tests. Add or update unit tests for logic and user-story tests for workflows.
- Whenever a bug, failed check, or regression is found, create or update a test that would catch it before fixing the code.
- Do not mark a feature done until its tests pass or the test blocker is documented.
- Avoid blanket coverage escapes. Do not add `pragma: no cover` without a specific documented reason.
- For PRD work, update `docs/PRD_IMPLEMENTATION_MATRIX.md` along with task/status docs.