AGENTS.md

AGENTS.md

Project

Objectverse Diary is a Build Small Hackathon project. It is an English-first, Chinese-second Gradio application where users upload everyday object photos and small AI models generate secret object personas, diary entries, conversations, and shareable cards.

Primary Goals

1. Compete in the "An Adventure in Thousand Token Wood" track.
2. Keep total model parameters <= 32B.
3. Use Gradio for all UI and interaction.
4. Host the final app as a Hugging Face Space.
5. Avoid commercial cloud AI APIs.
6. Maximize hackathon badges.
7. Use English as the main UI language and Chinese as secondary helper text.

Non-Negotiable Rules

• Do not use OpenAI, Anthropic, Gemini, Cohere, or other commercial model APIs.
• Do not leak private credit codes, tokens, emails, or credentials.
• Do not hardcode secrets.
• Do not remove Gradio.
• Do not make the UI Chinese-first.
• Do not exceed the 32B total model parameter limit.
• Do not add large features that risk missing the submission deadline.
• Do not store unconsented personal user data.

Tech Stack

• Python
• Gradio Blocks
• Hugging Face Spaces
• llama.cpp / llama-cpp-python for text generation
• MiniCPM-V or fallback lightweight VLM for object understanding
• LoRA / PEFT for fine-tuning
• Markdown documentation

UI Requirements

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

1. Image upload
2. Object understanding
3. Persona generation
4. Secret diary generation
5. Object chat
6. Share card rendering
7. Trace export

Coding Guidelines

• Use type hints.
• Prefer small, composable functions.
• Prompts belong under src/prompts/.
• UI copy belongs under src/ui/copy.py.
• CSS belongs under src/ui/styles.css.
• Runtime code belongs under src/models/.
• Trace code belongs under src/traces/.
• Use Pydantic schemas for model outputs.
• Add clear fallback behavior when model output is invalid.

Testing Requirements

• App runs locally.
• App runs on HF Space.
• At least 6 sample objects work.
• Share card renders correctly.
• Trace export works.
• No secret keys committed.
• README links valid.
• Demo video flow reproducible.

Current Implementation Boundary

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.