APEX Engine Inspection & Live State Loops

Sensing the live environment using ApexInspectionRequest and ApexInspectionResponse to drive the closed-loop See -> Think -> Act pattern.
Published: 7/10/2026

Closed-Loop Sensing vs Static Codebases

A common failure point for LLM agents interacting with 3D design software is relying on static workspace templates or local file structures to infer the viewport's contents. In a live session, options, operator values, and 3D positioning shift dynamically.

APEX solves this by pairing all transaction mutations with a highly efficient Inspect Tool (inspect_studio_structure). This tool acts as the agent's 'eyes', retrieving serialized real-time layouts and values directly from the active client session.

1. Core Paradigm: Decoupled Mutations, Relational Inspections

To keep the platform robust and prevent nested transaction state corruption, Aircada maintains a strict architectural split:

- Decoupled Mutations (Flat): Mutation payloads (dispatched via dispatch_studio_transaction) remain entirely flat. You configure schemas (DATASET), add individual records (DATASET_ROW), create configurator boundaries (OPTION_MODEL), or bind sets (OPTION_SET) independently.

- Context-Aware Inspections (Relational): Query parameters remain completely flat, but the backend resolver uses Context-Aware Dynamic Resolution to allow deep relational lookups on-demand without schema bloat.

2. The Query Signature: inspect_studio_structure

All inspections are executed via a single, clean query signature containing three optional filters:

typescript
export interface ApexInspectionRequest {
    /** Specific domain filters (e.g. ["DATASET_ROW", "OPTION_SET"]) */
    domains?: ApexDomain[];
    /** Unique component IDs (can be direct element IDs or parent IDs) */
    ids?: string[];
    /** Human-readable names (can be direct component names or parent names) */
    names?: string[];
}

3. Returned Types & Structural Schemas

All inspection results are returned in a flat array of wrappers containing the domain, component ID, and condensed structure:

typescript
export interface ApexInspectionResponse {
    status: ApexTransactionStatus;
    message: string[];
    structures: ApexInspectionTargetStructure[];
}
export interface ApexInspectionTargetStructure {
    domain: ApexDomain;
    id: string;
    structure: any; // Condensed Domain Representation
}

Detailed Sensing Rules & Schemas

For deep dive references, see the sub-nodes: - Context-Aware Dynamic Resolution Rules - APEX Domain Structure Schemas

Context-Aware Dynamic Resolution Rules#

How the APEX sensing engine resolves sub-domain relationships from flat parent ID and name filters.

Relational Query Parsing

When an agent or developer queries a sub-domain using parent filters, the backend dynamically resolves the relationship. This eliminates the need for complex, nested query structures.

Rule A: Dynamic Parent ID Resolution

When filtering a sub-domain (e.g., DATASET_ROW, OPTION_SET) by ids, the resolver checks:

- Direct ID Match: Does the queried ID match a child record's direct ID? (If yes, return it).

- Parent ID Match: Does the queried ID match a parent's ID (e.g. datasetId for rows, optionModelId for option sets)? (If yes, return all children belonging to that parent).

Rule B: Dynamic Parent Name Resolution

When filtering a sub-domain by names, the resolver checks:

- Direct Name Match: Does the queried name match the child record's direct name? (If yes, return it).

- Parent Name Match: Does the queried name match a parent component's name (e.g., the name of the dataset or option model)? (If yes, resolve the parent's ID in-memory and return all associated children.)

APEX Domain Structure Schemas#

Examples and layout definitions of the condensed structures returned by APEX sensing domains.

Condensed Serialization Formats

To maximize efficiency and preserve token budget limits, structures returned under ApexInspectionTargetStructure.structure are stripped of heavy runtime metadata.

1. DATASET Structure Schema

Represents the structural configuration of a spreadsheet or dynamic table. Omits dynamic data rows to maintain token efficiency.

json
{
  "domain": "DATASET",
  "id": "u96rhjwq5ub",
  "structure": {
    "id": "u96rhjwq5ub",
    "name": "gold test",
    "schema": {
      "id": "STRING",
      "name": "STRING",
      "color": "COLOR"
    }
  }
}

2. DATASET_ROW Structure Schema

Represents a granular record within a dataset.

json
{
  "domain": "DATASET_ROW",
  "id": "temp_row_24k_gold",
  "structure": {
    "datasetId": "u96rhjwq5ub",
    "values": {
      "id": "temp_row_24k_gold",
      "name": "24K Pure Gold",
      "color": [0.85, 0.65, 0.12, 1]
    }
  }
}

3. OPTION_MODEL Structure Schema

Represents a high-level product customization envelope (e.g., shoe customization parameters).

json
{
  "domain": "OPTION_MODEL",
  "id": "d4ya54XkRpU9aMVo",
  "structure": {
    "id": "d4ya54XkRpU9aMVo",
    "name": "Apex Test 1b"
  }
}

4. OPTION_SET Structure Schema

Binds a specific materials dataset to a configurator option model.

json
{
  "domain": "OPTION_SET",
  "id": "dG37uIuMNkl7Wls8",
  "structure": {
    "id": "dG37uIuMNkl7Wls8",
    "name": "Gold Options",
    "datasetId": "u96rhjwq5ub",
    "optionModelId": "d4ya54XkRpU9aMVo"
  }
}