Graph Orchestrator Architecture

Version: 1.0 Status: Implemented (Core) Layer: AI Orchestration Source: src/ai/graph/

---

1. Overview

The Graph Orchestrator is the central brain of Jorvis. Instead of a linear chain of thought, it executes a dynamic, directed graph of "Nodes". This allows the system to loop, branch, parallelize, and self-correct based on the evolving state of the request.

Storage: The underlying knowledge graph is powered by Apache AGE (PostgreSQL Extension), enabling seamless integration with relational data (see ADR-0011).

2. Core Concepts

2.1 Graph State (GraphState)

The state object is passed between nodes and contains the shared context.

interface GraphState {
  // Input
  question: string;
  history: ConversationHistoryEntry[];
  
  // RAG Context
  schema: string;
  relevantSchemaContext?: string;
  relevantDocumentContext?: string;
  
  // Execution Control
  nextNode?: string; // The next node to jump to
  error?: string;
  
  // Results
  sql?: string;
  answer?: string;
  
  // Parallelism
  parallelPaths?: GraphState[];
  consensusResult?: GraphState;
}

2.2 Nodes

Nodes are specialized NestJS services implementing GraphNode.

2.3 Routing Logic (Dynamic)

The routing is dynamic. Each node determines the nextNode.

Example Flow (Text-to-SQL):

1. SchemaContextNode → Finds tables → QuestionAnsweringNode
2. QuestionAnsweringNode → Generates SQL → DataExecutionNode
3. DataExecutionNode → Success → SynthesisNode
4. DataExecutionNode → Error → SqlRepairNode
5. SqlRepairNode → Fixes SQL → DataExecutionNode (Loop)

3. Parallel Execution

Task-094 introduced parallel processing for complex queries.

1. Splitter: Breaks question "Compare revenue 2023 vs 2024" into:
   • Path A: "Revenue 2023"
   • Path B: "Revenue 2024"
2. Execution: Paths run concurrently (with timeouts).
3. Trace: Each path has a unique parallelPathId.
4. Consensus: ConsensusNode aggregates results into a final answer.

4. Safety Mechanisms

• Max Steps: Limited to 10 steps to prevent infinite loops.
• Circuit Breaker: Halts execution if errors persist.
• Token Budget: Checks combined token usage before launching parallel paths.
• Timeout: Parallel paths time out after configured limit (default: 15s).

5. Implementation Status