jarviscore-framework 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

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.
 
 ---
 
@@ -32,7 +32,7 @@ python -m jarviscore.cli.smoketest --verbose
 
 **Solution:**
 ```bash
-pip install jarviscore
+pip install jarviscore-framework
 
 # Or install in development mode
 cd jarviscore
@@ -45,8 +45,8 @@ pip install -e .
 
 **Solution:**
 ```bash
-pip uninstall jarviscore
-pip install jarviscore
+pip uninstall jarviscore-framework
+pip install jarviscore-framework
 ```
 
 ---
@@ -58,8 +58,9 @@ pip install jarviscore
 **Cause:** Missing API key in `.env`
 
 **Solution:**
-1. Copy example config:
+1. Initialize project and copy example config:
    ```bash
+   python -m jarviscore.cli.scaffold
    cp .env.example .env
    ```
 
@@ -198,13 +199,77 @@ 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`
 
 **Solution:**
 ```bash
-# Create from example
+# Initialize project first (creates .env.example)
+python -m jarviscore.cli.scaffold
+
+# Then copy and configure
 cp .env.example .env
 
 # Or create manually
@@ -230,7 +295,7 @@ python your_script.py
 
 ---
 
-### 6. Sandbox Configuration
+### 7. Sandbox Configuration
 
 #### Issue: `Remote sandbox connection failed`
 
@@ -255,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)
 
@@ -291,7 +427,7 @@ python your_script.py
 
 ---
 
-### 8. Testing Issues
+### 9. Testing Issues
 
 #### Issue: Smoke test fails but examples work
 
@@ -361,7 +497,7 @@ If issues persist:
 
 3. **Provide this info when asking for help:**
    - Python version: `python --version`
-   - JarvisCore version: `pip show jarviscore`
+   - JarvisCore version: `pip show jarviscore-framework`
    - LLM provider used (Claude/Azure/Gemini)
    - Error message and logs
    - Minimal code to reproduce issue
@@ -391,7 +527,7 @@ If issues persist:
 
 4. **Keep dependencies updated:**
    ```bash
-   pip install --upgrade jarviscore
+   pip install --upgrade jarviscore-framework
    ```
 
 5. **Use version control for `.env`:**
@@ -421,4 +557,10 @@ If significantly slower:
 
 ---
 
-*Last updated: 2026-01-13*
+*Last updated: 2026-01-22*
+
+---
+
+## Version
+
+Troubleshooting Guide for JarvisCore v0.2.0