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

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 AutoAgent Profile or python examples/customagent_p2p_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()

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/context/__init__.py

@@ -0,0 +1,40 @@
+"""
+Context module for JarvisCore Custom Profile.
+
+Provides orchestration primitives for wrapped agents:
+- JarvisContext: Unified context with workflow info and accessors
+- MemoryAccessor: Clean API over workflow memory
+- DependencyAccessor: Clean API over dependency management
+
+These are facades over existing JarvisCore components, providing
+a developer-friendly interface for Custom Profile agents.
+
+Example:
+    from jarviscore.context import JarvisContext
+
+    @jarvis_agent(role="processor", capabilities=["processing"])
+    class Processor:
+        def run(self, task, ctx: JarvisContext):
+            # Access previous step
+            data = ctx.previous("step1")
+
+            # Access memory
+            all_data = ctx.memory.all()
+
+            # Check dependencies
+            if ctx.deps.is_ready("optional"):
+                optional = ctx.previous("optional")
+
+            return {"processed": process(data)}
+"""
+
+from .jarvis_context import JarvisContext, create_context
+from .memory import MemoryAccessor
+from .dependency import DependencyAccessor
+
+__all__ = [
+    'JarvisContext',
+    'create_context',
+    'MemoryAccessor',
+    'DependencyAccessor',
+]

jarviscore/context/dependency.py

@@ -0,0 +1,160 @@
+"""
+DependencyAccessor - Clean API over DependencyManager.
+
+Wraps the existing orchestration.DependencyManager to provide
+a developer-friendly interface for Custom Profile agents.
+"""
+from typing import List, Dict, Any, Tuple, Optional
+
+
+class DependencyAccessor:
+    """
+    Provides clean access to dependency management.
+
+    This is a facade over the existing DependencyManager class.
+    It provides a simpler interface for checking and waiting on dependencies.
+
+    Example:
+        # In agent's run method with ctx: JarvisContext
+        await ctx.deps.wait_for(["step1", "step2"])
+        ready, missing = ctx.deps.check(["step1", "step2"])
+        if ctx.deps.is_ready("optional_step"):
+            ...
+    """
+
+    def __init__(
+        self,
+        dependency_manager: Optional[Any],
+        memory: Dict[str, Any]
+    ):
+        """
+        Initialize dependency accessor.
+
+        Args:
+            dependency_manager: Reference to orchestration.DependencyManager
+            memory: Reference to WorkflowEngine.memory dict
+        """
+        self._manager = dependency_manager
+        self._memory = memory
+
+    async def wait_for(
+        self,
+        step_ids: List[str],
+        timeout: float = 300.0
+    ) -> Dict[str, Any]:
+        """
+        Wait for specific steps to complete.
+
+        Blocks until all specified steps have outputs in memory.
+
+        Args:
+            step_ids: List of step IDs to wait for
+            timeout: Maximum wait time in seconds (default: 5 minutes)
+
+        Returns:
+            Dictionary of step_id -> output
+
+        Raises:
+            TimeoutError: If dependencies not ready within timeout
+
+        Example:
+            results = await deps.wait_for(["step1", "step2"])
+            step1_data = results["step1"]
+        """
+        if self._manager is None:
+            # Fallback: simple check without manager
+            return self._simple_wait(step_ids)
+
+        return await self._manager.wait_for(step_ids, self._memory, timeout)
+
+    def _simple_wait(self, step_ids: List[str]) -> Dict[str, Any]:
+        """
+        Simple synchronous check (used when manager not available).
+
+        Returns outputs for steps that exist in memory.
+        """
+        result = {}
+        for step_id in step_ids:
+            if step_id in self._memory:
+                value = self._memory[step_id]
+                if isinstance(value, dict) and 'output' in value:
+                    result[step_id] = value['output']
+                else:
+                    result[step_id] = value
+        return result
+
+    def check(self, step_ids: List[str]) -> Tuple[bool, List[str]]:
+        """
+        Check if dependencies are satisfied (non-blocking).
+
+        Args:
+            step_ids: Steps to check
+
+        Returns:
+            Tuple of (all_satisfied, missing_step_ids)
+
+        Example:
+            ready, missing = deps.check(["step1", "step2"])
+            if not ready:
+                print(f"Still waiting for: {missing}")
+        """
+        if self._manager is None:
+            # Fallback: simple check without manager
+            missing = [s for s in step_ids if s not in self._memory]
+            return (len(missing) == 0, missing)
+
+        return self._manager.check_dependencies(step_ids, self._memory)
+
+    def is_ready(self, step_id: str) -> bool:
+        """
+        Check if a single step is ready (non-blocking).
+
+        Args:
+            step_id: Step to check
+
+        Returns:
+            True if step output exists in memory
+
+        Example:
+            if deps.is_ready("optional_step"):
+                data = ctx.memory.get("optional_step")
+        """
+        return step_id in self._memory
+
+    def all_ready(self, step_ids: List[str]) -> bool:
+        """
+        Check if all specified steps are ready.
+
+        Args:
+            step_ids: Steps to check
+
+        Returns:
+            True if all steps have outputs in memory
+
+        Example:
+            if deps.all_ready(["step1", "step2", "step3"]):
+                # All dependencies satisfied
+                ...
+        """
+        return all(self.is_ready(s) for s in step_ids)
+
+    def any_ready(self, step_ids: List[str]) -> bool:
+        """
+        Check if any of the specified steps are ready.
+
+        Args:
+            step_ids: Steps to check
+
+        Returns:
+            True if at least one step has output in memory
+
+        Example:
+            if deps.any_ready(["cache_step", "compute_step"]):
+                # At least one source available
+                ...
+        """
+        return any(self.is_ready(s) for s in step_ids)
+
+    def __repr__(self) -> str:
+        ready_count = sum(1 for k in self._memory.keys())
+        return f"<DependencyAccessor ready_steps={ready_count}>"

jarviscore/context/jarvis_context.py

@@ -0,0 +1,207 @@
+"""
+JarvisContext - Unified context for Custom Profile agents.
+
+Provides a single object that gives agents access to:
+- Workflow information (workflow_id, step_id)
+- Task information (task description, params)
+- Memory (shared state between steps)
+- Dependencies (check/wait for other steps)
+
+This is a facade over existing JarvisCore primitives.
+"""
+from dataclasses import dataclass, field
+from typing import Dict, Any, Optional, List
+
+from .memory import MemoryAccessor
+from .dependency import DependencyAccessor
+
+
+@dataclass
+class JarvisContext:
+    """
+    Context passed to wrapped agents during execution.
+
+    Provides unified access to JarvisCore orchestration primitives.
+    Agents receive this as the `ctx` parameter when they declare it
+    in their run method signature.
+
+    Attributes:
+        workflow_id: Unique identifier for the current workflow
+        step_id: Unique identifier for the current step
+        task: Task description string
+        params: Task parameters dictionary
+        memory: Accessor for shared workflow memory
+        deps: Accessor for dependency management
+
+    Example:
+        @jarvis_agent(role="aggregator", capabilities=["aggregation"])
+        class Aggregator:
+            def run(self, task, ctx: JarvisContext):
+                # Access previous step output
+                step1_data = ctx.previous("step1")
+
+                # Access all previous results
+                all_results = ctx.memory.all()
+
+                # Check workflow info
+                print(f"Running step {ctx.step_id} in {ctx.workflow_id}")
+
+                # Use params
+                threshold = ctx.params.get("threshold", 0.5)
+
+                return {"aggregated": process(step1_data)}
+    """
+
+    # Workflow info
+    workflow_id: str
+    step_id: str
+
+    # Task info
+    task: str
+    params: Dict[str, Any] = field(default_factory=dict)
+
+    # Orchestration accessors
+    memory: MemoryAccessor = None
+    deps: DependencyAccessor = None
+
+    def previous(self, step_id: str, default: Any = None) -> Any:
+        """
+        Get output from a previous step.
+
+        Convenience method that delegates to memory.get().
+
+        Args:
+            step_id: ID of the step to get output from
+            default: Default value if not found
+
+        Returns:
+            Step output or default
+
+        Example:
+            step1_result = ctx.previous("step1")
+            optional = ctx.previous("optional_step", default={})
+        """
+        if self.memory is None:
+            return default
+        return self.memory.get(step_id, default)
+
+    def all_previous(self) -> Dict[str, Any]:
+        """
+        Get all previous step outputs.
+
+        Convenience method that delegates to memory.all().
+
+        Returns:
+            Dictionary of step_id -> output
+
+        Example:
+            all_results = ctx.all_previous()
+            for step_id, output in all_results.items():
+                print(f"{step_id} produced: {output}")
+        """
+        if self.memory is None:
+            return {}
+        return self.memory.all()
+
+    @property
+    def previous_results(self) -> Dict[str, Any]:
+        """
+        Alias for all_previous().
+
+        Provides property-style access to all previous results.
+
+        Example:
+            results = ctx.previous_results
+        """
+        return self.all_previous()
+
+    def has_previous(self, step_id: str) -> bool:
+        """
+        Check if a previous step's output exists.
+
+        Args:
+            step_id: Step to check
+
+        Returns:
+            True if output exists
+
+        Example:
+            if ctx.has_previous("optional_step"):
+                data = ctx.previous("optional_step")
+        """
+        if self.memory is None:
+            return False
+        return self.memory.has(step_id)
+
+    def get_param(self, key: str, default: Any = None) -> Any:
+        """
+        Get a task parameter by key.
+
+        Args:
+            key: Parameter key
+            default: Default value if not found
+
+        Returns:
+            Parameter value or default
+
+        Example:
+            threshold = ctx.get_param("threshold", 0.5)
+            mode = ctx.get_param("mode", "default")
+        """
+        return self.params.get(key, default)
+
+    def __repr__(self) -> str:
+        return (
+            f"<JarvisContext "
+            f"workflow={self.workflow_id} "
+            f"step={self.step_id} "
+            f"params={list(self.params.keys())}>"
+        )
+
+
+def create_context(
+    workflow_id: str,
+    step_id: str,
+    task: str,
+    params: Dict[str, Any],
+    memory_dict: Dict[str, Any],
+    dependency_manager: Optional[Any] = None
+) -> JarvisContext:
+    """
+    Factory function to create a JarvisContext.
+
+    Used internally by the decorator and WorkflowEngine to create
+    context objects for agents.
+
+    Args:
+        workflow_id: Workflow identifier
+        step_id: Step identifier
+        task: Task description
+        params: Task parameters
+        memory_dict: Reference to WorkflowEngine.memory
+        dependency_manager: Optional reference to DependencyManager
+
+    Returns:
+        Configured JarvisContext instance
+
+    Example:
+        ctx = create_context(
+            workflow_id="pipeline-1",
+            step_id="step2",
+            task="Process data",
+            params={"threshold": 0.5},
+            memory_dict=engine.memory,
+            dependency_manager=engine.dependency_manager
+        )
+    """
+    memory_accessor = MemoryAccessor(memory_dict, step_id)
+    dep_accessor = DependencyAccessor(dependency_manager, memory_dict)
+
+    return JarvisContext(
+        workflow_id=workflow_id,
+        step_id=step_id,
+        task=task,
+        params=params,
+        memory=memory_accessor,
+        deps=dep_accessor
+    )