# Teaching Loop — Technical Specification & Case Study

> Human-in-the-Loop (HITL) agentic tutoring platform enforcing active recall and Socratic dialogue with real-time teacher oversight. Built with FastAPI, ChromaDB vector retrieval, and a multi-page Streamlit instructor console.

- **Status:** Active // Classroom Staging
- **Repository:** https://github.com/asimansari-git/teaching-loop
- **HTML Case Study:** https://asimansari.com/projects/teaching-loop.html
- **Canonical Domain:** https://teaching-loop.asimansari.com

---

## 1. Problem & Three-Way Interaction Loop

Generic conversational chatbots in education suffer from two fatal flaws: they either hallucinate answers outside approved course syllabi, or provide answers directly, depriving students of active recall. Worse, teachers are left blind to where students are struggling.

### The Three-Way Teaching Loop Architecture
```
                   ┌───────────────────────────┐
                   │    Human Teacher / TA     │
                   └─────────────┬─────────────┘
                                 │ Live Interruption & Direction
                                 ▼
┌──────────────────┐    Feedback & Guardrails    ┌──────────────────┐
│  Student Sandbox │ ◄─────────────────────────► │  Socratic Agent  │
│  (Chat Client)   │                             │  (FastAPI Backend│
└──────────────────┘                             └────────┬─────────┘
                                                          │ ChromaDB RAG
                                                          ▼
                                                 ┌──────────────────┐
                                                 │ Verified Syllabus│
                                                 │ Knowledge Store  │
                                                 └──────────────────┘
```

---

## 2. Core Capabilities

1. **Active Real-Time Teacher Interruption:** The teacher dashboard monitors active student dialogues in real time. If a student forms a misconception, the teacher can instantly pause the AI session and take over the terminal.
2. **Dynamic Live Prompt Steering:** Instructors can inject guidance into the AI's system prompt mid-conversation (e.g., `"Hint at dynamic programming without revealing the recurrence relation"`).
3. **Automated Deficit Reporting:** Tracks student query confusion markers and produces automated summaries identifying exactly which syllabus topics require class-wide review.
4. **Verified Syllabus Gating:** Syllabus chunks must be explicitly approved by an educator before ingestion into the ChromaDB vector collection.

---

## 3. Technical Stack & Deployment

- **Backend:** Python 3.12, FastAPI, Pydantic v2 schemas.
- **Retrieval Engine:** ChromaDB dense vector store with cosine distance indexing.
- **Instructor Dashboard:** Streamlit multi-page interface with real-time session introspection and chunk moderation.
- **Storage Layer:** MongoDB (Conversation history & transcripts) + PostgreSQL (User authentication & role-based access).