feat: impl llms collab && add new examples && update docs. (#141)

Signed-off-by: wiseaidev <oss@wiseai.dev>

Author: wiseaidev

Cargo.lock

@@ -25,6 +25,7 @@ iac-rs = { version = "0.0.8", path = "./iac-rs" }
 chrono = "0.4.41"
 derivative = "2.2.0"
 duckduckgo = "0.3.1"
+phf = { version = "0.13.1", features = ["macros"] }
 
 [profile.release]
 opt-level = "z"

Cargo.toml

@@ -342,6 +342,82 @@ async fn main() {
 }
 ```
 
+#### 🤝 Collaborative Multi-Provider Agent (SDK: `col` feature)
+
+Attach a [`CollabPool`] to `AutoGPT` so the orchestrator executes agents
+sequentially in round-robin provider order. Each entry in `agents![...]`
+corresponds to one entry in the pool's provider list.
+
+```rust
+use autogpt::prelude::*;
+
+#[tokio::main]
+async fn main() {
+    let persona = "Lead Architect";
+    let behavior = "Design a microservices architecture for an e-commerce platform.";
+
+    let pool = CollabPool::from_providers(vec![
+        "gemini".to_string(),
+        "openai".to_string(),
+    ]);
+
+    let agent_a = ArchitectGPT::new(persona, behavior).await;
+    let agent_b = ArchitectGPT::new(persona, behavior).await;
+
+    let autogpt = AutoGPT::default()
+        .with(agents![agent_a, agent_b])
+        .with_collab_pool(pool)
+        .build()
+        .expect("Failed to build AutoGPT");
+
+    match autogpt.run().await {
+        Ok(response) => println!("{}", response),
+        Err(err) => eprintln!("Agent error: {:?}", err),
+    }
+}
+```
+
+> [!NOTE]
+> **How it works**: `AutoGPT::run()` picks a random starting provider via
+> [`CollabSelection::Random`], then executes each agent in the `agents![...]`
+> list sequentially mapped to pool providers in round-robin order.
+> Enable `CollabSelection::Explicit(name)` to always start from a specific
+> provider.
+
+#### 🧠 Agent Metacognition SDK (`mta` feature)
+
+The `mta` feature embeds a [`MetacognitionEngine`] inside every [`AgentGPT`]
+that records task outcomes and injects strategy context into prompts.
+
+```rust
+use autogpt::prelude::*;
+
+#[tokio::main]
+async fn main() {
+    let persona = "Research Analyst";
+    let behavior = "Summarise research papers.";
+
+    let mut agent = AgentGPT::new_borrowed(persona, behavior);
+
+    agent.record_task_outcome("parse pdf", "success", 0);
+    agent.record_task_outcome("extract sections", "failed", 2);
+
+    println!("{}", agent.metacognition_context());
+    println!("Should adjust? {}", agent.should_adjust_strategy());
+}
+```
+
+| Method                                        | Description                                         |
+| --------------------------------------------- | --------------------------------------------------- |
+| `record_task_outcome(task, outcome, retries)` | Record a task result and generate an insight entry  |
+| `metacognition_context()`                     | Returns the LLM-injectable strategy context string  |
+| `should_adjust_strategy()`                    | `true` when the engine recommends a strategy change |
+| `consecutive_failures()`                      | Number of consecutive failing tasks                 |
+
+The engine triggers automatically inside `GenericAgent` every 3 tasks or
+after 2+ consecutive failures, querying the LLM to produce strategy
+adjustments. The TUI status bar shows **MetaCognizing** during this phase.
+
 ## 🛠️ CLI Usage
 
 The CLI provides a convenient means to interact with the code generation ecosystem. The `autogpt` crate bundles two binaries in a single package:
@@ -501,6 +577,35 @@ This opens a conversational AI shell where you can:
 - Press `ESC` to interrupt a running generation.
 - Type `exit` or `quit` to save the session and close.
 
+#### 🤝 Collaborative Multi-Provider Mode (`--collab`, requires `col + cli`)
+
+Collab mode spawns one `GenericAgent` per configured provider (all providers
+with an API key set in the environment) and distributes the task across them
+in round-robin order with per-model fallback:
+
+```sh
+# Build with collab support:
+cargo run --features "cli,col,gem,oai,xai" --bin autogpt -- --collab
+
+# Or install:
+cargo install autogpt --features "cli,col,gem,oai"
+autogpt --collab
+```
+
+**Provider discovery**: Any provider feature compiled in whose API key env var
+is set at runtime is automatically added to the pool (e.g. `GEMINI_API_KEY`,
+`OPENAI_API_KEY`, `XAI_API_KEY`).
+
+**Fallback behaviour**:
+
+| Event                             | Action                                        |
+| --------------------------------- | --------------------------------------------- |
+| Rate-limit / quota error          | Rotate to next model within the same provider |
+| All models for provider exhausted | Remove provider from pool, route to next      |
+| All providers exhausted           | Log `⚠ All collab providers exhausted.`       |
+
+The TUI logs the active pool and each routing step with `🤝`/`🔀` prefixes.
+
 #### ⚡ Direct Prompt Mode
 
 For a quick one-shot non-interactive prompt:

INSTALLATION.md

@@ -37,6 +37,7 @@ auto-derive = { workspace = true }
 chrono = { workspace = true }
 derivative = { workspace = true }
 duckduckgo = { workspace = true }
+phf = { workspace = true }
 iac-rs = { workspace = true, optional = true }
 
 uuid = { version = "=1.23.1", features = ["v4"] }
@@ -79,17 +80,20 @@ unicode-width = { version = "0.2.2", optional = true }
 default = []
 gpt = []
 mop = []
-img = ["getimg"]
+mta = []
+col = []
+mcp = ["dirs"]
 git = ["git2"]
 gem = ["gems"]
 xai = ["x-ai"]
 net = ["iac-rs"]
+img = ["getimg"]
 mail = ["nylas"]
+co = ["cohere-rust"]
 oai = ["openai_dive"]
 mem = ["pinecone-sdk"]
-cld = ["anthropic-ai-sdk"]
-co = ["cohere-rust"]
 hf = ["api_huggingface"]
+cld = ["anthropic-ai-sdk"]
 cli = [
     "clap",
     "dirs",
@@ -112,8 +116,6 @@ cli = [
     "tracing-appender",
     "tracing-subscriber",
 ]
-mcp = ["dirs"]
-mta = []
 
 [package.metadata.docs.rs]
 all-features = true

autogpt/Cargo.toml

@@ -342,6 +342,82 @@ async fn main() {
 }
 ```
 
+#### 🤝 Collaborative Multi-Provider Agent (SDK: `col` feature)
+
+Attach a [`CollabPool`] to `AutoGPT` so the orchestrator executes agents
+sequentially in round-robin provider order. Each entry in `agents![...]`
+corresponds to one entry in the pool's provider list.
+
+```rust
+use autogpt::prelude::*;
+
+#[tokio::main]
+async fn main() {
+    let persona = "Lead Architect";
+    let behavior = "Design a microservices architecture for an e-commerce platform.";
+
+    let pool = CollabPool::from_providers(vec![
+        "gemini".to_string(),
+        "openai".to_string(),
+    ]);
+
+    let agent_a = ArchitectGPT::new(persona, behavior).await;
+    let agent_b = ArchitectGPT::new(persona, behavior).await;
+
+    let autogpt = AutoGPT::default()
+        .with(agents![agent_a, agent_b])
+        .with_collab_pool(pool)
+        .build()
+        .expect("Failed to build AutoGPT");
+
+    match autogpt.run().await {
+        Ok(response) => println!("{}", response),
+        Err(err) => eprintln!("Agent error: {:?}", err),
+    }
+}
+```
+
+> [!NOTE]
+> **How it works**: `AutoGPT::run()` picks a random starting provider via
+> [`CollabSelection::Random`], then executes each agent in the `agents![...]`
+> list sequentially mapped to pool providers in round-robin order.
+> Enable `CollabSelection::Explicit(name)` to always start from a specific
+> provider.
+
+#### 🧠 Agent Metacognition SDK (`mta` feature)
+
+The `mta` feature embeds a [`MetacognitionEngine`] inside every [`AgentGPT`]
+that records task outcomes and injects strategy context into prompts.
+
+```rust
+use autogpt::prelude::*;
+
+#[tokio::main]
+async fn main() {
+    let persona = "Research Analyst";
+    let behavior = "Summarise research papers.";
+
+    let mut agent = AgentGPT::new_borrowed(persona, behavior);
+
+    agent.record_task_outcome("parse pdf", "success", 0);
+    agent.record_task_outcome("extract sections", "failed", 2);
+
+    println!("{}", agent.metacognition_context());
+    println!("Should adjust? {}", agent.should_adjust_strategy());
+}
+```
+
+| Method                                        | Description                                         |
+| --------------------------------------------- | --------------------------------------------------- |
+| `record_task_outcome(task, outcome, retries)` | Record a task result and generate an insight entry  |
+| `metacognition_context()`                     | Returns the LLM-injectable strategy context string  |
+| `should_adjust_strategy()`                    | `true` when the engine recommends a strategy change |
+| `consecutive_failures()`                      | Number of consecutive failing tasks                 |
+
+The engine triggers automatically inside `GenericAgent` every 3 tasks or
+after 2+ consecutive failures, querying the LLM to produce strategy
+adjustments. The TUI status bar shows **MetaCognizing** during this phase.
+
 ## 🛠️ CLI Usage
 
 The CLI provides a convenient means to interact with the code generation ecosystem. The `autogpt` crate bundles two binaries in a single package:
@@ -501,6 +577,35 @@ This opens a conversational AI shell where you can:
 - Press `ESC` to interrupt a running generation.
 - Type `exit` or `quit` to save the session and close.
 
+#### 🤝 Collaborative Multi-Provider Mode (`--collab`, requires `col + cli`)
+
+Collab mode spawns one `GenericAgent` per configured provider (all providers
+with an API key set in the environment) and distributes the task across them
+in round-robin order with per-model fallback:
+
+```sh
+# Build with collab support:
+cargo run --features "cli,col,gem,oai,xai" --bin autogpt -- --collab
+
+# Or install:
+cargo install autogpt --features "cli,col,gem,oai"
+autogpt --collab
+```
+
+**Provider discovery**: Any provider feature compiled in whose API key env var
+is set at runtime is automatically added to the pool (e.g. `GEMINI_API_KEY`,
+`OPENAI_API_KEY`, `XAI_API_KEY`).
+
+**Fallback behaviour**:
+
+| Event                             | Action                                        |
+| --------------------------------- | --------------------------------------------- |
+| Rate-limit / quota error          | Rotate to next model within the same provider |
+| All models for provider exhausted | Remove provider from pool, route to next      |
+| All providers exhausted           | Log `⚠ All collab providers exhausted.`       |
+
+The TUI logs the active pool and each routing step with `🤝`/`🔀` prefixes.
+
 #### ⚡ Direct Prompt Mode
 
 For a quick one-shot non-interactive prompt:

autogpt/INSTALLATION.md

@@ -15,6 +15,8 @@ pub mod agent;
 pub mod architect;
 #[cfg(feature = "gpt")]
 pub mod backend;
+#[cfg(feature = "col")]
+pub mod collab;
 #[cfg(feature = "gpt")]
 pub mod designer;
 #[cfg(feature = "gpt")]