Configurator

​

Overview

The Configurator solves the configure-to-order problem. Given a product family with many valid combinations of options — engine types, roof types, accessories, finishes — it walks through the option tree, makes selections, pins material attributes, and resolves those decisions into a concrete parts list for a specific unit. The data model has three layers:

• Configuration Templates — the possibility space (every valid option, every valid combination, all nested sub-options, and the materials each option pulls in)
• Configurations — identity-only containers (a name and description) that group revisions for a single real-world order
• Revisions — immutable state-bearing snapshots under a configuration, carrying the actual selections, material assignments, and resolved parts list

The Configurator is agent-assisted by design. Dexter is the primary operator of the per-turn decision loop: it reads an order document (PDF, pasted text, ERP export), maps its contents onto the template’s option classes, proposes each decision one at a time via ask_question, and the user confirms before each write. The user can override any decision at any point.

​

Key Concepts

​

Configuration Template

The full option space for a configurable product. A template carries: Templates have two parallel sibling arrays — materials and option_classes — at every level of the tree. There is no single polymorphic components array.

​

Materials

A fixed part included when its parent option (or the template root) is selected. Materials carry: Part numbers do not live on template materials. They belong on revisions, via material assignment attribute values.

​

Option Classes and Options

An Option Class is a group of interchangeable choices — the core decision unit: Selection types:

• select_one — exactly one option must be chosen
• select_many — zero or more options may be chosen (none is valid)
• select_at_least_one — one or more options must be chosen (zero is invalid)

An Option is a single choice within an option class — option_id, name, and its own materials and option_classes arrays. That nesting is recursive: selecting “diesel engine” can reveal a nested Turbo Configuration option class that wasn’t reachable until the engine choice was made.

​

Configurations

A Configuration is an identity-only container — just a name and description. It groups revisions for a single real-world order or quote. All state — selections, material assignments, resolved materials — lives on revisions, not on the configuration itself.

​

Revisions

A Revision is an immutable state-bearing snapshot under a configuration. Once written, it cannot be modified. The revision with the highest revision_number is the active state. Each selection records: Each material assignment records:

​

Variant Conditions

Material assignments pin attribute values using VariantCondition structures — the same system that BOM variant conditions use:

• boolean — true or false
• discrete_number — one or more specific numbers (e.g., [12, 24])
• discrete_text — one or more specific text values (e.g., ["red", "blue"])
• range — numeric range with inclusive/exclusive bounds

​

The Phase Model

The state script computes the current phase of a revision, which drives the entire workflow:

​

The State Script

The state script is the single source of truth for where a configuration run stands. Given a template and a revision, it computes: The agent re-calls the state script at the start of every turn and after every write. The conversation transcript is not a substitute.

​

Creating a New Configuration

1. Pick a Configuration Template
2. Upload an order document (PDF, spec sheet, customer email) or paste relevant text
3. The agent calls the state script to get the current phase and frontier
4. Option selection phase — for each option class on the frontier:
   • The agent identifies the next decision, reads the relevant order data, and proposes a selection
   • The agent presents the decision to the user via ask_question for confirmation
   • On confirmation, the agent writes the selection to the revision
   • The agent re-calls the state script — newly reachable nested option classes appear on the frontier
   • The loop continues until all option classes are decided
5. Material assignment phase — the agent pins attribute values on each reachable material. The cadence differs from option selection: when a single source document (an Epicor extract, an uploaded CSV, a customer order PDF) covers multiple materials, one ask_question authorizes the entire batch and a single write lands them all. The per-material fallback only applies when a material’s value can’t be grounded in a shared source.
   • The agent identifies materials on the frontier and groups them by source
   • The agent presents assignments via ask_question with source and notes for each
   • On confirmation, the agent writes the material assignments
   • The loop continues until all materials are assigned
6. When the state script returns phase: "completed", the revision is done

​

Reconfiguring an Existing Configuration

When a change request lands against a saved configuration — updated order, customer email, engineering change notice — a new revision is created under the same configuration.

1. Find the latest revision (highest revision_number) and read its selections and material assignments
2. Write a new revision file with:
   • A descriptive slug (e.g., rev-3-hardtop-swap)
   • revision_number incremented by 1
   • revision_notes describing the delta (e.g., “Switched roof type to hardtop per customer request 2026-05-12”)
   • All unchanged selections and material assignments carried forward
   • Changed entries removed — these become open decisions again
3. The per-turn loop re-walks the frontier for the removed decisions, just like an initial configuration
4. Stale entries (selections or assignments that are no longer reachable due to the changes) are resolved
5. When phase: "completed", the new revision is done

The configuration row itself is untouched — reconfiguration only adds a new revision. The version chain is implicit in the revision numbering; there is no explicit parent pointer.

​

Errors and Stale Entries

Before advancing the frontier, the agent resolves two surfaces the state script returns:

• Errors — structural problems that must be fixed: unknown option IDs, cardinality violations (e.g., two selections on a select_one class), unknown entity slugs
• Stale entries — selections or material assignments whose keys are no longer reachable. This happens when a parent option changes and previously-selected nested options become orphaned

Both must be resolved before a revision can reach phase: "completed".

​

Templates

A template is the source of truth for what’s configurable. Building one well is the highest-leverage work in the Configurator — the option tree’s shape determines what a quote-builder can answer. Templates are typically authored in two ways:

• From scratch — for genuinely new configurable products
• From an ERP / config table export — pipeline-mediated, using a pipeline to transform tabular data into the template JSON

When authoring templates:

• material_id must be stable across template edits — revisions key off it. Changing a material ID breaks existing revisions’ references
• Part numbers belong on revisions, not templates. The template defines the material; the revision pins its attributes (including part number) via material assignments
• Every entity referenced from a template must declare a part_number attribute with attr_type: text — this is an authoring prerequisite for the material assignment phase. Text typing is required because part numbers are alphanumeric (e.g., "87-A412"). A missing attribute slot means the material assignment phase can’t pin a part number to that material
• instructions fields on option classes and materials carry cross-class rules, sourcing guidance, and decision criteria that the agent reads when making proposals
• Quantity is fixed at the template level. If a material can appear in different quantities depending on configuration, model them as separate materials with separate IDs

​

Mid-Run Template Edits

Templates can be edited during a configuration run — when a customer’s order doesn’t fit the current option set. The edit is gated by ask_question, the change is written to the template file, and a one-line entry is appended to the revision_log field. The per-turn loop then resumes with the updated template.

​

Relationship to Other Features

​

Standard BOMs

The most important distinction: standard BOMs are flat production recipes; Configuration Templates define an option space. BOMs feed directly into simulation and planning; templates do not — they produce revisions, which carry a per-order parts list. If you find yourself wanting to use a template directly in a planning model, that’s the signal you actually need a BOM.

​

Entities

A template references entities in two places: the template root (the configurable product family) and the materials inside each option (the specific parts each selection pulls in). Entities also carry the attributes that the material assignment phase pins — the same attribute system that BOM variant conditions use.

​

Planning

A completed revision’s resolved materials list could in principle feed planning demand orders — if you know a specific order needs a specific parts list, that informs SKU demand. Today this linkage is manual or pipeline-mediated, not automatic. Completing a revision does not auto-create a demand order.

​

Simulation Models

Simulation models reference standard BOMs and entities; they do not consume Configuration Templates or revisions directly. To simulate a configurable product, build the corresponding BOM and ensure the model’s parameters reflect the configuration you care about.

​

Best Practices

​

Template Design

Shape the tree around the customer’s decision sequence, not the BOM structure. The option tree should mirror the order a customer or sales engineer actually thinks about choices — roof type before roof accessories, engine before turbo configuration. When the tree follows the natural decision order, the agent’s proposals align with what the order document says, and the user spends less time correcting sequence-dependent misreads. Prefer shallow nesting with clear gates over deep nesting. Every nesting level adds a decision the user must confirm before the nested options become reachable. Two or three levels deep is normal; beyond that, ask whether the inner decisions genuinely depend on the outer one or whether they’re independent choices that happen to be grouped together. Independent choices belong at the same level, not nested. Use select_one only when the choice is genuinely forced. If there’s a legitimate “none” case — an optional feature the customer might not want — select_many is the right cardinality, even if most customers pick exactly one. A select_one class with no valid “none” option forces the agent to pin an arbitrary default when the order document is silent on the topic. Write instructions as if the agent has never seen this product before. The instructions field is the only guidance the agent reads at decision time beyond the option names themselves. Encode the decision criteria explicitly: “Choose aluminum when the customer specifies a corrosive environment; choose steel otherwise.” Don’t assume the agent will infer cross-class dependencies — if selecting a heavy chassis means the tow package must include a class-IV hitch, say so in instructions. One material per attribute-varying part. If the same physical part can appear with different attribute values depending on the configuration (different voltages, different lengths), model them as separate materials with separate material_ids gated by the appropriate option. The material assignment phase pins attributes per material_id — a single material_id that needs different values in different configurations has no clean resolution.

​

Order Document Prep

Structured order documents produce faster, more accurate runs. When the order document cleanly maps to the template’s option classes — a line item per choice, a column per attribute — the agent can ground every proposal in a specific line or cell reference. Unstructured narratives (“customer wants the heavy-duty package with the upgraded electrical”) work, but they produce more proposals that need user verification. Include part numbers in the order document or a companion file. Since part numbers live on revisions, not templates, they need to come from somewhere during the material assignment phase. An Epicor extract, a part-number mapping CSV, or explicit part numbers in the order document give the agent a grounded source to cite. When part numbers aren’t in the source data, the agent will ask for each one individually — which is correct but slow. Flag what’s different about this order up front. If the customer is asking for something the template doesn’t currently support — a new option, an unusual quantity, a combination that doesn’t fit the tree — mention it at the start of the run. The agent can propose a mid-run template edit early rather than discovering the gap partway through the option selection phase.

​

Working with the Agent During a Run

Correct early, not late. If the agent’s proposal for an option class is wrong, override it immediately rather than confirming and planning to fix it later. Option selections can unlock nested option classes — a wrong selection at the top propagates through the tree, and correcting it later means a reconfiguration that re-walks every downstream decision. Use the notes field. When confirming a selection or material assignment, adding context to the notes field (“customer verbally confirmed 24V on 2026-05-10”, “defaulting to standard length per engineering guidance”) pays off during audits and reconfiguration. The agent proposes notes based on what it knows, but user-supplied context is often more specific. Let source-batching work for you during material assignments. When you have a single source document that covers many materials — a part-number mapping file, an Epicor extract — upload it and let the agent batch the assignments by source. This is significantly faster than pinning materials one at a time and produces a cleaner audit trail (every assignment in the batch cites the same source).

​

Reconfiguration Strategy

Name your revision slugs for the change, not the sequence. rev-3-hardtop-swap tells you what happened; rev-3 tells you nothing. When you’re scanning a directory of revisions six months later trying to understand the history of a customer order, descriptive slugs save real time. Write revision_notes that describe the delta, not the final state. “Switched roof type from canopy to hardtop per customer email 2026-05-12” is useful. “Roof type: hardtop” requires the reader to diff against the prior revision to understand what changed. Prune aggressively on reconfiguration. When carrying forward state from the prior revision, remove anything the change might cascade into — even if you think it’s probably still correct. The per-turn loop will surface the gaps, and the ask_question gate will bring the values back in with fresh verification. Carrying forward an assignment because it’s “probably still right” is how stale values survive into completed revisions. Don’t reconfigure what you should re-create. If the change is so extensive that most selections and assignments need to change, a fresh configuration (new revision 1) against the same template is cleaner than a reconfiguration that removes almost everything and re-walks it. Rule of thumb: if you’re removing more than half the entries, start fresh.

​

General

Treat empty source fields as audit failures. A material assignment without a source is a value no one can trace. The state script won’t reject it, but the next person who reads the revision — or the next reconfiguration that needs to decide whether to carry it forward — has no way to evaluate whether the value is still correct. Keep templates and revisions in sync on entity definitions. Every entity_id referenced in a template needs a corresponding entity definition with the right attributes (especially part_number with attr_type: text). Missing entity definitions or missing attributes don’t fail template authoring — they fail the material assignment phase, which is later and harder to debug.

​

Common Pitfalls

A few more to watch for:

• select_many allows zero selections; select_at_least_one does not. Validation catches the difference, but the constraint is easy to misread when authoring a template.
• Revisions are immutable once written. To change a completed revision, reconfigure it — which creates a new revision with an incremented revision_number. There’s no in-place edit.
• Empty source on a material assignment is an audit-trail gap. The agent will back up and ask if it can’t ground the value in user-stated facts or source data.
• revision_notes should describe the delta, not just the new state: “Switched roof type to hardtop per customer request” rather than “Hardtop selected.”
• Recursive option nesting is powerful but easy to overcomplicate. The state script catches structural errors, not poor design.
• material_id must remain stable across template edits — it’s the key that revision-level assignments reference. Changing it orphans existing assignments.

​

Reference

• Template schema — entity_id, name, description, revision_log, materials[], option_classes[] (parallel sibling arrays, recursive under each Option)
• Material schema — material_id, entity_id, name, quantity, instructions
• Option Class schema — option_class_id, name, instructions, selection_type, options[]
• Configuration schema — name, description (identity-only container)
• Revision schema — slug, revision_number, revision_notes, selections[], material_assignments[]
• Selection schema — option_class_id, chosen_option_ids[], notes
• Material Assignment schema — material_id, attribute_values[] (VariantCondition), source, notes
• VariantCondition types — boolean, discrete_number, discrete_text, range
• Phase model — pending, selecting_options, assigning_materials, completed
• State script output — phase, next[], stale[], errors[], resolved_materials[]
• Selection types — select_one, select_many, select_at_least_one