jarviscore-framework 0.2.1__tar.gz → 0.3.1__tar.gz

{jarviscore_framework-0.2.1/jarviscore_framework.egg-info → jarviscore_framework-0.3.1}/PKG-INFO

@@ -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
 

jarviscore_framework-0.3.1/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.4.0**
+
+## License
+
+MIT License

jarviscore_framework-0.3.1/examples/cloud_deployment_example.py

@@ -0,0 +1,162 @@
+"""
+Cloud Deployment Example (v0.3.0)
+
+Demonstrates agent self-registration with join_mesh() and leave_mesh().
+Agents join an existing mesh independently - no central orchestrator needed.
+
+This is the pattern for:
+- Docker containers where each container runs one agent
+- Kubernetes pods with auto-scaling
+- Cloud Functions / Lambda
+- Any distributed deployment where agents start independently
+
+Usage:
+    # Terminal 1: Start a mesh (or use an existing one)
+    python examples/customagent_p2p_example.py
+
+    # Terminal 2: Run standalone agent that joins the mesh
+    JARVISCORE_SEED_NODES=127.0.0.1:7946 python examples/cloud_deployment_example.py
+
+Environment Variables:
+    JARVISCORE_SEED_NODES: Comma-separated seed nodes (e.g., "host1:7946,host2:7946")
+    JARVISCORE_MESH_ENDPOINT: Single mesh endpoint (alternative to seed_nodes)
+"""
+import asyncio
+import os
+import signal
+import sys
+
+sys.path.insert(0, '.')
+
+from jarviscore.profiles import CustomAgent
+
+
+class StandaloneProcessor(CustomAgent):
+    """
+    Example standalone agent that joins mesh independently.
+
+    This agent:
+    - Self-registers with the mesh on startup
+    - Listens for peer requests
+    - Shows its view of the mesh (cognitive context)
+    - Gracefully leaves mesh on shutdown
+    """
+
+    role = "standalone_processor"
+    capabilities = ["standalone", "processing", "example"]
+    description = "Processes requests from other mesh agents (standalone deployment)"
+
+    async def on_peer_request(self, msg):
+        """Handle incoming requests from other agents."""
+        print(f"\n[{self.role}] Received request from {msg.sender}:")
+        print(f"  Data: {msg.data}")
+
+        # Process the request
+        task = msg.data.get("task", "")
+        result = {
+            "status": "success",
+            "output": f"Processed: {task}",
+            "agent_id": self.agent_id,
+            "processed_by": self.role
+        }
+
+        print(f"[{self.role}] Sending response: {result}")
+        return result
+
+    async def on_peer_notify(self, msg):
+        """Handle incoming notifications from other agents."""
+        print(f"\n[{self.role}] Received notification from {msg.sender}:")
+        print(f"  Event: {msg.data.get('event', 'unknown')}")
+        print(f"  Data: {msg.data}")
+
+
+async def main():
+    print("=" * 60)
+    print("Standalone Agent Example - Cloud Deployment Pattern")
+    print("=" * 60)
+
+    # Check for mesh connection info
+    endpoint = os.environ.get("JARVISCORE_MESH_ENDPOINT")
+    seed_nodes = os.environ.get("JARVISCORE_SEED_NODES")
+
+    if not endpoint and not seed_nodes:
+        print("\nNo mesh endpoint configured!")
+        print("\nSet one of:")
+        print("  - JARVISCORE_MESH_ENDPOINT (single endpoint)")
+        print("  - JARVISCORE_SEED_NODES (comma-separated list)")
+        print("\nExample:")
+        print("  JARVISCORE_SEED_NODES=127.0.0.1:7946 python cloud_deployment_example.py")
+        print("\nTo start a mesh first, run:")
+        print("  python examples/customagent_p2p_example.py")
+        return
+
+    print(f"\nConnecting to mesh via: {endpoint or seed_nodes}")
+
+    # Create agent
+    agent = StandaloneProcessor()
+
+    # Join the mesh
+    print(f"\nJoining mesh...")
+    try:
+        await agent.join_mesh()
+    except Exception as e:
+        print(f"Failed to join mesh: {e}")
+        return
+
+    print(f"\nSuccessfully joined mesh!")
+    print(f"  Agent ID: {agent.agent_id}")
+    print(f"  Role: {agent.role}")
+    print(f"  Capabilities: {agent.capabilities}")
+
+    # Show discovered peers
+    print(f"\n--- Discovered Peers ---")
+    peers = agent.peers.list_peers()
+    if peers:
+        for p in peers:
+            location = f" ({p.get('location', 'unknown')})" if 'location' in p else ""
+            print(f"  - {p['role']}: {p['capabilities']}{location}")
+    else:
+        print("  No other peers discovered yet")
+
+    # Show cognitive context (what an LLM would see)
+    print(f"\n--- Cognitive Context for LLM ---")
+    print(agent.peers.get_cognitive_context())
+
+    # Setup graceful shutdown
+    shutdown_event = asyncio.Event()
+
+    def signal_handler():
+        print("\n\nShutdown requested (Ctrl+C)...")
+        agent.request_shutdown()
+        shutdown_event.set()
+
+    # Register signal handlers
+    loop = asyncio.get_event_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, signal_handler)
+        except NotImplementedError:
+            # Windows doesn't support add_signal_handler
+            pass
+
+    print(f"\n--- Agent Running ---")
+    print("Listening for peer requests...")
+    print("Press Ctrl+C to stop.\n")
+
+    # Run agent (CustomAgent's run() handles the message loop)
+    try:
+        await agent.run()
+    except asyncio.CancelledError:
+        pass
+
+    # Leave mesh gracefully
+    print("\nLeaving mesh...")
+    await agent.leave_mesh()
+    print("Goodbye!")
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        print("\nInterrupted.")