jarviscore-framework 0.3.0__tar.gz → 0.3.2__tar.gz

{jarviscore_framework-0.3.0/jarviscore_framework.egg-info → jarviscore_framework-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jarviscore-framework
-Version: 0.3.0
+Version: 0.3.2
 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,13 +49,13 @@ Dynamic: license-file
 
 ## Features
 
-- ✅ **AutoAgent** - LLM generates and executes code from natural language
-- ✅ **CustomAgent** - Bring your own logic (LangChain, CrewAI, etc.)
-- ✅ **ListenerAgent** - API-first agents with background P2P (just implement 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
-- ✅ **Cloud Deployment** - Self-registering agents for Docker/K8s
+- **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
 
@@ -97,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
@@ -121,56 +142,50 @@ results = await mesh.workflow("demo", [
 print(results[0]["output"])  # [2, 4, 6]
 ```
 
-### ListenerAgent + FastAPI (API-First)
+## Profiles
 
-```python
-from fastapi import FastAPI
-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):
-        # Handle requests from other agents
-        return {"result": msg.data.get("task", "").upper()}
-
-# That's it - 3 lines to integrate with FastAPI
-app = FastAPI(lifespan=JarvisLifespan(ProcessorAgent(), mode="p2p"))
-```
+| 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, ListenerAgent | Agent-to-agent communication, swarms |
-| `distributed` | CustomAgent, ListenerAgent | 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) |
 
-## What's New in 0.3.0
+## Framework Integration
 
-**Developer Experience Improvements:**
-- **ListenerAgent** - No more writing `run()` loops. Just implement `on_peer_request()` and `on_peer_notify()` handlers.
-- **JarvisLifespan** - FastAPI integration reduced from ~100 lines to 3 lines.
-- **Cognitive Discovery** - `peers.get_cognitive_context()` generates LLM-ready peer descriptions. No more hardcoded agent names in prompts.
+JarvisCore is **async-first**. Best experience with async frameworks.
 
-**Cloud Deployment:**
-- **Self-Registration** - `agent.join_mesh()` lets agents join existing meshes without central orchestrator.
-- **Remote Visibility** - Agents on different nodes are automatically discovered and callable.
+| 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.3.0**
+**0.3.2**
 
 ## License
 

jarviscore_framework-0.3.2/README.md

@@ -0,0 +1,147 @@
+# JarvisCore Framework
+
+**Build autonomous AI agents with P2P mesh networking.**
+
+## Features
+
+- **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
+
+```bash
+pip install jarviscore-framework
+```
+
+## Setup
+
+```bash
+# Initialize project
+python -m jarviscore.cli.scaffold --examples
+cp .env.example .env
+# Add your LLM API key to .env
+
+# Validate
+python -m jarviscore.cli.check --validate-llm
+python -m jarviscore.cli.smoketest
+```
+
+## Quick Start
+
+### AutoAgent (LLM-Powered)
+
+```python
+from jarviscore import Mesh
+from jarviscore.profiles import AutoAgent
+
+class CalculatorAgent(AutoAgent):
+    role = "calculator"
+    capabilities = ["math"]
+    system_prompt = "You are a math expert. Store result in 'result'."
+
+mesh = Mesh(mode="autonomous")
+mesh.add(CalculatorAgent)
+await mesh.start()
+
+results = await mesh.workflow("calc", [
+    {"agent": "calculator", "task": "Calculate factorial of 10"}
+])
+print(results[0]["output"])  # 3628800
+```
+
+### 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
+from jarviscore.profiles import CustomAgent
+
+class ProcessorAgent(CustomAgent):
+    role = "processor"
+    capabilities = ["processing"]
+
+    async def execute_task(self, task):
+        data = task.get("params", {}).get("data", [])
+        return {"status": "success", "output": [x * 2 for x in data]}
+
+mesh = Mesh(mode="distributed", config={'bind_port': 7950})
+mesh.add(ProcessorAgent)
+await mesh.start()
+
+results = await mesh.workflow("demo", [
+    {"agent": "processor", "task": "Process", "params": {"data": [1, 2, 3]}}
+])
+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 | 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
+
+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.3.2**
+
+## License
+
+MIT License

{jarviscore_framework-0.3.0 → jarviscore_framework-0.3.2}/examples/cloud_deployment_example.py

@@ -28,10 +28,10 @@ import sys
 
 sys.path.insert(0, '.')
 
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 
 
-class StandaloneProcessor(ListenerAgent):
+class StandaloneProcessor(CustomAgent):
     """
     Example standalone agent that joins mesh independently.
 
@@ -143,7 +143,7 @@ async def main():
     print("Listening for peer requests...")
     print("Press Ctrl+C to stop.\n")
 
-    # Run agent (ListenerAgent's run() handles the message loop)
+    # Run agent (CustomAgent's run() handles the message loop)
     try:
         await agent.run()
     except asyncio.CancelledError:

jarviscore_framework-0.3.0/jarviscore/data/examples/listeneragent_cognitive_discovery_example.py → jarviscore_framework-0.3.2/examples/customagent_cognitive_discovery_example.py

@@ -1,42 +1,47 @@
 """
-ListenerAgent + Cognitive Discovery Example
+CustomAgent + Cognitive Discovery Example
 
-Demonstrates two v0.3.0 features:
+Demonstrates v0.3.0 and v0.3.2 features:
 
-1. ListenerAgent - Handler-based P2P agents (no run() loop needed)
+1. CustomAgent - 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
+2. Cognitive Discovery (v0.3.0) - 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
 
+3. Session Context (v0.3.2) - Request tracking with metadata
+   - Pass context={mission_id, request_id} with peer requests
+   - Track requests across agent boundaries for debugging/tracing
+
 Usage:
-    python examples/listeneragent_cognitive_discovery_example.py
+    python examples/customagent_cognitive_discovery_example.py
 
 Prerequisites:
     - .env file with CLAUDE_API_KEY (or other LLM provider)
 """
 import asyncio
 import sys
+import uuid
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
 from jarviscore import Mesh
-from jarviscore.profiles import ListenerAgent
+from jarviscore.profiles import CustomAgent
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # SPECIALIST AGENT - Responds to requests from other agents
 # ═══════════════════════════════════════════════════════════════════════════════
 
-class AnalystAgent(ListenerAgent):
+class AnalystAgent(CustomAgent):
     """
     Specialist agent that handles analysis requests.
 
-    Uses ListenerAgent profile - just implement handlers, no run() loop needed.
+    Uses CustomAgent profile - just implement handlers, no run() loop needed.
     """
     role = "analyst"
     capabilities = ["data_analysis", "statistics", "insights"]
@@ -45,13 +50,21 @@ class AnalystAgent(ListenerAgent):
     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]}...")
+
+        # v0.3.2: Access session context for request tracking
+        context = msg.context or {}
+        mission_id = context.get("mission_id", "unknown")
+        request_id = context.get("request_id", "unknown")
+
+        print(f"\n[Analyst] Received request (mission={mission_id[:8]}..., req={request_id[:8]}...)")
+        print(f"[Analyst] Query: {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"]
+            "insights": ["Trend is upward", "Growth rate: 15%", "Recommendation: Continue"],
+            "context": {"mission_id": mission_id, "request_id": request_id}  # Echo back for tracing
         }
 
         print(f"[Analyst] Sending response with {len(result['insights'])} insights")
@@ -62,7 +75,7 @@ class AnalystAgent(ListenerAgent):
 # COORDINATOR AGENT - Uses LLM with cognitive discovery
 # ═══════════════════════════════════════════════════════════════════════════════
 
-class CoordinatorAgent(ListenerAgent):
+class CoordinatorAgent(CustomAgent):
     """
     Coordinator agent that uses LLM with dynamic peer discovery.
 
@@ -78,6 +91,9 @@ class CoordinatorAgent(ListenerAgent):
     async def setup(self):
         await super().setup()
         self.llm = self._create_llm_client()
+        # v0.3.2: Track missions for context propagation
+        self.mission_id = str(uuid.uuid4())
+        self.request_counter = 0
 
     def _create_llm_client(self):
         """Create LLM client with fallback to mock."""
@@ -167,10 +183,22 @@ Never try to do analysis yourself - always delegate to the analyst."""
             # 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")
+
+                # v0.3.2: Generate request context for tracking
+                self.request_counter += 1
+                request_context = {
+                    "mission_id": self.mission_id,
+                    "request_id": str(uuid.uuid4()),
+                    "request_num": self.request_counter,
+                    "source": "coordinator"
+                }
+                print(f"[Coordinator] Sending with context: mission={self.mission_id[:8]}...")
+
                 response = await self.peers.request(
                     "analyst",
                     {"question": user_query},
-                    timeout=30
+                    timeout=30,
+                    context=request_context  # v0.3.2: Pass context
                 )
                 return f"Based on the analyst's findings: {response.get('analysis', 'No response')}"
             return f"I can help with: {user_query}"
@@ -261,12 +289,24 @@ Never try to do analysis yourself - always delegate to the analyst."""
         role = args.get("role", "")
         question = args.get("question", "")
 
+        # v0.3.2: Generate request context for tracking
+        self.request_counter += 1
+        request_context = {
+            "mission_id": self.mission_id,
+            "request_id": str(uuid.uuid4()),
+            "request_num": self.request_counter,
+            "source": "coordinator",
+            "tool": "ask_peer"
+        }
+
         print(f"[Coordinator] Asking {role}: {question[:50]}...")
+        print(f"[Coordinator] Context: mission={self.mission_id[:8]}..., req_num={self.request_counter}")
 
         response = await self.peers.request(
             role,
             {"question": question},
-            timeout=30
+            timeout=30,
+            context=request_context  # v0.3.2: Pass context
         )
 
         return response
@@ -284,7 +324,8 @@ Never try to do analysis yourself - always delegate to the analyst."""
 
 async def main():
     print("=" * 60)
-    print("LLM Cognitive Discovery Example")
+    print("CustomAgent + Cognitive Discovery + Session Context")
+    print("Features: v0.3.0 Cognitive Discovery, v0.3.2 Session Context")
     print("=" * 60)
 
     # Create mesh with both agents

{jarviscore_framework-0.3.0 → jarviscore_framework-0.3.2}/examples/customagent_distributed_example.py

@@ -6,6 +6,10 @@ Demonstrates CustomAgent in distributed mode, which combines:
 - Workflow orchestration (step execution, dependencies)
 - User-controlled execution logic (you write execute_task)
 
+v0.3.2 Features Demonstrated:
+- Async Requests (ask_async) - Non-blocking parallel requests to multiple agents
+- Load Balancing (strategy="round_robin") - Distribute requests across agent instances
+
 This is ideal for:
 - Multi-node deployments with custom logic
 - Integrating external frameworks (LangChain, CrewAI, etc.)
@@ -231,6 +235,7 @@ async def main():
     """Run CustomAgent distributed mode example."""
     print("\n" + "="*70)
     print("JarvisCore: CustomAgent in Distributed Mode")
+    print("v0.3.2: Also supports --async and --load-balance demos")
     print("="*70)
 
     # ─────────────────────────────────────────────────────────────────────────
@@ -358,5 +363,139 @@ async def peer_communication_example():
     pass
 
 
+# ═══════════════════════════════════════════════════════════════════════════════
+# v0.3.2 FEATURES: ASYNC REQUESTS & LOAD BALANCING
+# ═══════════════════════════════════════════════════════════════════════════════
+
+async def async_requests_demo():
+    """
+    Demonstrate v0.3.2 async requests for parallel agent communication.
+
+    ask_async() returns a Future that can be awaited later, enabling:
+    - Fire multiple requests in parallel
+    - Continue other work while waiting
+    - Gather results when needed
+    """
+    print("\n" + "="*70)
+    print("v0.3.2 Feature: Async Requests (ask_async)")
+    print("="*70)
+
+    mesh = Mesh(mode="p2p", config={"bind_port": 7966})
+
+    # Add multiple agents
+    mesh.add(ContentResearcherAgent)
+    mesh.add(ContentWriterAgent)
+    mesh.add(ContentReviewerAgent)
+
+    try:
+        await mesh.start()
+
+        # Get an agent with peer access
+        researcher = next((a for a in mesh.agents if a.role == "content_researcher"), None)
+        if not researcher or not researcher.peers:
+            print("Peers not available")
+            return
+
+        print("\n[Demo] Firing parallel requests to multiple agents...")
+
+        # v0.3.2: ask_async returns a Future - doesn't block!
+        future1 = researcher.peers.ask_async(
+            "content_writer",
+            {"question": "What makes good technical writing?"}
+        )
+        future2 = researcher.peers.ask_async(
+            "content_reviewer",
+            {"question": "What are common writing mistakes?"}
+        )
+
+        print("[Demo] Requests sent! Doing other work while waiting...")
+        await asyncio.sleep(0.1)  # Simulate other work
+
+        # Gather results when ready
+        print("[Demo] Gathering results...")
+        results = await asyncio.gather(future1, future2, return_exceptions=True)
+
+        for i, result in enumerate(results):
+            if isinstance(result, Exception):
+                print(f"  Request {i+1}: Error - {result}")
+            else:
+                print(f"  Request {i+1}: Got response")
+
+        print("\n[Demo] Async requests complete!")
+
+    finally:
+        await mesh.stop()
+
+
+async def load_balancing_demo():
+    """
+    Demonstrate v0.3.2 load balancing strategies.
+
+    When multiple agents have the same capability, use strategy parameter:
+    - "random" (default): Random selection
+    - "round_robin": Distribute evenly across instances
+    """
+    print("\n" + "="*70)
+    print("v0.3.2 Feature: Load Balancing Strategies")
+    print("="*70)
+
+    mesh = Mesh(mode="p2p", config={"bind_port": 7967})
+
+    # Add agents
+    mesh.add(ContentResearcherAgent)
+    mesh.add(ContentWriterAgent)
+
+    try:
+        await mesh.start()
+
+        researcher = next((a for a in mesh.agents if a.role == "content_researcher"), None)
+        if not researcher or not researcher.peers:
+            print("Peers not available")
+            return
+
+        print("\n[Demo] Load balancing with strategy='round_robin'")
+        print("[Demo] Sending 3 requests to 'writing' capability...")
+
+        # v0.3.2: Use discover_one() with strategy for load balancing
+        for i in range(3):
+            # round_robin distributes requests evenly across matching peers
+            # First, discover which peer to use with the strategy
+            target = researcher.peers.discover_one(
+                role="content_writer",
+                strategy="round_robin"  # v0.3.2: Load balancing
+            )
+
+            if target:
+                # Then make the request to that specific peer
+                response = await researcher.peers.request(
+                    target.role,
+                    {"question": f"Request #{i+1}"},
+                    timeout=10
+                )
+                print(f"  Request {i+1}: Handled by {target.agent_id[:8]}...")
+            else:
+                print(f"  Request {i+1}: No peer found")
+
+        print("\n[Demo] Load balancing complete!")
+        print("[Demo] In a multi-node setup with multiple writers,")
+        print("       round_robin would distribute across all instances.")
+
+    finally:
+        await mesh.stop()
+
+
 if __name__ == "__main__":
-    asyncio.run(main())
+    import sys
+
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "--async":
+            asyncio.run(async_requests_demo())
+        elif sys.argv[1] == "--load-balance":
+            asyncio.run(load_balancing_demo())
+        else:
+            print("Usage:")
+            print("  python customagent_distributed_example.py           # Main workflow demo")
+            print("  python customagent_distributed_example.py --async   # Async requests demo")
+            print("  python customagent_distributed_example.py --load-balance  # Load balancing demo")
+    else:
+        asyncio.run(main())