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

examples/cloud_deployment_example.py

@@ -28,10 +28,10 @@ import sys
 
 sys.path.insert(0, '.')
 
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 
 
-class StandaloneProcessor(ListenerAgent):
+class StandaloneProcessor(CustomAgent):
     """
     Example standalone agent that joins mesh independently.
 
@@ -143,7 +143,7 @@ async def main():
     print("Listening for peer requests...")
     print("Press Ctrl+C to stop.\n")
 
-    # Run agent (ListenerAgent's run() handles the message loop)
+    # Run agent (CustomAgent's run() handles the message loop)
     try:
         await agent.run()
     except asyncio.CancelledError:

examples/{listeneragent_cognitive_discovery_example.py → customagent_cognitive_discovery_example.py}

@@ -1,42 +1,47 @@
 """
-ListenerAgent + Cognitive Discovery Example
+CustomAgent + Cognitive Discovery Example
 
-Demonstrates two v0.3.0 features:
+Demonstrates v0.3.0 and v0.3.2 features:
 
-1. ListenerAgent - Handler-based P2P agents (no run() loop needed)
+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))
 
 from jarviscore import Mesh
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # SPECIALIST AGENT - Responds to requests from other agents
 # ═══════════════════════════════════════════════════════════════════════════════
 
-class AnalystAgent(ListenerAgent):
+class AnalystAgent(CustomAgent):
     """
     Specialist agent that handles analysis requests.
 
-    Uses ListenerAgent profile - just implement handlers, no run() loop needed.
+    Uses CustomAgent profile - just implement handlers, no run() loop needed.
     """
     role = "analyst"
     capabilities = ["data_analysis", "statistics", "insights"]
@@ -45,13 +50,21 @@ class AnalystAgent(ListenerAgent):
     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")
@@ -62,7 +75,7 @@ class AnalystAgent(ListenerAgent):
 # COORDINATOR AGENT - Uses LLM with cognitive discovery
 # ═══════════════════════════════════════════════════════════════════════════════
 
-class CoordinatorAgent(ListenerAgent):
+class CoordinatorAgent(CustomAgent):
     """
     Coordinator agent that uses LLM with dynamic peer discovery.
 
@@ -78,6 +91,9 @@ class CoordinatorAgent(ListenerAgent):
     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,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")

jarviscore/__init__.py

@@ -4,16 +4,15 @@ JarvisCore - P2P Distributed Agent Framework
 A production-grade framework for building autonomous agent systems with:
 - P2P coordination via SWIM protocol
 - Workflow orchestration with dependencies
-- Three agent profiles: AutoAgent, CustomAgent, and ListenerAgent
+- Two agent profiles: AutoAgent and CustomAgent
 
 Profiles:
-    AutoAgent     - LLM generates and executes code from prompts (autonomous mode)
-    CustomAgent   - You provide execute_task() or run() (p2p/distributed modes)
-    ListenerAgent - API-first agents with background P2P (just implement handlers)
+    AutoAgent   - LLM generates and executes code from prompts (autonomous mode)
+    CustomAgent - You provide handlers or execute_task() (p2p/distributed modes)
 
 Modes:
     autonomous  - Workflow engine only (AutoAgent)
-    p2p         - P2P coordinator only (CustomAgent/ListenerAgent with run() loops)
+    p2p         - P2P coordinator only (CustomAgent with run() loop)
     distributed - Both workflow + P2P (CustomAgent with execute_task())
 
 Quick Start (AutoAgent - autonomous mode):
@@ -30,12 +29,12 @@ Quick Start (AutoAgent - autonomous mode):
     await mesh.start()
     results = await mesh.workflow("calc", [{"agent": "calculator", "task": "Calculate 10!"}])
 
-Quick Start (ListenerAgent + FastAPI):
+Quick Start (CustomAgent + FastAPI):
     from fastapi import FastAPI
-    from jarviscore.profiles import ListenerAgent
+    from jarviscore.profiles import CustomAgent
     from jarviscore.integrations.fastapi import JarvisLifespan
 
-    class MyAgent(ListenerAgent):
+    class MyAgent(CustomAgent):
         role = "processor"
         capabilities = ["processing"]
 
@@ -61,7 +60,7 @@ Quick Start (CustomAgent - distributed mode):
     results = await mesh.workflow("demo", [{"agent": "processor", "task": "hello"}])
 """
 
-__version__ = "0.3.0"
+__version__ = "0.3.2"
 __author__ = "JarvisCore Contributors"
 __license__ = "MIT"
 
@@ -73,7 +72,6 @@ from jarviscore.core.mesh import Mesh, MeshMode
 # Execution profiles
 from jarviscore.profiles.autoagent import AutoAgent
 from jarviscore.profiles.customagent import CustomAgent
-from jarviscore.profiles.listeneragent import ListenerAgent
 
 # Custom Profile: Decorator, Wrapper, and Context
 from jarviscore.adapter import jarvis_agent, wrap
@@ -99,7 +97,6 @@ __all__ = [
     # Profiles
     "AutoAgent",
     "CustomAgent",
-    "ListenerAgent",
 
     # Custom Profile (decorator and wrapper)
     "jarvis_agent",

jarviscore/cli/smoketest.py

@@ -313,7 +313,7 @@ class SmokeTest:
         print("\nJarvisCore is working correctly. Next steps:")
         print("  1. AutoAgent example:     python examples/calculator_agent_example.py")
         print("  2. CustomAgent P2P:       python examples/customagent_p2p_example.py")
-        print("  3. ListenerAgent (v0.3):  python examples/listeneragent_cognitive_discovery_example.py")
+        print("  3. Cognitive Discovery:   python examples/customagent_cognitive_discovery_example.py")
         print("  4. FastAPI (v0.3):        python examples/fastapi_integration_example.py")
         print("  5. Cloud deploy (v0.3):   python examples/cloud_deployment_example.py")
         print("\nDocumentation:")