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

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
+    )

jarviscore/context/memory.py

@@ -0,0 +1,155 @@
+"""
+MemoryAccessor - Clean API over workflow memory.
+
+Wraps the existing WorkflowEngine.memory dict to provide
+a developer-friendly interface for Custom Profile agents.
+"""
+from typing import Dict, Any, Optional, List
+
+
+class MemoryAccessor:
+    """
+    Provides clean access to workflow memory (shared state between agents).
+
+    This is a facade over the existing WorkflowEngine.memory dict.
+    It extracts 'output' from step results automatically and provides
+    a simple get/put/has/all interface.
+
+    Example:
+        # In agent's run method with ctx: JarvisContext
+        data = ctx.memory.get("step1")
+        ctx.memory.put("intermediate", processed)
+        all_results = ctx.memory.all()
+    """
+
+    def __init__(self, memory: Dict[str, Any], current_step: str = ""):
+        """
+        Initialize memory accessor.
+
+        Args:
+            memory: Reference to WorkflowEngine.memory dict
+            current_step: ID of the current step (for context)
+        """
+        self._memory = memory
+        self._current_step = current_step
+
+    def get(self, step_id: str, default: Any = None) -> Any:
+        """
+        Get output from a specific step.
+
+        Automatically extracts 'output' from step result dicts.
+
+        Args:
+            step_id: Step to get output from
+            default: Default value if not found
+
+        Returns:
+            Step output or default
+
+        Example:
+            data = memory.get("step1")
+            data = memory.get("optional", default=[])
+        """
+        result = self._memory.get(step_id, default)
+
+        # If result is a dict with 'output' key, extract it
+        if isinstance(result, dict) and 'output' in result:
+            return result['output']
+
+        return result
+
+    def get_raw(self, step_id: str, default: Any = None) -> Any:
+        """
+        Get raw result from a step (without extracting 'output').
+
+        Use this when you need the full result dict including
+        status, error, agent_id, etc.
+
+        Args:
+            step_id: Step to get result from
+            default: Default value if not found
+
+        Returns:
+            Full step result dict or default
+        """
+        return self._memory.get(step_id, default)
+
+    def put(self, key: str, value: Any) -> None:
+        """
+        Store a value in memory.
+
+        Use for intermediate results that other steps may need.
+        Note: Step outputs are automatically stored by the engine.
+
+        Args:
+            key: Key to store under
+            value: Value to store
+
+        Example:
+            memory.put("intermediate_result", processed_data)
+        """
+        self._memory[key] = value
+
+    def has(self, step_id: str) -> bool:
+        """
+        Check if a step's output exists in memory.
+
+        Args:
+            step_id: Step to check
+
+        Returns:
+            True if output exists
+
+        Example:
+            if memory.has("optional_step"):
+                data = memory.get("optional_step")
+        """
+        return step_id in self._memory
+
+    def all(self) -> Dict[str, Any]:
+        """
+        Get all memory contents with outputs extracted.
+
+        Returns:
+            Dictionary of step_id -> output
+
+        Example:
+            all_results = memory.all()
+            for step_id, output in all_results.items():
+                print(f"{step_id}: {output}")
+        """
+        result = {}
+        for key, value in self._memory.items():
+            if isinstance(value, dict) and 'output' in value:
+                result[key] = value['output']
+            else:
+                result[key] = value
+        return result
+
+    def keys(self) -> List[str]:
+        """
+        Get all step IDs in memory.
+
+        Returns:
+            List of step IDs
+        """
+        return list(self._memory.keys())
+
+    def __contains__(self, step_id: str) -> bool:
+        """Support 'in' operator: if 'step1' in memory"""
+        return self.has(step_id)
+
+    def __getitem__(self, step_id: str) -> Any:
+        """Support dict-style access: memory['step1']"""
+        return self.get(step_id)
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        """Support dict-style assignment: memory['key'] = value"""
+        self.put(key, value)
+
+    def __len__(self) -> int:
+        """Return number of items in memory."""
+        return len(self._memory)
+
+    def __repr__(self) -> str:
+        return f"<MemoryAccessor keys={self.keys()}>"

jarviscore/data/.env.example

@@ -0,0 +1,146 @@
+# =============================================================================
+# JARVISCORE FRAMEWORK CONFIGURATION
+# =============================================================================
+# Copy this file to .env and fill in your values
+# All settings are optional - framework provides sensible defaults
+# Standard environment variable names (no JARVISCORE_ prefix)
+
+# =============================================================================
+# LLM CONFIGURATION (Zero-Config with Automatic Fallback)
+# =============================================================================
+# Framework tries providers in order: Claude → vLLM → Azure → Gemini
+# At least ONE provider must be configured for AutoAgent to work
+
+# --- Anthropic Claude ---
+# Standard: CLAUDE_API_KEY or ANTHROPIC_API_KEY
+# CLAUDE_API_KEY=your-anthropic-api-key
+# CLAUDE_ENDPOINT=https://api.anthropic.com  # Optional: custom endpoint
+# CLAUDE_MODEL=claude-sonnet-4
+
+# --- vLLM (Local/Self-Hosted) ---
+# Recommended for development and cost-effective production
+# LLM_ENDPOINT=http://localhost:8000
+# LLM_MODEL=Qwen/Qwen2.5-Coder-32B-Instruct
+
+# --- Azure OpenAI ---
+# Standard: AZURE_API_KEY or AZURE_OPENAI_KEY
+# AZURE_API_KEY=your-azure-openai-key
+# AZURE_ENDPOINT=https://your-resource.openai.azure.com
+# AZURE_DEPLOYMENT=gpt-4o
+# AZURE_API_VERSION=2024-02-15-preview
+
+# --- Google Gemini ---
+# GEMINI_API_KEY=your-gemini-api-key
+# GEMINI_MODEL=gemini-1.5-flash
+# GEMINI_TEMPERATURE=0.1
+# GEMINI_TIMEOUT=30.0
+
+# Common LLM Settings
+# LLM_TIMEOUT=120.0
+# LLM_TEMPERATURE=0.7
+
+# =============================================================================
+# EXECUTION SETTINGS
+# =============================================================================
+# Sandbox execution and code generation limits
+
+# Maximum execution time for generated code (seconds)
+EXECUTION_TIMEOUT=300
+
+# Maximum number of autonomous repair attempts
+MAX_REPAIR_ATTEMPTS=3
+
+# Maximum retries for failed operations
+MAX_RETRIES=3
+
+# =============================================================================
+# SANDBOX CONFIGURATION (Phase 2)
+# =============================================================================
+# Sandbox execution mode: "local" (in-process) or "remote" (service)
+# Default: local (for development)
+# Production: remote (uses JarvisCore's Azure Container Apps sandbox)
+SANDBOX_MODE=local
+
+# Remote sandbox service URL (provided by JarvisCore)
+# Azure Container Apps sandbox service - no setup required!
+# Uncomment and set SANDBOX_MODE=remote to use it
+# SANDBOX_SERVICE_URL=https://browser-task-executor.bravesea-3f5f7e75.eastus.azurecontainerapps.io
+
+# =============================================================================
+# STORAGE CONFIGURATION (Phase 1)
+# =============================================================================
+# Directory for result storage and code registry
+LOG_DIRECTORY=./logs
+
+# =============================================================================
+# P2P CONFIGURATION (For Distributed Mode)
+# =============================================================================
+# Required only if using mesh in distributed mode
+# Autonomous mode works without P2P
+
+# Enable P2P mesh networking
+P2P_ENABLED=true
+
+# Node identification
+NODE_NAME=jarviscore-node-1
+
+# Bind address and port for P2P communication
+BIND_HOST=127.0.0.1
+BIND_PORT=7946
+
+# Seed nodes to join existing mesh (comma-separated)
+# Example: 192.168.1.100:7946,192.168.1.101:7946
+# SEED_NODES=
+
+# ZeroMQ port offset (P2P messaging)
+ZMQ_PORT_OFFSET=1000
+
+# Transport type: udp, tcp, or hybrid
+TRANSPORT_TYPE=hybrid
+
+# =============================================================================
+# KEEPALIVE SETTINGS (P2P Health Monitoring)
+# =============================================================================
+
+# Enable smart keepalive (suppresses when active)
+KEEPALIVE_ENABLED=true
+
+# Keepalive interval (seconds)
+KEEPALIVE_INTERVAL=90
+
+# Keepalive timeout (seconds)
+KEEPALIVE_TIMEOUT=10
+
+# Activity suppression window (seconds)
+# If agent is actively working, suppress keepalive for this duration
+ACTIVITY_SUPPRESS_WINDOW=60
+
+# =============================================================================
+# LOGGING
+# =============================================================================
+# Log level: DEBUG, INFO, WARNING, ERROR, CRITICAL
+LOG_LEVEL=INFO
+
+# =============================================================================
+# EXAMPLES
+# =============================================================================
+
+# Example 1: Local development with vLLM
+# LLM_ENDPOINT=http://localhost:8000
+# LLM_MODEL=Qwen/Qwen2.5-Coder-32B-Instruct
+# P2P_ENABLED=false
+
+# Example 2: Production with Azure OpenAI + P2P mesh
+# AZURE_API_KEY=sk-...
+# AZURE_ENDPOINT=https://my-resource.openai.azure.com
+# AZURE_DEPLOYMENT=gpt-4o
+# P2P_ENABLED=true
+# BIND_HOST=0.0.0.0
+# BIND_PORT=7946
+# SEED_NODES=192.168.1.100:7946
+
+# Example 3: Zero-config (use defaults)
+# Just don't set any variables and framework will:
+# - Try to detect available LLM providers
+# - Use sensible defaults for all settings
+# - Work in autonomous mode (no P2P)