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

examples/listeneragent_cognitive_discovery_example.py

@@ -0,0 +1,343 @@
+"""
+ListenerAgent + Cognitive Discovery Example
+
+Demonstrates two v0.3.0 features:
+
+1. ListenerAgent - Handler-based P2P agents (no run() loop needed)
+   - on_peer_request() handles incoming requests
+   - on_peer_notify() handles broadcast notifications
+
+2. Cognitive Discovery - Dynamic peer awareness for LLMs
+   - get_cognitive_context() generates LLM-ready peer descriptions
+   - No hardcoded agent names in prompts
+   - LLM autonomously decides when to delegate
+
+Usage:
+    python examples/listeneragent_cognitive_discovery_example.py
+
+Prerequisites:
+    - .env file with CLAUDE_API_KEY (or other LLM provider)
+"""
+import asyncio
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from jarviscore import Mesh
+from jarviscore.profiles import ListenerAgent
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SPECIALIST AGENT - Responds to requests from other agents
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class AnalystAgent(ListenerAgent):
+    """
+    Specialist agent that handles analysis requests.
+
+    Uses ListenerAgent profile - just implement handlers, no run() loop needed.
+    """
+    role = "analyst"
+    capabilities = ["data_analysis", "statistics", "insights"]
+    description = "Analyzes data and provides statistical insights"
+
+    async def on_peer_request(self, msg):
+        """Handle incoming analysis requests."""
+        query = msg.data.get("question", msg.data.get("query", ""))
+        print(f"\n[Analyst] Received request: {query[:50]}...")
+
+        # Simulate analysis (in real usage, this would use an LLM)
+        result = {
+            "analysis": f"Analysis of '{query}': The data shows positive trends.",
+            "confidence": 0.85,
+            "insights": ["Trend is upward", "Growth rate: 15%", "Recommendation: Continue"]
+        }
+
+        print(f"[Analyst] Sending response with {len(result['insights'])} insights")
+        return result
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# COORDINATOR AGENT - Uses LLM with cognitive discovery
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class CoordinatorAgent(ListenerAgent):
+    """
+    Coordinator agent that uses LLM with dynamic peer discovery.
+
+    Key pattern:
+    1. Uses get_cognitive_context() to learn about available peers
+    2. Injects peer context into LLM system prompt
+    3. LLM decides when to delegate to specialists
+    """
+    role = "coordinator"
+    capabilities = ["coordination", "delegation", "chat"]
+    description = "Coordinates tasks and delegates to specialists"
+
+    async def setup(self):
+        await super().setup()
+        self.llm = self._create_llm_client()
+
+    def _create_llm_client(self):
+        """Create LLM client with fallback to mock."""
+        try:
+            from anthropic import Anthropic
+            from jarviscore.config import settings
+            import os
+
+            api_key = settings.claude_api_key or os.environ.get("CLAUDE_API_KEY")
+            if not api_key:
+                raise RuntimeError("No API key")
+
+            # Check for custom endpoint (e.g., Azure-hosted Claude)
+            endpoint = settings.claude_endpoint or os.environ.get("CLAUDE_ENDPOINT")
+            model = settings.claude_model or os.environ.get("CLAUDE_MODEL") or "claude-sonnet-4-20250514"
+
+            if endpoint:
+                client = Anthropic(api_key=api_key, base_url=endpoint)
+            else:
+                client = Anthropic(api_key=api_key)
+
+            # Test the API key with a minimal request
+            try:
+                client.messages.create(
+                    model=model,
+                    max_tokens=10,
+                    messages=[{"role": "user", "content": "Hi"}]
+                )
+            except Exception as e:
+                raise RuntimeError(f"API key validation failed: {e}")
+
+            print(f"[Coordinator] LLM initialized: {model}")
+            return {"client": client, "model": model, "available": True}
+        except Exception as e:
+            print(f"[Coordinator] LLM not available ({e}), using mock responses")
+            return {"available": False}
+
+    def _build_dynamic_prompt(self, base_prompt: str) -> str:
+        """
+        Build system prompt with dynamic peer awareness.
+
+        THIS IS THE KEY PATTERN - the LLM learns about peers dynamically!
+        """
+        if not self.peers:
+            return base_prompt
+
+        # Use get_cognitive_context() for dynamic peer discovery
+        peer_context = self.peers.get_cognitive_context(
+            format="markdown",
+            include_capabilities=True,
+            include_description=True,
+            tool_name="ask_peer"
+        )
+
+        return f"{base_prompt}\n\n{peer_context}"
+
+    async def process_query(self, user_query: str) -> str:
+        """
+        Process a user query using LLM with peer awareness.
+
+        The LLM sees available peers and can decide to delegate.
+        """
+        base_prompt = """You are a coordinator assistant that delegates tasks to specialists.
+
+IMPORTANT: You MUST use the ask_peer tool to delegate to specialists. You cannot perform analysis yourself.
+
+When a user asks for data analysis, statistics, or insights:
+1. Use the ask_peer tool with role="analyst"
+2. Pass their question to the analyst
+3. Report the analyst's findings
+
+Never try to do analysis yourself - always delegate to the analyst."""
+
+        # Build prompt with dynamic peer discovery
+        system_prompt = self._build_dynamic_prompt(base_prompt)
+
+        print(f"\n[Coordinator] System prompt includes peer context:")
+        print("-" * 40)
+        # Show just the peer context part
+        if "AVAILABLE MESH PEERS" in system_prompt:
+            peer_section = system_prompt.split("AVAILABLE MESH PEERS")[1][:200]
+            print(f"...AVAILABLE MESH PEERS{peer_section}...")
+        print("-" * 40)
+
+        # Check if LLM is available
+        if not self.llm.get("available"):
+            # Mock: simulate LLM deciding to delegate
+            if any(word in user_query.lower() for word in ["analyze", "analysis", "statistics", "data"]):
+                print("[Coordinator] Mock LLM decides to delegate to analyst")
+                response = await self.peers.request(
+                    "analyst",
+                    {"question": user_query},
+                    timeout=30
+                )
+                return f"Based on the analyst's findings: {response.get('analysis', 'No response')}"
+            return f"I can help with: {user_query}"
+
+        # Real LLM call with tools
+        tools = self._get_tools()
+        messages = [{"role": "user", "content": user_query}]
+
+        print(f"[Coordinator] Calling LLM with {len(tools)} tools: {[t['name'] for t in tools]}")
+
+        response = self.llm["client"].messages.create(
+            model=self.llm["model"],
+            max_tokens=1024,
+            system=system_prompt,
+            messages=messages,
+            tools=tools
+        )
+
+        print(f"[Coordinator] LLM stop_reason: {response.stop_reason}")
+        print(f"[Coordinator] Response blocks: {[b.type for b in response.content]}")
+
+        # Handle tool use - check for tool_use FIRST (prioritize over text)
+        tool_use_block = None
+        text_content = None
+
+        for block in response.content:
+            if block.type == "tool_use" and block.name == "ask_peer":
+                tool_use_block = block
+            elif hasattr(block, 'text'):
+                text_content = block.text
+
+        # If there's a tool use, execute it
+        if tool_use_block:
+            print(f"[Coordinator] LLM decided to use ask_peer tool")
+            peer_response = await self._execute_peer_tool(tool_use_block.input)
+
+            # Continue conversation with tool result
+            messages.append({"role": "assistant", "content": response.content})
+            messages.append({
+                "role": "user",
+                "content": [{
+                    "type": "tool_result",
+                    "tool_use_id": tool_use_block.id,
+                    "content": str(peer_response)
+                }]
+            })
+
+            final_response = self.llm["client"].messages.create(
+                model=self.llm["model"],
+                max_tokens=1024,
+                system=system_prompt,
+                messages=messages
+            )
+
+            for final_block in final_response.content:
+                if hasattr(final_block, 'text'):
+                    return final_block.text
+
+        # No tool use, return text content
+        if text_content:
+            return text_content
+
+        return "I processed your request."
+
+    def _get_tools(self) -> list:
+        """Get tools for LLM, including peer tools."""
+        return [{
+            "name": "ask_peer",
+            "description": "Ask a specialist agent for help. Use this to delegate tasks to experts.",
+            "input_schema": {
+                "type": "object",
+                "properties": {
+                    "role": {
+                        "type": "string",
+                        "description": "Role of the agent to ask (e.g., 'analyst')"
+                    },
+                    "question": {
+                        "type": "string",
+                        "description": "The question or task for the specialist"
+                    }
+                },
+                "required": ["role", "question"]
+            }
+        }]
+
+    async def _execute_peer_tool(self, args: dict) -> dict:
+        """Execute ask_peer tool."""
+        role = args.get("role", "")
+        question = args.get("question", "")
+
+        print(f"[Coordinator] Asking {role}: {question[:50]}...")
+
+        response = await self.peers.request(
+            role,
+            {"question": question},
+            timeout=30
+        )
+
+        return response
+
+    async def on_peer_request(self, msg):
+        """Handle incoming peer requests (for workflow compatibility)."""
+        query = msg.data.get("query", msg.data.get("question", ""))
+        result = await self.process_query(query)
+        return {"response": result}
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# MAIN - Demonstrate cognitive discovery
+# ═══════════════════════════════════════════════════════════════════════════════
+
+async def main():
+    print("=" * 60)
+    print("LLM Cognitive Discovery Example")
+    print("=" * 60)
+
+    # Create mesh with both agents
+    mesh = Mesh(mode="p2p", config={"bind_port": 7960})
+
+    analyst = mesh.add(AnalystAgent())
+    coordinator = mesh.add(CoordinatorAgent())
+
+    await mesh.start()
+
+    print(f"\n[Setup] Mesh started with agents:")
+    print(f"  - {analyst.role}: {analyst.capabilities}")
+    print(f"  - {coordinator.role}: {coordinator.capabilities}")
+
+    # Start analyst listener in background
+    analyst_task = asyncio.create_task(analyst.run())
+
+    # Give time for setup
+    await asyncio.sleep(0.5)
+
+    # Show cognitive context that LLM will see
+    print("\n" + "=" * 60)
+    print("COGNITIVE CONTEXT (what LLM sees about peers)")
+    print("=" * 60)
+    context = coordinator.peers.get_cognitive_context()
+    print(context)
+
+    # Test queries - one that should trigger delegation, one that shouldn't
+    test_queries = [
+        "Please analyze the Q4 sales data and give me insights",
+        "What time is it?",
+    ]
+
+    print("\n" + "=" * 60)
+    print("PROCESSING QUERIES")
+    print("=" * 60)
+
+    for query in test_queries:
+        print(f"\n>>> User: {query}")
+        response = await coordinator.process_query(query)
+        print(f"<<< Coordinator: {response}")
+
+    # Cleanup
+    analyst.request_shutdown()
+    analyst_task.cancel()
+    try:
+        await analyst_task
+    except asyncio.CancelledError:
+        pass
+
+    await mesh.stop()
+    print("\n[Done] Example completed!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

jarviscore/__init__.py

@@ -4,15 +4,16 @@ JarvisCore - P2P Distributed Agent Framework
 A production-grade framework for building autonomous agent systems with:
 - P2P coordination via SWIM protocol
 - Workflow orchestration with dependencies
-- Two agent profiles: AutoAgent (LLM-powered) and CustomAgent (your code)
+- Three agent profiles: AutoAgent, CustomAgent, and ListenerAgent
 
 Profiles:
-    AutoAgent  - LLM generates and executes code from prompts (autonomous mode)
-    CustomAgent - You provide execute_task() or run() (p2p/distributed modes)
+    AutoAgent     - LLM generates and executes code from prompts (autonomous mode)
+    CustomAgent   - You provide execute_task() or run() (p2p/distributed modes)
+    ListenerAgent - API-first agents with background P2P (just implement handlers)
 
 Modes:
     autonomous  - Workflow engine only (AutoAgent)
-    p2p         - P2P coordinator only (CustomAgent with run() loops)
+    p2p         - P2P coordinator only (CustomAgent/ListenerAgent with run() loops)
     distributed - Both workflow + P2P (CustomAgent with execute_task())
 
 Quick Start (AutoAgent - autonomous mode):
@@ -29,6 +30,20 @@ Quick Start (AutoAgent - autonomous mode):
     await mesh.start()
     results = await mesh.workflow("calc", [{"agent": "calculator", "task": "Calculate 10!"}])
 
+Quick Start (ListenerAgent + FastAPI):
+    from fastapi import FastAPI
+    from jarviscore.profiles import ListenerAgent
+    from jarviscore.integrations.fastapi import JarvisLifespan
+
+    class MyAgent(ListenerAgent):
+        role = "processor"
+        capabilities = ["processing"]
+
+        async def on_peer_request(self, msg):
+            return {"result": msg.data.get("task", "").upper()}
+
+    app = FastAPI(lifespan=JarvisLifespan(MyAgent(), mode="p2p"))
+
 Quick Start (CustomAgent - distributed mode):
     from jarviscore import Mesh
     from jarviscore.profiles import CustomAgent
@@ -46,7 +61,7 @@ Quick Start (CustomAgent - distributed mode):
     results = await mesh.workflow("demo", [{"agent": "processor", "task": "hello"}])
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 __author__ = "JarvisCore Contributors"
 __license__ = "MIT"
 
@@ -58,6 +73,7 @@ from jarviscore.core.mesh import Mesh, MeshMode
 # Execution profiles
 from jarviscore.profiles.autoagent import AutoAgent
 from jarviscore.profiles.customagent import CustomAgent
+from jarviscore.profiles.listeneragent import ListenerAgent
 
 # Custom Profile: Decorator, Wrapper, and Context
 from jarviscore.adapter import jarvis_agent, wrap
@@ -83,6 +99,7 @@ __all__ = [
     # Profiles
     "AutoAgent",
     "CustomAgent",
+    "ListenerAgent",
 
     # Custom Profile (decorator and wrapper)
     "jarvis_agent",

jarviscore/cli/smoketest.py

@@ -311,10 +311,14 @@ class SmokeTest:
 
         print("\n✓ All smoke tests passed!")
         print("\nJarvisCore is working correctly. Next steps:")
-        print("  1. Try examples - AutoAgent Profile: python examples/calculator_agent_example.py")
-        print("  2. Try examples - CustomAgent Profile: python examples/customagent_p2p_example.py")
-        print("  3. Read user guide: docs/USER_GUIDE.md")
-        print("  3. Build your first agent: docs/GETTING_STARTED.md")
+        print("  1. AutoAgent example:     python examples/calculator_agent_example.py")
+        print("  2. CustomAgent P2P:       python examples/customagent_p2p_example.py")
+        print("  3. ListenerAgent (v0.3):  python examples/listeneragent_cognitive_discovery_example.py")
+        print("  4. FastAPI (v0.3):        python examples/fastapi_integration_example.py")
+        print("  5. Cloud deploy (v0.3):   python examples/cloud_deployment_example.py")
+        print("\nDocumentation:")
+        print("  - Getting Started: docs/GETTING_STARTED.md")
+        print("  - User Guide:      docs/USER_GUIDE.md")
         print()
         return True
 

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