Skip to main content

Order guide parser

A deterministic parser for Audi of America Order Guide PDFs, in packages/ai_access_audi. Audi calls them Order Guides, and so does the module. The Stellantis equivalent in ai_dealer_connect is a Code Guide and keeps that name.

The parser returns what a guide contains. Records derived from a guide belong to the code that uses the parser, and this package defines none.

from ai_access_audi.order_guides.parser import parse, parse_document

guide = parse("Audi Order Guide 2027 USA (Invoice & Retail) 08.10.2026 - FINAL.pdf")
guide.page_count # 94
guide.page_text(59) # the Q7 quattro model page

document = parse_document(...)
document.identity.lineage_key # 'audi|USA|2027'

Status​

Implemented:

  • identity, the contents table, page kinds and model page ranges (parser);
  • the column grid (tables);
  • a model page's header, trim sections and options (grids);
  • the accessories table, the color matrix and the interior components (colors);
  • compatibility qualifiers (notes).

Not yet parsed: the Audi exclusive pages and the Updates table. exclusive_options and updates raise NotImplementedError.

What identifies a qualifier​

The text color identifies a qualifier, and punctuation does not. A qualifier is red, usually #c00000. A brighter red, #ff0000, is a qualifier only when it has a rule keyword such as req. or n/a, because the 2027 guide also prints notes in it. Audi sound system (10 speakers, 180 watts) is in parentheses but black, and has no rule. 21” black optic package (n/a with CN5) is red and has one.

The color also excludes two parenthesized texts that look like rules: limited time sub., accept. of Terms req'd has no code, and requires 1D6, helps with maneuvering a trailer is plain text inside a black feature name. Neither is red, so neither is parsed as a rule.

Guide structure​

From the 2026 and 2027 US guides:

SectionContents
CoverAudi of America, Model Year 2027, Order Guide, Invoice & Retail, the edition date
NoticesSignature Care, and a note on tariffs and pricing, in the Aptos font instead of AudiType
Table of Contentsone row per vehicle: name, page number, and a model code split across a body-style, an engine and a drivetrain column. Date Updated: gives the edition.
Model pagethe header, the STANDARD FEATURES table split into trim sections, and the OPTIONS table
Port Installed Accessoriesa code grid, then a table of description, code, retail and invoice
Exterior & Interioran availability matrix of exterior colors by seat trims, INTERIOR COMPONENT OPTIONS, and inlay and wheel images with text captions
Audi exclusivea section cover, an ordering FAQ, then per-model special paint and tailored interior tables
Addendumthe note on low-aspect-ratio tires
Updatesrows of model, update and date

A model has a header page, followed by its accessories and color pages. A model whose production window changes mid-year has two header pages that share one set of accessories and color pages. Their titles end in ...: Before CW 36/26 and ...: From SOP CW 36/26, or in the 2026 guide ...: Before CW 05/2026 and ...: From SOP CW 05/26.

The parsed document has these two levels. A ModelPage is one model, with the accessories, seat trims, colors and interior components that its pages list once. It has one ModelVariant per header page, with the header, the trim sections and the options that the production window prices separately.

The model page​

Page 59 of the 2027 guide, 2027 Q7 quattro, with text at its measured x positions:

ENGINE                    DRIVETRAIN / TRANSMISSION   MODEL CODE  RETAIL   INVOICE
2.9L TFSI, 6 CYL. 429 HP quattro® Tiptronic® G8BAYA $70,900 $66,647
Destination Charge (subject to change, add to all orders): $1,395 $1,395
Metallic or pearl effect paint: $595 $559

TRIM STANDARD FEATURES OPTION CODE RETAIL INVOICE
20" 5-arm aero design wheels Heated front seats
PREMIUM Audi drive select Power tailgate
PREMIUM INCLUDES PREMIUM FEATURES IN ADDITION TO:
PLUS Dashcam Power soft-closing doors WPS $4,400 $4,136
PRESTIGE INCLUDES PREMIUM PLUS FEATURES IN ADDITION TO:
Adaptive air suspension Head-up display WPT $14,000 $13,160

PREMIUM PREMIUM PLUS PRESTIGE OPTIONS OPTION CODE RETAIL INVOICE
21” black optic package (n/a with CN5)
- O O 21" 5-V-spoke wheels Black exterior trim XBO $1,750 $1,645

Three consequences:

  • Feature and option lists are in two columns (x≈73 and x≈280 in the features table, x≈111 and x≈273 in the options table). The reading order is down the left column of a trim section, then down the right column, and not line by line across the page.
  • Trim sections are cumulative. Each section after the first begins with INCLUDES <trim> FEATURES IN ADDITION TO: and lists only what that trim adds.
  • On a page with more than one trim, the options table has one availability mark column per trim. X and O mean available, S standard, and - not available. No other marks appear. Lowercase x also occurs and means the same as X.

Prices​

Prices are whole dollars, parsed as int. The guides have no cents, so neither float nor Decimal fits.

Most prices have the form $40,700. Three forms differ, and all are real prices:

TokenWhereMeaning
$-600 / $-5652026 p28, code CRTa package discount, with a minus sign instead of brackets
$10002027 p8, code U43no thousands separator
$1.2952027 p31, S8 destinationa period instead of the thousands comma. Every other model's destination charge is $1,395 in both columns.

A discount belongs to a trim, not to an option. The 2026 guide ends its XPP and XPR trim sections with a red row, CRT $-600 $-565, and the sentence ALL VEHICLES WITH XPP—PREMIUM PLUS PACKAGE WILL ALSO RECEIVE CRT—PACKAGE DISCOUNT. The parser reads it as the trim's discount, because ignoring it would overstate the price of every such vehicle by $600.

That sentence is Calibri in #ff0000, added over the page, while its code and price cells are AudiType in the table below it. That red is not the #c00000 of a compatibility qualifier.

Why the parser builds its own tables​

The guides are produced in Microsoft Publisher and embed the AudiType font family, so their text extracts cleanly per span. Their tables do not extract cleanly, because a guide has no vertical separator lines, only a shaded header row and thin row separators. The table-detection functions of pymupdf, pdfplumber and pymupdf4llm either find only the header rows, split cells in the middle of words, or drop characters from the text.

The guides do provide a column grid. The header row and each row separator are drawn as runs of filled rectangles, cut at every column edge. Page 59's OPTIONS table is cut at:

(18.0, 47.7) (47.7, 78.8) (78.8, 108.3) (108.3, 270.6) (270.6, 463.0)
(463.0, 472.5) (472.5, 506.2) (506.2, 515.2) (515.2, 548.5) (548.5, 557.5)
(557.5, 590.2)

These are the three trim columns, the two content columns, the option code column and the two price columns, with a 9pt gap rectangle between each pair. The cuts in one separator therefore give the same information as vertical separator lines. layout returns those rectangles as Bars, and tables builds the grid from them.

The Stellantis parser in ai_dealer_connect works the same way, from separator lines and font weights. Both parsers depend on PyMuPDF only.

Parsing pitfalls​

Titles. Body text is at most 6pt. Every title is 11pt or more in AudiType-ExtendedBold. The first non-blank line does not identify a title, because pages 99 to 107 of the 2026 guide begin with a page number. A page without an AudiType heading larger than body text has no title of its own and continues the page before it. Each such page in the US guides is an OPTIONS table that did not fit on its model page.

Overlays for unavailable models. A page whose model is closed to ordering has text added over it (NO LONGER AVAILABLE FOR ORDERING, NOT AVAILABLE FOR ORDERING), in Calibri instead of AudiType. Two simpler checks give wrong results:

  • On some pages the overlay is split across spans, so a check of single spans reads only NO LONGER AV.
  • The Updates table has the same words in a sentence about an option code, so a check of the page's full text finds overlays that do not exist.

The parser checks only the page's spans that are not in AudiType, which handles both.

Qualifiers. Compatibility is written inline in parentheses. The forms are req. X, n/a with X, lists separated by commas and slashes, req. X and Y/Z, and req. FW interior, where a code is followed by the noun it refers to. Two qualifiers in the guides have no rule and must not produce one: limited time sub., accept. of Terms req'd and requires 1D6, helps with maneuvering a trailer. Each fixture includes all of its guide's qualifiers as qualifier_corpus.json, so a new form appears as a diff.

A comma list without and or or. req. XBO, PQC needs one of its codes, and req. PPZ, QM interior needs all of them. A comma list names alternatives unless it has the word interior. In every such list in the guides, the codes exclude each other or are on different trims, so no car can have all of them. The A6 Sedan (FN2A5Y) prints the same pair as req. XBO, XSP on its 2027 illuminated rings and as req. XSP or XBO on its 2026 Daytona Gray paint. A list that names an interior needs all of its codes. The 2027 A6 Sedan prints its exclusive design package as req. PPZ and QM interior, and the 2027 S5 (FU2S5Y) prints the same package as req. PPZ, QM interior.

A qualifier can have one part per code. The 2027 A6 Sportback e-tron prices one warm weather package under PWE/PWF, and the row heading is BLACK (req. FW interior)/ BEIGE (req. II interior). The parts follow the codes in printed order, so PWE is the black package and PWF the beige one. Each entry takes the label and the rule of its own part only. Parsed as a whole, both codes would get both names and require both interiors.

Wrapped lines. A feature or option line that wraps continues at the same left edge and with the same line spacing, so the geometry does not separate the two lines. Their first character does: a new line starts with a capital letter or a digit, and every other line is a continuation, such as (40/20/40), front cross-traffic assist), season run flat tires or & center console sides.

A qualifier's brackets are black. Only the text inside them is red, and the brackets and the text can be in different spans. Removing the red text can therefore leave a lone ( or ). On page 70 of the 2027 guide, a qualifier wraps, and its closing bracket is alone on the next line, in bold, on a line that also has the previous group's content. A group therefore begins at its bold text only, never at the whole line.

Seat-trim columns have three forms. Page 7 has the code on a row of its own (AO). Page 66 has it after the description in one cell (Black (MP)). Page 13 has it in brackets before an unrelated option code ((GX) XBL). A code can also wrap onto a line of its own when its description is long, as (JN) does on page 82.

A seat-trim code is not unique on a page. Page 40 has GX in two columns under different seat styles. A color's availability marks are therefore positional, one per column in the order of seat_trims, and are not keyed by code.

Table layouts vary between pages of the same kind. Page 65's accessories table has trim availability columns, and page 6's does not. A model added before its pricing is final has no price columns. A missing column is part of the guide, so it is parsed as None and does not raise.

Some body rows are shaded. A shaded row is a table header only when its text is bold. The last two rows of page 6's accessories table are shaded body rows. Reading them as headers would cut off the table they belong to.

Header bars are not always cut at the column edges. The 2027 guide up to its 2026-10-05 edition cuts each header bar at every column edge, with a narrow gap piece between columns. The 2026-11-09 edition redraws the Q7 and Q9 pages and the contents page without gap pieces. Page 69 draws one STANDARD FEATURES header piece across TRIM, STANDARD FEATURES and OPTION CODE. Pages 69 and 85 cut the OPTIONS header inside the OPTIONS column, and page 7 cuts the INTERIOR COMPONENT OPTIONS caption into several pieces. A header label is centered in its column, so tables builds the grid from the labels. A piece with several labels is split where each label is centered. An unlabeled piece joins the labeled piece beside it when the joined piece still has the label centered, and stays a column of its own otherwise. A piece whose labels cannot all be centered is one caption, such as a title whose words are spaced apart.

Stamps in the title font. Page 20 of the 2026-11-09 edition has a red SOLD ORDER ONLY stamp in AudiType-ExtendedBold, 0.1pt larger than the black title. A title is therefore the largest black heading. The red production window on a title line, such as From SOP CW 36/26, is still part of the title, because it is on the same line as the black title text.

A color's marks can share its code's line. On page 7 of the 2026-11-09 edition the paint code is printed 1.6pt below the availability marks, close enough to share their line, and the color's name is a line above. The parser assigns the marks to the color whether they are on the name's line or on the code's line.

A superscript can begin where the line above ends. On page 85 of the 2026-11-09 edition Dashcam ends at the x where the nd of Heated 2nd begins, one line below. A superscript that already follows text on its own line stays on it.

The contents page's unavailable note. A model closed to ordering has a red note in its name cell, such as (No Longer Available for Ordering). The 2026 guide prints it in the qualifier red, #c00000. The 2027 guide prints it in a brighter red, #ff0000, between black brackets. Span.is_qualifier accepts #ff0000 text only when it has a rule keyword. Any red text in a contents name cell is the note, because the cell has no compatibility rules.

The contents page's group-heading bars. The first three group-heading bars of the 2026-11-09 contents page are cut at seven column edges instead of nine. The grid therefore comes from the first heading cut at all nine.

A row without a code. The parser raises on an OPTIONS row that prints no option code, because a misread usually moves a row's code to the row above or below it. Audi sometimes prints a row without its code. code_corrections in the AudiOrderGuidesComponent config gives the code of such a row, for one edition_key, page and row name. The parser logs a warning on a correction for a row that prints the corrected code, and raises on one for a row that prints a different code. Confirm the code against the previous edition and AccessAudi before adding a correction, because two options can share a model and a price.

Fixtures​

packages/ai_access_audi/tests/data/order_guides/parser/fixtures/ has one directory per guide, named audi_<market>_<model_year>_<edition_date>. The README.md there describes each file and what is left out on purpose.

Each guide's PDF is in its own fixture directory, so the tests run the parser on the document their expected values come from. The PDFs are 5 to 7 MB each, so the repo's large-file check excludes that directory. conftest.py also searches the working tree and its parent directories, and reports a missing PDF before the run and again at the end.

Rebuild a fixture's manifest from its PDF with:

python packages/ai_access_audi/tests/order_guides/build_fixture.py <pdf> <fixture_dir> <shipped_filename>