Rpa_Skills/rpa-dashboard-ai/templates/contract.md

Dashboard data contract (AI)

Everything in the no-AI contract (../rpa-dashboard-no-ai/templates/contract.md) applies unchanged: the {event, data} envelope, its events, its actions and its rules. The AI dashboard adds extraction runs, review rows and the approve gate. These shapes come from the Superbill prototype, trimmed.

Shapes

Run       { job_id, document, status: pending|queued|running|done|failed, model,
            pages_done, pages_total, summary: { green, amber, red, blank, unscored } | null,
            approved, error }
ReviewRow { row_id, field, value, band: green|amber|red|blank|unscored,
            score, reason, verified, corrected_value }

• summary counts the run's rows per band. It is null until the run is done.
• score is the field's worst word score, or null when it has none.
• corrected_value is null until a reviewer saves a value different from value.

Endpoints (web: {API_BASE} + path, JSON in and out)

Method and path	What it does
GET /runs	{runs: [Run]}. The page opens the first one.
GET /runs/{job_id}	One Run.
GET /runs/{job_id}/review	{rows: [ReviewRow]}. Empty until the run is done.
GET /runs/{job_id}/document	The source document (PDF or image) shown beside the fields.
PATCH /review/{row_id}	Body {corrected_value?, verified}. Patches one row, returns it.
POST /runs/{job_id}/verify-remaining	Verifies every flagged row not yet verified. Returns {verified: n}.
POST /runs/{job_id}/approve	The approve gate. 409 {detail} while the run isn't done or any flagged row is unverified, else 200 {ok: true}.

Errors answer with a non-2xx status and {detail: "<why>"}. The page shows detail.

Rules

• Bands come from templates/web/bands.py and nowhere else: green ≥0.95, amber 0.90–0.95, red <0.90. A field takes its worst word score. A blank mandatory field is blank, whatever its score. No scores is unscored.
• Flagged = every band but green. Each flagged row must be verified before approval.
• The server enforces the gate. The page disables nothing that matters for safety: it asks, and shows the server's refusal.
• Drafts: the page sends nothing while a reviewer types. Save sends one PATCH per edited row (with verified: true). Leaving with unsaved edits asks first.
• Polling: while a run is queued or running, the page polls GET /runs/{job_id} every 1.5s and shows "page X of Y". It stops when the run settles.
• Caveat: the legend always shows that colour reflects print clarity, not correctness.

templates/web/server_stub.py implements all of this on sample data, standard library only. A real backend serves the same endpoints with the same rules.

Desktop (PyQt, no web server)

The same endpoints and rules travel over the Qt bridge instead of HTTP:

• Page to Python: one slot, ai_request(id, method, path, body). path is the endpoint path above without {API_BASE}, body is a JSON string ("{}" when there is none).
• Python to page: one envelope, {event: "ai_response", data: {id, status, body}}, with the same status and JSON body the web endpoint would answer.
• GET /runs/{job_id}/document answers an SVG string or a URL the page can load (for example a file:/// path to the PDF).

templates/desktop/ai_bridge.py adds that slot to the no-AI Bridge. It hands each request to the review backend's dispatch(method, path, body) (server_stub.py until the project has its own), so the approve gate is enforced in Python, never in the page.