AGENT.md

Agent Guide for reachy_mini_minder

Context

Reachy Mini Minder is a Reachy Mini robot application that helps users log medication intake and record a headache diary via natural language conversation. It uses the OpenAI Realtime API for voice-first interaction.

Key Features:

• Voice-first medication logging
• Headache diary with neurological-standard fields
• Private SQLite storage with CSV/HTML export
• Robot emotion expressions during conversation

Structure & Navigation

reachy_mini_minder/
├── src/reachy_mini_conversation_app/  # Backend Python package (see src/AGENT.md)
│   ├── tools/                         # LLM tools (see tools/AGENT.md)
│   ├── profiles/                      # Conversation profiles (see profiles/AGENT.md)
│   └── prompts/                       # System prompts (see prompts/AGENT.md)
├── frontend/                           # Next.js React UI (see frontend/AGENT.md)
│   ├── src/components/                # Page panels (see components/AGENT.md)
│   ├── src/hooks/                     # Data hooks (see hooks/AGENT.md)
│   └── src/registry/                  # GenUI components (see registry/AGENT.md)
├── tests/                              # Test suite (see tests/AGENT.md)
├── documentation/                      # Docs, design system, case studies, guides
├── .agent/                             # Agent rules and skills
└── pyproject.toml                      # Package configuration

Key Entry Points

• Backend API: src/reachy_mini_conversation_app/console.py (FastAPI on port 7860)
• Frontend: frontend/ (Next.js on port 3000)
• Robot app: src/reachy_mini_conversation_app/main.py
• CLI: reachy-mini-minder (via pyproject.toml scripts)
• Database: src/reachy_mini_conversation_app/database.py

Cross-Stack Dependency Map

When implementing features, these are the key chains that must be updated together:

Feature Type	Backend	Bridge	Frontend
New LLM tool with UI	Tool in tools/ or profiles/_locked_profile/	emit_ui_component() in stream_api.py	GenUI component in registry/ + register in index.tsx
New REST data	Endpoint in console.py	—	Hook in hooks/ + wire into component
Real-time event	emit_*() in stream_api.py	WebSocket event type	Handle in useConversation or new hook
Voice navigation	ui_control.py tool	emit_ui_navigate()	Handle target in ChatInterface.tsx
Settings change	update_settings.py tool	emit_settings_updated()	SettingsPanel re-fetches data
Session lifecycle	console.py session mgmt	emit_session_event()	useSession via DOM event from useConversation

Development Workflow

# Backend
pip install -e .
python src/reachy_mini_conversation_app/console.py  # Standalone API server

# Frontend
cd frontend && npm install && npm run dev

# Tests
pytest tests/

Configuration

• OPENAI_API_KEY: OpenAI Realtime API
• REACHY_MINI_HOST: Robot connection (optional)

See .env.example for all variables.