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

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,12 @@ 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()` |
+| **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.
 
@@ -223,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
@@ -534,6 +537,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 CustomAgent
+from jarviscore.integrations.fastapi import JarvisLifespan
+
+class ProcessorAgent(CustomAgent):
+    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 CustomAgent
+
+class MyAgent(CustomAgent):
+    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 +904,6 @@ mesh = Mesh(config=config)
 
 ## Version
 
-User Guide for JarvisCore v0.2.1
+User Guide for JarvisCore v0.3.1
 
-Last Updated: 2026-01-23
+Last Updated: 2026-02-02

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 CustomAgent
+
+        class MyAgent(CustomAgent):
+            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 CustomAgent
+
+        class MyAgent(CustomAgent):
+            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)