Struct Orchestrator 

pub struct Orchestrator { /* private fields */ }

LLM orchestrator with tool loop execution.

The orchestrator wraps an LlmDriver and adds:

• Tool call detection and accumulation
• Tool execution via MCP
• Automatic tool result feeding
• Request ID tracking

Implementations

impl Orchestrator

pub fn new( llm_config: LlmConfig, mcp: Arc<McpRegistry>, native_skills: Arc<NativeSkillRegistry>, ) -> Result<Self>

Create a new orchestrator with the given LLM config, MCP registry, and native skill registry.

Uses LiterLlmDriver backed by liter-llm’s DefaultClient for all 142+ providers with unified tool-call normalization.

Errors

Returns an error if the underlying LLM client cannot be constructed.

pub fn from_driver( llm_config: LlmConfig, mcp: Arc<McpRegistry>, native_skills: Arc<NativeSkillRegistry>, driver: Arc<dyn LlmDriver>, ) -> Self

Create a new orchestrator with a host-supplied LLM driver.

This is the embedding seam for environments that own a local model runtime outside UAR, such as KnowMe mobile. UAR still owns the agent loop, tool governance, skills, and normalized events; the host-supplied driver only provides model streaming.

pub fn with_skill_activation( self, context: Arc<Mutex<ActivationContext>>, strategy: ContextStrategy, model: String, context_limit: usize, budget: SkillReattachmentBudget, ) -> Self

Share host-owned activations without persisting their reclaimable bodies in the history that compaction summarizes.

pub fn with_request_budget_contract( self, contract: RequestBudgetContract, ) -> Self

Attach a trusted-host-resolved final-wire budget contract to every request preparation performed by this orchestrator.

pub fn with_destination_preparations( self, preparations: Arc<DestinationRequestPreparations>, canonical_history: Vec<Message>, canonical_fragments: Vec<PromptFragment>, ) -> Self

Attach exact destination contracts and the immutable canonical history from which every initial, retry, failover, graph, resume and loop request is prepared.

pub fn with_protected_continuity(self, continuity: ProtectedContinuity) -> Self

Bind opaque provider continuity retained by the trusted host.

pub fn with_resolved_turn(self, turn: Arc<ResolvedTurn>) -> Self

pub fn with_canonical_receipt_store( self, store: Option<Arc<dyn PersistenceLayer>>, ) -> Self

Persist pre-format tool results through the trusted host’s run store.

pub fn with_mcp_preflight(self, preflight: Arc<McpPreflight>) -> Self

Use the host-prepared projection for all MCP advertisement and execution. Native implementations remain in their existing governed registries.

pub fn with_shadow_turn( self, turn: Arc<ResolvedTurn>, history: Vec<Message>, ) -> Self

pub fn with_world_state(self, state: Arc<WorldStateRuntime>) -> Self

Attach the host-owned world state for reduction and governed file reads.

pub fn with_failover( self, fallback_driver: Arc<dyn LlmDriver>, failover_config: FailoverConfig, ) -> Self

Attach one fallback driver and failover configuration.

When failover_config.enabled is true and the primary driver fails, the orchestrator will re-try the same request against the fallback. This compatibility helper uses the first configured fallback model.

pub fn with_failovers( self, fallback_drivers: Vec<(String, Arc<dyn LlmDriver>)>, failover_config: FailoverConfig, ) -> Self

Attach an ordered set of fallback model drivers.

pub fn with_health_monitor( self, health_monitor: Arc<ProviderHealthMonitor>, ) -> Self

Attach the shared provider-health monitor (CH-03). Driver successes/failures are recorded against it so ModelRouter and ProviderRegistry::resolve_to_llm_config see the outcome on the very next call.

pub fn build_fallback_driver( base_llm_config: &LlmConfig, fallback: &FallbackModel, ) -> Result<Arc<dyn LlmDriver>>

Build a driver for one FailoverConfig::fallback_models entry, reusing base_llm_config for every field except model/api_key/base_url (CH-03). Used by callers wiring with_failover from app config.

Errors

Returns an error if the underlying LLM client cannot be constructed.

pub fn llm_config(&self) -> &LlmConfig

Get the LLM configuration.

pub fn mcp(&self) -> &McpRegistry

Get the MCP registry.

pub fn with_tool_approval_gate(self, gate: ToolApprovalGate) -> Self

Set a tool approval gate that will be consulted before each tool call.

pub fn with_sandbox( self, runner: Arc<dyn SandboxRunner>, mode: ToolExecutionMode, ) -> Self

Attach a sandbox runner and execution mode for tool isolation.

Sandboxed mode requires isolation for every tool; Auto requires it for code-execution tools. A descriptor’s sandbox requirement always applies. Missing isolation or an unsupported tool adapter returns a failed result and never falls through to direct native/MCP execution.

pub fn with_tool_execution_mode(self, mode: ToolExecutionMode) -> Self

Apply the artifact’s execution mode even when no sandbox is available. Absence of a runner is not permission to discard an isolation policy.

pub fn with_sandbox_scope(self, scope: SandboxRun) -> Self

Bind the host-owned operation scope. The host must retain its lease and drain it before terminal completion; an unowned runner cannot execute.

pub fn with_resilience_policy(self, policy: ResiliencePolicy) -> Self

Apply bounded provider retry and stream-start policy to this run.

pub fn with_tool_output_policy(self, policy: TruncationPolicy) -> Self

Set the bound applied to every recorded tool result.

pub fn with_cache_strategy(self, strategy: Option<CacheStrategy>) -> Self

Apply the effective prompt-caching strategy to every policy-bearing request created by this orchestrator, including retries and failover.

pub async fn chat( &self, user_message: &str, ) -> Result<impl Stream<Item = NormalizedEvent> + Send>

Start a chat interaction with the given user message.

Returns a stream of NormalizedEvents that includes:

• StreamStart with a unique request ID
• MessageDelta for assistant text
• ToolCallDelta and ToolCallComplete for tool calls
• ToolResult after tool execution
• Done when complete

The orchestrator will automatically execute tool calls and feed results back to the LLM until a final response is produced.

pub async fn chat_with_history( &self, messages: Vec<Message>, ) -> Result<impl Stream<Item = NormalizedEvent> + Send + 'static + use<>>

Start a chat interaction with existing message history.

pub async fn chat_non_streaming(&self, messages: Vec<Message>) -> Result<String>

Non-streaming chat for simple requests (e.g., title generation).

This collects all message deltas into a single string response.

Trait Implementations

impl Clone for Orchestrator

fn clone(&self) -> Orchestrator

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Orchestrator

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.