# Project export: pigeonhole
This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.
## Project metadata
- Hackathon: TreeHacks 2026
- Tagline: Pigeonhole is an AI TA designed for instruction, not answer delivery. It follows course rules, prompts student reasoning, and produces reviewable summaries that help instructors diagnose confusion.
- Devpost: https://devpost.com/software/pigeonhole
- GitHub: https://github.com/danielmargento/course-ta-bot.git
- Video: https://player.vimeo.com/video/1165160143?byline=0&portrait=0&title=0#t=
- Team: 2 GitHub contributor(s) β danielmargento (16 commits), annie33lii (3 commits)
## Devpost submission (written by the team)
### Inspiration
Generative AI is now a default study tool. The issue is not use vs. no use, but alignment: general-purpose chatbots do not know a courseβs syllabus, policies, or pedagogical intent, and they often optimize for answer completion rather than conceptual understanding. We built pigeonhole to make AI support instruction by design, with instructor control and learning-first interaction.
### What it does
pigeonhole is a course-aligned AI TA that provides scaffolded help rather than direct solutions. For students, it guides problem solving through questions, hints, and stepwise decomposition. After a session, it produces a structured recap (what was confusing, how understanding changed, what to review) and enables quick review through a lightweight quiz. For instructors, it offers configurable guardrails (what help is allowed, what topics are off-limits) and aggregated insight into common misconceptions and friction points.
### How we built it
We implemented a web app with distinct student and instructor workflows: Instructor configuration: course context, policy constraints, and approved hint scaffolds. Student chat: a guided dialogue loop that prioritizes questioning, partial hints, and checking student work before progressing. Learning artifacts: automatic session summaries and exportable PDFs for later study or forum posting. Analytics: aggregation of anonymized interaction signals to surface high-level confusion patterns.
### Challenges we ran into
Defining βhelpful but not too helpfulβ in a way that is consistent across topics and student behaviors. Preventing accidental answer leakage while still allowing students to make progress under time pressure. Translating open-ended chat transcripts into concise, accurate recaps without introducing new errors. Designing instructor controls that are powerful but simple enough to set up quickly.
### Accomplishments we're proud of
Built an end-to-end experience that serves both students and instructors, not just a chatbot. Implemented policy-aware scaffolding that reliably pushes for student work and reasoning before hints escalate. Produced reusable learning artifacts (recaps + PDF export) that turn chat into study material.
### What we learned
Guardrails are most effective when they are explicit, instructor-configurable, and enforced at the interaction level, not just as a disclaimer. Students respond well to structured guidance when it reduces cognitive load (first step, plan, checkpoints). Instructor trust depends on transparency, control, and clear evidence of learning alignment.
### What's next
Richer instructor tooling: assignment-specific rubrics, granular hint templates, and per-topic constraints. Stronger analytics: confusion clustering by concept, time-to-first-progress, and pre/post understanding signals. Personalized study support: adaptive review plans before exams, spaced repetition prompts, and targeted practice sets. Multimodal outputs: short personalized explanation videos based on what a student struggled with. Deeper integration: LMS and course content connections to make setup and compliance seamless.
## README (from the GitHub repository)
# π Pascal β AI Teaching Assistant
AI isn't going anywhere. Students are already using ChatGPT, Claude, and Copilot to do their homework β often getting complete solutions with zero learning. Banning AI tools doesn't work. The answer isn't prohibition; it's giving teachers control.
**Pascal** is a course-aware AI TA that puts instructors in the loop. Teachers configure exactly how much help the bot gives, what it can and can't reveal, and which materials it draws from. Students get real-time scaffolded help that builds understanding β not an answer machine.
---
## π‘ Why Pascal?
Most AI tools treat education as an afterthought. Students paste a homework problem into ChatGPT and get a full solution. They learn nothing. Teachers have no visibility or control.
Pascal flips this:
- π§βπ« **Teacher in the loop.** Instructors set the rules β help level, allowed artifacts, topic restrictions, staff notes β and the bot follows them. The teacher decides whether students get Socratic questioning, guided hints, or full tutoring. Not the AI.
- π **Integrity first.** The default is restrictive. No answers, no full code, attempt required first. Teachers opt *in* to more permissive modes when appropriate. The bot enforces academic integrity by design, not as an afterthought.
- π **Scoped to real course materials.** Pascal only knows what the teacher gives it β syllabi, lecture notes, problem sets. It doesn't hallucinate references to materials that don't exist. When general chat is enabled, it's limited to teacher-selected documents.
- π **Assignment-aware.** Each assignment can have its own help level, anchor document, staff notes, and annotated hints. When a student asks about "question 4," the bot knows exactly which document to look in.
---
## β¨ Features
### π For Instructors
- **Course creation** with join codes for student enrollment
- **Three help levels** per assignment: Strict (confirmation only), Guided (Socratic hints), Full Support (complete tutoring after effort shown)
- **Policy guardrails** β toggle final answers, full code, require-attempt-first, allowed/disallowed artifacts
- **Topic gating** β mark topics as "not yet taught," "allowed," or "warn" to prevent the bot from spoiling upcoming material
- **Staff notes** β private per-assignment instructions the bot follows but never reveals to students
- **Anchor documents** β designate one material as THE assignment doc so the bot knows where to look for question numbers
- **PDF annotations** β highlight specific passages in uploaded PDFs with private hints for the bot
- **General chat control** β disabled by default; teachers enable it and select exactly which materials (e.g. syllabus) the bot can reference
- **Course materials** β upload PDFs, text files, and markdown; extracted text is chunked and embedded for RAG retrieval
- **Usage insights** β see which assignments get the most questions, top topics, common misconceptions (LLM-summarized)
- **Announcements** β post messages visible to enrolled students
- **Roster management** β view enrolled students
- **Student view preview** β see exactly what students see
### π For Students
- **Assignment-aware chat** β select an assignment and get help scoped to that specific problem set and its materials
- **Concept check quizzes** β inline multiple-choice questions after explanations to reinforce learning (toggleable)
- **Clickable source citations** β bot responses link back to specific pages/sections of course materials
- **Save and bookmark** helpful messages during a session
- **Export to PDF** β save threads or snippets for offline review or forum sharing
- **Session history** β resume past conversations per assignment
- **Feedback** β rate responses as helpful, not helpful, or too revealing
- **LaTeX and Markdown** rendering for math-heavy courses
### βοΈ Under the Hood
- **RAG retrieval** β course materials are chunked, embedded, and searched via vector similarity so the bot references real content, not hallucinations
- **Anchor boosting** β chunks from the designated assignment document get a similarity boost and a guaranteed secondary search fallback
- **Anti-hallucination prompting** β the bot is explicitly forbidden from inventing lecture names, chapter titles, or any references not present in its provided materials
- **Per-assignment policy overrides** β each assignment can override the course-level help policy
- **Streaming responses** via SSE for real-time chat
- **Question hint matching** β the bot detects when students reference specific questions and applies instructor-provided hints
---
## 𧱠Tech Stack
- **Next.js** (App Router) + TypeScript
- **TailwindCSS**
- **Supabase** (Postgres + Auth + Storage)
- **OpenAI API** (GPT-4o-mini for chat, text-embedding-3-small for RAG)
---
## π Getting Started
1. Clone the repo
2. Copy `.env.example` to `.env.local` and fill in Supabase + OpenAI keys
3. Run migrations: `supabase db push`
4. Install dependencies: `npm install`
5. Start dev server: `npm run dev`
---
## π Project Structure
```
src/
app/
admin/ # Instructor dashboard + course config
student/ # Student dashboard + chat
api/ # API routes (chat, assignments, bot-config, etc.)
components/
admin/ # AssignmentEditor, MaterialsPanel, PdfAnnotator, etc.
assignments/ # AssignmentSelect
chat/ # ChatWindow, ChatMessage, ChatComposer
courses/ # CourseCard
layout/ # AppShell (nav)
pdf/ # ExportButton
lib/
prompt.ts # System prompt builders (full-text + RAG)
policy.ts # Guardrail logic, topic gating
embeddings.ts # Vector embedding generation
types.ts # Shared TypeScript types
supabase/
migrations/ # SQL migrations
```
## Detected evidence (automated analysis)
Indexed codebase: 83 recognized source files, 290 KB.
- CSS (language) β detected in the code
- Next.js (technology) β detected in the code
- OpenAI (technology) β detected in the code
- React (technology) β detected in the code
- SQL (language) β detected in the code
- Supabase (technology) β detected in the code
- Tailwind CSS (technology) β detected in the code
- TypeScript (language) β detected in the code
- Node.js (technology) β claimed on Devpost, not found in the code
## Codebase structure (from repository index)
### Files (89 of 89)
```
.gitignore
eslint.config.mjs
next.config.ts
package.json
postcss.config.mjs
PROJECT_STRUCTURE.md
README.md
src/app/admin/course/[id]/page.tsx
src/app/admin/courses/page.tsx
src/app/api/announcements/route.ts
src/app/api/announcements/view/route.ts
src/app/api/assignments/route.ts
src/app/api/bot-config/route.ts
src/app/api/chat/route.ts
src/app/api/concept-checks/route.ts
src/app/api/courses/route.ts
src/app/api/debug-materials/route.ts
src/app/api/enroll/route.ts
src/app/api/insights/route.ts
src/app/api/instructor-chat/route.ts
src/app/api/materials/reextract/route.ts
src/app/api/materials/route.ts
src/app/api/materials/view/route.ts
src/app/api/messages/route.ts
src/app/api/profile/route.ts
src/app/api/roster/route.ts
src/app/api/sessions/route.ts
src/app/api/signup/route.ts
src/app/globals.css
src/app/layout.tsx
src/app/login/page.tsx
src/app/page.tsx
src/app/profile/page.tsx
src/app/signup/page.tsx
src/app/student/course/[id]/history/page.tsx
src/app/student/course/[id]/page.tsx
src/app/student/courses/page.tsx
src/components/admin/AssignmentEditor.tsx
src/components/admin/ContextUploader.tsx
src/components/admin/InsightsPanel.tsx
src/components/admin/InstructorChatPanel.tsx
src/components/admin/MaterialsPanel.tsx
src/components/admin/PolicyEditor.tsx
src/components/admin/PreviewPanel.tsx
src/components/admin/RosterPanel.tsx
src/components/admin/StylePresetSelect.tsx
src/components/assignments/AssignmentSelect.tsx
src/components/chat/ChatComposer.tsx
src/components/chat/ChatMessage.tsx
src/components/chat/ChatWindow.tsx
src/components/chat/ConceptCheckCard.tsx
src/components/chat/PigeonChatBubble.tsx
src/components/chat/SavedNotesPanel.tsx
src/components/chat/SaveToggle.tsx
src/components/courses/CourseCard.tsx
src/components/courses/CourseHeader.tsx
src/components/landing/PigeonHero.tsx
src/components/layout/AppShell.tsx
src/components/pdf/ExportButton.tsx
src/config/defaultPolicy.ts
src/config/stylePresets.ts
src/hooks/useUser.ts
src/lib/analytics.ts
src/lib/auth.ts
src/lib/conceptCheck.ts
src/lib/fileParse.ts
src/lib/pdf.ts
src/lib/policy.ts
src/lib/prompt.ts
src/lib/sourceLink.ts
src/lib/supabaseClient.ts
src/lib/supabaseServer.ts
src/lib/types.ts
src/middleware.ts
supabase/.temp/cli-latest
supabase/migrations/001_initial_schema.sql
supabase/migrations/002_auth_profiles.sql
supabase/migrations/003_profile_names.sql
supabase/migrations/004_enrollments.sql
supabase/migrations/005_announcements.sql
supabase/migrations/006_course_materials.sql
supabase/migrations/007_assignment_style.sql
supabase/migrations/008_assignment_due_date.sql
supabase/migrations/009_assignment_materials.sql
supabase/migrations/010_concept_checks.sql
supabase/migrations/011_concept_check_saved.sql
supabase/migrations/012_insights_per_assignment.sql
supabase/migrations/016_anchor_and_general_chat.sql
tsconfig.json
```
### Dependencies
- package.json: @supabase/ssr@^0.8.0, @supabase/supabase-js@^2.95.3, @tailwindcss/postcss@^4, @tailwindcss/typography@^0.5.19, @types/node@^20, @types/react@^19, @types/react-dom@^19, eslint@^9, eslint-config-next@16.1.6, katex@^0.16.28, marked@^17.0.2, next@16.1.6, openai@^6.22.0, pdf-parse@^2.4.5, react@19.2.3, react-dom@19.2.3, react-markdown@^10.1.0, rehype-katex@^7.0.1, remark-gfm@^4.0.1, remark-math@^6.0.0, tailwindcss@^4, typescript@^5
### Recent commits (newest first)
- Update README with project description, features, and emojis
- Anchor documents + general chat gating + anti-hallucination prompt fixes
- LaTeX source companion for PDF uploads + fix unicode extraction
- fix concept checks: make mandatory in prompt + render markdown in explanations
- clickable source citations + restrict uploads to PDF/TXT/MD
- concept check
- fix policy-blocked messages going silent and externalize native packages
- debugging final touches
- Fix pdf-parse import to avoid test-file bug
- Switch to pdf-parse v1 for reliable server-side PDF extraction
- Per-assignment insights and general mode restrictions
- Fix PDF extraction by replacing pdf-parse with direct pdfjs-dist
- Add material extraction status and re-extract button
- final touches
- updated functionality
- course materials
- assignment feature
- Changed chatbot UI.
- updated homepage
- updated chatbot page UI, added pigeon conversation feature.
## Key source files (fetched from GitHub, selected and truncated for size)
### PROJECT_STRUCTURE.md
```markdown
# Course TA Bot β Project Structure Memo
## Overview
This is a Next.js (App Router) + TypeScript project that lets instructors create course-specific, policy-constrained AI teaching assistants. Students chat with the TA for scaffolded learning help. The app uses Supabase for persistence and OpenAI for LLM responses.
---
## Top-Level Files
| File | Purpose |
|------|---------|
| `package.json` | Dependencies and scripts (`dev`, `build`, `start`, `lint`) |
| `tsconfig.json` | TypeScript config with `@/` path alias pointing to `src/` |
| `next.config.ts` | Next.js configuration |
| `postcss.config.mjs` | PostCSS config for Tailwind |
| `eslint.config.mjs` | ESLint rules |
| `.env.local.example` | Template for required env vars (Supabase URL/key, OpenAI key) |
---
## `src/lib/` β Core Logic
| File | What it does |
|------|-------------|
| `types.ts` | All shared TypeScript interfaces: `Course`, `Assignment`, `BotConfig`, `PolicyConfig`, `Session`, `Message`, `StylePreset`, `TopicGate`, `UsageInsight`, `Feedback` |
| `supabaseClient.ts` | Browser-side Supabase client (uses `NEXT_PUBLIC_` env vars) |
| `supabaseServer.ts` | Server-side Supabase client factory for use in API route handlers |
| `policy.ts` | Guardrail logic β checks if a student message requests something disallowed (e.g. full solutions), checks topic gating, and builds a policy instruction block for the LLM system prompt |
| `prompt.ts` | Assembles the full system prompt sent to OpenAI by combining course info, teaching style, policy rules, course context, and assignment details (including staff notes and FAQ) |
| `analytics.ts` | Stub for aggregating usage insights (top topics, session/message counts) β needs real queries wired up |
| `pdf.ts` | Uses `jsPDF` to export an array of messages into a formatted PDF document |
---
## `src/config/` β Constants & Defaults
| File | What it does |
|------|-------------|
| `stylePresets.ts` | Four teaching style presets (Socratic, Direct, Debugging Coach, Exam Review) β each has a label, description, and a system prompt fragment injected into the LLM prompt |
| `defaultPolicy.ts` | Default guardrail settings: no final answers, no full code, require attempt first, 3 hint levels, allowed/disallowed artifact lists, and a default refusal message |
---
## `src/app/api/` β API Route Handlers
All routes are server-side Next.js route handlers.
| Route | Methods | What it does |
|-------|---------|-------------|
| `api/chat/route.ts` | POST | Main chat endpoint. Fetches course + config + assignment from Supabase, runs policy check, builds system prompt, streams response from OpenAI via SSE |
| `api/courses/route.ts` | GET, POST | List all courses / create a new course |
| `api/assignments/route.ts` | GET, POST | List assignments (filterable by `course_id`) / create a new assignment |
| `api/sessions/route.ts` | GET, POST | List sessions (filterable by `course_id`, `student_id`) / create a new session |
| `api/messages/route.ts` | POST | Save
[truncated β 4052 more characters]
```
### package.json
```
{
"name": "temp-next-app",
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "eslint"
},
"dependencies": {
"@supabase/ssr": "^0.8.0",
"@supabase/supabase-js": "^2.95.3",
"@tailwindcss/typography": "^0.5.19",
"katex": "^0.16.28",
"marked": "^17.0.2",
"next": "16.1.6",
"openai": "^6.22.0",
"pdf-parse": "^2.4.5",
"react": "19.2.3",
"react-dom": "19.2.3",
"react-markdown": "^10.1.0",
"rehype-katex": "^7.0.1",
"remark-gfm": "^4.0.1",
"remark-math": "^6.0.0"
},
"devDependencies": {
"@tailwindcss/postcss": "^4",
"@types/node": "^20",
"@types/react": "^19",
"@types/react-dom": "^19",
"eslint": "^9",
"eslint-config-next": "16.1.6",
"tailwindcss": "^4",
"typescript": "^5"
}
}
```
### src/app/layout.tsx
```typescript
import type { Metadata } from "next";
import { Inter, Instrument_Serif } from "next/font/google";
import "./globals.css";
import AppShell from "@/components/layout/AppShell";
const inter = Inter({
variable: "--font-inter",
subsets: ["latin"],
});
const instrumentSerif = Instrument_Serif({
variable: "--font-instrument-serif",
subsets: ["latin"],
weight: "400",
});
export const metadata: Metadata = {
title: "pigeonhole",
description: "Pascal β AI-powered assistant for course-specific, policy-constrained learning",
};
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
{children}
);
}
```
### src/app/page.tsx
```typescript
"use client";
import Link from "next/link";
import { useRouter } from "next/navigation";
import { useEffect } from "react";
import { useUser } from "@/hooks/useUser";
import PigeonHero from "@/components/landing/PigeonHero";
export default function HomePage() {
const { user, role, loading } = useUser();
const router = useRouter();
useEffect(() => {
if (!loading && user) {
const dest = role === "instructor" ? "/admin/courses" : "/student/courses";
router.replace(dest);
}
}, [loading, user, role, router]);
if (loading || user) {
return (
Loading...
);
}
return (
{/* Hero */}
{/* Envelope animations */}
pigeonhole
Meet Pascal β an AI assistant that actually helps students learn, without doing the work for them.