docs/DEVELOPMENT_STATUS.md

# Development Status

Last updated: 2026-06-09

## Completed

- Project skeleton, README, AGENTS instructions, and Gradio app entrypoint.
- Mock MVP flow: upload/description, personality mode, object JSON, persona JSON, diary, object chat, share card, and trace saving.
- Archive-style Gradio UI with English-first / Chinese-second copy and six stable examples.
- Stable demo baseline:
  - example buttons replay committed sample traces before falling back to live generation
  - cached and live generation share the same UI output formatter
  - manual upload/description path still saves new runtime traces
- Trace and dataset tooling:
  - six public mock sample traces
  - public trace JSONL export
  - deterministic SFT preview JSONL
  - initial-stage acceptance script
- Hugging Face Space created: https://huggingface.co/spaces/build-small-hackathon/ObjectverseDiary
- MiniCPM-V 2.6 optional vision backend wiring with mock fallback.
- Optional llama.cpp / llama-cpp-python text runtime wiring through `TEXT_MODEL_PATH`, with mock fallback.
- Space VLM validation tooling:
  - `scripts/check_space_vlm.py`
  - hidden `/vision_runtime_probe` API for non-secret MiniCPM-V diagnostics
  - probe output support in Space VLM markdown and JSON reports
  - failure-note updater for the latest Space VLM failure summary
  - failed L4 validation report at `docs/SPACE_VLM_REPORT.md`
  - optional `--trace-output-dir` evidence export for validation traces
- Hosted MiniCPM-V 2.6 ZeroGPU validation passed on 2026-06-08 for public mug, keyboard, and shoe images after adding an `HF_TOKEN` Space secret for gated model access.
- Public Space live vision target:
  - hardware: `zero-a10g`
  - `OBJECTVERSE_VISION_BACKEND=minicpm-v`
  - `VISION_MODEL_ID=openbmb/MiniCPM-V-2_6`
  - `OBJECTVERSE_TEXT_BACKEND=mock`
  - text generation intentionally remains mock for this release
- Real VLM trace evidence from the hosted validation is available under `data/traces/space-vlm/`; text generation remained mock by design.
- ZeroGPU compatibility:
  - optional `src/utils/zero_gpu.py`
  - Gradio generation callback wrapped with `@zero_gpu(duration=180)`
  - hidden `/zero_gpu_probe` API confirms ZeroGPU CUDA availability when run through direct `hf.space` URL
- Stable submission materials:
  - Field Notes draft
  - demo video script
  - social post draft
  - stable submission guide
- Well-Tuned evidence:
  - 200-row synthetic curated v2 SFT dataset published at https://huggingface.co/datasets/qqyule/objectverse-diary-sft-curated
  - Modal Qwen 1.5B LoRA v2 run completed with 120 steps, 180 train rows, and 20 eval rows
  - LoRA v2 adapter published at https://huggingface.co/qqyule/objectverse-diary-qwen15b-lora
- LoRA v2 GGUF runtime evidence:
  - `scripts/check_llama_cpp_smoke.py`
  - adapter merged into `Qwen/Qwen2.5-1.5B-Instruct`
  - pinned `llama.cpp` commit: `8f83d6c271d194bde2d410145a0ce73bc42e85cd`
  - published Q4_K_M GGUF: https://huggingface.co/qqyule/objectverse-diary-qwen15b-lora/blob/main/objectverse-diary-qwen15b-lora-v2-q4_k_m.gguf
  - local smoke passed with `llama-cpp text generation`, schema-valid persona/diary, non-empty chat, and no `text-fallback-to-mock`
  - trace runtime no longer records literal `TEXT_MODEL_PATH`
- Local tests and initial acceptance currently pass.

## Not Completed

- Hosted Space text runtime validation with the published GGUF. The public Space still uses mock text until this passes.
- Real text model traces from the hosted non-mock text runtime.
- Published Field Notes URL, recorded demo video URL, social post URL, and final public submission.

## Current Runtime Defaults

Local development:

- `OBJECTVERSE_VISION_BACKEND=mock`
- `OBJECTVERSE_TEXT_BACKEND=mock`

Live Space:

- `OBJECTVERSE_VISION_BACKEND=minicpm-v`
- `VISION_MODEL_ID=openbmb/MiniCPM-V-2_6`
- `OBJECTVERSE_TEXT_BACKEND=mock`
- hardware: `zero-a10g`

- No commercial model API is used.
- GGUF files, tokens, credentials, and private images should not be committed.

## Next Recommended Gate

For live vision, keep the Space on ZeroGPU with MiniCPM-V and rerun hosted validation after dependency, Space variable, or deploy changes.

Next text model gate:

Download or mount the published GGUF on the target runtime, set:

```bash
OBJECTVERSE_TEXT_BACKEND=llama-cpp
TEXT_MODEL_PATH=/absolute/path/to/objectverse-diary-qwen15b-lora-v2-q4_k_m.gguf
```

Then rerun the local or Space smoke path before claiming live text runtime.

Live VLM validation gate:

```bash
.venv/bin/python -B scripts/check_space_vlm.py \
  --configure-space \
  --hardware zero-a10g \
  --space-url https://huggingface.co/spaces/build-small-hackathon/ObjectverseDiary \
  --output docs/SPACE_VLM_REPORT.md \
  --json-output docs/SPACE_VLM_REPORT.json \
  --trace-output-dir data/traces/space-vlm \
  --timeout-seconds 1200
```

If rollback is needed, use:

```bash
.venv/bin/python -B scripts/check_space_vlm.py \
  --space-url https://huggingface.co/spaces/build-small-hackathon/ObjectverseDiary \
  --configure-space \
  --hardware zero-a10g \
  --skip-validation \
  --rollback-to-mock
```