Backend

FastAPI backend for the InteractLLM frontend.

LLM logic and inference for chat LLM and feedback LLMs (immediate and general feedback). Chat LLM has a bunch of lesson templates and prompt templates (see overview below). LLM inference is setup to run via OpenAI-compatiable APIs for vLLM, Ollama and Anthropic (see LLM Hosting Setup).

🌟 Overview

app/main.py is where the API logic is. The table below gives an overview of the app folder; deeper write-ups for individual subfolders live in their own README.md, linked in the "More Info" column.

📁 Folder	Description	More Info
api	Request entry and exit points for the backend.
data	Lesson definitions and prompt templates.
models	Data shapes: chat and feedback payloads, lesson and session config, and the prompt builders for ChatModel and FeedbackModel.	README.md
services	Runtime logic: chat and feedback generation, game mechanics, and session management.	README.md

🛠️ Technical Requirements

The code was developed and run on Python 3.12.3 on a macOS (26.5.1), but is currently served on a Linux server.

The project also requires:

Tool	Installation
make	Installed via Homebrew
uv	Installed through this project's makefile (see Usage)

Project Setup

After having installed make, get started by:

make add-uv
make install

This installs uv and the project files onto your computer (omit first step if you have uv already)

LLM Hosting Setup

To setup up LLM providers, please refer to docs/hosting_setup.md.

🚀 Run the Server

Once you have followed the Project setup and the LLM Hosting setup, with your .env.local and .env.prod in place, you can run:

make dev   # runs locally with .env.local
make prod  # runs locally with .env.prod

Both commands run a local API that is not exposed to the internet. This is intentional: the frontend and backend share a server, and external traffic is handled at the infrastructure layer. The only difference between make dev and make prod is whether you are running with .env.local or .env.prod. Local dev also has it setup so that the API updates when you make file changes (useful for testing).