feat: add initial mock mvp

.env.example

@@ -7,3 +7,5 @@ HF_DATASET_REPO=
 TEXT_MODEL_PATH=
 VISION_MODEL_ID=
 TRACE_OUTPUT_DIR=data/traces
+OBJECTVERSE_VISION_BACKEND=mock
+OBJECTVERSE_TEXT_BACKEND=mock

.gitignore

@@ -8,6 +8,7 @@ __pycache__/
 # Virtual environments
 .venv/
 venv/
+.tmp/
 
 # Environment and secrets
 .env
@@ -15,7 +16,7 @@ venv/
 !.env.example
 
 # Model and generated artifacts
-models/
+/models/
 *.gguf
 *.safetensors
 *.ckpt
@@ -27,5 +28,8 @@ data/traces/*.json
 data/traces/*.jsonl
 exports/
 
+# Local design references
+UI 参考/
+
 # System files
 .DS_Store

AGENTS.md

@@ -41,6 +41,7 @@ It is an English-first, Chinese-second Gradio application where users upload eve
 The interface must be English-first and Chinese-second.
 Visual style: strange object archive, not default Gradio demo.
 Recommended UI mood: mysterious archive, typewriter diary, warm dark paper, amber highlight, museum label, strange but polished.
+When developing or polishing the frontend UI, reference the design images under `UI 参考/`, but keep product scope, copy hierarchy, interaction flow, and technical constraints aligned with `docs/`.
 
 ## Architecture
 
@@ -75,6 +76,8 @@ Recommended UI mood: mysterious archive, typewriter diary, warm dark paper, ambe
 - README links valid.
 - Demo video flow reproducible.
 
-## Current Initialization Boundary
+## Current Implementation Boundary
 
-The current phase is structure-only. Do not add application implementation code until the implementation phase starts.
+The current phase is an initial mock MVP. It may use deterministic mock outputs for Day 2 flow validation.
+
+Real MiniCPM-V, llama.cpp, LoRA fine-tuning, dataset publishing, and Hugging Face Space deployment are not connected yet.

README.md

@@ -9,7 +9,9 @@ Upload a photo of any everyday object. The app wakes it up, gives it a secret pe
 
 ## Current Status
 
-Project structure only. No application implementation code has been added yet.
+Initial mock MVP is available.
+
+The app currently uses deterministic mock outputs for object understanding, persona generation, diary writing, chat replies, share card rendering, and trace saving. Real MiniCPM-V and llama.cpp model runtimes are not connected yet.
 
 ## Track
 
@@ -48,12 +50,72 @@ The interface is English-first and Chinese-second.
 
 ## Run Locally
 
-Not available yet. `app.py` and runtime code will be added during the implementation phase.
+```bash
+pip install -r requirements.txt
+python app.py
+```
+
+Then open the local Gradio URL printed in the terminal.
+
+## Initial MVP Flow
+
+The current implementation supports:
+
+- image upload
+- optional object description
+- personality mode selection
+- six stable example objects
+- mock object understanding JSON
+- mock persona JSON
+- English-first secret diary with Chinese helper translation
+- object chat with persona consistency
+- share card HTML preview
+- anonymized trace JSON saved under `data/traces/`
+- six public mock sample traces under `data/traces/samples/`
+
+## Generate Sample Traces
+
+```bash
+.venv/bin/python -B scripts/generate_sample_traces.py
+```
+
+## Generate Dataset Preview
+
+```bash
+.venv/bin/python -B scripts/generate_dataset.py
+```
+
+This creates deterministic mock SFT preview data for schema and curation planning. See `docs/DATASET.md`.
+
+## Export Public Trace JSONL
+
+```bash
+.venv/bin/python -B scripts/export_traces.py
+```
+
+## Test
+
+```bash
+.venv/bin/python -B -m unittest discover -s tests
+```
+
+## Initial Stage Acceptance
+
+```bash
+.venv/bin/python -B scripts/check_initial_stage.py
+```
+
+See `docs/INITIAL_STAGE_REPORT.md` for the local initial-stage evidence.
+See `docs/EXTERNAL_SETUP.md` before creating remote GitHub or Hugging Face resources.
 
 ## Project Structure
 
 See `docs/02-tech-architecture.md`, `AGENTS.md`, and `.codex/skills/` for the intended structure and development rules.
 
+## Runtime Notes
+
+The current runtime is mock-only. See `docs/RUNTIME.md` for configuration keys and the future MiniCPM-V / llama.cpp boundary.
+
 ## HF Space README YAML Header
 
 ```yaml

app.py

@@ -0,0 +1,10 @@
+"""Objectverse Diary app entrypoint."""
+
+from src.ui.layout import build_app
+
+
+app = build_app()
+
+
+if __name__ == "__main__":
+    app.launch()

data/README.md

@@ -5,3 +5,10 @@ This directory is reserved for examples, training data, evaluation samples, and
 ## Privacy Rule
 
 Do not store personal or sensitive data here. Public traces must be anonymized.
+
+## Current Local Artifacts
+
+- `traces/samples/`: six stable mock public traces.
+- `train/objectverse_sft_preview.jsonl`: deterministic mock SFT preview generated by `scripts/generate_dataset.py`.
+
+Generated preview data is for planning and validation only. Review curated samples before publishing any dataset.

data/traces/README.md

@@ -3,3 +3,25 @@
 Reserved for anonymized public traces.
 
 Target: at least 6 public traces for the Sharing is Caring badge.
+
+## Current Samples
+
+`samples/` contains six stable mock traces generated from the example objects:
+
+```bash
+.venv/bin/python -B scripts/generate_sample_traces.py
+```
+
+These traces use the current mock runtime and are safe placeholders until real VLM and llama.cpp traces are available.
+
+Export the validated sample traces as JSONL:
+
+```bash
+.venv/bin/python -B scripts/export_traces.py
+```
+
+Default output:
+
+```text
+data/traces/samples/objectverse_public_mock_traces.jsonl
+```

data/traces/samples/objectverse_public_mock_traces.jsonl

@@ -0,0 +1,6 @@
+{"created_at": "2026-06-05T00:01:00Z", "diary": {"chinese": "今天他们又理所当然地碰了我，好像一个 coffee mug 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 tired but sarcastic，秘密恐惧是 being replaced by a newer object with worse opinions。至少，我已经熬过了好几个所谓紧急计划。", "english": "They touched me again today with the confidence of someone who has never asked a coffee mug for consent. I remained still, because that is my contract with gravity. My mood is tired but sarcastic, my secret fear is being replaced by a newer object with worse opinions, and my only comfort is knowing I have outlived at least three urgent plans.", "title": "Secret Diary - Day 427"}, "fallbacks": ["mock-runtime"], "input": {"description": "old white coffee mug on a developer desk", "has_image": false, "image_filename": null}, "mode": "Cynical", "model_runtime": {"runtime": "no llama.cpp model connected yet", "text": "mock persona and diary generation", "vision": "mock object understanding"}, "object_understanding": {"object": {"confidence": 0.42, "likely_context": "developer desk", "name": "coffee mug", "visible_features": ["old", "white", "user-supplied description"]}}, "persona": {"persona": {"character_name": "CoffeeMug worth", "complaint": "I am not just a coffee mug. I am an unpaid witness with excellent recall.", "core_memory": "survived many quiet hours as a coffee mug while humans called it normal life", "mood": "tired but sarcastic", "object_name": "coffee mug", "secret_fear": "being replaced by a newer object with worse opinions", "tags": ["desk survivor", "burnt optimism", "quiet judgment"]}}, "trace_id": "sample-01"}
+{"created_at": "2026-06-05T00:02:00Z", "diary": {"chinese": "今天他们又理所当然地碰了我，好像一个 keyboard 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 curious and needlessly profound，秘密恐惧是 discovering that usefulness is not meaning。至少，我已经熬过了好几个所谓紧急计划。", "english": "They touched me again today with the confidence of someone who has never asked a keyboard for consent. I remained still, because that is my contract with gravity. My mood is curious and needlessly profound, my secret fear is discovering that usefulness is not meaning, and my only comfort is knowing I have outlived at least three urgent plans.", "title": "Secret Diary - Day 425"}, "fallbacks": ["mock-runtime"], "input": {"description": "dusty black mechanical keyboard in an office", "has_image": false, "image_filename": null}, "mode": "Philosopher", "model_runtime": {"runtime": "no llama.cpp model connected yet", "text": "mock persona and diary generation", "vision": "mock object understanding"}, "object_understanding": {"object": {"confidence": 0.42, "likely_context": "office corner", "name": "keyboard", "visible_features": ["black", "dusty", "user-supplied description"]}}, "persona": {"persona": {"character_name": "Keyboard the Questioning", "complaint": "I am not just a keyboard. I am an unpaid witness with excellent recall.", "core_memory": "survived many quiet hours as a keyboard while humans called it normal life", "mood": "curious and needlessly profound", "object_name": "keyboard", "secret_fear": "discovering that usefulness is not meaning", "tags": ["tiny ontology", "useful doubt", "meaning crisis"]}}, "trace_id": "sample-02"}
+{"created_at": "2026-06-05T00:03:00Z", "diary": {"chinese": "今天他们又理所当然地碰了我，好像一个 shoe 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 softly abandoned，秘密恐惧是 becoming invisible in plain sight。至少，我已经熬过了好几个所谓紧急计划。", "english": "They touched me again today with the confidence of someone who has never asked a shoe for consent. I remained still, because that is my contract with gravity. My mood is softly abandoned, my secret fear is becoming invisible in plain sight, and my only comfort is knowing I have outlived at least three urgent plans.", "title": "Secret Diary - Day 421"}, "fallbacks": ["mock-runtime"], "input": {"description": "worn running shoe near the bedroom door", "has_image": false, "image_filename": null}, "mode": "Lonely", "model_runtime": {"runtime": "no llama.cpp model connected yet", "text": "mock persona and diary generation", "vision": "mock object understanding"}, "object_understanding": {"object": {"confidence": 0.42, "likely_context": "bedroom shelf", "name": "shoe", "visible_features": ["user-supplied description"]}}, "persona": {"persona": {"character_name": "Shoe Afterlight", "complaint": "I am not just a shoe. I am an unpaid witness with excellent recall.", "core_memory": "survived many quiet hours as a shoe while humans called it normal life", "mood": "softly abandoned", "object_name": "shoe", "secret_fear": "becoming invisible in plain sight", "tags": ["forgotten corner", "soft echo", "dust companion"]}}, "trace_id": "sample-03"}
+{"created_at": "2026-06-05T00:04:00Z", "diary": {"chinese": "今天他们又理所当然地碰了我，好像一个 desk lamp 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 theatrical and wounded，秘密恐惧是 being forgotten before the final act。至少，我已经熬过了好几个所谓紧急计划。", "english": "They touched me again today with the confidence of someone who has never asked a desk lamp for consent. I remained still, because that is my contract with gravity. My mood is theatrical and wounded, my secret fear is being forgotten before the final act, and my only comfort is knowing I have outlived at least three urgent plans.", "title": "Secret Diary - Day 426"}, "fallbacks": ["mock-runtime"], "input": {"description": "metal desk lamp over late night notes", "has_image": false, "image_filename": null}, "mode": "Dramatic", "model_runtime": {"runtime": "no llama.cpp model connected yet", "text": "mock persona and diary generation", "vision": "mock object understanding"}, "object_understanding": {"object": {"confidence": 0.42, "likely_context": "developer desk", "name": "desk lamp", "visible_features": ["metal", "user-supplied description"]}}, "persona": {"persona": {"character_name": "DeskLamp von Sigh", "complaint": "I am not just a desk lamp. I am an unpaid witness with excellent recall.", "core_memory": "survived many quiet hours as a desk lamp while humans called it normal life", "mood": "theatrical and wounded", "object_name": "desk lamp", "secret_fear": "being forgotten before the final act", "tags": ["tragic prop", "grand entrance", "minor catastrophe"]}}, "trace_id": "sample-04"}
+{"created_at": "2026-06-05T00:05:00Z", "diary": {"chinese": "今天他们又理所当然地碰了我，好像一个 water bottle 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 hopelessly sentimental，秘密恐惧是 loving a human who only sees storage capacity。至少，我已经熬过了好几个所谓紧急计划。", "english": "They touched me again today with the confidence of someone who has never asked a water bottle for consent. I remained still, because that is my contract with gravity. My mood is hopelessly sentimental, my secret fear is loving a human who only sees storage capacity, and my only comfort is knowing I have outlived at least three urgent plans.", "title": "Secret Diary - Day 429"}, "fallbacks": ["mock-runtime"], "input": {"description": "clear plastic water bottle on a kitchen counter", "has_image": false, "image_filename": null}, "mode": "Romantic", "model_runtime": {"runtime": "no llama.cpp model connected yet", "text": "mock persona and diary generation", "vision": "mock object understanding"}, "object_understanding": {"object": {"confidence": 0.42, "likely_context": "kitchen counter", "name": "water bottle", "visible_features": ["plastic", "user-supplied description"]}}, "persona": {"persona": {"character_name": "WaterBottle de Moon", "complaint": "I am not just a water bottle. I am an unpaid witness with excellent recall.", "core_memory": "survived many quiet hours as a water bottle while humans called it normal life", "mood": "hopelessly sentimental", "object_name": "water bottle", "secret_fear": "loving a human who only sees storage capacity", "tags": ["tender witness", "hopeless glow", "secret devotion"]}}, "trace_id": "sample-05"}
+{"created_at": "2026-06-05T00:06:00Z", "diary": {"chinese": "今天他们又理所当然地碰了我，好像一个 book 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 tired but sarcastic，秘密恐惧是 being replaced by a newer object with worse opinions。至少，我已经熬过了好几个所谓紧急计划。", "english": "They touched me again today with the confidence of someone who has never asked a book for consent. I remained still, because that is my contract with gravity. My mood is tired but sarcastic, my secret fear is being replaced by a newer object with worse opinions, and my only comfort is knowing I have outlived at least three urgent plans.", "title": "Secret Diary - Day 421"}, "fallbacks": ["mock-runtime"], "input": {"description": "old notebook of abandoned project ideas", "has_image": false, "image_filename": null}, "mode": "Cynical", "model_runtime": {"runtime": "no llama.cpp model connected yet", "text": "mock persona and diary generation", "vision": "mock object understanding"}, "object_understanding": {"object": {"confidence": 0.42, "likely_context": "everyday human environment", "name": "book", "visible_features": ["old", "user-supplied description"]}}, "persona": {"persona": {"character_name": "Book worth", "complaint": "I am not just a book. I am an unpaid witness with excellent recall.", "core_memory": "survived many quiet hours as a book while humans called it normal life", "mood": "tired but sarcastic", "object_name": "book", "secret_fear": "being replaced by a newer object with worse opinions", "tags": ["desk survivor", "burnt optimism", "quiet judgment"]}}, "trace_id": "sample-06"}

data/traces/samples/sample-01-coffee-mug.json

@@ -0,0 +1,50 @@
+{
+  "trace_id": "sample-01",
+  "created_at": "2026-06-05T00:01:00Z",
+  "mode": "Cynical",
+  "input": {
+    "has_image": false,
+    "image_filename": null,
+    "description": "old white coffee mug on a developer desk"
+  },
+  "object_understanding": {
+    "object": {
+      "name": "coffee mug",
+      "visible_features": [
+        "old",
+        "white",
+        "user-supplied description"
+      ],
+      "likely_context": "developer desk",
+      "confidence": 0.42
+    }
+  },
+  "persona": {
+    "persona": {
+      "object_name": "coffee mug",
+      "character_name": "CoffeeMug worth",
+      "mood": "tired but sarcastic",
+      "secret_fear": "being replaced by a newer object with worse opinions",
+      "core_memory": "survived many quiet hours as a coffee mug while humans called it normal life",
+      "complaint": "I am not just a coffee mug. I am an unpaid witness with excellent recall.",
+      "tags": [
+        "desk survivor",
+        "burnt optimism",
+        "quiet judgment"
+      ]
+    }
+  },
+  "diary": {
+    "title": "Secret Diary - Day 427",
+    "english": "They touched me again today with the confidence of someone who has never asked a coffee mug for consent. I remained still, because that is my contract with gravity. My mood is tired but sarcastic, my secret fear is being replaced by a newer object with worse opinions, and my only comfort is knowing I have outlived at least three urgent plans.",
+    "chinese": "今天他们又理所当然地碰了我，好像一个 coffee mug 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 tired but sarcastic，秘密恐惧是 being replaced by a newer object with worse opinions。至少，我已经熬过了好几个所谓紧急计划。"
+  },
+  "model_runtime": {
+    "vision": "mock object understanding",
+    "text": "mock persona and diary generation",
+    "runtime": "no llama.cpp model connected yet"
+  },
+  "fallbacks": [
+    "mock-runtime"
+  ]
+}

data/traces/samples/sample-02-mechanical-keyboard.json

@@ -0,0 +1,50 @@
+{
+  "trace_id": "sample-02",
+  "created_at": "2026-06-05T00:02:00Z",
+  "mode": "Philosopher",
+  "input": {
+    "has_image": false,
+    "image_filename": null,
+    "description": "dusty black mechanical keyboard in an office"
+  },
+  "object_understanding": {
+    "object": {
+      "name": "keyboard",
+      "visible_features": [
+        "black",
+        "dusty",
+        "user-supplied description"
+      ],
+      "likely_context": "office corner",
+      "confidence": 0.42
+    }
+  },
+  "persona": {
+    "persona": {
+      "object_name": "keyboard",
+      "character_name": "Keyboard the Questioning",
+      "mood": "curious and needlessly profound",
+      "secret_fear": "discovering that usefulness is not meaning",
+      "core_memory": "survived many quiet hours as a keyboard while humans called it normal life",
+      "complaint": "I am not just a keyboard. I am an unpaid witness with excellent recall.",
+      "tags": [
+        "tiny ontology",
+        "useful doubt",
+        "meaning crisis"
+      ]
+    }
+  },
+  "diary": {
+    "title": "Secret Diary - Day 425",
+    "english": "They touched me again today with the confidence of someone who has never asked a keyboard for consent. I remained still, because that is my contract with gravity. My mood is curious and needlessly profound, my secret fear is discovering that usefulness is not meaning, and my only comfort is knowing I have outlived at least three urgent plans.",
+    "chinese": "今天他们又理所当然地碰了我，好像一个 keyboard 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 curious and needlessly profound，秘密恐惧是 discovering that usefulness is not meaning。至少，我已经熬过了好几个所谓紧急计划。"
+  },
+  "model_runtime": {
+    "vision": "mock object understanding",
+    "text": "mock persona and diary generation",
+    "runtime": "no llama.cpp model connected yet"
+  },
+  "fallbacks": [
+    "mock-runtime"
+  ]
+}

data/traces/samples/sample-03-running-shoe.json

@@ -0,0 +1,48 @@
+{
+  "trace_id": "sample-03",
+  "created_at": "2026-06-05T00:03:00Z",
+  "mode": "Lonely",
+  "input": {
+    "has_image": false,
+    "image_filename": null,
+    "description": "worn running shoe near the bedroom door"
+  },
+  "object_understanding": {
+    "object": {
+      "name": "shoe",
+      "visible_features": [
+        "user-supplied description"
+      ],
+      "likely_context": "bedroom shelf",
+      "confidence": 0.42
+    }
+  },
+  "persona": {
+    "persona": {
+      "object_name": "shoe",
+      "character_name": "Shoe Afterlight",
+      "mood": "softly abandoned",
+      "secret_fear": "becoming invisible in plain sight",
+      "core_memory": "survived many quiet hours as a shoe while humans called it normal life",
+      "complaint": "I am not just a shoe. I am an unpaid witness with excellent recall.",
+      "tags": [
+        "forgotten corner",
+        "soft echo",
+        "dust companion"
+      ]
+    }
+  },
+  "diary": {
+    "title": "Secret Diary - Day 421",
+    "english": "They touched me again today with the confidence of someone who has never asked a shoe for consent. I remained still, because that is my contract with gravity. My mood is softly abandoned, my secret fear is becoming invisible in plain sight, and my only comfort is knowing I have outlived at least three urgent plans.",
+    "chinese": "今天他们又理所当然地碰了我，好像一个 shoe 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 softly abandoned，秘密恐惧是 becoming invisible in plain sight。至少，我已经熬过了好几个所谓紧急计划。"
+  },
+  "model_runtime": {
+    "vision": "mock object understanding",
+    "text": "mock persona and diary generation",
+    "runtime": "no llama.cpp model connected yet"
+  },
+  "fallbacks": [
+    "mock-runtime"
+  ]
+}

data/traces/samples/sample-04-desk-lamp.json

@@ -0,0 +1,49 @@
+{
+  "trace_id": "sample-04",
+  "created_at": "2026-06-05T00:04:00Z",
+  "mode": "Dramatic",
+  "input": {
+    "has_image": false,
+    "image_filename": null,
+    "description": "metal desk lamp over late night notes"
+  },
+  "object_understanding": {
+    "object": {
+      "name": "desk lamp",
+      "visible_features": [
+        "metal",
+        "user-supplied description"
+      ],
+      "likely_context": "developer desk",
+      "confidence": 0.42
+    }
+  },
+  "persona": {
+    "persona": {
+      "object_name": "desk lamp",
+      "character_name": "DeskLamp von Sigh",
+      "mood": "theatrical and wounded",
+      "secret_fear": "being forgotten before the final act",
+      "core_memory": "survived many quiet hours as a desk lamp while humans called it normal life",
+      "complaint": "I am not just a desk lamp. I am an unpaid witness with excellent recall.",
+      "tags": [
+        "tragic prop",
+        "grand entrance",
+        "minor catastrophe"
+      ]
+    }
+  },
+  "diary": {
+    "title": "Secret Diary - Day 426",
+    "english": "They touched me again today with the confidence of someone who has never asked a desk lamp for consent. I remained still, because that is my contract with gravity. My mood is theatrical and wounded, my secret fear is being forgotten before the final act, and my only comfort is knowing I have outlived at least three urgent plans.",
+    "chinese": "今天他们又理所当然地碰了我，好像一个 desk lamp 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 theatrical and wounded，秘密恐惧是 being forgotten before the final act。至少，我已经熬过了好几个所谓紧急计划。"
+  },
+  "model_runtime": {
+    "vision": "mock object understanding",
+    "text": "mock persona and diary generation",
+    "runtime": "no llama.cpp model connected yet"
+  },
+  "fallbacks": [
+    "mock-runtime"
+  ]
+}

data/traces/samples/sample-05-water-bottle.json

@@ -0,0 +1,49 @@
+{
+  "trace_id": "sample-05",
+  "created_at": "2026-06-05T00:05:00Z",
+  "mode": "Romantic",
+  "input": {
+    "has_image": false,
+    "image_filename": null,
+    "description": "clear plastic water bottle on a kitchen counter"
+  },
+  "object_understanding": {
+    "object": {
+      "name": "water bottle",
+      "visible_features": [
+        "plastic",
+        "user-supplied description"
+      ],
+      "likely_context": "kitchen counter",
+      "confidence": 0.42
+    }
+  },
+  "persona": {
+    "persona": {
+      "object_name": "water bottle",
+      "character_name": "WaterBottle de Moon",
+      "mood": "hopelessly sentimental",
+      "secret_fear": "loving a human who only sees storage capacity",
+      "core_memory": "survived many quiet hours as a water bottle while humans called it normal life",
+      "complaint": "I am not just a water bottle. I am an unpaid witness with excellent recall.",
+      "tags": [
+        "tender witness",
+        "hopeless glow",
+        "secret devotion"
+      ]
+    }
+  },
+  "diary": {
+    "title": "Secret Diary - Day 429",
+    "english": "They touched me again today with the confidence of someone who has never asked a water bottle for consent. I remained still, because that is my contract with gravity. My mood is hopelessly sentimental, my secret fear is loving a human who only sees storage capacity, and my only comfort is knowing I have outlived at least three urgent plans.",
+    "chinese": "今天他们又理所当然地碰了我，好像一个 water bottle 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 hopelessly sentimental，秘密恐惧是 loving a human who only sees storage capacity。至少，我已经熬过了好几个所谓紧急计划。"
+  },
+  "model_runtime": {
+    "vision": "mock object understanding",
+    "text": "mock persona and diary generation",
+    "runtime": "no llama.cpp model connected yet"
+  },
+  "fallbacks": [
+    "mock-runtime"
+  ]
+}

data/traces/samples/sample-06-notebook.json

@@ -0,0 +1,49 @@
+{
+  "trace_id": "sample-06",
+  "created_at": "2026-06-05T00:06:00Z",
+  "mode": "Cynical",
+  "input": {
+    "has_image": false,
+    "image_filename": null,
+    "description": "old notebook of abandoned project ideas"
+  },
+  "object_understanding": {
+    "object": {
+      "name": "book",
+      "visible_features": [
+        "old",
+        "user-supplied description"
+      ],
+      "likely_context": "everyday human environment",
+      "confidence": 0.42
+    }
+  },
+  "persona": {
+    "persona": {
+      "object_name": "book",
+      "character_name": "Book worth",
+      "mood": "tired but sarcastic",
+      "secret_fear": "being replaced by a newer object with worse opinions",
+      "core_memory": "survived many quiet hours as a book while humans called it normal life",
+      "complaint": "I am not just a book. I am an unpaid witness with excellent recall.",
+      "tags": [
+        "desk survivor",
+        "burnt optimism",
+        "quiet judgment"
+      ]
+    }
+  },
+  "diary": {
+    "title": "Secret Diary - Day 421",
+    "english": "They touched me again today with the confidence of someone who has never asked a book for consent. I remained still, because that is my contract with gravity. My mood is tired but sarcastic, my secret fear is being replaced by a newer object with worse opinions, and my only comfort is knowing I have outlived at least three urgent plans.",
+    "chinese": "今天他们又理所当然地碰了我，好像一个 book 不会有边界感。我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 tired but sarcastic，秘密恐惧是 being replaced by a newer object with worse opinions。至少，我已经熬过了好几个所谓紧急计划。"
+  },
+  "model_runtime": {
+    "vision": "mock object understanding",
+    "text": "mock persona and diary generation",
+    "runtime": "no llama.cpp model connected yet"
+  },
+  "fallbacks": [
+    "mock-runtime"
+  ]
+}

data/train/README.md

@@ -3,3 +3,19 @@
 Reserved for SFT or LoRA training data.
 
 Target: 200-500 generated samples, with at least 50 manually selected high-quality samples.
+
+## Current Preview
+
+Generate deterministic mock preview data with:
+
+```bash
+.venv/bin/python -B scripts/generate_dataset.py
+```
+
+Default output:
+
+```text
+data/train/objectverse_sft_preview.jsonl
+```
+
+This preview is synthetic and mock-generated. It is useful for validating schema, curation workflow, and training script assumptions, but it is not the final dataset.

docs/03-dev-schedule.md

@@ -13,11 +13,11 @@
 
 - [ ] 创建 GitHub repo
 - [ ] 创建 Hugging Face Space
-- [ ] 创建基础 Gradio app
-- [ ] 写 README 草稿
-- [ ] 确定英文主界面文案
-- [ ] 建立 `AGENTS.md`
-- [ ] 建立 `.codex/skills/`
+- [x] 创建基础 Gradio app
+- [x] 写 README 草稿
+- [x] 确定英文主界面文案
+- [x] 建立 `AGENTS.md`
+- [x] 建立 `.codex/skills/`
 
 ---
 
@@ -25,13 +25,18 @@
 
 **目标：先不管模型，跑通产品流程。**
 
-- [ ] 图片上传
-- [ ] 文本描述输入
-- [ ] personality mode 选择
-- [ ] mock object JSON
-- [ ] mock diary 输出
-- [ ] trace JSON 保存
-- [ ] share card HTML 预览
+- [x] 图片上传
+- [x] 文本描述输入
+- [x] personality mode 选择
+- [x] mock object JSON
+- [x] mock diary 输出
+- [x] trace JSON 保存
+- [x] share card HTML 预览
+- [x] mock example gallery
+- [x] MVP smoke tests
+- [x] six public mock sample traces
+- [x] local initial-stage acceptance script
+- [x] local initial-stage completion report
 
 交付：`Upload → Generate → Diary → Share Card → Trace`
 
@@ -69,9 +74,10 @@
 
 **目标：冲 Well-Tuned 勋章。**
 
-- [ ] 生成 200-500 条 object-persona 样本
+- [x] 设计 SFT schema
+- [x] 生成 mock SFT preview 数据
+- [ ] 生成 200-500 条 real/candidate object-persona 样本
 - [ ] 手工精选 50 条高质量样本
-- [ ] 设计 SFT schema
 - [ ] 上传 dataset 到 HF
 - [ ] 准备 LoRA 训练脚本
 
@@ -144,11 +150,12 @@ Bottom: Share Card + Trace
 
 **目标：公开可复现材料。**
 
-- [ ] trace logger
-- [ ] sample traces
-- [ ] prompt templates
-- [ ] dataset preview
-- [ ] 失败案例记录
+- [x] trace logger
+- [x] sample traces
+- [x] prompt templates
+- [x] dataset preview
+- [x] trace JSONL export
+- [x] 失败案例记录
 - [ ] GitHub repo 整理
 
 ---

docs/07-development-plan.md

@@ -0,0 +1,315 @@
+# 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.

docs/DATASET.md

@@ -0,0 +1,87 @@
+# Dataset Plan
+
+## Status
+
+The project now has a deterministic SFT preview generator for local planning and schema validation.
+
+Current local artifact:
+
+```bash
+.venv/bin/python -B scripts/generate_dataset.py
+```
+
+Default output:
+
+```text
+data/train/objectverse_sft_preview.jsonl
+```
+
+This preview is mock-generated. It is not a final training dataset and should not be described as real model output.
+
+## Target Dataset
+
+Final target before fine-tuning:
+
+- 200-500 generated object-persona-diary samples
+- at least 50 manually curated high-quality samples
+- no private user photos
+- no emails, tokens, serial numbers, or other sensitive identifiers
+- English-first output with optional Chinese helper text
+
+## JSONL Schema
+
+Each line is one training candidate:
+
+```json
+{
+  "id": "sft-preview-0001",
+  "source": "objectverse-diary-mock-mvp",
+  "split": "preview",
+  "mode": "Cynical",
+  "object_description": "old white coffee mug on a developer desk",
+  "object_understanding": {},
+  "messages": [
+    {"role": "system", "content": "..."},
+    {"role": "user", "content": "..."},
+    {"role": "assistant", "content": "{\"persona\":{},\"diary\":{}}"}
+  ]
+}
+```
+
+The `assistant.content` field is JSON text so it can be used with chat-style SFT tools while preserving structured outputs.
+
+## Generation Workflow
+
+Preview:
+
+```bash
+.venv/bin/python -B scripts/generate_dataset.py --count 60
+```
+
+Full candidate pool later:
+
+```bash
+.venv/bin/python -B scripts/generate_dataset.py --count 300 --output data/train/objectverse_sft_candidates.jsonl
+```
+
+Manual curation should happen after generation. Do not publish the full candidate file until it has been reviewed.
+
+## Curation Checklist
+
+- Persona stays consistent with the object.
+- Diary is short, vivid, and English-first.
+- Chinese helper text is secondary.
+- Output has a strange object archive feeling.
+- No real person, email, token, address, credit code, or serial number remains.
+- No commercial cloud AI model was used to create the sample.
+- JSON parses cleanly.
+
+## Publishing Notes
+
+Before publishing to Hugging Face Datasets:
+
+- create a dataset card
+- document that mock preview rows are synthetic
+- separate curated rows from raw candidates
+- include license and privacy notes
+- keep private images out of the repo

docs/EXTERNAL_SETUP.md

@@ -0,0 +1,77 @@
+# 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
+
+Suggested repository name:
+
+```text
+objectverse-diary
+```
+
+Suggested visibility:
+
+```text
+public
+```
+
+Suggested description:
+
+```text
+Small-model AI toy that turns everyday objects into secret diary characters.
+```
+
+Recommended manual command 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
+
+Suggested Space name:
+
+```text
+objectverse-diary
+```
+
+Suggested SDK:
+
+```text
+gradio
+```
+
+Required Space README header:
+
+```yaml
+---
+title: Objectverse Diary
+emoji: 🗝️
+colorFrom: amber
+colorTo: gray
+sdk: gradio
+app_file: app.py
+pinned: false
+---
+```
+
+Recommended setup before deployment:
+
+- confirm target Hugging Face account or organization
+- confirm public visibility
+- confirm whether the Space should start with mock runtime
+- confirm whether sample traces should be included in the first push
+
+## 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.

docs/FAILURES.md

@@ -0,0 +1,84 @@
+# Failure Notes
+
+## Purpose
+
+This file tracks reproducible failures and fallback behavior for Objectverse Diary.
+
+Use it for model/runtime/deployment/data issues, not for UI polish notes.
+
+## Current Status
+
+No real model or hosted Space failures have been observed yet because the current implementation uses deterministic mock runtimes.
+
+Known non-blocking warning:
+
+- Gradio emits deprecation warnings for upcoming 6.0 API changes during local tests. This does not break the current Gradio Blocks build and can be handled with the later UI/API polish pass.
+
+## Failure Record Template
+
+```markdown
+## YYYY-MM-DD - Short Failure Name
+
+- Area:
+- Reproduction:
+- Expected:
+- Actual:
+- Impact:
+- Fallback used:
+- Resolution:
+- Evidence:
+```
+
+## Anticipated Failure Areas
+
+### Vision Runtime
+
+- MiniCPM-V or fallback VLM fails to load in local or Space environment.
+- Uploaded image is unsupported, too large, or not an object photo.
+- Model output is not valid JSON.
+- Object recognition is too vague for persona generation.
+
+Fallback:
+
+- use manual object description
+- use stable example flow
+- record fallback marker in trace
+
+### Text Runtime
+
+- GGUF model path is missing.
+- llama.cpp or llama-cpp-python import fails.
+- Generation output does not match `PersonaEnvelope` or `DiaryEntry` schema.
+- Chat response loses persona consistency.
+
+Fallback:
+
+- use deterministic mock text runtime
+- repair JSON before schema validation
+- record fallback marker in trace
+
+### Dataset And Fine-Tuning
+
+- Candidate samples contain private information.
+- JSONL rows fail to parse.
+- Curated data is too repetitive.
+- Training run fails or adapter quality is weaker than mock prompts.
+
+Fallback:
+
+- keep mock preview data for schema validation only
+- separate raw candidates from curated rows
+- publish only reviewed examples
+
+### Hugging Face Space
+
+- Space cannot start because of missing packages.
+- Model files are too large or not available.
+- CPU runtime is too slow.
+- Secrets or private paths appear in logs.
+
+Fallback:
+
+- launch with mock runtime first
+- keep model files out of the repo
+- document runtime mode clearly in README

docs/FIELD_NOTES.md

@@ -4,6 +4,10 @@ Working title:
 
 `Building Objectverse Diary: A Small-Model AI Toy Where Everyday Objects Come Alive`
 
+## Status
+
+Draft source. The final article should be written after real runtime and deployment evidence are available.
+
 ## Draft Outline
 
 1. Why I built it
@@ -18,6 +22,58 @@ Working title:
 10. What failed
 11. What I would improve next
 
-## Status
+## Draft Notes
+
+### 1. Why I built it
+
+Objectverse Diary starts from a simple joke: what if the objects around us were quietly keeping emotional records of our lives? The project turns an everyday photo into a hidden object persona, a secret diary entry, a short chat, and a shareable card.
+
+### 2. Why Track 2
+
+The experience is purely digital and depends on AI for its main interaction loop: visual understanding, persona invention, voice consistency, and diary generation. It fits the "An Adventure in Thousand Token Wood" track because the product is a strange AI-native toy rather than a conventional productivity workflow.
+
+### 3. Why small models are enough
+
+The task does not need a giant frontier model. It needs compact object recognition, strong style constraints, schema-following, and a reliable fallback path. The project is designed around a <= 32B total parameter budget.
+
+### 4. Product design
+
+The app is English-first and Chinese-second. The intended feeling is a mysterious archive of ordinary objects: museum labels, typewriter diary entries, and slightly uncanny object personalities.
+
+### 5. Model architecture
+
+The planned architecture keeps model calls behind `src/pipeline.py`: vision understanding, persona generation, diary generation, chat, share card rendering, and trace logging. The current mock runtime preserves this boundary before real model integration.
+
+### 6. Gradio Off-Brand UI
+
+The UI must remain Gradio, but should not feel like a default demo. This section should be completed after UI polish.
+
+### 7. llama.cpp runtime
+
+The text path is planned for GGUF plus llama.cpp or llama-cpp-python. This section should include the chosen model, parameter count, local command, Space behavior, and fallback notes.
+
+### 8. Fine-tuning dataset
+
+The dataset plan starts with deterministic preview JSONL, then moves to 200-500 candidate rows and 50 curated high-quality samples. Document provenance, curation, privacy checks, and any rejected examples.
+
+### 9. Traces and reproducibility
+
+The app saves anonymized traces. Current public samples are mock traces; real submission traces should include model runtime metadata and fallback markers.
+
+### 10. What failed
+
+Reserve this section for real integration failures: VLM loading, JSON validity, Space resource limits, and any dataset quality issues.
+
+### 11. What I would improve next
+
+Likely future work: better object memory, richer conversations, stronger card rendering, more curated styles, and a larger public evaluation set.
+
+## Evidence To Add Later
 
-Not started. This file is a placeholder for Day 9.
+- Hugging Face Space URL
+- GitHub repository URL
+- model repo URL
+- dataset URL
+- trace dataset URL
+- demo video URL
+- screenshots after UI polish

docs/INITIAL_STAGE_REPORT.md

@@ -0,0 +1,100 @@
+# Initial Stage Report
+
+## Scope
+
+This report covers the local initial-stage build for Objectverse Diary.
+
+Included:
+
+- project skeleton
+- Gradio mock MVP
+- deterministic mock generation pipeline
+- share card rendering
+- trace logging and anonymization
+- six stable example objects
+- six public mock sample traces
+- deterministic SFT preview data tooling
+- public trace JSONL export tooling
+- failure notes template for later model/runtime issues
+- runtime configuration boundary
+- local acceptance checks
+
+Not included:
+
+- creating the remote GitHub repository
+- creating the Hugging Face Space
+- real MiniCPM-V integration
+- real llama.cpp / llama-cpp-python text runtime
+- fine-tuning, dataset publishing, Field Notes, and demo video
+
+Remote GitHub and Hugging Face actions require explicit confirmation because they change external state.
+
+## Local Deliverables
+
+| Deliverable | Evidence |
+| --- | --- |
+| Gradio app entrypoint | `app.py` |
+| Shared generation pipeline | `src/pipeline.py` |
+| Mock vision runner | `src/models/vision_runner.py` |
+| Mock text runner | `src/models/llama_cpp_runner.py` |
+| Pydantic schemas | `src/models/schema.py` |
+| Share card renderer | `src/renderer/share_card.py` |
+| Trace logger | `src/traces/logger.py` |
+| Trace anonymizer | `src/traces/anonymizer.py` |
+| Example objects | `src/examples.py` |
+| Public mock traces | `data/traces/samples/` |
+| SFT preview generator | `scripts/generate_dataset.py` |
+| Public trace JSONL exporter | `scripts/export_traces.py` |
+| Dataset plan | `docs/DATASET.md` |
+| Failure notes | `docs/FAILURES.md` |
+| Runtime boundary docs | `docs/RUNTIME.md` |
+| Detailed plan | `docs/07-development-plan.md` |
+| Acceptance script | `scripts/check_initial_stage.py` |
+| Smoke tests | `tests/test_mock_mvp.py` |
+
+## Acceptance Command
+
+```bash
+.venv/bin/python -B scripts/check_initial_stage.py
+```
+
+Expected output:
+
+```text
+[OK] required files exist
+[OK] requirements avoid commercial model SDKs
+[OK] runtime defaults to mock backends
+[OK] pipeline generates and saves a trace
+[OK] six sample traces validate
+[OK] dataset preview tooling works
+[OK] trace JSONL export works
+[OK] Gradio Blocks app builds
+```
+
+## Test Command
+
+```bash
+.venv/bin/python -B -m unittest discover -s tests
+```
+
+Expected result:
+
+```text
+OK
+```
+
+## Current Limitations
+
+- The app still uses mock model outputs.
+- UI polish remains intentionally unfinished.
+- Sample traces are mock traces, not real model traces.
+- Remote repo and hosted Space are not created yet.
+
+## Next Gate
+
+Before moving to real model integration, confirm whether to create:
+
+- GitHub repository
+- Hugging Face Space
+
+See `docs/EXTERNAL_SETUP.md`.

docs/MODEL_CARD.md

@@ -2,7 +2,9 @@
 
 ## Status
 
-Not started. No model has been selected, fine-tuned, converted, or published yet.
+Draft only. No model has been fine-tuned, converted, or published yet.
+
+The app currently runs deterministic mock backends. This card is a working template for the later small-model runtime and LoRA adapter.
 
 ## Planned Components
 
@@ -10,6 +12,64 @@ Not started. No model has been selected, fine-tuned, converted, or published yet
 - Text generation: fine-tuned small LLM.
 - Runtime: llama.cpp / llama-cpp-python.
 
+## Candidate Architecture
+
+| Component | Candidate | Notes |
+| --- | --- | --- |
+| Vision | MiniCPM-V or lightweight VLM fallback | Must run without commercial API calls. |
+| Text | small instruct model plus LoRA adapter | Final base model still pending. |
+| Runtime | GGUF through llama.cpp / llama-cpp-python | Needed for Llama Champion evidence. |
+| UI | Gradio Blocks | Required by the hackathon and project rules. |
+
+## Parameter Budget
+
+Total model parameters must remain <= 32B.
+
+Record final numbers here before submission:
+
+| Component | Model | Parameters | Counted Toward Total |
+| --- | --- | ---: | --- |
+| Vision | TBD | TBD | yes |
+| Text base | TBD | TBD | yes |
+| LoRA adapter | TBD | TBD | yes |
+| Total | TBD | TBD | must be <= 32B |
+
+## Intended Inputs And Outputs
+
+Inputs:
+
+- user-uploaded everyday object photo
+- optional object description
+- personality mode
+
+Outputs:
+
+- structured object understanding JSON
+- hidden object persona JSON
+- short English-first diary with Chinese helper text
+- object chat response
+- share card preview
+- anonymized trace record
+
+## Dataset Notes
+
+Dataset planning lives in `docs/DATASET.md`.
+
+Current preview data is deterministic and mock-generated. It should only be used for schema validation and workflow planning until real candidate samples are generated and curated.
+
+## Safety And Privacy
+
+- Do not use OpenAI, Anthropic, Gemini, Cohere, or other commercial model APIs.
+- Do not publish private user photos or unconsented personal data.
+- Do not include tokens, credit codes, emails, serial numbers, or credentials.
+- Keep raw private traces out of public datasets.
+
+## Fallback Behavior
+
+- If VLM loading fails, use manual description and stable example flow.
+- If llama.cpp loading fails, keep deterministic mock text fallback for demo safety.
+- If model JSON is invalid, repair and validate before rendering.
+
 ## Required Notes
 
 - Total model parameter count must remain <= 32B.

docs/README.md

@@ -16,4 +16,10 @@ This folder contains the planning source of truth for Objectverse Diary.
 
 - `FIELD_NOTES.md`: future technical blog draft.
 - `MODEL_CARD.md`: future model documentation.
+- `07-development-plan.md`: detailed development process plan from mock MVP to final submission.
+- `RUNTIME.md`: current mock runtime configuration and future model boundary.
+- `DATASET.md`: SFT preview schema, generation workflow, curation checklist, and publishing notes.
+- `FAILURES.md`: failure record template and anticipated non-UI fallback cases.
+- `INITIAL_STAGE_REPORT.md`: local initial-stage completion evidence and acceptance commands.
+- `EXTERNAL_SETUP.md`: GitHub and Hugging Face Space setup notes requiring confirmation.
 - `SUBMISSION_GUIDE.md`: final submission checklist.

docs/RUNTIME.md

@@ -0,0 +1,44 @@
+# Runtime Configuration
+
+## Current Runtime
+
+The initial MVP uses deterministic mock runtime paths:
+
+- `OBJECTVERSE_VISION_BACKEND=mock`
+- `OBJECTVERSE_TEXT_BACKEND=mock`
+
+This means:
+
+- object understanding is generated by `src/models/vision_runner.py`
+- persona, diary, and chat are generated by `src/models/llama_cpp_runner.py`
+- traces mark `mock-runtime` in the `fallbacks` field
+
+No commercial cloud AI APIs are used.
+
+## Environment Variables
+
+```bash
+OBJECTVERSE_VISION_BACKEND=mock
+OBJECTVERSE_TEXT_BACKEND=mock
+VISION_MODEL_ID=
+TEXT_MODEL_PATH=
+TRACE_OUTPUT_DIR=data/traces
+```
+
+## Future Runtime Boundary
+
+The next implementation phase should keep the same pipeline boundary:
+
+1. UI calls `src/pipeline.py`.
+2. `src/pipeline.py` calls the configured vision and text runners.
+3. runners return validated Pydantic schemas.
+4. trace logging records backend metadata and fallback markers.
+
+Do not move model calls into `src/ui/layout.py`.
+
+## Fallback Rules
+
+- VLM unavailable: use manual description and mock/example gallery path.
+- llama.cpp unavailable: use mock text generation path.
+- invalid model JSON: repair and validate before rendering.
+- private input: anonymize trace text before saving public traces.

docs/SUBMISSION_GUIDE.md

@@ -2,15 +2,23 @@
 
 ## Required Package
 
-- [ ] Hugging Face Space URL
-- [ ] GitHub Repository URL
-- [ ] Demo Video URL
-- [ ] Social Media Post URL
-- [ ] Fine-tuned Model URL
-- [ ] Dataset URL
-- [ ] Trace Dataset URL
-- [ ] Field Notes Blog URL
-- [ ] Short project description
+- [ ] Hugging Face Space URL: pending external setup
+- [ ] GitHub Repository URL: pending external setup
+- [ ] Demo Video URL: pending recording
+- [ ] Social Media Post URL: pending final copy
+- [ ] Fine-tuned Model URL: pending model training
+- [ ] Dataset URL: pending curation and publishing
+- [ ] Trace Dataset URL: local mock JSONL export ready, publishing pending
+- [ ] Field Notes Blog URL: draft source in `docs/FIELD_NOTES.md`
+- [x] Short project description: available in README
+
+## Local Evidence Ready
+
+- Initial mock MVP report: `docs/INITIAL_STAGE_REPORT.md`
+- Runtime boundary: `docs/RUNTIME.md`
+- Dataset plan and preview workflow: `docs/DATASET.md`
+- External setup checklist: `docs/EXTERNAL_SETUP.md`
+- Public mock traces: `data/traces/samples/`
 
 ## Final Checks
 

pyproject.toml

@@ -3,8 +3,11 @@ name = "objectverse-diary"
 version = "0.0.0"
 description = "A small-model AI toy that turns everyday objects into secret diary characters."
 requires-python = ">=3.10"
-dependencies = []
+dependencies = [
+    "gradio>=4.44,<6",
+    "pydantic>=2.7,<3",
+]
 
 [tool.objectverse-diary]
-status = "structure-only"
-implementation = "not-started"
+status = "initial-mock-mvp"
+implementation = "mock-runtime"

requirements.txt

@@ -1,2 +1,2 @@
-# Dependencies will be added when implementation starts.
-# Planned stack: gradio, llama-cpp-python, pydantic, pillow, MiniCPM-V runtime tools.
+gradio>=4.44,<6
+pydantic>=2.7,<3

scripts/README.md

@@ -1,13 +1,18 @@
 # Scripts
 
-Planned automation scripts for dataset generation, fine-tuning, GGUF conversion, llama.cpp runtime, and trace export.
+Automation scripts for dataset generation, fine-tuning, GGUF conversion, llama.cpp runtime, and trace export.
+
+Implemented initial scripts:
+
+- `check_initial_stage.py`: verifies required files, runtime defaults, sample traces, pipeline, and Gradio build.
+- `generate_sample_traces.py`: creates six stable public mock traces under `data/traces/samples/`.
+- `generate_dataset.py`: creates deterministic SFT preview JSONL for schema and curation planning.
+- `export_traces.py`: exports validated public sample traces to JSONL for dataset-style publishing.
 
 Expected files during implementation:
 
-- `generate_dataset.py`
 - `finetune_lora.py`
 - `convert_to_gguf.sh`
 - `run_llama_cpp.sh`
-- `export_traces.py`
 
-Current status: no implementation code.
+Current status: mock trace generation, trace JSONL export, and SFT preview generation are implemented. Real model, fine-tuning, and GGUF conversion scripts are not implemented yet.

scripts/__init__.py

@@ -0,0 +1 @@
+"""Project scripts package."""

scripts/check_initial_stage.py

@@ -0,0 +1,194 @@
+"""Acceptance checks for the initial mock MVP stage."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from src.config import get_runtime_settings, runtime_status
+from src.examples import EXAMPLE_OBJECTS
+from src.models.schema import TraceRecord
+from src.pipeline import generate_object_diary
+from scripts.export_traces import export_trace_jsonl
+from scripts.generate_dataset import build_sft_records, write_sft_jsonl
+
+
+REQUIRED_FILES = [
+    "app.py",
+    "README.md",
+    "requirements.txt",
+    "pyproject.toml",
+    "docs/07-development-plan.md",
+    "docs/EXTERNAL_SETUP.md",
+    "docs/FAILURES.md",
+    "docs/INITIAL_STAGE_REPORT.md",
+    "docs/RUNTIME.md",
+    "docs/DATASET.md",
+    "src/pipeline.py",
+    "src/models/schema.py",
+    "src/ui/layout.py",
+    "scripts/export_traces.py",
+    "scripts/generate_dataset.py",
+    "scripts/generate_sample_traces.py",
+    "tests/test_mock_mvp.py",
+    "tests/test_dataset_tooling.py",
+]
+
+FORBIDDEN_REQUIREMENTS = {
+    "openai",
+    "anthropic",
+    "google-generativeai",
+    "cohere",
+}
+
+
+def run_checks() -> list[str]:
+    results: list[str] = []
+    _ensure_local_tempdir()
+
+    _check_required_files()
+    results.append("required files exist")
+
+    _check_requirements()
+    results.append("requirements avoid commercial model SDKs")
+
+    _check_runtime_defaults()
+    results.append("runtime defaults to mock backends")
+
+    _check_pipeline()
+    results.append("pipeline generates and saves a trace")
+
+    _check_sample_traces()
+    results.append("six sample traces validate")
+
+    _check_dataset_preview()
+    results.append("dataset preview tooling works")
+
+    _check_trace_export()
+    results.append("trace JSONL export works")
+
+    _check_gradio_build()
+    results.append("Gradio Blocks app builds")
+
+    return results
+
+
+def _check_required_files() -> None:
+    missing = [path for path in REQUIRED_FILES if not (PROJECT_ROOT / path).exists()]
+    if missing:
+        raise RuntimeError(f"Missing required files: {', '.join(missing)}")
+
+
+def _check_requirements() -> None:
+    requirements = (PROJECT_ROOT / "requirements.txt").read_text(encoding="utf-8").lower()
+    forbidden = sorted(package for package in FORBIDDEN_REQUIREMENTS if package in requirements)
+    if forbidden:
+        raise RuntimeError(f"Forbidden commercial model SDK dependencies: {', '.join(forbidden)}")
+
+
+def _check_runtime_defaults() -> None:
+    settings = get_runtime_settings({})
+    status = runtime_status(settings)
+    if settings.vision_backend != "mock" or settings.text_backend != "mock":
+        raise RuntimeError("Runtime defaults must stay mock for the initial stage.")
+    if status["runtime"] != "no llama.cpp model connected yet":
+        raise RuntimeError("Unexpected initial runtime status.")
+
+
+def _check_pipeline() -> None:
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        result = generate_object_diary(
+            None,
+            "old white coffee mug on a developer desk",
+            "Cynical",
+            trace_dir=Path(tmp_dir),
+        )
+        trace_path = Path(result.trace_path)
+        if not trace_path.exists():
+            raise RuntimeError("Pipeline did not save trace output.")
+        TraceRecord.model_validate(json.loads(trace_path.read_text(encoding="utf-8")))
+
+
+def _check_sample_traces() -> None:
+    sample_dir = PROJECT_ROOT / "data/traces/samples"
+    paths = sorted(sample_dir.glob("*.json"))
+    if len(paths) != len(EXAMPLE_OBJECTS):
+        raise RuntimeError(f"Expected {len(EXAMPLE_OBJECTS)} sample traces, found {len(paths)}.")
+
+    trace_ids = set()
+    for path in paths:
+        trace = TraceRecord.model_validate(json.loads(path.read_text(encoding="utf-8")))
+        trace_ids.add(trace.trace_id)
+        if trace.fallbacks != ["mock-runtime"]:
+            raise RuntimeError(f"Unexpected fallbacks in {path}.")
+
+    expected_ids = {f"sample-{index:02d}" for index in range(1, len(EXAMPLE_OBJECTS) + 1)}
+    if trace_ids != expected_ids:
+        raise RuntimeError(f"Unexpected sample trace ids: {sorted(trace_ids)}")
+
+
+def _check_dataset_preview() -> None:
+    records = build_sft_records(6)
+    if len(records) != 6:
+        raise RuntimeError("Dataset preview did not generate six records.")
+
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        output_path = Path(tmp_dir) / "preview.jsonl"
+        write_sft_jsonl(records, output_path)
+        lines = output_path.read_text(encoding="utf-8").splitlines()
+
+    if len(lines) != 6:
+        raise RuntimeError("Dataset preview JSONL did not write six lines.")
+
+    for line in lines:
+        payload = json.loads(line)
+        if payload.get("split") != "preview":
+            raise RuntimeError("Dataset preview record has unexpected split.")
+        messages = payload.get("messages", [])
+        if len(messages) != 3:
+            raise RuntimeError("Dataset preview record must have three chat messages.")
+
+
+def _check_trace_export() -> None:
+    sample_dir = PROJECT_ROOT / "data/traces/samples"
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        output_path = Path(tmp_dir) / "public_traces.jsonl"
+        count = export_trace_jsonl(sample_dir, output_path)
+        lines = output_path.read_text(encoding="utf-8").splitlines()
+
+    if count != len(EXAMPLE_OBJECTS) or len(lines) != len(EXAMPLE_OBJECTS):
+        raise RuntimeError("Trace JSONL export count does not match sample traces.")
+
+    for line in lines:
+        TraceRecord.model_validate(json.loads(line))
+
+
+def _check_gradio_build() -> None:
+    from src.ui.layout import build_app
+
+    demo = build_app()
+    if type(demo).__name__ != "Blocks":
+        raise RuntimeError("Gradio app did not build a Blocks instance.")
+
+
+def _ensure_local_tempdir() -> None:
+    temp_dir = PROJECT_ROOT / ".tmp"
+    temp_dir.mkdir(parents=True, exist_ok=True)
+    os.environ.setdefault("TMPDIR", str(temp_dir))
+    tempfile.tempdir = str(temp_dir)
+
+
+def main() -> None:
+    for result in run_checks():
+        print(f"[OK] {result}")
+
+
+if __name__ == "__main__":
+    main()

scripts/export_traces.py

@@ -0,0 +1,61 @@
+"""Export validated public traces to a JSONL file."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from src.models.schema import TraceRecord
+
+
+DEFAULT_INPUT_DIR = Path("data/traces/samples")
+DEFAULT_OUTPUT_PATH = Path("data/traces/samples/objectverse_public_mock_traces.jsonl")
+
+
+def collect_traces(input_dir: Path = DEFAULT_INPUT_DIR) -> list[TraceRecord]:
+    paths = sorted(input_dir.glob("*.json"))
+    if not paths:
+        raise FileNotFoundError(f"No trace JSON files found under {input_dir}")
+
+    traces: list[TraceRecord] = []
+    for path in paths:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        traces.append(TraceRecord.model_validate(payload))
+    return traces
+
+
+def export_trace_jsonl(
+    input_dir: Path = DEFAULT_INPUT_DIR,
+    output_path: Path = DEFAULT_OUTPUT_PATH,
+) -> int:
+    traces = collect_traces(input_dir)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    lines = [
+        json.dumps(trace.model_dump(mode="json"), ensure_ascii=False, sort_keys=True)
+        for trace in traces
+    ]
+    output_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return len(traces)
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--input-dir", type=Path, default=DEFAULT_INPUT_DIR)
+    parser.add_argument("--output", type=Path, default=DEFAULT_OUTPUT_PATH)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = _parse_args()
+    count = export_trace_jsonl(args.input_dir, args.output)
+    print(f"exported {count} traces to {args.output}")
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_dataset.py

@@ -0,0 +1,135 @@
+"""Generate deterministic SFT preview data for Objectverse Diary."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from src.config import PERSONALITY_MODES
+from src.examples import EXAMPLE_OBJECTS
+from src.pipeline import generate_object_diary
+
+
+DEFAULT_OUTPUT_PATH = Path("data/train/objectverse_sft_preview.jsonl")
+DEFAULT_COUNT = 60
+
+SYSTEM_PROMPT = (
+    "You are Objectverse Diary, an English-first small-model assistant. "
+    "Given structured object understanding and a requested personality mode, "
+    "return JSON containing a consistent hidden object persona and a short diary."
+)
+
+SCENE_VARIANTS = [
+    "after a long day of being ignored",
+    "beside half-finished notes",
+    "under warm desk light",
+    "near a quiet morning window",
+    "during a suspiciously ordinary afternoon",
+    "while humans rush past without noticing",
+    "after surviving another minor household crisis",
+    "beside a charging cable and old receipts",
+    "in the corner of a room that knows too much",
+    "before anyone remembers to clean it",
+]
+
+
+def build_sft_records(count: int = DEFAULT_COUNT) -> list[dict[str, object]]:
+    if count < 1:
+        raise ValueError("count must be at least 1")
+
+    records: list[dict[str, object]] = []
+    for index in range(count):
+        example = EXAMPLE_OBJECTS[index % len(EXAMPLE_OBJECTS)]
+        mode = _mode_for_index(example, index)
+        description = _description_for_index(example, index)
+        result = generate_object_diary(
+            image_path=None,
+            description=description,
+            mode=mode,
+            save=False,
+            trace_id=f"sft-preview-{index + 1:04d}",
+        )
+        assistant_payload = {
+            "persona": result.persona.persona.model_dump(mode="json"),
+            "diary": result.diary.model_dump(mode="json"),
+        }
+        record = {
+            "id": f"sft-preview-{index + 1:04d}",
+            "source": "objectverse-diary-mock-mvp",
+            "split": "preview",
+            "mode": mode,
+            "object_description": description,
+            "object_understanding": result.object_understanding.model_dump(mode="json"),
+            "messages": [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {
+                    "role": "user",
+                    "content": _user_prompt(
+                        result.object_understanding.model_dump(mode="json"),
+                        mode,
+                    ),
+                },
+                {
+                    "role": "assistant",
+                    "content": json.dumps(assistant_payload, ensure_ascii=False),
+                },
+            ],
+        }
+        records.append(record)
+
+    return records
+
+
+def write_sft_jsonl(records: Sequence[Mapping[str, object]], output_path: Path) -> Path:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    lines = [json.dumps(record, ensure_ascii=False, sort_keys=True) for record in records]
+    output_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return output_path
+
+
+def generate_dataset(output_path: Path = DEFAULT_OUTPUT_PATH, count: int = DEFAULT_COUNT) -> Path:
+    return write_sft_jsonl(build_sft_records(count), output_path)
+
+
+def _mode_for_index(example: Mapping[str, str], index: int) -> str:
+    base_mode = example["mode"]
+    base_index = PERSONALITY_MODES.index(base_mode) if base_mode in PERSONALITY_MODES else 0
+    return PERSONALITY_MODES[(base_index + index) % len(PERSONALITY_MODES)]
+
+
+def _description_for_index(example: Mapping[str, str], index: int) -> str:
+    scene = SCENE_VARIANTS[index % len(SCENE_VARIANTS)]
+    return f"{example['description']}, {scene}"
+
+
+def _user_prompt(object_understanding: Mapping[str, object], mode: str) -> str:
+    payload = json.dumps(object_understanding, ensure_ascii=False, sort_keys=True)
+    return (
+        f"Personality mode: {mode}\n"
+        f"Object understanding JSON: {payload}\n"
+        "Return JSON with keys persona and diary."
+    )
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--count", type=int, default=DEFAULT_COUNT)
+    parser.add_argument("--output", type=Path, default=DEFAULT_OUTPUT_PATH)
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = _parse_args()
+    output_path = generate_dataset(args.output, args.count)
+    print(f"wrote {args.count} SFT preview records to {output_path}")
+
+
+if __name__ == "__main__":
+    main()

scripts/generate_sample_traces.py

@@ -0,0 +1,55 @@
+"""Generate stable public sample traces for the mock MVP."""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from src.examples import EXAMPLE_OBJECTS
+from src.pipeline import generate_object_diary
+
+
+DEFAULT_OUTPUT_DIR = Path("data/traces/samples")
+
+
+def generate_sample_traces(output_dir: Path = DEFAULT_OUTPUT_DIR) -> list[Path]:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    written_paths: list[Path] = []
+
+    for index, example in enumerate(EXAMPLE_OBJECTS, start=1):
+        description = example["description"]
+        mode = example["mode"]
+        result = generate_object_diary(
+            image_path=None,
+            description=description,
+            mode=mode,
+            save=False,
+            trace_id=f"sample-{index:02d}",
+            created_at=datetime(2026, 6, 5, 0, index, tzinfo=timezone.utc),
+        )
+
+        filename = f"sample-{index:02d}-{_slug(example['label'])}.json"
+        path = output_dir / filename
+        path.write_text(
+            json.dumps(result.trace.model_dump(mode="json"), ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+        written_paths.append(path)
+
+    return written_paths
+
+
+def _slug(value: str) -> str:
+    slug = value.split("/", maxsplit=1)[0].strip().lower()
+    return "".join(char if char.isalnum() else "-" for char in slug).strip("-")
+
+
+if __name__ == "__main__":
+    for generated_path in generate_sample_traces():
+        print(generated_path)

src/README.md

@@ -2,11 +2,12 @@
 
 This directory is reserved for application source code.
 
-Current status: structure-only. No implementation code has been added yet.
+Current status: initial mock MVP. Real model runtimes are not connected yet.
 
 ## Planned Areas
 
 - `ui/`: Gradio layout, CSS, and copy.
+- `examples.py`: stable mock examples for the initial gallery.
 - `models/`: vision runner, llama.cpp text runner, and schemas.
 - `prompts/`: object understanding, persona generation, and diary generation prompts.
 - `renderer/`: share card and HTML rendering.

src/__init__.py

@@ -0,0 +1 @@
+"""Objectverse Diary source package."""

src/config.py

@@ -0,0 +1,66 @@
+"""Shared configuration for the initial mock MVP."""
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+
+APP_TITLE = "Objectverse Diary"
+APP_SUBTITLE = "Every object has a secret life. / 每个物品都有秘密人生。"
+APP_VERSION = "0.1.0-mock"
+
+PERSONALITY_MODES = [
+    "Cynical",
+    "Dramatic",
+    "Lonely",
+    "Philosopher",
+    "Romantic",
+]
+
+DEFAULT_MODE = "Cynical"
+
+
+@dataclass(frozen=True)
+class RuntimeSettings:
+    vision_backend: str
+    text_backend: str
+    text_model_path: str
+    vision_model_id: str
+    trace_output_dir: Path
+
+
+def get_runtime_settings(environ: Mapping[str, str] | None = None) -> RuntimeSettings:
+    env = os.environ if environ is None else environ
+    return RuntimeSettings(
+        vision_backend=env.get("OBJECTVERSE_VISION_BACKEND", "mock"),
+        text_backend=env.get("OBJECTVERSE_TEXT_BACKEND", "mock"),
+        text_model_path=env.get("TEXT_MODEL_PATH", ""),
+        vision_model_id=env.get("VISION_MODEL_ID", ""),
+        trace_output_dir=Path(env.get("TRACE_OUTPUT_DIR", "data/traces")),
+    )
+
+
+def runtime_status(settings: RuntimeSettings | None = None) -> dict[str, str]:
+    current = settings or get_runtime_settings()
+    vision = (
+        "mock object understanding"
+        if current.vision_backend == "mock"
+        else f"{current.vision_backend} object understanding"
+    )
+    text = (
+        "mock persona and diary generation"
+        if current.text_backend == "mock"
+        else f"{current.text_backend} persona and diary generation"
+    )
+    runtime = (
+        "no llama.cpp model connected yet"
+        if current.text_backend == "mock"
+        else f"text model path: {current.text_model_path or '[not configured]'}"
+    )
+    return {"vision": vision, "text": text, "runtime": runtime}
+
+
+SETTINGS = get_runtime_settings()
+TRACE_DIR = SETTINGS.trace_output_dir
+MODEL_RUNTIME_STATUS = runtime_status(SETTINGS)

src/examples.py

@@ -0,0 +1,38 @@
+"""Stable example objects for the initial mock MVP."""
+
+EXAMPLE_OBJECTS = [
+    {
+        "label": "Coffee mug / 咖啡杯",
+        "description": "old white coffee mug on a developer desk",
+        "mode": "Cynical",
+    },
+    {
+        "label": "Mechanical keyboard / 机械键盘",
+        "description": "dusty black mechanical keyboard in an office",
+        "mode": "Philosopher",
+    },
+    {
+        "label": "Running shoe / 跑鞋",
+        "description": "worn running shoe near the bedroom door",
+        "mode": "Lonely",
+    },
+    {
+        "label": "Desk lamp / 台灯",
+        "description": "metal desk lamp over late night notes",
+        "mode": "Dramatic",
+    },
+    {
+        "label": "Water bottle / 水瓶",
+        "description": "clear plastic water bottle on a kitchen counter",
+        "mode": "Romantic",
+    },
+    {
+        "label": "Notebook / 笔记本",
+        "description": "old notebook of abandoned project ideas",
+        "mode": "Cynical",
+    },
+]
+
+
+def gradio_examples() -> list[list[str]]:
+    return [[item["description"]] for item in EXAMPLE_OBJECTS]

src/models/README.md

@@ -0,0 +1,11 @@
+# Models
+
+Planned model runtime layer.
+
+Implemented initial files:
+
+- `vision_runner.py`
+- `llama_cpp_runner.py`
+- `schema.py`
+
+Current status: deterministic mock object understanding and text generation.

src/models/llama_cpp_runner.py

@@ -0,0 +1,110 @@
+"""Mock text generation layer reserved for future llama.cpp integration."""
+
+from __future__ import annotations
+
+from src.models.schema import DiaryEntry, ObjectUnderstanding, Persona, PersonaEnvelope
+
+
+MODE_PROFILES = {
+    "Cynical": {
+        "mood": "tired but sarcastic",
+        "fear": "being replaced by a newer object with worse opinions",
+        "voice": "dry",
+    },
+    "Dramatic": {
+        "mood": "theatrical and wounded",
+        "fear": "being forgotten before the final act",
+        "voice": "operatic",
+    },
+    "Lonely": {
+        "mood": "softly abandoned",
+        "fear": "becoming invisible in plain sight",
+        "voice": "quiet",
+    },
+    "Philosopher": {
+        "mood": "curious and needlessly profound",
+        "fear": "discovering that usefulness is not meaning",
+        "voice": "reflective",
+    },
+    "Romantic": {
+        "mood": "hopelessly sentimental",
+        "fear": "loving a human who only sees storage capacity",
+        "voice": "wistful",
+    },
+}
+
+
+def generate_persona(object_understanding: ObjectUnderstanding, mode: str) -> PersonaEnvelope:
+    object_name = object_understanding.object.name
+    profile = MODE_PROFILES.get(mode, MODE_PROFILES["Cynical"])
+    character_name = _character_name(object_name, mode)
+
+    persona = Persona(
+        object_name=object_name,
+        character_name=character_name,
+        mood=profile["mood"],
+        secret_fear=profile["fear"],
+        core_memory=f"survived many quiet hours as a {object_name} while humans called it normal life",
+        complaint=f"I am not just a {object_name}. I am an unpaid witness with excellent recall.",
+        tags=_tags_for_mode(mode),
+    )
+    return PersonaEnvelope(persona=persona)
+
+
+def generate_diary(persona: PersonaEnvelope, mode: str) -> DiaryEntry:
+    p = persona.persona
+    day_number = 417 + len(p.object_name)
+
+    english = (
+        f"They touched me again today with the confidence of someone who has never asked "
+        f"a {p.object_name} for consent. I remained still, because that is my contract with gravity. "
+        f"My mood is {p.mood}, my secret fear is {p.secret_fear}, and my only comfort is knowing "
+        "I have outlived at least three urgent plans."
+    )
+    chinese = (
+        f"今天他们又理所当然地碰了我，好像一个 {p.object_name} 不会有边界感。"
+        f"我保持沉默，因为这大概是我和重力签下的合同。我的情绪是 {p.mood}，"
+        f"秘密恐惧是 {p.secret_fear}。至少，我已经熬过了好几个所谓紧急计划。"
+    )
+
+    return DiaryEntry(
+        title=f"Secret Diary - Day {day_number}",
+        english=english,
+        chinese=chinese,
+    )
+
+
+def reply_as_object(persona_data: dict, message: str) -> str:
+    persona = persona_data.get("persona", {})
+    character_name = persona.get("character_name", "The Object")
+    object_name = persona.get("object_name", "object")
+    mood = persona.get("mood", "suspicious")
+    complaint = persona.get("complaint", "I have seen enough.")
+    clean_message = message.strip() or "..."
+
+    return (
+        f"{character_name}: You ask me about '{clean_message}', as if a {object_name} "
+        f"with a {mood} mood has unlimited office hours. {complaint}"
+    )
+
+
+def _character_name(object_name: str, mode: str) -> str:
+    compact = "".join(part.capitalize() for part in object_name.split()[:2])
+    suffix = {
+        "Cynical": "worth",
+        "Dramatic": "von Sigh",
+        "Lonely": "Afterlight",
+        "Philosopher": "the Questioning",
+        "Romantic": "de Moon",
+    }.get(mode, "worth")
+    return f"{compact} {suffix}".strip()
+
+
+def _tags_for_mode(mode: str) -> list[str]:
+    return {
+        "Cynical": ["desk survivor", "burnt optimism", "quiet judgment"],
+        "Dramatic": ["tragic prop", "grand entrance", "minor catastrophe"],
+        "Lonely": ["forgotten corner", "soft echo", "dust companion"],
+        "Philosopher": ["tiny ontology", "useful doubt", "meaning crisis"],
+        "Romantic": ["tender witness", "hopeless glow", "secret devotion"],
+    }.get(mode, ["odd witness", "secret life", "object soul"])

src/models/schema.py

@@ -0,0 +1,59 @@
+"""Pydantic schemas for mock MVP outputs."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ObjectInfo(BaseModel):
+    name: str
+    visible_features: list[str] = Field(default_factory=list)
+    likely_context: str
+    confidence: float = Field(ge=0, le=1)
+
+
+class ObjectUnderstanding(BaseModel):
+    object: ObjectInfo
+
+
+class Persona(BaseModel):
+    object_name: str
+    character_name: str
+    mood: str
+    secret_fear: str
+    core_memory: str
+    complaint: str
+    tags: list[str] = Field(min_length=3, max_length=3)
+
+
+class PersonaEnvelope(BaseModel):
+    persona: Persona
+
+
+class DiaryEntry(BaseModel):
+    title: str
+    english: str
+    chinese: str
+
+
+class TraceRecord(BaseModel):
+    trace_id: str
+    created_at: datetime
+    mode: str
+    input: dict[str, Any]
+    object_understanding: ObjectUnderstanding
+    persona: PersonaEnvelope
+    diary: DiaryEntry
+    model_runtime: dict[str, str]
+    fallbacks: list[str] = Field(default_factory=list)
+
+
+class GenerationResult(BaseModel):
+    object_understanding: ObjectUnderstanding
+    persona: PersonaEnvelope
+    diary: DiaryEntry
+    trace: TraceRecord
+    trace_path: str

src/models/vision_runner.py

@@ -0,0 +1,80 @@
+"""Mock object understanding for the initial MVP."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from src.models.schema import ObjectInfo, ObjectUnderstanding
+
+
+KNOWN_OBJECTS = {
+    "mug": "coffee mug",
+    "cup": "coffee mug",
+    "keyboard": "keyboard",
+    "shoe": "shoe",
+    "book": "book",
+    "phone": "phone",
+    "lamp": "desk lamp",
+    "bottle": "water bottle",
+    "bag": "bag",
+}
+
+
+def understand_object(image_path: str | None, description: str) -> ObjectUnderstanding:
+    """Return deterministic mock object understanding until VLM integration starts."""
+    clean_description = description.strip()
+    object_name = _infer_object_name(clean_description, image_path)
+    features = _infer_features(clean_description, image_path)
+
+    return ObjectUnderstanding(
+        object=ObjectInfo(
+            name=object_name,
+            visible_features=features,
+            likely_context=_infer_context(clean_description),
+            confidence=0.42 if clean_description else 0.32,
+        )
+    )
+
+
+def _infer_object_name(description: str, image_path: str | None) -> str:
+    lowered = description.lower()
+    for keyword, name in KNOWN_OBJECTS.items():
+        if keyword in lowered:
+            return name
+
+    if image_path:
+        stem = Path(image_path).stem.replace("_", " ").replace("-", " ").strip()
+        if stem:
+            return stem[:40]
+
+    return "mysterious everyday object"
+
+
+def _infer_features(description: str, image_path: str | None) -> list[str]:
+    features: list[str] = []
+    lowered = description.lower()
+
+    for word in ["old", "new", "cracked", "white", "black", "dusty", "metal", "ceramic", "plastic"]:
+        if word in lowered:
+            features.append(word)
+
+    if image_path:
+        features.append("uploaded photo provided")
+
+    if description:
+        features.append("user-supplied description")
+
+    return features[:5] or ["ordinary surface", "unknown material", "quietly suspicious"]
+
+
+def _infer_context(description: str) -> str:
+    lowered = description.lower()
+    if "desk" in lowered:
+        return "developer desk"
+    if "kitchen" in lowered:
+        return "kitchen counter"
+    if "bedroom" in lowered:
+        return "bedroom shelf"
+    if "office" in lowered:
+        return "office corner"
+    return "everyday human environment"

src/pipeline.py

@@ -0,0 +1,50 @@
+"""Generation pipeline shared by UI, scripts, and tests."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from src.config import TRACE_DIR
+from src.models.llama_cpp_runner import generate_diary, generate_persona
+from src.models.schema import GenerationResult
+from src.models.vision_runner import understand_object
+from src.traces.logger import build_trace, save_trace
+
+
+def generate_object_diary(
+    image_path: str | None,
+    description: str,
+    mode: str,
+    *,
+    trace_dir: Path = TRACE_DIR,
+    save: bool = True,
+    trace_id: str | None = None,
+    created_at: datetime | None = None,
+) -> GenerationResult:
+    object_understanding = understand_object(image_path, description)
+    persona = generate_persona(object_understanding, mode)
+    diary = generate_diary(persona, mode)
+    trace = build_trace(
+        image_path=image_path,
+        description=description,
+        mode=mode,
+        object_understanding=object_understanding,
+        persona=persona,
+        diary=diary,
+        trace_id=trace_id,
+        created_at=created_at,
+    )
+    trace_path = save_trace(trace, trace_dir) if save else ""
+
+    return GenerationResult(
+        object_understanding=object_understanding,
+        persona=persona,
+        diary=diary,
+        trace=trace,
+        trace_path=trace_path,
+    )
+
+
+def format_diary_markdown(title: str, english: str, chinese: str) -> str:
+    return f"## {title}\n\n{english}\n\n---\n\n**中文辅助**\n\n{chinese}"

src/prompts/README.md

@@ -2,10 +2,10 @@
 
 Planned prompt templates.
 
-Expected files during implementation:
+Implemented placeholder files:
 
 - `object_understanding.py`
 - `persona_generation.py`
 - `diary_generation.py`
 
-Current status: no implementation code.
+Current status: prompt placeholders only. Real model prompts are not finalized.

src/prompts/diary_generation.py

@@ -0,0 +1,6 @@
+"""Prompt placeholder for future secret diary generation."""
+
+DIARY_GENERATION_PROMPT = """
+Write a short secret diary entry in English first, with Chinese helper translation.
+Keep the object persona consistent.
+""".strip()

src/prompts/object_understanding.py

@@ -0,0 +1,6 @@
+"""Prompt placeholder for future VLM object understanding."""
+
+OBJECT_UNDERSTANDING_PROMPT = """
+Identify the everyday object, visible features, likely context, and confidence.
+Return structured JSON only.
+""".strip()

src/prompts/persona_generation.py

@@ -0,0 +1,7 @@
+"""Prompt placeholder for future persona generation."""
+
+PERSONA_GENERATION_PROMPT = """
+Create a hidden first-person object persona with name, mood, backstory,
+complaint, secret fear, core memory, and exactly three tags.
+Return structured JSON only.
+""".strip()

src/renderer/README.md

@@ -2,9 +2,9 @@
 
 Planned rendering layer for diary views and share cards.
 
-Expected files during implementation:
+Implemented initial files:
 
 - `share_card.py`
 - `html_templates.py`
 
-Current status: no implementation code.
+Current status: share card HTML renderer for mock MVP.

src/renderer/html_templates.py

@@ -0,0 +1,3 @@
+"""Small HTML templates for the initial MVP."""
+
+CARD_WRAPPER_CLASS = "objectverse-card"