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

examples/customagent_cognitive_discovery_example.py

@@ -1,25 +1,30 @@
 """
 CustomAgent + Cognitive Discovery Example
 
-Demonstrates two v0.3.0 features:
+Demonstrates v0.3.0 and v0.3.2 features:
 
 1. CustomAgent - Handler-based P2P agents (no run() loop needed)
    - on_peer_request() handles incoming requests
    - on_peer_notify() handles broadcast notifications
 
-2. Cognitive Discovery - Dynamic peer awareness for LLMs
+2. Cognitive Discovery (v0.3.0) - Dynamic peer awareness for LLMs
    - get_cognitive_context() generates LLM-ready peer descriptions
    - No hardcoded agent names in prompts
    - LLM autonomously decides when to delegate
 
+3. Session Context (v0.3.2) - Request tracking with metadata
+   - Pass context={mission_id, request_id} with peer requests
+   - Track requests across agent boundaries for debugging/tracing
+
 Usage:
-    python examples/listeneragent_cognitive_discovery_example.py
+    python examples/customagent_cognitive_discovery_example.py
 
 Prerequisites:
     - .env file with CLAUDE_API_KEY (or other LLM provider)
 """
 import asyncio
 import sys
+import uuid
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
@@ -45,13 +50,21 @@ class AnalystAgent(CustomAgent):
     async def on_peer_request(self, msg):
         """Handle incoming analysis requests."""
         query = msg.data.get("question", msg.data.get("query", ""))
-        print(f"\n[Analyst] Received request: {query[:50]}...")
+
+        # v0.3.2: Access session context for request tracking
+        context = msg.context or {}
+        mission_id = context.get("mission_id", "unknown")
+        request_id = context.get("request_id", "unknown")
+
+        print(f"\n[Analyst] Received request (mission={mission_id[:8]}..., req={request_id[:8]}...)")
+        print(f"[Analyst] Query: {query[:50]}...")
 
         # Simulate analysis (in real usage, this would use an LLM)
         result = {
             "analysis": f"Analysis of '{query}': The data shows positive trends.",
             "confidence": 0.85,
-            "insights": ["Trend is upward", "Growth rate: 15%", "Recommendation: Continue"]
+            "insights": ["Trend is upward", "Growth rate: 15%", "Recommendation: Continue"],
+            "context": {"mission_id": mission_id, "request_id": request_id}  # Echo back for tracing
         }
 
         print(f"[Analyst] Sending response with {len(result['insights'])} insights")
@@ -78,6 +91,9 @@ class CoordinatorAgent(CustomAgent):
     async def setup(self):
         await super().setup()
         self.llm = self._create_llm_client()
+        # v0.3.2: Track missions for context propagation
+        self.mission_id = str(uuid.uuid4())
+        self.request_counter = 0
 
     def _create_llm_client(self):
         """Create LLM client with fallback to mock."""
@@ -167,10 +183,22 @@ Never try to do analysis yourself - always delegate to the analyst."""
             # Mock: simulate LLM deciding to delegate
             if any(word in user_query.lower() for word in ["analyze", "analysis", "statistics", "data"]):
                 print("[Coordinator] Mock LLM decides to delegate to analyst")
+
+                # v0.3.2: Generate request context for tracking
+                self.request_counter += 1
+                request_context = {
+                    "mission_id": self.mission_id,
+                    "request_id": str(uuid.uuid4()),
+                    "request_num": self.request_counter,
+                    "source": "coordinator"
+                }
+                print(f"[Coordinator] Sending with context: mission={self.mission_id[:8]}...")
+
                 response = await self.peers.request(
                     "analyst",
                     {"question": user_query},
-                    timeout=30
+                    timeout=30,
+                    context=request_context  # v0.3.2: Pass context
                 )
                 return f"Based on the analyst's findings: {response.get('analysis', 'No response')}"
             return f"I can help with: {user_query}"
@@ -261,12 +289,24 @@ Never try to do analysis yourself - always delegate to the analyst."""
         role = args.get("role", "")
         question = args.get("question", "")
 
+        # v0.3.2: Generate request context for tracking
+        self.request_counter += 1
+        request_context = {
+            "mission_id": self.mission_id,
+            "request_id": str(uuid.uuid4()),
+            "request_num": self.request_counter,
+            "source": "coordinator",
+            "tool": "ask_peer"
+        }
+
         print(f"[Coordinator] Asking {role}: {question[:50]}...")
+        print(f"[Coordinator] Context: mission={self.mission_id[:8]}..., req_num={self.request_counter}")
 
         response = await self.peers.request(
             role,
             {"question": question},
-            timeout=30
+            timeout=30,
+            context=request_context  # v0.3.2: Pass context
         )
 
         return response
@@ -284,7 +324,8 @@ Never try to do analysis yourself - always delegate to the analyst."""
 
 async def main():
     print("=" * 60)
-    print("LLM Cognitive Discovery Example")
+    print("CustomAgent + Cognitive Discovery + Session Context")
+    print("Features: v0.3.0 Cognitive Discovery, v0.3.2 Session Context")
     print("=" * 60)
 
     # Create mesh with both agents

examples/customagent_distributed_example.py

@@ -6,6 +6,10 @@ Demonstrates CustomAgent in distributed mode, which combines:
 - Workflow orchestration (step execution, dependencies)
 - User-controlled execution logic (you write execute_task)
 
+v0.3.2 Features Demonstrated:
+- Async Requests (ask_async) - Non-blocking parallel requests to multiple agents
+- Load Balancing (strategy="round_robin") - Distribute requests across agent instances
+
 This is ideal for:
 - Multi-node deployments with custom logic
 - Integrating external frameworks (LangChain, CrewAI, etc.)
@@ -231,6 +235,7 @@ async def main():
     """Run CustomAgent distributed mode example."""
     print("\n" + "="*70)
     print("JarvisCore: CustomAgent in Distributed Mode")
+    print("v0.3.2: Also supports --async and --load-balance demos")
     print("="*70)
 
     # ─────────────────────────────────────────────────────────────────────────
@@ -358,5 +363,139 @@ async def peer_communication_example():
     pass
 
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# v0.3.2 FEATURES: ASYNC REQUESTS & LOAD BALANCING
+# ═══════════════════════════════════════════════════════════════════════════════
+
+async def async_requests_demo():
+    """
+    Demonstrate v0.3.2 async requests for parallel agent communication.
+
+    ask_async() returns a Future that can be awaited later, enabling:
+    - Fire multiple requests in parallel
+    - Continue other work while waiting
+    - Gather results when needed
+    """
+    print("\n" + "="*70)
+    print("v0.3.2 Feature: Async Requests (ask_async)")
+    print("="*70)
+
+    mesh = Mesh(mode="p2p", config={"bind_port": 7966})
+
+    # Add multiple agents
+    mesh.add(ContentResearcherAgent)
+    mesh.add(ContentWriterAgent)
+    mesh.add(ContentReviewerAgent)
+
+    try:
+        await mesh.start()
+
+        # Get an agent with peer access
+        researcher = next((a for a in mesh.agents if a.role == "content_researcher"), None)
+        if not researcher or not researcher.peers:
+            print("Peers not available")
+            return
+
+        print("\n[Demo] Firing parallel requests to multiple agents...")
+
+        # v0.3.2: ask_async returns a Future - doesn't block!
+        future1 = researcher.peers.ask_async(
+            "content_writer",
+            {"question": "What makes good technical writing?"}
+        )
+        future2 = researcher.peers.ask_async(
+            "content_reviewer",
+            {"question": "What are common writing mistakes?"}
+        )
+
+        print("[Demo] Requests sent! Doing other work while waiting...")
+        await asyncio.sleep(0.1)  # Simulate other work
+
+        # Gather results when ready
+        print("[Demo] Gathering results...")
+        results = await asyncio.gather(future1, future2, return_exceptions=True)
+
+        for i, result in enumerate(results):
+            if isinstance(result, Exception):
+                print(f"  Request {i+1}: Error - {result}")
+            else:
+                print(f"  Request {i+1}: Got response")
+
+        print("\n[Demo] Async requests complete!")
+
+    finally:
+        await mesh.stop()
+
+
+async def load_balancing_demo():
+    """
+    Demonstrate v0.3.2 load balancing strategies.
+
+    When multiple agents have the same capability, use strategy parameter:
+    - "random" (default): Random selection
+    - "round_robin": Distribute evenly across instances
+    """
+    print("\n" + "="*70)
+    print("v0.3.2 Feature: Load Balancing Strategies")
+    print("="*70)
+
+    mesh = Mesh(mode="p2p", config={"bind_port": 7967})
+
+    # Add agents
+    mesh.add(ContentResearcherAgent)
+    mesh.add(ContentWriterAgent)
+
+    try:
+        await mesh.start()
+
+        researcher = next((a for a in mesh.agents if a.role == "content_researcher"), None)
+        if not researcher or not researcher.peers:
+            print("Peers not available")
+            return
+
+        print("\n[Demo] Load balancing with strategy='round_robin'")
+        print("[Demo] Sending 3 requests to 'writing' capability...")
+
+        # v0.3.2: Use discover_one() with strategy for load balancing
+        for i in range(3):
+            # round_robin distributes requests evenly across matching peers
+            # First, discover which peer to use with the strategy
+            target = researcher.peers.discover_one(
+                role="content_writer",
+                strategy="round_robin"  # v0.3.2: Load balancing
+            )
+
+            if target:
+                # Then make the request to that specific peer
+                response = await researcher.peers.request(
+                    target.role,
+                    {"question": f"Request #{i+1}"},
+                    timeout=10
+                )
+                print(f"  Request {i+1}: Handled by {target.agent_id[:8]}...")
+            else:
+                print(f"  Request {i+1}: No peer found")
+
+        print("\n[Demo] Load balancing complete!")
+        print("[Demo] In a multi-node setup with multiple writers,")
+        print("       round_robin would distribute across all instances.")
+
+    finally:
+        await mesh.stop()
+
+
 if __name__ == "__main__":
-    asyncio.run(main())
+    import sys
+
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "--async":
+            asyncio.run(async_requests_demo())
+        elif sys.argv[1] == "--load-balance":
+            asyncio.run(load_balancing_demo())
+        else:
+            print("Usage:")
+            print("  python customagent_distributed_example.py           # Main workflow demo")
+            print("  python customagent_distributed_example.py --async   # Async requests demo")
+            print("  python customagent_distributed_example.py --load-balance  # Load balancing demo")
+    else:
+        asyncio.run(main())

examples/fastapi_integration_example.py

@@ -1,5 +1,5 @@
 """
-FastAPI Integration Example (v0.3.0)
+FastAPI Integration Example (v0.3.0 + v0.3.2)
 
 Demonstrates JarvisLifespan for 3-line FastAPI integration with autonomous agents.
 
@@ -8,6 +8,8 @@ Features shown:
     2. CustomAgent - API-first agents with on_peer_request handlers
     3. Cognitive Discovery - get_cognitive_context() for LLM awareness
     4. Autonomous Agents - Each agent has MESH as a TOOL, LLM decides when to delegate
+    5. Mesh Diagnostics (v0.3.2) - /health endpoint using get_diagnostics()
+    6. Session Context (v0.3.2) - Request tracking with context parameter
 
 Real-World Flow:
     HTTP Request → Agent A (with LLM) → LLM sees peers as tools
@@ -22,6 +24,9 @@ Usage:
         -H "Content-Type: application/json" \
         -d '{"message": "Analyze the Q4 sales trends"}'
 
+    # Check mesh health (v0.3.2)
+    curl http://localhost:8000/health
+
     # Optional: Start a standalone agent that joins the mesh (in another terminal)
     python examples/fastapi_integration_example.py --join-as scout
 
@@ -32,6 +37,7 @@ Prerequisites:
 import asyncio
 import sys
 import os
+import uuid
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
@@ -104,14 +110,27 @@ class LLMAgent(CustomAgent):
             }
         }]
 
-    async def _ask_peer(self, role: str, question: str) -> dict:
+    async def _ask_peer(self, role: str, question: str, request_id: str = None) -> dict:
         """Execute ask_peer tool - send request to another agent."""
         print(f"[{self.role}] Asking {role}: {question[:50]}...")
-        response = await self.peers.request(role, {"question": question}, timeout=30)
+
+        # v0.3.2: Pass context for request tracking
+        context = {
+            "request_id": request_id or str(uuid.uuid4()),
+            "source_agent": self.role,
+            "tool": "ask_peer"
+        }
+
+        response = await self.peers.request(
+            role,
+            {"question": question},
+            timeout=30,
+            context=context  # v0.3.2: Session context
+        )
         print(f"[{self.role}] Got response from {role}")
         return response
 
-    async def chat(self, message: str) -> dict:
+    async def chat(self, message: str, request_id: str = None) -> dict:
         """
         Process a message with LLM that can discover and delegate to peers.
 
@@ -119,7 +138,14 @@ class LLMAgent(CustomAgent):
         1. Build system prompt with WHO I AM + WHO ELSE IS AVAILABLE
         2. LLM sees available peers as potential helpers
         3. LLM decides whether to handle directly or delegate
+
+        Args:
+            message: The user message to process
+            request_id: Optional request ID for tracking (v0.3.2)
         """
+        # v0.3.2: Generate request_id for tracking if not provided
+        request_id = request_id or str(uuid.uuid4())
+
         if not self.llm:
             return await self._chat_mock(message)
 
@@ -154,7 +180,8 @@ class LLMAgent(CustomAgent):
             role = tool_use_block.input.get("role")
             question = tool_use_block.input.get("question")
 
-            peer_response = await self._ask_peer(role, question)
+            # v0.3.2: Pass request_id for tracing
+            peer_response = await self._ask_peer(role, question, request_id=request_id)
 
             # Continue with tool result
             messages = [{"role": "user", "content": message}]
@@ -467,6 +494,36 @@ def create_app():
                 }
         return result
 
+    @app.get("/health")
+    async def health_check(request: Request):
+        """
+        Health check endpoint using mesh diagnostics (v0.3.2).
+
+        Returns mesh status, connected agents, and network health.
+        Useful for Kubernetes probes, load balancer checks, and monitoring.
+        """
+        # Get the mesh from JarvisLifespan state
+        mesh = getattr(request.app.state, "jarvis_mesh", None)
+        if not mesh:
+            return JSONResponse(
+                status_code=503,
+                content={"status": "unhealthy", "error": "Mesh not initialized"}
+            )
+
+        # v0.3.2: Use get_diagnostics() for comprehensive health info
+        diagnostics = mesh.get_diagnostics()
+
+        return {
+            "status": "healthy",
+            "mesh": {
+                "mode": diagnostics.get("mode", "unknown"),
+                "agent_count": diagnostics.get("agent_count", 0),
+                "agents": diagnostics.get("agents", []),
+            },
+            "network": diagnostics.get("network", {}),
+            "uptime_seconds": diagnostics.get("uptime_seconds", 0)
+        }
+
     @app.post("/chat")
     async def chat(request: Request):
         """
@@ -476,16 +533,21 @@ def create_app():
         1. Sees other agents via get_cognitive_context()
         2. Decides if it needs to delegate
         3. Uses ask_peer tool to communicate
+
+        v0.3.2: Supports request_id for tracking across agent boundaries.
         """
         body = await request.json()
         message = body.get("message", "")
 
+        # v0.3.2: Generate request_id for tracking
+        request_id = str(uuid.uuid4())
+
         assistant = request.app.state.jarvis_agents.get("assistant")
         if not assistant:
             return JSONResponse(status_code=503, content={"error": "Assistant not available"})
 
-        result = await assistant.chat(message)
-        return {"message": message, **result}
+        result = await assistant.chat(message, request_id=request_id)
+        return {"message": message, "request_id": request_id, **result}
 
     @app.post("/ask/{agent_role}")
     async def ask_agent(agent_role: str, request: Request):
@@ -551,6 +613,7 @@ def main():
     print("  - LLM decides when to delegate autonomously")
     print("  - Standalone agents can join with --join-as flag")
     print("\nEndpoints:")
+    print("  GET  /health      - Mesh health diagnostics (v0.3.2)")
     print("  GET  /agents      - Show what each agent sees")
     print("  POST /chat        - Chat with assistant (may delegate)")
     print("  POST /ask/{role}  - Ask specific agent directly")

jarviscore/__init__.py

@@ -60,7 +60,7 @@ Quick Start (CustomAgent - distributed mode):
     results = await mesh.workflow("demo", [{"agent": "processor", "task": "hello"}])
 """
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 __author__ = "JarvisCore Contributors"
 __license__ = "MIT"
 

jarviscore/core/mesh.py

@@ -624,6 +624,155 @@ class Mesh:
         """
         return self._capability_index.get(capability, [])
 
+    # ─────────────────────────────────────────────────────────────────
+    # DIAGNOSTICS
+    # ─────────────────────────────────────────────────────────────────
+
+    def get_diagnostics(self) -> Dict[str, Any]:
+        """
+        Get diagnostic information about the mesh and P2P connectivity.
+
+        Useful for debugging P2P issues, monitoring mesh health,
+        and understanding the current state of the distributed system.
+
+        Returns:
+            Dictionary containing:
+            - local_node: This node's configuration and status
+            - known_peers: List of discovered remote peers
+            - local_agents: List of local agents with capabilities
+            - connectivity_status: Overall health assessment
+            - keepalive_status: Keepalive manager health (if P2P enabled)
+            - swim_status: SWIM protocol status (if P2P enabled)
+            - capability_map: Mapping of capabilities to agent IDs
+
+        Example:
+            diagnostics = mesh.get_diagnostics()
+            print(f"Status: {diagnostics['connectivity_status']}")
+            for peer in diagnostics['known_peers']:
+                print(f"  {peer['role']} at {peer['node_id']}: {peer['status']}")
+        """
+        result = {
+            "local_node": self._get_local_node_info(),
+            "known_peers": self._get_peer_list(),
+            "local_agents": self._get_local_agents_info(),
+            "connectivity_status": self._assess_connectivity_status()
+        }
+
+        # Add P2P-specific diagnostics if coordinator is available
+        if self._p2p_coordinator:
+            result["keepalive_status"] = self._get_keepalive_status()
+            result["swim_status"] = self._get_swim_status()
+            result["capability_map"] = self._get_capability_map()
+
+        return result
+
+    def _get_local_node_info(self) -> Dict[str, Any]:
+        """Get local node information."""
+        info = {
+            "mode": self.mode.value,
+            "started": self._started,
+            "agent_count": len(self.agents)
+        }
+
+        if self._p2p_coordinator and self._p2p_coordinator.swim_manager:
+            addr = self._p2p_coordinator.swim_manager.bind_addr
+            if addr:
+                info["bind_address"] = f"{addr[0]}:{addr[1]}"
+
+        return info
+
+    def _get_peer_list(self) -> List[Dict[str, Any]]:
+        """Get list of known remote peers."""
+        peers = []
+
+        if self._p2p_coordinator:
+            for agent in self._p2p_coordinator.list_remote_agents():
+                peers.append({
+                    "role": agent.get("role", "unknown"),
+                    "agent_id": agent.get("agent_id", "unknown"),
+                    "node_id": agent.get("node_id", "unknown"),
+                    "capabilities": agent.get("capabilities", []),
+                    "status": "connected"
+                })
+
+        return peers
+
+    def _get_local_agents_info(self) -> List[Dict[str, Any]]:
+        """Get information about local agents."""
+        return [
+            {
+                "role": agent.role,
+                "agent_id": agent.agent_id,
+                "capabilities": list(agent.capabilities),
+                "description": getattr(agent, 'description', ''),
+                "has_peers": hasattr(agent, 'peers') and agent.peers is not None
+            }
+            for agent in self.agents
+        ]
+
+    def _assess_connectivity_status(self) -> str:
+        """
+        Assess overall connectivity status.
+
+        Returns:
+            "healthy" - P2P fully operational with peers
+            "isolated" - No peers connected
+            "degraded" - Some connectivity issues detected
+            "not_started" - Mesh not yet started
+            "local_only" - Not in distributed/p2p mode
+        """
+        if not self._started:
+            return "not_started"
+
+        if self.mode == MeshMode.AUTONOMOUS:
+            return "local_only"
+
+        if not self._p2p_coordinator:
+            return "local_only"
+
+        # Check SWIM health
+        if self._p2p_coordinator.swim_manager:
+            if not self._p2p_coordinator.swim_manager.is_healthy():
+                return "degraded"
+
+        # Check for connected peers
+        remote_agents = self._p2p_coordinator.list_remote_agents()
+        if not remote_agents:
+            return "isolated"
+
+        # Check keepalive health if available
+        if hasattr(self._p2p_coordinator, 'keepalive_manager') and self._p2p_coordinator.keepalive_manager:
+            health = self._p2p_coordinator.keepalive_manager.get_health_status()
+            if health.get('circuit_state') == 'OPEN':
+                return "degraded"
+
+        return "healthy"
+
+    def _get_keepalive_status(self) -> Optional[Dict[str, Any]]:
+        """Get keepalive manager status."""
+        if not self._p2p_coordinator:
+            return None
+
+        if hasattr(self._p2p_coordinator, 'keepalive_manager') and self._p2p_coordinator.keepalive_manager:
+            return self._p2p_coordinator.keepalive_manager.get_health_status()
+
+        return None
+
+    def _get_swim_status(self) -> Optional[Dict[str, Any]]:
+        """Get SWIM protocol status."""
+        if not self._p2p_coordinator or not self._p2p_coordinator.swim_manager:
+            return None
+
+        return self._p2p_coordinator.swim_manager.get_status()
+
+    def _get_capability_map(self) -> Dict[str, List[str]]:
+        """Get the capability to agent_id mapping."""
+        if not self._p2p_coordinator:
+            return {}
+
+        # Convert defaultdict to regular dict for serialization
+        return dict(self._p2p_coordinator._capability_map)
+
     def __repr__(self) -> str:
         """String representation of mesh."""
         return (