The Problem
Learners often struggle to understand how their current knowledge maps to a target goal. A tool that can measure, plan, and adapt lessons in real time is missing in most learning platforms. This repo provides that capability by letting an AI agent observe a user’s responses, build a dependency graph, and deliver incremental explanations.
What This Does
The application is a full‑stack Next.js app that hosts a learning harness.
- UI lives in
app/andcomponents/– e.g.components/chat.tsxrenders the chat UI,components/graph-view.tsxvisualises the knowledge graph. - API routes in
app/api/expose endpoints such as/api/chats/[id]/stream/route.tsand/api/graph/render-settings/route.ts. - Core logic resides in
src/core/index.ts, which implements the planning, reasoning, and graph‑storage layers. - Agent code in
src/agent/(e.g.image-processing/index.ts) handles domain‑specific processing like image annotation. - Electron in
electron/bundles the same code into a desktop app.
How It Is Wired
- Entry Point – a browser request to
/api/chats/[id]/streamtriggers the Next.js runtime. - Route Handler –
app/api/chats/[id]/stream/route.tsimportsstreamChatfromsrc/core/index.ts. - Core Function –
streamChatcallsplanLesson(insrc/core/plan.ts) to build a dependency map, then streams back prompts withres.write. - Graph Persistence –
src/core/graph.tsuses a local JSON store (db/graph.json) for the knowledge graph. - UI Update – client‑side code (
components/chat.tsx) consumes the stream via the browser’sfetchAPI, rendering messages in real time. - Electron – the same route files are imported by
electron/main.ts, so the desktop app shares logic with the web build.
The only functions that touch the filesystem are in src/core/graph.ts and src/agent/image-processing/index.ts, both of which read/write to ./data/. No API route writes to the database directly; all writes route through core abstractions, keeping side‑effects contained.
How To Use It
- Setup ``
bash git clone https://github.com/moses-y/learnharness cd learnharness npm install`` - Configuration Copy
env.exampleto.env.localand setOPENAI_API_KEYorCLAUDE_API_KEY. - Run ``
bash npm run dev`The web UI is athttp://localhost:3000. To build the desktop app:`bash npm run build:electron npm run start:electron``
Real‑World Use
A university instructor can embed the harness into their LMS. The instructor sets a learning goal in the UI; the agent measures baseline knowledge via a short quiz, plans a lesson, and then delivers explanations. The instructor can review the knowledge graph (components/graph-view.tsx) to see how students connect concepts over multiple sessions.
Code Health & Issues
- Measured Analysis – No linting or test coverage reports are present.
- Missing CI – Only a basic GitHub Actions workflow (
.github/workflows/ci.yml) runs tests; no deploy or security scans are defined. - Licensing – The repo contains
LICENSE, but no SPDX header in source files. - Secrets – No secrets are committed;
.gitignoreexcludes*.env.
These findings come from static inspection; no automated analysis was run.
The Bottom Line
LearnHarness offers a coherent Next.js and Electron stack for AI‑driven learning. The core logic is isolated in src/core, making it straightforward to swap out providers or extend the graph model. However, the lack of automated testing and CI security checks means a production deployment would need additional tooling. It is best suited for teams that can invest in CI pipelines and have a clear policy for handling large language model keys.