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

jarviscore/__init__.py

@@ -4,11 +4,12 @@ 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
-- Two execution profiles:
+- 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)
 
-Quick Start:
+Quick Start (AutoAgent):
     from jarviscore import Mesh, AutoAgent
 
     class ScraperAgent(AutoAgent):
@@ -20,12 +21,33 @@ Quick Start:
     mesh.add(ScraperAgent)
     await mesh.start()
 
-    results = await mesh.workflow("my-workflow", [
-        {"agent": "scraper", "task": "Scrape example.com"}
+Quick Start (Custom Profile with decorator):
+    from jarviscore import Mesh, jarvis_agent, JarvisContext
+
+    @jarvis_agent(role="processor", capabilities=["processing"])
+    class DataProcessor:
+        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 {"result": prev}
+
+    mesh = Mesh(mode="autonomous")
+    mesh.add(DataProcessor)
+    mesh.add(Aggregator)
+    await mesh.start()
+
+    results = await mesh.workflow("pipeline", [
+        {"agent": "processor", "task": "Process", "params": {"data": [1,2,3]}},
+        {"agent": "aggregator", "task": "Aggregate", "depends_on": [0]}
     ])
 """
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 __author__ = "JarvisCore Contributors"
 __license__ = "MIT"
 
@@ -38,6 +60,10 @@ 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
+from jarviscore.context import JarvisContext, MemoryAccessor, DependencyAccessor
+
 __all__ = [
     # Version
     "__version__",
@@ -51,4 +77,10 @@ __all__ = [
     # Profiles
     "AutoAgent",
     "CustomAgent",
+
+    # Custom Profile (decorator approach)
+    "jarvis_agent",
+    "JarvisContext",
+    "MemoryAccessor",
+    "DependencyAccessor",
 ]

jarviscore/adapter/__init__.py

@@ -0,0 +1,34 @@
+"""
+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
+
+Example:
+    from jarviscore import jarvis_agent, Mesh, JarvisContext
+
+    @jarvis_agent(role="processor", capabilities=["processing"])
+    class DataProcessor:
+        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()
+"""
+
+from .decorator import jarvis_agent, detect_execute_method, EXECUTE_METHODS
+
+__all__ = [
+    'jarvis_agent',
+    'detect_execute_method',
+    'EXECUTE_METHODS',
+]

jarviscore/adapter/decorator.py

@@ -0,0 +1,332 @@
+"""
+@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)
+
+            # Build 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
+                )
+
+            # 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/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

jarviscore/cli/scaffold.py

@@ -0,0 +1,178 @@
+"""
+JarvisCore Project Initialization CLI
+
+Scaffolds a new JarvisCore project with configuration and examples.
+
+Usage:
+    python -m jarviscore.cli.scaffold              # Create .env from template
+    python -m jarviscore.cli.scaffold --examples   # Also copy example files
+    python -m jarviscore.cli.scaffold --force      # Overwrite existing files
+"""
+
+import sys
+import shutil
+from pathlib import Path
+from importlib import resources
+import argparse
+
+
+def get_data_path() -> Path:
+    """Get path to the data directory within the package."""
+    # Python 3.9+ approach using importlib.resources
+    try:
+        # resources.files() returns a Traversable, convert to Path
+        data_path = resources.files('jarviscore.data')
+        return Path(str(data_path))
+    except (TypeError, AttributeError):
+        # Fallback for older Python or if resources.files doesn't work
+        import jarviscore.data
+        return Path(jarviscore.data.__file__).parent
+
+
+def copy_env_example(dest_dir: Path, force: bool = False) -> bool:
+    """
+    Copy .env.example to destination directory.
+
+    Args:
+        dest_dir: Destination directory
+        force: Overwrite if exists
+
+    Returns:
+        True if copied, False if skipped
+    """
+    data_path = get_data_path()
+    src = data_path / '.env.example'
+    dest = dest_dir / '.env.example'
+
+    if not src.exists():
+        print(f"✗ Source file not found: {src}")
+        return False
+
+    if dest.exists() and not force:
+        print(f"⚠ {dest.name} already exists (use --force to overwrite)")
+        return False
+
+    shutil.copy2(src, dest)
+    print(f"✓ Created {dest.name}")
+    return True
+
+
+def copy_examples(dest_dir: Path, force: bool = False) -> bool:
+    """
+    Copy example files to destination directory.
+
+    Args:
+        dest_dir: Destination directory
+        force: Overwrite if exists
+
+    Returns:
+        True if copied, False if skipped
+    """
+    data_path = get_data_path()
+    src = data_path / 'examples'
+    dest = dest_dir / 'examples'
+
+    if not src.exists():
+        print(f"✗ Examples directory not found: {src}")
+        return False
+
+    if dest.exists() and not force:
+        print(f"⚠ examples/ directory already exists (use --force to overwrite)")
+        return False
+
+    if dest.exists() and force:
+        shutil.rmtree(dest)
+
+    shutil.copytree(src, dest)
+
+    # Count files copied
+    file_count = sum(1 for _ in dest.glob('*.py'))
+    print(f"✓ Created examples/ directory ({file_count} files)")
+    return True
+
+
+def print_header():
+    """Print initialization header."""
+    print("\n" + "=" * 60)
+    print("  JarvisCore Project Initialization")
+    print("=" * 60 + "\n")
+
+
+def print_next_steps(env_created: bool, examples_created: bool):
+    """Print next steps after initialization."""
+    print("\n" + "=" * 60)
+    print("  Next Steps")
+    print("=" * 60)
+
+    steps = []
+
+    if env_created:
+        steps.append("1. Copy and configure your environment:\n"
+                    "   cp .env.example .env\n"
+                    "   # Edit .env and add your LLM API key")
+
+    steps.append(f"{'2' if env_created else '1'}. Validate your setup:\n"
+                "   python -m jarviscore.cli.check --validate-llm")
+
+    steps.append(f"{'3' if env_created else '2'}. Run smoke test:\n"
+                "   python -m jarviscore.cli.smoketest")
+
+    if examples_created:
+        steps.append(f"{'4' if env_created else '3'}. Try an example:\n"
+                    "   python examples/calculator_agent_example.py")
+
+    for step in steps:
+        print(f"\n{step}")
+
+    print()
+
+
+def main():
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description='Initialize a new JarvisCore project'
+    )
+    parser.add_argument(
+        '--examples',
+        action='store_true',
+        help='Also copy example agent files'
+    )
+    parser.add_argument(
+        '--force',
+        action='store_true',
+        help='Overwrite existing files'
+    )
+    parser.add_argument(
+        '--dir',
+        type=str,
+        default='.',
+        help='Target directory (default: current directory)'
+    )
+
+    args = parser.parse_args()
+    dest_dir = Path(args.dir).resolve()
+
+    print_header()
+    print(f"Initializing in: {dest_dir}\n")
+
+    # Ensure destination exists
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    # Copy files
+    env_created = copy_env_example(dest_dir, args.force)
+
+    examples_created = False
+    if args.examples:
+        examples_created = copy_examples(dest_dir, args.force)
+
+    # Summary
+    if env_created or examples_created:
+        print_next_steps(env_created, examples_created)
+        sys.exit(0)
+    else:
+        print("\n⚠ No files were created. Use --force to overwrite existing files.")
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()