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

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

{jarviscore_framework-0.2.1.dist-info → jarviscore_framework-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jarviscore-framework
-Version: 0.2.1
+Version: 0.3.1
 Summary: Build autonomous AI agents in 3 lines of code. Production-ready orchestration with P2P mesh networking.
 Author-email: Ruth Mutua <mutuandinda82@gmail.com>, Muyukani Kizito <muyukani@prescottdata.io>
 Maintainer-email: Prescott Data <info@prescottdata.io>
@@ -26,6 +26,8 @@ Requires-Dist: pyzmq
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn>=0.29.0
 Requires-Dist: anthropic>=0.18.0
 Requires-Dist: openai>=1.0.0
 Requires-Dist: google-genai>=1.0.0
@@ -47,10 +49,13 @@ Dynamic: license-file
 
 ## Features
 
-- ✅ **AutoAgent** - LLM generates and executes code from natural language
-- ✅ **CustomAgent** - Bring your own logic (LangChain, CrewAI, etc.)
-- ✅ **P2P Mesh** - Agent discovery and communication via SWIM protocol
-- ✅ **Workflow Orchestration** - Dependencies, context passing, multi-step pipelines
+- **AutoAgent** - LLM generates and executes code from natural language
+- **CustomAgent** - Bring your own logic with P2P message handlers
+- **P2P Mesh** - Agent discovery and communication via SWIM protocol
+- **Workflow Orchestration** - Dependencies, context passing, multi-step pipelines
+- **FastAPI Integration** - 3-line setup with JarvisLifespan
+- **Cognitive Discovery** - LLM-ready peer descriptions for autonomous delegation
+- **Cloud Deployment** - Self-registering agents for Docker/K8s
 
 ## Installation
 
@@ -94,7 +99,26 @@ results = await mesh.workflow("calc", [
 print(results[0]["output"])  # 3628800
 ```
 
-### CustomAgent (Your Code)
+### CustomAgent + FastAPI (Recommended)
+
+```python
+from fastapi import FastAPI
+from jarviscore.profiles import CustomAgent
+from jarviscore.integrations.fastapi import JarvisLifespan
+
+class ProcessorAgent(CustomAgent):
+    role = "processor"
+    capabilities = ["processing"]
+
+    async def on_peer_request(self, msg):
+        # Handle requests from other agents
+        return {"result": msg.data.get("task", "").upper()}
+
+# 3 lines to integrate with FastAPI
+app = FastAPI(lifespan=JarvisLifespan(ProcessorAgent(), mode="p2p"))
+```
+
+### CustomAgent (Workflow Mode)
 
 ```python
 from jarviscore import Mesh
@@ -118,26 +142,50 @@ results = await mesh.workflow("demo", [
 print(results[0]["output"])  # [2, 4, 6]
 ```
 
+## Profiles
+
+| Profile | You Write | JarvisCore Handles |
+|---------|-----------|-------------------|
+| **AutoAgent** | System prompt | LLM code generation, sandboxed execution |
+| **CustomAgent** | `on_peer_request()` and/or `execute_task()` | Mesh, discovery, routing, lifecycle |
+
 ## Execution Modes
 
-| Mode | Profile | Use Case |
-|------|---------|----------|
-| `autonomous` | AutoAgent | Single machine, LLM code generation |
-| `p2p` | CustomAgent | Agent-to-agent communication, swarms |
-| `distributed` | CustomAgent | Multi-node workflows + P2P |
+| Mode | Use Case |
+|------|----------|
+| `autonomous` | Single machine, LLM code generation (AutoAgent) |
+| `p2p` | Agent-to-agent communication, swarms (CustomAgent) |
+| `distributed` | Multi-node workflows + P2P (CustomAgent) |
+
+## Framework Integration
+
+JarvisCore is **async-first**. Best experience with async frameworks.
+
+| Framework | Integration |
+|-----------|-------------|
+| **FastAPI** | `JarvisLifespan` (3 lines) |
+| **aiohttp, Quart, Tornado** | Manual lifecycle (see docs) |
+| **Flask, Django** | Background thread pattern (see docs) |
 
 ## Documentation
 
-- [User Guide](jarviscore/docs/USER_GUIDE.md) - Complete documentation
-- [Getting Started](jarviscore/docs/GETTING_STARTED.md) - 5-minute quickstart
-- [AutoAgent Guide](jarviscore/docs/AUTOAGENT_GUIDE.md) - LLM-powered agents
-- [CustomAgent Guide](jarviscore/docs/CUSTOMAGENT_GUIDE.md) - Bring your own code
-- [API Reference](jarviscore/docs/API_REFERENCE.md) - Detailed API docs
-- [Configuration](jarviscore/docs/CONFIGURATION.md) - Settings reference
+Documentation is included with the package:
+
+```bash
+python -c "import jarviscore; print(jarviscore.__path__[0] + '/docs')"
+```
+
+**Available guides:**
+- `GETTING_STARTED.md` - 5-minute quickstart
+- `CUSTOMAGENT_GUIDE.md` - CustomAgent patterns and framework integration
+- `AUTOAGENT_GUIDE.md` - LLM-powered agents
+- `USER_GUIDE.md` - Complete documentation
+- `API_REFERENCE.md` - Detailed API docs
+- `CONFIGURATION.md` - Settings reference
 
 ## Version
 
-**0.2.1**
+**0.4.0**
 
 ## License