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.