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

jarviscore/docs/CUSTOMAGENT_GUIDE.md

@@ -0,0 +1,415 @@
+# CustomAgent Guide
+
+CustomAgent is for users who **already have working code** and want to integrate with JarvisCore.
+
+You keep your execution logic. Framework provides:
+- Agent discovery and communication
+- Workflow orchestration (distributed mode)
+- P2P peer tools (ask_peer, broadcast, etc.)
+
+---
+
+## Quick Reference
+
+| Mode | Use Case | Agent Method |
+|------|----------|--------------|
+| **P2P** | Direct agent communication | `run()` loop |
+| **Distributed** | Multi-node workflows | `execute_task()` |
+
+---
+
+## P2P Mode: Standalone → Framework
+
+### Your Standalone Agents (Before)
+
+You have two agents that communicate directly:
+
+```python
+# standalone_researcher.py
+class StandaloneResearcher:
+    """Your existing researcher agent."""
+
+    def __init__(self):
+        self.llm = MyLLMClient()
+
+    def research(self, query: str) -> str:
+        """Your existing research logic."""
+        return self.llm.chat(f"Research: {query}")
+
+
+# standalone_assistant.py
+class StandaloneAssistant:
+    """Your existing assistant that needs researcher help."""
+
+    def __init__(self, researcher: StandaloneResearcher):
+        self.researcher = researcher  # Direct reference
+        self.llm = MyLLMClient()
+
+    def help(self, question: str) -> str:
+        # Directly calls researcher
+        research = self.researcher.research(question)
+        return self.llm.chat(f"Based on: {research}\nAnswer: {question}")
+```
+
+**Problem**: Agents are tightly coupled. Can't run on different machines.
+
+---
+
+### With JarvisCore P2P Mode (After)
+
+**Step 1: Create `agents.py`** - Convert to CustomAgent
+
+```python
+# agents.py
+from jarviscore.profiles import CustomAgent
+
+class ResearcherAgent(CustomAgent):
+    """Same logic, now framework-integrated."""
+    role = "researcher"
+    capabilities = ["research", "analysis"]
+
+    async def setup(self):
+        await super().setup()
+        self.llm = MyLLMClient()  # Your existing LLM
+
+    async def run(self):
+        """REQUIRED for P2P: Listen for peer requests."""
+        while not self.shutdown_requested:
+            if self.peers:
+                msg = await self.peers.receive(timeout=0.5)
+                if msg and msg.is_request:
+                    query = msg.data.get("question", "")
+                    # Your existing logic
+                    result = self.llm.chat(f"Research: {query}")
+                    await self.peers.respond(msg, {"response": result})
+            else:
+                await asyncio.sleep(0.1)
+
+    async def execute_task(self, task):
+        return {"status": "success"}  # Required but unused in P2P
+
+
+class AssistantAgent(CustomAgent):
+    """Same logic, now uses peer tools instead of direct reference."""
+    role = "assistant"
+    capabilities = ["help", "coordination"]
+
+    async def setup(self):
+        await super().setup()
+        self.llm = MyLLMClient()
+
+    async def ask_researcher(self, question: str) -> str:
+        """Replaces direct self.researcher reference."""
+        if self.peers:
+            return await self.peers.as_tool().execute(
+                "ask_peer",
+                {"role": "researcher", "question": question}
+            )
+        return "No researcher available"
+
+    async def help(self, question: str) -> str:
+        """Your existing logic, now uses peer communication."""
+        research = await self.ask_researcher(question)
+        return self.llm.chat(f"Based on: {research}\nAnswer: {question}")
+
+    async def run(self):
+        """Listen for requests or external triggers."""
+        while not self.shutdown_requested:
+            # Your run loop - could listen for HTTP, websocket, etc.
+            await asyncio.sleep(0.1)
+
+    async def execute_task(self, task):
+        return {"status": "success"}
+```
+
+**Step 2: Create `main.py`** - Run with mesh
+
+```python
+# main.py
+import asyncio
+from jarviscore import Mesh
+from agents import ResearcherAgent, AssistantAgent
+
+async def main():
+    mesh = Mesh(
+        mode="p2p",
+        config={
+            'bind_port': 7950,
+            'node_name': 'my-agents',
+        }
+    )
+
+    mesh.add(ResearcherAgent)
+    mesh.add(AssistantAgent)
+
+    await mesh.start()
+
+    # Option 1: Run forever (agents handle their own work)
+    # await mesh.run_forever()
+
+    # Option 2: Manual interaction
+    assistant = mesh.get_agent("assistant")
+    result = await assistant.help("What is quantum computing?")
+    print(result)
+
+    await mesh.stop()
+
+asyncio.run(main())
+```
+
+### What Changed
+
+| Before | After |
+|--------|-------|
+| Direct object reference | `self.peers.as_tool().execute("ask_peer", ...)` |
+| Tightly coupled | Loosely coupled via peer discovery |
+| Same process only | Can run on different machines |
+| No discovery | Automatic agent discovery |
+
+### Key Additions
+
+1. **Inherit from `CustomAgent`** instead of plain class
+2. **Add `role` and `capabilities`** class attributes
+3. **Implement `run()`** method for continuous listening
+4. **Use `self.peers`** for communication instead of direct references
+
+---
+
+## Distributed Mode: Standalone → Framework
+
+### Your Standalone Pipeline (Before)
+
+You have agents that execute in a pipeline:
+
+```python
+# standalone_pipeline.py
+class StandaloneResearcher:
+    def __init__(self):
+        self.llm = MyLLMClient()
+
+    def execute(self, task: str) -> dict:
+        result = self.llm.chat(f"Research: {task}")
+        return {"output": result}
+
+
+class StandaloneWriter:
+    def __init__(self):
+        self.llm = MyLLMClient()
+
+    def execute(self, task: str, context: dict = None) -> dict:
+        prompt = task
+        if context:
+            prompt = f"Based on: {context}\n\n{task}"
+        result = self.llm.chat(prompt)
+        return {"output": result}
+
+
+# Manual orchestration
+def run_pipeline():
+    researcher = StandaloneResearcher()
+    writer = StandaloneWriter()
+
+    # Step 1
+    research = researcher.execute("Research AI trends")
+
+    # Step 2 - manually pass context
+    article = writer.execute("Write article", context=research["output"])
+
+    return article
+```
+
+**Problem**: Manual orchestration. No dependency management. Single machine.
+
+---
+
+### With JarvisCore Distributed Mode (After)
+
+**Step 1: Create `agents.py`** - Convert to CustomAgent
+
+```python
+# agents.py
+from jarviscore.profiles import CustomAgent
+
+class ResearcherAgent(CustomAgent):
+    role = "researcher"
+    capabilities = ["research"]
+
+    async def setup(self):
+        await super().setup()
+        self.llm = MyLLMClient()
+
+    async def execute_task(self, task):
+        """REQUIRED for Distributed: Called by workflow engine."""
+        task_desc = task.get("task", "")
+        # Your existing logic
+        result = self.llm.chat(f"Research: {task_desc}")
+        return {
+            "status": "success",
+            "output": result
+        }
+
+
+class WriterAgent(CustomAgent):
+    role = "writer"
+    capabilities = ["writing"]
+
+    async def setup(self):
+        await super().setup()
+        self.llm = MyLLMClient()
+
+    async def execute_task(self, task):
+        """Context from previous steps is automatically passed."""
+        task_desc = task.get("task", "")
+        context = task.get("context", {})  # From depends_on steps
+
+        prompt = task_desc
+        if context:
+            prompt = f"Based on: {context}\n\n{task_desc}"
+
+        result = self.llm.chat(prompt)
+        return {
+            "status": "success",
+            "output": result
+        }
+```
+
+**Step 2: Create `main.py`** - Run with mesh
+
+```python
+# main.py
+import asyncio
+from jarviscore import Mesh
+from agents import ResearcherAgent, WriterAgent
+
+async def main():
+    mesh = Mesh(
+        mode="distributed",
+        config={
+            'bind_port': 7950,
+            'node_name': 'content-node',
+        }
+    )
+
+    mesh.add(ResearcherAgent)
+    mesh.add(WriterAgent)
+
+    await mesh.start()
+
+    # Workflow engine handles orchestration
+    results = await mesh.workflow("content-pipeline", [
+        {
+            "id": "research",
+            "agent": "researcher",
+            "task": "Research AI trends"
+        },
+        {
+            "id": "write",
+            "agent": "writer",
+            "task": "Write article about the research",
+            "depends_on": ["research"]  # Auto-injects context
+        }
+    ])
+
+    print(results[0]["output"])  # Research
+    print(results[1]["output"])  # Article
+
+    await mesh.stop()
+
+asyncio.run(main())
+```
+
+### What Changed
+
+| Before | After |
+|--------|-------|
+| Manual `context` passing | `depends_on` + automatic injection |
+| Manual orchestration | `mesh.workflow()` handles it |
+| Same process only | Can span multiple machines |
+| No retries | Framework handles failures |
+
+### Key Additions
+
+1. **Inherit from `CustomAgent`**
+2. **Add `role` and `capabilities`**
+3. **Implement `execute_task(task)`** - receives `task` dict with `context`
+4. **Use `mesh.workflow()`** with `depends_on` for dependencies
+
+---
+
+## Multi-Node Distributed
+
+Same agents, different machines:
+
+**Machine 1:**
+```python
+mesh = Mesh(mode="distributed", config={
+    'bind_host': '0.0.0.0',
+    'bind_port': 7950,
+    'node_name': 'research-node',
+})
+mesh.add(ResearcherAgent)
+await mesh.start()
+await mesh.serve_forever()
+```
+
+**Machine 2:**
+```python
+mesh = Mesh(mode="distributed", config={
+    'bind_host': '0.0.0.0',
+    'bind_port': 7950,
+    'node_name': 'writer-node',
+    'seed_nodes': '192.168.1.10:7950',  # Machine 1
+})
+mesh.add(WriterAgent)
+await mesh.start()
+await mesh.serve_forever()
+```
+
+Workflows automatically route to the right machine.
+
+---
+
+## P2P vs Distributed: Which to Use?
+
+| Scenario | Mode |
+|----------|------|
+| Agents run continuously, self-coordinate | **P2P** |
+| Chatbot with specialist agents | **P2P** |
+| Task pipelines with dependencies | **Distributed** |
+| Need workflow orchestration | **Distributed** |
+| Both continuous + workflows | **Distributed** (supports both) |
+
+---
+
+## Summary
+
+### P2P Mode
+```python
+class MyAgent(CustomAgent):
+    role = "my_role"
+    capabilities = ["my_cap"]
+
+    async def run(self):  # Required
+        while not self.shutdown_requested:
+            msg = await self.peers.receive(timeout=0.5)
+            # Handle messages
+
+mesh = Mesh(mode="p2p", config={'bind_port': 7950})
+await mesh.run_forever()
+```
+
+### Distributed Mode
+```python
+class MyAgent(CustomAgent):
+    role = "my_role"
+    capabilities = ["my_cap"]
+
+    async def execute_task(self, task):  # Required
+        # Your logic
+        return {"status": "success", "output": result}
+
+mesh = Mesh(mode="distributed", config={'bind_port': 7950})
+results = await mesh.workflow("my-workflow", [...])
+```
+
+See `examples/customagent_p2p_example.py` and `examples/customagent_distributed_example.py` for complete examples.

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!
@@ -29,17 +50,20 @@ An **AutoAgent** that takes natural language prompts and automatically:
 ## Step 1: Install JarvisCore (30 seconds)
 
 ```bash
-pip install jarviscore
+pip install jarviscore-framework
 ```
 
 ---
 
 ## Step 2: Configure Your LLM (2 minutes)
 
-Create a `.env` file in your project directory:
+Initialize your project and create configuration files:
 
 ```bash
-# Copy the example config
+# Initialize project (creates .env.example and optionally examples)
+python -m jarviscore.cli.scaffold --examples
+
+# Copy and configure your environment
 cp .env.example .env
 ```
 
@@ -175,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:
@@ -196,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
 
@@ -302,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:
 
@@ -328,7 +425,7 @@ results = await mesh.workflow("workflow-id", [
 ])
 ```
 
-### 4. Results
+### 5. Results
 
 Each task returns a result dict:
 
@@ -368,7 +465,7 @@ Fine-tune LLM behavior:
 # Model selection (provider-specific)
 CLAUDE_MODEL=claude-sonnet-4        # Claude
 AZURE_DEPLOYMENT=gpt-4o             # Azure
-GEMINI_MODEL=gemini-1.5-flash       # Gemini
+GEMINI_MODEL=gemini-2.0-flash       # Gemini
 LLM_MODEL=Qwen/Qwen2.5-Coder-32B   # vLLM
 
 # Generation parameters
@@ -494,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
 
 ---
 
@@ -596,5 +694,3 @@ Need help?
 ---
 
 **🚀 Happy building with JarvisCore!**
-
-*Built for the AutoAgent/Prompt-Dev generation - where AI writes the code, you write the prompts.*