Exam Intelligence 🧠📚

Turn past exams into an evidence-backed study plan—because who needs a 10 when you can barely pass? (The target grade is configurable. Overachievers are welcome too.)

Exam Intelligence is a local, portable Agent Skill and Python CLI for turning historical university exams into evidence-backed study priorities. It analyzes already-classified question records deterministically: exact historical frequencies, recurring solution patterns, near-duplicate structures, transparent SOS/ROI rankings, and safety-margin study plans.

It is not a PDF summarizer and it does not claim to predict the next exam.

Historical occurrence is not prediction probability. “Taylor appeared in 9 of 11 variants (81.8%)” is valid. “Taylor has an 81.8% chance of appearing” is not.

Why this exists

Past exams often contain more useful structure than a heroic all-nighter can extract manually. Exam Intelligence turns that structure into transparent, reproducible priorities while keeping the student—not a mysterious score—in control.

Highlights:

• Exact frequencies across exam variants, sittings, and individual questions
• Structural pattern matching across differently worded problems
• Explainable SOS and return-on-study-time rankings
• Target-grade plans with a configurable safety margin
• A tactical cram mode for when optimism has become the primary study method
• Persistent manual corrections and low-confidence review queues
• Local-first storage with no account, telemetry, database, or API key
• A portable SKILL.md workflow for Codex, Claude, and compatible agents

How it works

Past exams + notes
        ↓
agent/native-text extraction
        ↓
topic + structural pattern classification
        ↓
validated local JSON
        ↓
exact variant/sitting/question statistics
        ↓
transparent SOS + study ROI
        ↓
target-grade and cram plans

The architecture draws a deliberate boundary:

• The agent does semantic work: reads notation, splits subquestions, identifies topics/patterns/methods, assesses difficulty and records confidence.
• Python does deterministic work: validation, counts, percentages, grouping, recency, scoring, caching, duplicate bookkeeping and report generation.

The core has no model integration, account, telemetry, database, or API key. It works with Codex-style, Claude-style, or other agents that can write the documented JSON contract.

Requirements and installation

• Python 3.12 or newer

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

For native PDF and DOCX text extraction:

python -m pip install -e '.[documents]'

For development:

python -m pip install -e '.[dev,documents]'
ruff check .
pytest

Quick start with the synthetic dataset

mkdir /tmp/mathematics-1
exam-intelligence init /tmp/mathematics-1
exam-intelligence --project /tmp/mathematics-1 import-data \
  examples/mathematics/classified-dataset.json
exam-intelligence --project /tmp/mathematics-1 doctor
exam-intelligence --project /tmp/mathematics-1 analyze
exam-intelligence --project /tmp/mathematics-1 report
exam-intelligence --project /tmp/mathematics-1 plan --target 5 --hours 6
exam-intelligence --project /tmp/mathematics-1 cram --target 5 --hours 3

That last command is the academic equivalent of a fire extinguisher. It is most effective before the room is fully on fire.

The example intentionally maps n^2/2^n, n^5/3^n, and n^8/e^n to the same canonical pattern: series.polynomial_over_exponential.ratio_test. Shifted terms such as 1/[n(n+1)] and 1/[(n+1)(n+2)] share series.telescoping.partial_fractions.

Real course workflow

Initialize a project inside any course directory:

cd mathematics-1
exam-intelligence init
exam-intelligence add ./past-exams --type exam
exam-intelligence add ./notes --type notes
exam-intelligence add ./solutions --type solution

add hashes every supported source (pdf, images, text, Markdown, DOCX, JSON). Unchanged files reuse their SHA-256 cache. Text and parsed documents use native extraction. Images are queued for agent visual inspection; the tool never blindly OCRs mathematics.

The agent reads .exam-intelligence/sources.json and progressively inspects cached text under .exam-intelligence/cache/text/. It creates one independent record per subquestion using the extraction contract, then imports it:

exam-intelligence import-data classified.json
exam-intelligence review
exam-intelligence set-pattern math1-2025-a-3b \
  series.telescoping.partial_fractions
exam-intelligence doctor
exam-intelligence report

Manual pattern corrections persist across future agent imports. Confidence below 0.70 appears in review; unreadable symbols should remain explicitly uncertain.

Commands

Command	Purpose
init [PATH]	Create inspectable .exam-intelligence/ state
add PATH --type TYPE	Hash, cache and extract sources incrementally
import-data FILE	Validate and upsert agent-classified JSON
analyze / rebuild	Calculate all deterministic statistics
stats	Print topic and pattern occurrences
patterns	List taxonomy entries and occurrence counts
report [--output FILE]	Write Markdown and machine-readable JSON
plan --target N [--hours H]	Create a safety-margin study plan
cram --target N --hours H	Print only tactical priorities
practice --top N	Write clearly labelled generated practice
explain PATTERN	Show recognition, recipe, traps and sources
compare LEFT RIGHT	Compare exam IDs/date substrings
review [--threshold .7]	List low-confidence classifications
set-pattern QUESTION PATTERN	Persist a manual correction
profile --mastery TOPIC=.75	Store course-specific mastery
doctor	Validate IDs, references, taxonomy and caches

Use exam-intelligence COMMAND --help for options.

Example report output

Top patterns:
1. series.polynomial_over_exponential.ratio_test
   appeared in 4/4 variants (100.0% historical occurrence)
2. series.telescoping.partial_fractions
   appeared in 3/4 variants (75.0% historical occurrence)

Target: 5/10
Safety target: 6.5/10
Estimated historical coverage: a range when marks are incomplete

Reports explain every score component and retain source file, page, exam, and question number. Markdown is never the source of truth; report.json is.

Persistence

.exam-intelligence/
├── config.json
├── manifest.json
├── sources.json
├── exams.json
├── questions.json
├── patterns.json
├── stats.json
├── profile.json
├── cache/text/
└── reports/
    ├── report.json
    ├── report.md
    └── practice.md

JSON is intentional: students and agents can inspect, version externally, repair, or extend it without a database tool. Project state is ignored by this repository by default so private course material is not accidentally committed.

Taxonomies

The built-in package supplies a strong mathematics taxonomy and conservative structural recognition helpers. The analytics engine itself is subject-neutral; projects can import patterns such as graphs.shortest_path.dijkstra or networking.ipv4.subnetting. See mathematics, computer-science examples, and the generic naming guide.

Using it as an Agent Skill

Point an agent's skill loader at this repository's SKILL.md, or copy only the SKILL.md plus the references/ directory into the agent's supported skills location and keep this package installed. The skill documents the staged workflow and portable JSON contract; no vendor-specific core adapter is required.

Privacy

Your source material and generated .exam-intelligence/ state remain local. The repository ignores common course-document formats and course-material folders by default, helping prevent accidental publication of exams, notes, solutions, or analysis. Always review git status before committing material from a real course.

Contributing

Bug reports, taxonomy improvements, documentation fixes, and narrowly scoped features are welcome. Start with CONTRIBUTING.md, follow the Code of Conduct, and report security issues according to SECURITY.md.

Limitations

• Semantic classification quality depends on the agent and legibility of sources.
• Native PDF extraction can still damage mathematical notation; uncertain pages require visual review.
• Duplicate similarity identifies review candidates, not proof of plagiarism or mathematical identity.
• Difficulty, learning time, SOS, ROI and plan coverage are explicit heuristics.
• Missing marks remain missing. Theme-level equal weighting is only valid when the exam states it, and never implies equal subquestion weights.
• Historical patterns can fail to recur. No passing outcome is guaranteed.

License

MIT — use it, improve it, and may your partial fractions actually cancel.