Agentic Maths

Agentic Maths is a small end-to-end demo of a kids' maths quiz chatbot built with a local LLM. The project combines a React chat interface, an Express backend, a LangChain agent, and Ollama so you can run the whole experience on your own machine with an open model such as Qwen 2.5.

The app is designed as a practical example of agentic AI patterns rather than a production-ready product. The agent is given a tutor persona, can call quiz-specific tools, streams responses back to the browser, and keeps per-session chat history and scores in memory.

5-minute quick start

If you want the shortest path to running the app locally with Ollama and Qwen:

curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5:7b

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env.local

npm install
npm run setup
npm run dev

Then open the Vite URL shown in the terminal, usually http://localhost:5173.

What this project does

• Presents a chatbot-style maths quiz UI for children.
• Uses a LangChain agent backed by ChatOllama to run the tutoring flow.
• Streams assistant output from the backend to the frontend over Server-Sent Events (SSE).
• Uses simple tools for question generation, answer evaluation, and score tracking.
• Runs fully locally when Ollama and the selected model are installed on your machine.

How it works

At a high level, the system looks like this:

1. The React frontend sends the user's message and a generated sessionId to the backend.
2. The Express backend builds the conversation context, including an in-memory chat history for that session.
3. A LangChain agent calls a local Ollama model using ChatOllama.
4. The agent can use three tools: generate_question, evaluate_answer, and track_score.
5. The backend streams the model's response back to the frontend token by token via SSE.
6. The final assistant reply is appended to in-memory history so the next turn has context.

Architecture

flowchart LR
	User[Child using chat UI] --> Frontend[React + Vite frontend]
	Frontend -->|POST /api/chat| Backend[Express backend]
	Backend -->|stream tokens via SSE| Frontend
	Backend --> Agent[LangChain maths agent]
	Agent --> Ollama[Ollama local runtime]
	Agent --> GQ[generate_question tool]
	Agent --> EA[evaluate_answer tool]
	Agent --> TS[track_score tool]
	Ollama --> Model[Qwen 2.5 model]

Loading

Tech stack

• Frontend: React, TypeScript, Vite
• Backend: Node.js, Express, TypeScript
• Agent framework: LangChain
• Local model runtime: Ollama
• Default model family: Qwen 2.5

Project structure

frontend/   React chat UI
backend/    Express API + LangChain agent + Ollama integration

Key backend pieces:

• backend/src/server.ts starts the Express server.
• backend/src/routes/chatRouter.ts handles the streaming chat endpoint.
• backend/src/agent/mathsAgent.ts creates the LangChain agent and in-memory history store.
• backend/src/agent/tools/ contains the quiz tools.
• backend/src/agent/prompts/system.ts defines the tutor persona and behaviour rules.

Key frontend pieces:

• frontend/src/hooks/useChat.ts manages chat state.
• frontend/src/services/api.ts consumes the streaming API.
• frontend/src/components/ contains the chat UI components.

Prerequisites

Before running the project, make sure you have:

• Node.js and npm installed
• Ollama installed locally
• At least one Ollama model pulled locally

Local setup with Ollama and Qwen

This project is configured to work with a local Ollama server at http://localhost:11434.

1. Install Ollama

On macOS, the Ollama download page currently offers two straightforward options:

Option A: install from the official app

1. Download the macOS installer from https://ollama.com/download/mac
2. Open the .dmg
3. Drag Ollama into Applications
4. Launch Ollama once so the local service is available

Option B: install from the command line

curl -fsSL https://ollama.com/install.sh | sh

Notes:

• The Ollama macOS download page currently states that macOS 14 Sonoma or later is required.
• If you are on Linux or Windows, use the relevant installer from https://ollama.com/download.

2. Start Ollama

If you installed the macOS app, launching the app is usually enough to start the local server.

You can verify that Ollama is available with:

ollama list

If Ollama is running correctly, that command should return a model list, even if it is empty.

3. Pull a Qwen model

The backend defaults to the qwen2.5 model family. A good starting point for local development is qwen2.5:7b.

Pull it with:

ollama pull qwen2.5:7b

You can also try other sizes depending on your hardware:

• qwen2.5:1.5b for a lighter setup
• qwen2.5:3b for a smaller but more capable option
• qwen2.5:7b for a better quality default

After pulling the model, you can sanity-check it with:

ollama run qwen2.5:7b

If the prompt opens and the model responds, Ollama is ready.

4. Configure the backend environment

The backend reads its config from environment variables.

The code-level fallback model is qwen2.5, while the provided example env file pins qwen2.5:7b, which is a clearer starting point for local development.

There is already an example file at backend/.env.example:

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:7b
PORT=3001

Create your local backend env file:

cd backend
cp .env.example .env

If you want to use a different local model tag, update OLLAMA_MODEL so it exactly matches the model you pulled. For example:

OLLAMA_MODEL=qwen2.5:3b

5. Install dependencies

Install backend dependencies:

cd backend
npm install

Install frontend dependencies:

cd frontend
npm install

Running the project

You need two terminals: one for the backend and one for the frontend.

If you prefer running everything from the repository root, use the convenience scripts described below.

Start both apps from the repo root

npm install
npm run setup
npm run dev

This starts:

• the backend in watch mode on http://localhost:3001
• the frontend dev server on http://localhost:5173

Start the backend

cd backend
npm run dev

The backend starts on:

http://localhost:3001

By default it expects:

• OLLAMA_BASE_URL=http://localhost:11434
• OLLAMA_MODEL=qwen2.5 if no env file is set, or the explicit model tag from backend/.env if you configured one

Start the frontend

In a second terminal:

cd frontend
npm run dev

Vite will print the local URL, which is typically:

http://localhost:5173

The frontend defaults to calling the backend at http://localhost:3001.

If your backend is running elsewhere, copy the example frontend env file and point it at the correct API base URL:

cd frontend
cp .env.example .env.local

Then edit the value if needed:

VITE_API_URL=http://localhost:3001

Using the app

1. Open the frontend URL in your browser.
2. Send a message such as Hi, Start quiz, or I'm ready.
3. The assistant should respond as the maths tutor and begin the quiz flow.
4. Answers and score are tracked within the current backend process.

Available scripts

Repository root:

• npm run setup installs dependencies for both backend and frontend
• npm run dev starts backend and frontend together
• npm run dev:backend starts only the backend
• npm run dev:frontend starts only the frontend
• npm run build builds backend and frontend
• npm run test runs backend and frontend tests
• npm run lint runs the frontend linter

Backend:

• npm run dev runs the backend in watch mode using tsx
• npm run build compiles TypeScript
• npm run start runs the compiled backend
• npm run test runs backend tests

Frontend:

• npm run dev starts the Vite dev server
• npm run build builds the frontend
• npm run preview serves the production build locally
• npm run test runs frontend tests
• npm run lint runs ESLint

Current limitations

This repo is intentionally simple. A few things to know:

• Chat history is stored in memory, so it is lost when the backend restarts.
• Score tracking is also stored in memory per session.
• The question generation tool currently returns structured tool data rather than a full question bank or persistent quiz engine.
• This is a demo of local agent orchestration, not a hardened tutoring product.

Production notes

If you wanted to take this beyond a demo, the main gaps to address are:

• Persistence: move chat history and score tracking out of in-memory maps into a database or durable store.
• Session management: replace the generated client-side session ID with proper user or anonymous session handling.
• Observability: add structured logging, request tracing, and monitoring around the streaming endpoint and agent/tool calls.
• Rate limiting and abuse protection: protect the chat endpoint from spam and excessive local model usage.
• Safety hardening: do not rely only on the system prompt for behavioural constraints; add server-side validation and moderation policy handling.
• Deployment shape: run the frontend as static assets, host the backend separately, and ensure the Ollama host is reachable only where intended.

Troubleshooting

Ollama connection errors

If the backend cannot reach Ollama:

• Make sure the Ollama app is running
• Check that OLLAMA_BASE_URL matches your local Ollama address
• Verify Ollama is responding with ollama list

Model not found

If you see errors about a missing model:

• Run ollama list to see what is installed
• Pull the missing model with ollama pull <model-name>
• Make sure OLLAMA_MODEL exactly matches the installed tag

Example:

ollama pull qwen2.5:7b

OLLAMA_MODEL=qwen2.5:7b

Frontend cannot reach backend

If the browser UI loads but messages fail:

• Confirm the backend is running on port 3001
• Check VITE_API_URL if you changed ports or hostnames
• Confirm CORS and network access are not being blocked locally

Responses reset after restart

That is expected with the current implementation. Both chat history and score state are held in memory only.