LENA - Learning Engagement & Navigation Assistant

LENA (Learner Engagement and Needs Assistant) is a lightweight AI chatbot pilot designed to support students in online courses. It helps learners get quick, accurate answers about assignments, schedules, and university policies, reducing instructor burden in high-enrollment classes and accelerating response times so students stay on track and succeed.

LENA isn't meant to replace instructors. It handles common questions and points students toward resources, then captures any low-confidence answers for instructors to review. Every question and interaction is logged, creating a feedback loop that helps instructors spot confusion early, adjust materials, and improve the course.

Students interact through a simple chat interface that works on desktop and mobile. Instructors and course admins can view real-time insights in an analytics dashboard - tracking trends, top questions, and emerging pain points across multiple courses. The pilot version is fully containerized (FastAPI backend + Next.js frontend + Qdrant vector store) and integrates with GitHub Actions for automated testing and builds.

LENA Features

• Student view - Ask a question, get a sourced answer.
  • Each response links back to the syllabus, policy doc, or calendar event it pulled from.
  • When the bot isn't confident, it invites the student to escalate to the instructor and collects consented contact info.
• Instructor view - Review the course dashboard.
  • KPI cards highlight volume, helpfulness, and escalations.
  • Trend charts and emerging pain points call out what needs syllabus edits or follow-up announcements.
  • Course management tools let instructors/admins add or retire courses, upload documents, save link snapshots, and re-run ingestion so new materials are searchable - without touching the server filesystem.
• Admin / support staff - Watch aggregate metrics across pilots, tune ingest jobs, and plug alerts into campus systems as needed.

Screenshots

Course selection modal (choose the active course).

Chat interface (course-scoped Q and A with citations).

Course FAQ page (curated questions and answers).

Instructor landing page (demo login prompt).

Course management page (add or retire courses and manage resources).

Insights page (course trends, top questions, and escalations).

Export modal (choose course scope, components, time range, and CSV or JSON).

Demo Authentication

This repo is a pilot/demo build: it ships with demo courses and sample content, and it does not include production-ready authentication or role-based access control.

• Student experience (Chat + Course FAQ) is intentionally open in the pilot.

• Instructor tools (Insights + Course management + Data export + Ingest) are behind a demo-only login prompt to demonstrate a basic authentication flow.

• Username: demo

• Password: demo

For any production environment, the app must be connected to institutional authentication for proper security and compliance. This applies to both chat access and role-based access to Insights and Course Admin for instructors, staff, and administrators.

---

Stack at a Glance

• Frontend - Next.js (Pages router) + TypeScript + Tailwind, ships as a standalone Node server.
• Backend - FastAPI service that handles ingestion, retrieval, and the /ask workflow.
• Vector store - Qdrant (running inside Docker by default).
• CI - GitHub Actions runs backend tests and a frontend build on every push / PR.

Directory map:

backend/     FastAPI app, embeddings, ingestion tasks
frontend/    Next.js pilot UI (chat, FAQ, insights)
docker/      Compose file booting qdrant + api + web
data/        Sample markdown + calendar sources for pilots
docs/        Architecture notes and support docs
storage/     Local persisted feedback, cached runs

---

One-Click Start

The fastest way to get LENA running on your machine:

git clone https://github.com/watrall/lena.git
cd lena
./start.sh

The script checks that Docker is installed, builds the containers, and opens your browser to the chat interface in one step. After the stack is up, use the Instructors page to re-run ingestion so the demo course materials are searchable.

---

Quickstart (Docker Compose)

If you prefer more control over the startup process, or if you're on Windows, use Docker Compose directly:

git clone https://github.com/watrall/lena.git
cd lena
docker compose -f docker/docker-compose.yml up --build

Once the stack is up:

1. Seed content (optional but handy): open http://localhost:3000/instructors, log in (demo / demo), and click Re-run ingestion
2. Open the chat: http://localhost:3000 and ask "When is Assignment 1 due?"
3. Open instructor tools: http://localhost:3000/instructors (requires demo instructor login; graphs fill in after a few /ask + /feedback events)
4. When prompted, pick one of the sample courses - the backend validates the course_id on /ask, /feedback, /faq, /insights, and /escalations/request.

Optional API-only ingest:

TOKEN="$(curl -sS -X POST http://localhost:8000/instructors/login \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"demo"}' | python -c "import json,sys; print(json.load(sys.stdin)['access_token'])")"

curl -sS -X POST http://localhost:8000/ingest/run -H "Authorization: Bearer $TOKEN"

If you change course data or want a clean slate, stop the stack and remove storage/ before restarting.

---

Local Development Notes

Environment variables

Create a .env file at the repo root using .env.example as a guide (used by ./start.sh and Docker Compose). If you run the backend directly from backend/, either export the LENA_* variables in your shell or create a backend/.env file as well.

Variable	Description
NEXT_PUBLIC_API_BASE	Base URL the frontend calls (defaults to http://localhost:8000). Always include course_id in client requests.
LENA_QDRANT_HOST / LENA_QDRANT_PORT	Qdrant connection details if you run the vector store elsewhere.
LENA_DATA_DIR / LENA_STORAGE_DIR	Override data or storage paths for ingestion/output.
LENA_LLM_MODE	hf (default) to call a Hugging Face hosted model, or off for deterministic demos.
LENA_CORS_ORIGINS	Comma-separated list of allowed CORS origins (defaults to http://localhost:3000).

The backend reads any LENA_* variables via Pydantic settings, while the frontend only needs the NEXT_PUBLIC_* keys because Next.js exposes them to the browser build.

Courses & multi-course mode

The course picker reads from storage/courses.json. If the file doesn't exist, the backend seeds two sample anthropology courses so the UI always has something to display. To customize the pilot, drop in your own catalog:

[
  { "id": "anth101", "name": "ANTH 101 · Cultural Anthropology", "code": "ANTH 101", "term": "Fall 2024" },
  { "id": "anth204", "name": "ANTH 204 · Archaeology of Everyday Life", "code": "ANTH 204", "term": "Fall 2024" }
]

Escalation requests initiated from the chat are stored in storage/escalations.jsonl so instructor follow-ups can be audited or replayed. FAQ entries and review queue items now record the originating course_id, keeping per-course dashboards consistent with the student experience.

API note: Dashboard/admin endpoints (e.g. /insights, /admin/*, /ingest/run, /instructors/*) require demo instructor login in this pilot build. Course-scoped endpoints also require an explicit course_id.

Ingestion tip: organize course content under data/<course_id>/... so each vector chunk carries the proper course_id. Files placed directly under data/ inherit the first course from storage/courses.json, making it easy to pilot with a single catalog while still supporting multi-course retrieval later.

API requirements

• POST /ask - body must include question and course_id. Responses contain a question_id you'll reuse.
• POST /feedback - requires question_id, course_id, and the user's helpfulness choice (plus optional transcript context).
• GET /faq - requires course_id query params; the backend rejects empty IDs.
• GET /insights - requires instructor login + course_id query params.
• POST /escalations/request - include course_id, student_name, and student_email so instructors can follow up.
• GET /admin/review / POST /admin/promote / GET /admin/export / POST /ingest/run - require instructor login and are locked down via feature flags for the demo.

Running without Docker

Frontend:

cd frontend
npm ci
npm run dev

Backend:

cd backend
python3 -m pip install -r requirements.txt  # Requires Python 3.10+
uvicorn app.main:app --reload --port 8000

Ensure Qdrant is reachable (either docker run qdrant/qdrant or the docker compose stack) before hitting /ask.

Testing & linting

Run backend tests (which include a deterministic ingest pass) and the frontend checks before opening a PR:

python3 -m pip install -r backend/requirements.txt
pytest

cd frontend
npm ci
npm run lint

Set LENA_LLM_MODE=off locally for quick deterministic answers and to avoid downloading large Hugging Face models during test runs.

---

Docker Images

The LENA pilot publishes both backend and frontend containers for reproducibility and deployment.

Service	Image	Technology	Description
Backend		FastAPI	FastAPI backend for LENA AI - course Q&A, feedback, and analytics to support online learning.
Frontend		Next.js	Next.js frontend for LENA AI - chat Q&A and learner analytics for online course support.

Pull and Run

To pull the latest images directly from Docker Hub:

# Backend (FastAPI)
docker pull docker.io/watrall/lena-backend:latest
docker run -d -p 8000:8000 docker.io/watrall/lena-backend:latest

# Frontend (Next.js)
docker pull docker.io/watrall/lena-web:latest
docker run -d -p 3000:3000 docker.io/watrall/lena-web:latest

Set NEXT_PUBLIC_API_BASE=http://localhost:8000 (or your backend host) before starting the frontend container so the chat can reach the API.

---

CORS & Production Considerations

• When deploying the frontend separately (Netlify, Vercel, etc.), set LENA_CORS_ORIGINS in the backend environment to include the web origin (e.g., https://lena-pilot.example.edu). The Compose stack already runs both services on the same network so no extra config is required locally.
• Mattermost, Slack, LMS, or email integrations should live behind opt-in environment flags so student data only routes to approved channels. The README keeps the defaults closed off; check docs/SECURITY-NOTES.md before rolling into a large cohort.

---

Helpful Docs

• Architecture overview: docs/OVERVIEW.md
• Demo script for pilots: docs/DEMO-SCRIPT.md
• Security and guardrails: docs/SECURITY-NOTES.md
• Changelog: CHANGELOG.md

---

Provenance

This pilot was created within an institution-wide initiative focused on applying AI responsibly across the curriculum to strengthen student learning and institutional outcomes. LENA launched within Department of Anthropology online courses in the summer of 2024. Faculty, students, and administrators were paired to ensure the guardrails matched the department's pedagogical goals. After two cycles of online classes, the codebase was migrated from MSU's internal GitLab instance to GitHub to share the work openly and invite collaboration from the broader community.