Struct Orchestration 

pub struct Orchestration {
    pub id: String,
    pub name: String,
    /* private fields */
}

The orchestration engine that coordinates multiple Agents in a chosen OrchestrationMode.

An Orchestration owns a set of agents, a collaboration mode, and a running conversation history. Call Orchestration::run to execute a multi-agent conversation and receive an OrchestrationResponse.

Examples

use cloudllm::{Agent, orchestration::{Orchestration, OrchestrationMode}};
use cloudllm::clients::openai::OpenAIClient;
use std::sync::Arc;

let client = || Arc::new(OpenAIClient::new_with_model_string("key", "gpt-4o"));

let mut orch = Orchestration::new("team", "My Team")
    .with_mode(OrchestrationMode::RoundRobin)
    .with_system_context("You are expert engineers.")
    .with_max_tokens(16384);

orch.add_agent(Agent::new("alice", "Alice", client())).unwrap();
orch.add_agent(Agent::new("bob", "Bob", client())).unwrap();

let result = orch.run("Design a REST API", 2).await.unwrap();
println!("{} messages over {} rounds", result.messages.len(), result.round);

Fields

id: String

Stable identifier used for logging, metrics, and external integrations.

name: String

Human-readable name of this orchestration.

Implementations

impl Orchestration

pub fn new(id: impl Into<String>, name: impl Into<String>) -> Self

Create an orchestration with the provided identifiers.

Defaults to OrchestrationMode::Parallel, a generic system context, and an 8 192-token budget. Use the with_* builder methods to customise.

Examples

use cloudllm::orchestration::Orchestration;

let orch = Orchestration::new("qa-team", "QA Review Team");
assert_eq!(orch.id, "qa-team");
assert_eq!(orch.name, "QA Review Team");

pub fn with_mode(self, mode: OrchestrationMode) -> Self

Select the collaboration mode used during Orchestration::run (builder pattern).

Examples

use cloudllm::orchestration::{Orchestration, OrchestrationMode};

let orch = Orchestration::new("id", "name")
    .with_mode(OrchestrationMode::Debate {
        max_rounds: 3,
        convergence_threshold: Some(0.8),
    });

pub fn with_system_context(self, context: impl Into<String>) -> Self

Override the default system context prompt shared across agents (builder pattern).

This string is passed as the system prompt in every LLM call made during Orchestration::run.

Examples

use cloudllm::orchestration::Orchestration;

let orch = Orchestration::new("id", "name")
    .with_system_context("You are senior Rust engineers reviewing a PR.");

pub fn with_max_tokens(self, max_tokens: usize) -> Self

Override the soft token budget used for context trimming (builder pattern).

The budget is forwarded to each agent’s LLM call so that overly-long conversation histories can be trimmed before transmission.

Examples

use cloudllm::orchestration::Orchestration;

let orch = Orchestration::new("id", "name")
    .with_max_tokens(32768);

pub fn with_event_handler(self, handler: Arc<dyn EventHandler>) -> Self

Attach an EventHandler for orchestration and agent lifecycle events (builder pattern).

The handler receives OrchestrationEvents directly from the orchestration engine (run start/end, round boundaries, RALPH progress, etc.). Additionally, the handler is automatically propagated to every agent added via add_agent, so those agents will also emit their AgentEvents through the same handler. This gives you a unified stream of both orchestration-level and agent-level events through a single callback.

Example

use cloudllm::orchestration::{Orchestration, OrchestrationMode};
use cloudllm::event::{EventHandler, OrchestrationEvent};
use async_trait::async_trait;
use std::sync::Arc;

struct MyHandler;
#[async_trait]
impl EventHandler for MyHandler {
    async fn on_orchestration_event(&self, event: &OrchestrationEvent) {
        println!("{:?}", event);
    }
}

let orch = Orchestration::new("id", "name")
    .with_mode(OrchestrationMode::RoundRobin)
    .with_event_handler(Arc::new(MyHandler));

pub fn add_agent(&mut self, agent: Agent) -> Result<(), OrchestrationError>

Register a new agent with the orchestration.

Returns an error if an agent with the same Agent::id is already registered. The insertion order determines the round-robin sequence used by RoundRobin, Debate, and Ralph modes.

Examples

use cloudllm::{Agent, orchestration::Orchestration};
use cloudllm::clients::openai::OpenAIClient;
use std::sync::Arc;

let mut orch = Orchestration::new("id", "name");
let client = Arc::new(OpenAIClient::new_with_model_string("key", "gpt-4o"));

orch.add_agent(Agent::new("analyst", "Analyst", client)).unwrap();

// Duplicate ID is an error
assert!(orch.add_agent(Agent::new("analyst", "Analyst 2", client2)).is_err());

pub fn remove_agent(&mut self, id: &str) -> Option<Agent>

Remove and return an agent by its identifier.

Returns None if no agent with the given ID exists. Removing an agent also removes it from the round-robin order.

Examples

let mut orch = Orchestration::new("id", "name");

let removed = orch.remove_agent("a1");
assert!(removed.is_some());
assert!(orch.remove_agent("a1").is_none()); // already gone

pub fn get_agent(&self, id: &str) -> Option<&Agent>

Borrow a registered agent by its identifier.

Examples

let mut orch = Orchestration::new("id", "name");

if let Some(agent) = orch.get_agent("a1") {
    println!("Found agent: {}", agent.name);
}

pub fn list_agents(&self) -> Vec<&Agent>

List agents in their insertion order.

The returned order matches the round-robin sequence used by RoundRobin, Debate, and Ralph modes.

Examples

let mut orch = Orchestration::new("id", "name");

for agent in orch.list_agents() {
    println!("{}: {}", agent.id, agent.name);
}

pub async fn run( &mut self, prompt: &str, rounds: usize, ) -> Result<OrchestrationResponse, Box<dyn Error + Send + Sync>>

Execute a multi-agent discussion according to the configured OrchestrationMode.

The prompt is broadcast to all agents according to the active mode.

Parameters

• prompt — The user question or task description.
• rounds — Number of iterations for fixed-round modes (Parallel, RoundRobin, Moderated). Ignored by Hierarchical (which runs once per layer), Debate (uses max_rounds), and Ralph (uses max_iterations).

Errors

Returns OrchestrationError::NoAgents if no agents have been registered. May also surface errors from individual agent LLM calls or tokio task joins.

Examples

let response = orch.run("Summarise this paper", 2).await?;
assert!(response.is_complete);

pub fn get_conversation_history(&self) -> &[OrchestrationMessage]

Return a slice of all messages accumulated since the orchestration was created (or since the last Orchestration::clear_history call).

This includes the initial user prompt(s) and every agent response across all rounds.

Examples

let _ = orch.run("Hello", 1).await?;

let history = orch.get_conversation_history();
println!("{} messages in history", history.len());

pub fn clear_history(&mut self)

Remove all historical messages, resetting the orchestration state.

Call this between unrelated discussions when you want to reuse the same Orchestration instance without carrying over prior context.

Examples

let _ = orch.run("First topic", 1).await?;
orch.clear_history();

// Start fresh — agents will not see "First topic" responses
let _ = orch.run("Second topic", 1).await?;