AI-assisted analytic assessment that keeps the teacher's judgement central.
Marking open-response exams — essays, long written answers — means judging each answer against several criteria, scoring it fairly, and writing feedback a student can actually use. For a whole class that is slow, and staying consistent across dozens of answers is hard.
Assessment Suite helps you do it one aspect at a time, with AI assistance. Claude reads each answer, proposes a score for each aspect with the evidence quoted from the student's own words, and drafts a correction and a concrete next step. You confirm, adjust, or reject every judgement — the AI never decides a grade.
The assessment rules are not hidden in code: they live in plain-text methodology documents you can read and edit, so every score traces back to a written rule. Under the hood it is two Model Context Protocol servers that run inside Claude Desktop, built for Swedish upper-secondary and higher education.
Most of what Assessment Suite "knows" is not in its code. The assessment logic — what to look at, how to interpret it, what counts as evidence, how to phrase feedback — lives in plain-markdown methodology documents. The AI reads those documents and follows them; the MCP tools only move data (read a file, write a file, track progress) and contain no assessment logic of their own.
Three consequences follow, and they are the point of the design:
- Transparent. Every assessment step traces back to a written rule you can read. No hidden model is deciding grades — the reasoning is in the methodology and in the cited evidence from the student's own answer.
- Auditable. Because the logic is text rather than opaque code, a colleague, a researcher, or a reviewing authority can inspect exactly how an assessment was reached.
- Yours to adapt. When you set up a project, the methodology is copied into your project folder as editable markdown. You can read it, question it, and change it to fit your subject and your professional judgement — the system's "brain" is not locked away.
This is also why the teacher stays in control by construction: the AI has no independent assessment opinion to impose. It facilitates a methodology that you own, and the teacher decides.
These tools share one philosophy — teacher-led: scaffolding, not automation — and one design: MCP servers (and one pipeline) that run locally over plain-Markdown workspaces, each locked to a folder with no network service of their own. They are split along a deliberate data boundary: the teaching side never holds student personal data, and the assessment side keeps student work walled off in its own workspace.
| Tool | Role | Side |
|---|---|---|
| edusafe-pipeline | Anonymise Swedish classroom recordings and transcripts offline (names → pseudonyms) before anything is shared or reused. | Data-safety gate |
| Teaching Suite | Plan lessons, capture ideas, and reflect across lesson, course, and profession cycles. | Teaching — course workspace, no student PII |
| QuestionForge | Author exam questions from what was actually taught and export them to QTI for Inspera. Belongs to the teaching side by data zone (course material, no student data) but runs fully on its own — Teaching Suite is not required. | Teaching — course workspace, no student PII |
| Assessment Suite | Assess open-response answers aspect by aspect, with cited evidence and feedback — the teacher deciding every judgement. | Assessment — separate workspace, student data stays here |
How they fit together over one teaching cycle:
edusafe-pipeline anonymise recordings/transcripts (offline, names → pseudonyms)
│
▼
Teaching Suite plan lessons, capture ideas, reflect
│
▼
QuestionForge author exam questions from what was taught
│
▼
Inspera / QTI LMS exam delivered and sat
│
▼
Assessment Suite assess answers; reports and formative feedback
│ (student work stays in this workspace)
▼
Teaching Suite only teacher insights flow back — by design, no student data
(aggregate_logs unifies the timeline)
Your folders, your files. Everything every tool writes is plain Markdown in your
own Nextcloud workspace — no database, no lock-in. The files are the source of truth
and stay readable on their own, with or without the tools. The teaching side and the
assessment side are deliberately separate folders, so student work never lands in the
course workspace; only anonymised insights about teaching flow from Assessment Suite
back to Teaching Suite. Point an Obsidian vault at a workspace (one per side, to keep the
data boundary intact) and your Markdown becomes a browsable, linkable web of your
practice — richer still where a tool writes [[wikilinks]] and #tags, as Teaching
Suite does. Sync the folders — for example via Nextcloud — and they follow you across
machines.
All tools are licensed under PolyForm Noncommercial 1.0.0.
You are reading the Assessment Suite README — see also Teaching Suite and QuestionForge.
Assessment Suite serves three audiences. Pick the door that fits — they need different things.
The tool helps you assess open-response exams aspect by aspect, with AI assistance, while you make every decision. Claude proposes a score and a justification grounded in the student's own words; you confirm, adjust, or reject it. The output is the kind students rarely receive: per-aspect scoring with cited evidence, error corrections, and a concrete "next step" for each question.
You do not install this yourself. It runs on a computer set up with Claude Desktop, Python and Node.js — that part is a technical job. Ask a developer or IT colleague to set it up (point them at the developer door), then start here:
- docs/TEACHER_GUIDE.md — how to work with Claude through an assessment session
- docs/WORKFLOW-INTEGRATION.md — what each phase produces
- FAQ.md — common questions
A hosted demo and screenshots are planned but not yet available — see ROADMAP.md.
The interesting part of this project is its methodology, not its plumbing. The pipeline is deliberately structured as a validity argument — separating scoring, synthesis, extrapolation, and decision so that each inference is explicit and auditable rather than collapsed into one opaque judgement. The methodology engages with assessment-validity work (Kane, Moss, Messick) and formative-feedback research (Sadler, Black & Wiliam, Hattie & Timperley, Lundahl; Hirsh for the Swedish context).
The theoretical layer is under active development — it is a working framework, not a finished claim, and the methodology documents are explicit about where the grounding is still being built. Engagement and critique are welcome.
- methodology/ — the assessment framework (start with
pedagogical/00_foundation.md) - docs/decisions/ — architecture decision records, including why the phases are separated
- SECURITY.md — data-protection posture (GDPR / AI Act / third-country transfer)
You can clone, install and run Assessment Suite end-to-end in roughly ten minutes on a recent macOS or Linux machine.
- Install: docs/SETUP_GUIDE.md — clone, build the TypeScript server, install the Python server, configure Claude Desktop
- Try it on sample data: examples/ — a runnable mini-project with fabricated data, no real-student files
- Understand the architecture: docs/decisions/ — the hybrid Python/TypeScript split, workspace lockdown, and other key choices
It is built as two MCP servers — a TypeScript server for text analysis and assessment, and a Python server for file processing and reports.
Assessment moves through numbered phases, deliberately separated so that each inference is explicit and auditable rather than collapsed into a single judgement:
- Phases 1–2 — Prepare: discover the exam files and convert PDFs to markdown.
- Phase 4 — Rubric: design or confirm a rubric with named aspects.
- Phase 5 — Extract: gather each student's answers, organised per question.
- Phase 6 — Assess: the core step — per-aspect scoring with cited evidence and a concrete next step, confirmed by the teacher.
- Phases 7–8 — Reports: compile per-student reports and class-level quantitative summaries.
- Phases 9–14 — Synthesis to feedback: synthesise each student's profile, map it to the course criteria, and produce grade decisions and student-facing feedback.
The separation mirrors a validity argument: scoring → synthesis → extrapolation → decision, each step warranted on its own rather than read directly off a single answer. The full pipeline is described in docs/WORKFLOW-INTEGRATION.md; the reasoning behind each phase lives in methodology/.
Assessment Suite is alpha software for supervised use — suitable for pilot work where a teacher reviews every result, not for unsupervised or high-stakes grading.
- Phases 1–8 (the core) are the most developed: the pipeline from PDFs through assessment to quantitative summaries.
- Phases 9–14 (synthesis and feedback) are functional but less theoretically grounded than the core assessment step; their methodology is under active development.
- The theoretical framework as a whole is a work in progress — the methodology documents are explicit about where the grounding is still being built.
- It has been used in real assessment work in Swedish upper-secondary and higher education, always with teacher review.
Per-student / lab-report mode is experimental and not yet supported in this version — use the standard per-question flow.
Versions and roadmap: see ROADMAP.md.
Student answers are personal data, so be deliberate about how they flow.
- Local file operations, but not local-only AI. File processing runs on your machine, but the AI-assisted phases send the student answers they reason over to Anthropic's API through Claude Desktop. This is not a self-contained, offline tool — understand this before loading real student data.
- Workspace lockdown. The MCP tools can only read and write inside a required
--workspacedirectory, with symlink-escape and dangerous-path guards. - You stay the decision-maker. The teacher confirms every judgement; the tool never sets a grade autonomously.
- Anonymise first. Assessment Suite has no built-in PII detection — strip names and identifiers from answer files before loading them. (For classroom recordings and transcripts, edusafe-pipeline does this offline.)
The full posture — GDPR, the EU AI Act, third-country transfer, and Skollagen — is in SECURITY.md.
- Python 3.10+
- Node.js 18+
- Claude Desktop
- macOS, Linux, or Windows (WSL)
- docs/GETTING_STARTED.md — installation walkthrough with a first-assessment tutorial
- docs/SETUP_GUIDE.md — full setup, troubleshooting, Claude Desktop configuration
- docs/WORKFLOW-INTEGRATION.md — the assessment pipeline, phase by phase
- docs/TEACHER_GUIDE.md — working with Claude through an assessment session
- methodology/ — the assessment framework and its theoretical grounding (under active development)
- docs/decisions/ — architecture decision records
- SECURITY.md · CONTRIBUTING.md · CODE_OF_CONDUCT.md
Contributions are welcome — bug reports, documentation improvements, feature ideas, and testing with real assessments. See CONTRIBUTING.md. By contributing you agree that your contributions are licensed under PolyForm Noncommercial 1.0.0.
PolyForm Noncommercial License 1.0.0 — see LICENSE.
This project is source-available, not OSI-approved open source: free for any noncommercial purpose, with commercial use reserved.
- Free for teachers, researchers, and educational institutions (any noncommercial purpose)
- Commercial use requires a separate licence
- See ADR-010 for why PolyForm rather than CC BY-NC-SA
Built with the Model Context Protocol, Claude, and pdfplumber.
The assessment methodology draws on analytic and formative-assessment scholarship — among others Sadler, Black & Wiliam, and Hattie & Timperley — and on validity theory from Kane, Moss, and Messick, contextualised for Swedish education by Hirsh. The theoretical grounding is under active development.
Thanks to the teachers and colleagues who tested the workflow with real exams and provided pedagogical feedback.
- Questions and bugs: GitHub Issues
- Discussion: GitHub Discussions