orchestrata_ultimate.orchestrator.intent_broker_factory

Reference › orchestrata_ultimate › orchestrator › intent_broker_factory

The one function that wires the real intent pipeline together. build_intent_broker is called by the kernel CLI (kernel.cli_main) and returns a ready IntentBroker. It is traced to spec 003 story US-004.

It takes a volk registry and a Postman transport as required arguments. It builds a PrologBridge when none is passed, so validation and routing always sit behind real rules, then constructs an IntentValidator with the per-minute rate limit (60 by default), an IntentRouter with a fallback volk (default U:Ox), an IntentDispatcher that delivers through the Postman route_sync, and a Redis-backed IntentLifecycleManager on the chosen Redis database. When enable_nl is true (the default) it also builds an NLIntentClassifier and IntentEvaluator over the default vocabulary, sharing the same Prolog bridge so the grammar tier is active. Impact analysis is off by default and runs only if the caller passes an analyzer; tool-call refactor routing is on by default.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/orchestrator/intent_broker_factory.py

"""Production factory for the SPEC-003 Intent Broker pipeline.

``IntentBroker`` has rich, correct pipeline logic (validate -> route ->
dispatch -> lifecycle) but historically had zero production construction
sites — nothing ever assembled the real dependency graph. This factory is
that assembly point: it wires real ``IntentValidator``, ``IntentRouter``,
``IntentDispatcher`` (real Postman transport, not the removed
``mark_delivered()`` stub), and ``IntentLifecycleManager`` into a working
``IntentBroker``.

Spec: 003-intent / US-004
Author: Mohamed
"""

from orchestrata_ultimate.core.base.traces import traces
from orchestrata_ultimate.core.protocols import IVolkRegistry
from orchestrata_ultimate.infra.prolog_bridge import PrologBridge
from orchestrata_ultimate.orchestrator.impact.analyzer import IntentImpactAnalyzer
from orchestrata_ultimate.orchestrator.intent_broker import (
    IntentBroker,
    IntentBrokerConfig,
)
from orchestrata_ultimate.orchestrator.intent_classifier import (
    IntentEvaluator,
    NLIntentClassifier,
)
from orchestrata_ultimate.orchestrator.intent_lifecycle import IntentLifecycleManager
from orchestrata_ultimate.orchestrator.intent_router import (
    IntentDispatcher,
    IntentRouter,
)
from orchestrata_ultimate.orchestrator.intent_validator import IntentValidator
from orchestrata_ultimate.orchestrator.intent_vocabulary import IntentVocabulary
from orchestrata_ultimate.postman.postman import Postman


@traces(spec="003", story="US-004", reqs=["REQ-003-US-004-001"])
def build_intent_broker(
    *,
    volk_registry: IVolkRegistry,
    transport: Postman,
    prolog_bridge: PrologBridge | None = None,
    redis_db: int = 0,
    fallback_volk: str = "U:Ox",
    rate_limit_per_minute: int = 60,
    impact_analyzer: IntentImpactAnalyzer | None = None,
    enable_impact_analysis: bool = False,
    enable_tool_refactor: bool = True,
    enable_nl: bool = True,
    vocabulary: IntentVocabulary | None = None,
) -> IntentBroker:
    """Assemble the real SPEC-003 intent pipeline (US-004 REQ-003-US-004-001).

    Wires validate -> route -> dispatch -> lifecycle with real components,
    no doubles:

    - ``IntentValidator``: Prolog-backed governance checks (fail-closed).
    - ``IntentRouter``: Prolog ``route_intent/3`` + static-mapping fallback.
    - ``IntentDispatcher``: real Postman transport (``route_sync``) — the
      previous ``mark_delivered()`` false-confidence stub is gone.
    - ``IntentLifecycleManager``: Redis-backed intent state machine.

    A default real ``PrologBridge()`` is constructed when none is supplied,
    so the validator and router always sit behind real governance/routing
    rather than silently degrading. Impact analysis is opt-in
    (``enable_impact_analysis=False`` by default) so this factory carries no
    hard KG dependency unless the caller supplies a real
    ``impact_analyzer``.

    Args:
        volk_registry: Real Volk registry (e.g. ``agents.volk_registry.
            VolkRegistry``) used for route resolution and heartbeat
            recording.
        transport: Real ``Postman`` instance the dispatcher delivers
            through via ``route_sync``.
        prolog_bridge: Real ``PrologBridge`` shared by the validator and
            router. Defaults to a fresh ``PrologBridge()`` when omitted.
        redis_db: Redis logical DB index for ``IntentLifecycleManager``
            (its host/port default to the ``REDIS_HOST``/``REDIS_PORT``
            environment, matching every other Redis-backed component).
        fallback_volk: Alias ``IntentRouter`` falls back to when no other
            route resolves.
        rate_limit_per_minute: Per-requester validation rate limit.
        impact_analyzer: Optional real ``IntentImpactAnalyzer``. Required
            for impact analysis to actually run even if
            ``enable_impact_analysis=True``.
        enable_impact_analysis: Gate for the KG-backed impact-analysis
            pipeline step. Defaults to ``False``.
        enable_tool_refactor: Gate for SPEC-103 FR-009 REFACTOR-intent
            routing to the tool-calling refactor capability.

    Returns:
        A fully-wired ``IntentBroker`` ready for ``process_intent``.
    """
    prolog = prolog_bridge or PrologBridge()

    validator = IntentValidator(
        prolog_bridge=prolog, rate_limit_per_minute=rate_limit_per_minute
    )
    router = IntentRouter(
        volk_registry, fallback_volk=fallback_volk, prolog_bridge=prolog
    )
    dispatcher = IntentDispatcher(volk_registry, transport)
    lifecycle = IntentLifecycleManager(redis_db=redis_db)

    # SPEC-003 US-001: wire the NL evaluator so process_text() accepts free
    # natural-language text. Its classifier gets the same real PrologBridge, so
    # the preferred DCG-grammar tier (intent_grammar.pl) is active, with the
    # extensible vocabulary as the fallback tier.
    evaluator: IntentEvaluator | None = None
    if enable_nl:
        vocab = vocabulary or IntentVocabulary.default()
        classifier = NLIntentClassifier(vocabulary=vocab, prolog_bridge=prolog)
        evaluator = IntentEvaluator(vocabulary=vocab, classifier=classifier)

    config = IntentBrokerConfig(
        validator=validator,
        router=router,
        dispatcher=dispatcher,
        lifecycle=lifecycle,
        impact_analyzer=impact_analyzer,
        evaluator=evaluator,
        enable_impact_analysis=enable_impact_analysis,
        enable_tool_refactor=enable_tool_refactor,
    )
    return IntentBroker(config)