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

jarviscore/core/agent.py

@@ -5,14 +5,19 @@ This is the foundation of the JarvisCore framework. All agents inherit from this
 
 For p2p mode, agents can implement a run() method for their own execution loop
 and use self.peers for direct peer-to-peer communication.
+
+For cloud deployment, agents can self-register with a mesh using join_mesh().
 """
 from abc import ABC, abstractmethod
 from typing import List, Dict, Any, Optional, TYPE_CHECKING
 from uuid import uuid4
+import asyncio
 import logging
+import os
 
 if TYPE_CHECKING:
     from jarviscore.p2p import PeerClient
+    from jarviscore.p2p.coordinator import P2PCoordinator
 
 logger = logging.getLogger(__name__)
 
@@ -70,6 +75,10 @@ class Agent(ABC):
         self.peers: Optional['PeerClient'] = None  # Injected by Mesh in p2p mode
         self.shutdown_requested: bool = False  # Set True to stop run() loop
 
+        # Cloud deployment support (standalone mode)
+        self._standalone_p2p: Optional['P2PCoordinator'] = None
+        self._mesh_connected: bool = False
+
         self._logger.debug(f"Agent initialized: {self.agent_id}")
 
     @abstractmethod
@@ -204,3 +213,221 @@ class Agent(ABC):
     def __str__(self) -> str:
         """Human-readable string representation."""
         return f"{self.role} ({self.agent_id})"
+
+    # ─────────────────────────────────────────────────────────────────
+    # CLOUD DEPLOYMENT (Standalone Mode)
+    # ─────────────────────────────────────────────────────────────────
+
+    async def join_mesh(
+        self,
+        endpoint: str = None,
+        seed_nodes: str = None,
+        config: dict = None
+    ) -> bool:
+        """
+        Self-register with a running mesh (for cloud/container deployment).
+
+        Instead of using mesh.add(), agents can join an existing mesh
+        independently. This is the pattern for containerized deployments
+        where each container runs a single agent.
+
+        Args:
+            endpoint: Mesh endpoint (host:port) - uses JARVISCORE_MESH_ENDPOINT env if not provided
+            seed_nodes: Comma-separated seed nodes - uses JARVISCORE_SEED_NODES env if not provided
+            config: Additional P2P configuration options
+
+        Returns:
+            True if successfully joined the mesh
+
+        Raises:
+            ValueError: If no endpoint or seed_nodes provided and not in environment
+
+        Example - Direct:
+            agent = MyAgent()
+            await agent.join_mesh(seed_nodes="192.168.1.10:7946")
+            await agent.run()
+            await agent.leave_mesh()
+
+        Example - Environment Variable:
+            # Set JARVISCORE_SEED_NODES=192.168.1.10:7946
+            agent = MyAgent()
+            await agent.join_mesh()  # Auto-discovers from env
+            await agent.run()
+            await agent.leave_mesh()
+
+        Example - Docker/K8s:
+            # In container entrypoint
+            async def main():
+                agent = ProcessorAgent()
+                await agent.join_mesh()  # Uses env vars
+                await agent.run_standalone()  # Handles graceful shutdown
+        """
+        from jarviscore.p2p.coordinator import P2PCoordinator
+        from jarviscore.p2p.peer_client import PeerClient
+
+        # 1. Resolve connection info from args or environment
+        endpoint = endpoint or os.environ.get("JARVISCORE_MESH_ENDPOINT")
+        seed_nodes = seed_nodes or os.environ.get("JARVISCORE_SEED_NODES", "")
+
+        if not endpoint and not seed_nodes:
+            raise ValueError(
+                "Must provide endpoint, seed_nodes, or set "
+                "JARVISCORE_MESH_ENDPOINT / JARVISCORE_SEED_NODES environment variable"
+            )
+
+        # 2. Build P2P configuration - use same config loading as Mesh
+        from jarviscore.config import get_config_from_dict
+        mesh_config = get_config_from_dict(config)
+
+        # Set seed nodes for joining the cluster
+        if endpoint:
+            mesh_config["seed_nodes"] = endpoint
+        if seed_nodes:
+            mesh_config["seed_nodes"] = seed_nodes
+
+        # Find an available port for this agent's P2P listener
+        # SWIM doesn't support bind_port=0, so we find a free port
+        if "bind_port" not in mesh_config or mesh_config.get("bind_port") == 0:
+            import socket
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(('', 0))
+                mesh_config["bind_port"] = s.getsockname()[1]
+
+        mesh_config["node_name"] = f"agent-{self.agent_id}"
+
+        self._logger.info(f"Joining mesh via {endpoint or seed_nodes}...")
+
+        # 3. Setup agent (call setup hook)
+        await self.setup()
+
+        # 4. Start standalone P2P coordinator
+        self._standalone_p2p = P2PCoordinator([self], mesh_config)
+        await self._standalone_p2p.start()
+
+        # 5. Wait for SWIM cluster to converge
+        # This allows SWIM gossip to sync membership
+        import asyncio
+        self._logger.info("Waiting for SWIM cluster convergence...")
+        await asyncio.sleep(1.0)  # Brief wait for SWIM gossip
+
+        # 6. Request existing capabilities from peers (we're a late joiner)
+        # Note: request_peer_capabilities will wait for ZMQ connections internally
+        self._logger.info("Requesting capabilities from existing peers...")
+        await self._standalone_p2p.request_peer_capabilities()
+
+        # 7. Announce our own capabilities to mesh
+        # Note: announce_capabilities will wait for ZMQ connections internally
+        await self._standalone_p2p.announce_capabilities()
+
+        # 7. Setup PeerClient for this agent
+        node_id = ""
+        if self._standalone_p2p.swim_manager:
+            addr = self._standalone_p2p.swim_manager.bind_addr
+            if addr:
+                node_id = f"{addr[0]}:{addr[1]}"
+
+        self.peers = PeerClient(
+            coordinator=self._standalone_p2p,
+            agent_id=self.agent_id,
+            agent_role=self.role,
+            agent_registry={self.role: [self]},
+            node_id=node_id
+        )
+
+        # Register PeerClient with coordinator for message routing
+        self._standalone_p2p.register_peer_client(self.agent_id, self.peers)
+
+        self._mesh_connected = True
+        self._logger.info(f"Successfully joined mesh as {self.role} ({self.agent_id})")
+
+        return True
+
+    async def leave_mesh(self) -> bool:
+        """
+        Gracefully deregister from mesh.
+
+        Called when agent is shutting down to notify other nodes
+        that this agent is no longer available.
+
+        Returns:
+            True if successfully left the mesh
+
+        Example:
+            try:
+                await agent.run()
+            finally:
+                await agent.leave_mesh()
+        """
+        if not self._mesh_connected:
+            return True
+
+        self._logger.info("Leaving mesh...")
+
+        # 1. Deannounce capabilities (notify mesh we're leaving)
+        if self._standalone_p2p:
+            try:
+                await self._standalone_p2p.deannounce_capabilities()
+            except Exception as e:
+                self._logger.warning(f"Error deannouncing capabilities: {e}")
+
+        # 2. Unregister peer client
+        if self._standalone_p2p:
+            self._standalone_p2p.unregister_peer_client(self.agent_id)
+
+        # 3. Stop P2P coordinator
+        if self._standalone_p2p:
+            await self._standalone_p2p.stop()
+            self._standalone_p2p = None
+
+        # 4. Teardown agent (call teardown hook)
+        await self.teardown()
+
+        self._mesh_connected = False
+        self.peers = None
+        self._logger.info("Successfully left mesh")
+
+        return True
+
+    @property
+    def is_mesh_connected(self) -> bool:
+        """Check if agent is currently connected to a mesh."""
+        return self._mesh_connected
+
+    async def run_standalone(self):
+        """
+        Run agent in standalone mode with automatic mesh cleanup.
+
+        Combines run() loop with graceful leave_mesh() on exit.
+        Use this as the main entrypoint for containerized agents.
+
+        Example - Container Entrypoint:
+            async def main():
+                agent = ProcessorAgent()
+                await agent.join_mesh()
+                await agent.run_standalone()  # Blocks until shutdown
+
+            if __name__ == "__main__":
+                asyncio.run(main())
+        """
+        if not self._mesh_connected:
+            raise RuntimeError(
+                "Not connected to mesh. Call join_mesh() first."
+            )
+
+        try:
+            # Run the agent's main loop
+            if hasattr(self, 'run') and asyncio.iscoroutinefunction(self.run):
+                await self.run()
+            else:
+                # No run() method - just wait for shutdown signal
+                while not self.shutdown_requested:
+                    await asyncio.sleep(0.1)
+
+        except asyncio.CancelledError:
+            self._logger.info("Agent cancelled, cleaning up...")
+        except Exception as e:
+            self._logger.error(f"Agent error: {e}")
+            raise
+        finally:
+            # Always leave mesh gracefully
+            await self.leave_mesh()

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:

jarviscore/data/examples/cloud_deployment_example.py

@@ -0,0 +1,162 @@
+"""
+Cloud Deployment Example (v0.3.0)
+
+Demonstrates agent self-registration with join_mesh() and leave_mesh().
+Agents join an existing mesh independently - no central orchestrator needed.
+
+This is the pattern for:
+- Docker containers where each container runs one agent
+- Kubernetes pods with auto-scaling
+- Cloud Functions / Lambda
+- Any distributed deployment where agents start independently
+
+Usage:
+    # Terminal 1: Start a mesh (or use an existing one)
+    python examples/customagent_p2p_example.py
+
+    # Terminal 2: Run standalone agent that joins the mesh
+    JARVISCORE_SEED_NODES=127.0.0.1:7946 python examples/cloud_deployment_example.py
+
+Environment Variables:
+    JARVISCORE_SEED_NODES: Comma-separated seed nodes (e.g., "host1:7946,host2:7946")
+    JARVISCORE_MESH_ENDPOINT: Single mesh endpoint (alternative to seed_nodes)
+"""
+import asyncio
+import os
+import signal
+import sys
+
+sys.path.insert(0, '.')
+
+from jarviscore.profiles import CustomAgent
+
+
+class StandaloneProcessor(CustomAgent):
+    """
+    Example standalone agent that joins mesh independently.
+
+    This agent:
+    - Self-registers with the mesh on startup
+    - Listens for peer requests
+    - Shows its view of the mesh (cognitive context)
+    - Gracefully leaves mesh on shutdown
+    """
+
+    role = "standalone_processor"
+    capabilities = ["standalone", "processing", "example"]
+    description = "Processes requests from other mesh agents (standalone deployment)"
+
+    async def on_peer_request(self, msg):
+        """Handle incoming requests from other agents."""
+        print(f"\n[{self.role}] Received request from {msg.sender}:")
+        print(f"  Data: {msg.data}")
+
+        # Process the request
+        task = msg.data.get("task", "")
+        result = {
+            "status": "success",
+            "output": f"Processed: {task}",
+            "agent_id": self.agent_id,
+            "processed_by": self.role
+        }
+
+        print(f"[{self.role}] Sending response: {result}")
+        return result
+
+    async def on_peer_notify(self, msg):
+        """Handle incoming notifications from other agents."""
+        print(f"\n[{self.role}] Received notification from {msg.sender}:")
+        print(f"  Event: {msg.data.get('event', 'unknown')}")
+        print(f"  Data: {msg.data}")
+
+
+async def main():
+    print("=" * 60)
+    print("Standalone Agent Example - Cloud Deployment Pattern")
+    print("=" * 60)
+
+    # Check for mesh connection info
+    endpoint = os.environ.get("JARVISCORE_MESH_ENDPOINT")
+    seed_nodes = os.environ.get("JARVISCORE_SEED_NODES")
+
+    if not endpoint and not seed_nodes:
+        print("\nNo mesh endpoint configured!")
+        print("\nSet one of:")
+        print("  - JARVISCORE_MESH_ENDPOINT (single endpoint)")
+        print("  - JARVISCORE_SEED_NODES (comma-separated list)")
+        print("\nExample:")
+        print("  JARVISCORE_SEED_NODES=127.0.0.1:7946 python cloud_deployment_example.py")
+        print("\nTo start a mesh first, run:")
+        print("  python examples/customagent_p2p_example.py")
+        return
+
+    print(f"\nConnecting to mesh via: {endpoint or seed_nodes}")
+
+    # Create agent
+    agent = StandaloneProcessor()
+
+    # Join the mesh
+    print(f"\nJoining mesh...")
+    try:
+        await agent.join_mesh()
+    except Exception as e:
+        print(f"Failed to join mesh: {e}")
+        return
+
+    print(f"\nSuccessfully joined mesh!")
+    print(f"  Agent ID: {agent.agent_id}")
+    print(f"  Role: {agent.role}")
+    print(f"  Capabilities: {agent.capabilities}")
+
+    # Show discovered peers
+    print(f"\n--- Discovered Peers ---")
+    peers = agent.peers.list_peers()
+    if peers:
+        for p in peers:
+            location = f" ({p.get('location', 'unknown')})" if 'location' in p else ""
+            print(f"  - {p['role']}: {p['capabilities']}{location}")
+    else:
+        print("  No other peers discovered yet")
+
+    # Show cognitive context (what an LLM would see)
+    print(f"\n--- Cognitive Context for LLM ---")
+    print(agent.peers.get_cognitive_context())
+
+    # Setup graceful shutdown
+    shutdown_event = asyncio.Event()
+
+    def signal_handler():
+        print("\n\nShutdown requested (Ctrl+C)...")
+        agent.request_shutdown()
+        shutdown_event.set()
+
+    # Register signal handlers
+    loop = asyncio.get_event_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, signal_handler)
+        except NotImplementedError:
+            # Windows doesn't support add_signal_handler
+            pass
+
+    print(f"\n--- Agent Running ---")
+    print("Listening for peer requests...")
+    print("Press Ctrl+C to stop.\n")
+
+    # Run agent (CustomAgent's run() handles the message loop)
+    try:
+        await agent.run()
+    except asyncio.CancelledError:
+        pass
+
+    # Leave mesh gracefully
+    print("\nLeaving mesh...")
+    await agent.leave_mesh()
+    print("Goodbye!")
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        print("\nInterrupted.")

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())