docs/07-development-plan.md

Objectverse Diary — Detailed Development Plan

Purpose

This document turns the day-by-day schedule into an execution plan for completing Objectverse Diary from the initial mock MVP to hackathon submission.

The plan is intentionally staged. Each phase has a clear goal, implementation scope, verification method, and exit criteria.

Current Baseline

As of 2026-06-05, the project has:

• initialized project structure
• root README and AGENTS instructions
• .codex/skills/ project guidance
• initial Gradio mock MVP
• six stable example objects
• mock object understanding JSON
• mock persona and diary generation
• object chat with mock persona consistency
• share card HTML preview
• anonymized trace JSON saving under data/traces/
• six stable public mock traces under data/traces/samples/
• deterministic SFT preview generator and dataset plan
• public trace JSONL exporter
• failure notes template
• scripts/generate_sample_traces.py
• scripts/generate_dataset.py
• scripts/export_traces.py
• stdlib unittest smoke tests for the mock MVP
• runtime configuration boundary documented in docs/RUNTIME.md
• initial-stage acceptance script at scripts/check_initial_stage.py

Not yet done:

• GitHub repo creation
• Hugging Face Space creation
• real MiniCPM-V or fallback VLM integration
• real llama.cpp / llama-cpp-python text runtime
• real curated dataset
• LoRA fine-tuning
• model card completion
• Field Notes article
• demo video
• final submission package

Phase 1 — Initial Mock MVP

Goal: validate the product loop before model integration.

Scope:

• Build app.py entrypoint.
• Build Gradio Blocks UI.
• Support image upload and optional text description.
• Add personality mode selection.
• Add six stable example objects.
• Produce deterministic mock object JSON.
• Produce deterministic mock persona JSON.
• Produce English-first diary with Chinese helper translation.
• Support chat replies using the generated persona.
• Render a share card preview.
• Save anonymized trace JSON.

Exit criteria:

• python app.py starts a Gradio app.
• User can complete Upload -> Generate -> Diary -> Share Card -> Trace.
• Trace JSON is saved locally.
• No commercial model APIs are used.

Verification:

• Import smoke test for app.
• Direct function smoke test for generation flow.
• unittest smoke tests for mock flow, chat, share card, trace save, and anonymization.
• Sample trace generation script writes six stable trace files.
• Dataset preview script writes deterministic mock SFT preview JSONL.
• Trace export script writes validated public trace JSONL.
• scripts/check_initial_stage.py validates required initial-stage artifacts.
• Manual Gradio preview.

Phase 2 — UI Polish And Example Gallery

Goal: make the app feel like an object archive instead of a default Gradio demo.

Scope:

• Refine src/ui/styles.css.
• Reference the design images under UI 参考/ for visual direction.
• Keep content, interaction flow, language hierarchy, and feature scope aligned with docs/.
• Keep six stable example objects visible in the UI.
• Add clearer empty states and error states.
• Improve mobile layout.
• Keep UI English-first and Chinese-second.

Exit criteria:

• 1366px desktop layout is usable.
• Mobile-width layout is usable.
• Example gallery can reproduce stable outputs.
• Share card is readable and screenshot-friendly.

Verification:

• Manual browser preview.
• Screenshot review at desktop and mobile widths.
• Example generation for at least six objects.

Phase 3 — Vision Understanding

Goal: replace mock object recognition with a real VLM path while preserving fallback behavior.

Scope:

• Add MiniCPM-V or lightweight VLM runner in src/models/vision_runner.py.
• Keep manual description fallback.
• Validate object understanding JSON with schemas.
• Add JSON repair or retry behavior.
• Cache stable examples for demo reliability.

Exit criteria:

• Uploaded object photos produce structured object JSON.
• Cups, keyboards, and shoes are recognized with useful visible features.
• Fallback path works when VLM fails.

Verification:

• Run local sample image checks.
• Confirm schema validation.
• Confirm fallback trace markers.

Phase 4 — Text Runtime With llama.cpp

Goal: make persona, diary, and chat generation use a small local text model runtime.

Scope:

• Add llama.cpp / llama-cpp-python runner.
• Add model path configuration.
• Preserve src/pipeline.py as the UI-independent generation boundary.
• Implement persona generation.
• Implement diary generation.
• Implement chat continuation.
• Keep deterministic mock fallback for demos.

Exit criteria:

• Text generation can run through llama.cpp or documented local fallback.
• README documents model size and runtime path.
• Trace records include runtime metadata.

Verification:

• Local runtime smoke test.
• JSON schema validation.
• Compare at least three object generations for persona consistency.

Phase 5 — Dataset And Fine-Tuning Preparation

Goal: prepare Well-Tuned badge evidence.

Scope:

• Use scripts/generate_dataset.py to validate the SFT schema locally.
• Generate 200-500 object-persona candidate samples after real model path is available.
• Manually curate at least 50 high-quality examples.
• Define SFT schema.
• Prepare dataset preview.
• Draft dataset privacy notes.

Exit criteria:

• Mock SFT preview exists and parses as JSONL.
• Training dataset is structured and inspectable.
• Public examples contain no private data.
• Dataset card draft exists.

Verification:

• Validate JSONL format.
• Spot-check curated samples.
• Confirm no obvious sensitive data.

Phase 6 — LoRA Fine-Tuning And Model Card

Goal: publish a small fine-tuned model or adapter that can be linked in submission materials.

Scope:

• Run LoRA training with Modal or local resources.
• Export adapter or merged model.
• Convert to GGUF if needed.
• Publish HF model repo.
• Complete docs/MODEL_CARD.md.

Exit criteria:

• Fine-tuned model repo exists.
• Model parameter count is documented.
• Runtime instructions are documented.

Verification:

• Run inference on sample prompts.
• Confirm HF model links.
• Confirm no private credit codes or tokens are present.

Phase 7 — Public Traces And Reproducibility

Goal: satisfy Sharing is Caring expectations.

Scope:

• Produce at least six public traces.
• Keep data/traces/samples/ in sync with the six example objects.
• Export public traces to JSONL for dataset-style sharing.
• Add prompt templates.
• Add dataset preview.
• Document failures and fallbacks.
• Ensure trace anonymization.

Exit criteria:

• Public trace files are readable JSON.
• Trace docs explain how outputs were produced.
• Example gallery aligns with public traces.

Verification:

• Validate trace JSON.
• Inspect anonymization.
• Confirm README links.

Phase 8 — Hugging Face Space Deployment

Goal: deploy the app in the required Gradio format.

Scope:

• Create Hugging Face Space.
• Add Space README YAML header.
• Confirm app_file: app.py.
• Configure model paths and fallback mode.
• Check runtime resource constraints.

Exit criteria:

• Space opens publicly or under the official hackathon organization.
• App can generate at least stable demo examples.
• README includes deployment and model notes.

Verification:

• Launch on HF Space.
• Run demo flow in hosted environment.
• Check logs for missing secrets or path errors.

Phase 9 — Field Notes And Demo Video

Goal: complete narrative submission assets.

Scope:

• Write Field Notes article.
• Record demo video under 2 minutes.
• Prepare social post.
• Add badge evidence to README.

Exit criteria:

• Field Notes URL exists.
• Demo video URL exists.
• Social post URL exists.
• Submission package has all required links.

Verification:

• Watch final video.
• Check all URLs.
• Confirm README and submission guide are aligned.

Phase 10 — Final Submission Audit

Goal: reduce avoidable submission risk.

Checklist:

• Space under official organization.
• Demo video ready.
• Social post ready.
• README complete.
• Model parameter count documented.
• No commercial cloud AI API.
• Fine-tuned model linked.
• Dataset linked.
• Traces linked.
• Field Notes linked.
• UI English-first and Chinese-second.
• Submit before June 15, 2026.

Risk Register

Risk	Impact	Mitigation
VLM deployment is slow	Blocks real image understanding	Keep manual description and example gallery fallback
llama.cpp setup is unstable	Blocks Llama Champion badge	Use text mock fallback for demo while isolating runtime work
Fine-tuning takes too long	Weakens Well-Tuned badge	Prepare small curated dataset and prompt-tuned fallback
HF Space resources are limited	Demo may be slow	Cache examples and support CPU fallback
Trace contains private data	Submission/privacy risk	Anonymize trace input and avoid raw private images

Working Rule

Do not start a later phase by breaking an earlier verified flow. The mock MVP should remain usable while real model paths are added behind clear fallbacks.