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

jarviscore/docs/GETTING_STARTED.md

@@ -4,11 +4,32 @@ Build your first AI agent in 5 minutes!
 
 ---
 
+## Choose Your Path
+
+### Profiles (How agents execute)
+
+| Profile | Best For | LLM Required |
+|---------|----------|--------------|
+| **AutoAgent** | Rapid prototyping, LLM generates code from prompts | Yes |
+| **CustomAgent** | Existing code, full control (LangChain, CrewAI, etc.) | Optional |
+
+### Execution Modes (How agents are orchestrated)
+
+| Mode | Use Case | Start Here |
+|------|----------|------------|
+| **Autonomous** | Single machine, simple pipelines | ✅ This guide |
+| **P2P** | Direct agent communication, swarms | [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) |
+| **Distributed** | Multi-node production systems | [AutoAgent Guide](AUTOAGENT_GUIDE.md) |
+
+**Recommendation:** Start with **AutoAgent + Autonomous mode** below, then explore other modes.
+
+---
+
 ## What You'll Build
 
 An **AutoAgent** that takes natural language prompts and automatically:
 1. Generates Python code using an LLM
-2. Executes the code securely
+2. Executes the code securely in a sandbox
 3. Returns the result
 
 **No manual coding required** - just describe what you want!
@@ -178,6 +199,56 @@ Execution time: 4.23s
 
 ---
 
+## Step 5: Try CustomAgent (Alternative Path)
+
+If you have existing agents or don't need LLM code generation, use **CustomAgent**:
+
+```python
+import asyncio
+from jarviscore import Mesh
+from jarviscore.profiles import CustomAgent
+
+
+class MyAgent(CustomAgent):
+    role = "processor"
+    capabilities = ["data_processing"]
+
+    async def execute_task(self, task):
+        """Your existing logic goes here."""
+        data = task.get("params", {}).get("data", [])
+        result = [x * 2 for x in data]
+        return {"status": "success", "output": result}
+
+
+async def main():
+    # CustomAgent uses "distributed" (workflow + P2P) or "p2p" (P2P only)
+    mesh = Mesh(mode="distributed", config={
+        'bind_port': 7950,
+        'node_name': 'custom-node',
+    })
+    mesh.add(MyAgent)
+    await mesh.start()
+
+    results = await mesh.workflow("custom-demo", [
+        {"agent": "processor", "task": "Process data", "params": {"data": [1, 2, 3]}}
+    ])
+
+    print(results[0]["output"])  # [2, 4, 6]
+    await mesh.stop()
+
+
+asyncio.run(main())
+```
+
+**Key Benefits:**
+- No LLM API required (no costs!)
+- Keep your existing logic
+- Works with any framework (LangChain, CrewAI, etc.)
+
+**For more:** See [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) for P2P mode and multi-node examples.
+
+---
+
 ## What Just Happened?
 
 Behind the scenes, JarvisCore:
@@ -199,7 +270,7 @@ All from a single natural language prompt!
 
 ---
 
-## Step 5: Try More Complex Examples
+## Step 5: Try More Complex AutoAgent Profile Examples
 
 ### Example 1: Data Processing
 
@@ -305,19 +376,42 @@ class MyAgent(AutoAgent):
     system_prompt = "Instructions for the LLM"  # How to generate code
 ```
 
-### 2. Mesh
+### 2. CustomAgent Profile
+
+The `CustomAgent` profile lets you bring your own execution logic:
+
+```python
+class MyAgent(CustomAgent):
+    role = "unique_name"
+    capabilities = ["skill1", "skill2"]
+
+    async def execute_task(self, task):      # For workflow steps (distributed)
+        return {"status": "success", "output": ...}
+
+    async def run(self):                      # For continuous loop (p2p)
+        while not self.shutdown_requested:
+            msg = await self.peers.receive(timeout=0.5)
+            ...
+```
+
+### 3. Mesh
 
 The `Mesh` is the orchestrator that manages agents and workflows:
 
 ```python
-mesh = Mesh(mode="autonomous")  # Autonomous mode for AutoAgent
+mesh = Mesh(mode="autonomous")  # Or "p2p", "distributed"
 mesh.add(MyAgent)               # Register your agent
 await mesh.start()              # Initialize
 results = await mesh.workflow(...)  # Execute tasks
 await mesh.stop()               # Cleanup
 ```
 
-### 3. Workflow
+**Modes:**
+- `autonomous`: Workflow engine only (AutoAgent)
+- `p2p`: P2P coordinator for agent-to-agent communication (CustomAgent)
+- `distributed`: Both workflow engine AND P2P (CustomAgent)
+
+### 4. Workflow
 
 A workflow is a list of tasks to execute:
 
@@ -331,7 +425,7 @@ results = await mesh.workflow("workflow-id", [
 ])
 ```
 
-### 4. Results
+### 5. Results
 
 Each task returns a result dict:
 
@@ -497,11 +591,12 @@ Check `repairs` in the result to see how many fixes were needed.
 
 ## Next Steps
 
-1. **Read the User Guide**: Complete documentation at [USER_GUIDE.md](USER_GUIDE.md)
-2. **Explore Examples**: Check out `examples/` directory
-3. **Try the API Reference**: [API_REFERENCE.md](API_REFERENCE.md)
-4. **Configuration Guide**: [CONFIGURATION.md](CONFIGURATION.md)
-5. **Troubleshooting**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+1. **AutoAgent Guide**: Multi-node distributed mode → [AUTOAGENT_GUIDE.md](AUTOAGENT_GUIDE.md)
+2. **CustomAgent Guide**: P2P and distributed with your code → [CUSTOMAGENT_GUIDE.md](CUSTOMAGENT_GUIDE.md)
+3. **User Guide**: Complete documentation → [USER_GUIDE.md](USER_GUIDE.md)
+4. **API Reference**: [API_REFERENCE.md](API_REFERENCE.md)
+5. **Configuration**: [CONFIGURATION.md](CONFIGURATION.md)
+6. **Examples**: Check out `examples/` directory
 
 ---
 
@@ -594,10 +689,8 @@ Need help?
    python -m jarviscore.cli.smoketest --verbose
    ```
 3. **Check logs**: `cat logs/<agent>/<latest>.json`
-4. **Report issues**: [GitHub Issues](https://github.com/yourusername/jarviscore/issues)
+4. **Report issues**: [GitHub Issues](https://github.com/Prescott-Data/jarviscore-framework/issues)
 
 ---
 
 **🚀 Happy building with JarvisCore!**
-
-*Built for the AutoAgent/Prompt-Dev generation - where AI writes the code, you write the prompts.*

jarviscore/docs/TROUBLESHOOTING.md

@@ -1,6 +1,6 @@
 # JarvisCore Troubleshooting Guide
 
-Common issues and solutions for AutoAgent/Prompt-Dev users.
+Common issues and solutions for AutoAgent and CustomAgent users.
 
 ---
 
@@ -199,7 +199,68 @@ await mesh.workflow("wf-1", [
 
 ---
 
-### 5. Environment Issues
+### 5. CustomAgent Issues
+
+#### Issue: `execute_task not called`
+
+**Cause:** Wrong mode for your use case
+
+**Solution:**
+```python
+# For workflow orchestration (autonomous/distributed modes)
+class MyAgent(CustomAgent):
+    async def execute_task(self, task):  # Called by workflow engine
+        return {"status": "success", "output": ...}
+
+# For P2P mode, use run() instead
+class MyAgent(CustomAgent):
+    async def run(self):  # Called in P2P mode
+        while not self.shutdown_requested:
+            msg = await self.peers.receive(timeout=0.5)
+            ...
+```
+
+#### Issue: `self.peers is None`
+
+**Cause:** Agent not in P2P or distributed mode
+
+**Solution:**
+```python
+# Ensure mesh is in p2p or distributed mode
+mesh = Mesh(mode="distributed", config={  # or "p2p"
+    'bind_port': 7950,
+    'node_name': 'my-node',
+})
+
+# Check peers is available before using
+if self.peers:
+    result = await self.peers.as_tool().execute("ask_peer", {...})
+```
+
+#### Issue: `No response from peer`
+
+**Cause:** Target agent not listening or wrong role
+
+**Solution:**
+```python
+# Ensure target agent is running its run() loop
+# In researcher agent:
+async def run(self):
+    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": ...})
+
+# When asking, use correct role
+result = await self.peers.as_tool().execute(
+    "ask_peer",
+    {"role": "researcher", "question": "..."}  # Must match agent's role
+)
+```
+
+---
+
+### 6. Environment Issues
 
 #### Issue: `.env file not found`
 
@@ -234,7 +295,7 @@ python your_script.py
 
 ---
 
-### 6. Sandbox Configuration
+### 7. Sandbox Configuration
 
 #### Issue: `Remote sandbox connection failed`
 
@@ -259,7 +320,78 @@ python your_script.py
 
 ---
 
-### 7. Performance Issues
+### 8. P2P/Distributed Mode Issues
+
+#### Issue: `P2P coordinator failed to start`
+
+**Cause:** Port already in use or network issue
+
+**Solution:**
+```bash
+# Check if port is in use
+lsof -i :7950
+
+# Try different port
+mesh = Mesh(mode="distributed", config={
+    'bind_port': 7960,  # Different port
+})
+```
+
+#### Issue: `Cannot connect to seed nodes`
+
+**Cause:** Firewall, wrong address, or seed node not running
+
+**Solution:**
+```bash
+# Check connectivity
+nc -zv 192.168.1.10 7950
+
+# Open firewall ports
+sudo ufw allow 7950/tcp
+sudo ufw allow 7950/udp
+
+# Ensure seed node is running first
+# On seed node:
+mesh = Mesh(mode="distributed", config={
+    'bind_host': '0.0.0.0',  # Listen on all interfaces
+    'bind_port': 7950,
+})
+```
+
+#### Issue: `Workflow not available in p2p mode`
+
+**Cause:** P2P mode doesn't include workflow engine
+
+**Solution:**
+```python
+# Use distributed mode for both workflow + P2P
+mesh = Mesh(mode="distributed", config={...})
+
+# Or use p2p mode with run() loops instead
+mesh = Mesh(mode="p2p", config={...})
+await mesh.start()
+await mesh.run_forever()  # Agents use run() loops
+```
+
+#### Issue: `Agents not discovering each other`
+
+**Cause:** Network configuration or timing
+
+**Solution:**
+```python
+# Wait for mesh to stabilize after start
+await mesh.start()
+await asyncio.sleep(1)  # Give time for peer discovery
+
+# Check if peers are available
+agent = mesh.get_agent("my_role")
+if agent.peers:
+    print("Peers available")
+```
+
+---
+
+### 9. Performance Issues
 
 #### Issue: Code generation is slow (>10 seconds)
 
@@ -295,7 +427,7 @@ python your_script.py
 
 ---
 
-### 8. Testing Issues
+### 9. Testing Issues
 
 #### Issue: Smoke test fails but examples work
 
@@ -371,7 +503,7 @@ If issues persist:
    - Minimal code to reproduce issue
 
 4. **Create an issue:**
-   - GitHub: https://github.com/yourusername/jarviscore/issues
+   - GitHub: https://github.com/Prescott-Data/jarviscore-framework/issues
    - Include diagnostics output above
 
 ---
@@ -425,4 +557,10 @@ If significantly slower:
 
 ---
 
-*Last updated: 2026-01-13*
+*Last updated: 2026-01-23*
+
+---
+
+## Version
+
+Troubleshooting Guide for JarvisCore v0.2.1