AI Teacher Chat

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.

---

Project Structure

aiteacher-demo/
├── scripts/         # Script entry points (preload, chat launcher)
├── tests/           # Unit tests
├── aiteacher_demo/  # Main application code
├── .env.sample      # Environment variable template
├── README.md

---

🚀 Quickstart

1. Clone the Repository

git clone git@github.com:compasspathways/aiteacher-demo.git
cd aiteacher-demo
python3 -m venv venv-aiteacher
source venv-aiteacher/bin/activate

2. Set Up Environment Variables

Create your .env file by copying the template:

cp .env.sample .env

Edit the .env file to configure environment-specific variables (API keys, paths, etc.).

---

Install Dependencies

Prerequisites

• Python 3.10+
• poetry

Install with 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.3

---

Running the Application

1. Before starting

Run preload.py once to download models

poetry run python scripts/preload.py

Relax, it will take a couple of minutes :)

2. Launch the Chat Demo

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

Customizing the Knowledge Base

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

Best Practices

• Keep knowledge entries focused and concise
• Use clear, descriptive metadata
• Organize knowledge by topics
• Include source information
• Test your knowledge base with different questions

---

📄 Additional Notes

• Refer to aiteacher/README.md for internal module documentation.
• This project follows Python best practices with pre-commit hooks, Poetry environments, and .env configuration.