jarviscore-framework 0.2.1__py3-none-any.whl → 0.3.1__py3-none-any.whl

jarviscore/docs/CUSTOMAGENT_GUIDE.md

@@ -11,12 +11,16 @@ CustomAgent lets you integrate your **existing agent code** with JarvisCore's ne
 
 1. [Prerequisites](#prerequisites)
 2. [Choose Your Mode](#choose-your-mode)
-3. [P2P Mode](#p2p-mode)
-4. [Distributed Mode](#distributed-mode)
-5. [API Reference](#api-reference)
-6. [Multi-Node Deployment](#multi-node-deployment)
-7. [Error Handling](#error-handling)
-8. [Troubleshooting](#troubleshooting)
+3. [P2P Mode](#p2p-mode) - Handler-based peer communication
+4. [Distributed Mode](#distributed-mode) - Workflow tasks + P2P
+5. [Cognitive Discovery (v0.3.0)](#cognitive-discovery-v030) - Dynamic peer awareness for LLMs
+6. [FastAPI Integration (v0.3.0)](#fastapi-integration-v030) - 3-line setup with JarvisLifespan
+7. [Framework Integration Patterns](#framework-integration-patterns) - aiohttp, Flask, Django
+8. [Cloud Deployment (v0.3.0)](#cloud-deployment-v030) - Self-registration for containers
+9. [API Reference](#api-reference)
+10. [Multi-Node Deployment](#multi-node-deployment)
+11. [Error Handling](#error-handling)
+12. [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -98,13 +102,15 @@ class MyLLMClient:
 
 ### Quick Comparison
 
-| Feature | P2P Mode | Distributed Mode |
-|---------|----------|------------------|
-| **Primary method** | `run()` - continuous loop | `execute_task()` - on-demand |
-| **Communication** | Direct peer messaging | Workflow orchestration |
-| **Best for** | Chatbots, real-time agents | Pipelines, batch processing |
-| **Coordination** | Agents self-coordinate | Framework coordinates |
-| **Supports workflows** | No | Yes |
+| Feature | P2P Mode (CustomAgent) | P2P Mode (CustomAgent) | Distributed Mode |
+|---------|------------------------|--------------------------|------------------|
+| **Primary method** | `run()` - continuous loop | `on_peer_request()` handlers | `execute_task()` - on-demand |
+| **Communication** | Direct peer messaging | Handler-based (no loop) | Workflow orchestration |
+| **Best for** | Custom message loops | API-first agents, FastAPI | Pipelines, batch processing |
+| **Coordination** | Agents self-coordinate | Framework handles loop | Framework coordinates |
+| **Supports workflows** | No | No | Yes |
+
+> **CustomAgent** includes built-in P2P handlers - just implement `on_peer_request()` and `on_peer_notify()`. No need to write your own `run()` loop.
 
 ---
 
@@ -112,6 +118,46 @@ class MyLLMClient:
 
 P2P mode is for agents that run continuously and communicate directly with each other.
 
+### v0.3.1 Update: Handler-Based Pattern
+
+**We've simplified P2P agents!** No more manual `run()` loops.
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    OLD vs NEW Pattern                          │
+├────────────────────────────────────────────────────────────────┤
+│                                                                │
+│  ❌ OLD (v0.2.x) - Manual Loop                                 │
+│  ┌──────────────────────────────────────────────┐              │
+│  │ async def run(self):                         │              │
+│  │     while not self.shutdown_requested:       │              │
+│  │         msg = await self.peers.receive()     │ ← Polling    │
+│  │         if msg and msg.is_request:           │              │
+│  │             result = self.process(msg)       │              │
+│  │             await self.peers.respond(...)    │ ← Manual     │
+│  │         await asyncio.sleep(0.1)             │              │
+│  └──────────────────────────────────────────────┘              │
+│                                                                │
+│  ✅ NEW (v0.3.0+) - Handler-Based                              │
+│  ┌──────────────────────────────────────────────┐              │
+│  │ async def on_peer_request(self, msg):        │              │
+│  │     result = self.process(msg)               │              │
+│  │     return result                            │ ← Simple!    │
+│  └──────────────────────────────────────────────┘              │
+│         ▲                                                      │
+│         │                                                      │
+│         └─ Framework calls this automatically                 │
+│                                                                │
+└────────────────────────────────────────────────────────────────┘
+```
+
+**Benefits:**
+- ✅ **Less Code**: No boilerplate loops
+- ✅ **Simpler**: Just return your result
+- ✅ **Automatic**: Framework handles message dispatch
+- ✅ **Error Handling**: Built-in exception capture
+- ✅ **FastAPI Ready**: Works with `JarvisLifespan` out of the box
+
 ### Migration Overview
 
 ```
@@ -157,59 +203,89 @@ if __name__ == "__main__":
 
 ### Step 3: Modify Your Agent Code → `agents.py`
 
-Convert your existing class to inherit from `CustomAgent`:
+**🚨 IMPORTANT CHANGE (v0.3.0+)**: We've moved from `run()` loops to **handler-based** agents!
 
+#### ❌ OLD Pattern (Deprecated)
 ```python
-# agents.py (MODIFIED VERSION OF YOUR CODE)
-import asyncio
+# DON'T DO THIS ANYMORE!
+class ResearcherAgent(CustomAgent):
+    async def run(self):  # ❌ Manual loop
+        while not self.shutdown_requested:
+            msg = await self.peers.receive(timeout=0.5)
+            if msg and msg.is_request:
+                result = self.llm.chat(f"Research: {msg.data['question']}")
+                await self.peers.respond(msg, {"response": result})
+            await asyncio.sleep(0.1)
+```
+**Problems**: Manual loops, boilerplate, error-prone
+
+#### ✅ NEW Pattern (Recommended)
+```python
+# agents.py (MODERN VERSION)
 from jarviscore.profiles import CustomAgent
 
 
 class ResearcherAgent(CustomAgent):
-    """Your agent, now framework-integrated."""
+    """Your agent, now framework-integrated with handlers."""
 
-    # NEW: Required class attributes for discovery
+    # Required class attributes for discovery
     role = "researcher"
     capabilities = ["research", "analysis"]
+    description = "Research specialist that gathers and synthesizes information"
 
     async def setup(self):
-        """NEW: Called once on startup. Move your __init__ logic here."""
+        """Called once on startup. Initialize your LLM here."""
         await super().setup()
         self.llm = MyLLMClient()  # Your existing initialization
 
-    async def run(self):
-        """NEW: Main loop - replaces your if __name__ == '__main__' block."""
-        while not self.shutdown_requested:
-            if self.peers:
-                msg = await self.peers.receive(timeout=0.5)
-                if msg and msg.is_request:
-                    query = msg.data.get("question", "")
-                    # YOUR EXISTING LOGIC:
-                    result = self.llm.chat(f"Research: {query}")
-                    await self.peers.respond(msg, {"response": result})
-            await asyncio.sleep(0.1)
+    async def on_peer_request(self, msg):
+        """
+        Handle incoming requests from other agents.
+        
+        This is called AUTOMATICALLY when another agent asks you a question.
+        No loops, no polling, no boilerplate!
+        """
+        query = msg.data.get("question", "")
+        
+        # YOUR EXISTING LOGIC:
+        result = self.llm.chat(f"Research: {query}")
+        
+        # Just return the data - framework handles the response
+        return {"response": result}
 
     async def execute_task(self, task: dict) -> dict:
         """
-        Required by base Agent class (@abstractmethod).
-
-        In P2P mode, your main logic lives in run(), not here.
-        This must exist because Python requires all abstract methods
-        to be implemented, or you get TypeError on instantiation.
+        Required by base Agent class for workflow mode.
+        
+        In pure P2P mode, your logic is in on_peer_request().
+        This is used when agent is part of a workflow pipeline.
         """
-        return {"status": "success", "note": "This agent uses run() for P2P mode"}
+        return {"status": "success", "note": "This agent uses handlers for P2P mode"}
 ```
 
 **What changed:**
 
-| Before | After |
-|--------|-------|
-| `class MyResearcher:` | `class ResearcherAgent(CustomAgent):` |
-| `def __init__(self):` | `async def setup(self):` + `await super().setup()` |
-| `if __name__ == "__main__":` | `async def run(self):` loop |
-| Direct method calls | Peer message handling |
+| Before (v0.2.x) | After (v0.3.0+) | Why? |
+|-----------------|-----------------|------|
+| `async def run(self):` with `while` loop | `async def on_peer_request(self, msg):` handler | Automatic dispatch, less boilerplate |
+| Manual `await self.peers.receive()` | Framework calls your handler | No polling needed |
+| Manual `await self.peers.respond(msg, data)` | Just `return data` | Simpler error handling |
+| `asyncio.create_task(agent.run())` | Not needed - handlers run automatically | Cleaner lifecycle |
+
+#### Migration Checklist (v0.2.x → v0.3.0+)
 
-> **Note**: This is a minimal example. For the full pattern with **LLM-driven peer communication** (where your LLM autonomously decides when to call other agents), see the [Complete Example](#complete-example-llm-driven-peer-communication) below.
+If you have existing agents using the `run()` loop pattern:
+
+- [ ] Replace `async def run(self):` with `async def on_peer_request(self, msg):`
+- [ ] Remove `while not self.shutdown_requested:` loop
+- [ ] Remove `msg = await self.peers.receive(timeout=0.5)` polling
+- [ ] Change `await self.peers.respond(msg, data)` to `return data`
+- [ ] Remove manual `asyncio.create_task(agent.run())` calls in main.py
+- [ ] Consider using `JarvisLifespan` for FastAPI integration (see Step 4)
+- [ ] Add `description` class attribute for better cognitive discovery
+- [ ] Use `get_cognitive_context()` instead of hardcoded peer lists
+
+> **Note**: The `run()` method is **still supported** for backward compatibility, but handlers are now the recommended approach. For the full pattern with **LLM-driven peer communication** (where your LLM autonomously decides when to call other agents), see the [Complete Example](#complete-example-llm-driven-peer-communication) below.
 
 ### Step 4: Create New Entry Point → `main.py`
 
@@ -310,22 +386,22 @@ This is the **key pattern** for P2P mode. Your LLM gets peer tools added to its
 **The key insight**: You add peer tools to your LLM's toolset. The LLM decides when to use them.
 
 ```python
-# agents.py
-import asyncio
+# agents.py - UPDATED FOR v0.3.0+
 from jarviscore.profiles import CustomAgent
 
 
 class AnalystAgent(CustomAgent):
     """
-    Analyst agent - specialists in data analysis.
+    Analyst agent - specialist in data analysis.
 
-    This agent:
-    1. Listens for incoming requests from peers
-    2. Processes requests using its own LLM
-    3. Responds with analysis results
+    NEW PATTERN (v0.3.0+):
+    - Uses @on_peer_request HANDLER instead of run() loop
+    - Automatically receives and responds to peer requests
+    - No manual message polling needed!
     """
     role = "analyst"
     capabilities = ["analysis", "data_interpretation", "reporting"]
+    description = "Expert data analyst for statistics and insights"
 
     async def setup(self):
         await super().setup()
@@ -400,19 +476,20 @@ Analyze data thoroughly and provide insights."""
 
         return response.get("content", "Analysis complete.")
 
-    async def run(self):
-        """Listen for incoming requests from peers."""
-        while not self.shutdown_requested:
-            if self.peers:
-                msg = await self.peers.receive(timeout=0.5)
-                if msg and msg.is_request:
-                    query = msg.data.get("question", msg.data.get("query", ""))
+    async def on_peer_request(self, msg):
+        """
+        Handle incoming requests from peers.
+        
+        ✅ NEW: This is called automatically when another agent sends a request.
+        ❌ OLD: Manual while loop with receive() polling
+        """
+        query = msg.data.get("question", msg.data.get("query", ""))
 
-                    # Process with LLM
-                    result = await self.process_with_llm(query)
+        # Process with LLM
+        result = await self.process_with_llm(query)
 
-                    await self.peers.respond(msg, {"response": result})
-            await asyncio.sleep(0.1)
+        # Just return the data - framework handles the response!
+        return {"response": result}
 
     async def execute_task(self, task: dict) -> dict:
         """Required by base class."""
@@ -423,13 +500,16 @@ class AssistantAgent(CustomAgent):
     """
     Assistant agent - coordinates with other specialists.
 
-    This agent:
+    NEW PATTERN (v0.3.0+):
     1. Has its own LLM for reasoning
-    2. Has peer tools (ask_peer, broadcast) in its toolset
-    3. LLM AUTONOMOUSLY decides when to ask other agents
+    2. Uses get_cognitive_context() to discover available peers
+    3. Peer tools (ask_peer, broadcast) added to LLM toolset
+    4. LLM AUTONOMOUSLY decides when to ask other agents
+    5. Uses on_peer_request handler instead of run() loop
     """
     role = "assistant"
     capabilities = ["chat", "coordination", "search"]
+    description = "General assistant that delegates specialized tasks to experts"
 
     async def setup(self):
         await super().setup()
@@ -529,16 +609,16 @@ Be concise in your responses."""
 
         return response.get("content", "")
 
-    async def run(self):
-        """Main loop - listen for incoming requests."""
-        while not self.shutdown_requested:
-            if self.peers:
-                msg = await self.peers.receive(timeout=0.5)
-                if msg and msg.is_request:
-                    query = msg.data.get("query", "")
-                    result = await self.chat(query)
-                    await self.peers.respond(msg, {"response": result})
-            await asyncio.sleep(0.1)
+    async def on_peer_request(self, msg):
+        """
+        Handle incoming requests from other agents.
+        
+        ✅ NEW: Handler-based - called automatically on request
+        ❌ OLD: Manual while loop with receive() polling
+        """
+        query = msg.data.get("query", "")
+        result = await self.chat(query)
+        return {"response": result}
 
     async def execute_task(self, task: dict) -> dict:
         """Required by base class."""
@@ -546,13 +626,14 @@ Be concise in your responses."""
 ```
 
 ```python
-# main.py
+# main.py - UPDATED FOR v0.3.0+ (Handler-Based Pattern)
 import asyncio
 from jarviscore import Mesh
 from agents import AnalystAgent, AssistantAgent
 
 
 async def main():
+    """Simple P2P mesh without web server."""
     mesh = Mesh(
         mode="p2p",
         config={
@@ -561,17 +642,15 @@ async def main():
         }
     )
 
-    # Add both agents
+    # Add both agents - they'll use handlers automatically
     mesh.add(AnalystAgent)
     assistant = mesh.add(AssistantAgent)
 
     await mesh.start()
 
-    # Start analyst listening in background
-    analyst = mesh.get_agent("analyst")
-    analyst_task = asyncio.create_task(analyst.run())
-
-    # Give time for setup
+    # ✅ NO MORE MANUAL run() TASKS! Handlers are automatic.
+    
+    # Give time for mesh to stabilize
     await asyncio.sleep(0.5)
 
     # User asks a question - LLM will autonomously decide to use ask_peer
@@ -584,8 +663,6 @@ async def main():
     # Output: [{'tool': 'ask_peer', 'args': {'role': 'analyst', 'question': '...'}}]
 
     # Cleanup
-    analyst.request_shutdown()
-    analyst_task.cancel()
     await mesh.stop()
 
 
@@ -593,6 +670,59 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+**Or better yet, use FastAPI + JarvisLifespan:**
+
+```python
+# main.py - PRODUCTION PATTERN (FastAPI + JarvisLifespan)
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from jarviscore.integrations import JarvisLifespan
+from agents import AnalystAgent, AssistantAgent
+import uvicorn
+
+
+# ✅ ONE-LINE MESH SETUP with JarvisLifespan!
+app = FastAPI(lifespan=JarvisLifespan([AnalystAgent, AssistantAgent]))
+
+
+@app.post("/chat")
+async def chat(request: Request):
+    """Chat endpoint - assistant may autonomously delegate to analyst."""
+    data = await request.json()
+    message = data.get("message", "")
+    
+    # Get assistant from mesh (JarvisLifespan manages it)
+    assistant = app.state.mesh.get_agent("assistant")
+    
+    # Chat - LLM autonomously discovers and delegates if needed
+    response = await assistant.chat(message)
+    
+    return JSONResponse(response)
+
+
+@app.get("/agents")
+async def list_agents():
+    """Show what each agent sees (cognitive context)."""
+    mesh = app.state.mesh
+    agents_info = {}
+    
+    for agent in mesh.agents:
+        if agent.peers:
+            context = agent.peers.get_cognitive_context(format="markdown")
+            agents_info[agent.role] = {
+                "role": agent.role,
+                "capabilities": agent.capabilities,
+                "peers_visible": len(agent.peers.get_all_peers()),
+                "cognitive_context": context[:200] + "..."
+            }
+    
+    return JSONResponse(agents_info)
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+```
+
 ### Key Concepts for P2P Mode
 
 #### Adding Peer Tools to Your LLM
@@ -660,6 +790,150 @@ async def run(self):
 
 ---
 
+## P2P Message Handlers
+
+CustomAgent includes built-in handlers for P2P communication - just implement the handlers you need.
+
+### Handler-Based P2P (Recommended)
+
+```python
+from jarviscore.profiles import CustomAgent
+
+class MyAgent(CustomAgent):
+    role = "processor"
+    capabilities = ["processing"]
+
+    async def on_peer_request(self, msg):
+        """Called when another agent sends a request."""
+        return {"result": msg.data.get("task", "").upper()}
+
+    async def on_peer_notify(self, msg):
+        """Called when another agent broadcasts a notification."""
+        print(f"Notification received: {msg.data}")
+```
+
+**What the framework handles:**
+- Message receiving loop (`run()` is built-in)
+- Routing requests to `on_peer_request()`
+- Routing notifications to `on_peer_notify()`
+- Automatic response sending (configurable with `auto_respond`)
+- Shutdown handling
+
+**Configuration:**
+- `listen_timeout` (float): Seconds to wait for messages (default: 1.0)
+- `auto_respond` (bool): Auto-send `on_peer_request()` return value (default: True)
+
+### Complete P2P Example
+
+```python
+# agents.py
+from jarviscore.profiles import CustomAgent
+
+
+class AnalystAgent(CustomAgent):
+    """A data analyst that responds to peer requests."""
+
+    role = "analyst"
+    capabilities = ["analysis", "data_interpretation"]
+
+    async def setup(self):
+        await super().setup()
+        self.llm = MyLLMClient()  # Your LLM client
+
+    async def on_peer_request(self, msg):
+        """
+        Handle incoming requests from other agents.
+
+        Args:
+            msg: IncomingMessage with msg.data, msg.sender_role, etc.
+
+        Returns:
+            dict: Response sent back to the requesting agent
+        """
+        query = msg.data.get("question", "")
+
+        # Your analysis logic
+        result = self.llm.chat(f"Analyze: {query}")
+
+        return {"response": result, "status": "success"}
+
+    async def on_peer_notify(self, msg):
+        """
+        Handle broadcast notifications.
+
+        Args:
+            msg: IncomingMessage with notification data
+
+        Returns:
+            None (notifications don't expect responses)
+        """
+        print(f"[{self.role}] Received notification: {msg.data}")
+
+
+class AssistantAgent(CustomAgent):
+    """An assistant that coordinates with specialists."""
+
+    role = "assistant"
+    capabilities = ["chat", "coordination"]
+
+    async def setup(self):
+        await super().setup()
+        self.llm = MyLLMClient()
+
+    async def on_peer_request(self, msg):
+        """Handle incoming chat requests."""
+        query = msg.data.get("query", "")
+
+        # Use peer tools to ask specialists
+        if self.peers and "data" in query.lower():
+            # Ask the analyst for help
+            analyst_response = await self.peers.as_tool().execute(
+                "ask_peer",
+                {"role": "analyst", "question": query}
+            )
+            return {"response": analyst_response.get("response", "")}
+
+        # Handle directly
+        return {"response": self.llm.chat(query)}
+```
+
+```python
+# main.py
+import asyncio
+from jarviscore import Mesh
+from agents import AnalystAgent, AssistantAgent
+
+
+async def main():
+    mesh = Mesh(mode="p2p", config={"bind_port": 7950})
+
+    mesh.add(AnalystAgent)
+    mesh.add(AssistantAgent)
+
+    await mesh.start()
+
+    # Agents automatically run their listeners
+    await mesh.run_forever()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### When to Use Handlers vs Custom run()
+
+| Use handlers (`on_peer_request`) when... | Override `run()` when... |
+|------------------------------------------|--------------------------|
+| Request/response pattern fits your use case | You need custom message loop timing |
+| You're integrating with FastAPI | You need to initiate messages proactively |
+| You want minimal boilerplate | You have complex coordination logic |
+
+### CustomAgent with FastAPI
+
+CustomAgent works seamlessly with FastAPI. See [FastAPI Integration](#fastapi-integration-v030) below.
+
+---
+
 ## Distributed Mode
 
 Distributed mode is for task pipelines where the framework orchestrates execution order and passes data between steps.
@@ -1066,6 +1340,592 @@ results = await mesh.workflow("parallel-example", [
 
 ---
 
+## Cognitive Discovery (v0.3.0)
+
+**Cognitive Discovery** lets your LLM dynamically learn about available peers instead of hardcoding agent names in prompts.
+
+### The Problem: Hardcoded Peer Names
+
+Before v0.3.0, you had to hardcode peer information in your system prompts:
+
+```python
+# BEFORE: Hardcoded peer names - breaks when peers change
+system_prompt = """You are a helpful assistant.
+
+You have access to:
+- ask_peer: Ask specialist agents for help
+  - Use role="analyst" for data analysis
+  - Use role="researcher" for research tasks
+  - Use role="writer" for content creation
+
+When a user needs data analysis, USE ask_peer with role="analyst"."""
+```
+
+**Problems:**
+- If you add a new agent, you must update every prompt
+- If an agent is offline, the LLM still tries to call it
+- Prompts become stale as your system evolves
+- Difficult to manage across many agents
+
+### The Solution: `get_cognitive_context()`
+
+```python
+# AFTER: Dynamic peer awareness - always up to date
+async def get_system_prompt(self) -> str:
+    base_prompt = """You are a helpful assistant.
+
+You have access to peer tools for collaborating with other agents."""
+
+    # Generate LLM-ready peer descriptions dynamically
+    if self.peers:
+        peer_context = self.peers.get_cognitive_context()
+        return f"{base_prompt}\n\n{peer_context}"
+
+    return base_prompt
+```
+
+The `get_cognitive_context()` method generates text like:
+
+```
+Available Peers:
+- analyst (capabilities: analysis, data_interpretation)
+  Use ask_peer with role="analyst" for data analysis tasks
+- researcher (capabilities: research, web_search)
+  Use ask_peer with role="researcher" for research tasks
+```
+
+### Complete Example: Dynamic Peer Discovery
+
+```python
+# agents.py
+from jarviscore.profiles import CustomAgent
+
+
+class AssistantAgent(CustomAgent):
+    """An assistant that dynamically discovers and uses peers."""
+
+    role = "assistant"
+    capabilities = ["chat", "coordination"]
+
+    async def setup(self):
+        await super().setup()
+        self.llm = MyLLMClient()
+
+    def get_system_prompt(self) -> str:
+        """Build system prompt with dynamic peer context."""
+        base_prompt = """You are a helpful AI assistant.
+
+When users ask questions that require specialized knowledge:
+1. Check what peers are available
+2. Use ask_peer to get help from the right specialist
+3. Synthesize their response for the user"""
+
+        # DYNAMIC: Add current peer information
+        if self.peers:
+            peer_context = self.peers.get_cognitive_context()
+            return f"{base_prompt}\n\n{peer_context}"
+
+        return base_prompt
+
+    def get_tools(self) -> list:
+        """Get tools including peer tools."""
+        tools = [
+            # Your local tools...
+        ]
+
+        if self.peers:
+            tools.extend(self.peers.as_tool().schema)
+
+        return tools
+
+    async def chat(self, user_message: str) -> str:
+        """Chat with dynamic peer awareness."""
+        # System prompt now includes current peer info
+        system = self.get_system_prompt()
+        tools = self.get_tools()
+
+        response = self.llm.chat(
+            messages=[{"role": "user", "content": user_message}],
+            tools=tools,
+            system=system
+        )
+
+        # Handle tool use...
+        return response.get("content", "")
+```
+
+### Benefits of Cognitive Discovery
+
+| Before (Hardcoded) | After (Dynamic) |
+|--------------------|-----------------|
+| Update prompts manually when peers change | Prompts auto-update |
+| LLM tries to call offline agents | Only shows available agents |
+| Difficult to manage at scale | Scales automatically |
+| Stale documentation in prompts | Always current |
+
+---
+
+## FastAPI Integration (v0.3.0)
+
+**JarvisLifespan** reduces FastAPI integration from ~100 lines to 3 lines.
+
+### The Problem: Manual Lifecycle Management
+
+Before v0.3.0, integrating an agent with FastAPI required manual lifecycle management:
+
+```python
+# BEFORE: ~100 lines of boilerplate
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from jarviscore import Mesh
+from jarviscore.profiles import CustomAgent
+import asyncio
+
+
+class MyAgent(CustomAgent):
+    role = "processor"
+    capabilities = ["processing"]
+
+    async def run(self):
+        while not self.shutdown_requested:
+            if self.peers:
+                msg = await self.peers.receive(timeout=0.5)
+                if msg and msg.is_request:
+                    result = self.process(msg.data)
+                    await self.peers.respond(msg, {"response": result})
+            await asyncio.sleep(0.1)
+
+    async def execute_task(self, task):
+        return {"status": "success"}
+
+
+# Manual lifecycle management
+mesh = None
+agent = None
+run_task = None
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global mesh, agent, run_task
+
+    # Startup
+    mesh = Mesh(mode="p2p", config={"bind_port": 7950})
+    agent = mesh.add(MyAgent)
+    await mesh.start()
+    run_task = asyncio.create_task(agent.run())
+
+    yield
+
+    # Shutdown
+    agent.request_shutdown()
+    run_task.cancel()
+    await mesh.stop()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.post("/process")
+async def process(data: dict):
+    # Your endpoint logic
+    return {"result": "processed"}
+```
+
+### The Solution: JarvisLifespan
+
+```python
+# AFTER: 3 lines to integrate
+from fastapi import FastAPI
+from jarviscore.profiles import CustomAgent
+from jarviscore.integrations.fastapi import JarvisLifespan
+
+
+class ProcessorAgent(CustomAgent):
+    role = "processor"
+    capabilities = ["processing"]
+
+    async def on_peer_request(self, msg):
+        return {"result": msg.data.get("task", "").upper()}
+
+
+# That's it - 3 lines!
+app = FastAPI(lifespan=JarvisLifespan(ProcessorAgent(), mode="p2p"))
+
+
+@app.post("/process")
+async def process(data: dict):
+    return {"result": "processed"}
+```
+
+### JarvisLifespan Configuration
+
+```python
+from jarviscore.integrations.fastapi import JarvisLifespan
+
+# Basic usage
+app = FastAPI(lifespan=JarvisLifespan(agent, mode="p2p"))
+
+# With configuration
+app = FastAPI(
+    lifespan=JarvisLifespan(
+        agent,
+        mode="p2p",              # or "distributed"
+        bind_port=7950,          # P2P port
+        seed_nodes="ip:port",    # For multi-node
+    )
+)
+```
+
+### Complete FastAPI Example
+
+```python
+# app.py
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from jarviscore.profiles import CustomAgent
+from jarviscore.integrations.fastapi import JarvisLifespan
+
+
+class AnalysisRequest(BaseModel):
+    data: str
+
+
+class AnalystAgent(CustomAgent):
+    """Agent that handles both API requests and P2P messages."""
+
+    role = "analyst"
+    capabilities = ["analysis"]
+
+    async def setup(self):
+        await super().setup()
+        self.llm = MyLLMClient()
+
+    async def on_peer_request(self, msg):
+        """Handle requests from other agents in the mesh."""
+        query = msg.data.get("question", "")
+        result = self.llm.chat(f"Analyze: {query}")
+        return {"response": result}
+
+    def analyze(self, data: str) -> dict:
+        """Method called by API endpoint."""
+        result = self.llm.chat(f"Analyze this data: {data}")
+        return {"analysis": result}
+
+
+# Create agent instance
+analyst = AnalystAgent()
+
+# Create FastAPI app with automatic lifecycle management
+app = FastAPI(
+    title="Analyst Service",
+    lifespan=JarvisLifespan(analyst, mode="p2p", bind_port=7950)
+)
+
+
+@app.post("/analyze")
+async def analyze(request: AnalysisRequest):
+    """API endpoint - also accessible as a peer in the mesh."""
+    result = analyst.analyze(request.data)
+    return result
+
+
+@app.get("/peers")
+async def list_peers():
+    """See what other agents are in the mesh."""
+    if analyst.peers:
+        return {"peers": analyst.peers.list()}
+    return {"peers": []}
+```
+
+Run with:
+```bash
+uvicorn app:app --host 0.0.0.0 --port 8000
+```
+
+Your agent is now:
+- Serving HTTP API on port 8000
+- Participating in P2P mesh on port 7950
+- Discoverable by other agents
+- Automatically handles lifecycle
+
+### Testing the Flow
+
+**Step 1: Start the FastAPI server (Terminal 1)**
+```bash
+python examples/fastapi_integration_example.py
+```
+
+**Step 2: Join a scout agent (Terminal 2)**
+```bash
+python examples/fastapi_integration_example.py --join-as scout
+```
+
+**Step 3: Test with curl (Terminal 3)**
+```bash
+# Chat with assistant (may delegate to analyst)
+curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" -d '{"message": "Analyze Q4 sales trends"}'
+
+# Ask analyst directly
+curl -X POST http://localhost:8000/ask/analyst -H "Content-Type: application/json" -d '{"message": "What are key revenue metrics?"}'
+
+# See what each agent knows about peers (cognitive context)
+curl http://localhost:8000/agents
+```
+
+**Expected flow for `/chat`:**
+1. Request goes to **assistant** agent
+2. Assistant's LLM sees peers via `get_cognitive_context()`
+3. LLM decides to delegate to **analyst** (data analysis request)
+4. Assistant uses `ask_peer` tool → P2P message to analyst
+5. Analyst processes and responds via P2P
+6. Response includes `"delegated_to": "analyst"` and `"peer_data"`
+
+**Example response:**
+```json
+{
+  "message": "Analyze Q4 sales trends",
+  "response": "Based on the analyst's findings...",
+  "delegated_to": "analyst",
+  "peer_data": {"analysis": "...", "confidence": 0.9}
+}
+```
+
+---
+
+## Cloud Deployment (v0.3.0)
+
+**Self-registration** lets agents join existing meshes without a central orchestrator - perfect for Docker, Kubernetes, and auto-scaling.
+
+### The Problem: Central Orchestrator Required
+
+Before v0.3.0, all agents had to be registered with a central Mesh:
+
+```python
+# BEFORE: Central orchestrator pattern
+# You needed one "main" node that registered all agents
+
+# main_node.py (central orchestrator)
+mesh = Mesh(mode="distributed", config={"bind_port": 7950})
+mesh.add(ResearcherAgent)  # Must be on this node
+mesh.add(WriterAgent)      # Must be on this node
+await mesh.start()
+```
+
+**Problems with this approach:**
+- Single point of failure
+- Can't easily scale agent instances
+- Doesn't work well with Kubernetes/Docker
+- All agents must be on the same node or manually configured
+
+### The Solution: `join_mesh()` and `leave_mesh()`
+
+```python
+# AFTER: Self-registering agents
+# Each agent can join any mesh independently
+
+# agent_container.py (runs in Docker/K8s)
+from jarviscore.profiles import CustomAgent
+import os
+
+
+class WorkerAgent(CustomAgent):
+    role = "worker"
+    capabilities = ["processing"]
+
+    async def on_peer_request(self, msg):
+        return {"result": "processed"}
+
+
+async def main():
+    agent = WorkerAgent()
+    await agent.setup()
+
+    # Join existing mesh via environment variable
+    seed_nodes = os.environ.get("JARVISCORE_SEED_NODES", "mesh-service:7950")
+    await agent.join_mesh(seed_nodes=seed_nodes)
+
+    # Agent is now part of the mesh, discoverable by others
+    await agent.serve_forever()
+
+    # Clean shutdown
+    await agent.leave_mesh()
+```
+
+### Environment Variables for Cloud
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `JARVISCORE_SEED_NODES` | Comma-separated list of mesh nodes | `"10.0.0.1:7950,10.0.0.2:7950"` |
+| `JARVISCORE_MESH_ENDPOINT` | This agent's reachable address | `"worker-pod-abc:7950"` |
+| `JARVISCORE_BIND_PORT` | Port to listen on | `"7950"` |
+
+### Docker Deployment Example
+
+```dockerfile
+# Dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+COPY . .
+CMD ["python", "agent.py"]
+```
+
+```python
+# agent.py
+import asyncio
+import os
+from jarviscore.profiles import CustomAgent
+
+
+class WorkerAgent(CustomAgent):
+    role = "worker"
+    capabilities = ["processing"]
+
+    async def on_peer_request(self, msg):
+        task = msg.data.get("task", "")
+        return {"result": f"Processed: {task}"}
+
+
+async def main():
+    agent = WorkerAgent()
+    await agent.setup()
+
+    # Configuration from environment
+    seed_nodes = os.environ.get("JARVISCORE_SEED_NODES")
+    mesh_endpoint = os.environ.get("JARVISCORE_MESH_ENDPOINT")
+
+    if seed_nodes:
+        await agent.join_mesh(
+            seed_nodes=seed_nodes,
+            advertise_endpoint=mesh_endpoint
+        )
+        print(f"Joined mesh via {seed_nodes}")
+    else:
+        print("Running standalone (no JARVISCORE_SEED_NODES)")
+
+    await agent.serve_forever()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+services:
+  mesh-seed:
+    build: .
+    environment:
+      - JARVISCORE_BIND_PORT=7950
+    ports:
+      - "7950:7950"
+
+  worker-1:
+    build: .
+    environment:
+      - JARVISCORE_SEED_NODES=mesh-seed:7950
+      - JARVISCORE_MESH_ENDPOINT=worker-1:7950
+    depends_on:
+      - mesh-seed
+
+  worker-2:
+    build: .
+    environment:
+      - JARVISCORE_SEED_NODES=mesh-seed:7950
+      - JARVISCORE_MESH_ENDPOINT=worker-2:7950
+    depends_on:
+      - mesh-seed
+```
+
+### Kubernetes Deployment Example
+
+```yaml
+# k8s-deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: jarvis-worker
+spec:
+  replicas: 3  # Scale as needed
+  selector:
+    matchLabels:
+      app: jarvis-worker
+  template:
+    metadata:
+      labels:
+        app: jarvis-worker
+    spec:
+      containers:
+      - name: worker
+        image: myregistry/jarvis-worker:latest
+        env:
+        - name: JARVISCORE_SEED_NODES
+          value: "jarvis-mesh-service:7950"
+        - name: JARVISCORE_MESH_ENDPOINT
+          valueFrom:
+            fieldRef:
+              fieldPath: status.podIP
+        ports:
+        - containerPort: 7950
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: jarvis-mesh-service
+spec:
+  selector:
+    app: jarvis-mesh-seed
+  ports:
+  - port: 7950
+    targetPort: 7950
+```
+
+### How Self-Registration Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SELF-REGISTRATION FLOW                    │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  1. New container starts                                    │
+│     │                                                       │
+│     ▼                                                       │
+│  2. agent.join_mesh(seed_nodes="mesh:7950")                │
+│     │                                                       │
+│     ▼                                                       │
+│  3. Agent connects to seed node                            │
+│     │                                                       │
+│     ▼                                                       │
+│  4. SWIM protocol discovers all peers                      │
+│     │                                                       │
+│     ▼                                                       │
+│  5. Agent registers its role/capabilities                  │
+│     │                                                       │
+│     ▼                                                       │
+│  6. Other agents can now discover and call this agent      │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### RemoteAgentProxy (Automatic)
+
+When agents join from different nodes, the framework automatically creates `RemoteAgentProxy` objects. You don't need to do anything special - the mesh handles it:
+
+```python
+# On any node, you can discover and call remote agents
+if agent.peers:
+    # This works whether the peer is local or remote
+    response = await agent.peers.as_tool().execute(
+        "ask_peer",
+        {"role": "worker", "question": "Process this data"}
+    )
+```
+
+---
+
 ## API Reference
 
 ### CustomAgent Class Attributes
@@ -1082,8 +1942,26 @@ results = await mesh.workflow("parallel-example", [
 | `setup()` | Both | Called once on startup. Initialize resources here. Always call `await super().setup()` |
 | `run()` | P2P | Main loop for continuous operation. Required for P2P mode |
 | `execute_task(task)` | Distributed | Handle a workflow task. Required for Distributed mode |
+| `join_mesh(seed_nodes, ...)` | Both | **(v0.3.0)** Self-register with an existing mesh |
+| `leave_mesh()` | Both | **(v0.3.0)** Gracefully leave the mesh |
+| `serve_forever()` | Both | **(v0.3.0)** Block until shutdown signal |
+
+### P2P Message Handlers (v0.3.1)
+
+CustomAgent includes built-in P2P message handlers for handler-based communication.
 
-### Why `execute_task()` is Required in P2P Mode
+| Attribute/Method | Type | Description |
+|------------------|------|-------------|
+| `listen_timeout` | `float` | Seconds to wait for messages in `run()` loop. Default: 1.0 |
+| `auto_respond` | `bool` | Auto-send `on_peer_request` return value. Default: True |
+| `on_peer_request(msg)` | async method | Handle incoming requests. Return value sent as response |
+| `on_peer_notify(msg)` | async method | Handle broadcast notifications. No return needed |
+| `on_error(error, msg)` | async method | Handle errors during message processing |
+| `run()` | async method | Built-in listener loop that dispatches to handlers |
+
+**Note:** Override `on_peer_request()` and `on_peer_notify()` for your business logic. The `run()` method handles the message dispatch automatically.
+
+### Why `execute_task()` Exists in CustomAgent
 
 You may notice that P2P agents must implement `execute_task()` even though they primarily use `run()`. Here's why:
 
@@ -1128,6 +2006,33 @@ Access via `self.peers.as_tool().execute(tool_name, params)`:
 | `broadcast` | `{"message": str}` | Send a message to all connected peers |
 | `list_peers` | `{}` | Get list of available peers and their capabilities |
 
+### PeerClient Methods (v0.3.0)
+
+Access via `self.peers`:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get_cognitive_context()` | `str` | Generate LLM-ready text describing available peers |
+| `list()` | `list[PeerInfo]` | Get list of connected peers |
+| `as_tool()` | `PeerTool` | Get peer tools for LLM tool use |
+| `receive(timeout)` | `IncomingMessage` | Receive next message (for CustomAgent run loops) |
+| `respond(msg, data)` | `None` | Respond to a request message |
+
+### JarvisLifespan (v0.3.0)
+
+FastAPI integration helper:
+
+```python
+from jarviscore.integrations.fastapi import JarvisLifespan
+
+JarvisLifespan(
+    agent,                      # Agent instance
+    mode="p2p",                 # "p2p" or "distributed"
+    bind_port=7950,             # Optional: P2P port
+    seed_nodes="ip:port",       # Optional: for multi-node
+)
+```
+
 ### Mesh Configuration
 
 ```python
@@ -1358,5 +2263,12 @@ async def ask_researcher(self, question: str) -> str:
 
 For complete, runnable examples, see:
 
-- `examples/customagent_p2p_example.py` - P2P mode with peer communication
+- `examples/customagent_p2p_example.py` - P2P mode with LLM-driven peer communication
 - `examples/customagent_distributed_example.py` - Distributed mode with workflows
+- `examples/customagent_cognitive_discovery_example.py` - CustomAgent + cognitive discovery (v0.4.0)
+- `examples/fastapi_integration_example.py` - FastAPI + JarvisLifespan (v0.3.0)
+- `examples/cloud_deployment_example.py` - Self-registration with join_mesh (v0.3.0)
+
+---
+
+*CustomAgent Guide - JarvisCore Framework v0.3.1*