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:

```text
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:

```text
objectverse-diary
```

Suggested description:

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

If a new repository is ever needed after confirmation:

```bash
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:

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

SDK:

```text
gradio
```

Required Space README header:

```yaml
---
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:

```bash
.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:

```bash
.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:

```text
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:

```bash
.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.