jarviscore-framework 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

jarviscore/core/mesh.py

@@ -1,9 +1,10 @@
 """
 Mesh - Central orchestrator for JarvisCore framework.
 
-The Mesh coordinates agent execution and provides two operational modes:
+The Mesh coordinates agent execution and provides three operational modes:
 - Autonomous: Execute multi-step workflows with dependency resolution
 - Distributed: Run as P2P service responding to task requests
+- P2P: Agents run their own loops with direct peer-to-peer communication
 
 Day 1: Foundation with agent registration and setup
 Day 2: P2P integration for agent discovery and coordination
@@ -11,6 +12,7 @@ Day 3: Full workflow orchestration with state management
 """
 from typing import List, Dict, Any, Optional, Type
 from enum import Enum
+import asyncio
 import logging
 
 from .agent import Agent
@@ -21,7 +23,8 @@ logger = logging.getLogger(__name__)
 class MeshMode(Enum):
     """Operational modes for Mesh."""
     AUTONOMOUS = "autonomous"  # Execute workflows locally
-    DISTRIBUTED = "distributed"  # Run as P2P service
+    DISTRIBUTED = "distributed"  # Run as P2P service (workflow-driven)
+    P2P = "p2p"  # Agents run own loops with direct peer communication
 
 
 class Mesh:
@@ -29,18 +32,23 @@ class Mesh:
     Central orchestrator for JarvisCore agent framework.
 
     The Mesh manages agent lifecycle, coordinates execution, and provides
-    two operational modes:
+    three operational modes:
 
     1. **Autonomous Mode**: Execute multi-step workflows locally
        - User defines workflow steps with dependencies
        - Mesh routes tasks to capable agents
        - Handles crash recovery and checkpointing
 
-    2. **Distributed Mode**: Run as P2P service
+    2. **Distributed Mode**: Run as P2P service (workflow-driven)
        - Agents join P2P network and announce capabilities
        - Receive and execute tasks from other nodes
        - Coordinate with remote agents for complex workflows
 
+    3. **P2P Mode**: Direct agent-to-agent communication
+       - Agents run their own execution loops via run() method
+       - Agents communicate directly via self.peers client
+       - No workflow engine - agents control their own flow
+
     Example (Autonomous):
         mesh = Mesh(mode="autonomous")
         mesh.add(ScraperAgent)
@@ -58,7 +66,15 @@ class Mesh:
         mesh.add(DatabaseAgent)
 
         await mesh.start()
-        await mesh.serve_forever()  # Run as service
+        await mesh.serve_forever()  # Run as workflow service
+
+    Example (P2P):
+        mesh = Mesh(mode="p2p")
+        mesh.add(ScoutAgent)    # Has run() method
+        mesh.add(AnalystAgent)  # Has run() method
+
+        await mesh.start()
+        await mesh.run_forever()  # Agents run their own loops
     """
 
     def __init__(
@@ -70,9 +86,9 @@ class Mesh:
         Initialize Mesh orchestrator.
 
         Args:
-            mode: Operational mode ("autonomous" or "distributed")
+            mode: Operational mode ("autonomous", "distributed", or "p2p")
             config: Optional configuration dictionary:
-                - p2p_enabled: Enable P2P networking (default: True for distributed)
+                - p2p_enabled: Enable P2P networking (default: True for distributed/p2p)
                 - state_backend: "file", "redis", "mongodb" (default: "file")
                 - event_store: Path or connection string for event storage
                 - checkpoint_interval: Save checkpoints every N steps (default: 1)
@@ -86,7 +102,7 @@ class Mesh:
             self.mode = MeshMode(mode)
         except ValueError:
             raise ValueError(
-                f"Invalid mode '{mode}'. Must be 'autonomous' or 'distributed'"
+                f"Invalid mode '{mode}'. Must be 'autonomous', 'distributed', or 'p2p'"
             )
 
         self.config = config or {}
@@ -107,7 +123,7 @@ class Mesh:
 
     def add(
         self,
-        agent_class: Type[Agent],
+        agent_class_or_instance,
         agent_id: Optional[str] = None,
         **kwargs
     ) -> Agent:
@@ -115,30 +131,39 @@ class Mesh:
         Register an agent with the mesh.
 
         Args:
-            agent_class: Agent class to instantiate (must inherit from Agent)
-            agent_id: Optional unique identifier for the agent
-            **kwargs: Additional arguments passed to agent constructor
+            agent_class_or_instance: Agent class to instantiate, or pre-instantiated
+                agent (from wrap() function). Must inherit from Agent.
+            agent_id: Optional unique identifier for the agent (ignored if instance)
+            **kwargs: Additional arguments passed to agent constructor (ignored if instance)
 
         Returns:
-            Instantiated agent instance
+            Agent instance
 
         Raises:
             ValueError: If agent with same role already registered
-            TypeError: If agent_class doesn't inherit from Agent
+            TypeError: If agent doesn't inherit from Agent
 
         Example:
             mesh = Mesh()
+
+            # Add a class (will be instantiated)
             scraper = mesh.add(ScraperAgent, agent_id="scraper-1")
-            processor = mesh.add(ProcessorAgent)
-        """
-        # Validate agent class
-        if not issubclass(agent_class, Agent):
-            raise TypeError(
-                f"{agent_class.__name__} must inherit from Agent base class"
-            )
 
-        # Instantiate agent
-        agent = agent_class(agent_id=agent_id, **kwargs)
+            # Add a pre-instantiated agent (from wrap())
+            wrapped = wrap(my_instance, role="processor", capabilities=["processing"])
+            mesh.add(wrapped)
+        """
+        # Check if it's already an instance (from wrap() function)
+        if isinstance(agent_class_or_instance, Agent):
+            agent = agent_class_or_instance
+        else:
+            # It's a class - validate and instantiate
+            agent_class = agent_class_or_instance
+            if not issubclass(agent_class, Agent):
+                raise TypeError(
+                    f"{agent_class.__name__} must inherit from Agent base class"
+                )
+            agent = agent_class(agent_id=agent_id, **kwargs)
 
         # Check for duplicate agent_ids
         if agent.agent_id in self._agent_ids:
@@ -149,7 +174,9 @@ class Mesh:
 
         # If agent_id was NOT explicitly provided (auto-generated),
         # prevent duplicate roles to avoid accidents
-        if agent_id is None and agent.role in self._agent_registry:
+        # For instances (from wrap()), check if it's a new role
+        is_instance = isinstance(agent_class_or_instance, Agent)
+        if not is_instance and agent_id is None and agent.role in self._agent_registry:
             raise ValueError(
                 f"Agent with role '{agent.role}' already registered. "
                 f"Use agent_id parameter to create multiple agents with same role."
@@ -215,8 +242,8 @@ class Mesh:
                 self._logger.error(f"Failed to setup agent {agent.agent_id}: {e}")
                 raise
 
-        # Initialize P2P coordinator (Day 2 implementation)
-        if self.mode == MeshMode.DISTRIBUTED or self.config.get("p2p_enabled", False):
+        # Initialize P2P coordinator for distributed and p2p modes
+        if self.mode in (MeshMode.DISTRIBUTED, MeshMode.P2P) or self.config.get("p2p_enabled", False):
             self._logger.info("Initializing P2P coordinator...")
             from jarviscore.p2p import P2PCoordinator
             from jarviscore.config import get_config_from_dict
@@ -233,8 +260,13 @@ class Mesh:
             await self._p2p_coordinator.announce_capabilities()
             self._logger.info("✓ Capabilities announced to mesh")
 
-        # Initialize workflow engine (Day 3 implementation)
-        if self.mode == MeshMode.AUTONOMOUS:
+        # Inject PeerClients for p2p mode
+        if self.mode == MeshMode.P2P:
+            self._inject_peer_clients()
+            self._logger.info("✓ PeerClients injected into agents")
+
+        # Initialize workflow engine (for autonomous and distributed modes)
+        if self.mode in (MeshMode.AUTONOMOUS, MeshMode.DISTRIBUTED):
             self._logger.info("Initializing workflow engine...")
             from jarviscore.orchestration import WorkflowEngine
 
@@ -300,10 +332,11 @@ class Mesh:
         if not self._started:
             raise RuntimeError("Mesh not started. Call await mesh.start() first.")
 
-        if self.mode != MeshMode.AUTONOMOUS:
+        if self.mode == MeshMode.P2P:
             raise RuntimeError(
-                f"workflow() only available in autonomous mode. "
-                f"Current mode: {self.mode.value}"
+                f"workflow() not available in p2p mode. "
+                f"P2P mode uses agent.run() loops with direct peer communication. "
+                f"Use autonomous or distributed mode for workflow orchestration."
             )
 
         self._logger.info(f"Executing workflow: {workflow_id} with {len(steps)} step(s)")
@@ -366,10 +399,11 @@ class Mesh:
         Stop mesh and cleanup resources.
 
         This method:
-        1. Calls teardown() on all agents
-        2. Disconnects from P2P network (distributed mode)
-        3. Saves state and checkpoints
-        4. Closes all connections
+        1. Requests shutdown for all agents (p2p mode)
+        2. Calls teardown() on all agents
+        3. Disconnects from P2P network
+        4. Saves state and checkpoints
+        5. Closes all connections
 
         Example:
             await mesh.stop()
@@ -379,6 +413,15 @@ class Mesh:
 
         self._logger.info("Stopping mesh...")
 
+        # Request shutdown for all agents (for p2p mode loops)
+        for agent in self.agents:
+            agent.request_shutdown()
+
+        # Unregister peer clients
+        if self._p2p_coordinator:
+            for agent in self.agents:
+                self._p2p_coordinator.unregister_peer_client(agent.agent_id)
+
         # Teardown agents
         for agent in self.agents:
             try:
@@ -400,6 +443,124 @@ class Mesh:
         self._started = False
         self._logger.info("Mesh stopped successfully")
 
+    def _inject_peer_clients(self):
+        """
+        Inject PeerClient instances into all agents.
+
+        Called during start() in p2p mode. Gives each agent a self.peers
+        client for direct peer-to-peer communication.
+        """
+        from jarviscore.p2p import PeerClient
+
+        node_id = ""
+        if self._p2p_coordinator and self._p2p_coordinator.swim_manager:
+            addr = self._p2p_coordinator.swim_manager.bind_addr
+            if addr:
+                node_id = f"{addr[0]}:{addr[1]}"
+
+        for agent in self.agents:
+            peer_client = PeerClient(
+                coordinator=self._p2p_coordinator,
+                agent_id=agent.agent_id,
+                agent_role=agent.role,
+                agent_registry=self._agent_registry,
+                node_id=node_id
+            )
+            agent.peers = peer_client
+
+            # Register with coordinator for remote message routing
+            if self._p2p_coordinator:
+                self._p2p_coordinator.register_peer_client(agent.agent_id, peer_client)
+
+            self._logger.debug(f"Injected PeerClient into agent: {agent.agent_id}")
+
+    async def run_forever(self):
+        """
+        Run all agent loops concurrently (p2p mode only).
+
+        In p2p mode, agents run their own execution loops via their run() method.
+        This method starts all agent loops and waits until shutdown is requested.
+
+        Raises:
+            RuntimeError: If mesh not started or not in p2p mode
+
+        Example:
+            mesh = Mesh(mode="p2p")
+            mesh.add(ScoutAgent)    # Has async def run(self)
+            mesh.add(AnalystAgent)  # Has async def run(self)
+
+            await mesh.start()
+            await mesh.run_forever()  # Blocks until Ctrl+C
+        """
+        if not self._started:
+            raise RuntimeError("Mesh not started. Call await mesh.start() first.")
+
+        if self.mode != MeshMode.P2P:
+            raise RuntimeError(
+                f"run_forever() only available in p2p mode. "
+                f"Current mode: {self.mode.value}. "
+                f"Use workflow() for autonomous mode or serve_forever() for distributed mode."
+            )
+
+        self._logger.info("Starting agent loops in p2p mode...")
+
+        # Collect all agent run() coroutines
+        agent_tasks = []
+        for agent in self.agents:
+            if hasattr(agent, 'run') and asyncio.iscoroutinefunction(agent.run):
+                task = asyncio.create_task(
+                    self._run_agent_loop(agent),
+                    name=f"agent-{agent.agent_id}"
+                )
+                agent_tasks.append(task)
+                self._logger.info(f"Started loop for agent: {agent.agent_id}")
+            else:
+                self._logger.warning(
+                    f"Agent {agent.agent_id} has no async run() method, skipping"
+                )
+
+        if not agent_tasks:
+            raise RuntimeError(
+                "No agents with run() method found. "
+                "p2p mode requires agents that implement async def run(self)."
+            )
+
+        self._logger.info(f"Running {len(agent_tasks)} agent loop(s). Press Ctrl+C to stop.")
+
+        # Run until shutdown
+        try:
+            await asyncio.gather(*agent_tasks)
+        except asyncio.CancelledError:
+            self._logger.info("Agent loops cancelled")
+        except KeyboardInterrupt:
+            self._logger.info("Keyboard interrupt received")
+        finally:
+            # Request shutdown for all agents
+            for agent in self.agents:
+                agent.request_shutdown()
+
+            # Cancel any remaining tasks
+            for task in agent_tasks:
+                if not task.done():
+                    task.cancel()
+
+            await self.stop()
+
+    async def _run_agent_loop(self, agent: Agent):
+        """
+        Run a single agent's loop with error handling.
+
+        Wraps the agent's run() method to catch and log errors.
+        """
+        try:
+            await agent.run()
+        except asyncio.CancelledError:
+            self._logger.debug(f"Agent {agent.agent_id} loop cancelled")
+            raise
+        except Exception as e:
+            self._logger.error(f"Agent {agent.agent_id} loop error: {e}")
+            raise
+
     def _find_agent_for_step(self, step: Dict[str, Any]) -> Optional[Agent]:
         """
         Find agent capable of executing a step.

jarviscore/data/examples/autoagent_distributed_example.py

@@ -0,0 +1,211 @@
+"""
+AutoAgent Distributed Mode Example
+
+Demonstrates AutoAgent in distributed mode, which combines:
+- P2P network layer (SWIM protocol, ZMQ messaging)
+- Workflow orchestration (step execution, dependencies)
+
+This is ideal for multi-node deployments where agents can:
+- Execute on different machines
+- Discover each other via SWIM
+- Run orchestrated workflows across the network
+
+Usage:
+    python examples/autoagent_distributed_example.py
+
+Prerequisites:
+    - .env file with LLM API key (CLAUDE_API_KEY, etc.)
+"""
+import asyncio
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from jarviscore import Mesh
+from jarviscore.profiles import AutoAgent
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# AUTOAGENT DEFINITIONS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class DataCollectorAgent(AutoAgent):
+    """Collects and generates data."""
+    role = "collector"
+    capabilities = ["data_collection", "sampling"]
+    system_prompt = """
+    You are a data collection specialist. Generate sample datasets
+    based on specifications. Use Python's standard library only.
+    Store results in a variable named 'result' as a dictionary.
+    """
+
+
+class DataProcessorAgent(AutoAgent):
+    """Processes and transforms data."""
+    role = "processor"
+    capabilities = ["data_processing", "transformation"]
+    system_prompt = """
+    You are a data processing expert. Transform and clean datasets.
+    Apply filters, aggregations, and transformations as needed.
+    Use Python's standard library only. Store results in 'result'.
+    """
+
+
+class ReportWriterAgent(AutoAgent):
+    """Generates reports from processed data."""
+    role = "reporter"
+    capabilities = ["reporting", "documentation"]
+    system_prompt = """
+    You are a technical writer. Create clear, well-formatted reports
+    from data. Use markdown formatting. Store the report in 'result'.
+    """
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# MAIN EXAMPLE
+# ═══════════════════════════════════════════════════════════════════════════════
+
+async def main():
+    """Run AutoAgent distributed mode example."""
+    print("\n" + "="*70)
+    print("JarvisCore: AutoAgent in Distributed Mode")
+    print("="*70)
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # KEY DIFFERENCE: mode="distributed" with P2P configuration
+    # ─────────────────────────────────────────────────────────────────────────
+    mesh = Mesh(
+        mode="distributed",  # Enables P2P + Workflow Engine
+        config={
+            # P2P Network Configuration
+            'bind_host': '127.0.0.1',    # Interface to bind to
+            'bind_port': 7950,            # SWIM protocol port (ZMQ uses +1000)
+            'node_name': 'autoagent-node',
+
+            # For multi-node: uncomment to join existing cluster
+            # 'seed_nodes': '192.168.1.10:7950,192.168.1.11:7950',
+
+            # AutoAgent Configuration
+            'execution_timeout': 60,      # Max seconds per task
+            'max_repair_attempts': 2,     # Auto-repair on failure
+            'log_directory': './logs',    # Result storage
+        }
+    )
+
+    # Add agents - same as autonomous mode
+    mesh.add(DataCollectorAgent)
+    mesh.add(DataProcessorAgent)
+    mesh.add(ReportWriterAgent)
+
+    try:
+        await mesh.start()
+
+        print("\n[INFO] Mesh started in DISTRIBUTED mode")
+        print(f"  - P2P Coordinator: Active (port {mesh.config.get('bind_port', 7950)})")
+        print(f"  - Workflow Engine: Active")
+        print(f"  - Agents: {len(mesh.agents)}")
+
+        # ─────────────────────────────────────────────────────────────────────
+        # WORKFLOW EXECUTION - Same API as autonomous mode
+        # ─────────────────────────────────────────────────────────────────────
+        print("\n" + "-"*70)
+        print("Executing Pipeline: Collect → Process → Report")
+        print("-"*70)
+
+        results = await mesh.workflow("distributed-pipeline", [
+            {
+                "id": "collect",
+                "agent": "collector",
+                "task": "Generate a dataset of 10 products with name, price, and category"
+            },
+            {
+                "id": "process",
+                "agent": "processor",
+                "task": "Calculate total value, average price, and count by category",
+                "depends_on": ["collect"]
+            },
+            {
+                "id": "report",
+                "agent": "reporter",
+                "task": "Create a summary report with the statistics",
+                "depends_on": ["process"]
+            }
+        ])
+
+        # Display results
+        print("\n" + "="*70)
+        print("RESULTS")
+        print("="*70)
+
+        for i, result in enumerate(results):
+            step_names = ["Data Collection", "Data Processing", "Report Generation"]
+            print(f"\n{step_names[i]}:")
+            print(f"  Status: {result['status']}")
+            if result['status'] == 'success':
+                output = str(result.get('output', ''))[:200]
+                print(f"  Output: {output}...")
+            else:
+                print(f"  Error: {result.get('error')}")
+
+        # Summary
+        successes = sum(1 for r in results if r['status'] == 'success')
+        print(f"\n{'='*70}")
+        print(f"Pipeline Complete: {successes}/{len(results)} steps successful")
+        print(f"{'='*70}")
+
+        await mesh.stop()
+
+    except Exception as e:
+        print(f"\nError: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# MULTI-NODE EXAMPLE (Reference)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+async def multi_node_example():
+    """
+    Example: Running agents across multiple machines.
+
+    Node 1 (seed node):
+        mesh = Mesh(mode="distributed", config={
+            'bind_host': '0.0.0.0',
+            'bind_port': 7950,
+            'node_name': 'node-1',
+        })
+        mesh.add(DataCollectorAgent)
+        await mesh.start()
+        await mesh.serve_forever()  # Keep running
+
+    Node 2 (joins cluster):
+        mesh = Mesh(mode="distributed", config={
+            'bind_host': '0.0.0.0',
+            'bind_port': 7950,
+            'node_name': 'node-2',
+            'seed_nodes': '192.168.1.10:7950',  # Node 1's address
+        })
+        mesh.add(DataProcessorAgent)
+        await mesh.start()
+        await mesh.serve_forever()
+
+    Node 3 (joins cluster):
+        mesh = Mesh(mode="distributed", config={
+            'bind_host': '0.0.0.0',
+            'bind_port': 7950,
+            'node_name': 'node-3',
+            'seed_nodes': '192.168.1.10:7950',
+        })
+        mesh.add(ReportWriterAgent)
+        await mesh.start()
+        await mesh.serve_forever()
+
+    Any node can now execute workflows that span all three!
+    """
+    pass
+
+
+if __name__ == "__main__":
+    asyncio.run(main())