Menu
Use when working in examples/ocr, or running / debugging the OCR→FiftyOne datapipe example (multi-LLM structured OCR on passport/id-doc images).
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when asked to create, scaffold, or build a NEW datapipe pipeline or project (any size — plain ETL/ingest, ML training with metrics, LLM-processing steps, annotation loops, viewers/UI), usually in an empty directory outside the datapipe repo. Also when a user describes a recurring data-processing task ("files keep arriving and I need to...") and no pipeline exists yet.
Use when working in the epoch8 datapipe repo with the examples/* folders, when asked to run or debug any datapipe example pipeline on your own data, or when unsure which example or setup skill applies.
Use when setting up or running examples/detection_tags — a self-contained datapipe detection demo built around tags (per-scenario metrics), split into two parts around a checkpoint (train a baseline, then add a tagged TRAIN batch and retrain, watching the tag metric rise), with a FiftyOne view and injected ground truth (no Label Studio). Also for "add a tagged batch, retrain, watch the tag metric rise" and for rehearsing that retraining demo from a saved checkpoint.
Use when setting up or running examples/e2e_template (image_detection or image_keypoints) — datapipe YOLO/Label Studio pipelines — or debugging their install, stages, training, or FiftyOne output.
Use when working in examples/embedder_fiftyone, or running / debugging the embedder→FiftyOne datapipe example (DINOv2/DINOv3 image embeddings, UMAP, similarity search).
Use when working in examples/sam_cvat, or when setting up / running / debugging the datapipe SAM3→CVAT pre-annotation example, on the cats-n-dogs demo data or on your own images.
| name | setup-ocr |
| description | Use when working in examples/ocr, or running / debugging the OCR→FiftyOne datapipe example (multi-LLM structured OCR on passport/id-doc images). |
This skill = run multi-engine LLM OCR on YOUR passport/id-doc images and publish structured JSON to FiftyOne. The HF dataset (ud-synthetic/printed-usa-passports) is just a smoke-test; the real goal is your own images — set the knobs below first.
Ask first — don't assume (only the unresolved): demo (HF passports) or your own images? which Postgres + which database for DB_URL — never point it at an existing DB or drop in a localhost default without confirming; reuse an existing venv / uv env or create a fresh one? which OCR engines (OCR_ENGINES → subset of openai,gemini,qwen; each needs its API key)? which model names (defaults below — keep or change in config.py ENGINE_REGISTRY)? cost cap (HF_LIMIT in demo mode; local mode = all images × all engines)? custom output schema (default IdDocument in config.py or user edits OUTPUT_MODEL)? surface stage logs or run quiet?
How to work: read the setup, then propose a short plan and get a go-ahead before touching anything. Prepare .env and pause for the user to verify it before running. Run each stage with its logs shown and, after each, say what you did and what changed — don't run the pipeline silently. If a stage fails and the cause isn't clear from the normal logs, re-run it with datapipe --debug … run (or --debug-sql for SQL errors); debug is very verbose, so send it to a file and grep it (e.g. datapipe --debug run > /tmp/dp_debug.log 2>&1; grep -nEi "error|traceback" /tmp/dp_debug.log) rather than dumping it inline.
LOCAL_IMAGES_DIR=/path (recursive .jpg/.jpeg/.png/.webp/.heic; file stem → image_id).
Local wins when the dir exists and has images (use_local_images() in config.py); otherwise HF fallback.HF_DATASET_NAME, HF_SPLIT, HF_LIMIT (caps download and LLM calls in demo mode).OCR_ENGINES=openai,gemini (comma list). Model names + inference kwargs live in config.py
ENGINE_REGISTRY (not .env) — ask which models to use, then edit ENGINE_REGISTRY[..]["model"] if needed.
Current defaults (verify against config.py): openai → gpt-5.4-nano, gemini → gemini-3.5-flash,
qwen → qwen3.7-plus.FIFTYONE_DATASET_NAME (default datapipe_ocr).OUTPUT_MODEL in config.py — ocr_prompt() auto-follows the pydantic schema.Stages (labels match app.py): ingest (list images + engines) → ocr (LLM inference, images × engines
cross-join, chunk_size=2) → fiftyone (per-engine {engine_id}_ocr StringField via Caption Viewer).
DB_URL (SQLAlchemy URL). Not started by the example; an empty DB is fine —
datapipe db create-all auto-creates tables. .env.example default ...postgres@localhost:5432/postgres.OPENAI_API_KEY, GEMINI_API_KEY (or GOOGLE_API_KEY), QWEN_API_KEY.
Geoblock: openai / gemini call the native OpenAI / Google APIs — blocked from Russian IPs. Workarounds
(proxy/router) are possible outside this example; from RU, prefer qwen (DashScope) or run from a non-blocked network.fiftyone plugins download https://github.com/harpreetsahota204/caption_vieweruv + Python 3.10–3.12 → uv sync
(pins CPU torch==2.6.0 for transitive cv-pipeliner; OCR itself doesn't use it).ud-synthetic/printed-usa-passports) is public — no HF_TOKEN required.Skip if you have data. Leave LOCAL_IMAGES_DIR unset → HF fallback (HF_DATASET_NAME=ud-synthetic/printed-usa-passports,
HF_LIMIT=10 in .env.example keeps LLM cost low); run §Run as-is to confirm install/DB/API keys/FiftyOne.
cp .env.example .env # DB_URL, API keys, OCR_ENGINES, LOCAL_IMAGES_DIR or HF_*, FIFTYONE_DATASET_NAME
uv sync && source .venv/bin/activate # else prefix each command with `uv run`
fiftyone plugins download https://github.com/harpreetsahota204/caption_viewer # once per venv
datapipe db create-all && datapipe run
# one stage: datapipe step --labels=stage=ingest run (ingest|ocr|fiftyone)
Run from examples/ocr/ (load_dotenv() in app.py — wrong cwd breaks .env).
OCR runs a cross-product of images × enabled engines. Demo: HF_LIMIT caps both. Local: every image hits
every engine — confirm image count and OCR_ENGINES before a full run.
fiftyone app launch --remote --address 0.0.0.0 --port 5151 --wait -1 # venv active; SSH-forward 5151
Open FIFTYONE_DATASET_NAME. Per engine: open a sample → add panel → Caption Viewer → field
openai_ocr / gemini_ocr / qwen_ocr. Open multiple panels to compare engines side by side.
ocr_results table has a row per (image_id, engine_id) pair with populated output_json.{engine_id}_ocr fields containing structured JSON.LOCAL_IMAGES_DIR and HF misconfigured; or local dir has no supported suffixes.OCR_ENGINES empty or unknown IDs (must match ENGINE_REGISTRY keys in config.py).OPENAI_API_KEY, GEMINI_API_KEY, QWEN_API_KEY).qwen or a non-blocked network/proxy.HF_LIMIT in demo mode, or large local folder with all three engines enabled.~/.fiftyone datadir (FCV mismatch / port bind). Use a fresh
dir: FIFTYONE_DATABASE_DIR=/tmp/fo_db.OUTPUT_MODEL → re-run datapipe step --labels=stage=ocr run so engines pick up the new prompt.