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

jarviscore/data/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())

jarviscore/data/examples/fastapi_integration_example.py

@@ -1,13 +1,15 @@
 """
-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.
 
 Features shown:
     1. JarvisLifespan - Automatic agent lifecycle management
-    2. ListenerAgent - API-first agents with on_peer_request handlers
+    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))
@@ -45,14 +51,14 @@ except ImportError:
     FASTAPI_AVAILABLE = False
     print("FastAPI not installed. Run: pip install fastapi uvicorn")
 
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # LLM-POWERED AGENT BASE - Each agent can discover and delegate
 # ═══════════════════════════════════════════════════════════════════════════════
 
-class LLMAgent(ListenerAgent):
+class LLMAgent(CustomAgent):
     """
     Base for LLM-powered agents that can discover and delegate to peers.
 
@@ -104,14 +110,27 @@ class LLMAgent(ListenerAgent):
             }
         }]
 
-    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(ListenerAgent):
         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(ListenerAgent):
             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):
@@ -544,13 +606,14 @@ def main():
     print("=" * 60)
     print("\n - FastAPI Integration:")
     print("  - JarvisLifespan for one-line integration")
-    print("  - ListenerAgent with on_peer_request handlers")
+    print("  - CustomAgent with on_peer_request handlers")
     print("  - Cognitive discovery via get_cognitive_context()")
     print("\n - Cloud Deployment:")
     print("  - Each agent has MESH as a TOOL")
     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")