# AGENTS.md — Odoo OCR Project

This file provides context and rules for AI agents working on `odoo_ocr`, a local-first invoice OCR pipeline that reads scanned, printed, handwritten, and native-PDF invoices and produces Odoo Enterprise-ready XML.

## Project Goal

Build a Python application that:

1. Classifies incoming invoice files by type (native PDF, scanned print, handwritten, mixed image).
2. Routes each file to a specialized processing branch.
3. Runs OCR using local vision-language models (Ollama or llama.cpp).
4. Extracts a structured invoice representation.
5. Reviews extracted data against the original image using a second vision model.
6. Emits valid Odoo XML for import into Odoo Enterprise.

## Tech Stack

- **Language**: Python 3.11+
- **Dependency management**: `pyproject.toml` (PEP 621); use `uv` or `pip`.
- **Core libraries**:
  - `pydantic` v2 for all data schemas and settings.
  - `pymupdf` and `pdf2image` for PDF ingestion.
  - `Pillow` and `opencv-python-headless` for image preprocessing.
  - `httpx` for HTTP model clients.
  - `lxml` for XML generation and validation.
  - `pytest` and `pytest-asyncio` for tests.
- **Local inference**:
  - Primary runtime: **Ollama** for fast iteration.
  - Optimized/runtime path: **llama.cpp server** (custom GGUF quants).
- **Models**:
  - Document classifier: `Qwen2.5-VL-3B` or heuristics.
  - OCR / extraction: `Qwen2.5-VL-7B` or `GLM-OCR` (preferred for handwriting).
  - Review / validation: `Qwen2.5-VL-7B` or larger (`72B` if available).

## Architecture

```
Input File
  → Classifier (heuristic + small VLM)
    → Branch: digital_pdf      → text/layout extraction
    → Branch: scanned_print    → preprocess → VLM OCR
    → Branch: handwritten      → preprocess → GLM-OCR / handwriting OCR
    → Branch: mixed_unknown    → preprocess → ensemble OCR
      → Structured Extraction VLM
      → Review VLM (image vs extracted JSON)
        → Confidence check
          → XML Builder
            → Odoo XML + sidecar JSON
```

## Code Conventions

1. **Project layout**: keep application code under `src/odoo_ocr/`.
2. **Schemas first**: define Pydantic models before writing business logic.
3. **Type hints**: use `typing` everywhere; run `mypy` in strict mode where practical.
4. **Error handling**: never swallow exceptions; return structured `Result` objects or raise domain exceptions.
5. **Configuration**: use `pydantic-settings` with `config.yaml` and env var overrides.
6. **Logging**: use Python standard `logging`; log every model call latency and token usage.
7. **No hardcoded secrets**: model endpoints, credentials, and paths come from settings.
8. **Tests**: every module must have tests under `tests/`. Use fixtures from `tests/fixtures/`.

## Model Client Rules

1. Support both Ollama and llama.cpp with a unified interface (`BaseVLMClient`).
2. Always emit JSON from VLMs when doing extraction/review. Use constrained prompts, not regex scraping.
3. Retry on transient failures with exponential backoff.
4. Cache model responses by content hash to avoid re-running expensive inference during development.
5. Record per-call metrics (model name, tokens, latency, prompt hash).

## Data Flow Rules

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.
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

Generate Odoo data-import XML compatible with Odoo Enterprise vendor bills:

- `res.partner` (vendor)
- `account.move` (vendor bill header)
- `account.move.line` (invoice lines)
- `account.tax` references by percentage/name

See skill `odoo-xml-import` for detailed field mapping and a sample XML template.

## When to Ask the User

Ask for clarification when:

- The requested change would alter the model stack.
- The change affects the Odoo target schema or import method.
- You are unsure whether a file should be committed or a dependency added.
- A requested feature conflicts with the local-only / privacy constraint.

## Skills Reference

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.