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

jarviscore/docs/API_REFERENCE.md

@@ -12,6 +12,7 @@ Complete API documentation for JarvisCore framework components.
    - [Profile](#profile)
 2. [Agent Profiles](#agent-profiles)
    - [AutoAgent](#autoagent)
+   - [Custom Profile](#custom-profile)
    - [CustomAgent](#customagent)
 3. [Execution Components](#execution-components)
    - [CodeGenerator](#codegenerator)
@@ -39,35 +40,43 @@ The central orchestrator for managing agents and workflows.
 ```python
 from jarviscore import Mesh
 
-mesh = Mesh(mode="autonomous")  # or "distributed"
+mesh = Mesh(mode="autonomous")  # or "p2p" or "distributed"
 ```
 
 **Parameters:**
-- `mode` (str): Execution mode - "autonomous" (single-node) or "distributed" (P2P mesh)
+- `mode` (str): Execution mode
+  - `"autonomous"` - Workflow Engine only (single-node)
+  - `"p2p"` - P2P Coordinator only (SWIM protocol, ZMQ messaging)
+  - `"distributed"` - Both Workflow Engine AND P2P Coordinator
 - `config` (dict, optional): Configuration dictionary
 
+**Modes Comparison:**
+
+| Mode | Workflow Engine | P2P Coordinator | Use Case |
+|------|-----------------|-----------------|----------|
+| `autonomous` | ✅ | ❌ | Single machine, simple pipelines |
+| `p2p` | ❌ | ✅ | Agent swarms, real-time coordination |
+| `distributed` | ✅ | ✅ | Multi-node production systems |
+
 **Methods:**
 
-#### `add_agent(profile_class, role, capabilities, **kwargs)`
+#### `add(agent_class)`
 
-Register an agent in the mesh.
+Register an agent class in the mesh.
 
 ```python
 from jarviscore.profiles import AutoAgent
 
-mesh.add_agent(
-    AutoAgent,
-    role="calculator",
-    capabilities=["math", "calculation"],
-    system_prompt="You are a math expert"
-)
+class CalculatorAgent(AutoAgent):
+    role = "calculator"
+    capabilities = ["math", "calculation"]
+    system_prompt = "You are a math expert"
+
+mesh.add(CalculatorAgent)
 ```
 
 **Parameters:**
-- `profile_class`: Agent profile class (AutoAgent or CustomAgent)
-- `role` (str): Unique agent role identifier
-- `capabilities` (list): List of capability strings
-- `**kwargs`: Additional agent-specific parameters
+- `agent_class`: Agent class (AutoAgent or CustomAgent subclass)
 
 **Returns:** Agent instance
 
@@ -95,12 +104,12 @@ await mesh.stop()
 
 ---
 
-#### `async run_workflow(steps)`
+#### `async workflow(workflow_id, steps)`
 
 Execute a multi-step workflow with dependency management.
 
 ```python
-results = await mesh.run_workflow([
+results = await mesh.workflow("pipeline-id", [
     {"agent": "scraper", "task": "Scrape data from URL"},
     {"agent": "processor", "task": "Clean the data", "depends_on": [0]},
     {"agent": "storage", "task": "Save to database", "depends_on": [1]}
@@ -108,6 +117,7 @@ results = await mesh.run_workflow([
 ```
 
 **Parameters:**
+- `workflow_id` (str): Unique workflow identifier
 - `steps` (list): List of step dictionaries with keys:
   - `agent` (str): Role or capability of target agent
   - `task` (str): Task description
@@ -116,6 +126,20 @@ results = await mesh.run_workflow([
 
 **Returns:** List of result dictionaries
 
+**Note:** Only available in `autonomous` and `distributed` modes.
+
+---
+
+#### `async run_forever()`
+
+Keep the mesh running until shutdown signal (P2P and distributed modes).
+
+```python
+await mesh.run_forever()  # Blocks until SIGINT/SIGTERM
+```
+
+**Note:** Only available in `p2p` and `distributed` modes.
+
 ---
 
 ### Agent
@@ -288,6 +312,180 @@ results = await mesh.run_workflow([
 
 ---
 
+### Custom Profile
+
+The Custom Profile enables integration of existing agents without modification.
+
+#### Decorator: `@jarvis_agent`
+
+Convert any Python class into a JarvisCore agent:
+
+```python
+from jarviscore import jarvis_agent, JarvisContext
+
+@jarvis_agent(role="processor", capabilities=["data_processing"])
+class DataProcessor:
+    def run(self, data):
+        return {"processed": [x * 2 for x in data]}
+```
+
+**Parameters:**
+- `role` (str): Agent role identifier
+- `capabilities` (list): List of capability strings
+- `execute_method` (str, optional): Method name to call (default: auto-detect)
+
+**Auto-detected Methods:** `run`, `execute`, `invoke`, `call`, `process`
+
+**Context-Aware Methods:**
+
+If your method has a parameter named `ctx` or `context`, JarvisContext is automatically injected:
+
+```python
+@jarvis_agent(role="aggregator", capabilities=["aggregation"])
+class Aggregator:
+    def run(self, task, ctx: JarvisContext):
+        previous = ctx.previous("step1")
+        return {"result": previous}
+```
+
+---
+
+#### Function: `wrap()`
+
+Wrap an existing instance as a JarvisCore agent:
+
+```python
+from jarviscore import wrap
+
+wrapped = wrap(
+    instance=my_langchain_agent,
+    role="assistant",
+    capabilities=["chat", "qa"],
+    execute_method="invoke"
+)
+```
+
+**Parameters:**
+- `instance` (Any): Pre-instantiated object to wrap
+- `role` (str): Agent role identifier
+- `capabilities` (list): List of capability strings
+- `execute_method` (str, optional): Method name to call (default: auto-detect)
+
+**Returns:** `CustomAgent` instance ready for `mesh.add()`
+
+**Example:**
+
+```python
+from jarviscore import Mesh, wrap
+
+# Your existing LangChain agent
+my_agent = MyLangChainAgent(model="gpt-4")
+
+# Wrap it
+wrapped = wrap(
+    my_agent,
+    role="assistant",
+    capabilities=["chat"],
+    execute_method="invoke"
+)
+
+mesh = Mesh(mode="autonomous")
+mesh.add(wrapped)  # Add directly to mesh
+await mesh.start()
+```
+
+---
+
+#### Class: `JarvisContext`
+
+Provides workflow context access for Custom Profile agents:
+
+```python
+from jarviscore import JarvisContext
+
+def run(self, task, ctx: JarvisContext):
+    # Access previous step outputs
+    step1_output = ctx.previous("step1")
+
+    # Get all previous outputs
+    all_outputs = ctx.all_previous()
+
+    # Access shared memory
+    ctx.memory["key"] = "value"
+    value = ctx.memory.get("key")
+
+    return {"result": "..."}
+```
+
+**Attributes:**
+- `workflow_id` (str): Current workflow identifier
+- `step_id` (str): Current step identifier
+- `task` (str): Task description
+- `params` (dict): Task parameters
+- `memory` (MemoryAccessor): Shared workflow memory
+
+**Methods:**
+
+#### `previous(step_id: str) -> Optional[Any]`
+
+Get output from a specific previous step.
+
+```python
+step1_output = ctx.previous("step1")
+if step1_output:
+    data = step1_output.get("processed", [])
+```
+
+**Parameters:**
+- `step_id` (str): ID of the step to retrieve
+
+**Returns:** Step output or None if not found
+
+---
+
+#### `all_previous() -> Dict[str, Any]`
+
+Get outputs from all previous steps.
+
+```python
+all_outputs = ctx.all_previous()
+# {"step1": {...}, "step2": {...}}
+
+for step_id, output in all_outputs.items():
+    print(f"{step_id}: {output}")
+```
+
+**Returns:** Dictionary mapping step IDs to their outputs
+
+---
+
+#### Class: `MemoryAccessor`
+
+Dictionary-like interface for shared workflow memory:
+
+```python
+# Set value
+ctx.memory["key"] = "value"
+
+# Get value
+value = ctx.memory.get("key", "default")
+
+# Check existence
+if "key" in ctx.memory:
+    ...
+
+# Get all memory
+all_memory = ctx.memory.all()
+```
+
+**Methods:**
+- `get(key, default=None)` - Get value with optional default
+- `set(key, value)` - Set value
+- `all()` - Get entire memory dictionary
+- `__getitem__`, `__setitem__`, `__contains__` - Dict-like access
+
+---
+
 ### CustomAgent
 
 Flexible agent profile for integrating external frameworks.
@@ -297,51 +495,66 @@ Flexible agent profile for integrating external frameworks.
 ```python
 from jarviscore.profiles import CustomAgent
 
-class LangChainAgent(CustomAgent):
+class MyAgent(CustomAgent):
+    role = "my_role"
+    capabilities = ["my_capability"]
+
     async def setup(self):
-        from langchain import LLMChain
-        self.chain = LLMChain(...)
+        await super().setup()
+        # Initialize your resources
 
     async def execute_task(self, task):
-        result = await self.chain.arun(task['task'])
-        return {
-            "status": "success",
-            "output": result,
-            "agent": self.agent_id
-        }
+        """Called by workflow engine (autonomous/distributed modes)."""
+        return {"status": "success", "output": result}
+
+    async def run(self):
+        """Called in P2P mode - continuous run loop."""
+        while not self.shutdown_requested:
+            msg = await self.peers.receive(timeout=0.5)
+            if msg and msg.is_request:
+                await self.peers.respond(msg, {"response": "..."})
 ```
 
-**Features:**
-- Integrate LangChain, LlamaIndex, Haystack, CrewAI, etc.
-- Manual control over execution logic
-- Optional cost tracking with `track_cost()`
-- Full access to mesh and workflow context
+**Class Attributes:**
+- `role` (str): Agent role identifier (required)
+- `capabilities` (list): List of capability strings (required)
 
-**Example:**
+**Instance Attributes:**
+- `agent_id` (str): Unique agent identifier
+- `peers` (PeerTool): P2P communication tool (distributed/p2p modes)
+- `shutdown_requested` (bool): Set to True when shutdown requested
 
-```python
-class APIAgent(CustomAgent):
-    async def setup(self):
-        self.api_client = MyAPIClient()
+**Key Methods:**
 
-    async def execute_task(self, task):
-        # Manual implementation
-        response = await self.api_client.call(task['task'])
+| Method | Purpose | Mode |
+|--------|---------|------|
+| `setup()` | Initialize resources | All |
+| `execute_task(task)` | Handle workflow steps | Autonomous/Distributed |
+| `run()` | Continuous loop | P2P |
+| `teardown()` | Cleanup resources | All |
 
-        # Optional cost tracking
-        self.track_cost(
-            input_tokens=100,
-            output_tokens=50,
-            cost_usd=0.01
-        )
+**P2P Communication (distributed/p2p modes):**
 
-        return {
-            "status": "success",
-            "output": response,
-            "agent": self.agent_id
-        }
+```python
+async def run(self):
+    while not self.shutdown_requested:
+        # Receive messages
+        msg = await self.peers.receive(timeout=0.5)
+        if msg and msg.is_request:
+            # Process and respond
+            await self.peers.respond(msg, {"response": result})
+
+async def ask_another_agent(self, question):
+    # Ask another agent via peer tools
+    result = await self.peers.as_tool().execute(
+        "ask_peer",
+        {"role": "researcher", "question": question}
+    )
+    return result
 ```
 
+See [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) for P2P and distributed mode details.
+
 ---
 
 ## Execution Components
@@ -927,6 +1140,6 @@ async def execute_task(self, task: Dict[str, Any]) -> Dict[str, Any]:
 
 ## Version
 
-API Reference for JarvisCore v0.1.0
+API Reference for JarvisCore v0.2.1
 
-Last Updated: 2026-01-12
+Last Updated: 2026-01-23

jarviscore/docs/AUTOAGENT_GUIDE.md

@@ -0,0 +1,198 @@
+# AutoAgent Guide
+
+AutoAgent is the **zero-config** profile where the framework handles everything:
+- LLM code generation from natural language
+- Sandboxed code execution
+- Automatic error repair
+- Result storage
+
+You write **3 attributes**, framework does the rest.
+
+---
+
+## Quick Reference
+
+| Mode | Use Case | Key Difference |
+|------|----------|----------------|
+| **Autonomous** | Single machine | No network, local execution |
+| **Distributed** | Multi-node | P2P network + workflow orchestration |
+
+---
+
+## Autonomous Mode
+
+Single-node execution. No networking required.
+
+### Example
+
+```python
+import asyncio
+from jarviscore import Mesh
+from jarviscore.profiles import AutoAgent
+
+class CalculatorAgent(AutoAgent):
+    role = "calculator"
+    capabilities = ["math", "calculation"]
+    system_prompt = """
+    You are a math expert. Generate Python code to solve problems.
+    Store the result in a variable named 'result'.
+    """
+
+async def main():
+    mesh = Mesh(mode="autonomous")  # Default mode
+    mesh.add(CalculatorAgent)
+
+    await mesh.start()
+
+    results = await mesh.workflow("calc-task", [
+        {"agent": "calculator", "task": "Calculate factorial of 10"}
+    ])
+
+    print(results[0]["output"])  # {'result': 3628800}
+
+    await mesh.stop()
+
+asyncio.run(main())
+```
+
+### When to Use
+- Rapid prototyping
+- Single-machine deployments
+- Simple task pipelines
+- No need for agent-to-agent communication
+
+---
+
+## Distributed Mode
+
+Multi-node execution with P2P networking. Same API, just add config.
+
+### What Changes
+
+| Autonomous | Distributed |
+|------------|-------------|
+| `mode="autonomous"` | `mode="distributed"` |
+| No config needed | Add `bind_port`, `node_name` |
+| Single machine | Can span multiple machines |
+
+### Example (Single Node)
+
+```python
+import asyncio
+from jarviscore import Mesh
+from jarviscore.profiles import AutoAgent
+
+class CalculatorAgent(AutoAgent):
+    role = "calculator"
+    capabilities = ["math", "calculation"]
+    system_prompt = """
+    You are a math expert. Generate Python code to solve problems.
+    Store the result in a variable named 'result'.
+    """
+
+async def main():
+    mesh = Mesh(
+        mode="distributed",  # Enable P2P + workflow
+        config={
+            'bind_port': 7950,        # SWIM protocol port
+            'node_name': 'calc-node', # Node identifier
+        }
+    )
+    mesh.add(CalculatorAgent)
+
+    await mesh.start()
+
+    # Same API as autonomous!
+    results = await mesh.workflow("calc-task", [
+        {"agent": "calculator", "task": "Calculate factorial of 10"}
+    ])
+
+    print(results[0]["output"])
+
+    await mesh.stop()
+
+asyncio.run(main())
+```
+
+### Example (Multi-Node)
+
+**Node 1 - Seed node with calculator:**
+```python
+# node1.py
+mesh = Mesh(
+    mode="distributed",
+    config={
+        'bind_host': '0.0.0.0',
+        'bind_port': 7950,
+        'node_name': 'node-1',
+    }
+)
+mesh.add(CalculatorAgent)
+await mesh.start()
+await mesh.serve_forever()  # Keep running
+```
+
+**Node 2 - Joins cluster with analyzer:**
+```python
+# node2.py
+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(AnalyzerAgent)
+await mesh.start()
+await mesh.serve_forever()
+```
+
+**Execute workflows across nodes:**
+```python
+# From any node
+results = await mesh.workflow("cross-node", [
+    {"agent": "calculator", "task": "..."},  # Runs on Node 1
+    {"agent": "analyzer", "task": "...", "depends_on": [0]}  # Runs on Node 2
+])
+```
+
+### When to Use
+- Production multi-node systems
+- Agents on different machines
+- Scalable agent architectures
+- Need cross-node workflow coordination
+
+---
+
+## Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `bind_host` | `127.0.0.1` | Interface to bind |
+| `bind_port` | `7950` | SWIM protocol port |
+| `node_name` | `jarviscore-node` | Node identifier |
+| `seed_nodes` | `None` | Comma-separated seed addresses |
+| `execution_timeout` | `300` | Max seconds per task |
+| `max_repair_attempts` | `3` | Auto-repair retries |
+| `log_directory` | `./logs` | Result storage path |
+
+---
+
+## Summary
+
+```python
+# Autonomous (single node)
+mesh = Mesh(mode="autonomous")
+
+# Distributed (multi-node capable)
+mesh = Mesh(mode="distributed", config={'bind_port': 7950})
+
+# Everything else stays the same!
+mesh.add(MyAutoAgent)
+await mesh.start()
+results = await mesh.workflow(...)
+```
+
+See `examples/calculator_agent_example.py` and `examples/autoagent_distributed_example.py` for complete examples.

jarviscore/docs/CONFIGURATION.md

@@ -251,27 +251,28 @@ Generated code is automatically registered:
 
 ## P2P Configuration
 
-Configure distributed mesh networking (optional).
+Configure distributed mesh networking for `p2p` and `distributed` modes.
 
-### Enable P2P
+### Execution Modes
 
-```bash
-# Enable P2P mesh
-P2P_ENABLED=true
-
-# Node identification
-NODE_NAME=jarviscore-node-1
-```
+| Mode | Code Config | Workflow Engine | P2P Coordinator |
+|------|-------------|-----------------|-----------------|
+| `autonomous` | `Mesh(mode="autonomous")` | ✅ | ❌ |
+| `p2p` | `Mesh(mode="p2p", config={...})` | ❌ | ✅ |
+| `distributed` | `Mesh(mode="distributed", config={...})` | ✅ | ✅ |
 
-### Network Settings
+### Network Settings (P2P and Distributed)
 
 ```bash
 # Bind address and port
 BIND_HOST=0.0.0.0      # Listen on all interfaces
-BIND_PORT=7946         # SWIM protocol port
+BIND_PORT=7950         # SWIM protocol port
 
-# Seed nodes (comma-separated)
-SEED_NODES=192.168.1.100:7946,192.168.1.101:7946
+# Node identification
+NODE_NAME=jarviscore-node-1
+
+# Seed nodes (comma-separated) for joining existing cluster
+SEED_NODES=192.168.1.100:7950,192.168.1.101:7950
 ```
 
 ### Transport Configuration
@@ -540,14 +541,27 @@ Override environment variables in code:
 ```python
 from jarviscore import Mesh
 
-config = {
-    'sandbox_mode': 'remote',
-    'sandbox_service_url': 'https://...',
+# Autonomous mode (no P2P config needed)
+mesh = Mesh(mode="autonomous", config={
     'execution_timeout': 600,
     'log_level': 'DEBUG'
-}
-
-mesh = Mesh(mode="autonomous", config=config)
+})
+
+# P2P mode (requires network config)
+mesh = Mesh(mode="p2p", config={
+    'bind_host': '0.0.0.0',
+    'bind_port': 7950,
+    'node_name': 'my-node',
+    'seed_nodes': '192.168.1.10:7950',  # Optional, for joining cluster
+})
+
+# Distributed mode (both workflow + P2P)
+mesh = Mesh(mode="distributed", config={
+    'bind_host': '0.0.0.0',
+    'bind_port': 7950,
+    'node_name': 'my-node',
+    'execution_timeout': 600,
+})
 ```
 
 **Note:** Programmatic config overrides environment variables.
@@ -752,6 +766,6 @@ LOG_DIRECTORY=/tmp/jarviscore-logs
 
 ## Version
 
-Configuration Guide for JarvisCore v0.1.0
+Configuration Guide for JarvisCore v0.2.1
 
-Last Updated: 2026-01-12
+Last Updated: 2026-01-23