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

jarviscore/__init__.py

@@ -2,52 +2,51 @@
 JarvisCore - P2P Distributed Agent Framework
 
 A production-grade framework for building autonomous agent systems with:
-- Event-sourced state management (crash recovery, HITL support)
 - P2P coordination via SWIM protocol
-- Three execution profiles:
-  * AutoAgent: LLM code generation (3 lines of user code)
-  * CustomAgent: Framework-agnostic (LangChain, MCP, raw Python)
-  * @jarvis_agent: Decorator to wrap existing agents (1 line)
+- Workflow orchestration with dependencies
+- Two agent profiles: AutoAgent (LLM-powered) and CustomAgent (your code)
 
-Quick Start (AutoAgent):
-    from jarviscore import Mesh, AutoAgent
+Profiles:
+    AutoAgent  - LLM generates and executes code from prompts (autonomous mode)
+    CustomAgent - You provide execute_task() or run() (p2p/distributed modes)
 
-    class ScraperAgent(AutoAgent):
-        role = "scraper"
-        capabilities = ["web_scraping"]
-        system_prompt = "You are an expert web scraper..."
+Modes:
+    autonomous  - Workflow engine only (AutoAgent)
+    p2p         - P2P coordinator only (CustomAgent with run() loops)
+    distributed - Both workflow + P2P (CustomAgent with execute_task())
+
+Quick Start (AutoAgent - autonomous mode):
+    from jarviscore import Mesh
+    from jarviscore.profiles import AutoAgent
+
+    class CalcAgent(AutoAgent):
+        role = "calculator"
+        capabilities = ["math"]
+        system_prompt = "You are a math expert. Store result in 'result'."
 
     mesh = Mesh(mode="autonomous")
-    mesh.add(ScraperAgent)
+    mesh.add(CalcAgent)
     await mesh.start()
+    results = await mesh.workflow("calc", [{"agent": "calculator", "task": "Calculate 10!"}])
 
-Quick Start (Custom Profile with decorator):
-    from jarviscore import Mesh, jarvis_agent, JarvisContext
+Quick Start (CustomAgent - distributed mode):
+    from jarviscore import Mesh
+    from jarviscore.profiles import CustomAgent
 
-    @jarvis_agent(role="processor", capabilities=["processing"])
-    class DataProcessor:
-        def run(self, data):
-            return {"processed": data * 2}
+    class MyAgent(CustomAgent):
+        role = "processor"
+        capabilities = ["processing"]
 
-    # With context access
-    @jarvis_agent(role="aggregator", capabilities=["aggregation"])
-    class Aggregator:
-        def run(self, task, ctx: JarvisContext):
-            prev = ctx.previous("step1")
-            return {"result": prev}
+        async def execute_task(self, task):
+            return {"status": "success", "output": task.get("task").upper()}
 
-    mesh = Mesh(mode="autonomous")
-    mesh.add(DataProcessor)
-    mesh.add(Aggregator)
+    mesh = Mesh(mode="distributed", config={'bind_port': 7950})
+    mesh.add(MyAgent)
     await mesh.start()
-
-    results = await mesh.workflow("pipeline", [
-        {"agent": "processor", "task": "Process", "params": {"data": [1,2,3]}},
-        {"agent": "aggregator", "task": "Aggregate", "depends_on": [0]}
-    ])
+    results = await mesh.workflow("demo", [{"agent": "processor", "task": "hello"}])
 """
 
-__version__ = "0.1.1"
+__version__ = "0.2.1"
 __author__ = "JarvisCore Contributors"
 __license__ = "MIT"
 
@@ -60,16 +59,23 @@ from jarviscore.core.mesh import Mesh, MeshMode
 from jarviscore.profiles.autoagent import AutoAgent
 from jarviscore.profiles.customagent import CustomAgent
 
-# Custom Profile: Decorator and Context
-from jarviscore.adapter import jarvis_agent
+# Custom Profile: Decorator, Wrapper, and Context
+from jarviscore.adapter import jarvis_agent, wrap
 from jarviscore.context import JarvisContext, MemoryAccessor, DependencyAccessor
 
+# P2P Direct Communication
+from jarviscore.p2p import PeerClient, PeerTool, PeerInfo, IncomingMessage
+
+# Alias for p2p mode agents
+JarvisAgent = Agent  # Use this for agents with run() loops
+
 __all__ = [
     # Version
     "__version__",
 
     # Core
     "Agent",
+    "JarvisAgent",  # Alias for p2p mode
     "Profile",
     "Mesh",
     "MeshMode",
@@ -78,9 +84,16 @@ __all__ = [
     "AutoAgent",
     "CustomAgent",
 
-    # Custom Profile (decorator approach)
+    # Custom Profile (decorator and wrapper)
     "jarvis_agent",
+    "wrap",
     "JarvisContext",
     "MemoryAccessor",
     "DependencyAccessor",
+
+    # P2P Direct Communication
+    "PeerClient",
+    "PeerTool",
+    "PeerInfo",
+    "IncomingMessage",
 ]

jarviscore/adapter/__init__.py

@@ -3,8 +3,9 @@ Adapter module for JarvisCore Custom Profile.
 
 Provides utilities to wrap existing agents for use with JarvisCore:
 - @jarvis_agent: Decorator to convert any class into a JarvisCore agent
+- wrap(): Function to wrap an existing instance as a JarvisCore agent
 
-Example:
+Example (decorator):
     from jarviscore import jarvis_agent, Mesh, JarvisContext
 
     @jarvis_agent(role="processor", capabilities=["processing"])
@@ -12,23 +13,28 @@ Example:
         def run(self, data):
             return {"processed": data * 2}
 
-    # With context access
-    @jarvis_agent(role="aggregator", capabilities=["aggregation"])
-    class Aggregator:
-        def run(self, task, ctx: JarvisContext):
-            prev = ctx.previous("step1")
-            return {"aggregated": prev}
-
     mesh = Mesh(mode="autonomous")
     mesh.add(DataProcessor)
-    mesh.add(Aggregator)
+    await mesh.start()
+
+Example (wrap function):
+    from jarviscore import wrap, Mesh
+
+    # Wrap an existing instance
+    my_agent = MyLangChainAgent(llm=my_llm)
+    wrapped = wrap(my_agent, role="assistant", capabilities=["chat"])
+
+    mesh = Mesh(mode="autonomous")
+    mesh.add(wrapped)
     await mesh.start()
 """
 
 from .decorator import jarvis_agent, detect_execute_method, EXECUTE_METHODS
+from .wrapper import wrap
 
 __all__ = [
     'jarvis_agent',
+    'wrap',
     'detect_execute_method',
     'EXECUTE_METHODS',
 ]

jarviscore/adapter/decorator.py

@@ -188,27 +188,31 @@ def jarvis_agent(
             # Get the execute method from instance
             method = getattr(self._instance, method_name)
 
-            # Build context if method expects it
+            # Get context if method expects it
             ctx = None
             if expects_context:
-                # Get memory from mesh/workflow engine
-                memory_dict = {}
-                dep_manager = None
-
-                if self._mesh:
-                    engine = getattr(self._mesh, '_workflow_engine', None)
-                    if engine:
-                        memory_dict = engine.memory
-                        dep_manager = getattr(engine, 'dependency_manager', None)
-
-                ctx = create_context(
-                    workflow_id=task.get('context', {}).get('workflow_id', 'unknown'),
-                    step_id=task.get('context', {}).get('step_id', task.get('id', 'unknown')),
-                    task=task.get('task', ''),
-                    params=task.get('params', {}),
-                    memory_dict=memory_dict,
-                    dependency_manager=dep_manager
-                )
+                # Use pre-injected context from WorkflowEngine if available
+                ctx = task.get('_jarvis_context')
+
+                # Fallback: build context manually (for standalone usage)
+                if ctx is None:
+                    memory_dict = {}
+                    dep_manager = None
+
+                    if self._mesh:
+                        engine = getattr(self._mesh, '_workflow_engine', None)
+                        if engine:
+                            memory_dict = engine.memory
+                            dep_manager = getattr(engine, 'dependency_manager', None)
+
+                    ctx = create_context(
+                        workflow_id=task.get('context', {}).get('workflow_id', 'unknown'),
+                        step_id=task.get('context', {}).get('step_id', task.get('id', 'unknown')),
+                        task=task.get('task', ''),
+                        params=task.get('params', {}),
+                        memory_dict=memory_dict,
+                        dependency_manager=dep_manager
+                    )
 
             # Prepare arguments based on method signature
             args = self._prepare_args(task, ctx, params)

jarviscore/adapter/wrapper.py

@@ -0,0 +1,303 @@
+"""
+wrap() function - Wrap an existing instance as a JarvisCore agent.
+
+Alternative to @jarvis_agent decorator when you have an existing instance
+rather than a class definition.
+
+Example:
+    from jarviscore import wrap, Mesh
+
+    # Your existing agent instance
+    my_langchain_agent = LangChainAgent(llm=my_llm)
+
+    # Wrap it for JarvisCore
+    wrapped = wrap(
+        my_langchain_agent,
+        role="researcher",
+        capabilities=["research", "analysis"],
+        execute_method="invoke"
+    )
+
+    mesh = Mesh(mode="autonomous")
+    mesh.add(wrapped)
+    await mesh.start()
+"""
+from typing import List, Optional, Any
+import inspect
+import logging
+
+from jarviscore.profiles.customagent import CustomAgent
+from jarviscore.context import JarvisContext, create_context
+
+logger = logging.getLogger(__name__)
+
+# Common method names to auto-detect
+EXECUTE_METHODS = [
+    "run",           # Most common
+    "invoke",        # LangChain
+    "execute",       # Generic
+    "call",          # Callable pattern
+    "__call__",      # Callable objects
+    "process",       # Processing agents
+    "handle",        # Handler pattern
+]
+
+
+def detect_execute_method(instance: Any) -> Optional[str]:
+    """
+    Auto-detect the execute method on an instance.
+
+    Args:
+        instance: Object instance to inspect
+
+    Returns:
+        Method name or None if not found
+    """
+    for method_name in EXECUTE_METHODS:
+        if hasattr(instance, method_name):
+            attr = getattr(instance, method_name)
+            if callable(attr) and method_name != '__call__':
+                return method_name
+            elif method_name == '__call__':
+                # Check if __call__ is defined on the class itself
+                for klass in type(instance).__mro__:
+                    if klass is object:
+                        break
+                    if '__call__' in klass.__dict__:
+                        return method_name
+    return None
+
+
+def wrap(
+    instance: Any,
+    role: str,
+    capabilities: List[str],
+    execute_method: Optional[str] = None
+) -> CustomAgent:
+    """
+    Wrap an existing instance as a JarvisCore agent.
+
+    Use this when you have an already-instantiated object (like a LangChain
+    agent or custom class instance) that you want to use with JarvisCore.
+
+    Args:
+        instance: The object instance to wrap
+        role: Agent role identifier (used for step routing)
+        capabilities: List of capabilities (used for step matching)
+        execute_method: Method name to call for execution (auto-detected if not provided)
+
+    Returns:
+        A CustomAgent instance wrapping the original object
+
+    Example:
+        # Wrap a LangChain agent
+        from langchain.agents import AgentExecutor
+
+        langchain_agent = AgentExecutor(agent=my_agent, tools=my_tools)
+
+        wrapped = wrap(
+            langchain_agent,
+            role="assistant",
+            capabilities=["chat", "tools"],
+            execute_method="invoke"
+        )
+
+        mesh.add(wrapped)
+
+        # Wrap a simple Python object
+        class MyProcessor:
+            def run(self, data):
+                return {"processed": data * 2}
+
+        processor = MyProcessor()
+        wrapped = wrap(processor, role="processor", capabilities=["processing"])
+
+        # Wrap with context access
+        class MyAggregator:
+            def run(self, task, ctx: JarvisContext):
+                prev = ctx.previous("step1")
+                return {"aggregated": prev}
+
+        aggregator = MyAggregator()
+        wrapped = wrap(aggregator, role="aggregator", capabilities=["aggregation"])
+    """
+    # Detect execute method if not provided
+    method_name = execute_method or detect_execute_method(instance)
+    if not method_name:
+        raise ValueError(
+            f"Could not detect execute method on {type(instance).__name__}. "
+            f"Please specify execute_method parameter or add one of: {EXECUTE_METHODS}"
+        )
+
+    # Verify method exists
+    if not hasattr(instance, method_name):
+        raise ValueError(
+            f"{type(instance).__name__} has no method '{method_name}'"
+        )
+
+    # Check if method expects context parameter
+    method = getattr(instance, method_name)
+    sig = inspect.signature(method)
+    params = list(sig.parameters.keys())
+
+    # Remove 'self' from params (shouldn't be there for bound methods, but just in case)
+    if params and params[0] == 'self':
+        params = params[1:]
+
+    expects_context = 'ctx' in params or 'context' in params
+
+    logger.debug(
+        f"Wrapping instance {type(instance).__name__}: method={method_name}, "
+        f"expects_context={expects_context}, params={params}"
+    )
+
+    # Create a CustomAgent subclass dynamically
+    class WrappedInstanceAgent(CustomAgent):
+        """Agent wrapping an existing instance via wrap()."""
+        pass
+
+    # Set class attributes
+    WrappedInstanceAgent.role = role
+    WrappedInstanceAgent.capabilities = capabilities
+
+    # Store metadata
+    WrappedInstanceAgent._wrapped_instance = instance
+    WrappedInstanceAgent._execute_method = method_name
+    WrappedInstanceAgent._expects_context = expects_context
+    WrappedInstanceAgent._original_params = params
+
+    # Create the agent instance
+    agent = WrappedInstanceAgent.__new__(WrappedInstanceAgent)
+
+    # Initialize CustomAgent parts
+    CustomAgent.__init__(agent)
+
+    # Store the wrapped instance
+    agent._instance = instance
+
+    # Override execute_task
+    async def execute_task(self, task: dict) -> dict:
+        """Execute by calling the wrapped instance's method."""
+        method = getattr(self._instance, method_name)
+
+        # Get context if method expects it
+        ctx = None
+        if expects_context:
+            # Use pre-injected context from WorkflowEngine if available
+            ctx = task.get('_jarvis_context')
+
+            # Fallback: build context manually (for standalone usage)
+            if ctx is None:
+                memory_dict = {}
+                dep_manager = None
+
+                if self._mesh:
+                    engine = getattr(self._mesh, '_workflow_engine', None)
+                    if engine:
+                        memory_dict = engine.memory
+                        dep_manager = getattr(engine, 'dependency_manager', None)
+
+                ctx = create_context(
+                    workflow_id=task.get('context', {}).get('workflow_id', 'unknown'),
+                    step_id=task.get('context', {}).get('step_id', task.get('id', 'unknown')),
+                    task=task.get('task', ''),
+                    params=task.get('params', {}),
+                    memory_dict=memory_dict,
+                    dependency_manager=dep_manager
+                )
+
+        # Prepare arguments
+        args = _prepare_args(task, ctx, params)
+
+        # Call the method
+        try:
+            result = method(*args)
+
+            # Handle async methods
+            if inspect.isawaitable(result):
+                result = await result
+
+        except Exception as e:
+            logger.error(f"Error in {type(instance).__name__}.{method_name}: {e}")
+            return {
+                'status': 'failure',
+                'error': str(e),
+                'agent': self.agent_id
+            }
+
+        # Normalize result
+        return _normalize_result(self, result)
+
+    # Bind the method to the agent
+    import types
+    agent.execute_task = types.MethodType(execute_task, agent)
+
+    # Copy class name for better debugging
+    WrappedInstanceAgent.__name__ = f"Wrapped_{type(instance).__name__}"
+    WrappedInstanceAgent.__qualname__ = f"Wrapped_{type(instance).__name__}"
+
+    logger.debug(f"Created wrapped agent: role={role}, instance={type(instance).__name__}")
+
+    return agent
+
+
+def _prepare_args(task: dict, ctx: Optional[JarvisContext], param_names: List[str]) -> tuple:
+    """Prepare arguments for the wrapped method."""
+    args = []
+
+    task_params = task.get('params', {})
+    params_is_dict = isinstance(task_params, dict)
+
+    for param in param_names:
+        if param in ('ctx', 'context'):
+            args.append(ctx)
+        elif param == 'task':
+            args.append(task.get('task', task))
+        elif param == 'data':
+            if params_is_dict:
+                args.append(task_params.get('data', task_params))
+            else:
+                args.append(task_params)
+        elif param == 'params':
+            args.append(task_params)
+        elif param in ('input', 'query', 'text', 'message'):
+            if params_is_dict:
+                args.append(task.get('task', task_params.get(param, '')))
+            else:
+                args.append(task.get('task', task_params))
+        else:
+            if params_is_dict and param in task_params:
+                args.append(task_params[param])
+            elif param in task:
+                args.append(task[param])
+            else:
+                args.append(task_params)
+                break
+
+    if not args:
+        if 'params' in task:
+            args.append(task_params)
+        else:
+            args.append(task)
+
+    return tuple(args)
+
+
+def _normalize_result(agent: CustomAgent, result: Any) -> dict:
+    """Normalize result to expected format."""
+    if isinstance(result, dict):
+        if 'status' not in result:
+            return {
+                'status': 'success',
+                'output': result,
+                'agent': agent.agent_id
+            }
+        if 'agent' not in result:
+            result['agent'] = agent.agent_id
+        return result
+    else:
+        return {
+            'status': 'success',
+            'output': result,
+            'agent': agent.agent_id
+        }

jarviscore/cli/scaffold.py

@@ -119,7 +119,7 @@ def print_next_steps(env_created: bool, examples_created: bool):
 
     if examples_created:
         steps.append(f"{'4' if env_created else '3'}. Try an example:\n"
-                    "   python examples/calculator_agent_example.py")
+                    "   python examples/calculator_agent_example.py for AutoAgent Profile or python examples/customagent_p2p_example.py ")
 
     for step in steps:
         print(f"\n{step}")

jarviscore/cli/smoketest.py

@@ -311,8 +311,9 @@ class SmokeTest:
 
         print("\n✓ All smoke tests passed!")
         print("\nJarvisCore is working correctly. Next steps:")
-        print("  1. Try examples: python examples/calculator_agent_example.py")
-        print("  2. Read user guide: docs/USER_GUIDE.md")
+        print("  1. Try examples - AutoAgent Profile: python examples/calculator_agent_example.py")
+        print("  2. Try examples - CustomAgent Profile: python examples/customagent_p2p_example.py")
+        print("  3. Read user guide: docs/USER_GUIDE.md")
         print("  3. Build your first agent: docs/GETTING_STARTED.md")
         print()
         return True

jarviscore/core/agent.py

@@ -2,12 +2,18 @@
 Agent base class - defines WHAT an agent does (role, capabilities).
 
 This is the foundation of the JarvisCore framework. All agents inherit from this class.
+
+For p2p mode, agents can implement a run() method for their own execution loop
+and use self.peers for direct peer-to-peer communication.
 """
 from abc import ABC, abstractmethod
-from typing import List, Dict, Any, Optional
+from typing import List, Dict, Any, Optional, TYPE_CHECKING
 from uuid import uuid4
 import logging
 
+if TYPE_CHECKING:
+    from jarviscore.p2p import PeerClient
+
 logger = logging.getLogger(__name__)
 
 
@@ -60,6 +66,10 @@ class Agent(ABC):
         self._mesh = None  # Set by Mesh when agent is added
         self._logger = logging.getLogger(f"jarviscore.agent.{self.agent_id}")
 
+        # P2P mode support
+        self.peers: Optional['PeerClient'] = None  # Injected by Mesh in p2p mode
+        self.shutdown_requested: bool = False  # Set True to stop run() loop
+
         self._logger.debug(f"Agent initialized: {self.agent_id}")
 
     @abstractmethod
@@ -125,6 +135,39 @@ class Agent(ABC):
         """
         self._logger.info(f"Tearing down agent: {self.agent_id}")
 
+    async def run(self):
+        """
+        Optional execution loop for p2p mode agents.
+
+        Override this for agents that run their own execution loops
+        instead of waiting for tasks from the workflow engine.
+
+        The loop should check self.shutdown_requested to know when to stop.
+
+        Example:
+            async def run(self):
+                while not self.shutdown_requested:
+                    # Do agent work
+                    result = await self.do_work()
+
+                    # Notify peer
+                    await self.peers.notify("analyst", {"done": True, "data": result})
+
+                    # Wait before next cycle
+                    await asyncio.sleep(5)
+        """
+        # Default: do nothing (for task-driven agents)
+        pass
+
+    def request_shutdown(self):
+        """
+        Request the agent to stop its run() loop.
+
+        Called by Mesh during shutdown.
+        """
+        self.shutdown_requested = True
+        self._logger.info(f"Shutdown requested for agent: {self.agent_id}")
+
     def can_handle(self, task: Dict[str, Any]) -> bool:
         """
         Check if agent can handle a task based on capabilities.