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

jarviscore/docs/GETTING_STARTED.md

@@ -12,6 +12,7 @@ Build your first AI agent in 5 minutes!
 |---------|----------|--------------|
 | **AutoAgent** | Rapid prototyping, LLM generates code from prompts | Yes |
 | **CustomAgent** | Existing code, full control (LangChain, CrewAI, etc.) | Optional |
+| **ListenerAgent** | API-first (FastAPI), just implement handlers | Optional |
 
 ### Execution Modes (How agents are orchestrated)
 
@@ -19,9 +20,12 @@ Build your first AI agent in 5 minutes!
 |------|----------|------------|
 | **Autonomous** | Single machine, simple pipelines | ✅ This guide |
 | **P2P** | Direct agent communication, swarms | [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) |
-| **Distributed** | Multi-node production systems | [AutoAgent Guide](AUTOAGENT_GUIDE.md) |
+| **Distributed** | Multi-node production systems | [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) |
 
-**Recommendation:** Start with **AutoAgent + Autonomous mode** below, then explore other modes.
+**Recommendation:**
+- **New to agents?** Start with **AutoAgent + Autonomous mode** below
+- **Have existing code?** Jump to **CustomAgent** or **ListenerAgent** sections
+- **Building APIs?** See **ListenerAgent + FastAPI** below
 
 ---
 
@@ -249,6 +253,90 @@ asyncio.run(main())
 
 ---
 
+## Step 6: ListenerAgent + FastAPI (API-First Path)
+
+Building an API where agents run in the background? **ListenerAgent** eliminates the boilerplate.
+
+### The Problem
+
+With CustomAgent, you write a `run()` loop to handle peer messages:
+
+```python
+# CustomAgent - you write the loop
+class MyAgent(CustomAgent):
+    async def run(self):
+        while not self.shutdown_requested:
+            msg = await self.peers.receive(timeout=1.0)
+            if msg is None:
+                continue
+            if msg.type == MessageType.REQUEST:
+                result = await self.process(msg.data)
+                await self.peers.respond(msg, result)
+            # ... error handling, logging, etc.
+```
+
+### The Solution
+
+With ListenerAgent, just implement handlers:
+
+```python
+from jarviscore.profiles import ListenerAgent
+
+class MyAgent(ListenerAgent):
+    role = "processor"
+    capabilities = ["processing"]
+
+    async def on_peer_request(self, msg):
+        """Handle requests - return value is sent as response."""
+        return {"result": await self.process(msg.data)}
+
+    async def on_peer_notify(self, msg):
+        """Handle fire-and-forget notifications."""
+        await self.log_event(msg.data)
+```
+
+### FastAPI Integration (3 Lines)
+
+```python
+from fastapi import FastAPI, Request
+from jarviscore.profiles import ListenerAgent
+from jarviscore.integrations.fastapi import JarvisLifespan
+
+class ProcessorAgent(ListenerAgent):
+    role = "processor"
+    capabilities = ["data_processing"]
+
+    async def on_peer_request(self, msg):
+        return {"processed": msg.data.get("task", "").upper()}
+
+# Create agent and integrate with FastAPI
+agent = ProcessorAgent()
+app = FastAPI(lifespan=JarvisLifespan(agent, mode="p2p", bind_port=7950))
+
+@app.post("/process")
+async def process(data: dict, request: Request):
+    # Access your agent from the request
+    agent = request.app.state.jarvis_agents["processor"]
+    return await agent.process(data)
+
+@app.get("/peers")
+async def list_peers(request: Request):
+    agent = request.app.state.jarvis_agents["processor"]
+    return {"peers": agent.peers.list_peers()}
+```
+
+Run with: `uvicorn myapp:app --host 0.0.0.0 --port 8000`
+
+**What you get:**
+- HTTP endpoints (FastAPI routes) as primary interface
+- P2P mesh participation in background
+- Auto message dispatch to handlers
+- Graceful startup/shutdown handled by JarvisLifespan
+
+**For more:** See [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) for ListenerAgent details.
+
+---
+
 ## What Just Happened?
 
 Behind the scenes, JarvisCore:
@@ -394,7 +482,23 @@ class MyAgent(CustomAgent):
             ...
 ```
 
-### 3. Mesh
+### 3. ListenerAgent Profile
+
+The `ListenerAgent` profile is for API-first agents - just implement handlers:
+
+```python
+class MyAgent(ListenerAgent):
+    role = "unique_name"
+    capabilities = ["skill1", "skill2"]
+
+    async def on_peer_request(self, msg):    # Handle requests (return = response)
+        return {"result": ...}
+
+    async def on_peer_notify(self, msg):     # Handle notifications (fire-and-forget)
+        await self.log(msg.data)
+```
+
+### 4. Mesh
 
 The `Mesh` is the orchestrator that manages agents and workflows:
 
@@ -408,10 +512,10 @@ await mesh.stop()               # Cleanup
 
 **Modes:**
 - `autonomous`: Workflow engine only (AutoAgent)
-- `p2p`: P2P coordinator for agent-to-agent communication (CustomAgent)
-- `distributed`: Both workflow engine AND P2P (CustomAgent)
+- `p2p`: P2P coordinator for agent-to-agent communication (CustomAgent, ListenerAgent)
+- `distributed`: Both workflow engine AND P2P (CustomAgent, ListenerAgent)
 
-### 4. Workflow
+### 5. Workflow
 
 A workflow is a list of tasks to execute:
 
@@ -425,7 +529,7 @@ results = await mesh.workflow("workflow-id", [
 ])
 ```
 
-### 5. Results
+### 6. Results
 
 Each task returns a result dict:
 

jarviscore/docs/USER_GUIDE.md

@@ -16,9 +16,12 @@ Practical guide to building agent systems with JarvisCore.
 8. [Remote Sandbox](#remote-sandbox)
 9. [Result Storage](#result-storage)
 10. [Code Registry](#code-registry)
-11. [Best Practices](#best-practices)
-12. [Common Patterns](#common-patterns)
-13. [Troubleshooting](#troubleshooting)
+11. [FastAPI Integration (v0.3.0)](#fastapi-integration-v030)
+12. [Cloud Deployment (v0.3.0)](#cloud-deployment-v030)
+13. [Cognitive Discovery (v0.3.0)](#cognitive-discovery-v030)
+14. [Best Practices](#best-practices)
+15. [Common Patterns](#common-patterns)
+16. [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -138,12 +141,13 @@ mesh = Mesh(mode="distributed", config={'bind_port': 7950})
 
 ### Agents
 
-**Agents** are workers that execute tasks. JarvisCore offers two profiles:
+**Agents** are workers that execute tasks. JarvisCore offers three profiles:
 
 | 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 |
 
 See [AutoAgent Guide](AUTOAGENT_GUIDE.md) and [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) for details.
 
@@ -534,6 +538,148 @@ print(f"Registered: {func['registered_at']}")
 
 ---
 
+## FastAPI Integration (v0.3.0)
+
+Deploy agents as FastAPI services with minimal boilerplate:
+
+### JarvisLifespan
+
+```python
+from fastapi import FastAPI, Request
+from jarviscore.profiles import ListenerAgent
+from jarviscore.integrations.fastapi import JarvisLifespan
+
+class ProcessorAgent(ListenerAgent):
+    role = "processor"
+    capabilities = ["processing"]
+
+    async def on_peer_request(self, msg):
+        return {"result": msg.data.get("task", "").upper()}
+
+# 3 lines to integrate
+agent = ProcessorAgent()
+app = FastAPI(lifespan=JarvisLifespan(agent, mode="p2p", bind_port=7950))
+
+@app.get("/peers")
+async def list_peers(request: Request):
+    agent = request.app.state.jarvis_agents["processor"]
+    return {"peers": agent.peers.list_peers()}
+```
+
+**What JarvisLifespan handles:**
+- Mesh startup/shutdown
+- Background task management for agent run() loops
+- Graceful shutdown with timeouts
+- State injection into FastAPI app
+
+---
+
+## Cloud Deployment (v0.3.0)
+
+Deploy agents to containers without a central orchestrator:
+
+### Self-Registration Pattern
+
+```python
+# In your container entrypoint
+import asyncio
+from jarviscore.profiles import ListenerAgent
+
+class MyAgent(ListenerAgent):
+    role = "worker"
+    capabilities = ["processing"]
+
+    async def on_peer_request(self, msg):
+        return {"processed": msg.data}
+
+async def main():
+    agent = MyAgent()
+
+    # Join existing mesh (uses JARVISCORE_SEED_NODES env var)
+    await agent.join_mesh()
+
+    print(f"Joined as {agent.role}, discovered: {agent.peers.list_peers()}")
+
+    # Run until shutdown, auto-leaves mesh on exit
+    await agent.run_standalone()
+
+asyncio.run(main())
+```
+
+### Docker/Kubernetes
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY . .
+RUN pip install jarviscore-framework
+
+# Point to existing mesh
+ENV JARVISCORE_SEED_NODES=mesh-service:7946
+
+CMD ["python", "-m", "myapp.agent"]
+```
+
+**Environment Variables:**
+- `JARVISCORE_SEED_NODES` - Comma-separated list of seed nodes
+- `JARVISCORE_MESH_ENDPOINT` - Single endpoint to join
+
+---
+
+## Cognitive Discovery (v0.3.0)
+
+Let LLMs dynamically discover mesh peers instead of hardcoding agent names:
+
+### The Problem
+
+```python
+# Before: Hardcoded peer names in prompts
+system_prompt = """
+You can delegate to:
+- analyst for data analysis
+- scout for research
+"""
+# Breaks when mesh composition changes!
+```
+
+### The Solution
+
+```python
+# After: Dynamic discovery
+system_prompt = self.peers.build_system_prompt(
+    "You are a coordinator agent."
+)
+# Automatically includes all available peers!
+```
+
+### get_cognitive_context()
+
+```python
+# Get prompt-ready peer descriptions
+context = self.peers.get_cognitive_context(format="markdown")
+```
+
+**Output:**
+```markdown
+## AVAILABLE MESH PEERS
+
+You are part of a multi-agent mesh. The following peers are available:
+
+- **analyst** (`agent-analyst-abc123`)
+  - Capabilities: analysis, charting, reporting
+  - Description: Analyzes data and generates insights
+
+- **scout** (`agent-scout-def456`)
+  - Capabilities: research, reconnaissance
+  - Description: Gathers information
+
+Use the `ask_peer` tool to delegate tasks to these specialists.
+```
+
+**Formats:** `markdown`, `json`, `text`
+
+---
+
 ## Best Practices
 
 ### 1. Always Use Context Managers
@@ -759,6 +905,6 @@ mesh = Mesh(config=config)
 
 ## Version
 
-User Guide for JarvisCore v0.2.1
+User Guide for JarvisCore v0.3.0
 
-Last Updated: 2026-01-23
+Last Updated: 2026-01-29

jarviscore/integrations/__init__.py

@@ -0,0 +1,16 @@
+"""
+Framework integrations for JarvisCore.
+
+Provides first-class support for popular web frameworks,
+reducing boilerplate for production deployments.
+
+Available integrations:
+- FastAPI: JarvisLifespan, create_jarvis_app
+"""
+
+try:
+    from .fastapi import JarvisLifespan, create_jarvis_app
+    __all__ = ['JarvisLifespan', 'create_jarvis_app']
+except ImportError:
+    # FastAPI not installed - integrations not available
+    __all__ = []

jarviscore/integrations/fastapi.py

@@ -0,0 +1,247 @@
+"""
+FastAPI integration for JarvisCore.
+
+Reduces boilerplate from ~100 lines to 3 lines for integrating
+JarvisCore agents with FastAPI applications.
+
+Example:
+    from fastapi import FastAPI
+    from jarviscore.integrations.fastapi import JarvisLifespan
+
+    agent = MyAgent()
+    app = FastAPI(lifespan=JarvisLifespan(agent, mode="p2p", bind_port=7950))
+
+    @app.get("/peers")
+    async def get_peers(request: Request):
+        agent = request.app.state.jarvis_agents.get("my_role")
+        return {"peers": agent.peers.list_peers()}
+"""
+from contextlib import asynccontextmanager
+from typing import Union, List, TYPE_CHECKING
+import asyncio
+import logging
+
+if TYPE_CHECKING:
+    from jarviscore.core.agent import Agent
+
+logger = logging.getLogger(__name__)
+
+
+class JarvisLifespan:
+    """
+    FastAPI lifespan manager for JarvisCore agents.
+
+    Handles the complete lifecycle of JarvisCore mesh integration:
+    - Mesh initialization on startup
+    - Background task management for agent run() loops
+    - Graceful shutdown with proper cleanup
+    - State injection into FastAPI app for handler access
+
+    Args:
+        agents: Single agent instance or list of agents to run
+        mode: Mesh mode - "p2p", "distributed", or "autonomous"
+        **mesh_config: Additional Mesh configuration options:
+            - bind_host: P2P bind address (default: "127.0.0.1")
+            - bind_port: P2P bind port (default: 7946)
+            - seed_nodes: Comma-separated seed nodes for joining cluster
+            - node_name: Node identifier for P2P network
+
+    Example - Single Agent:
+        from fastapi import FastAPI, Request
+        from jarviscore.integrations.fastapi import JarvisLifespan
+        from jarviscore.profiles import ListenerAgent
+
+        class MyAgent(ListenerAgent):
+            role = "processor"
+            capabilities = ["processing"]
+
+            async def on_peer_request(self, msg):
+                return {"processed": msg.data}
+
+        agent = MyAgent()
+        app = FastAPI(lifespan=JarvisLifespan(agent, mode="p2p", bind_port=7950))
+
+        @app.get("/health")
+        async def health(request: Request):
+            mesh = request.app.state.jarvis_mesh
+            return {"status": "ok", "mesh_started": mesh._started}
+
+    Example - Multiple Agents:
+        agents = [ProcessorAgent(), AnalyzerAgent()]
+        app = FastAPI(lifespan=JarvisLifespan(agents, mode="p2p"))
+
+    Example - Joining Existing Cluster:
+        app = FastAPI(lifespan=JarvisLifespan(
+            agent,
+            mode="p2p",
+            seed_nodes="192.168.1.10:7946,192.168.1.11:7946"
+        ))
+    """
+
+    def __init__(
+        self,
+        agents: Union['Agent', List['Agent']],
+        mode: str = "p2p",
+        **mesh_config
+    ):
+        """
+        Initialize JarvisLifespan.
+
+        Args:
+            agents: Single agent or list of agents to run
+            mode: Mesh mode ("p2p", "distributed", "autonomous")
+            **mesh_config: Additional Mesh configuration
+        """
+        self.agents = agents if isinstance(agents, list) else [agents]
+        self.mode = mode
+        self.mesh_config = mesh_config
+        self.mesh = None
+        self._background_tasks: List[asyncio.Task] = []
+        self._nodes: List['Agent'] = []
+
+    @asynccontextmanager
+    async def __call__(self, app):
+        """
+        ASGI lifespan context manager.
+
+        Called by FastAPI/Starlette on app startup/shutdown.
+        Manages the complete mesh lifecycle.
+        """
+        from jarviscore import Mesh
+
+        # ─────────────────────────────────────────────────────────────
+        # STARTUP
+        # ─────────────────────────────────────────────────────────────
+        logger.info(f"JarvisLifespan: Starting mesh in {self.mode} mode...")
+
+        # 1. Create mesh with provided configuration
+        self.mesh = Mesh(mode=self.mode, config=self.mesh_config)
+
+        # 2. Register all agents with the mesh
+        self._nodes = []
+        for agent in self.agents:
+            node = self.mesh.add(agent)
+            self._nodes.append(node)
+            logger.debug(f"JarvisLifespan: Registered agent {node.role}")
+
+        # 3. Start mesh (initializes P2P coordinator, injects PeerClients)
+        await self.mesh.start()
+        logger.info(f"JarvisLifespan: Mesh started with {len(self._nodes)} agent(s)")
+
+        # 4. Launch agent run() loops as background tasks
+        # This is crucial - without backgrounding, the HTTP server would hang
+        for node in self._nodes:
+            if hasattr(node, 'run') and asyncio.iscoroutinefunction(node.run):
+                task = asyncio.create_task(
+                    self._run_agent_with_error_handling(node),
+                    name=f"jarvis-agent-{node.agent_id}"
+                )
+                self._background_tasks.append(task)
+                logger.info(f"JarvisLifespan: Started background loop for {node.role}")
+
+        # 5. Inject state into FastAPI app for handler access
+        app.state.jarvis_mesh = self.mesh
+        app.state.jarvis_agents = {node.role: node for node in self._nodes}
+
+        logger.info("JarvisLifespan: Startup complete")
+
+        # ─────────────────────────────────────────────────────────────
+        # APP RUNS HERE
+        # ─────────────────────────────────────────────────────────────
+        try:
+            yield
+        finally:
+            # ─────────────────────────────────────────────────────────────
+            # SHUTDOWN
+            # ─────────────────────────────────────────────────────────────
+            logger.info("JarvisLifespan: Shutting down...")
+
+            # 1. Request shutdown for all agents (signals run() loops to exit)
+            for node in self._nodes:
+                node.request_shutdown()
+
+            # 2. Cancel background tasks gracefully with timeout
+            for task in self._background_tasks:
+                if not task.done():
+                    task.cancel()
+                    try:
+                        await asyncio.wait_for(task, timeout=5.0)
+                    except (asyncio.CancelledError, asyncio.TimeoutError):
+                        pass
+
+            # 3. Stop mesh (cleanup P2P coordinator, call agent teardown)
+            if self.mesh:
+                await self.mesh.stop()
+
+            logger.info("JarvisLifespan: Shutdown complete")
+
+    async def _run_agent_with_error_handling(self, agent: 'Agent'):
+        """
+        Run agent loop with error handling and logging.
+
+        Wraps the agent's run() method to catch and log errors
+        without crashing the entire application.
+        """
+        try:
+            await agent.run()
+        except asyncio.CancelledError:
+            logger.debug(f"Agent {agent.agent_id} loop cancelled")
+            raise
+        except Exception as e:
+            logger.error(f"Agent {agent.agent_id} loop error: {e}", exc_info=True)
+            # Re-raise to allow task to be marked as failed
+            raise
+
+
+def create_jarvis_app(
+    agent: 'Agent',
+    mode: str = "p2p",
+    title: str = "JarvisCore Agent",
+    description: str = "API powered by JarvisCore",
+    version: str = "1.0.0",
+    **mesh_config
+) -> 'FastAPI':
+    """
+    Create a FastAPI app with JarvisCore integration pre-configured.
+
+    Convenience function for simple single-agent deployments.
+    For more control, use JarvisLifespan directly.
+
+    Args:
+        agent: Agent instance to run
+        mode: Mesh mode ("p2p", "distributed", "autonomous")
+        title: FastAPI app title
+        description: FastAPI app description
+        version: API version
+        **mesh_config: Mesh configuration options
+
+    Returns:
+        Configured FastAPI app with JarvisCore integration
+
+    Example:
+        from jarviscore.integrations.fastapi import create_jarvis_app
+        from jarviscore.profiles import ListenerAgent
+
+        class MyAgent(ListenerAgent):
+            role = "processor"
+            capabilities = ["processing"]
+
+            async def on_peer_request(self, msg):
+                return {"result": "processed"}
+
+        app = create_jarvis_app(MyAgent(), mode="p2p", bind_port=7950)
+
+        @app.get("/health")
+        async def health():
+            return {"status": "ok"}
+
+        # Run with: uvicorn myapp:app --host 0.0.0.0 --port 8000
+    """
+    from fastapi import FastAPI
+
+    return FastAPI(
+        title=title,
+        description=description,
+        version=version,
+        lifespan=JarvisLifespan(agent, mode=mode, **mesh_config)
+    )

jarviscore/p2p/broadcaster.py

@@ -143,12 +143,19 @@ class StepOutputBroadcaster:
         """
         try:
             message_id = message_data.get('id', str(uuid.uuid4()))
-            step_result_data = message_data.get('step_result', {})
-            
+
+            # The sender uses 'step_output_data' as the key (json string)
+            step_output_json = message_data.get('step_output_data', '')
+            if step_output_json:
+                step_result_data = json.loads(step_output_json)
+            else:
+                # Fallback for legacy format
+                step_result_data = message_data.get('step_result', {})
+
             # Send acknowledgment if callback provided
             if send_ack_callback:
                 await send_ack_callback(sender_swim_id, message_id, "STEP_OUTPUT_BROADCAST")
-            
+
             # Create StepExecutionResult from received data
             result = StepExecutionResult(**step_result_data)