Tiny AI Tutor

A small chat bot tutor, powered by generative AI.

Ask a question. Get a tailored response. Continue the conversation.

(More screenshots below.)

If you need help getting started, a set of example prompts is provided for inspiration.

---

Quick Start | Features | Screenshots | Tech Stack | Build Pipeline | Service Management | Configuration

---

Quick Start

Prerequisites

To install, build and run the application locally, you will need:

1. OpenAI API key: You must provide your own API key. Sign up or retrieve one here.

2. Node.js: Tested with node v22 and node v20 (the current and previous LTS releases, respectively, as of this writing) but any moderately recent version should work. (For help installing Node, see instructions here.)

3. Docker: Tested with the v20 engine, but should be compatible with most modern versions of Docker. (If you need help installing Docker, instructions are here.)

   • Technically Docker is not a strict requirement. See the manual build instructions below for alternatives.

All other external dependencies will installed automatically.

Launching

1. Configure with OpenAI API key:

   • Copy .env.example to .env: cp .env.example .env
   • Edit this new .env file to set OPENAI_KEY. All other parameters are optional.

2. Build and launch: Run make run to install, build and launch the cluster of services.

3. Open your browser: Visit http://localhost:8080 (or whatever value you set HOST_PORT to in your .env file) to access the site.

Notes:

• Ctrl+C to stop the service. The command make run launches the service (as a docker-compose cluster) in the foreground. Hence you can use the standard "keyboard interrupt" to stop the running process.

• If you don't want to use make (or Docker for that matter), see the manual build instructions for alternatives.

• Rather than creating an .env file, you may provide the OPENAI_KEY value as an environment variable instead. For example, you could skip step #1 and use OPENAI_KEY=sk-… make run in step #2 instead.

• There's no harm in using make run (and subsequently Ctrl+C) every time you want to start (and subsequently stop) the service, but

Troubleshooting

If you encounter issues with make run, try:

• make clean install build run to force the build sequence without relying on make's dependency resolution magic.

• make clean-more reinstall (followed by any of the above) to invoke the "nuclear option" of wiping out all installed dependencies and lockfiles to force a full, fresh install.

If you're still having problems see the manual build instructions.

Manual Build Instructions

If you don't want to use make, you can also build and run the services manually:

(cd client && npm install)
(cd server && npm install)
(docker compose up --build)

If you don't want to use docker, you also run the client and server directly on the host. See the npm run […] scripts provided in respective package.json files for details.

---

Features

• Pedagogical Orientation ¹

  The tutor follows a collaborative, constructivist approach to learning that builds new understanding from prior knowledge, driven by the student's curiosity.

  Emphasizes: (a) clear and accessible language; (b) Socratic questioning rather than rote answer-giving; (c) metacognitive coaching to help students notice and address gaps in their understanding; and (d) multiple representations and modes of interaction to support diverse learning styles.

• Authoritative Sourcing

  The tutor draws from a curated collection of trusted educational, informational and reference sources (e.g., Britannica, The National Archives, Khan Academy) to connect students with primary sources, expert explanations, and alternative perspectives.

  Notable people, places, events, and concepts are hyperlinked to an authoritative reference source.

  Images and media are provided (inline or as links) when they meaningfully enhance understanding.

• Rich Formatting

  Responses are rendered as "GitHub-flavored" Markdown (tables, task lists, code blocks, footnotes) extended with support for robust, LaTeX-style typesetting of mathematical equations, chemical formulas and other technical content. (See here and here for example.)

• Engagement Scaffolding

  Every response includes: (a) curated links for further reading on the topic or alternative presentations of the material; and (b) suggestions for follow-up activities, questions, and prompts to invite more in-depth exploration.

Screenshots and Examples

Screenshots

Transcripts

• Chat Transcript: Articles of Confederation
• Chat Transcript: Fibonacci Sequence and the Golden Ratio
• Chat Transcript: DBQ on the Great Depression

The transcripts are (PDF-format) exports of longer conversations, generated using the "Print Transcript" action as seen in the screenshots above).

---

Tech Stack

Frontend

An HTML5 / CSS3 / ES6 (JavaScript) web UI built with:

• React
• TypeScript
• Vite

supported by:

• CSS Modules
• Markdown rendering via Unified.js
• KaTeX (and mhchem) for LaTeX-style scientific typesetting

Backend

An event-based, streaming API built with:

• Node.js
• Express.js
• TypeScript

using:

• OpenAI's API "platform"
• Server-Sent Events (SSE) - i.e. Content-Type: text/event-stream

DevOps and Tooling

While the service can be built and run with just npm and vite, this repo also includes more robust operational infrastructure, using:

• Docker to containerize both the (client-side-code-hosting) web and (API-providing) app server applications for easy and standardized deployment.
• Docker Compose for multi-container orchestration (i.e. to build, launch, manage and monitor the end-to-end application as if it were a single service).
• nginx to serve the client-side artifacts needed for the web UI over HTTP.
• envalid for operator-friendly validation of run-time configuration parameters; dotenv to support configuration via an (optional) .env file in addition to conventional environment variables.
• a GNU Make-based Makefile to simplify and streamline the build/deploy pipeline and other forms of workflow automation.

Workflow Automation

The Makefile includes a number of targets to support build pipeline automation and basic service management.

Use:

• make run to launch the service in the foreground, as described in Quick Start.

• make start | stop | restart | status | logs for daemon-style service management.

• make build to generate the deployment artifacts (docker images).

• make clean to remove generated build files (or make clean-more to remove both generated and installed files).

• make help for a menu of additional build targets (example below).

All targets should trigger any necessary prerequisite actions by default.

Note that build targets may be combined, e.g., make clean build or make restart logs.

Also see Troubleshooting and Manual Build Instructions.

make help

Running make help (or just make) will generate the following help text:

Common Build Targets:

  help       show this help message
  help.all   list ALL build targets in this Makefile
  install    install 3rd-party dependencies
  build      generate docker images
  run        launch docker containers in foreground
  start      launch docker containers as a daemon
  stop       stop docker containers
  restart    stop then start
  status     check if docker containers are up
  logs       tail docker logs
  force      remove dummy files used for "manual" freshness checking
  clean      remove generated files

Quick Start:

  1. cp .env.example .env
  2. Edit .env to set OPENAI_KEY.
  3. Run make run to launch in the foreground
      or make start to launch as a daemon.
      Both targets will automatically
      install and build as needed.
  4. Visit http://localhost:8080
     (or the HOST_PORT set in .env).

Configuration

Configuration parameters may be provided as environment variables or in an .env file in project root. (See .env.example for a template.)

OPENAI_KEY is the only required parameter.

Variable	Default	Description
OPENAI_KEY	(none)	OpenAI API key (REQUIRED!)
OPENAI_MODEL	gpt-4o	OpenAI model name
SERVER_PORT	3000	app server port (ignored in Docker)
HOST_PORT	8080	web server port (only used in Docker)
NODE_DEBUG	(empty)	Add tiny-ai-tutor-server for debug logging

Footnotes

1. To a limited extent: I have none of the relevant qualifications and can't claim any particular expertise in learning science. While there may be a "nod" in that general direction, pedagogical strategies are not the primary focus of the current version of this demonstration. ↩