### GET Request Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tools/http_client/index.html

Shows how to perform a GET request and access the response status, headers, and body.

```rust
let response = client.get("https://api.example.com/data").await?;
println!("Status: {}", response.status);
println!("Headers: {:?}", response.headers);
println!("Body: {}", response.body);
```

--------------------------------

### Basic Orchestration Setup with Parallel Mode

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/orchestration.rs.html

Demonstrates how to initialize an Orchestration system, add an agent, and run a query. This example uses the Parallel collaboration mode and specifies a maximum token limit for the responses.

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

# async {
let agent = Agent::new(
    "analyst",
    "Technical Analyst",
    Arc::new(OpenAIClient::new_with_model_string("key", "gpt-4o"))
);

let mut orchestration = Orchestration::new("tech-team", "Technical Advisory Orchestration")
    .with_mode(OrchestrationMode::Parallel)
    .with_max_tokens(8192);

orchestration.add_agent(agent).unwrap();

let response = orchestration.run("How should we architect this system?", 1).await.unwrap();
# };
```

--------------------------------

### Quick Start: Basic HTTP Client Usage

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tools/http_client/index.html

Demonstrates initializing the HttpClient and making simple GET and POST requests with JSON payloads. Requires tokio runtime.

```rust
use cloudllm::tools::HttpClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = HttpClient::new();

    // Simple GET request
    let response = client.get("https://api.example.com/users").await?;
    println!("Status: {}", response.status);
    println!("Body: {}", response.body);

    // POST with JSON payload
    let response = client.post(
        "https://api.example.com/users",
        serde_json::json!({ "name": "Alice", "email": "alice@example.com" })
    ).await?;

    Ok(())
}
```

--------------------------------

### Basic Setup for HttpClientProtocol

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tool_protocols/struct.HttpClientProtocol.html

Initializes an HttpClient and wraps it in an HttpClientProtocol. This is the fundamental setup required before using the HTTP tools.

```rust
use cloudllm::tools::HttpClient;
use cloudllm::tool_protocols::HttpClientProtocol;
use std::sync::Arc;

let http_client = Arc::new(HttpClient::new());
let http_protocol = Arc::new(HttpClientProtocol::new(http_client));
```

--------------------------------

### NoopStream on_tool_start Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/struct.NoopStream.html

Demonstrates the usage of the no-op tool start hook for NoopStream. This is useful when no specific action is required when a tool starts.

```rust
use cloudllm::planner::{NoopStream, StreamSink};

let sink = NoopStream;
sink.on_tool_start("tool", &serde_json::json!({})).await?;
```

--------------------------------

### End-to-End Planner Usage Example

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/planner.rs.html

Demonstrates the complete workflow of setting up and using the planner with a custom tool. This example requires an OpenAI API key and sets up an LLM session, registers a custom 'add' tool, and then uses the planner to resolve a user query.

```rust
use std::sync::Arc;

use cloudllm::clients::openai::{Model, OpenAIClient};
use cloudllm::tool_protocol::{ToolMetadata, ToolRegistry, ToolResult};
use cloudllm::tool_protocols::CustomToolProtocol;
use cloudllm::planner::{
    BasicPlanner, NoopMemory, NoopPolicy, NoopStream, Planner, PlannerContext, UserMessage,
};
use cloudllm::LLMSession;

# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
let client = Arc::new(OpenAIClient::new_with_model_enum(
    &std::env::var("OPEN_AI_SECRET")?,
    Model::GPT41Mini,
));

let mut session = LLMSession::new(client, "You are concise.".into(), 16_000);

let protocol = Arc::new(CustomToolProtocol::new());
protocol
    .register_tool(
        ToolMetadata::new("add", "Add two numbers"),
        Arc::new(|params| {
            let a = params["a"].as_f64().unwrap_or(0.0);
            let b = params["b"].as_f64().unwrap_or(0.0);
            Ok(ToolResult::success(serde_json::json!({ "result": a + b })))
        }),
    )
    .await;

let mut tools = ToolRegistry::new(protocol);
tools.discover_tools_from_primary().await?;

let planner = BasicPlanner::new();
let outcome = planner
    .plan(
        UserMessage::from("What is 2+2? Use the add tool."),
        PlannerContext {
            session: &mut session,
            tools: &tools,
            policy: &NoopPolicy,
            memory: &NoopMemory,
            streamer: &NoopStream,
            grok_tools: None,
            openai_tools: None,
            event_handler: None,
        },
    )
    .await?;

println!("{}", outcome.final_message);
# Ok(())
# }

```

--------------------------------

### Start HTTP Server Method

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/mcp_http_adapter/trait.HttpServerAdapter.html

The `start` method is required for all HttpServerAdapter implementations. It initiates the HTTP server using the provided configuration and exposes the specified tool protocol. The server must offer endpoints for listing and executing tools, and potentially for resource management.

```rust
fn start<'life0, 'async_trait>(
        &'life0 self,
        config: HttpServerConfig,
        protocol: Arc<dyn ToolProtocol>,
    ) -> Pin<Box<dyn Future<Output = Result<HttpServerInstance, Box<dyn Error + Sync + Send>>> + Send + 'async_trait>>
       where 'life0: 'async_trait,
             Self: 'async_trait;
```

--------------------------------

### Example: Creating and Converting ToolMetadata

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tool_protocol/struct.ToolMetadata.html

Demonstrates how to create ToolMetadata, add parameters, and convert it into a ToolDefinition. This example shows the typical workflow for defining a tool's schema.

```rust
use mcp::{ToolMetadata, ToolParameter, ToolParameterType};

let meta = ToolMetadata::new("calculator", "Evaluates a math expression")
    .with_parameter(
        ToolParameter::new("expression", ToolParameterType::String)
            .with_description("The expression to evaluate")
            .required(),
    );

let def = meta.to_tool_definition();
assert_eq!(def.name, "calculator");
let schema = &def.parameters_schema;
assert_eq!(schema["type"], "object");
assert!(schema["properties"]["expression"].is_object());
```

--------------------------------

### Example Usage of PlannerContext

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/struct.PlannerContext.html

Demonstrates how to construct a PlannerContext instance. This example shows the typical way to initialize the struct with necessary components and default or no-op implementations for optional or trait-based fields.

```rust
use cloudllm::planner::{NoopMemory, NoopPolicy, NoopStream, PlannerContext};
use cloudllm::tool_protocol::ToolRegistry;
use cloudllm::LLMSession;

fn example<'a>(session: &'a mut LLMSession, tools: &'a ToolRegistry) -> PlannerContext<'a> {
    PlannerContext {
        session,
        tools,
        policy: &NoopPolicy,
        memory: &NoopMemory,
        streamer: &NoopStream,
        grok_tools: None,
        openai_tools: None,
        event_handler: None,
    }
}
```

--------------------------------

### OrchestrationMode Examples

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/orchestration/enum.OrchestrationMode.html

Illustrates how to instantiate different OrchestrationMode variants. Includes examples for Parallel, Debate, Ralph, and AnthropicAgentTeams.

```rust
use cloudllm::orchestration::{OrchestrationMode, RalphTask, WorkItem};

// Simple parallel — every agent answers independently
let mode = OrchestrationMode::Parallel;

// Debate with convergence detection
let mode = OrchestrationMode::Debate {
    max_rounds: 5,
    convergence_threshold: Some(0.75),
};

// RALPH — agents work through a PRD checklist
let mode = OrchestrationMode::Ralph {
    tasks: vec![
        RalphTask::new("step1", "Step 1", "Do the first thing"),
        RalphTask::new("step2", "Step 2", "Do the second thing"),
    ],
    max_iterations: 3,
};

// AnthropicAgentTeams — decentralized task coordination
let mode = OrchestrationMode::AnthropicAgentTeams {
    pool_id: "research-2024".to_string(),
    tasks: vec![
        WorkItem::new("task1", "Research phase", "Find 5 sources"),
        WorkItem::new("task2", "Analysis phase", "Synthesize findings"),
    ],
    max_iterations: 10,
};
```

--------------------------------

### Start Server on Given Port

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/mcp_server_builder.rs.html

Starts the MCP server listening on localhost and the specified port. Returns a `HttpServerInstance` upon successful startup.

```rust
pub async fn start_on(
    self,
    port: u16,
) -> Result<HttpServerInstance, Box<dyn Error + Send + Sync>> {
    self.inner.start_on(port).await
}
```

--------------------------------

### Example: AllowAll Policy Implementation

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/trait.PolicyEngine.html

An example implementation of the PolicyEngine trait that allows all tool calls. This is useful for scenarios where no restrictions are needed.

```rust
use async_trait::async_trait;
use cloudllm::planner::{PolicyDecision, PolicyEngine, ToolCallRequest};

struct AllowAll;

#[async_trait]
impl PolicyEngine for AllowAll {
    async fn allow_tool_call(
        &self,
        _call: &ToolCallRequest,
    ) -> Result<PolicyDecision, Box<dyn std::error::Error + Send + Sync>> {
        Ok(PolicyDecision::Allow)
    }
}
```

--------------------------------

### StreamSink on_tool_start Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/trait.StreamSink.html

Example of implementing the `on_tool_start` method for the StreamSink trait. This method is called when a tool execution is about to begin.

```rust
use async_trait::async_trait;
use cloudllm::planner::StreamSink;

struct Logger;

#[async_trait]
impl StreamSink for Logger {
    async fn on_tool_start(
        &self,
        name: &str,
        _parameters: &serde_json::Value,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        println!("tool start: {name}");
        Ok(())
    }
}
```

--------------------------------

### Initialize CloudLLMConfig

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/config/struct.CloudLLMConfig.html

Example of manually constructing a CloudLLMConfig with a custom MentisDB directory.

```rust
use cloudllm::CloudLLMConfig;
use std::path::PathBuf;

let config = CloudLLMConfig {
    mentisdb_dir: PathBuf::from("/tmp/my_chains"),
};

```

--------------------------------

### Example Usage of ToolCallRequest

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/struct.ToolCallRequest.html

Demonstrates how to create and use a ToolCallRequest. This example shows initializing a request for a 'calculator' tool with specific parameters.

```rust
use cloudllm::planner::ToolCallRequest;

let call = ToolCallRequest {
    name: "calculator".to_string(),
    parameters: serde_json::json!({"expr": "2+2"}),
};
assert_eq!(call.name, "calculator");
```

--------------------------------

### Single Protocol Setup

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tool_protocols/index.html

Instantiates a single CustomToolProtocol and registers it with a ToolRegistry. Use this for basic setups with only one communication method.

```rust
let protocol = Arc::new(CustomToolProtocol::new());
let registry = ToolRegistry::new(protocol);
```

--------------------------------

### NoveltyAwareStrategy: Conditional Compression Example

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/context_strategy.rs.html

This example shows how to configure an Agent with NoveltyAwareStrategy, wrapping a SelfCompressionStrategy. It demonstrates setting custom thresholds for triggering compression based on token pressure and conversation novelty.

```rust
use cloudllm::Agent;
use cloudllm::context_strategy::{NoveltyAwareStrategy, SelfCompressionStrategy};
use cloudllm::clients::openai::OpenAIClient;
use std::sync::Arc;

let agent = Agent::new(
    "a1", "Agent",
    Arc::new(OpenAIClient::new_with_model_string("key", "gpt-4o")),
)
.context_collapse_strategy(Box::new(
    NoveltyAwareStrategy::new(Box::new(SelfCompressionStrategy::default()))
        .with_thresholds(0.85, 0.65, 0.25),
));
```

--------------------------------

### Create a New BasicPlanner

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/struct.BasicPlanner.html

Initializes a BasicPlanner with its default configuration. This is the most straightforward way to get a functional planner.

```rust
use cloudllm::planner::BasicPlanner;

let planner = BasicPlanner::new();
```

--------------------------------

### Quickstart: Build Client, Session, Send Message, and Inspect Tokens

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/llm_session/index.html

Demonstrates setting up an OpenAI client and an LLM session, sending a message, and then inspecting the token usage. Ensure the OPEN_AI_SECRET environment variable is set.

```rust
use std::sync::Arc;
use tokio::runtime::Runtime;
use cloudllm::client_wrapper::Role;
use cloudllm::clients::openai::OpenAIClient;
use cloudllm::clients::openai::Model;
use cloudllm::LLMSession;

// 1) Build the client & session
let secret_key : String = std::env::var("OPEN_AI_SECRET").expect("OPEN_AI_SECRET not set");
let client = OpenAIClient::new_with_model_enum(&secret_key, Model::GPT5Nano);
let mut session = LLMSession::new(
    Arc::new(client),
    "You are a bilingual crypto journalist.".into(),
    8_192  // max context window
);

// 2) Send a message
let rt = Runtime::new().unwrap();

let reply = rt.block_on(async {
   match session.send_message(Role::User, "Hola, ¿cómo estás?".into(), None).await {
       Ok(response) => response,
    Err(e) => {
        panic!("client error: {}", e);
    }
  } // await
});
println!("Assistant: {}", reply.content);

// 3) Inspect token usage so far
let usage = session.token_usage();
println!(
    "Input: {} tokens, Output: {} tokens, Total: {} tokens",
    usage.input_tokens, usage.output_tokens, usage.total_tokens
);
```

--------------------------------

### HTTP GET Request Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tool_protocols/struct.HttpClientProtocol.html

Example of a GET request to fetch data from a specified URL. Used for retrieving information from an endpoint.

```json
{
  "tool": "http_get",
  "parameters": {
    "url": "https://api.github.com/repos/anthropics/anthropic-sdk-python"
  }
}
```

--------------------------------

### Basic Orchestration Setup and Run

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/orchestration/index.html

Demonstrates how to initialize an Agent and an Orchestration engine, add the agent, and run a task. Use this for simple parallel processing tasks.

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

let agent = Agent::new(
    "analyst",
    "Technical Analyst",
    Arc::new(OpenAIClient::new_with_model_string("key", "gpt-4o"))
);

let mut orchestration = Orchestration::new("tech-team", "Technical Advisory Orchestration")
    .with_mode(OrchestrationMode::Parallel)
    .with_max_tokens(8192);

orchestration.add_agent(agent).unwrap();

let response = orchestration.run("How should we architect this system?", 1).await.unwrap();
```

--------------------------------

### Rust Result iter Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tools/calculator/type.CalculatorResult.html

Illustrates using iter to get an iterator that yields the Ok value once or yields nothing for an Err.

```rust
let x: Result<u32, &str> = Ok(7);
assert_eq!(x.iter().next(), Some(&7));

let x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter().next(), None);
```

--------------------------------

### Get Model Name Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/image_generation/trait.ImageGenerationClient.html

Shows how to retrieve the name of the image generation model currently in use by calling the `model_name` method.

```rust
use cloudllm::cloudllm::image_generation::ImageGenerationClient;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Using model: {}", client.model_name());
    Ok(())
}
```

--------------------------------

### Example Usage of LLMClientInfo

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/client_wrapper/trait.LLMClientInfo.html

Demonstrates how to use the LLMClientInfo trait to get provider and model names from an OpenRouterClient instance wrapped in an Arc.

```rust
use std::sync::Arc;
use cloudllm::client_wrapper::{ClientWrapper, LLMClientInfo};
use cloudllm::clients::openrouter::OpenRouterClient;

let key = std::env::var("OPENROUTER_API_KEY").expect("OPENROUTER_API_KEY");
let client: Arc<dyn ClientWrapper> = Arc::new(
    OpenRouterClient::new_with_model_str(&key, "qwen/qwen3.7-max"),
);
println!(
    "uninews routed through {} ({})",
    client.llm_provider_name().unwrap_or("unknown"),
    client.llm_model_name().unwrap_or("unknown"),
);
```

--------------------------------

### Example: Setting up Agent with SelfCompressionStrategy

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/context_strategy.rs.html

Demonstrates how to configure an Agent with the SelfCompressionStrategy, including attaching a MentisDb for persistent storage of summaries.

```rust
use cloudllm::Agent;
use cloudllm::context_strategy::SelfCompressionStrategy;
use mentisdb::MentisDb;
use cloudllm::clients::openai::OpenAIClient;
use std::sync::Arc;
use std::path::PathBuf;
use tokio::sync::RwLock;

# async {
let chain = Arc::new(RwLock::new(
    MentisDb::open(&PathBuf::from("/tmp/chains"), "a1", "Agent", None, None).unwrap()
));

let agent = Agent::new(
    "a1", "Agent",
    Arc::new(OpenAIClient::new_with_model_string("key", "gpt-4o")),
)
.with_mentisdb(chain)
.context_collapse_strategy(Box::new(SelfCompressionStrategy::default()));
# };
```

--------------------------------

### Initialize Orchestration with OpenAI Client

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/orchestration.rs.html

Illustrates the setup for an orchestration, including creating an OpenAI client and an agent, and initializing the orchestration with a parallel mode.

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

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


```

--------------------------------

### Logger Implementation of StreamSink

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/trait.StreamSink.html

An example implementation of the StreamSink trait that logs tool start, tool end, and final content to the console.

```rust
use async_trait::async_trait;
use cloudllm::planner::StreamSink;
use cloudllm::tool_protocol::ToolResult;

struct Logger;

#[async_trait]
impl StreamSink for Logger {
    async fn on_tool_start(
        &self,
        name: &str,
        _parameters: &serde_json::Value,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        println!("tool start: {name}");
        Ok(())
    }

    async fn on_tool_end(
        &self,
        name: &str,
        _result: &ToolResult,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        println!("tool end: {name}");
        Ok(())
    }

    async fn on_final(
        &self,
        content: &str,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        println!("final: {content}");
        Ok(())
    }
}
```

--------------------------------

### Example Usage of JsonlStorageAdapter

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/trait.StorageAdapter.html

Demonstrates how to instantiate and use the JsonlStorageAdapter to get its storage location. This adapter is suitable for JSON Lines formatted storage.

```rust
use std::path::PathBuf;
use mentisdb::{JsonlStorageAdapter, StorageAdapter};

let adapter = JsonlStorageAdapter::for_chain_key(PathBuf::from("/tmp/tc_store"), "demo");
let location = adapter.storage_location();

assert!(location.ends_with(".jsonl"));
```

--------------------------------

### BasicPlanner::new

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/struct.BasicPlanner.html

Creates a new BasicPlanner instance with default settings. This is the entry point for initializing the planner.

```APIDOC
## BasicPlanner::new

### Description
Creates a new planner with default settings.

### Method
`new()`

### Returns
- `Self`: A new instance of `BasicPlanner`.

### Example
```rust
use cloudllm::planner::BasicPlanner;

let planner = BasicPlanner::new();
```
```

--------------------------------

### Rust Result iter_mut Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tools/calculator/type.CalculatorResult.html

Shows using iter_mut to get a mutable iterator that yields a mutable reference to the Ok value once or yields nothing for an Err.

```rust
let mut x: Result<u32, &str> = Ok(7);
assert_eq!(x.iter_mut().next(), Some(&mut 7));

let mut x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter_mut().next(), None);
```

--------------------------------

### Example: Getting a Reference to Result Content

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tools/calculator/type.CalculatorResult.html

Shows how `as_ref` converts a reference to a Result into a Result of references, allowing inspection without consuming the original Result.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### Example: Clearing and Resetting Conversation

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/orchestration.rs.html

Shows how to clear the existing conversation history and then start a new topic, ensuring agents do not retain context from the previous discussion.

```rust
# use cloudllm::{Agent, orchestration::{Orchestration, OrchestrationMode}};
# use cloudllm::clients::openai::OpenAIClient;
# use std::sync::Arc;
# async {
# let c = Arc::new(OpenAIClient::new_with_model_string("key", "gpt-4o"));
# let mut orch = Orchestration::new("id", "name");
# orch.add_agent(Agent::new("a", "A", c)).unwrap();
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?;
# Ok::<(), Box<dyn std::error::Error + Send + Sync>>(()) 
# };
```

--------------------------------

### End-to-End Planner Usage Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/index.html

Demonstrates how to use the BasicPlanner for a single agent turn, including setting up an LLM session, registering a custom tool, and executing the plan. This is useful for understanding the full workflow of a planner interaction.

```rust
use std::sync::Arc;

use cloudllm::clients::openai::{Model, OpenAIClient};
use cloudllm::tool_protocol::{ToolMetadata, ToolRegistry, ToolResult};
use cloudllm::tool_protocols::CustomToolProtocol;
use cloudllm::planner::{
    BasicPlanner,
    NoopMemory,
    NoopPolicy,
    NoopStream,
    Planner,
    PlannerContext,
    UserMessage,
};
use cloudllm::LLMSession;

let client = Arc::new(OpenAIClient::new_with_model_enum(
    &std::env::var("OPEN_AI_SECRET")?,
    Model::GPT41Mini,
));

let mut session = LLMSession::new(client, "You are concise.".into(), 16_000);

let protocol = Arc::new(CustomToolProtocol::new());
protocol
    .register_tool(
        ToolMetadata::new("add", "Add two numbers"),
        Arc::new(|params| {
            let a = params["a"].as_f64().unwrap_or(0.0);
            let b = params["b"].as_f64().unwrap_or(0.0);
            Ok(ToolResult::success(serde_json::json!({ "result": a + b })))
        }),
    )
    .await;

let mut tools = ToolRegistry::new(protocol);
tools.discover_tools_from_primary().await?;

let planner = BasicPlanner::new();
let outcome = planner
    .plan(
        UserMessage::from("What is 2+2? Use the add tool."),
        PlannerContext {
            session: &mut session,
            tools: &tools,
            policy: &NoopPolicy,
            memory: &NoopMemory,
            streamer: &NoopStream,
            grok_tools: None,
            openai_tools: None,
            event_handler: None,
        },
    )
    .await?;

println!("{}", outcome.final_message);
```

--------------------------------

### Example: Sending a Message with GeminiClient

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/clients/gemini/struct.GeminiClient.html

Demonstrates how to instantiate a GeminiClient and send a user message, then print the response content. Requires GEMINI_KEY environment variable.

```rust
use std::sync::Arc;
use cloudllm::client_wrapper::{ClientWrapper, Message, Role};
use cloudllm::clients::gemini::{GeminiClient, Model};

let client = GeminiClient::new_with_model_enum(
    &std::env::var("GEMINI_KEY")?,
    Model::Gemini25Flash,
);
let resp = client.send_message(
    &[Message { role: Role::User, content: Arc::from("Hello"), tool_calls: vec![] }],
    None,
).await?;
println!("{}", resp.content);
```

--------------------------------

### Example: Getting a Mutable Reference to Result Content

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tools/calculator/type.CalculatorResult.html

Demonstrates `as_mut`, which converts a mutable reference to a Result into a mutable Result of mutable references, enabling in-place modification.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### PlannerContext Construction Example

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/planner.rs.html

Demonstrates how to construct a PlannerContext, which bundles all necessary inputs for a single planner turn. This is typically done at call time.

```rust
use cloudllm::planner::{NoopMemory, NoopPolicy, NoopStream, PlannerContext};
use cloudllm::tool_protocol::ToolRegistry;
use cloudllm::LLMSession;

fn example<'a>(session: &'a mut LLMSession, tools: &'a ToolRegistry) -> PlannerContext<'a> {
    PlannerContext {
        session,
        tools,
        policy: &NoopPolicy,
        memory: &NoopMemory,
        streamer: &NoopStream,
        grok_tools: None,
        openai_tools: None,
        event_handler: None,
    }
}

```

--------------------------------

### Creating Zeroed Arc with System Allocator

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tool_protocols/type.ToolFunction.html

Illustrates creating an `Arc` with memory zeroed before initialization using the `System` allocator and `new_zeroed_in`. The example uses `assume_init` to get the initialized value.

```rust
#![feature(allocator_api)]

use std::sync::Arc;
use std::alloc::System;

let zero = Arc::<u32, _>::new_zeroed_in(System);
let zero = unsafe { zero.assume_init() };

assert_eq!(*zero, 0)

```

--------------------------------

### EchoPlanner Implementation of Planner Trait

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/trait.Planner.html

An example implementation of the Planner trait that simply echoes the user's input as the final message. This is useful for basic testing or as a starting point for more complex planners.

```rust
use async_trait::async_trait;
use cloudllm::planner::{Planner, PlannerContext, PlannerOutcome, UserMessage};

struct EchoPlanner;

#[async_trait(?Send)]
impl Planner for EchoPlanner {
    async fn plan(
        &self,
        input: UserMessage,
        _ctx: PlannerContext<'_>,
    ) -> Result<PlannerOutcome, Box<dyn std::error::Error + Send + Sync>> {
        Ok(PlannerOutcome {
            final_message: input.content,
            tool_calls: Vec::new(),
            memory_writes: Vec::new(),
            tokens_used: None,
        })
    }
}
```

--------------------------------

### Quick Start: CloudLLM Calculator

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tools/calculator/index.html

Demonstrates basic usage of the Calculator tool, including arithmetic, trigonometry, and statistics. Ensure you have the `cloudllm` crate and `tokio` runtime set up.

```rust
use cloudllm::tools::Calculator;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let calc = Calculator::new();

    // Simple arithmetic
    let result = calc.evaluate("2 + 2 * 3").await?;
    println!("2 + 2 * 3 = {}", result); // 8.0

    // Trigonometry
    let result = calc.evaluate("sin(0)").await?;
    println!("sin(0) = {}", result); // 0.0

    // Statistics
    let result = calc.evaluate("mean([1, 2, 3, 4, 5])").await?;
    println!("mean([1,2,3,4,5]) = {}", result); // 3.0

    Ok(())
}
```

--------------------------------

### Initialize and Execute BashTool

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tools/bash/index.html

Demonstrates how to create a BashTool instance with custom security settings and execute a command. Includes timeout, output size cap, CWD restriction, and denied commands.

```rust
use cloudllm::tools::{BashTool, Platform};
use std::path::PathBuf;

let bash = BashTool::new(Platform::Linux)
    .with_timeout(15)
    .with_max_output_size(1 * 1024 * 1024)        // 1 MiB cap
    .with_cwd_restriction(PathBuf::from("/tmp/sandbox"))
    .with_denied_commands(vec![
        "sudo".to_string(),
        "su".to_string(),
        "bash".to_string(),   // block trampoline bypass
        "sh".to_string(),
        "eval".to_string(),
        "exec".to_string(),
    ]);

let result = bash.execute("find . -name '*.log' | head -20").await?;
println!("{}", result.stdout);
```

--------------------------------

### Arc::into_raw and Arc::from_raw Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tool_protocols/type.ToolFunction.html

Demonstrates the use of `Arc::into_raw` to get a raw pointer and `Arc::from_raw` to reconstruct an Arc. It also shows how to manually manage strong counts using `Arc::increment_strong_count` and `Arc::decrement_strong_count`. Ensure the pointer is valid and the Arc is not released before calling these methods.

```rust
use std::sync::Arc;

let five = Arc::new(5);

unsafe {
    let ptr = Arc::into_raw(five);
    Arc::increment_strong_count(ptr);

    // Those assertions are deterministic because we haven't shared
    // the `Arc` between threads.
    let five = Arc::from_raw(ptr);
    assert_eq!(2, Arc::strong_count(&five));
    Arc::decrement_strong_count(ptr);
    assert_eq!(1, Arc::strong_count(&five));
}
```

--------------------------------

### Get Cause for HttpClientError (Deprecated)

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tools/http_client/struct.HttpClientError.html

Deprecated method for getting the cause of the error. Replaced by Error::source.

```rust
fn cause(&self) -> Option<&dyn Error>
```

--------------------------------

### Example: Sending a Message with GrokClient

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/clients/grok.rs.html

Demonstrates how to initialize a `GrokClient` with a specific model and send a user message. Requires the XAI_KEY environment variable to be set.

```rust
use std::sync::Arc;
use cloudllm::client_wrapper::{ClientWrapper, Message, Role};
use cloudllm::clients::grok::{GrokClient, Model};

# #[tokio::main]
# async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = GrokClient::new_with_model_enum(&std::env::var("XAI_KEY")?, Model::Grok3Mini);
let resp = client.send_message(
    &[Message { role: Role::User, content: Arc::from("Hello"), tool_calls: vec![] }],
    None,
).await?;
println!("{}", resp.content);
# Ok(())
# }
```

--------------------------------

### Basic Image Generation Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/image_generation/index.html

Demonstrates how to generate a single image with default options and retrieve its URL. Ensure a client is initialized before use.

```rust
use cloudllm::cloudllm::image_generation::{ImageGenerationClient, ImageGenerationOptions};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Create a client (e.g., OpenAI)

    let options = ImageGenerationOptions {
        aspect_ratio: Some("16:9".to_string()),
        num_images: Some(1),
        response_format: Some("url".to_string()),
    };

    let response = client.generate_image(
        "A futuristic city at sunset",
        options,
    ).await?;

    for image in response.images {
        if let Some(url) = image.url {
            println!("Generated image: {}", url);
        }
    }
    Ok(())
}
```

--------------------------------

### initialize

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tool_protocol/trait.ToolProtocol.html

Initializes or connects to the tool protocol. This is an optional setup step that may be required before using other protocol methods.

```APIDOC
## initialize

### Description
Initialize/connect to the tool protocol.

### Method
`initialize`

### Parameters
None

### Response
#### Success Response
- `()` - Indicates successful initialization.
#### Error Response
- `Box<dyn Error + Sync + Send>` - An error that occurred during initialization.
```

--------------------------------

### MCP Memory Protocol Client Setup

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/tool_protocols.rs.html

Demonstrates how to set up and use the McpMemoryProtocol client to interact with a remote Memory service. Requires async context.

```rust
use cloudllm::tool_protocols::McpMemoryProtocol;
use cloudllm::tool_protocol::ToolProtocol;

# async {

```

--------------------------------

### HTTP GET Request

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/tool_protocols.rs.html

Makes an HTTP GET request to a specified URL. It returns the status, body, and headers of the response.

```APIDOC
## http_get

### Description
Makes an HTTP GET request to a specified URL. It returns the status, body, and headers of the response.

### Method
GET

### Endpoint
`/tools/http_get`

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to request (e.g., 'https://api.example.com/data')

### Response
#### Success Response (200)
- **status** (integer) - The HTTP status code of the response.
- **body** (json) - The response body.
- **headers** (object) - The response headers.

#### Response Example
```json
{
  "status": 200,
  "body": {
    "message": "Success"
  },
  "headers": {
    "Content-Type": "application/json"
  }
}
```
```

--------------------------------

### Setting up and Running AnthropicAgentTeams

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/orchestration.rs.html

Demonstrates how to initialize AnthropicAgentTeams with system context, add agents, and run a coordination task. Ensure to adjust max_iterations based on task and agent counts.

```rust
    let mut orchestration = AnthropicAgentTeams::new("research-team", 8)?;
    orchestration
        .with_system_context(
            "You are a specialized researcher in a coordinated team. Autonomously claim and complete tasks from the shared pool. Work collaboratively and focus on scientific accuracy."
        )
        .with_max_tokens(4096);

    orchestration.add_agent(researcher)?;
    orchestration.add_agent(analyst)?;
    // ... add other agents

    // Run the team coordination
    let prompt = "Prepare a comprehensive report on NMN+ for Alzheimer's recovery";
    let response = orchestration.run(prompt, 1).await?;

    println!("Completed: {}/{} tasks",
        (response.convergence_score.unwrap_or(0.0) * response.messages.len() as f32) as usize,
        task_count
    );
    # Ok(())
    # }

```

--------------------------------

### HTTP DELETE Request Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tool_protocols/struct.HttpClientProtocol.html

Example of a DELETE request to remove a resource at a specified URL. Used for deleting data.

```json
{
  "tool": "http_delete",
  "parameters": {
    "url": "https://api.example.com/users/123"
  }
}
```

--------------------------------

### StreamSink on_tool_end Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/trait.StreamSink.html

Example of implementing the `on_tool_end` method for the StreamSink trait. This method is called when a tool execution has completed.

```rust
use async_trait::async_trait;
use cloudllm::planner::StreamSink;
use cloudllm::tool_protocol::ToolResult;

struct Logger;

#[async_trait]
impl StreamSink for Logger {
    async fn on_tool_end(
        &self,
        name: &str,
        _result: &ToolResult,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        println!("tool end: {name}");
        Ok(())
    }
}
```

--------------------------------

### Building a Custom Client Wrapper with CloudLLM Utilities

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/clients/common/index.html

Demonstrates how to create a custom client wrapper by integrating CloudLLM's shared HTTP client and request sending utilities. This example shows how to adapt messages for an OpenAI-compatible API and handle responses.

```rust
use std::sync::Arc;

use async_trait::async_trait;
use cloudllm::client_wrapper::{ClientWrapper, Message, Role, ToolDefinition, TokenUsage};
use cloudllm::clients::common::{get_shared_http_client, send_and_track};
use openai_rust2 as openai_rust;
use tokio::sync::Mutex;

struct MyHostedClient {
    client: openai_rust::Client,
    model: String,
    usage: Mutex<Option<TokenUsage>>,
}

impl MyHostedClient {
    fn new(key: &str, base_url: &str, model: &str) -> Self {
        Self {
            client: openai_rust::Client::new_with_client_and_base_url(
                key,
                get_shared_http_client().clone(),
                base_url,
            ),
            model: model.to_owned(),
            usage: Mutex::new(None),
        }
    }
}

#[async_trait]
impl ClientWrapper for MyHostedClient {
    fn model_name(&self) -> &str {
        &self.model
    }

    fn provider_name(&self) -> &str {
        "MyHosted"
    }

    async fn send_message(
        &self,
        messages: &[Message],
        _tools: Option<Vec<ToolDefinition>>,
    ) -> Result<Message, Box<dyn std::error::Error>> {
        let formatted = messages
            .iter()
            .map(|msg| openai_rust::chat::Message {
                role: match msg.role {
                    Role::System => "system".into(),
                    Role::User => "user".into(),
                    Role::Assistant => "assistant".into(),
                    _ => "user".into(),
                },
                content: msg.content.as_ref().to_owned(),
            })
            .collect();

        let reply = send_and_track(
            &self.client,
            &self.model,
            formatted,
            Some("/v1/chat/completions".to_string()),
            &self.usage,
            None,
        )
        .await?;

        Ok(Message {
            role: Role::Assistant,
            content: Arc::<str>::from(reply),
            tool_calls: vec![],
        })
    }
}

```

--------------------------------

### Initialize BashProtocol

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tool_protocols/struct.BashProtocol.html

Demonstrates how to create a new BashProtocol instance by wrapping a BashTool. The BashTool can be configured with a platform and a timeout.

```rust
use cloudllm::tools::{BashTool, Platform};
use cloudllm::tool_protocols::BashProtocol;
use std::sync::Arc;

let bash_tool = Arc::new(BashTool::new(Platform::Linux).with_timeout(30));
let protocol = BashProtocol::new(bash_tool);
```

--------------------------------

### Create New LLMSession and Clone Client

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/llm_session/struct.LLMSession.html

Demonstrates how to initialize an LLMSession and then clone its underlying client to create a new session with a different system prompt but shared provider.

```rust
use cloudllm::LLMSession;
use cloudllm::clients::openai::OpenAIClient;
use std::sync::Arc;

let session = LLMSession::new(
    Arc::new(OpenAIClient::new_with_model_string("key", "gpt-4o")),
    "system".into(),
    8_192,
);

// Clone the client to create a sibling session
let sibling = LLMSession::new(
    session.client().clone(),
    "different system prompt".into(),
    4_096,
);

```

--------------------------------

### Multiple Protocols Implementation

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tool_protocol/struct.ToolRegistry.html

Example demonstrating how to manage multiple ToolProtocols within a single ToolRegistry. This allows agents to access tools from diverse sources.

```rust
use async_trait::async_trait;
use mcp::{ToolMetadata, ToolProtocol, ToolRegistry, ToolResult};
use std::sync::Arc;

struct LocalProtocol;
struct RemoteProtocol;

#[async_trait]
impl ToolProtocol for LocalProtocol {
    async fn execute(
        &self,
        _tool_name: &str,
        _parameters: serde_json::Value,
    ) -> Result<ToolResult, Box<dyn std::error::Error + Send + Sync>> {
        Ok(ToolResult::success(serde_json::json!({"source": "local"})))
    }

    async fn list_tools(
        &self,
    ) -> Result<Vec<ToolMetadata>, Box<dyn std::error::Error + Send + Sync>> {
        Ok(vec![])
    }
}

#[async_trait]
impl ToolProtocol for RemoteProtocol {
    async fn execute(
        &self,
        _tool_name: &str,
        _parameters: serde_json::Value,
    ) -> Result<ToolResult, Box<dyn std::error::Error + Send + Sync>> {
        Ok(ToolResult::success(serde_json::json!({"source": "remote"})))
    }

    async fn list_tools(
        &self,
    ) -> Result<Vec<ToolMetadata>, Box<dyn std::error::Error + Send + Sync>> {
        Ok(vec![])
    }
}

let mut registry = ToolRegistry::empty();

// Add local tools
registry.add_protocol(
    "local",
    Arc::new(LocalProtocol)
).await.ok();

// Add remote MCP server
registry.add_protocol(
    "youtube",
    Arc::new(RemoteProtocol)
).await.ok();

// Agent transparently accesses both
```

--------------------------------

### Get Description for HttpClientError (Deprecated)

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/tools/http_client/struct.HttpClientError.html

Deprecated method for getting a string description of the error. It is recommended to use the Display implementation or to_string() instead.

```rust
fn description(&self) -> &str
```

--------------------------------

### HttpServerAdapter::start

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/mcp_http_adapter/trait.HttpServerAdapter.html

Starts the HTTP server with the provided configuration and tool protocol. This method is required for any implementation of the HttpServerAdapter trait.

```APIDOC
## POST /tools/list

### Description
List all available tools from the protocol.

### Method
POST

### Endpoint
/tools/list

### Request Body
This endpoint expects a request body, but the specific schema is not detailed in the source.

### Response
#### Success Response
Details of the success response are not provided in the source.

## POST /tools/execute

### Description
Execute a tool with given parameters.

### Method
POST

### Endpoint
/tools/execute

### Request Body
This endpoint expects a request body, but the specific schema is not detailed in the source.

### Response
#### Success Response
Details of the success response are not provided in the source.

## POST /resources/list

### Description
List all available resources (if protocol supports).

### Method
POST

### Endpoint
/resources/list

### Request Body
This endpoint expects a request body, but the specific schema is not detailed in the source.

### Response
#### Success Response
Details of the success response are not provided in the source.

## POST /resources/read

### Description
Read a resource by URI (if protocol supports).

### Method
POST

### Endpoint
/resources/read

### Request Body
This endpoint expects a request body, but the specific schema is not detailed in the source.

### Response
#### Success Response
Details of the success response are not provided in the source.
```

--------------------------------

### StreamSink on_final Example

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/trait.StreamSink.html

Example of implementing the `on_final` method for the StreamSink trait. This method is called to notify the final response content for a turn.

```rust
use async_trait::async_trait;
use cloudllm::planner::StreamSink;

struct Logger;

#[async_trait]
impl StreamSink for Logger {
    async fn on_final(
        &self,
        content: &str,
    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
        println!("final: {content}");
        Ok(())
    }
}
```

--------------------------------

### Example: DenyAll Policy Implementation

Source: https://docs.rs/cloudllm/0.15.9/cloudllm/cloudllm/planner/trait.PolicyEngine.html

An example implementation of the PolicyEngine trait that denies all tool calls. This can be used for testing or as a default restrictive policy.

```rust
use async_trait::async_trait;
use cloudllm::planner::{PolicyDecision, PolicyEngine, ToolCallRequest};

struct DenyAll;

#[async_trait]
impl PolicyEngine for DenyAll {
    async fn allow_tool_call(
        &self,
        _call: &ToolCallRequest,
    ) -> Result<PolicyDecision, Box<dyn std::error::Error + Send + Sync>> {
        Ok(PolicyDecision::Deny("blocked".to_string()))
    }
}
```

--------------------------------

### Initialize and Configure Orchestration

Source: https://docs.rs/cloudllm/0.15.9/src/cloudllm/cloudllm/orchestration.rs.html

Demonstrates creating a new Orchestration instance, setting its mode to RoundRobin, defining a system context, and setting a maximum token limit. It also shows how to add agents and run a task.

```rust
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);
```