PROJECT_PLAN.md

CoRGI Custom Demo — Project Plan

Context

• Objective: ship a runnable CoRGI demo (CLI + Gradio) powered entirely by Qwen3-VL for structured reasoning, ROI evidence extraction, and answer synthesis.
• Scope: stay within the corgi_custom package, reuse Qwen3-VL cookbooks where possible, keep dependency footprint minimal (no extra detectors/rerankers).
• Environment: Conda env pytorch, default VLM Qwen/Qwen3-VL-8B-Thinking.

Milestones

Status	Milestone	Notes
✅	Core pipeline skeleton (dataclasses, parsers, Qwen client wrappers)	Already merged in repo.
✅	Project documentation & progress tracking scaffolding	Plan + progress log committed.
✅	CLI runner that prints step-by-step pipeline output	Supports overrides + JSON export.
✅	Gradio demo mirroring CLI functionality	Blocks UI with markdown report messaging.
✅	Automated tests for new modules	CLI + Gradio helpers covered with unit tests.
✅	HF Space deployment automation	Bash script + app harness for zerogpu Spaces.
🟡	Final verification (unit tests, smoke instructions)	Document how to run pytest and the demos.

Work Breakdown Structure

1. Docs & Tracking
   • Finalize plan and progress log templates.
   • Document environment setup expectations.
2. Pipeline UX
   • Implement CLI entrypoint (corgi.cli:main).
   • Provide structured stdout for steps/evidence/answer.
   • Allow optional JSON dump for downstream tooling.
3. Interactive Demo
   • Build Gradio app harness (image upload + question textbox).
   • Stream progress (optional) and display textual reasoning/evidence.
   • Handle model loading errors gracefully.
4. Testing & Tooling
   • Add fixture-friendly helpers to avoid heavy model loads in tests.
   • Write unit tests for CLI argument parsing + formatting.
   • Add regression test for pipeline serialization.
5. Docs & Hand-off
   • Update README/demo instructions.
   • Provide sample command sequences for CLI/Gradio.
   • Capture open risks & future enhancements.
6. Deployment & Ops
   • Add Hugging Face Space entrypoint (app.py).
   • Write deployment helper script (scripts/push_space.sh).
   • Add automated checklists/logs for Space updates.

Risks & Mitigations

• Model loading latency / VRAM → expose config knobs and mention 4B fallback.
• Parsing drift from Qwen outputs → keep parser tolerant; add debug flag to dump raw responses.
• Test runtime → mock Qwen client via fixtures; avoid loading real model in unit tests.

Progress Tracking

• Refer to PROGRESS_LOG.md for dated status updates.
• Update milestone table whenever a deliverable completes.