APEX Protocol Architecture & Philosophy

Overview

APEX (Agent Protocol for Engine Execution) is engineered to solve a fundamental problem in LLM-driven 3D application configuration: semantic hallucination and state synchronization failures. Traditional REST or nested JSON APIs force LLMs to do complex, conditional reasoning within mutation payloads (e.g., 'if child items exist, modify them in-place, otherwise construct them on the parent'). This leads to massive token waste and high error rates.

APEX replaces nested, hierarchical payloads with three strict architectural pillars:

1. Flat Domains over Nested Payloads

To maximize AI reasoning reliability, APEX strictly avoids nested conditional mutations. Rather than having a parent 'Dataset' accept rows in a deeply nested array, a Dataset Row is elevated to its own first-class, flat domain (DATASET_ROW) with dedicated, discrete action interfaces.

Every operation targets a singular, granular entity. This keeps context windows extremely clean and prevents LLMs from writing invalid, partial schemas that could crash or desynchronize the live 3D engine.

2. The 'See -> Think -> Act' Loop

Agents must never assume the engine's state from static repository files or outdated metadata. In APEX, every mutation is paired with a powerful Inspect Tool (Live State Inspection) that serializes the live state of the active 3D scene, operators, and options on demand.

Before applying any modification, the agent first queries the live scene state ('See'), builds a plan based on real-time reality ('Think'), and dispatches atomic mutations ('Act'). This closed-loop design ensures robust operation even in highly dynamic client-side environments.

3. Atomic Transactions

Mutations are never dispatched as standalone, fire-and-forget commands. Instead, APEX transactions are batched in transaction arrays. An entire batch succeeds as a whole or rolls back as a whole. This transactional boundary preserves critical 3D engine integrity, preventing corrupted partially-built scenes if a single operation fails.