README.md

CASL Voice Bot

A speech pathology assistant using AI to assess students' speaking abilities based on the CASL-2 framework. This application helps speech-language pathologists (SLPs) with speech assessment in school settings.

Implementations

This project provides multiple implementations:

1. LiveKit Implementation - Uses LiveKit agents with OpenAI's real-time voice API for low-latency, high-quality audio streaming.
2. Direct API Implementation - Uses OpenAI's API directly without LiveKit, for simpler deployment.
3. Hugging Face Spaces - An adaptive implementation that works on Hugging Face Spaces, automatically detecting whether LiveKit is available.

Features

• Voice-to-voice interaction with AI speech pathologist
• CASL-2 framework assessment
• Real-time assessment tracking
• Session recording and saving
• Custom note-taking for SLPs
• Gradio web interface for easy sharing and use in school settings

CASL-2 Assessment Areas

The AI speech pathologist assesses students in these key areas:

1. Lexical/Semantic Skills: Vocabulary knowledge, word meanings, and contextual word use
2. Syntactic Skills: Grammar and sentence structure understanding
3. Supralinguistic Skills: Higher-level language skills beyond literal meanings
4. Pragmatic Skills: Language use in social contexts (less emphasis for younger students)

Setup Instructions

Prerequisites

• Python 3.8+
• OpenAI API key with access to GPT-4o and TTS models

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/CASLVoiceBot.git
   cd CASLVoiceBot
   

2. Create a virtual environment and install dependencies:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

3. For LiveKit implementation, install LiveKit dependencies:

   # Edit requirements.txt to uncomment the livekit-agents line
   pip install livekit-agents>=0.7.0
   

4. Set up environment variables:

   cp .env.example .env
   

   Then edit .env to add your OpenAI API key.

Running the Application

LiveKit Implementation (recommended for best performance)

python run_livekit.py

Direct API Implementation (simpler deployment)

python run_direct.py

Command Line Options

Both implementations support these options:

• --share: Share the app publicly (enabled by default)
• --local: Run the app locally without sharing

Deployment on Hugging Face Spaces

1. Create a new Space on Hugging Face with the Gradio SDK
2. Upload the repository contents to the Space
3. Add your OPENAI_API_KEY as a secret in the Space settings

By default, the Hugging Face Spaces deployment will try to use LiveKit if available, and fall back to direct API if not.

Project Structure

CASLVoiceBot/
├── app.py                  # Hugging Face Spaces entry point
├── run_direct.py           # Direct API implementation runner
├── run_livekit.py          # LiveKit implementation runner
├── requirements.txt        # Common dependencies
├── .env.example            # Environment variables template
├── implementations/
│   ├── common/             # Shared utilities
│   │   ├── casl_utils.py   # CASL-2 assessment utilities
│   ├── direct/             # Direct API implementation
│   │   ├── app.py          # Direct OpenAI API app
│   ├── livekit/            # LiveKit implementation
│   │   ├── app.py          # LiveKit app
│   │   ├── livekit_gradio_hf.py # HF-compatible LiveKit app
├── session_data/           # Saved session data

Usage

1. Optionally enter a Student ID to track sessions
2. Select your preferred AI voice
3. Click "Start Session" to begin a speech assessment
4. Wait for the AI to introduce itself, then speak when prompted
5. View real-time assessment in the interface
6. SLPs can add notes throughout the session
7. Save the session when finished
8. Click "Stop Session" to end

License

MIT License