AI Agent Architecture — XyzPilot XYZ-SPEC-001

1. Executive Summary

XyzPilot is a precision CAD engine. Its geometry kernel — intersections, tangencies, projections, and constraint solving — is mature, tested, and correct. The question has never been whether XyzPilot can compute geometry. The question is: how should users interact with it?

The answer is a catalog-driven AI agent architecture. Rather than teaching an AI model to perform geometry, the agent is taught to translate natural language commands into validated function calls that XyzPilot executes natively. The geometry stays inside XyzPilot. The agent becomes a smart, reliable interface layer.

“

The geometry remains entirely inside XyzPilot. The agent becomes a translator.

2. Two-Tier Entity Model

XyzPilot distinguishes between two fundamentally different classes of geometry entity. This distinction is a core architectural principle that governs how the agent, the registry, and the dependency tracking system behave.

Tier	Entity Types	Persistence	Dependency Tracking
Construction Tier	Points	Disposable — may be deleted at any time	Not tracked — deletion never invalidates downstream geometry
Product Tier	Lines, Arcs, Circles, Toolpaths	Persistent — baked geometry, permanent output	Tracked — modifications propagate to downstream dependents

The formal rule: "Points are non-persistent construction entities. Toolpaths are the only contract."

What This Means in Practice

Points are construction aids — used to define lines, arcs, and toolpaths, then discarded
Once a line or arc is built from points, its geometry is baked — stored as a fixed numerical result
Deleting a point after product geometry is created has no downstream effect
The dependency graph applies only to product-tier entities
The kernel's contract: baked entities are numerically valid, operators are deterministic

3. The Old Model vs. The New Model

Old Model — Agent as CAD Engine	New Model — Agent as Translator
Agent computes geometry internally	Agent calls XyzPilot functions
Geometry logic duplicated in AI layer	Geometry stays entirely in XyzPilot
Errors are silent and hard to trace	Errors are caught at validation stage
Difficult to extend or maintain	New operators added to catalog only
One monolithic agent	Multiple specialized agents from one catalog

The key insight is that the agent does not need to understand trigonometry. It needs to understand intent, validate inputs, and route the command to the correct XyzPilot function.

4. Core Agent Capabilities

The catalog-driven agent architecture unlocks eight distinct capabilities that were previously impossible or impractical.

Natural Language Command Parsing

Users can issue commands in plain English. The agent parses the intent, identifies the operator from the catalog, and maps the inputs to the correct function signature.

User: "Create the YLarge intersection of L2 and C1"
Agent: POINT_DIR_INTOF_LX_CX → Point_LineCircleIntersection(L2, C1)
       → Select YLarge → Create P5

Menu Shortcut Interpretation

Quick-input shortcuts become machine-readable. The catalog defines the field order for every operator, so the agent can decode abbreviated inputs without ambiguity.

Input:    Point/XLarge,Intof,LX,CX
Shortcut: XLarge,0,1 → Point/XLarge,Intof,L0,C1

Pre-Execution Validation

Before calling any XyzPilot function, the agent validates all inputs against the catalog schema:

Does the referenced geometry (L0, C1) exist in the registry?
Is the selector (XLarge, YLarge) valid for this operator?
Are all required inputs supplied?
Are input types correct (line vs. circle vs. point)?

Errors are surfaced before execution, not after. This eliminates silent failures and reduces debugging time significantly.

Automatic Geometry Registration

When a function returns a result, the agent automatically assigns the next available ID, writes the entity to the geometry registry, and confirms creation to the user.

Function returns → Agent assigns ID → Writes to registry → Confirms "Created P12"

5. Business & Technical Advantages

Separation of Concerns

XyzPilot owns the mathematics. The agent owns the interface. Neither layer needs to understand the other's internals. XyzPilot can be updated without retraining the agent. The agent can be improved without touching the geometry kernel.

Multiple Specialized Agents from One Catalog

Once the operator catalog exists, it becomes the foundation for an entire ecosystem of specialized agents:

Geometry Creation Agent — executes commands and builds models
Documentation Agent — generates manuals from operator metadata
Training Agent — produces worked examples using real functions
Validation Agent — checks models against design rules
Debug Agent — traces failures through the operator log

Automatic Documentation Generation

Every operator in the catalog carries structured metadata. A Documentation Agent can consume this metadata directly and produce user manuals, API reference documentation, and training datasets — automatically.

Transparent, Traceable Debugging

Every command execution produces a structured log entry:

Input:    Point/YLarge,Intof,L1,C1
Operator: POINT_DIR_INTOF_LX_CX
Function: Point_LineCircleIntersection
Selector: YLarge
Output:   P7

Reduced Training Burden

You only need to teach the agents the command templates and function mappings — not geometry. This dramatically reduces the complexity of agent training, the risk of hallucinated geometry, and the cost of maintaining AI models over time.

6. Use Case Examples

Scenario	User Input	Agent Action
Point from line/circle	"Create the YLarge intersection of L2 and C1"	Calls Point_LineCircleIntersection(L2,C1), selects YLarge, creates P5
Circle from centre + point	"Circle from P1 through P2"	Calls Circle_FromCentreAndPoint(P1,P2), creates C4
Point at coordinates	"Point at X=50, Y=30"	Calls Point_XY(50,30), creates P6
Shortcut input	"XLarge,0,1"	Decodes to Point/XLarge,Intof,L0,C1 → executes intersection
Validation failure	"Intersect L5 and C1"	Validates: L5 does not exist → returns error before calling function

7. Implementation Roadmap

Phase	Deliverable	Description
1	Corrected Command Templates	Fix all operator definitions: syntax, field order, selectors, and input types. The foundation everything else depends on.
2	Function Mapping Catalog	Build the complete catalog mapping every command template to its XyzPilot function. Include input types, selectors, and validation rules.
3	Geometry Creation Agent	Deploy the first agent: natural language parsing, validation, function routing, and registry management.
4	Documentation Agent	Automate manual and reference generation directly from catalog metadata.
5	Training & Debug Agents	Deploy specialized agents for example generation, model training data production, and structured failure tracing.

Each phase is independently deployable. Phase 1 and 2 are prerequisites. Phases 3–5 can be developed in parallel once the catalog is stable.

8. Conclusion

The catalog-driven agent architecture is not a replacement for XyzPilot. It is an amplifier. XyzPilot's geometry engine remains the authoritative source of truth. The agent architecture makes that engine accessible, reliable, and extensible in ways that were previously out of reach.

The core principle is simple: teach the agents the interface, not the mathematics. Once the operator catalog is complete and the function mappings are defined, every chat agent immediately becomes smarter — not because it understands geometry, but because it knows exactly which XyzPilot function to call, with which inputs, and how to validate the result.

“