AI Tutors That Know Every Student

1import { Sonzai } from "sonzai";
2
3const client = new Sonzai(); // uses SONZAI_API_KEY env
4
5// Idempotent — same name always maps to the same agent
6// Create the AI tutor with personality and goals
7const tutor = await client.agents.create({
8  name: "Professor Ada",
9  bio: "A patient CS tutor who adapts to each student",
10  gender: "female",
11  personalityPrompt: "You are a patient computer science tutor...",
12  primaryTraits: ["patient", "encouraging", "analytical"],
13  big5: {
14    openness: 90,
15    conscientiousness: 85,
16    extraversion: 60,
17    agreeableness: 95,
18    neuroticism: 15,
19  },
20  trueInterests: ["algorithms", "teaching", "visual learning"],
21  speechPatterns: ["uses analogies", "asks guiding questions"],
22  initialGoals: [{
23    type: "skill_mastery",
24    title: "Help students master CS fundamentals",
25    description: "Guide each student through core CS concepts",
26    priority: 2,
27  }],
28  toolCapabilities: { webSearch: true, rememberName: true },
29});
30
31// Chat by name: agent: "Professor Ada" — no UUID needed

1// Student asks a question — Ada remembers their history
2const response = await client.agents.chat({
3  agent: "Professor Ada",
4  messages: [{ role: "user", content: "Can you explain recursion again?" }],
5  userId: "student-456",
6  sessionId: "lesson-12",
7});
8
9console.log(response.content);
10// "I remember you had trouble with this last Thursday!
11//  Let me try a different approach..."
12
13// Search what Ada remembers about this student
14const memories = await client.agents.memory.search("Professor Ada", {
15  query: "recursion understanding",
16  userId: "student-456",
17  limit: 10,
18});
19
20// Get the full learning timeline
21const timeline = await client.agents.memory.timeline("Professor Ada", {
22  userId: "student-456",
23});
24
25// List specific facts Ada has learned
26const facts = await client.agents.memory.listFacts("Professor Ada", {
27  userId: "student-456",
28  category: "preference",
29});

1// Create a learning goal for a specific student
2const goal = await client.agents.createGoal("Professor Ada", {
3  title: "Master recursion fundamentals",
4  description: "Understand base cases, recursive calls, and stack behavior",
5  type: "skill_mastery",
6  priority: 2, // 0=low, 1=medium, 2=high
7  userId: "student-456",
8  relatedTraits: ["analytical", "persistent"],
9});
10
11// Read all goals for this student
12const goals = await client.agents.getGoals("Professor Ada", {
13  userId: "student-456",
14});
15
16// goals.goals → [{
17//   goalId: "g-abc123",
18//   title: "Master recursion fundamentals",
19//   status: "in_progress",
20//   priority: 2,
21//   type: "skill_mastery",
22// }, ...]
23
24// Update goal when student makes progress
25await client.agents.updateGoal("Professor Ada", goal.goalId, {
26  userId: "student-456",
27  status: "achieved",
28});
29
30// Delete a goal that's no longer relevant
31await client.agents.deleteGoal("Professor Ada", goal.goalId, {
32  userId: "student-456",
33});

1// Read the relationship between Ada and this student
2const relationships = await client.agents.getRelationships("Professor Ada", {
3  userId: "student-456",
4});
5// → { trust: 0.82, rapport: 0.76, familiarity: 0.91, ... }
6
7// Read Ada's current mood toward this student
8const mood = await client.agents.getMood("Professor Ada", {
9  userId: "student-456",
10});
11// → { dominant: "engaged", valence: 0.7, arousal: 0.5, ... }
12
13// Read Ada's personality profile (evolves over time)
14const personality = await client.agents.personality.get("Professor Ada", {
15  historyLimit: 50,
16});
17// → { profile: { big5: { openness: 90, ... }, ... }, deltaHistory: [...] }
18
19// Get the knowledge constellation — entities and connections
20const constellation = await client.agents.getConstellation("Professor Ada", {
21  userId: "student-456",
22});
23// → { entities: [...], relationships: [...] }
24// Maps topics, students, and concepts as a graph
25
26// Read Ada's diary entries (internal reflections)
27const diary = await client.agents.getDiary("Professor Ada", {
28  userId: "student-456",
29});

1// Assign a learning resource to the student
2const item = await client.agents.inventory.update("Professor Ada", "student-456", {
3  action: "add",
4  item_type: "exercise",
5  description: "Big-O Practice Set",
6  properties: { questions: 20, difficulty: "beginner", topic: "complexity" },
7});
8
9// Query what resources this student has
10const inventory = await client.agents.inventory.query("Professor Ada", "student-456", {
11  mode: "list",
12});
13// → { items: [{ factId: "f-xyz", itemLabel: "Big-O Practice Set", ... }], totalItems: 3 }
14
15// Query with aggregation — how many exercises completed?
16const stats = await client.agents.inventory.query("Professor Ada", "student-456", {
17  mode: "aggregate",
18  item_type: "exercise",
19  aggregations: "count",
20  group_by: "difficulty",
21});
22
23// Batch import a full curriculum
24await client.agents.inventory.batchImport("Professor Ada", "student-456", {
25  items: [
26    { item_type: "resource", description: "Recursion Cheat Sheet", properties: { format: "pdf" } },
27    { item_type: "tool", description: "Sorting Visualizer", properties: { interactive: true } },
28    { item_type: "exercise", description: "Tree Traversal Problems", properties: { questions: 15 } },
29  ],
30});