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

jarviscore/docs/USER_GUIDE.md

@@ -9,15 +9,16 @@ Practical guide to building agent systems with JarvisCore.
 1. [Quick Start](#quick-start)
 2. [Basic Concepts](#basic-concepts)
 3. [AutoAgent Tutorial](#autoagent-tutorial)
-4. [CustomAgent Tutorial](#customagent-tutorial)
-5. [Multi-Agent Workflows](#multi-agent-workflows)
-6. [Internet Search](#internet-search)
-7. [Remote Sandbox](#remote-sandbox)
-8. [Result Storage](#result-storage)
-9. [Code Registry](#code-registry)
-10. [Best Practices](#best-practices)
-11. [Common Patterns](#common-patterns)
-12. [Troubleshooting](#troubleshooting)
+4. [Custom Profile Tutorial](#custom-profile-tutorial)
+5. [CustomAgent Tutorial](#customagent-tutorial)
+6. [Multi-Agent Workflows](#multi-agent-workflows)
+7. [Internet Search](#internet-search)
+8. [Remote Sandbox](#remote-sandbox)
+9. [Result Storage](#result-storage)
+10. [Code Registry](#code-registry)
+11. [Best Practices](#best-practices)
+12. [Common Patterns](#common-patterns)
+13. [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -26,14 +27,18 @@ Practical guide to building agent systems with JarvisCore.
 ### Step 1: Installation (1 minute)
 
 ```bash
-pip install jarviscore
+pip install jarviscore-framework
 ```
 
 ### Step 2: Configuration (2 minutes)
 
-JarvisCore needs an LLM provider to generate code for AutoAgent. Copy the example config:
+JarvisCore needs an LLM provider to generate code for AutoAgent. Initialize your project:
 
 ```bash
+# Initialize project (creates .env.example and examples)
+python -m jarviscore.cli.scaffold --examples
+
+# Copy and configure your environment
 cp .env.example .env
 ```
 
@@ -80,39 +85,30 @@ 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. Store results in 'result' variable."
+
 async def main():
-    # Create mesh
     mesh = Mesh(mode="autonomous")
-
-    # Add calculator agent
-    mesh.add_agent(
-        AutoAgent,
-        role="calculator",
-        capabilities=["math", "calculation"],
-        system_prompt="You are a math expert"
-    )
-
-    # Start mesh
+    mesh.add(CalculatorAgent)
     await mesh.start()
 
-    # Execute task
-    results = await mesh.run_workflow([
+    results = await mesh.workflow("calc", [
         {"agent": "calculator", "task": "Calculate the factorial of 10"}
     ])
 
     print(results[0]['output'])  # 3628800
-
-    # Cleanup
     await mesh.stop()
 
-if __name__ == '__main__':
-    asyncio.run(main())
+asyncio.run(main())
 ```
 
-**That's it!** No configuration files, no setup, just three steps:
-1. Create mesh
-2. Add agent
-3. Run task
+**That's it!** Three steps:
+1. Define agent class
+2. Add to mesh
+3. Run workflow
 
 ---
 
@@ -123,26 +119,40 @@ if __name__ == '__main__':
 The **Mesh** is your control center. It manages agents and orchestrates workflows.
 
 ```python
-# Autonomous mode (single machine)
+# Autonomous mode (single machine, workflow engine only)
 mesh = Mesh(mode="autonomous")
 
-# Distributed mode (P2P mesh across network)
-mesh = Mesh(mode="distributed")
+# P2P mode (agent-to-agent communication via SWIM/ZMQ)
+mesh = Mesh(mode="p2p", config={'bind_port': 7950})
+
+# Distributed mode (both workflow engine AND P2P networking)
+mesh = Mesh(mode="distributed", config={'bind_port': 7950})
 ```
 
+**Mode Selection:**
+| Mode | Use Case | Components |
+|------|----------|------------|
+| `autonomous` | Single machine, simple pipelines | Workflow Engine |
+| `p2p` | Agent swarms, real-time coordination | P2P Coordinator |
+| `distributed` | Multi-node production systems | Both |
+
 ### Agents
 
-**Agents** are workers that execute tasks. JarvisCore has two agent types:
+**Agents** are workers that execute tasks. JarvisCore offers two profiles:
+
+| Profile | Best For | How It Works |
+|---------|----------|--------------|
+| **AutoAgent** | Rapid prototyping | LLM generates + executes code from prompts |
+| **CustomAgent** | Existing code | You provide `execute_task()` or `run()` |
 
-1. **AutoAgent**: Zero-config, LLM-powered (for rapid prototyping)
-2. **CustomAgent**: Full control (for production systems)
+See [AutoAgent Guide](AUTOAGENT_GUIDE.md) and [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) for details.
 
 ### Workflows
 
 **Workflows** are sequences of tasks with dependencies:
 
 ```python
-await mesh.run_workflow([
+await mesh.workflow("pipeline-id", [
     {"agent": "scraper", "task": "Scrape data"},
     {"agent": "processor", "task": "Clean data", "depends_on": [0]},
     {"agent": "storage", "task": "Save data", "depends_on": [1]}
@@ -153,6 +163,8 @@ await mesh.run_workflow([
 
 ## AutoAgent Tutorial
 
+AutoAgent handles the "prompt → code → result" workflow automatically. See [AutoAgent Guide](AUTOAGENT_GUIDE.md) for distributed mode.
+
 ### Example 1: Simple Calculator
 
 ```python
@@ -160,25 +172,21 @@ import asyncio
 from jarviscore import Mesh
 from jarviscore.profiles import AutoAgent
 
-async def calculator_demo():
-    mesh = Mesh()
-
-    mesh.add_agent(
-        AutoAgent,
-        role="calculator",
-        capabilities=["math", "calculation"],
-        system_prompt="You are a mathematical calculation expert"
-    )
+class CalculatorAgent(AutoAgent):
+    role = "calculator"
+    capabilities = ["math", "calculation"]
+    system_prompt = "You are a mathematical calculation expert. Store results in 'result'."
 
+async def calculator_demo():
+    mesh = Mesh(mode="autonomous")
+    mesh.add(CalculatorAgent)
     await mesh.start()
 
-    # Single calculation
-    result = await mesh.run_workflow([
+    result = await mesh.workflow("calc", [
         {"agent": "calculator", "task": "Calculate 15!"}
     ])
 
     print(f"15! = {result[0]['output']}")
-
     await mesh.stop()
 
 asyncio.run(calculator_demo())
@@ -187,19 +195,17 @@ asyncio.run(calculator_demo())
 ### Example 2: Data Analyst
 
 ```python
-async def data_analyst_demo():
-    mesh = Mesh()
-
-    mesh.add_agent(
-        AutoAgent,
-        role="analyst",
-        capabilities=["data_analysis", "statistics"],
-        system_prompt="You are a data analyst expert"
-    )
+class AnalystAgent(AutoAgent):
+    role = "analyst"
+    capabilities = ["data_analysis", "statistics"]
+    system_prompt = "You are a data analyst expert. Store results in 'result'."
 
+async def data_analyst_demo():
+    mesh = Mesh(mode="autonomous")
+    mesh.add(AnalystAgent)
     await mesh.start()
 
-    result = await mesh.run_workflow([{
+    result = await mesh.workflow("analysis", [{
         "agent": "analyst",
         "task": """
         Given this data: [23, 45, 12, 67, 89, 34, 56, 78, 90, 11]
@@ -208,287 +214,112 @@ async def data_analyst_demo():
     }])
 
     print(result[0]['output'])
-    # {'mean': 50.5, 'median': 50.5, 'std': 28.7, ...}
-
     await mesh.stop()
 
 asyncio.run(data_analyst_demo())
 ```
 
-### Example 3: Text Processor
-
-```python
-async def text_processor_demo():
-    mesh = Mesh()
-
-    mesh.add_agent(
-        AutoAgent,
-        role="processor",
-        capabilities=["text_processing", "nlp"],
-        system_prompt="You are a text processing expert"
-    )
-
-    await mesh.start()
-
-    text = """
-    The quick brown fox jumps over the lazy dog.
-    Python is a popular programming language.
-    """
-
-    result = await mesh.run_workflow([{
-        "agent": "processor",
-        "task": f"""
-        Analyze this text and return:
-        - Word count
-        - Sentence count
-        - Most common word
-        - Text: {text}
-        """
-    }])
+---
 
-    print(result[0]['output'])
+## Custom Profile Tutorial
 
-    await mesh.stop()
+The **Custom Profile** (decorator/wrap approach) is deprecated. Use **CustomAgent** instead.
 
-asyncio.run(text_processor_demo())
-```
+See [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) for:
+- Converting standalone agents to JarvisCore
+- P2P mode for agent-to-agent communication
+- Distributed mode for multi-node systems
 
 ---
 
 ## CustomAgent Tutorial
 
-### Example 1: API Integration
+CustomAgent gives you full control over execution logic. See [CustomAgent Guide](CUSTOMAGENT_GUIDE.md) for P2P and distributed modes.
 
-```python
-from jarviscore.profiles import CustomAgent
-import aiohttp
-
-class WeatherAgent(CustomAgent):
-    """Agent that fetches weather data from external API."""
-
-    async def setup(self):
-        """Initialize API client."""
-        self.api_key = "your-api-key"
-        self.base_url = "https://api.weather.com"
-
-    async def execute_task(self, task):
-        """Execute weather query."""
-        task_desc = task.get('task', '')
-
-        # Extract city from task description
-        city = self._extract_city(task_desc)
-
-        # Fetch weather data
-        async with aiohttp.ClientSession() as session:
-            async with session.get(
-                f"{self.base_url}/weather?city={city}&key={self.api_key}"
-            ) as response:
-                data = await response.json()
-
-        # Track cost (optional)
-        self.track_cost(cost_usd=0.001)
-
-        return {
-            "status": "success",
-            "output": {
-                "city": city,
-                "temperature": data['temp'],
-                "conditions": data['conditions']
-            },
-            "agent": self.agent_id
-        }
-
-    def _extract_city(self, text):
-        """Simple city extraction logic."""
-        # Your parsing logic here
-        return "New York"
-
-# Usage
-async def weather_demo():
-    mesh = Mesh()
-
-    mesh.add_agent(
-        WeatherAgent,
-        role="weather",
-        capabilities=["weather", "api"]
-    )
-
-    await mesh.start()
-
-    result = await mesh.run_workflow([
-        {"agent": "weather", "task": "Get weather for New York"}
-    ])
-
-    print(result[0]['output'])
-
-    await mesh.stop()
-
-asyncio.run(weather_demo())
-```
-
-### Example 2: Database Agent
+### Quick Example
 
 ```python
+from jarviscore import Mesh
 from jarviscore.profiles import CustomAgent
-import asyncpg
 
-class DatabaseAgent(CustomAgent):
-    """Agent that queries PostgreSQL database."""
+class MyAgent(CustomAgent):
+    role = "processor"
+    capabilities = ["data_processing"]
 
     async def setup(self):
-        """Connect to database."""
-        self.pool = await asyncpg.create_pool(
-            host='localhost',
-            database='mydb',
-            user='user',
-            password='password'
-        )
-
-    async def teardown(self):
-        """Close database connection."""
-        await self.pool.close()
+        """Initialize resources (DB connections, API clients, etc.)."""
+        await super().setup()
+        self.data = []
 
     async def execute_task(self, task):
-        """Execute database query."""
-        query = task.get('task', '')
-
-        async with self.pool.acquire() as conn:
-            # Execute query
-            rows = await conn.fetch(query)
+        """Called by workflow engine for each task."""
+        task_desc = task.get("task", "")
+        context = task.get("context", {})  # From depends_on steps
 
-            # Convert to list of dicts
-            results = [dict(row) for row in rows]
+        # Your logic here
+        result = {"processed": task_desc.upper()}
 
         return {
             "status": "success",
-            "output": results,
-            "agent": self.agent_id
+            "output": result,
+            "agent_id": self.agent_id
         }
 
-# Usage
-async def database_demo():
-    mesh = Mesh()
-
-    mesh.add_agent(
-        DatabaseAgent,
-        role="database",
-        capabilities=["database", "query"]
-    )
-
+async def main():
+    mesh = Mesh(mode="autonomous")
+    mesh.add(MyAgent)
     await mesh.start()
 
-    result = await mesh.run_workflow([
-        {"agent": "database", "task": "SELECT * FROM users LIMIT 10"}
+    results = await mesh.workflow("demo", [
+        {"agent": "processor", "task": "hello world"}
     ])
 
-    print(f"Found {len(result[0]['output'])} users")
-
+    print(results[0]["output"])  # {"processed": "HELLO WORLD"}
     await mesh.stop()
-
-asyncio.run(database_demo())
 ```
 
-### Example 3: LangChain Integration
-
-```python
-from jarviscore.profiles import CustomAgent
-from langchain_openai import ChatOpenAI
-from langchain.prompts import ChatPromptTemplate
-from langchain.schema.runnable import RunnableSequence
-
-class LangChainAgent(CustomAgent):
-    """Agent using LangChain for LLM interactions."""
+### Key Methods
 
-    async def setup(self):
-        """Initialize LangChain components."""
-        self.llm = ChatOpenAI(model="gpt-4")
-
-        self.prompt = ChatPromptTemplate.from_messages([
-            ("system", "You are a helpful assistant"),
-            ("user", "{input}")
-        ])
-
-        self.chain = self.prompt | self.llm
-
-    async def execute_task(self, task):
-        """Execute task using LangChain."""
-        task_desc = task.get('task', '')
-
-        # Run LangChain
-        response = await self.chain.ainvoke({"input": task_desc})
-
-        # Track tokens and cost
-        self.track_cost(
-            input_tokens=100,
-            output_tokens=50,
-            cost_usd=0.002
-        )
-
-        return {
-            "status": "success",
-            "output": response.content,
-            "agent": self.agent_id
-        }
-
-# Usage
-async def langchain_demo():
-    mesh = Mesh()
-
-    mesh.add_agent(
-        LangChainAgent,
-        role="assistant",
-        capabilities=["chat", "qa"]
-    )
-
-    await mesh.start()
-
-    result = await mesh.run_workflow([
-        {"agent": "assistant", "task": "Explain quantum computing"}
-    ])
-
-    print(result[0]['output'])
-
-    await mesh.stop()
-
-asyncio.run(langchain_demo())
-```
+| Method | Purpose | Mode |
+|--------|---------|------|
+| `setup()` | Initialize resources | All |
+| `execute_task(task)` | Handle workflow steps | Autonomous/Distributed |
+| `run()` | Continuous loop | P2P |
+| `teardown()` | Cleanup resources | All |
 
 ---
 
 ## Multi-Agent Workflows
 
-### Example 1: Data Pipeline
+### Example: Data Pipeline
 
 ```python
-async def data_pipeline():
-    mesh = Mesh()
-
-    # Add three agents
-    mesh.add_agent(
-        AutoAgent,
-        role="scraper",
-        capabilities=["web_scraping", "data_collection"],
-        system_prompt="You are a web scraping expert"
-    )
+from jarviscore import Mesh
+from jarviscore.profiles import AutoAgent
 
-    mesh.add_agent(
-        AutoAgent,
-        role="processor",
-        capabilities=["data_processing", "cleaning"],
-        system_prompt="You are a data cleaning expert"
-    )
+class ScraperAgent(AutoAgent):
+    role = "scraper"
+    capabilities = ["web_scraping", "data_collection"]
+    system_prompt = "You are a web scraping expert. Store results in 'result'."
 
-    mesh.add_agent(
-        AutoAgent,
-        role="analyzer",
-        capabilities=["analysis", "statistics"],
-        system_prompt="You are a data analysis expert"
-    )
+class ProcessorAgent(AutoAgent):
+    role = "processor"
+    capabilities = ["data_processing", "cleaning"]
+    system_prompt = "You are a data cleaning expert. Store results in 'result'."
+
+class AnalyzerAgent(AutoAgent):
+    role = "analyzer"
+    capabilities = ["analysis", "statistics"]
+    system_prompt = "You are a data analysis expert. Store results in 'result'."
 
+async def data_pipeline():
+    mesh = Mesh(mode="autonomous")
+    mesh.add(ScraperAgent)
+    mesh.add(ProcessorAgent)
+    mesh.add(AnalyzerAgent)
     await mesh.start()
 
-    # Run workflow with dependencies
-    results = await mesh.run_workflow([
+    results = await mesh.workflow("pipeline", [
         {
             "id": "scrape",
             "agent": "scraper",
@@ -508,61 +339,14 @@ async def data_pipeline():
         }
     ])
 
-    # Each step gets context from previous steps
-    print("Scrape result:", results[0]['output'])
-    print("Clean result:", results[1]['output'])
+    print("Scrape:", results[0]['output'])
+    print("Clean:", results[1]['output'])
     print("Analysis:", results[2]['output'])
-
     await mesh.stop()
 
 asyncio.run(data_pipeline())
 ```
 
-### Example 2: Report Generator
-
-```python
-async def report_generator():
-    mesh = Mesh()
-
-    mesh.add_agent(
-        AutoAgent,
-        role="researcher",
-        capabilities=["research", "data_gathering"],
-        system_prompt="You are a researcher",
-        enable_search=True  # Enable internet search
-    )
-
-    mesh.add_agent(
-        AutoAgent,
-        role="writer",
-        capabilities=["writing", "formatting"],
-        system_prompt="You are a technical writer"
-    )
-
-    await mesh.start()
-
-    results = await mesh.run_workflow([
-        {
-            "id": "research",
-            "agent": "researcher",
-            "task": "Research latest Python 3.12 features"
-        },
-        {
-            "id": "write",
-            "agent": "writer",
-            "task": "Write a 2-paragraph summary of the research findings",
-            "depends_on": ["research"]
-        }
-    ])
-
-    print("Research:", results[0]['output'])
-    print("\nReport:", results[1]['output'])
-
-    await mesh.stop()
-
-asyncio.run(report_generator())
-```
-
 ---
 
 ## Internet Search
@@ -573,27 +357,23 @@ Enable web search for research tasks:
 from jarviscore import Mesh
 from jarviscore.profiles import AutoAgent
 
-async def search_demo():
-    mesh = Mesh()
-
-    mesh.add_agent(
-        AutoAgent,
-        role="researcher",
-        capabilities=["research", "web_search"],
-        system_prompt="You are an expert researcher",
-        enable_search=True  # ← Enable internet search
-    )
+class ResearcherAgent(AutoAgent):
+    role = "researcher"
+    capabilities = ["research", "web_search"]
+    system_prompt = "You are an expert researcher. Store results in 'result'."
+    enable_search = True  # ← Enable internet search
 
+async def search_demo():
+    mesh = Mesh(mode="autonomous")
+    mesh.add(ResearcherAgent)
     await mesh.start()
 
-    result = await mesh.run_workflow([{
+    result = await mesh.workflow("search", [{
         "agent": "researcher",
-        "task": "Search for 'Python asyncio best practices' and summarize the top 3 results"
+        "task": "Search for 'Python asyncio best practices' and summarize top 3 results"
     }])
 
     print(result[0]['output'])
-    # Returns: Summary of top 3 search results
-
     await mesh.stop()
 
 asyncio.run(search_demo())
@@ -969,15 +749,16 @@ mesh = Mesh(config=config)
 
 ## Next Steps
 
-1. **Read the [API Reference](API_REFERENCE.md)** for detailed component documentation
-2. **Check the [Configuration Guide](CONFIGURATION.md)** for environment setup
-3. **Explore examples/** directory for more code samples
-4. **Join the community** on GitHub for support
+1. **[AutoAgent Guide](AUTOAGENT_GUIDE.md)** - Multi-node distributed mode
+2. **[CustomAgent Guide](CUSTOMAGENT_GUIDE.md)** - P2P and distributed with your code
+3. **[API Reference](API_REFERENCE.md)** - Detailed component documentation
+4. **[Configuration Guide](CONFIGURATION.md)** - Environment setup
+5. **Explore `examples/`** directory for more code samples
 
 ---
 
 ## Version
 
-User Guide for JarvisCore v0.1.0
+User Guide for JarvisCore v0.2.0
 
-Last Updated: 2026-01-12
+Last Updated: 2026-01-22