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

jarviscore/adapter/decorator.py

@@ -0,0 +1,336 @@
+"""
+@jarvis_agent decorator - Convert any class into a JarvisCore agent.
+
+Wraps existing classes (LangChain, CrewAI, raw Python) to work with
+JarvisCore orchestration without requiring them to inherit from CustomAgent.
+"""
+from typing import List, Optional, Type, 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(cls: Type) -> Optional[str]:
+    """
+    Auto-detect the execute method on a class.
+
+    Checks for common method names in order of preference.
+    Only detects methods defined on the class itself, not inherited
+    from object (like __call__ from type).
+
+    Args:
+        cls: Class to inspect
+
+    Returns:
+        Method name or None if not found
+    """
+    for method_name in EXECUTE_METHODS:
+        # Check if method is defined on the class itself (not inherited from object)
+        # We walk the MRO but stop before 'object'
+        for klass in cls.__mro__:
+            if klass is object:
+                break
+            if method_name in klass.__dict__:
+                attr = getattr(cls, method_name)
+                if callable(attr):
+                    return method_name
+                break
+    return None
+
+
+def jarvis_agent(
+    role: str,
+    capabilities: List[str],
+    execute_method: Optional[str] = None
+):
+    """
+    Decorator to convert any class into a JarvisCore agent.
+
+    The decorated class can use any framework (LangChain, CrewAI, raw Python).
+    JarvisCore provides orchestration (data handoff, dependencies, memory).
+
+    Args:
+        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:
+        Wrapped class that extends CustomAgent
+
+    Example:
+        # Simple agent
+        @jarvis_agent(role="processor", capabilities=["data_processing"])
+        class DataProcessor:
+            def run(self, data):
+                return {"processed": data * 2}
+
+        # Agent with context access
+        @jarvis_agent(role="aggregator", capabilities=["aggregation"])
+        class Aggregator:
+            def run(self, task, ctx: JarvisContext):
+                prev = ctx.previous("step1")
+                return {"result": prev}
+
+        # Agent with custom method name
+        @jarvis_agent(role="researcher", capabilities=["research"], execute_method="invoke")
+        class Researcher:
+            def invoke(self, query):
+                return {"findings": search(query)}
+
+    Usage:
+        mesh = Mesh(mode="autonomous")
+        mesh.add(DataProcessor)
+        await mesh.start()
+        results = await mesh.workflow("pipeline", [...])
+    """
+    def decorator(cls: Type) -> Type:
+        # Detect execute method if not provided
+        method_name = execute_method or detect_execute_method(cls)
+        if not method_name:
+            raise ValueError(
+                f"Could not detect execute method on {cls.__name__}. "
+                f"Please specify execute_method parameter or add one of: {EXECUTE_METHODS}"
+            )
+
+        # Verify method exists
+        if not hasattr(cls, method_name):
+            raise ValueError(
+                f"{cls.__name__} has no method '{method_name}'"
+            )
+
+        # Check if method expects context parameter
+        method = getattr(cls, method_name)
+        sig = inspect.signature(method)
+        params = list(sig.parameters.keys())
+
+        # Remove 'self' from params
+        if params and params[0] == 'self':
+            params = params[1:]
+
+        expects_context = 'ctx' in params or 'context' in params
+
+        logger.debug(
+            f"Wrapping {cls.__name__}: method={method_name}, "
+            f"expects_context={expects_context}, params={params}"
+        )
+
+        # Create wrapped CustomAgent subclass
+        class WrappedAgent(CustomAgent):
+            """Wrapped agent created by @jarvis_agent decorator."""
+
+            # Override class attributes from decorator
+            # (Can't use nonlocal role/capabilities directly due to scoping)
+            pass
+
+        # Set class attributes (must do this after class creation)
+        WrappedAgent.role = role
+        WrappedAgent.capabilities = capabilities
+
+        # Store metadata for introspection
+        WrappedAgent._wrapped_class = cls
+        WrappedAgent._execute_method = method_name
+        WrappedAgent._expects_context = expects_context
+        WrappedAgent._original_params = params
+
+        # Override __init__
+        original_init = WrappedAgent.__init__
+
+        def new_init(self, agent_id=None, **kwargs):
+            # Call CustomAgent init
+            CustomAgent.__init__(self, agent_id)
+
+            # Instantiate the wrapped class
+            try:
+                self._instance = cls(**kwargs) if kwargs else cls()
+            except TypeError:
+                # Class might not accept kwargs
+                self._instance = cls()
+
+            self._logger.debug(f"Created wrapped instance of {cls.__name__}")
+
+        WrappedAgent.__init__ = new_init
+
+        # Override setup
+        async def new_setup(self):
+            await CustomAgent.setup(self)
+
+            # Call wrapped class setup if it exists
+            if hasattr(self._instance, 'setup'):
+                setup_fn = self._instance.setup
+                if inspect.iscoroutinefunction(setup_fn):
+                    await setup_fn()
+                else:
+                    setup_fn()
+
+            self._logger.debug(f"Setup complete for wrapped {cls.__name__}")
+
+        WrappedAgent.setup = new_setup
+
+        # Override execute_task
+        async def new_execute_task(self, task: dict) -> dict:
+            """Execute by calling the wrapped class's method."""
+            # Get the execute method from instance
+            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 based on method signature
+            args = self._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:
+                self._logger.error(f"Error in {cls.__name__}.{method_name}: {e}")
+                return {
+                    'status': 'failure',
+                    'error': str(e),
+                    'agent': self.agent_id
+                }
+
+            # Normalize result to expected format
+            return self._normalize_result(result)
+
+        WrappedAgent.execute_task = new_execute_task
+
+        # Helper to prepare arguments
+        def prepare_args(self, task: dict, ctx: Optional[JarvisContext], param_names: List[str]) -> tuple:
+            """Prepare arguments for the wrapped method."""
+            args = []
+
+            # Get params, handling both dict and non-dict cases
+            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':
+                    # Try to get data from params or context
+                    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'):
+                    # Common input parameter names
+                    if params_is_dict:
+                        args.append(task.get('task', task_params.get(param, '')))
+                    else:
+                        args.append(task.get('task', task_params))
+                else:
+                    # Try to get from params, fall back to task dict
+                    if params_is_dict and param in task_params:
+                        args.append(task_params[param])
+                    elif param in task:
+                        args.append(task[param])
+                    else:
+                        # Pass whole params as fallback
+                        args.append(task_params)
+                        break  # Only do this once
+
+            # If no args were determined, pass the task/params
+            if not args:
+                if 'params' in task:
+                    args.append(task_params)
+                else:
+                    args.append(task)
+
+            return tuple(args)
+
+        WrappedAgent._prepare_args = prepare_args
+
+        # Helper to normalize result
+        def normalize_result(self, result: Any) -> dict:
+            """Normalize result to expected format."""
+            if isinstance(result, dict):
+                if 'status' not in result:
+                    return {
+                        'status': 'success',
+                        'output': result,
+                        'agent': self.agent_id
+                    }
+                if 'agent' not in result:
+                    result['agent'] = self.agent_id
+                return result
+            else:
+                return {
+                    'status': 'success',
+                    'output': result,
+                    'agent': self.agent_id
+                }
+
+        WrappedAgent._normalize_result = normalize_result
+
+        # Override teardown
+        async def new_teardown(self):
+            # Call wrapped class teardown if it exists
+            if hasattr(self._instance, 'teardown'):
+                teardown_fn = self._instance.teardown
+                if inspect.iscoroutinefunction(teardown_fn):
+                    await teardown_fn()
+                else:
+                    teardown_fn()
+
+            await CustomAgent.teardown(self)
+            self._logger.debug(f"Teardown complete for wrapped {cls.__name__}")
+
+        WrappedAgent.teardown = new_teardown
+
+        # Copy class metadata
+        WrappedAgent.__name__ = cls.__name__
+        WrappedAgent.__qualname__ = cls.__qualname__
+        WrappedAgent.__doc__ = cls.__doc__ or f"Wrapped agent from {cls.__name__}"
+        WrappedAgent.__module__ = cls.__module__
+
+        return WrappedAgent
+
+    return decorator

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/check.py

@@ -222,14 +222,17 @@ class HealthChecker:
             return False
 
     async def _test_gemini(self) -> bool:
-        """Test Gemini connectivity."""
+        """Test Gemini connectivity using the new google.genai SDK."""
         try:
-            import google.generativeai as genai
+            from google import genai
 
-            genai.configure(api_key=os.getenv('GEMINI_API_KEY'))
-            model = genai.GenerativeModel(os.getenv('GEMINI_MODEL', 'gemini-1.5-flash'))
+            client = genai.Client(api_key=os.getenv('GEMINI_API_KEY'))
+            model_name = os.getenv('GEMINI_MODEL', 'gemini-2.0-flash')
 
-            response = await model.generate_content_async("Reply with just 'OK'")
+            response = await client.aio.models.generate_content(
+                model=model_name,
+                contents="Reply with just 'OK'"
+            )
             return 'OK' in response.text.upper()
 
         except Exception:
@@ -291,13 +294,15 @@ class HealthChecker:
             print("\n" + "="*70)
             print("  Next Steps")
             print("="*70)
-            print("\n1. Copy .env.example to .env:")
+            print("\n1. Initialize project (creates .env.example and examples):")
+            print("   python -m jarviscore.cli.scaffold --examples")
+            print("\n2. Configure your environment:")
             print("   cp .env.example .env")
-            print("\n2. Add your LLM API key to .env (choose one):")
-            print("   - CLAUDE_API_KEY=sk-ant-...")
-            print("   - AZURE_API_KEY=...")
-            print("   - GEMINI_API_KEY=...")
-            print("   - LLM_ENDPOINT=http://localhost:8000 (for local vLLM)")
+            print("   # Edit .env and add one of:")
+            print("   #   CLAUDE_API_KEY=sk-ant-...")
+            print("   #   AZURE_API_KEY=...")
+            print("   #   GEMINI_API_KEY=...")
+            print("   #   LLM_ENDPOINT=http://localhost:8000 (for local vLLM)")
             print("\n3. Run health check again:")
             print("   python -m jarviscore.cli.check --validate-llm")
             print("\n4. Try the smoke test:")
@@ -309,8 +314,8 @@ class HealthChecker:
         print("\n✓ All checks passed! Ready to use JarvisCore.\n")
         print("Next steps:")
         print("  1. Run smoke test: python -m jarviscore.cli.smoketest")
-        print("  2. Try examples: python examples/calculator_agent_example.py")
-        print("  3. Read guide: docs/GETTING_STARTED.md")
+        print("  2. Get examples:   python -m jarviscore.cli.scaffold --examples")
+        print("  3. Try example:    python examples/calculator_agent_example.py")
         print()
 
         return True