chatterbox-ui/AGENTS.md

Agent Guidelines for Chatterbox-UI

Build/Test Commands

# Backend (FastAPI)
pip install -r backend/requirements.txt
uvicorn backend.app.main:app --reload --host 0.0.0.0 --port 8000
python backend/run_api_test.py  # Run all backend tests

# Frontend
npm test  # Run all frontend tests
npx jest frontend/tests/api.test.js  # Run single test file

# Alternative UI
python gradio_app.py  # Run Gradio interface

Code Style Guidelines

Python

• Use type hints (from typing import Optional, List, etc.)
• Exception handling: Use try/except with specific exceptions
• Async/await for FastAPI endpoints and services
• Docstrings for functions and classes
• Use pathlib.Path for file operations
• Organize code into routers, models, and services

JavaScript

• ES6 modules with import/export
• JSDoc comments for functions
• Async/await for API calls
• Proper error handling with detailed messages
• Descriptive variable and function names
• Consistent error handling pattern in API calls

Error Handling

• Backend: Raise specific exceptions, use try/except/finally
• Frontend: Use try/catch with detailed error messages
• Always include error details in API responses

Naming Conventions

• Python: snake_case for variables/functions, PascalCase for classes
• JavaScript: camelCase for variables/functions
• Descriptive, intention-revealing names

Architecture Notes

• Backend: FastAPI on port 8000, structured as routers/models/services
• Frontend: Vanilla JS (ES6+) on port 8001, modular design
• API Base URL: http://localhost:8000/api
• Speaker data in YAML format at speaker_data/speakers.yaml