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

jarviscore/docs/TROUBLESHOOTING.md

@@ -563,4 +563,4 @@ If significantly slower:
 
 ## Version
 
-Troubleshooting Guide for JarvisCore v0.2.1
+Troubleshooting Guide for JarvisCore v0.3.1

jarviscore/docs/USER_GUIDE.md

@@ -146,8 +146,7 @@ mesh = Mesh(mode="distributed", config={'bind_port': 7950})
 | Profile | Best For | How It Works |
 |---------|----------|--------------|
 | **AutoAgent** | Rapid prototyping | LLM generates + executes code from prompts |
-| **CustomAgent** | Existing code | You provide `execute_task()` or `run()` |
-| **ListenerAgent** | API-first agents | Just implement `on_peer_request()` handlers |
+| **CustomAgent** | Your own code | Implement `on_peer_request()` for P2P or `execute_task()` for workflows |
 
 See [AutoAgent Guide](AUTOAGENT_GUIDE.md) and [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) for details.
 
@@ -227,7 +226,7 @@ asyncio.run(data_analyst_demo())
 
 ## Custom Profile Tutorial
 
-The **Custom Profile** (decorator/wrap approach) is deprecated. Use **CustomAgent** instead.
+Use **CustomAgent** profile.
 
 See [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) for:
 - Converting standalone agents to JarvisCore
@@ -546,10 +545,10 @@ Deploy agents as FastAPI services with minimal boilerplate:
 
 ```python
 from fastapi import FastAPI, Request
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 from jarviscore.integrations.fastapi import JarvisLifespan
 
-class ProcessorAgent(ListenerAgent):
+class ProcessorAgent(CustomAgent):
     role = "processor"
     capabilities = ["processing"]
 
@@ -583,9 +582,9 @@ Deploy agents to containers without a central orchestrator:
 ```python
 # In your container entrypoint
 import asyncio
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 
-class MyAgent(ListenerAgent):
+class MyAgent(CustomAgent):
     role = "worker"
     capabilities = ["processing"]
 
@@ -905,6 +904,6 @@ mesh = Mesh(config=config)
 
 ## Version
 
-User Guide for JarvisCore v0.3.0
+User Guide for JarvisCore v0.3.1
 
-Last Updated: 2026-01-29
+Last Updated: 2026-02-02

jarviscore/integrations/fastapi.py

@@ -49,9 +49,9 @@ class JarvisLifespan:
     Example - Single Agent:
         from fastapi import FastAPI, Request
         from jarviscore.integrations.fastapi import JarvisLifespan
-        from jarviscore.profiles import ListenerAgent
+        from jarviscore.profiles import CustomAgent
 
-        class MyAgent(ListenerAgent):
+        class MyAgent(CustomAgent):
             role = "processor"
             capabilities = ["processing"]
 
@@ -220,9 +220,9 @@ def create_jarvis_app(
 
     Example:
         from jarviscore.integrations.fastapi import create_jarvis_app
-        from jarviscore.profiles import ListenerAgent
+        from jarviscore.profiles import CustomAgent
 
-        class MyAgent(ListenerAgent):
+        class MyAgent(CustomAgent):
             role = "processor"
             capabilities = ["processing"]
 

jarviscore/p2p/peer_client.py

@@ -153,6 +153,7 @@ class PeerClient:
         """
         results = []
 
+        # Search LOCAL agents first
         if role:
             agents = self._agent_registry.get(role, [])
             for agent in agents:
@@ -166,7 +167,7 @@ class PeerClient:
                     ))
 
         elif capability:
-            # Search all agents for capability
+            # Search all local agents for capability
             for role_name, agents in self._agent_registry.items():
                 for agent in agents:
                     if agent.agent_id != self._agent_id:  # Exclude self
@@ -180,7 +181,7 @@ class PeerClient:
                             ))
 
         else:
-            # Return all peers
+            # Return all local peers
             for role_name, agents in self._agent_registry.items():
                 for agent in agents:
                     if agent.agent_id != self._agent_id:  # Exclude self
@@ -192,6 +193,32 @@ class PeerClient:
                             status="alive"
                         ))
 
+        # BUG FIX: Also search REMOTE agents from other nodes
+        # Access coordinator's _remote_agent_registry
+        if self._coordinator and hasattr(self._coordinator, '_remote_agent_registry'):
+            remote_registry = self._coordinator._remote_agent_registry
+            
+            for agent_id, info in remote_registry.items():
+                if agent_id == self._agent_id:  # Exclude self
+                    continue
+                
+                # Filter by role if specified
+                if role and info.get('role') != role:
+                    continue
+                
+                # Filter by capability if specified
+                if capability and capability not in info.get('capabilities', []):
+                    continue
+                
+                # Add remote peer
+                results.append(PeerInfo(
+                    agent_id=info['agent_id'],
+                    role=info['role'],
+                    capabilities=info.get('capabilities', []),
+                    node_id=info.get('node_id', 'unknown'),
+                    status="alive"
+                ))
+
         return results
 
     @property

jarviscore/profiles/__init__.py

@@ -3,12 +3,10 @@ Execution profiles for agents.
 
 Profiles define HOW agents execute tasks:
 - AutoAgent: LLM-powered code generation + sandboxed execution
-- CustomAgent: User-defined logic (LangChain, MCP, raw Python)
-- ListenerAgent: API-first agents with background P2P listening
+- CustomAgent: User-defined logic with P2P message handling
 """
 
 from .autoagent import AutoAgent
 from .customagent import CustomAgent
-from .listeneragent import ListenerAgent
 
-__all__ = ["AutoAgent", "CustomAgent", "ListenerAgent"]
+__all__ = ["AutoAgent", "CustomAgent"]

jarviscore/profiles/customagent.py

@@ -1,87 +1,130 @@
 """
-CustomAgent - User-controlled execution profile.
-
-User provides their own implementation using any framework:
-- LangChain
-- MCP (Model Context Protocol)
-- CrewAI
-- Raw Python
-- Any other tool/framework
+CustomAgent - User-controlled execution profile with P2P message handling.
+
+Unified profile for building agents that:
+- Handle P2P mesh communication (requests, notifications)
+- Execute workflow tasks
+- Integrate with HTTP APIs (FastAPI, Flask, etc.)
+
+Example - Basic P2P Agent:
+    class AnalystAgent(CustomAgent):
+        role = "analyst"
+        capabilities = ["analysis"]
+
+        async def on_peer_request(self, msg):
+            result = await self.analyze(msg.data)
+            return {"status": "success", "result": result}
+
+Example - With FastAPI:
+    from fastapi import FastAPI
+    from jarviscore.integrations.fastapi import JarvisLifespan
+
+    class ProcessorAgent(CustomAgent):
+        role = "processor"
+        capabilities = ["processing"]
+
+        async def on_peer_request(self, msg):
+            return {"result": await self.process(msg.data)}
+
+    app = FastAPI(lifespan=JarvisLifespan(ProcessorAgent(), mode="p2p"))
 """
-from typing import Dict, Any
+from typing import Dict, Any, Optional
+import asyncio
+import logging
+
 from jarviscore.core.profile import Profile
 
+logger = logging.getLogger(__name__)
+
 
 class CustomAgent(Profile):
     """
-    Custom execution profile with full user control.
+    User-controlled agent profile with P2P message handling.
+
+    For P2P messaging, implement these handlers:
+        on_peer_request(msg) - Handle requests, return response
+        on_peer_notify(msg)  - Handle notifications (fire-and-forget)
+        on_error(error, msg) - Handle errors
 
-    User defines:
-    - role: str
-    - capabilities: List[str]
-    - setup(): Initialize custom framework/tools
-    - execute_task(): Custom execution logic
+    For workflow execution:
+        execute_task(task)   - Handle workflow tasks directly
+        (defaults to delegating to on_peer_request)
 
-    Framework provides:
-    - Orchestration (task claiming, dependencies, nudging)
-    - P2P coordination (agent discovery, task routing)
-    - State management (crash recovery, HITL)
-    - Cost tracking (if user provides token counts)
+    Configuration:
+        listen_timeout: Seconds to wait for messages (default: 1.0)
+        auto_respond: Auto-send on_peer_request return value (default: True)
 
-    Example with LangChain:
-        class APIAgent(CustomAgent):
-            role = "api_client"
-            capabilities = ["api_calls"]
+    Example - P2P Agent:
+        class AnalystAgent(CustomAgent):
+            role = "analyst"
+            capabilities = ["analysis"]
+
+            async def on_peer_request(self, msg):
+                result = await self.analyze(msg.data)
+                return {"status": "success", "result": result}
+
+    Example - With LangChain:
+        class LangChainAgent(CustomAgent):
+            role = "assistant"
+            capabilities = ["chat"]
 
             async def setup(self):
                 await super().setup()
                 from langchain.agents import Agent
                 self.lc_agent = Agent(...)
 
-            async def execute_task(self, task):
-                result = await self.lc_agent.run(task["task"])
+            async def on_peer_request(self, msg):
+                result = await self.lc_agent.run(msg.data["query"])
                 return {"status": "success", "output": result}
 
-    Example with MCP:
+    Example - With MCP:
         class MCPAgent(CustomAgent):
             role = "tool_user"
             capabilities = ["mcp_tools"]
-            mcp_server_url = "stdio://./server.py"
 
             async def setup(self):
                 await super().setup()
                 from mcp import Client
-                self.mcp = Client(self.mcp_server_url)
+                self.mcp = Client("stdio://./server.py")
                 await self.mcp.connect()
 
-            async def execute_task(self, task):
-                result = await self.mcp.call_tool("my_tool", task["params"])
+            async def on_peer_request(self, msg):
+                result = await self.mcp.call_tool("my_tool", msg.data)
                 return {"status": "success", "data": result}
 
-    Example with Raw Python:
-        class DataProcessor(CustomAgent):
+    Example - With FastAPI:
+        from fastapi import FastAPI
+        from jarviscore.integrations.fastapi import JarvisLifespan
+
+        class ProcessorAgent(CustomAgent):
             role = "processor"
             capabilities = ["data_processing"]
 
-            async def execute_task(self, task):
-                # Pure Python logic
-                data = task["params"]["data"]
-                processed = [x * 2 for x in data]
-                return {"status": "success", "output": processed}
+            async def on_peer_request(self, msg):
+                if msg.data.get("action") == "process":
+                    return {"result": await self.process(msg.data["payload"])}
+                return {"error": "unknown action"}
+
+        agent = ProcessorAgent()
+        app = FastAPI(lifespan=JarvisLifespan(agent, mode="p2p"))
+
+        @app.post("/process")
+        async def process_endpoint(data: dict, request: Request):
+            # HTTP endpoint - primary interface
+            agent = request.app.state.jarvis_agents["processor"]
+            return await agent.process(data)
     """
 
-    def __init__(self, agent_id=None):
-        super().__init__(agent_id)
+    # Configuration - can be overridden in subclasses
+    listen_timeout: float = 1.0  # Seconds to wait for messages
+    auto_respond: bool = True    # Automatically send response for requests
 
-        # User can add any custom attributes
-        # e.g., mcp_server_url, langchain_config, etc.
+    def __init__(self, agent_id: Optional[str] = None):
+        super().__init__(agent_id)
 
     async def setup(self):
         """
-        User implements this to initialize custom framework/tools.
-
-        DAY 1: Base implementation (user overrides)
-        DAY 5+: Full examples with LangChain, MCP, etc.
+        Initialize agent resources. Override to add custom setup.
 
         Example:
             async def setup(self):
@@ -91,47 +134,225 @@ class CustomAgent(Profile):
                 self.agent = Agent(...)
         """
         await super().setup()
-
         self._logger.info(f"CustomAgent setup: {self.agent_id}")
-        self._logger.info(
-            f"  Note: Override setup() to initialize your custom framework"
+
+    # ─────────────────────────────────────────────────────────────────
+    # P2P Message Handling
+    # ─────────────────────────────────────────────────────────────────
+
+    async def run(self):
+        """
+        Listener loop - receives and dispatches P2P messages.
+
+        Runs automatically in P2P mode. Dispatches messages to:
+        - on_peer_request() for request-response messages
+        - on_peer_notify() for fire-and-forget notifications
+
+        You typically don't need to override this. Just implement the handlers.
+        """
+        self._logger.info(f"[{self.role}] Listener loop started")
+
+        while not self.shutdown_requested:
+            try:
+                # Wait for incoming message with timeout
+                # Timeout allows periodic shutdown_requested checks
+                msg = await self.peers.receive(timeout=self.listen_timeout)
+
+                if msg is None:
+                    # Timeout - no message, continue loop to check shutdown
+                    continue
+
+                # Dispatch to appropriate handler
+                await self._dispatch_message(msg)
+
+            except asyncio.CancelledError:
+                self._logger.debug(f"[{self.role}] Listener loop cancelled")
+                raise
+            except Exception as e:
+                self._logger.error(f"[{self.role}] Listener loop error: {e}")
+                await self.on_error(e, None)
+
+        self._logger.info(f"[{self.role}] Listener loop stopped")
+
+    async def _dispatch_message(self, msg):
+        """
+        Dispatch message to appropriate handler based on message type.
+
+        Handles:
+        - REQUEST messages: calls on_peer_request, sends response if auto_respond=True
+        - NOTIFY messages: calls on_peer_notify
+        """
+        from jarviscore.p2p.messages import MessageType
+
+        try:
+            # Check if this is a request (expects response)
+            is_request = (
+                msg.type == MessageType.REQUEST or
+                getattr(msg, 'is_request', False) or
+                msg.correlation_id is not None
+            )
+
+            if is_request:
+                # Request-response: call handler, optionally send response
+                response = await self.on_peer_request(msg)
+
+                if self.auto_respond and response is not None:
+                    await self.peers.respond(msg, response)
+                    self._logger.debug(
+                        f"[{self.role}] Sent response to {msg.sender}"
+                    )
+            else:
+                # Notification: fire-and-forget
+                await self.on_peer_notify(msg)
+
+        except Exception as e:
+            self._logger.error(
+                f"[{self.role}] Error handling message from {msg.sender}: {e}"
+            )
+            await self.on_error(e, msg)
+
+    # ─────────────────────────────────────────────────────────────────
+    # Message Handlers - Override in your agent
+    # ─────────────────────────────────────────────────────────────────
+
+    async def on_peer_request(self, msg) -> Any:
+        """
+        Handle incoming peer request.
+
+        Override to process request-response messages from other agents.
+        The return value is automatically sent as response (if auto_respond=True).
+
+        Args:
+            msg: IncomingMessage with:
+                - msg.sender: Sender agent ID or role
+                - msg.data: Request payload (dict)
+                - msg.correlation_id: For response matching (handled automatically)
+
+        Returns:
+            Response data (dict) to send back to the requester.
+            Return None to skip sending a response.
+
+        Example:
+            async def on_peer_request(self, msg):
+                action = msg.data.get("action")
+
+                if action == "analyze":
+                    result = await self.analyze(msg.data["payload"])
+                    return {"status": "success", "result": result}
+
+                elif action == "status":
+                    return {"status": "ok", "queue_size": self.queue_size}
+
+                return {"status": "error", "message": f"Unknown action: {action}"}
+        """
+        return None
+
+    async def on_peer_notify(self, msg) -> None:
+        """
+        Handle incoming peer notification.
+
+        Override to process fire-and-forget messages from other agents.
+        No response is expected or sent.
+
+        Args:
+            msg: IncomingMessage with:
+                - msg.sender: Sender agent ID or role
+                - msg.data: Notification payload (dict)
+
+        Example:
+            async def on_peer_notify(self, msg):
+                event = msg.data.get("event")
+
+                if event == "task_complete":
+                    await self.update_dashboard(msg.data)
+                    self._logger.info(f"Task completed by {msg.sender}")
+
+                elif event == "peer_joined":
+                    self._logger.info(f"New peer in mesh: {msg.data.get('role')}")
+        """
+        self._logger.debug(
+            f"[{self.role}] Received notify from {msg.sender}: "
+            f"{list(msg.data.keys()) if isinstance(msg.data, dict) else 'data'}"
         )
 
+    async def on_error(self, error: Exception, msg=None) -> None:
+        """
+        Handle errors during message processing.
+
+        Override to customize error handling (logging, alerting, metrics, etc.)
+        Default implementation logs the error and continues processing.
+
+        Args:
+            error: The exception that occurred
+            msg: The message being processed when error occurred (may be None)
+
+        Example:
+            async def on_error(self, error, msg):
+                # Log with context
+                self._logger.error(
+                    f"Error processing message: {error}",
+                    extra={"sender": msg.sender if msg else None}
+                )
+
+                # Send to error tracking service
+                await self.error_tracker.capture(error, context={"msg": msg})
+
+                # Optionally notify the sender of failure
+                if msg and msg.correlation_id:
+                    await self.peers.respond(msg, {
+                        "status": "error",
+                        "error": str(error)
+                    })
+        """
+        if msg:
+            self._logger.error(
+                f"[{self.role}] Error processing message from {msg.sender}: {error}"
+            )
+        else:
+            self._logger.error(f"[{self.role}] Error in listener loop: {error}")
+
+    # ─────────────────────────────────────────────────────────────────
+    # Workflow Compatibility
+    # ─────────────────────────────────────────────────────────────────
+
     async def execute_task(self, task: Dict[str, Any]) -> Dict[str, Any]:
         """
-        User implements this with custom execution logic.
+        Execute a task (for workflow/distributed modes).
 
-        DAY 1: Raises NotImplementedError (user must override)
-        DAY 5+: Full examples provided
+        Default: Delegates to on_peer_request via synthetic message.
+        Override for custom workflow logic.
 
         Args:
-            task: Task specification
+            task: Task specification dict
 
         Returns:
-            Result dictionary with at least:
-            - status: "success" or "failure"
-            - output: Task result
-            - error (optional): Error message if failed
-            - tokens_used (optional): For cost tracking
-            - cost_usd (optional): For cost tracking
+            Result dict with status and output
 
         Raises:
-            NotImplementedError: User must override this method
-
-        Example:
-            async def execute_task(self, task):
-                result = await self.my_framework.run(task)
-                return {
-                    "status": "success",
-                    "output": result,
-                    "tokens_used": 1000,  # Optional
-                    "cost_usd": 0.002     # Optional
-                }
+            NotImplementedError: If on_peer_request returns None and
+                                 execute_task is not overridden
         """
+        from jarviscore.p2p.messages import IncomingMessage, MessageType
+
+        # Create a synthetic message to pass to the handler
+        synthetic_msg = IncomingMessage(
+            sender="workflow",
+            sender_node="local",
+            type=MessageType.REQUEST,
+            data=task,
+            correlation_id=None,
+            timestamp=0
+        )
+
+        result = await self.on_peer_request(synthetic_msg)
+
+        if result is not None:
+            return {"status": "success", "output": result}
+
         raise NotImplementedError(
-            f"{self.__class__.__name__} must implement execute_task()\n\n"
+            f"{self.__class__.__name__} must implement on_peer_request() or execute_task()\n\n"
             f"Example:\n"
-            f"    async def execute_task(self, task):\n"
-            f"        result = await self.my_framework.run(task['task'])\n"
-            f"        return {{'status': 'success', 'output': result}}\n"
+            f"    async def on_peer_request(self, msg):\n"
+            f"        result = await self.process(msg.data)\n"
+            f"        return {{'status': 'success', 'result': result}}\n"
         )