Roadmap

← Back to YouLab

Implementation roadmap for YouLab’s AI tutoring platform.

Vision

A complete system where:

1. Students log into OpenWebUI, each routed to their personal Letta agent
2. All messages persisted to Honcho for long-term ToM modeling
3. Agent context adapts based on which chat/module student is in
4. Curriculum defined in markdown, hot-reloadable without redeploy
5. Background process periodically enriches agent memory from Honcho insights
6. New students smoothly onboarded with initial setup flow

---

Current Status

┌─────────────────────────────────────────────────────────────────┐
│                         Completed                                │
├─────────────────────────────────────────────────────────────────┤
│  Phase 1: HTTP Service ✓                                        │
│  Phase 2: User Identity ✓ (absorbed into Phase 1)               │
│  Phase 3: Honcho Integration ✓                                  │
│  Phase 4: Thread Context ✓                                      │
│  Phase 5: Curriculum System ✓                                   │
│  Phase 6: Background Worker ✓                                   │
└─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
                    ┌──────────────────────────┐
                    │     Next: Phase 7        │
                    └──────────────────────────┘

---

Phase Overview

Phase	Name	Status	Dependencies
1	HTTP Service	Complete	-
2	User Identity & Routing	Complete	Phase 1
3	Honcho Integration	Complete	Phase 1
4	Thread Context	Complete	Phase 1
5	Curriculum System	Complete	Phase 4
6	Background Worker	Complete	Phase 3
7	Student Onboarding	Not Started	Phase 5

Dependency Graph

Phase 1: HTTP Service (includes Phase 2)
    │
    ├── Phase 3: Honcho ──────┐
    │       │                 │
    │       └── Phase 6: Background Worker
    │
    └── Phase 4: Thread Context
            │
            └── Phase 5: Curriculum
                    │
                    └── Phase 7: Onboarding

---

Phase 1: HTTP Service (Complete)

Convert YouLab Server from a library to an HTTP service.

Deliverables

• FastAPI application on port 8100
• Health endpoint with Letta connection status
• Agent CRUD endpoints
• Synchronous chat endpoint
• SSE streaming chat endpoint
• Agent template system
• Strategy agent for RAG
• Langfuse tracing

Key Files

• src/youlab_server/server/main.py
• src/youlab_server/server/agents.py
• src/youlab_server/agents/templates.py

---

Phase 2: User Identity & Routing (Complete)

Ensure each student gets their own persistent agent.

Note: This phase was absorbed into Phase 1 during implementation.

Deliverables

• User ID extraction (__user__["id"])
• Agent creation and lookup
• Agent caching for fast lookups
• Per-user agent naming convention (youlab_{user_id}_{agent_type})

Deferred to Future Phases

• First-interaction detection (Phase 7: Onboarding)
• Course-specific memory fields (Phase 4: Thread Context)

---

Phase 3: Honcho Integration (Complete)

Persist all messages to Honcho for theory-of-mind modeling.

Deliverables

• HonchoClient with lazy initialization
• Fire-and-forget message persistence
• Integration with /chat endpoint
• Integration with /chat/stream endpoint
• Health endpoint reports Honcho status
• Graceful degradation when Honcho unavailable
• Configuration via environment variables
• Unit and integration tests

Key Files

• src/youlab_server/honcho/client.py
• src/youlab_server/config/settings.py (ServiceSettings)
• src/youlab_server/server/main.py (lifespan, endpoints)
• tests/test_honcho.py
• tests/test_server_honcho.py

What’s NOT Included (Future Work)

• Dialectic queries from Honcho (Phase 6)
• Working representation updates (Phase 6)
• ToM-informed agent behavior (Phase 6)

---

Phase 4: Thread Context (Complete)

Chat title extraction and management for thread context.

Deliverables

• Chat title extraction from OpenWebUI database (_get_chat_title)
• Chat title passed to HTTP service in requests
• Chat title stored in Honcho as message metadata
• Chat title rename capability (_set_chat_title)
• Unit tests for title operations

Key Files

• src/youlab_server/pipelines/letta_pipe.py (_get_chat_title, _set_chat_title)
• tests/test_pipe.py (TestGetChatTitle, TestSetChatTitle)

What’s NOT Included (Simplified Scope)

Original plan included complex title parsing (“Module 1 / Step 2” format), context caching, and memory block updates. These were deferred as:

• 1:1 OpenWebUI→Honcho thread mapping simplifies architecture
• Primary course uses single thread
• Title metadata already flows through system

---

Phase 5: Curriculum System (Complete)

Load course definitions from TOML files.

Deliverables

• Define curriculum in TOML with course.toml and modules/
• Parse into Pydantic schemas (CourseConfig, ModuleConfig, StepConfig)
• Hot-reload on API endpoint
• Dynamic memory block generation from schema
• HTTP endpoints for curriculum management

Key Files

• src/youlab_server/curriculum/schema.py
• src/youlab_server/curriculum/loader.py
• src/youlab_server/curriculum/blocks.py
• src/youlab_server/server/curriculum.py
• config/courses/college-essay/course.toml

---

Phase 6: Background Worker (Complete)

Query Honcho dialectic and update agent memory on schedule or manual trigger.

Deliverables

• BackgroundAgentRunner execution engine
• MemoryEnricher for external memory updates
• Audit trails in archival memory
• HTTP endpoints for manual triggers
• TOML configuration for background agents

Key Files

• src/youlab_server/background/runner.py
• src/youlab_server/memory/enricher.py
• src/youlab_server/server/background.py

---

Phase 7: Student Onboarding

Handle new student first-time experience.

Goals

• Detect new students
• Initialize agent with onboarding context
• Guide through setup flow
• Transition to Module 1

Onboarding Flow

1. Welcome message
2. Collect basic info (name, goals)
3. Explain system capabilities
4. First step setup

---

What We’re NOT Doing

Out of scope for current roadmap:

• Full user management UI (admin dashboard)
• Multi-facilitator support
• Course marketplace / multi-course
• Production deployment infrastructure
• Automated pedagogical testing
• Mobile-specific optimizations

---

Verification Plan

Automated

• Unit tests for each component
• Integration tests for message flow
• Pre-commit verification

Manual

1. Create two test users in OpenWebUI
2. Each sends messages in multiple chats
3. Verify isolation (different agents)
4. Verify continuity (same agent across sessions)
5. Check Honcho dashboard for messages
6. Trigger background process, verify updates
7. Modify curriculum, verify hot-reload
8. New user goes through onboarding

---

Related Pages

• Architecture - System design
• HTTP Service - Phase 1 implementation
• Memory System - Memory management
• Agent System - Agent templates