Skip to content

09. Unique Engineering Highlights

Focus on distinctive work, not ordinary FastAPI/Celery plumbing.

1. Resumable stage/chunk job state machine

Problem: Long OCR/extraction jobs fail mid-document; restarting from scratch wastes LLM spend.
How: DocumentJob + JobStage + JobChunk with unique constraints; APIs to start, resume, or re-run OCR/extraction/merge.
Why interesting: Treats pipeline progress as durable domain state, not just Celery task state.
Tradeoff: More schema and orchestration complexity.
Evidence: db/models.py, core/extraction/router.py, workers/tasks/pipeline_tasks.py.
Interview line: "Jobs are state machines with chunk-level retry, not fire-and-forget tasks."

2. Pluggable OCR backends behind one pipeline

Problem: Teams want to A/B VLM OCR, Sarvam, and Paddle layout without rewriting clients.
How: OCR_ENGINE factory selects vlm | sarvam | layout; pipeline stages stay the same.
Why interesting: Product flexibility with a stable job API.
Tradeoff: Metadata richness and failure modes differ by engine.
Evidence: config.py, core/ocr/.
Interview line: "Clients speak jobs; workers speak OCR providers."

3. Discriminator-driven multi-phase factsheet

Problem: One giant prompt over full OCR is brittle for tribunal forms.
How: Phase1 selects discriminators / fields; Phase2 fills Pydantic sub-models; Phase3 assembles with provenance.
Why interesting: Schema-guided extraction matched to a factsheet manifest.
Tradeoff: More moving parts and prompt templates to maintain.
Evidence: uc1_factsheet/service/phase1.py, phase2.py, factsheet_manifest.json.
Interview line: "We decide what to extract before we extract it."

4. Entities-first with confidence fallback

Problem: Re-reading full OCR for every field is slow and noisy when structured extraction already exists.
How: Prefer entity/attribute context; if confidence < FACTSHEET_CONFIDENCE_THRESHOLD, fall back to broader OCR text.
Why interesting: Explicit quality/latency tradeoff encoded in settings.
Tradeoff: Threshold tuning is empirical.
Evidence: phase2.py, FACTSHEET_CONFIDENCE_THRESHOLD.
Interview line: "Structured extraction is the fast path; OCR text is the safety net."

5. Field-level provenance in API and UI

Problem: Operators will not trust LLM-filled legal forms without sources.
How: Provenance carries doc id, confidence, snippet; UI ProvenanceTooltip surfaces it.
Why interesting: Closes the loop from extraction to human verification.
Tradeoff: Larger payloads; snippet quality depends on upstream chunking.
Evidence: uc1_factsheet/models.py, frontend/src/components/factsheet/ProvenanceTooltip.tsx.
Interview line: "Every prefilled field can point back to evidence."

6. Prefill short-circuit

Problem: Some fields are already known from the case system.
How: prefilled input skips LLM work for provided values in Phase1.
Why interesting: Cheap integration seam for e-Tribunal or clerk entry.
Tradeoff: Must trust upstream prefilled data.
Evidence: phase1.py, factsheet router schemas.
Interview line: "Don't pay for tokens you already know."

7. Async bridge inside sync Celery workers

Problem: SQLAlchemy async + async LLM clients don't run natively in sync Celery tasks.
How: Process-local event loop via run_async_in_worker_loop.
Why interesting: Pragmatic concurrency model without rewriting the worker runtime.
Tradeoff: One loop per process; must avoid nested loop bugs.
Evidence: workers/async_runner.py.
Interview line: "We kept Celery sync and gave it a dedicated asyncio loop."

8. Prompt pack separation

Problem: OCR, extraction, and factsheet prompts evolve independently.
How: Jinja templates under prompts/ with a prompt manager.
Why interesting: Keeps model instructions out of business logic modules.
Tradeoff: Template drift vs code if not tested.
Evidence: prompts/, prompt_manager.py.

9. Base64 image sanitization before LLM context

Problem: OCR markdown can embed huge images that blow context windows and bills.
How: core/text/sanitize.py strips/limits base64 image payloads.
Why interesting: Operational guardrail learned from multimodal pipelines.
Tradeoff: May drop useful figure context.
Evidence: sanitize module + unit test.

10. Unusually complete in-repo wiki and phased plans

Problem: Multi-use-case legal AI platforms are hard to onboard.
How: MkDocs docs/ plus plans/ PRD, TDD, and phase docs.
Why interesting: Strong product/engineering narrative — with the caveat that some docs lead the code (search, auth, CI).
Tradeoff: Docs/code drift risk.
Evidence: docs/, plans/, mkdocs.yml.

What is ordinary (do not oversell)

  • FastAPI + Celery + Redis + Postgres + MinIO
  • React + Vite + TanStack Query + shadcn
  • LiteLLM as a provider shim
  • Docker Compose for local dependencies