Skip to main content

​
Connection Rules

components/builder/connectionRules.ts is the single source of truth for which nodes can connect to which handles. It’s used by:
  • The canvas drag-drop validation (live rejection of invalid connections)
  • The AI flow generator’s system prompt (so the AI knows what’s allowed)
  • The graph validation before applying AI operations

​
Rule structure

type InputRule = {
  maxConnections: number
  allowedSourceTypes?: string[]    // Specific allowed source node types
  allowedSourceCategories?: string[]
}

type TargetRule = {
  nodeType?: string          // Exact node type to target
  nodeCategory?: string      // Or a node category
  excludeNodeTypes?: string[]
  targetHandleId: string     // The handle to connect to
}

type OutputRule = {
  maxConnections: number
  targets: TargetRule[]
}

​
findTargetRule(sourceType, sourceHandleId, targetType, targetCategory)

When a user drags an edge and drops it on a target node (without specifying the exact handle), findTargetRule() auto-routes to the correct handle:
  1. Look up the source node’s rules from connectionRules[sourceType]
  2. Get the outputs rule
  3. Priority 1: Find a rule with exact nodeType match on the target
  4. Priority 2: Find a rule with nodeCategory match, excluding excludeNodeTypes
  5. Return the first matching TargetRule (contains targetHandleId)

​
Key rules summary

​
Component → Framework wiring

SourceAuto-routes to
personaframework.persona_in
llmframework.llm_in
ttsframework.tts_in
sttframework.stt_in
avatarframework.avatar_in

​
Conversation step constraints

  • start can connect to any conversation node except start
  • ifelse and categorize cannot immediately follow start (require an intermediate step)
  • ifelse and categorize cannot connect to each other
  • end connects to webhook only (optional)
  • transfer connects to framework.transfer_in or webhook

​
Integration → Framework

SourceConnects to
mcpframework.tools_in
exaframework.tools_in

​
Validation in the AI generator

The AI flow generator builds an ALLOWED_INPUTS map from connectionRules.ts and simulates the operations against the current graph. If any operation would violate a rule, the AI retries with error feedback (max 3 attempts).