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

jarviscore/core/mesh.py

@@ -256,9 +256,18 @@ class Mesh:
             await self._p2p_coordinator.start()
             self._logger.info("✓ P2P coordinator started")
 
+            # Wait for mesh to stabilize before announcing
+            # Increased delay to ensure SWIM fully connects all nodes
+            await asyncio.sleep(5)
+            self._logger.info("Waited for mesh stabilization")
+
             # Announce capabilities to network
             await self._p2p_coordinator.announce_capabilities()
             self._logger.info("✓ Capabilities announced to mesh")
+            
+            # Request capabilities from existing peers (for late-joiners)
+            await self._p2p_coordinator.request_peer_capabilities()
+            self._logger.info("✓ Requested capabilities from existing peers")
 
         # Inject PeerClients for p2p mode
         if self.mode == MeshMode.P2P:
@@ -615,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 (

jarviscore/data/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:

jarviscore/data/examples/custom_profile_decorator.py

@@ -0,0 +1,134 @@
+"""
+Custom Profile Example: Using @jarvis_agent Decorator
+
+This example shows how to use the @jarvis_agent decorator to convert
+any Python class into a JarvisCore agent without modifying the class.
+
+Use Case: You have existing Python classes/agents and want JarvisCore
+to handle orchestration (data handoff, dependencies, shared memory).
+"""
+import asyncio
+from jarviscore import Mesh, jarvis_agent, JarvisContext
+
+
+# Example 1: Simple decorator (no context needed)
+@jarvis_agent(role="processor", capabilities=["data_processing"])
+class DataProcessor:
+    """Simple data processor - doubles input values."""
+
+    def run(self, data):
+        """Process data by doubling values."""
+        if isinstance(data, list):
+            return {"processed": [x * 2 for x in data]}
+        return {"processed": data * 2}
+
+
+# Example 2: Decorator with context access
+@jarvis_agent(role="aggregator", capabilities=["aggregation"])
+class Aggregator:
+    """Aggregates results from previous steps using JarvisContext."""
+
+    def run(self, task, ctx: JarvisContext):
+        """
+        Access previous step results via ctx.previous().
+
+        Args:
+            task: The task description
+            ctx: JarvisContext with memory and dependency access
+        """
+        # Get output from a specific previous step
+        processed = ctx.previous("step1")
+
+        if processed:
+            data = processed.get("processed", [])
+            return {
+                "sum": sum(data) if isinstance(data, list) else data,
+                "count": len(data) if isinstance(data, list) else 1,
+                "source_step": "step1"
+            }
+
+        return {"error": "No previous data found"}
+
+
+# Example 3: Decorator with custom execute method
+@jarvis_agent(role="validator", capabilities=["validation"], execute_method="validate")
+class DataValidator:
+    """Validates data using a custom method name."""
+
+    def validate(self, data):
+        """Custom execute method - validates input data."""
+        if isinstance(data, list):
+            return {
+                "valid": all(isinstance(x, (int, float)) for x in data),
+                "count": len(data),
+                "type": "list"
+            }
+        return {
+            "valid": isinstance(data, (int, float)),
+            "type": type(data).__name__
+        }
+
+
+async def main():
+    """Run a multi-step workflow with custom profile agents."""
+    print("=" * 60)
+    print("  Custom Profile Example: @jarvis_agent Decorator")
+    print("=" * 60)
+
+    # Create mesh in autonomous mode
+    mesh = Mesh(mode="autonomous")
+
+    # Add our decorated agents
+    mesh.add(DataProcessor)
+    mesh.add(Aggregator)
+    mesh.add(DataValidator)
+
+    # Start the mesh
+    await mesh.start()
+
+    try:
+        # Execute a multi-step workflow
+        print("\nExecuting workflow with 3 steps...\n")
+
+        results = await mesh.workflow("custom-profile-demo", [
+            {
+                "id": "step1",
+                "agent": "processor",
+                "task": "Process input data",
+                "params": {"data": [1, 2, 3, 4, 5]}
+            },
+            {
+                "id": "step2",
+                "agent": "aggregator",
+                "task": "Aggregate processed results",
+                "depends_on": ["step1"]  # Wait for step1
+            },
+            {
+                "id": "step3",
+                "agent": "validator",
+                "task": "Validate original data",
+                "params": {"data": [1, 2, 3, 4, 5]}
+            }
+        ])
+
+        # Print results
+        print("Results:")
+        print("-" * 40)
+
+        for i, result in enumerate(results):
+            step_name = ["Processor", "Aggregator", "Validator"][i]
+            print(f"\n{step_name} (step{i+1}):")
+            print(f"  Status: {result.get('status')}")
+            print(f"  Output: {result.get('output')}")
+
+        print("\n" + "=" * 60)
+        print("  Workflow completed successfully!")
+        print("=" * 60)
+
+    finally:
+        # Stop the mesh
+        await mesh.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

jarviscore/data/examples/custom_profile_wrap.py

@@ -0,0 +1,168 @@
+"""
+Custom Profile Example: Using wrap() Function
+
+This example shows how to use the wrap() function to convert
+an existing instance into a JarvisCore agent.
+
+Use Case: You have an already-instantiated object (like a LangChain
+agent, CrewAI agent, or any configured instance) and want to use it
+with JarvisCore orchestration.
+"""
+import asyncio
+from jarviscore import Mesh, wrap, JarvisContext
+
+
+# Simulate an existing "LangChain-like" agent
+class ExternalLLMAgent:
+    """
+    Simulates an external LLM agent (like LangChain).
+    In real usage, this would be your actual LangChain/CrewAI agent.
+    """
+
+    def __init__(self, model_name: str, temperature: float = 0.7):
+        self.model_name = model_name
+        self.temperature = temperature
+        print(f"  Initialized ExternalLLMAgent with {model_name}")
+
+    def invoke(self, query: str) -> dict:
+        """LangChain-style invoke method."""
+        # Simulate LLM response
+        return {
+            "answer": f"Response to '{query}' from {self.model_name}",
+            "model": self.model_name,
+            "tokens_used": len(query.split()) * 10
+        }
+
+
+# Simulate a data processing service
+class DataService:
+    """Simulates an external data processing service."""
+
+    def __init__(self, api_url: str):
+        self.api_url = api_url
+        print(f"  Initialized DataService with {api_url}")
+
+    def run(self, data):
+        """Process data through the service."""
+        if isinstance(data, list):
+            return {
+                "transformed": [x ** 2 for x in data],
+                "source": self.api_url
+            }
+        return {"transformed": data ** 2, "source": self.api_url}
+
+
+# Simulate an agent that needs context
+class ContextAwareProcessor:
+    """Agent that uses JarvisContext to access previous results."""
+
+    def run(self, task, ctx: JarvisContext):
+        """Process with context access."""
+        # Get all previous results
+        all_previous = ctx.all_previous()
+
+        summary = {
+            "task": task,
+            "previous_steps": list(all_previous.keys()),
+            "combined_data": {}
+        }
+
+        for step_id, output in all_previous.items():
+            if isinstance(output, dict):
+                summary["combined_data"][step_id] = output
+
+        return summary
+
+
+async def main():
+    """Demonstrate wrapping existing instances."""
+    print("=" * 60)
+    print("  Custom Profile Example: wrap() Function")
+    print("=" * 60)
+
+    # Create instances of "external" agents
+    print("\nCreating external agent instances...")
+    llm_agent = ExternalLLMAgent(model_name="gpt-4-turbo", temperature=0.3)
+    data_service = DataService(api_url="https://api.example.com/process")
+    context_processor = ContextAwareProcessor()
+
+    # Wrap them for JarvisCore
+    print("\nWrapping instances for JarvisCore...")
+
+    wrapped_llm = wrap(
+        llm_agent,
+        role="llm_assistant",
+        capabilities=["chat", "qa"],
+        execute_method="invoke"  # LangChain uses "invoke"
+    )
+
+    wrapped_data = wrap(
+        data_service,
+        role="data_processor",
+        capabilities=["data_processing", "transformation"]
+        # execute_method auto-detected as "run"
+    )
+
+    wrapped_context = wrap(
+        context_processor,
+        role="context_aggregator",
+        capabilities=["aggregation", "summary"]
+    )
+
+    # Create mesh and add wrapped agents
+    mesh = Mesh(mode="autonomous")
+    mesh.add(wrapped_llm)
+    mesh.add(wrapped_data)
+    mesh.add(wrapped_context)
+
+    await mesh.start()
+
+    try:
+        print("\nExecuting workflow with wrapped agents...\n")
+
+        results = await mesh.workflow("wrap-demo", [
+            {
+                "id": "llm_step",
+                "agent": "llm_assistant",
+                "task": "What is the capital of France?",
+                "params": {"query": "What is the capital of France?"}
+            },
+            {
+                "id": "data_step",
+                "agent": "data_processor",
+                "task": "Transform numbers",
+                "params": {"data": [1, 2, 3, 4, 5]}
+            },
+            {
+                "id": "summary_step",
+                "agent": "context_aggregator",
+                "task": "Summarize all results",
+                "depends_on": ["llm_step", "data_step"]
+            }
+        ])
+
+        # Print results
+        print("Results:")
+        print("-" * 40)
+
+        step_names = ["LLM Assistant", "Data Processor", "Context Aggregator"]
+        for i, result in enumerate(results):
+            print(f"\n{step_names[i]}:")
+            print(f"  Status: {result.get('status')}")
+            output = result.get('output', {})
+            if isinstance(output, dict):
+                for key, value in output.items():
+                    print(f"  {key}: {value}")
+            else:
+                print(f"  Output: {output}")
+
+        print("\n" + "=" * 60)
+        print("  Workflow with wrapped instances completed!")
+        print("=" * 60)
+
+    finally:
+        await mesh.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

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