docs/EXTERNAL_SETUP.md

External Setup

Purpose

This document lists the external actions needed after the local initial-stage build is ready.

These actions change external account state and should only be run after explicit confirmation.

GitHub Repository

Local origin is already configured:

https://github.com/qqyule/Objectverse-Diary.git

Use this section to confirm the remote target and branch before pushing. Do not create a second repository unless the target changes.

Originally suggested repository name:

objectverse-diary

Suggested description:

Small-model AI toy that turns everyday objects into secret diary characters.

If a new repository is ever needed after confirmation:

gh repo create objectverse-diary --public --description "Small-model AI toy that turns everyday objects into secret diary characters." --source . --remote origin

Do not push until the user confirms the remote target and branch.

Hugging Face Space

Created Space:

https://huggingface.co/spaces/build-small-hackathon/ObjectverseDiary

SDK:

gradio

Required Space README header:

---
title: Objectverse Diary
emoji: 🗝️
colorFrom: amber
colorTo: gray
sdk: gradio
python_version: '3.10'
app_file: app.py
pinned: false
---

Recommended runtime setup:

• stable public demo: keep OBJECTVERSE_VISION_BACKEND=mock and OBJECTVERSE_TEXT_BACKEND=mock
• optional MiniCPM-V validation: temporarily set OBJECTVERSE_VISION_BACKEND=minicpm-v
• optional MiniCPM-V validation: set VISION_MODEL_ID=openbmb/MiniCPM-V-2_6
• optional MiniCPM-V validation: keep OBJECTVERSE_TEXT_BACKEND=mock
• optional MiniCPM-V validation: use ZeroGPU zero-a10g first; paid L4 previously returned 402 Payment Required
• always roll back to mock-safe settings after validation unless the hosted VLM path passes reliably

Automated validation command after confirmation:

.venv/bin/python -B scripts/check_space_vlm.py \
  --configure-space \
  --hardware zero-a10g \
  --rollback-to-mock \
  --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 \
  --failure-notes-output docs/FAILURES.md \
  --timeout-seconds 1200

The validation command now calls the hidden /vision_runtime_probe endpoint before mug/keyboard/shoe generation. The probe output is written into the markdown/JSON report and must remain free of token markers, .env paths, and private local paths.

Optional rollback to mock-safe settings:

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

The validation script must not print Hugging Face tokens. It uses three temporary public Wikimedia Commons images and does not commit downloaded assets.

Optional GGUF Smoke Test

This is a local-only model evidence step. It should be run only after confirming optional dependency installation and GGUF download.

Recommended model:

repo: Qwen/Qwen2.5-1.5B-Instruct-GGUF
file: qwen2.5-1.5b-instruct-q4_k_m.gguf
local path: models/qwen2.5-1.5b-instruct-q4_k_m.gguf

Do not commit the downloaded GGUF. After the file is present and optional llama-cpp-python is installed:

.venv/bin/python -B scripts/check_llama_cpp_smoke.py \
  --model-path models/qwen2.5-1.5b-instruct-q4_k_m.gguf

Passing evidence requires llama-cpp text generation and no text-fallback-to-mock marker for generation or chat.

2026-06-06 validation attempt:

• --configure-space was run for l4x1.
• Hugging Face returned 402 Payment Required for paid hardware on the build-small-hackathon organization.
• Mock-safe rollback was run afterward.
• ZeroGPU compatibility was added and uploaded to the Space.
• --configure-space --hardware zero-a10g reached RUNNING, and /config was reachable, but the validation request did not return within the practical waiting window.
• spaces>=0.30 and a hidden /zero_gpu_probe endpoint were added.
• The ZeroGPU probe succeeded through the direct hf.space URL with CUDA available on an NVIDIA RTX PRO 6000 Blackwell MIG device.

2026-06-08 validation attempt:

• --configure-space --hardware zero-a10g --rollback-to-mock reached the app through the direct hf.space client path.
• Mug, keyboard, and shoe checks all returned schema-valid traces, but every trace included vision-fallback-to-mock.
• Evidence is saved in docs/SPACE_VLM_REPORT.md, docs/SPACE_VLM_REPORT.json, and data/traces/space-vlm/.
• The report records rollback to cpu-basic with OBJECTVERSE_VISION_BACKEND=mock and OBJECTVERSE_TEXT_BACKEND=mock.
• Next model unblock step: inspect Space runtime logs or add non-secret MiniCPM-V diagnostics before rerunning validation.

Safety Notes

• Do not commit .env.
• Do not expose tokens, credit codes, private paths, or model credentials.
• Do not push large model files.
• Keep real model files under ignored /models/ unless explicitly publishing them.