Before the quiz: testing Imgobot’s document boundaries

The heading belongs to the question

A document-to-quiz pipeline can preserve every visible sentence and still lose the relationship that makes a sentence teachable. A paragraph under “Heat” has a different role from a page header or a footer. A table may need its section title to explain what its cells compare. Before generating blanks or questions, the system needs a useful account of those boundaries.

In the operator's Imgobot project, we inspected the function that groups parsed document elements into source units. It tracks a heading path, excludes header and footer elements, skips empty content, and preserves the original HTML fragments within each unit. We then executed an exact snapshot of that function against three original synthetic fixtures. All three produced the expected grouping.

This is a directly tested implementation case study. The test covers the pure grouping function, not document parsing, AI transformation, blank generation, database persistence, or learning outcomes. Those later stages are visible in the inspected orchestration code, but they were not executed for this article. Keeping that boundary clear makes the small result useful without turning it into a claim about the whole product.

Original TrendsWhat diagram. The grouping stage was executed on three synthetic fixtures; the later stages were inspected in source only.

What enters the grouping function

The function receives document elements with a category and HTML content. Categories identify headings, paragraphs, tables, and page furniture such as headers and footers. The function does not itself read a PDF or infer layout from an image. It works on an already parsed representation.

That distinction gives the pipeline a useful diagnostic boundary. If a heading is mislabeled as a paragraph by the parser, grouping may behave consistently with its input while producing an undesirable unit. A later AI transformation should not be blamed automatically for a mistake introduced during extraction.

For someone building an AI learning tool, the practical question is what intermediate representation survives between stages. If the original document is immediately flattened into one string, there may be no way to distinguish page furniture from meaningful content. A structured element list preserves information that later stages can use or inspect.

The heading path is more than a title

The inspected function maintains a hierarchy of heading text. A level-one heading starts a new top-level path. A level-two heading extends that path beneath its parent. When a new heading appears, the current content unit is flushed before subsequent fragments are collected under the new path.

Our first fixture contains “Science,” a paragraph, “Heat,” a table, and then a new top-level “History” section. The expected grouping has three units: Science, Science followed by Heat, and History. The returned headings match that expectation, and the table HTML remains attached to the nested Heat unit.

The result matters because a quiz interface can use the path as context or navigation. A short heading by itself may be ambiguous when several chapters contain a section called “Examples.” Preserving the parent path provides additional meaning without asking a model to reconstruct the hierarchy from disconnected text.

The three executed cases

The second fixture includes a workbook header, a section heading, a paragraph containing only a nonbreaking space, a meaningful sentence, and a page footer. Only the meaningful sentence remains as a content fragment under the section heading. This is a deliberately constructed example, not a claim that every real document parser labels those elements correctly.

The third fixture contains two readable paragraphs with no heading. The function groups them under its existing Korean fallback label. The test preserves that behavior rather than translating it to make the output look more uniform. A case study should report what the implementation returns, including details that may need different treatment in another product.

Reproduce the source-level test

Download the source snapshot and the fixture runner into the same folder. Run the following command with Node.js:

node run-source-units.mjs source-units-results.json

The recorded result includes the execution time, Node version, inputs, expected units, actual units, and pass flags. The published snapshot's SHA-256 matched the inspected local implementation when the experiment was prepared. The inspection notes record the source location and scope.

No upload, model call, or database write occurs in this test. The snapshot is a small pure function, and every fixture is fictional. You can inspect the expected output before running it, then add a new case without needing the rest of Imgobot's infrastructure.

What happens after grouping in the inspected pipeline

The orchestration code takes grouped units and transforms their fragments into quiz blocks. It records the original fragment positions, runs bounded concurrent workers, and collects transformed blocks back into their source units. This arrangement preserves the intended order independently of which transformation finishes first.

The next inspected stage sends blocks to a separate blank-generation process. Blocks receive identifiers based on unit and block position, and returned results are associated by those identifiers. The persistence code then creates metadata, sections, quiz records, blocks, and blank-answer records. These observations describe the code path; they are not an end-to-end execution result from this article.

Separating these stages helps locate a defect. A wrong section title belongs to a different investigation from a poor blank choice. A missing block differs from an incorrect answer normalization. If the pipeline exposes counts and identifiers at each boundary, a maintainer can ask where the expected material first disappeared.

Why preserving HTML can help, and where it stops helping

The grouping function uses a text approximation to decide whether content is readable, but it retains the original HTML string in the returned fragment. For a table, that means the grouped output still contains its markup rather than only a sequence of cell words. This preserves material that a later transformation may need.

Preserving markup is not the same as validating it. The grouping function does not establish whether HTML is safe to render, whether a table's visual relationships survived parsing, or whether a source image contains information absent from the text. Those concerns belong to other stages and require separate checks.

The distinction is useful when asking AI to process documents. “We retained the source fragment” is a provenance statement. “The fragment accurately represents the original page” requires comparison with the document. “The generated question is educationally sound” requires another kind of review. Each claim needs its own evidence.

A reader-facing quality check

For a generated quiz, inspect one question beside its source section. Confirm that the heading path is appropriate, the source passage contains the answer, and any table labels needed to interpret the answer remain visible. Check whether the blank tests a meaningful concept or merely removes a word without context.

Then inspect an exception: a headingless page, a repeated page header, a nested section, or a table spanning pages. The exact cases depend on the documents you accept. A pipeline can work on a clean sample while failing on the structure that appears most often in a user's material.

This article does not establish improved retention, exam performance, or pedagogical quality. It provides a method for reviewing the structural prerequisites of a usable quiz. Learning outcomes would require a different study with appropriate participants, measures, and controls rather than an inference from successful parsing.

Copy this document-to-quiz inspection sheet

The sheet is a reusable review aid, not an assertion that every row passed in this case study. We executed only the source-unit grouping tests. The remaining rows explain what a broader validation should inspect before making stronger claims about the complete pipeline.

Extend the fixtures before expanding the promise

A useful next fixture would contain a skipped heading level, such as a level-three heading without an explicit level-two parent. Another could include an image-only element, repeated heading text, or markup whose readable text is not captured by the simple stripping rule. Define the desired outcome before changing the implementation.

Add real-format examples only after removing private material or creating synthetic equivalents. Keep the exact element categories supplied by the parser you use. If you manually improve the categories before testing, you may accidentally evaluate an idealized input rather than the boundary your system actually receives.

For the concurrent transformation stage, a separate test could use controlled delays and verify that output order remains stable. For persistence, a test environment could inject a failure and inspect transaction behavior. These are concrete follow-ups suggested by the source, not tests we silently count as completed here.

What this project experience contributes

The operator's document workflow shows that creating useful AI-assisted learning material involves more than generating question text. Headings, fragments, order, identifiers, and answer records form a chain that makes the result understandable and diagnosable. The tested grouping function is one small but consequential part of that chain.

Our three fixtures demonstrate its behavior on nested headings, page furniture, and headingless text. They do not establish a general success rate for uploaded documents. The value is inspectability: readers can see the inputs, run the exact function snapshot, and extend the test where their own documents differ.

Before asking an assistant to generate better questions, inspect the source unit it receives. If the question has lost its heading, table labels, or neighboring qualification, the repair may belong upstream. Better AI work often begins with preserving the ordinary structure that tells a sentence what it means.

Sources, materials, and limits

• Source snapshot, fixture runner, and actual output.
• Project inspection notes: Imgobot grouping and orchestration source locations.
• Original synthetic fixtures, diagram, and inspection sheet. Three grouping tests passed; no end-to-end document conversion, AI generation, production persistence, or learning-outcome study was performed.