Case study

CorralGPT (NUC Course Parser)
Applied AI/ML Engineering
CorralGPT is an AI course-writing workspace that turns Nigerian NUC curriculum PDFs into editable course records. I built it with FastAPI (62 endpoints) and SQLAlchemy (23 models) for the backend, PyMuPDF for rule-based parsing, five LLM provider adapters streaming drafts over SSE, and React with Tiptap for an editor that exports to Word.
How it’s built
CorralGPT (NUC Course Parser) · AI course-writing workspace that parses NUC curriculum PDFs into editable course records
CorralGPT turns Nigerian NUC curriculum PDFs into structured course records that authors edit and expand with AI drafts. I built the FastAPI backend with 62 endpoints, 23 SQLAlchemy models, a regex-based PyMuPDF course parser and five LLM provider adapters, plus a React and Tiptap editor that exports to Word. 27 of 35 commits are mine; a collaborator contributed 7.
- FastAPI endpoints
- 62
- SQLAlchemy models
- 23
- AI provider adapters
- 5
- pytest test functions in backend/tests and services tests
- 63
- lines of Python backend / TypeScript frontend
- 8,325 / 15,182
Technology and what it does here
- FastAPI
- REST API for courses, revisions, settings, writing sessions and agent tasks
- PyMuPDF (fitz)
- Extracts raw text from curriculum PDFs before rule-based parsing
- Python re
- Detects course codes, unit and lecture-hour metadata, learning outcomes and content blocks
- SQLAlchemy + Alembic
- 23 models; SQLite by default, PostgreSQL via psycopg2
- LangChain + LangGraph
- Provider clients and a research, draft, visualize StateGraph agent
- Gemini, OpenAI, Anthropic, DeepSeek, Ollama
- Selectable drafting models; DeepSeek via OpenAI-compatible base URL
- StreamingResponse (SSE)
- Streams AI drafts from ai_endpoints.py and writing_endpoints.py
- cryptography Fernet
- Encrypts stored provider API keys
- python-docx
- Server-side Word export with styles, headings and table of contents
- React 19 + TypeScript + Vite
- Course editor front end
- Tiptap 3
- Rich-text editor with tables, images, highlights and alignment
- Docker Compose
- Runs backend and frontend containers
Implementation details
- parse_courses splits text on a course-code regex and pulls units, C/E status and LH/PH hours from '(3 Units C: LH 45)' style headers.
- AIOrchestrator loads provider configs from the database and instantiates the matching adapter by name.
- A LangGraph StateGraph chains research_node, draft_node and visualize_node for long-form generation.
- export_docx converts stored HTML sections into a styled .docx with a generated TOC field.
System architecture
The parser turns curriculum PDFs into editable course records. Authors select records as context for model-assisted drafting and review the result in the editor.
Project screenshots
Open full-size screenshot in a new tab
Open full-size screenshot in a new tab
Open full-size screenshot in a new tabResults and testing
A synthetic PDF through the parser
An offline run extracted the expected course code, title, credits, hours, learning outcome, and topics from a generated PDF. It also exposed a multi-word programme heading that the current rules truncate.
Offline staging checks
Seventy-three tests passed for document parsing, state and metadata, and proofreading. Extraction accuracy across real curriculum layouts still needs a labelled benchmark.
Curriculum Extraction
Course codes, credit hours, and learning outcomes are facts the draft depends on. I kept their extraction separate from generation so an editor can inspect and correct the records first.
Turn layout-dependent text into course fields
I built the PDF text extraction and rule-based parser. It detects course headings and separates credit units, lecture and practical hours, learning outcomes, and topics. The API stores the results by project so they can be selected and edited later.
Use the curriculum to shape the draft
On staging, I added Nigerian education context and prompt templates that let the author use course details and teaching instructions to shape the generated material.
Model Integration and Review
The drafting workflow needed to support several model providers and give educators control over the text they keep.
Stream drafts across model providers
I implemented adapters for Gemini, Anthropic, OpenAI, and Ollama behind a shared generation interface. I fixed the Gemini adapter’s async stream iteration so it could pass text chunks to the editor as they arrived.
Make proofreading suggestions reviewable
On staging, I built a proofreading flow that combines local checks with model suggestions. It maps suggestions to the text in the editor and drops suggestions whose quoted text cannot be located. Local checks remain available when the model is unavailable.
Technologies
- Python
- FastAPI
- PyMuPDF
- SQLAlchemy
- Google Gemini
- Server-Sent Events
- React
- TypeScript
- Tiptap
