From 3661831221c4ed2e62a34a9c25e5edb4d3d986ff Mon Sep 17 00:00:00 2001 From: Florian Egger Date: Fri, 21 Aug 2026 14:06:48 +0200 Subject: [PATCH] Add review skill and make review stage mandatory in AGENTS.md - Add .agents/skills/review/SKILL.md with a required review checklist covering project rules, model client rules, pipeline rules, XML rules, and test rules. - Update AGENTS.md with a dedicated 'Review Stage Rules' section that makes review mandatory and maps confidence thresholds to XML generation behavior. - Add review skill to the skills reference. - Add .ruff_cache/ to .gitignore and keep agent XML templates out of the '*.xml' ignore rule. --- .agents/skills/review/SKILL.md | 62 ++++++++++++++++++++++++++++++++++ .gitignore | 2 ++ AGENTS.md | 20 +++++++++-- 3 files changed, 81 insertions(+), 3 deletions(-) create mode 100644 .agents/skills/review/SKILL.md diff --git a/.agents/skills/review/SKILL.md b/.agents/skills/review/SKILL.md new file mode 100644 index 0000000..04d6280 --- /dev/null +++ b/.agents/skills/review/SKILL.md @@ -0,0 +1,62 @@ +--- +name: review +description: Use this skill when reviewing code, tests, or design decisions in the odoo_ocr project before approving or committing changes. +--- + +# Review Skill + +Use this skill whenever you are asked to review code, tests, architecture, or any proposed change in the `odoo_ocr` project. + +## Required Review Checklist + +Before approving any change, verify the following. If any item fails, flag it and request a fix. + +### 1. Project Rules Compliance + +- [ ] New code lives under `src/odoo_ocr/`. +- [ ] Pydantic schemas are updated or added before business logic changes. +- [ ] Type hints are present; `mypy --strict` passes or only has justified exceptions. +- [ ] No hardcoded secrets, endpoints, or model names outside of `config.py` / settings. +- [ ] Logging is used; model calls log latency and token usage. + +### 2. Model Client Rules + +- [ ] Model calls go through `BaseVLMClient` (Ollama or llama.cpp). +- [ ] Extraction/review prompts force JSON output; no regex scraping of prose. +- [ ] Retries use exponential backoff for transient failures. +- [ ] Cache keys include prompt + image hash + model + temperature. + +### 3. Pipeline Rules + +- [ ] Every invoice must pass through the **review stage** before XML generation. +- [ ] `ReviewResult` includes `valid`, `confidence`, and `issues`. +- [ ] Confidence thresholds from `config.yaml` are respected: + - `>= 0.90`: generate final XML. + - `0.75–0.89`: generate XML with human-review flag. + - `< 0.75`: do not generate final XML; emit sidecar JSON only. +- [ ] The original image is passed to the review VLM alongside the extracted JSON. + +### 4. XML Rules + +- [ ] Generated XML is parseable by `lxml`. +- [ ] Required Odoo records are present: `res.partner`, `account.move`, `account.move.line`. +- [ ] Tax records are deterministic by rate/type. +- [ ] External IDs are sanitized and stable. + +### 5. Test Rules + +- [ ] New modules have tests under `tests/`. +- [ ] Model calls are mocked in unit tests (use `FakeVLMClient` from `conftest.py`). +- [ ] `pytest`, `ruff check src tests`, and `mypy src/odoo_ocr --strict` all pass. + +## Review Output Format + +When asked to review, produce a concise report with: + +1. **Summary**: what changed and whether it looks correct. +2. **Checklist results**: pass/fail per section above. +3. **Required fixes**: blockers that must be addressed. +4. **Suggestions**: non-blocking improvements. +5. **Verdict**: `APPROVE`, `APPROVE WITH NITS`, or `REQUEST CHANGES`. + +If the user did not ask a specific question, default to reviewing the most recent changes in the working tree or the file(s) they mentioned. diff --git a/.gitignore b/.gitignore index 2dad4b5..61ed358 100644 --- a/.gitignore +++ b/.gitignore @@ -47,6 +47,7 @@ dmypy.json htmlcov/ .tox/ .nox/ +.ruff_cache/ # Project-specific out/ @@ -54,5 +55,6 @@ output/ *.xml !tests/fixtures/*.xml !templates/*.xml +!src/odoo_ocr/.agents/skills/odoo-xml-import/templates/*.xml .cache/ ~/.cache/ diff --git a/AGENTS.md b/AGENTS.md index f4ad7b0..0b6d256 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,13 +69,26 @@ Input File ## Data Flow Rules -1. Every invoice must produce: +1. Every invoice must pass through the **review stage** before XML generation. The review model compares the original image with the extracted JSON and produces a `ReviewResult`. +2. Every invoice must produce: - A Pydantic `ExtractedInvoice` object. - A review result (`ReviewResult`) with confidence score and issue list. - An Odoo XML file (unless blocked by low confidence). - A sidecar JSON file with metadata, timings, and confidence. -2. If review confidence is below the configured threshold, mark the invoice for human review and do not generate final XML (or generate a draft with a warning flag). -3. Never send invoice data outside the local model endpoints. +3. If review confidence is below the configured threshold, mark the invoice for human review and do not generate final XML (or generate a draft with a warning flag). +4. Never send invoice data outside the local model endpoints. + +## Review Stage Rules + +1. The review stage is **mandatory**, not optional. +2. The review VLM must receive both the original invoice image and the extracted `ExtractedInvoice` JSON. +3. The review prompt asks the model to verify field presence, arithmetic, and consistency. +4. The `ReviewResult` must include a confidence score between 0.0 and 1.0 and a list of issues. +5. XML generation must respect the confidence thresholds in `config.yaml`: + - `confidence >= 0.90`: generate final XML. + - `0.75 <= confidence < 0.90`: generate XML with a human-review flag. + - `confidence < 0.75`: do not generate final XML; emit sidecar JSON only. +6. See skill `review` for the full review checklist. ## Odoo XML Target @@ -104,3 +117,4 @@ Agents should load the relevant project skills from `.agents/skills/`: - `odoo-ocr-pipeline` — when implementing classifier, branches, OCR, extraction, or review. - `odoo-xml-import` — when generating or validating Odoo XML. - `local-vlm-client` — when writing model clients or prompts. +- `review` — when reviewing code, tests, or design decisions before approving changes.