AI Teacher Chat is an interactive educational agent designed to simulate conversations with a knowledgeable teacher persona. The system loads domain-specific instructional content from YAML files and indexes it using an in-memory LlamaIndex store. The frontend is built with Gradio and allows users to personalize their experience by providing a name, which is included in the conversation metadata.
aiteacher-demo/
├── scripts/ # Script entry points (preload, chat launcher)
├── tests/ # Unit tests
├── aiteacher_demo/ # Main application code
├── .env.sample # Environment variable template
├── README.md
git clone git@github.com:compasspathways/aiteacher-demo.git
cd aiteacher-demo
python3 -m venv venv-aiteacher
source venv-aiteacher/bin/activateCreate your .env file by copying the template:
cp .env.sample .envEdit the .env file to configure environment-specific variables (API keys, paths, etc.).
- Python 3.10+
poetry
-
For development:
poetry install pre-commit install
-
For production/testing:
poetry install --without dev
Optional: Gradio External Access Setup (macOS ARM64)
If you plan to share your Gradio app online:
curl -o ~/Downloads/frpc_darwin_arm64 https://cdn-media.huggingface.co/frpc-gradio-0.3/frpc_darwin_arm64
mv ~/Downloads/frpc_darwin_arm64 ~/.cache/huggingface/gradio/frpc/frpc_darwin_arm64_v0.3
chmod +x ~/.cache/huggingface/gradio/frpc/frpc_darwin_arm64_v0.3Run preload.py once to download models
poetry run python scripts/preload.pyRelax, it will take a couple of minutes :)
poetry run python scripts/chat_with.py <user_name> <teacher_id> [--cloud]Arguments:
<user_name>: Your name for personalized interaction<teacher_id>: Identifier for the teacher persona (e.g.,dr_zen)--cloud: (Optional) Use LlamaCloud for inference
Example:
poetry run python scripts/chat_with.py Cris dr_zen Once started, access the app at:
Running on local URL: http://127.0.0.1:7860
For more info on the system architecture
The AI Teacher's knowledge comes from YAML files in the aiteacher/content directory. Here's how to add your own knowledge:
1. Understanding the Structure
- teachers/: Contains teacher personas and their configurations
- prompts/: Contains conversation prompts and templates
- knowledge: Contains the main knowledge base in YAML format
2. Adding Your Own Knowledge
Create a new YAML file in aiteacher/content/knowledge.yaml with this structure:
- type: your_domain
embed_text: >
Your specialized knowledge goes here.
This can be any content relevant to your domain.
metadata:
source: Your_Source
type: your_domain
topic: specific_topic
3. Creating a New Teacher
Create a new YAML file in aiteacher/content/teachers/ with this structure:
agent_type: teacher
name: Your Teacher Name
description: >
A brief description of your teacher's expertise and personality.
enabled: true
id: your_teacher_id
model_id: openai_gpt-4
completion_model_id: openai_gpt-3.5-turbo
user_type: patient
definition:
max_num_words: 1200
num_top_memories_in_embedding: 20
rerank_top_n: 10
4. Using Your Custom Knowledge
After adding your files, run the application with your new teacher:
poetry run python chat_with.py YourName your_teacher_id
- Keep knowledge entries focused and concise
- Use clear, descriptive metadata
- Organize knowledge by topics
- Include source information
- Test your knowledge base with different questions
- Refer to
aiteacher/README.mdfor internal module documentation. - This project follows Python best practices with
pre-commithooks, Poetry environments, and.envconfiguration.