Orchestration¶
The orchestration layer is responsible for planning multi-step operations and resolving which diagram type should be targeted for a given user request.
On this page
Request Planner¶
Location: src/orchestrator/request_planner.py
The request planner converts a single user message into an ordered list of operations. It uses either a heuristic approach or an LLM-based planner depending on request complexity.
Decision Flow¶
The request planner uses a 3-tier approach to minimize LLM calls:
Tier 0 – Fast heuristic regex patterns: A bank of compiled regular expressions matches common request shapes (e.g., “create a web app for X”, “generate Django”, “create a GUI for this system”, “add a state machine”). Handles ~90% of simple requests with zero LLM calls.
Tier 1 – Keyword-based fallback with discriminating patterns: Diagram type is resolved via explicit keywords (
KEYWORD_TARGETS) or discriminating regex patterns (_IMPLICIT_PATTERNS). Skips the LLM planner when the intent classifier already resolved a single target with no generation request. When no pattern matches a creation intent, escalates to Tier 2 instead of defaulting blindly.Tier 2 – LLM planner: Only genuinely complex multi-step requests (multiple diagram types + generation in one message) invoke the LLM for decomposition.
_should_use_llm_planner() now includes a fast-path that returns False
when matched_intent is a single-target intent and inferred_target_count
is 1, allowing Tier 0 and Tier 1 to handle the request without invoking the
LLM.
After planning, the result passes through normalize operations
(_normalize_operations()):
Deduplicate identical operations
Validate operation shapes
Enforce ClassDiagram-first ordering (required by other handlers)
If neither tier produces valid operations, the heuristic fallback is used.
Operation Format¶
Each operation is a dict with one of two types:
Model operation:
{
"type": "model",
"diagramType": "ClassDiagram",
"mode": "complete_system",
"request": "create a bookstore class diagram"
}
mode is one of complete_system or modify_model
(ALLOWED_MODEL_MODES). request is a focused sub-request for that
one diagram, carrying enough domain detail for the handler to act on it alone
— not a bare “create a class diagram”.
Generation operation:
{
"type": "generation",
"generatorType": "django",
"config": { "project_name": "myapp" }
}
Generator Prerequisites¶
When a generation operation is planned, the planner checks whether the required diagram types exist. Missing prerequisites are auto-injected as modeling operations before the generation step.
A diagram type exists when one of its tabs has content: a new editor project
sends every tab with an empty model, and those do not count. For the planner
the GUI diagram exists once a page has components; the direct generation check
(_missing_generator_prerequisites) accepts the empty default page, because
the editor builds basic screens itself for a web_app trigger.
Generator |
Required Diagram Types |
|---|---|
|
ClassDiagram, GUINoCodeDiagram |
|
ClassDiagram, GUINoCodeDiagram |
|
ClassDiagram |
|
ClassDiagram |
|
ClassDiagram |
|
ClassDiagram |
|
ClassDiagram |
|
ClassDiagram |
|
ClassDiagram |
|
ClassDiagram |
|
ClassDiagram |
|
ClassDiagram |
|
ClassDiagram |
|
AgentDiagram |
|
QuantumCircuitDiagram |
export and deploy have no prerequisites. GENERATOR_PREREQUISITES
(src/routing/generation_signals.py) is the source of truth, and it is
also injected verbatim into the Tier-2 planner prompt so the LLM planner
orders operations correctly.
Note
react appears in GENERATOR_PREREQUISITES but is not a key of
GENERATOR_KEYWORDS, so it is not in ALLOWED_GENERATORS and no route
can currently produce it. Treat that row as reserved, not reachable.
Example¶
User message: "create a bookstore class model and then generate django"
Planned operations:
{ "type": "model", "diagramType": "ClassDiagram", "mode": "complete_system", "request": "create a bookstore class model" }{ "type": "generation", "generatorType": "django", "config": {} }
Workspace Orchestrator¶
Location: src/orchestrator/workspace_orchestrator.py
Resolves which diagram type to target when the user does not specify one explicitly.
Three-Level Resolution¶
Level 0: The classifier's target_diagram_type
When the unified classifier named a target, it wins. Only diagrams
the message explicitly NAMES (Level 1 keywords) are added as extra
targets; Level 2 pattern hits never append a second diagram.
│
▼ (classifier left it NULL)
Level 1: Explicit keywords (KEYWORD_TARGETS)
"class diagram" → ClassDiagram
"object diagram" → ObjectDiagram
"state machine" → StateMachineDiagram
"agent diagram" → AgentDiagram
"gui" → GUINoCodeDiagram
"quantum circuit" → QuantumCircuitDiagram
"bpmn" / "business process" → BPMN
"user profile" / "persona" → UserDiagram
"component diagram" → ComponentDiagram
"deployment diagram" → DeploymentDiagram
│
▼ (no keyword match)
Level 2: Discriminating pattern rules (_IMPLICIT_PATTERNS)
AND-based regex patterns requiring
strong, unambiguous vocabulary
│
▼ (no pattern match)
Level 3: Context fallback (FALLBACK_PRIORITY)
Active diagram type from WorkspaceContext, then the
project snapshot in priority order:
ClassDiagram > ObjectDiagram > StateMachineDiagram >
AgentDiagram > GUINoCodeDiagram > QuantumCircuitDiagram >
BPMN > UserDiagram > ComponentDiagram > DeploymentDiagram
Level 1: Keyword Matching¶
Whole-word matching against the user message (KEYWORD_TARGETS); the last
word of a keyword may be plural, a gerund or numbered ("personas",
"process modelling", "bpmn2"), so "persona" does not match
"personal":
Keyword Pattern |
Resolved Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Note
Component and Deployment keywords are deliberately limited to phrases that name the diagram. Generic architecture vocabulary (“system architecture”, “software architecture”, “subsystem”, “service architecture”) is ordinary class-diagram phrasing and resolves through the normal levels instead.
Level 2: Discriminating Pattern Rules¶
When no explicit keyword matches, the system uses discriminating regex
patterns (_IMPLICIT_PATTERNS) that require strong, unambiguous signals
using AND-based logic.
Note
This replaced an older additive weight scoring system where generic words like “model” (weight=1) + “system” (weight=1) + “application” (weight=1) could accumulate to score 3 for ClassDiagram — three vague words confidently picking a diagram type. The new system requires at least one domain-specific term or a co-occurrence of two related terms.
How patterns work:
Single strong signal:
"lifecycle"alone → StateMachineDiagram. No supporting evidence needed — the word is unambiguous.Co-occurrence:
"state"+"transition"(within 40 characters) → StateMachineDiagram. Neither word alone is sufficient.No match on generic words:
"system","model","application"alone produce NO match. The request falls through to Level 3.
Diagram Type |
Discriminating Signals |
|---|---|
|
Any of: |
|
|
|
|
|
|
|
|
|
|
|
|
|
the diagram-naming phrases above, including plurals and a |
|
|
Note
Order matters. Patterns are evaluated in list order, and BPMN is deliberately checked before StateMachineDiagram because the word “process” appears in both vocabularies. Quantum is checked first because its vocabulary is the most specific.
Level 3: Context Fallback¶
If no discriminating pattern matches:
Use
active_diagram_typefrom theWorkspaceContextCheck
project_snapshotfor existing diagram types in priority orderUse
diagram_typefrom the request headerLast resort: default to
ClassDiagram
Note
When Level 2 produces no match and the matched intent is
create_complete_system_intent, the system now escalates to the LLM
planner (Tier 2) rather than defaulting blindly to ClassDiagram. This
ensures ambiguous creation requests like “build a system with states and
processes” get LLM-resolved diagram types.
Execution Flow¶
The orchestration and execution layers work together:
flowchart TD
UM["User Message"] --> PARSE["parse_assistant_request()"]
PARSE --> IC["Intent Classifier → State Body"]
IC --> EPO["execute_planned_operations()"]
EPO --> PLAN["plan_assistant_operations()"]
PLAN --> H["Heuristic operations"]
PLAN --> LLM["LLM planner (if complex)"]
PLAN --> NORM["Normalize + deduplicate"]
NORM --> LOOP{"For each operation"}
LOOP -->|"type == model"| EMO["execute_model_operation()"]
EMO --> R1["Resolve diagram type"]
R1 --> R2["Resolve target model"]
R2 --> R3["Build workspace context"]
R3 --> R4["Dispatch to handler"]
R4 --> R5["Apply layout"]
R5 --> R6["Send reply"]
LOOP -->|"type == generation"| HGR["handle_generation_request()"]
HGR --> G1["Match generator type"]
G1 --> G2["Parse inline config"]
G2 --> G3["Return trigger payload"]
Common Preamble¶
Every state body starts with _common_preamble()
(src/app/state_bodies.py), which runs these checks in order:
Reconnect replay — a
replay_last_responseaction re-sends the buffered terminal reply and stops. It never re-runs generation or consumes a pending flow.Pending dialogs —
resume_pending()(src/app/confirmation.py) hands the message to each open dialog inpending_dialogs.PRECEDENCEorder until one consumes it (see Pending Dialogs).Parse the request into an
AssistantRequestFile attachments —
handle_file_attachments()Record the user message in conversation memory, keyed on the stable payload
sessionIdso it survives reconnectsAsk instead of guess — if the cached classification set
needs_clarification, the preamble streamsclarifying_questionand stops rather than guessing a destructive mutation. It reads the cached verdict, so this costs no extra LLM call, and it never fires on afrontend_event.
It returns the parsed AssistantRequest when the message should be handled
normally, or None when a pending flow, an attachment, or a clarifying
question already consumed it — in which case the state body short-circuits.
Pending Dialogs¶
A turn that ends on a question stores what the answer needs in one session
variable, PENDING_DIALOGS, through src/common/pending_dialogs.py
(get / put / clear; never session.get on a slot name). Several
dialogs can be open at once — the domain-mismatch “Update model + generate”
chain keeps its Spec-Driven stash while the rebuild asks replace-or-keep, and a
“design X and generate Y” plan keeps its paused generator while its model step
asks the same — so the order is fixed in PRECEDENCE:
Dialog |
Question |
Resume handler ( |
|---|---|---|
|
Basic CRUD pages or experimental AI design? |
|
|
Replace, keep or new tab; or confirm a destructive modify |
|
|
Run the Spec-Driven Agent? (exact phrases confirm; the classifier may only cancel) |
|
|
Continue with the paused generator? (exact yes/ok/generate/no only,
because the classifier has stamped a bare “ok” as |
|
A handler returns True when it consumed the message and False when the
message is not its answer, after either leaving its dialog open or abandoning
it; the next open dialog is then tried. The classifier is shown the same first
open dialog (_pending_flow_context). Answers no handler consumes — the
generator menu, generator settings, a non-exact reply to a Spec-Driven or
plan-pause question — reach handle_generation_request through routing: the
pending gate in json_intent_matches keeps them out of intent routing,
should_route_to_generation sends them to the generation state, and
decline_body hands a decline to it while a generator dialog is open.
A plan’s model operations on independent diagram types run in parallel, but
open at most one replace/keep, GUI-choice or destructive-modify question
(pending_dialogs.one_per_plan): an operation whose question would come
second stops before asking and is queued in the open dialog’s
remaining_operations, so it asks once that dialog is answered. A queued
destructive modify keeps the change it already computed, so asking later makes
no second LLM call. If the operation that claimed the dialog fails before
opening it, the queued operations run in plan order right away and the first
of them that has a question asks it.