| # 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. |
|
|
