AI Educational Assistant Agent

Overview

This repository is a demo MVP of an automated educational assistant that:

• Loads and validates student performance data from a JSON file.
• Computes deterministic, explainable metrics (averages, risk signals, strengths/focus areas).
• Uses an OpenAI model (via LangChain) to generate structured coaching insights.
• Renders those insights into messages (student-facing and teacher-facing).
• Persists an audit trail to SQLite and optional “email output” files on disk.
• Maintains compact “memory” JSON files so guidance can stay consistent across runs.

It is designed for workshop/demo workflows where you want a clear separation between:

• A Deno backend that owns secrets, scheduling, storage, and LLM calls.
• A Next.js UI (run with Bun) that provides a chat interface and proxies requests to Deno.

Additional reference material is in docs/ (API contract and examples).

What’s In This Repo

• Deno agent backend (src/): scheduled analysis pipeline + HTTP API server.
• Chat UI (apps/chat-ui/): Next.js App Router UI with API route proxies.
• Shared contracts (packages/shared-types/): TypeScript interfaces + Zod schemas used by both UI and API.
• Demo data: students.json (student records) and teacher_rules.json (optional teacher preferences).
• Scripts: scripts/dev.sh runs API + UI together.
• Tests: tests/ validates analyzer, validator, and insight parsing.

Quick Start (Local)

1. Configure the Deno backend:

cp .env.example .env
# edit .env and set OPENAI_API_KEY

2. Start the Deno API server (terminal 1):

deno task serve

3. Start the UI (terminal 2):

cd apps/chat-ui
bun install
echo 'DENO_AGENT_URL=http://localhost:8000' > .env.local
bun run dev

4. Open the UI at http://localhost:3000.

If you prefer, run both services together:

./scripts/dev.sh

Requirements

• Deno 1.40 or higher (backend + tests)
• Bun (recommended) or Node.js (frontend tooling/runtime for Next.js)
• OpenAI API key (any ChatCompletions-capable model supported by @langchain/openai)
• Filesystem permissions for:
  • SQLite database path (HISTORY_DB_PATH, default data/history.db)
  • memory directory (MEMORY_DIR, default memory/)
  • optional email output directory (EMAIL_OUT_DIR)

Notes:

• The SQLite dependency uses Deno’s FFI; the provided Deno tasks include --allow-ffi.
• The provided tasks set DENO_DIR=.deno_dir so Deno caches (including FFI artifacts) live inside the repo for easier demos.

Installation

# Clone repository
git clone <repository-url>
cd ai-education-agent

# Configure environment
cp .env.example .env
# Edit .env with your OpenAI API key and settings

Configuration

Required environment variables in .env:

• OPENAI_API_KEY - OpenAI API authentication key

Optional configuration:

• OpenAI / model:
  • OPENAI_MODEL - model name (default: gpt-4)
  • OPENAI_BASE_URL - optional base URL for OpenAI-compatible providers
  • OPENAI_PRICE_INPUT_PER_1K / OPENAI_PRICE_OUTPUT_PER_1K - optional pricing values used to compute usage.costUsd for chat responses
• Data inputs:
  • STUDENTS_JSON_PATH - student data file path (default: students.json)
  • TEACHER_RULES_PATH - optional teacher preferences JSON path (default: teacher_rules.json if set)
• Persistence:
  • HISTORY_DB_PATH - SQLite history database path (default: data/history.db)
  • MEMORY_DIR - directory for memory files (default: memory)
  • MEMORY_HISTORY_LIMIT - number of memory history entries retained (default: 5)
  • EMAIL_OUT_DIR - directory for saving “email output” files (if empty, emails are only logged)
• Scheduler:
  • SCHEDULE_CRON - cron expression (takes precedence if set)
  • SCHEDULE_INTERVAL_MIN - interval fallback in minutes (default: 30)
• Logging:
  • LOG_LEVEL - debug | info | warn | error (default: info)
• API server:
  • API_HOST - host (default: 0.0.0.0)
  • API_PORT - port (default: 8000)
  • API_CORS_ORIGIN - * or comma-separated origin allowlist (default: *)

Frontend configuration:

• The Next.js UI reads DENO_AGENT_URL from apps/chat-ui/.env.local (or process env) and proxies all browser traffic through /api/*.

Student Data Format

JSON array with required fields per student:

{
  "id": "S001",
  "name": "Student Name",
  "email": "student@example.com",
  "grades": [{"subject": "Math", "score": 85}],
  "participationScore": 7,
  "assignmentCompletionRate": 90,
  "teacherNotes": "Notes",
  "performanceTrend": "improving",
  "lastAssessmentDate": "2024-09-01"
}

Validation rules (enforced by src/validator.ts):

• grades[].score must be 0..100
• participationScore must be 1..10
• assignmentCompletionRate must be 0..100
• performanceTrend must be improving | stable | declining
• email must match a basic email pattern
• lastAssessmentDate must be parseable as a date

IDs matter:

• The UI uses /v1/students to populate the student dropdown, and the selected studentId is sent to chat requests.
• Ensure your student IDs in students.json match what you expect to use in chat (e.g. S001, S002, ...).

Execution

deno task start

This runs the scheduled “tool-first” analysis pipeline (src/run_with_tool.ts):

• Performs a tool-based validation pass over the raw student JSON.
• Analyzes all valid students.
• Generates insights and persists history/memory outputs.
• Runs immediately once on startup, then repeats on the configured cron/interval.

Terminate with Control‑C.

API Server

Run the Deno HTTP API (chat + analysis triggers):

deno task serve

API documentation is in docs/api-contract.md (includes /v1/config and /v1/students for safe runtime settings and student lists).

The server is a lightweight Deno HTTP service built on Deno.serve. It acts as the boundary between the UI and the analysis pipeline, enforcing role rules, attaching memory summaries, and returning only safe configuration values. Chat requests are handled synchronously, while analysis runs are triggered on-demand through /v1/analyze without interrupting the UI.

Requests and responses are JSON-first and include consistent error shapes so the UI can surface clear messages. CORS handling is configurable via API_CORS_ORIGIN, and the service loads configuration once on startup to keep request handling fast and deterministic.

API Endpoints (Summary)

This summary lists the high-level API surface area used by the UI and operational tooling:

• GET /health - health check for the Deno service.
• POST /v1/chat - role-based chat responses (student/teacher/admin).
• POST /v1/analyze - trigger a full analysis run.
• GET /v1/history - recent analysis run history.
• GET /v1/students - student list (id + name + email).
• GET /v1/students/{id} - student memory + latest insights.
• GET /v1/config - safe runtime config values for the UI.

Responses are designed to be safe for client display, omitting secrets while keeping operational context such as schedule cadence and model name.

Side note: what /v1/ means
The /v1/* prefix is API versioning. It marks “version 1” of the Deno backend’s HTTP contract (e.g. POST /v1/chat, GET /v1/config). Versioning makes it possible to introduce a future /v2/* with breaking changes while keeping /v1/* stable for existing clients. In this repo, the browser usually calls Next.js proxy routes under /api/*, and those server routes forward requests to the Deno backend’s /v1/* endpoints.

API Endpoints (Behavior Details)

POST /v1/chat

• Validates the basic payload shape server-side (role + message + user id).
• Applies role constraints:
  • admin: system-only; studentId is rejected.
  • teacher: requires studentId and loads the student’s memory summary.
  • student: uses studentId (or falls back to userId) to resolve the student profile and load memory.
• Uses dedicated role prompts (student/teacher/admin) in src/chat_agent.ts.
• Returns { reply, memoryUpdated, usage? } where usage is extracted from LangChain metadata when available.

POST /v1/analyze

• Triggers a single run of the analysis pipeline via runOnce(...) from src/run_with_tool.ts.
• Rejects “student-only” scopes for now (only scope: all is supported).
• Includes a simple in-memory “running” guard to avoid overlapping runs.

GET /v1/history

• Returns recent run metadata from SQLite (runs table), newest first.
• Use ?limit= to control the number of entries (default 25).

GET /v1/students

• Loads students.json, validates records, and returns a safe index: { id, name, email }.
• Grades and detailed performance data are intentionally not sent to the UI.

GET /v1/students/{id}

• Returns the student’s memory file (if present) and the latest stored insights from SQLite.
• Useful for debugging what the last run produced and what the agent will remember.

Chat UI (Next.js + Bun)

From a separate terminal:

cd apps/chat-ui
bun install
bun run dev

Set DENO_AGENT_URL in apps/chat-ui/.env.local to point at the Deno API (default http://localhost:8000).

To launch both services together, use:

./scripts/dev.sh

The UI uses the Next.js App Router and ships API route proxies (apps/chat-ui/app/api/*) so the browser never calls the Deno server directly. This keeps the dev workflow simple and avoids CORS issues while still letting you deploy the UI separately if needed.

The UI includes:

• Role toggle (student/teacher/admin) with student selector.
• Smart prompts for each role.
• Live agent config panel (from /v1/config).
• Token usage and cost summary per session (from /v1/chat response metadata).
• Scrollable chat window with auto-scroll on new responses.

Student selection is driven by /v1/students, so the UI can always address learners by name and avoid ambiguous IDs. The config panel surfaces runtime values like model, schedule, memory limits, and history path to help you validate that the backend is running with the expected settings.

Smart prompts are scoped to the active role and act as quick-starts for common questions. For example, teacher prompts are oriented around coaching plans and classroom strategies, while admin prompts request system status and run health.

UI Request Flow

The UI never calls the Deno server from the browser. Instead:

• Browser → Next.js server: POST /api/chat, GET /api/students, GET /api/config
• Next.js server → Deno: forwards the request to DENO_AGENT_URL (default http://localhost:8000)

This keeps API keys and Deno-only concerns (permissions, file I/O, SQLite) on the backend side.

How Deno and Bun Work Together

This project intentionally splits responsibilities between two runtimes:

• Deno runs the agent backend. It owns environment loading, data validation, scheduled analysis, memory persistence, and all OpenAI/LangChain calls. Deno is used here because it provides a secure permission model and a standard runtime for the existing TypeScript agent pipeline.
• Bun runs the Next.js UI. It handles the client-side interface, API route proxies, and fast development tooling for React. Bun is used because it starts Next.js quickly and provides a modern JS runtime for the web frontend.

The two runtimes communicate over HTTP. The Next.js API routes (apps/chat-ui/app/api/*) act as a local proxy layer:

• The browser sends requests to the Next.js server (Bun).
• The Next.js route handler forwards the request to the Deno API (/v1/chat, /v1/config, /v1/students).
• The Deno server responds with JSON, which is returned to the browser unchanged.

This proxy pattern keeps the UI decoupled from the backen