jf-sebastian: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

J.F. Sebastian is an AI-powered animatronic conversation system that brings vintage animatronic toys to life through real-time voice interactions. The system enables personality-driven conversations with ChatGPT through devices like the 1985 Teddy Ruxpin doll, featuring speech recognition, text-to-speech synthesis, and optional voice conversion.

Critical Requirements:

• Python 3.10.x specifically (RVC dependencies incompatible with 3.11+)
• macOS is the primary environment (audio device names in .env.example are Mac devices); Linux/Jetson is also supported (see docs/JETSON_DEPLOYMENT.md)
• OpenAI API key required for Whisper, the GPT chat model (GPT_MODEL), and TTS

Essential Commands

Setup and Installation

# Automated setup (recommended)
./setup.sh

# Manual virtual environment setup
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

# Install RVC (optional, requires Python 3.10)
./scripts/install_rvc.sh
# OR manually:
pip install pip==24.0
pip install -r requirements-rvc.txt
pip install --upgrade pip

# Download OpenWakeWord preprocessing models
python3 -c "from openwakeword import utils; utils.download_models(['alexa'])"

# List available audio devices
python -m jf_sebastian.modules.audio_output

Running the Application

# Using convenience script
./run.sh

# Direct execution
python -m jf_sebastian.main

# Supervised (recommended for unattended deployments: auto-restart on crash,
# watchdog kill of hung children, crash reports to ./crash_reports/).
# See scripts/jf-sebastian.plist (macOS) and scripts/jf-sebastian.service (Linux)
# for the production install paths.
HEARTBEAT_FILE=/tmp/jf_sebastian.heartbeat python scripts/supervisor.py

Testing

# Run all tests
pytest tests/

# Run specific test markers (all five are registered in pytest.ini, but only
# `unit` is applied today, in the tool-provider, Hue, and conversation-tools
# tests; the other markers currently select nothing)
pytest -m unit        # Unit tests only
pytest -m integration # Integration tests
pytest -m audio       # Audio-related tests
pytest -m slow        # Long-running tests

# Run tests with verbose output
pytest -v tests/

# Test specific component
pytest tests/modules/test_state_machine.py
pytest tests/personalities/test_base.py