ImageWorkflow Workflow

Loading workflow diagram…

triaged

ai-tools (Python) read the full-frame mat + sidecar from the shared dir, produced the canonical crop + thumbnail in derivatives/, and ran Tesseract + OpenCV heuristics. realPath now points at the crop. Upload to S3 runs next.

next: ["upload"]

Upload canonical crop (+ archived full frame) to S3 → uploaded ◷ Pushes realPath (the ai-tools crop) to S3 as the canonical image. When defaults.full_frame_key is present, also archives the original mat under originals/ on S3 for re-processing / QR re-extraction during Python dev. The full-frame archive is planned to drop for real-client tenants. View command

ai-tools crop + Tesseract OCR + OpenCV heuristics → triaged ◷ When fired from NEW: local-file mode. ai-tools reads defaults.full_frame_key + defaults.sidecar_key from the shared dir, produces the canonical crop + thumbnail in derivatives/, and returns deskew/type/detections. realPath is repointed at the crop. When re-run from TRIAGED: same, idempotent. Non-URL mode is the only path browser captures take. Failures keep the image in NEW (async retry). View command

Paid low-res vision pass — ONE image call per image → enriched ◷ Single cheap AI call (~$0.0004) against a ≤512px thumbnail, with triage OCR + flags in context. Populates title/description/subjects/people/places/dense_summary and text-type flags. Can run from TRIAGED (using ssai image_view via imgProxy, skipping S3 upload) or from UPLOADED. Re-runnable from enriched for debugging. View command

Ignore this scan -- blank back or otherwise not worth keeping → ignored Operator triage from the narrate screen. Hides the image from narration immediately and queues it for permanent deletion at intake close. No AI transition lists IGNORED in its `from`, so an ignored image can never be sent for enrichment -- the workflow itself is the guard, no separate check needed. View command

uploaded

Canonical crop pushed to S3. Full-frame archived alongside (until real-client cutover).

next: ["enrich"]

new

Full-frame mat + sidecar on shared dir; awaiting ai-tools crop/triage.

next: ["triage"]

Mark external IIIF/URL image as uploaded without S3 copy → uploaded Sets defaults["storage"]["mode"] = "external_url". Used by IIIF imports so the image remains accessible via its external URL and subsequent transitions can run against it directly. Skips triage — the UPLOADED place lets enrich run against the remote URL. View command

enriched

enrich_from_thumbnail ran with OCR in context. Emits title/description/subjects/people/places/dense_summary and pixelsDone/high-res extraction routing claims.

next: ["extract","close"]

Optional paid high-res extraction — routed by thumbnail sufficiency → extracted ◷ The optional second image call. Runs only when enrich_from_thumbnail sets pixelsDone=false. Dispatches by extraction goal/signals: filled forms → ExtractMetadata; handwriting → TranscribeHandwriting; dense print/layout → OcrMistral. Re-runnable. View command

Close image-level processing → closed Bookkeeping only. Requires pixelsDone=true. The item workflow performs text-only catalog analysis across all images. View command

extracted

Paid high-res pass (Mistral OCR by default; HTR for handwriting, ExtractMetadata for filled forms, CensusExtraction for tabular pages). Emits ai:ocrText upgrades, ai:formFields, ai:tableRows, etc.

next: ["close"]

Close image-level processing → closed Bookkeeping only. Requires pixelsDone=true. The item workflow performs text-only catalog analysis across all images. View command

closed

No more image calls. Item workflow consumes image claims/text/metadata for catalog-level analysis.

next: []

ignored

The operator looked at this scan during the narrate pass and said it carries nothing worth keeping -- in practice a blank photo back. Hidden from the narrate/preview screens immediately so the rest of the stack pages faster, and permanently deleted (row + S3 object) by IgnoredImageService::purgeIntake() when the intake is closed. Reversible until then.

next: []

remove

Soft-delete marker. Image remains in DB/S3 until a later cleanup step removes it.

next: []

Transition descriptions, execution mode, guards and paths
Transition	From → To
Upload canonical crop (+ archived full frame) to S3 ◷ `upload` Pushes realPath (the ai-tools crop) to S3 as the canonical image. When defaults.full_frame_key is present, also archives the original mat under originals/ on S3 for re-processing / QR re-extraction during Python dev. The full-frame archive is planned to drop for real-client tenants.	Free triage complete — proper crop + OCR + type flags extracted → Stored in S3; ready for enrich
Mark external IIIF/URL image as uploaded without S3 copy `external_upload` Sets defaults["storage"]["mode"] = "external_url". Used by IIIF imports so the image remains accessible via its external URL and subsequent transitions can run against it directly. Skips triage — the UPLOADED place lets enrich run against the remote URL.	New image, not yet triaged → Stored in S3; ready for enrich
ai-tools crop + Tesseract OCR + OpenCV heuristics ◷ `triage` When fired from NEW: local-file mode. ai-tools reads defaults.full_frame_key + defaults.sidecar_key from the shared dir, produces the canonical crop + thumbnail in derivatives/, and returns deskew/type/detections. realPath is repointed at the crop. When re-run from TRIAGED: same, idempotent. Non-URL mode is the only path browser captures take. Failures keep the image in NEW (async retry).	New image, not yet triaged → Free triage complete — proper crop + OCR + type flags extracted Free triage complete — proper crop + OCR + type flags extracted → Free triage complete — proper crop + OCR + type flags extracted
Paid low-res vision pass — ONE image call per image ◷ `enrich` Single cheap AI call (~$0.0004) against a ≤512px thumbnail, with triage OCR + flags in context. Populates title/description/subjects/people/places/dense_summary and text-type flags. Can run from TRIAGED (using ssai image_view via imgProxy, skipping S3 upload) or from UPLOADED. Re-runnable from enriched for debugging.	Free triage complete — proper crop + OCR + type flags extracted → Low-res vision pass complete — rich claims emitted Stored in S3; ready for enrich → Low-res vision pass complete — rich claims emitted Low-res vision pass complete — rich claims emitted → Low-res vision pass complete — rich claims emitted
Optional paid high-res extraction — routed by thumbnail sufficiency ◷ `extract` The optional second image call. Runs only when enrich_from_thumbnail sets pixelsDone=false. Dispatches by extraction goal/signals: filled forms → ExtractMetadata; handwriting → TranscribeHandwriting; dense print/layout → OcrMistral. Re-runnable.	Low-res vision pass complete — rich claims emitted → High-res faithful extraction complete High-res faithful extraction complete → High-res faithful extraction complete
Close image-level processing `close` Bookkeeping only. Requires pixelsDone=true. The item workflow performs text-only catalog analysis across all images.	Low-res vision pass complete — rich claims emitted → Image-level pixel work is closed High-res faithful extraction complete → Image-level pixel work is closed Image-level pixel work is closed → Image-level pixel work is closed
Ignore this scan -- blank back or otherwise not worth keeping `ignore` Operator triage from the narrate screen. Hides the image from narration immediately and queues it for permanent deletion at intake close. No AI transition lists IGNORED in its `from`, so an ignored image can never be sent for enrichment -- the workflow itself is the guard, no separate check needed.	New image, not yet triaged → Ignored -- hidden from narration, deleted when the intake closes Free triage complete — proper crop + OCR + type flags extracted → Ignored -- hidden from narration, deleted when the intake closes Stored in S3; ready for enrich → Ignored -- hidden from narration, deleted when the intake closes Low-res vision pass complete — rich claims emitted → Ignored -- hidden from narration, deleted when the intake closes High-res faithful extraction complete → Ignored -- hidden from narration, deleted when the intake closes Image-level pixel work is closed → Ignored -- hidden from narration, deleted when the intake closes