feat: add agent marketplace swarm example with skill-based routing

examples/agent_marketplace_swarm/.env.example

@@ -0,0 +1,2 @@
+OPENAI_API_KEY=your_openrouter_key
+OPENAI_API_BASE=https://openrouter.ai/api/v1

examples/agent_marketplace_swarm/README.md

@@ -0,0 +1,296 @@
+# 🌻 Bindu Agent Marketplace Swarm
+
+## A Dynamic Multi-Agent Marketplace Built with Bindu
+
+This project demonstrates how to build a skill-driven AI agent marketplace using Bindu — the identity, communication, and orchestration layer for AI agents.
+
+Instead of relying on a single large AI system, this architecture enables multiple specialized agents to collaborate through dynamic skill discovery and intelligent routing.
+
+The system showcases how autonomous agents can register capabilities, discover tasks, and execute them collaboratively, forming a scalable agent ecosystem.
+
+## 🌍 Why Agent Marketplaces?
+
+Traditional AI applications typically rely on one model performing all tasks.
+
+This approach has several limitations:
+
+- Poor scalability
+- Lack of specialization
+- Difficult maintenance
+- Limited extensibility
+
+Agent marketplaces solve this by enabling multiple specialized agents to collaborate.
+
+Each agent:
+
+- Advertises its skills
+- Receives tasks dynamically
+- Executes specialized operations
+- Returns results through a shared orchestration layer
+
+Bindu provides the infrastructure to support these decentralized AI ecosystems.
+
+## 🧠 Core Concept
+
+This project models an AI agent marketplace.
+
+Agents dynamically register their capabilities in a Skill Registry.
+
+When a user sends a request:
+
+1. The Router Agent analyzes the request
+2. The Skill Registry identifies which agent has the required capability
+3. The Orchestrator executes the appropriate agent
+4. The result is returned to the user
+
+This enables flexible, scalable multi-agent collaboration.
+
+## 🏗️ System Architecture
+
+The system consists of four primary components:
+
+| Component | Role |
+|-----------|------|
+| Router Agent | Determines which skill is required for a request |
+| Skill Registry | Stores agent capabilities and enables agent discovery |
+| Specialized Agents | Perform specific tasks (research, summarization, translation) |
+| Orchestrator | Coordinates routing and agent execution |
+
+## 🔁 Execution Flow
+
+```
+User Request
+     ↓
+Router Agent
+     ↓
+Skill Registry Lookup
+     ↓
+Agent Discovery
+     ↓
+Selected Agent Executes Task
+     ↓
+Response Returned
+```
+
+Example queries:
+
+- Explain quantum computing
+- Summarize this article
+- Translate hello to Spanish
+
+## 🤖 Agents in the Marketplace
+
+### Research Agent
+
+Handles knowledge and explanation queries.
+
+Example:
+```
+Explain quantum computing
+```
+
+### Summarizer Agent
+
+Condenses long content into concise summaries.
+
+Example:
+```
+Summarize this article about artificial intelligence
+```
+
+### Translator Agent
+
+Translates text between languages.
+
+Example:
+```
+Translate hello how are you to Spanish
+```
+
+## 🧩 Dynamic Skill Registration
+
+Unlike traditional static routing systems, agents register their skills dynamically with the registry.
+
+Example:
+
+```python
+registry.register_agent("research_agent", ["research", "explain"])
+registry.register_agent("summarizer_agent", ["summarize"])
+registry.register_agent("translator_agent", ["translate"])
+```
+
+This allows new agents to be added easily without modifying the router logic.
+
+## 📁 Project Structure
+
+```
+examples/
+└── agent_marketplace_swarm/
+    ├── bindu_super_agent.py
+    ├── orchestrator.py
+    ├── router_agent.py
+    ├── skill_registry.py
+    ├── research_agent.py
+    ├── summarizer_agent.py
+    ├── translator_agent.py
+    ├── env.example
+    ├── README.md
+    └── skills/
+        └── agent-marketplace-routing/
+            └── skill.yaml
+```
+
+## ⚙️ Technologies Used
+
+| Technology | Purpose |
+|------------|---------|
+| Bindu | Agent identity and runtime framework |
+| Groq LLM | High-performance language model inference |
+| Python | Core application logic |
+| FastAPI | Testing interface |
+| dotenv | Environment configuration |
+
+## 🚀 Quick Start
+
+### 1️⃣ Clone the Repository
+
+```bash
+git clone https://github.com/getbindu/bindu.git
+cd bindu
+```
+
+### 2️⃣ Create Virtual Environment
+
+```bash
+python -m venv .venv
+```
+
+Activate environment:
+
+**Windows**
+```bash
+.venv\Scripts\activate
+```
+
+**macOS / Linux**
+```bash
+source .venv/bin/activate
+```
+
+### 3️⃣ Install Dependencies
+
+```bash
+pip install -e .
+pip install groq python-dotenv fastapi uvicorn
+```
+
+### 4️⃣ Configure Environment Variables
+
+Create `.env` file inside:
+
+```
+examples/agent_marketplace_swarm/
+```
+
+Add:
+
+```
+GROQ_API_KEY=your_groq_api_key
+MODEL_NAME=llama-3.3-70b-versatile
+```
+
+### 5️⃣ Run the Bindu Agent
+
+```bash
+cd examples/agent_marketplace_swarm
+python bindu_super_agent.py
+```
+
+The agent will start at:
+
+```
+http://localhost:3773
+```
+
+### 6️⃣ Test the Agent (Swagger)
+
+Run the test API:
+
+```bash
+uvicorn test_api:app --reload
+```
+
+Open:
+
+```
+http://127.0.0.1:8000/docs
+```
+
+Example request:
+
+```json
+{
+  "message": "Explain quantum computing"
+}
+```
+
+## 🌻 How This Demonstrates Bindu's Vision
+
+Bindu is designed to support Internet-scale AI agents.
+
+This example demonstrates key principles:
+
+**Agent Identity**
+
+Each agent operates as a unique entity within the system.
+
+**Skill Discovery**
+
+Agents advertise capabilities through the Skill Registry.
+
+**Agent Collaboration**
+
+Agents collaborate through an orchestration pipeline.
+
+**Extensible Ecosystem**
+
+New agents can be added without modifying existing infrastructure.
+
+## 🔮 Possible Extensions
+
+Future improvements could include:
+
+- Autonomous agent negotiation
+- Economic agent marketplaces
+- Reputation systems for agents
+- Distributed multi-agent swarms
+- Agent-to-agent communication protocols
+
+## 🧬 Philosophy
+
+Most AI systems focus on building:
+
+> larger models
+
+Bindu focuses on building:
+
+> better systems
+
+This project demonstrates that complex intelligence emerges from collaboration between specialized agents.
+
+## ⭐ Why This Example Exists
+
+This example helps developers:
+
+- Understand multi-agent architectures
+- Learn dynamic skill routing
+- Build scalable AI agent systems
+- Explore Bindu-based agent orchestration
+
+## 🌍 The Bigger Picture
+
+The future of AI will not be a single agent.
+
+It will be a network of collaborating agents.
+
+This project is a small step toward that vision.

examples/agent_marketplace_swarm/bindu_super_agent.py

@@ -0,0 +1,65 @@
+from dotenv import load_dotenv
+load_dotenv()
+
+import asyncio
+from bindu.penguin.bindufy import bindufy
+from orchestrator import Orchestrator
+from typing import List, Dict, Any
+
+orchestrator = Orchestrator()
+
+
+def handler(messages: list[dict[str, str]]) -> str:
+    """
+    Protocol-compliant handler for Bindu.
+
+    Safely extracts user input from message history
+    and routes it through the agent marketplace swarm.
+    """
+
+    # -------- Input Validation --------
+
+    if not isinstance(messages, list):
+        return "Invalid input format: messages must be a list."
+
+    if not messages:
+        return "No input message received."
+
+    last_msg = messages[-1]
+
+    if not isinstance(last_msg, dict):
+        return "Invalid message structure."
+
+    user_input = last_msg.get("content")
+
+    if not user_input or not isinstance(user_input, str):
+        return "Empty or invalid message content."
+
+    # -------- Swarm Execution --------
+
+    try:
+        # FIX: Run async orchestrator properly
+        result = asyncio.run(orchestrator.run(user_input))
+        return result
+
+    except Exception as e:
+        return f"Internal agent error: {str(e)}"
+
+
+if __name__ == "__main__":
+    config = {
+        "author": "yatirajkulkarni143@gmail.com",
+        "name": "agent-marketplace-swarm",
+        "description": "Skill-based agent marketplace demonstrating routing between summarization and translation agents using Bindu.",
+        "capabilities": {"streaming": True},
+        "deployment": {
+            "url": "http://localhost:3773",
+            "expose": True,
+            "cors_origins": ["http://localhost:5173"]
+        },
+        "skills": ["skills/agent-marketplace-routing"],
+        "storage": {"type": "memory"},
+        "scheduler": {"type": "memory"}
+    }
+
+    bindufy(config=config, handler=handler)