AI Engine

AI Engine

Role

The AI Engine interprets design intent and produces structured, validated proposals that operate on the real DesignForge document. It should use the project’s components, variables, styles, and tokens when available and clearly identify unavailable components rather than silently inventing library assets.

Context available to planning

The context builder may retrieve the relevant subset of:

• Active document, page, frame and selection
• Layer hierarchy and object properties
• Components, variants, styles, variables and tokens
• Layout constraints and responsive rules
• Existing naming and spacing conventions
• Attached requirements or supported reference inputs
• Recent edits and conversation history, where appropriate

Context should be scoped to the user’s request. The interface should communicate whether the operation targets a selection, frame, page, or full document.

Proposed AI workflow

1. Interpret: identify user intent and unresolved ambiguity.
2. Retrieve context: inspect relevant document nodes, components, tokens and constraints.
3. Plan: generate typed operations such as creating a tree, updating nodes, applying layout, or applying a theme.
4. Validate: check schema, target IDs, allowed operation types, hierarchy invariants, property ranges and scope.
5. Preview: show a change summary or visual diff for meaningful changes.
6. Approve: let the user apply or reject the proposal.
7. Execute: send approved operations through the normal command/transaction engine.
8. Evaluate: inspect resulting document integrity and surface warnings.
9. Recover: support undo and actionable diagnostics if the result is wrong or execution fails.

flowchart LR
    Prompt[User Intent] --> Context[Context Builder]
    Context --> Planner[AI Planner]
    Planner --> Schema[Typed Plan Validation]
    Schema --> Preview[Preview / Diff]
    Preview -->|Approve| Commands[Command Engine]
    Preview -->|Reject| Discard[Discard Proposal]
    Commands --> Document[Canonical Document]
    Document --> Evaluation[Integrity / Quality Checks]
    Evaluation --> Result[Result and Diagnostics]

Loading

Safety and determinism

• AI must not directly rewrite serialized project files or bypass document commands.
• Treat model output as untrusted input.
• Validate IDs, types, bounds, allowed fields, and operation scope before execution.
• Keep AI changes non-destructive by default.
• Do not invoke AI unexpectedly during ordinary drag-and-drop.
• Preserve deterministic geometry, serialization and compiler behavior.
• Clearly label local/offline versus remote inference mode.
• Respect user privacy settings and explicit consent for remote services.
• Record useful diagnostics without exposing secrets or sensitive project content unnecessarily.

Model integration

Use a provider-independent gateway so the application can support the existing local/offline path and configured remote providers without embedding vendor logic into UI controls. Model routing, fallback behavior, prompts, and current integration contracts should remain behind existing interfaces.

The current MCP integration and AI/agent structure are protected by the project's engineering guardrails. New functionality should use adapters around existing contracts instead of changing tool definitions or schemas without explicit approval.

Acceptance criteria

• Context reflects the actual selected document scope.
• Plans are schema-valid and rejected safely when malformed.
• Meaningful edits are previewable.
• Apply/reject actions are explicit.
• Applied changes are undoable.
• AI cannot bypass the command engine.
• Failures provide diagnostics and leave the document in a valid state.
• Local/remote mode is visible and follows configured privacy behavior.