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/ and components/ – e.g. components/chat.tsx renders the chat UI, components/graph-view.tsx visualises the knowledge graph.
  • API routes in app/api/ expose endpoints such as /api/chats/[id]/stream/route.ts and /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

  1. Entry Point – a browser request to /api/chats/[id]/stream triggers the Next.js runtime.
  2. Route Handler – app/api/chats/[id]/stream/route.ts imports streamChat from src/core/index.ts.
  3. Core Function – streamChat calls planLesson (in src/core/plan.ts) to build a dependency map, then streams back prompts with res.write.
  4. Graph Persistence – src/core/graph.ts uses a local JSON store (db/graph.json) for the knowledge graph.
  5. UI Update – client‑side code (components/chat.tsx) consumes the stream via the browser’s fetch API, rendering messages in real time.
  6. 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

  1. Setup ``bash git clone https://github.com/moses-y/learnharness cd learnharness npm install ``
  2. Configuration Copy env.example to .env.local and set OPENAI_API_KEY or CLAUDE_API_KEY.
  3. Run ``bash npm run dev ` The web UI is at http://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; .gitignore excludes *.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.