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

jarviscore_framework-0.2.1/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: jarviscore-framework
+Version: 0.2.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>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Prescott-Data/jarviscore-framework
+Project-URL: Documentation, https://github.com/Prescott-Data/jarviscore-framework/tree/main/jarviscore/docs
+Project-URL: Repository, https://github.com/Prescott-Data/jarviscore-framework
+Project-URL: Issues, https://github.com/Prescott-Data/jarviscore-framework/issues
+Keywords: agents,p2p,llm,distributed,workflow,orchestration
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: swim-p2p
+Requires-Dist: pyzmq
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: anthropic>=0.18.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: jarviscore[dev]; extra == "all"
+Dynamic: license-file
+
+# 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 (LangChain, CrewAI, etc.)
+- ✅ **P2P Mesh** - Agent discovery and communication via SWIM protocol
+- ✅ **Workflow Orchestration** - Dependencies, context passing, multi-step pipelines
+
+## 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 (Your Code)
+
+```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]
+```
+
+## 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 |
+
+## 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
+
+## Version
+
+**0.2.1**
+
+## License
+
+MIT License

jarviscore_framework-0.2.1/README.md

@@ -0,0 +1,101 @@
+# 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 (LangChain, CrewAI, etc.)
+- ✅ **P2P Mesh** - Agent discovery and communication via SWIM protocol
+- ✅ **Workflow Orchestration** - Dependencies, context passing, multi-step pipelines
+
+## 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 (Your Code)
+
+```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]
+```
+
+## 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 |
+
+## 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
+
+## Version
+
+**0.2.1**
+
+## License
+
+MIT License

jarviscore_framework-0.2.1/examples/autoagent_distributed_example.py

@@ -0,0 +1,211 @@
+"""
+AutoAgent Distributed Mode Example
+
+Demonstrates AutoAgent in distributed mode, which combines:
+- P2P network layer (SWIM protocol, ZMQ messaging)
+- Workflow orchestration (step execution, dependencies)
+
+This is ideal for multi-node deployments where agents can:
+- Execute on different machines
+- Discover each other via SWIM
+- Run orchestrated workflows across the network
+
+Usage:
+    python examples/autoagent_distributed_example.py
+
+Prerequisites:
+    - .env file with LLM API key (CLAUDE_API_KEY, etc.)
+"""
+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 AutoAgent
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# AUTOAGENT DEFINITIONS
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class DataCollectorAgent(AutoAgent):
+    """Collects and generates data."""
+    role = "collector"
+    capabilities = ["data_collection", "sampling"]
+    system_prompt = """
+    You are a data collection specialist. Generate sample datasets
+    based on specifications. Use Python's standard library only.
+    Store results in a variable named 'result' as a dictionary.
+    """
+
+
+class DataProcessorAgent(AutoAgent):
+    """Processes and transforms data."""
+    role = "processor"
+    capabilities = ["data_processing", "transformation"]
+    system_prompt = """
+    You are a data processing expert. Transform and clean datasets.
+    Apply filters, aggregations, and transformations as needed.
+    Use Python's standard library only. Store results in 'result'.
+    """
+
+
+class ReportWriterAgent(AutoAgent):
+    """Generates reports from processed data."""
+    role = "reporter"
+    capabilities = ["reporting", "documentation"]
+    system_prompt = """
+    You are a technical writer. Create clear, well-formatted reports
+    from data. Use markdown formatting. Store the report in 'result'.
+    """
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# MAIN EXAMPLE
+# ═══════════════════════════════════════════════════════════════════════════════
+
+async def main():
+    """Run AutoAgent distributed mode example."""
+    print("\n" + "="*70)
+    print("JarvisCore: AutoAgent in Distributed Mode")
+    print("="*70)
+
+    # ─────────────────────────────────────────────────────────────────────────
+    # KEY DIFFERENCE: mode="distributed" with P2P configuration
+    # ─────────────────────────────────────────────────────────────────────────
+    mesh = Mesh(
+        mode="distributed",  # Enables P2P + Workflow Engine
+        config={
+            # P2P Network Configuration
+            'bind_host': '127.0.0.1',    # Interface to bind to
+            'bind_port': 7950,            # SWIM protocol port (ZMQ uses +1000)
+            'node_name': 'autoagent-node',
+
+            # For multi-node: uncomment to join existing cluster
+            # 'seed_nodes': '192.168.1.10:7950,192.168.1.11:7950',
+
+            # AutoAgent Configuration
+            'execution_timeout': 60,      # Max seconds per task
+            'max_repair_attempts': 2,     # Auto-repair on failure
+            'log_directory': './logs',    # Result storage
+        }
+    )
+
+    # Add agents - same as autonomous mode
+    mesh.add(DataCollectorAgent)
+    mesh.add(DataProcessorAgent)
+    mesh.add(ReportWriterAgent)
+
+    try:
+        await mesh.start()
+
+        print("\n[INFO] Mesh started in DISTRIBUTED mode")
+        print(f"  - P2P Coordinator: Active (port {mesh.config.get('bind_port', 7950)})")
+        print(f"  - Workflow Engine: Active")
+        print(f"  - Agents: {len(mesh.agents)}")
+
+        # ─────────────────────────────────────────────────────────────────────
+        # WORKFLOW EXECUTION - Same API as autonomous mode
+        # ─────────────────────────────────────────────────────────────────────
+        print("\n" + "-"*70)
+        print("Executing Pipeline: Collect → Process → Report")
+        print("-"*70)
+
+        results = await mesh.workflow("distributed-pipeline", [
+            {
+                "id": "collect",
+                "agent": "collector",
+                "task": "Generate a dataset of 10 products with name, price, and category"
+            },
+            {
+                "id": "process",
+                "agent": "processor",
+                "task": "Calculate total value, average price, and count by category",
+                "depends_on": ["collect"]
+            },
+            {
+                "id": "report",
+                "agent": "reporter",
+                "task": "Create a summary report with the statistics",
+                "depends_on": ["process"]
+            }
+        ])
+
+        # Display results
+        print("\n" + "="*70)
+        print("RESULTS")
+        print("="*70)
+
+        for i, result in enumerate(results):
+            step_names = ["Data Collection", "Data Processing", "Report Generation"]
+            print(f"\n{step_names[i]}:")
+            print(f"  Status: {result['status']}")
+            if result['status'] == 'success':
+                output = str(result.get('output', ''))[:200]
+                print(f"  Output: {output}...")
+            else:
+                print(f"  Error: {result.get('error')}")
+
+        # Summary
+        successes = sum(1 for r in results if r['status'] == 'success')
+        print(f"\n{'='*70}")
+        print(f"Pipeline Complete: {successes}/{len(results)} steps successful")
+        print(f"{'='*70}")
+
+        await mesh.stop()
+
+    except Exception as e:
+        print(f"\nError: {e}")
+        import traceback
+        traceback.print_exc()
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# MULTI-NODE EXAMPLE (Reference)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+async def multi_node_example():
+    """
+    Example: Running agents across multiple machines.
+
+    Node 1 (seed node):
+        mesh = Mesh(mode="distributed", config={
+            'bind_host': '0.0.0.0',
+            'bind_port': 7950,
+            'node_name': 'node-1',
+        })
+        mesh.add(DataCollectorAgent)
+        await mesh.start()
+        await mesh.serve_forever()  # Keep running
+
+    Node 2 (joins cluster):
+        mesh = Mesh(mode="distributed", config={
+            'bind_host': '0.0.0.0',
+            'bind_port': 7950,
+            'node_name': 'node-2',
+            'seed_nodes': '192.168.1.10:7950',  # Node 1's address
+        })
+        mesh.add(DataProcessorAgent)
+        await mesh.start()
+        await mesh.serve_forever()
+
+    Node 3 (joins cluster):
+        mesh = Mesh(mode="distributed", config={
+            'bind_host': '0.0.0.0',
+            'bind_port': 7950,
+            'node_name': 'node-3',
+            'seed_nodes': '192.168.1.10:7950',
+        })
+        mesh.add(ReportWriterAgent)
+        await mesh.start()
+        await mesh.serve_forever()
+
+    Any node can now execute workflows that span all three!
+    """
+    pass
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

jarviscore_framework-0.2.1/examples/custom_profile_decorator.py

@@ -0,0 +1,134 @@
+"""
+Custom Profile Example: Using @jarvis_agent Decorator
+
+This example shows how to use the @jarvis_agent decorator to convert
+any Python class into a JarvisCore agent without modifying the class.
+
+Use Case: You have existing Python classes/agents and want JarvisCore
+to handle orchestration (data handoff, dependencies, shared memory).
+"""
+import asyncio
+from jarviscore import Mesh, jarvis_agent, JarvisContext
+
+
+# Example 1: Simple decorator (no context needed)
+@jarvis_agent(role="processor", capabilities=["data_processing"])
+class DataProcessor:
+    """Simple data processor - doubles input values."""
+
+    def run(self, data):
+        """Process data by doubling values."""
+        if isinstance(data, list):
+            return {"processed": [x * 2 for x in data]}
+        return {"processed": data * 2}
+
+
+# Example 2: Decorator with context access
+@jarvis_agent(role="aggregator", capabilities=["aggregation"])
+class Aggregator:
+    """Aggregates results from previous steps using JarvisContext."""
+
+    def run(self, task, ctx: JarvisContext):
+        """
+        Access previous step results via ctx.previous().
+
+        Args:
+            task: The task description
+            ctx: JarvisContext with memory and dependency access
+        """
+        # Get output from a specific previous step
+        processed = ctx.previous("step1")
+
+        if processed:
+            data = processed.get("processed", [])
+            return {
+                "sum": sum(data) if isinstance(data, list) else data,
+                "count": len(data) if isinstance(data, list) else 1,
+                "source_step": "step1"
+            }
+
+        return {"error": "No previous data found"}
+
+
+# Example 3: Decorator with custom execute method
+@jarvis_agent(role="validator", capabilities=["validation"], execute_method="validate")
+class DataValidator:
+    """Validates data using a custom method name."""
+
+    def validate(self, data):
+        """Custom execute method - validates input data."""
+        if isinstance(data, list):
+            return {
+                "valid": all(isinstance(x, (int, float)) for x in data),
+                "count": len(data),
+                "type": "list"
+            }
+        return {
+            "valid": isinstance(data, (int, float)),
+            "type": type(data).__name__
+        }
+
+
+async def main():
+    """Run a multi-step workflow with custom profile agents."""
+    print("=" * 60)
+    print("  Custom Profile Example: @jarvis_agent Decorator")
+    print("=" * 60)
+
+    # Create mesh in autonomous mode
+    mesh = Mesh(mode="autonomous")
+
+    # Add our decorated agents
+    mesh.add(DataProcessor)
+    mesh.add(Aggregator)
+    mesh.add(DataValidator)
+
+    # Start the mesh
+    await mesh.start()
+
+    try:
+        # Execute a multi-step workflow
+        print("\nExecuting workflow with 3 steps...\n")
+
+        results = await mesh.workflow("custom-profile-demo", [
+            {
+                "id": "step1",
+                "agent": "processor",
+                "task": "Process input data",
+                "params": {"data": [1, 2, 3, 4, 5]}
+            },
+            {
+                "id": "step2",
+                "agent": "aggregator",
+                "task": "Aggregate processed results",
+                "depends_on": ["step1"]  # Wait for step1
+            },
+            {
+                "id": "step3",
+                "agent": "validator",
+                "task": "Validate original data",
+                "params": {"data": [1, 2, 3, 4, 5]}
+            }
+        ])
+
+        # Print results
+        print("Results:")
+        print("-" * 40)
+
+        for i, result in enumerate(results):
+            step_name = ["Processor", "Aggregator", "Validator"][i]
+            print(f"\n{step_name} (step{i+1}):")
+            print(f"  Status: {result.get('status')}")
+            print(f"  Output: {result.get('output')}")
+
+        print("\n" + "=" * 60)
+        print("  Workflow completed successfully!")
+        print("=" * 60)
+
+    finally:
+        # Stop the mesh
+        await mesh.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())