orchestrator package

Reviewed against commit 8a2cb42ad on 2026-10-23.

Reference: generated package page orchestrata_ultimate.orchestrator (42 modules, 15,904 lines of code); key modules engine, intent_broker, pipeline_runner, graph_audit, verification_gate, and the impact subpackage. How the intent pipeline, the kernel and the gateway fit together is in the orchestrata overview; the Postman it routes through is postman.

The story

Every piece of work that flows through orchestrata — a user request, an agent task, a governance question — eventually needs someone to decide who does it, whether it is allowed, and in what order it happens. That someone is orchestrata_ultimate.orchestrator, the Orchestrator volk (U:Ox): the governance and policy management engine of the system. The package exists because the surrounding pieces are deliberately dumb about policy — the gateway just moves WebSocket messages, Postman just delivers CXP packets, and the volks just do their specialty — so a single component has to own staffing decisions, policy evaluation, escalation handling, and routing. The top-level Orchestrator class (and its UltimateOrchestrator extension in orchestrator.py) implements the IOrchestrator interface and owns exactly that: volk staffing (VolkStatus, VolkInstance, VolkDefinition), governance decisions (PolicyContext, PolicyDecision), and escalations (EscalationIssue, EscalationResult).

The first major flow through the package is the intent pipeline. A raw natural-language request arrives at the IntentBroker (intent_broker.py), which walks it through a fixed sequence of collaborators. Free text is first run through the natural-language evaluator (IntentEvaluator in intent_classifier.py, which classifies with NLIntentClassifier against the term tables in intent_vocabulary.py and maps the result onto a workflow via WorkflowMapper); a formally-typed intent string is instead parsed by IntentParser (intent_parser.py, backed by nlp.py tokenization/NER and parameter_extractor.py). From there the broker applies security checks — authentication, authorization, injection prevention, and rate limiting in IntentSecurity (intent_security.py) — then Prolog-based validation (intent_validator.py), routing to a target volk (IntentRouter in intent_router.py), and finally dispatch as a CXP packet by IntentDispatcher (also defined in intent_router.py, wired to a real Postman transport by intent_broker_factory.py). Each stage produces a typed outcome from intent_results.py; state transitions are enforced by the intent_lifecycle.py state machine, every intent is persisted to dual Redis+graph history by intent_history.py, and intent_metrics.py instruments the whole run. Reusable intent patterns live in intent_template.py, and multi-step compositions are executed by intent_workflow.py.

The second major flow is pipeline execution. Once work is accepted, pipeline_router.py maps a WorkType (e.g. review, analysis, documentation) to a sequence of StageSpecs keyed by agent Capability, and PipelineRunner (pipeline_runner.py) executes those stages one by one through Postman routing — each volk stage produces a stage result, retryable failures are classified internally, and the whole run is summarized in a PipelineResult. Stage outputs land in the thread-safe ArtifactStore (artifact_store.py); a stage that escalates can INTERRUPT the pipeline via the EscalationInterruptMixin in pipeline_escalation.py; knowledge-graph absorption is folded in through PipelineKGMixin (defined in kernel/pipeline_kg.py, outside this package); and pipeline_kernel.py provides PipelineKernelClient, the in-process bridge that lets the Gateway hand work directly to the runner and stream events back over pub/sub.

Underneath both flows sits the governance substrate. engine.py's UOxEngine evaluates a PolicyContext against Prolog rules and returns a GovernanceResult/GovernanceDecision; the rules run on the janus-swi engine behind prolog_worker.py's single thread-safe PrologWorker, fronted by the PrologBridge fact/query abstraction (prolog_bridge.py). Policies themselves are versioned and tracked in policy_registry.py. Everything the engine decides is auditable: graph_audit.py (GraphAuditTrail; named neo4j_audit.py until the 2026-07-27 Neo4j retirement) writes the durable audit trail to the operational KG, fact_store.py/fact_manager.py/fact_graph.py (the last was fact_neo4j.py until then) keep governance facts in dual Redis+graph storage, and the redis_state.py session-state module is no longer in the package (removed; the table below lists what exists at 8a2cb42ad). The PrologBridge fact/query abstraction now lives in infra/prolog_bridge.py, not in this package. Finally, the impact/ subpackage answers "what will this intent break?" — IntentImpactAnalyzer classifies the intent, queries the graph (orchkg) for blast radius, and produces parallel execution plans. Neighboring packages depend on all of this: the gateway calls in via PipelineKernelClient, Postman carries the CXP packets the dispatcher and runner emit, the governance package's Prolog gate is invoked from the runner, and the knowledge graph both feeds impact analysis and receives audit writes.

Source: the orchestrata_ultimate.orchestrator package — 42 modules and 15,904 lines of code at commit 8a2cb42ad, including the 7-module impact/ subpackage (an earlier revision of this page counted 34).

Module inventory (8a2cb42ad)

Key responsibilities

• Governance & policy — evaluate a PolicyContext against Prolog rules and return an allow/deny/escalate decision (UOxEngine, PrologBridge, PrologWorker, policy_registry.py).
• Volk staffing & escalation — hire/fire/list volks and route escalations (Orchestrator / UltimateOrchestrator).
• Intent lifecycle — turn free text or a typed intent string into a routed, dispatched CXP packet through parse → classify → secure → validate → route → dispatch (IntentBroker and collaborators).
• Pipeline execution — map a WorkType to an ordered stage plan and run each volk stage through Postman, collecting artifacts and handling escalation interrupts (PipelineRunner, PipelineRouter, ArtifactStore).
• Impact analysis — classify an intent, compute its dependency blast radius from the operational graph (orchkg), and produce a parallel execution plan (impact/).
• Durable state & audit — persist intents, facts, and governance decisions to dual Redis+graph storage (intent_history.py, fact_store.py, graph_audit.py).
• Gateway bridge — expose an in-process client so the WebSocket gateway can drive the runner and stream events back (PipelineKernelClient).

Class diagram

Governance core

The staffing/escalation façade (Orchestrator, extended by UltimateOrchestrator, implementing the IOrchestrator interface) alongside the policy engine UOxEngine, which evaluates decisions through the PrologBridge fact/query abstraction over the single thread-safe PrologWorker:

Intent pipeline

IntentBroker composes the stage collaborators. Free text goes through IntentEvaluator (which delegates classification to NLIntentClassifier); every intent is then guarded by IntentSecurity, validated by IntentValidator, routed by IntentRouter, and dispatched by IntentDispatcher:

Pipeline execution

PipelineRunner mixes in PipelineKGMixin (KG absorption) and EscalationInterruptMixin (escalation-as-interrupt), plans stages with PipelineRouter, and collects outputs into ArtifactStore. PipelineKernelClient is the in-process bridge the gateway uses to drive it:

Impact analysis (impact/)

IntentImpactAnalyzer composes three collaborators: IntentClassifier categorizes the intent, DependencyAnalyzer queries the dependency graph in orchkg for the affected scope, and ParallelPlanner produces the parallel execution plan:

Notes

• IntentDispatcher is defined in intent_router.py (there is no intent_dispatcher.py); intent_broker_factory.py wires it to a real Postman route_sync transport.
• Orchestrator and its subclass UltimateOrchestrator live in orchestrator.py; the package __init__.py re-exports Orchestrator plus the Volk*, Policy*, and Escalation* dataclasses/enums.
• Governance rules run on the patched janus-swi engine through a single PrologWorker; keep variable-bearing rules in .pl files (consult) and only assert ground facts via PrologBridge.
• The impact/ subpackage additionally ships a CLI (impact/cli.py) and a rich types module (impact/types.py) covering IntentClassification, ImpactScope, InterfaceContract, ParallelPlan, and ImpactReport.

Class map (generated)

Generated from the live source AST by scripts/gen-module-class-diagrams.py — do not hand-edit. Abstract classes have a green border; members listed are those defined on the class itself (inherited members excluded). Solid empty-triangle arrows = in-package inheritance; dashed arrows into dashed boxes = external/stdlib/cross-package bases; filled diamond = composition (constructed in __init__); open diamond = aggregation (annotated/injected reference); diamond edge labels name the owning attribute.