P/N 02Case studyPersonal startup

HERISAGA Authoring

The AI authoring system behind HERISAGA. A source-to-facts pipeline chunks and indexes historical sources and extracts cited, structured facts from them, so every episode starts from evidence instead of a blank page. People review each fact before lessons and questions are drafted from the approved ones in English and Albanian, and editors approve every episode in Directus before it is published as a pinned revision. It is built so that AI makes writing history faster without inventing it.

Role: Co-Founder, Software Engineer
Team: Co-Founding Team (2)
Duration: 4 Months
Year: 2026
Stack: Python · FastAPI · Jinja2 · HTMX · OpenAI SDK · Voyage embeddings and reranking · pgvector · PostgreSQL · Directus · JSON Schema · Docker

Outcomes

11
Tracked steps from topic and retrieval to a recorded publish
0
Drafts that can reach learners without human review

Writing accurate, engaging history lessons in two languages is slow, and AI can speed it up, but language models confidently invent facts. For an education product, one invented date destroys trust. HERISAGA needed a way to use AI for drafting while keeping every claim traceable to a real source.

Every lesson must stay traceable to historical evidence. Machine-generated drafts always require human review. Content is bilingual, and once an episode is published it must never change under a learner mid-session.

The foundation is a source-to-facts pipeline, written in Python and FastAPI. It takes each historical source, splits it into chunks that stay tied to their source, and indexes them as vector embeddings in PostgreSQL with pgvector. For a topic it retrieves chunks with dense and lexical search, reranks them with Voyage, and checks that the evidence clears a threshold before anything is extracted. An LLM, called through the OpenAI SDK, then extracts structured facts from the strongest chunks, each citing the section and pages it came from. People review those facts in the Episode Studio, a FastAPI, Jinja2 and HTMX web app, and the passages, exercises and translations are drafted from the approved ones, each carrying the grounding facts behind it. Editors refine the bilingual episode in Directus and approve it there, and publishing records the exact revision that goes out as immutable, schema-validated content for the CDN.

The source-to-facts pipeline on the lower lane, human review on the upper: sources are chunked and indexed, retrieved and reranked, and an LLM extracts cited facts. People review them, then drafts and translations follow from the approved facts, and the episode is approved in Directus and published.

Do the reading in a pipeline, and start every episode from facts. The source-to-facts pipeline turns long historical sources into something an editor can work with straight away: structured facts, each saying who did what to whom and when, tagged with a reliability tier, citing the section and pages it came from, and held in English and Albanian from the start. Editors begin with a cited, bilingual list of claims instead of a blank page, which makes an episode both faster to build and better grounded.

Retrieve before generating. The model never writes from memory. The Retrieval console shows what it would be working from: the chunks found, how each one scored, whether the evidence clears a threshold, and what the extraction will cost. Nothing runs until that cost is confirmed.

The whole Retrieval console page: a topic and collection, an abstention check showing the top rerank score above its threshold, a table of retrieved source chunks with dense, lexical, fused and rerank scores, and a token and cost estimate to confirm before extracting facts — The Retrieval console from top to bottom: the topic, the abstention check, every retrieved chunk with its dense, lexical, fused and rerank scores, and the cost to confirm before extraction.

The Retrieval console from top to bottom: the topic, the abstention check, every retrieved chunk with its dense, lexical, fused and rerank scores, and the cost to confirm before extraction.

Review facts, not only finished text. A reviewer reads each extracted claim in English and Albanian beside the highlighted passage it came from, and approves, rejects, edits or skips it from the keyboard, one at a time or all at once. Checking a claim against its cited source is quicker than researching it from scratch. An automated evidence check, JEV, scores how well a passage supports a claim, but it never approves anything on its own. Exercises then list the grounding facts behind them, so evidence travels with the content.

Fact review in the Episode Studio: one claim in English and Albanian with its subject, relation, object and date, the source it came from, the highlighted passage, and buttons to approve, reject, edit, skip or undo — Fact review, one claim at a time: the claim in both languages, its structure, its source and the highlighted passage, with shortcuts to approve, reject, edit, skip or undo.

Fact review, one claim at a time: the claim in both languages, its structure, its source and the highlighted passage, with shortcuts to approve, reject, edit, skip or undo.

The whole Fact review all-at-once page: eleven extracted claims listed with their structured fields, sources and a Reject button each, ending in a single Approve all 11 button — The same claims as one list, each with its own Reject button and a single Approve all at the end.

The same claims as one list, each with its own Reject button and a single Approve all at the end.

Humans approve, the pipeline publishes. Episodes are edited in Directus with English and Albanian side by side, approved there, and only then published. Each publish records its run, the revision and a content hash, so the app only ever receives a pinned, validated revision.

The whole Directus page for an episode: its English and Albanian translations side by side, then its slug, status, published revision and timestamps — An episode record in Directus: English and Albanian fields side by side, then its status and published revision further down.

An episode record in Directus: English and Albanian fields side by side, then its status and published revision further down.

The retrieval, extraction, review and publication workflow is implemented and feeding content into the HERISAGA app as the product moves toward launch. A real episode, "Rome Won. Or Did It?", has run through all eleven steps, from topic and retrieval to a recorded publish.

Publish, step 11 of 11 in the Episode Studio: every step checked off, and the publish run recorded with its outcome, run ID, revision, content hash and who published it — The last step: all eleven steps checked off, and the publish recorded with its run, pinned revision, content hash and author.

The last step: all eleven steps checked off, and the publish recorded with its run, pinned revision, content hash and author.

Episode Studio's passages and exercises step: a drafted passage and a multiple-choice question in English, with the four grounding facts behind it listed in English and Albanian — What a reviewer sees for each generated exercise: the passage, the question and the grounding facts behind it, in English and Albanian.

I would run one real source through the complete workflow, from retrieval to a learner playing it, earlier, and tune retrieval quality against that real example. I would keep evidence-first drafting, because in education, trust is the product.

HERISAGA Authoring

Outcomes

Problem

Constraints

Architecture

Key decisions

Results

Reflection