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:
| Section | Contents |
|---|---|
| Cover | Audi of America, Model Year 2027, Order Guide, Invoice & Retail, the edition date |
| Notices | Signature Care, and a note on tariffs and pricing, in the Aptos font instead of AudiType |
| Table of Contents | one 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 page | the header, the STANDARD FEATURES table split into trim sections, and the OPTIONS table |
| Port Installed Accessories | a code grid, then a table of description, code, retail and invoice |
| Exterior & Interior | an availability matrix of exterior colors by seat trims, INTERIOR COMPONENT OPTIONS, and inlay and wheel images with text captions |
| Audi exclusive | a section cover, an ordering FAQ, then per-model special paint and tailored interior tables |
| Addendum | the note on low-aspect-ratio tires |
| Updates | rows 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.
XandOmean available,Sstandard, and-not available. No other marks appear. Lowercasexalso occurs and means the same asX.
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:
| Token | Where | Meaning |
|---|---|---|
$-600 / $-565 | 2026 p28, code CRT | a package discount, with a minus sign instead of brackets |
$1000 | 2027 p8, code U43 | no thousands separator |
$1.295 | 2027 p31, S8 destination | a 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>