janus-labs 0.2.0__py3-none-any.whl

janus_types.py

@@ -0,0 +1,140 @@
+"""
+Stub types for standalone Janus Labs operation.
+
+When running within the AoP monorepo, the full Janus Protocol is available.
+For standalone use, these stubs provide minimal functionality.
+"""
+
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+
+@dataclass
+class TrustScore:
+    """Trust score for an agent session."""
+
+    value: float  # 0.0 to 1.0
+    confidence: float  # 0.0 to 1.0
+
+    @classmethod
+    def default(cls) -> "TrustScore":
+        """Return default trust score."""
+        return cls(value=0.7, confidence=0.5)
+
+
+@dataclass
+class GovernanceState:
+    """Minimal governance state for standalone operation."""
+
+    iteration_count: int = 1
+    halted: bool = False
+    trust_score: Optional[TrustScore] = None
+
+
+def foundation_check(
+    iteration_count: int,
+    same_pattern: bool = False,
+    merge_ready: bool = False,
+    current_approach: Optional[str] = None,
+    approach_history: Optional[List[str]] = None,
+    confidence: Optional[float] = None,
+    confidence_history: Optional[List[float]] = None,
+) -> dict:
+    """
+    Stub foundation check for standalone operation.
+
+    Returns PASS for iterations 1-2, WARN for iteration 3+.
+    Full implementation available in mcp-janus.
+
+    Args:
+        iteration_count: Current iteration number
+        same_pattern: Whether the same approach is being repeated
+        merge_ready: Whether work is ready for merge
+        current_approach: Description of current approach
+        approach_history: List of previous approaches
+        confidence: Current confidence level
+        confidence_history: History of confidence levels
+
+    Returns:
+        dict with result, trigger, signals, and recommendation
+    """
+    _ = merge_ready, current_approach, approach_history, confidence, confidence_history
+
+    if iteration_count >= 3:
+        return {
+            "result": "HALT" if same_pattern else "WARN",
+            "trigger": "iteration",
+            "signals": {"iteration": iteration_count},
+            "recommendation": "Consider decomposing the task",
+        }
+    return {
+        "result": "PASS",
+        "trigger": "none",
+        "signals": {"iteration": iteration_count},
+        "recommendation": "Proceed",
+    }
+
+
+def handle_escalation(result: dict, context: dict) -> dict:
+    """
+    Stub escalation handler - logs but takes no action.
+
+    Args:
+        result: The governance check result
+        context: Additional context for escalation
+
+    Returns:
+        dict with escalation_id and action taken
+    """
+    _ = result, context
+    return {"escalation_id": None, "action": "logged"}
+
+
+def infer_confidence(text: str) -> Tuple[float, str]:
+    """
+    Stub confidence inference - returns moderate confidence.
+
+    Args:
+        text: Text to analyze for confidence signals
+
+    Returns:
+        Tuple of (confidence_value, confidence_label)
+    """
+    _ = text
+    return (0.7, "moderate")
+
+
+# In-memory storage for standalone operation
+_memory_store: dict = {}
+
+
+def read_tier(tier: str, target_dir: str = ".") -> dict:
+    """
+    Stub memory tier reader - uses in-memory storage.
+
+    Args:
+        tier: Memory tier name (e.g., "governance")
+        target_dir: Target directory (ignored in stub)
+
+    Returns:
+        Stored data for the tier, or empty dict
+    """
+    _ = target_dir
+    return _memory_store.get(tier, {})
+
+
+def write_tier(tier: str, data: dict, target_dir: str = ".") -> Tuple[bool, List[str]]:
+    """
+    Stub memory tier writer - uses in-memory storage.
+
+    Args:
+        tier: Memory tier name (e.g., "governance")
+        data: Data to store
+        target_dir: Target directory (ignored in stub)
+
+    Returns:
+        Tuple of (success, error_list)
+    """
+    _ = target_dir
+    _memory_store[tier] = data
+    return (True, [])

probe/__init__.py

@@ -0,0 +1,19 @@
+"""Probe layer - Discovery via Phoenix integration."""
+
+from .mutations import TaskMutation, MutationStrategy, apply_mutation, generate_mutation_suite
+from .explorer import Explorer, ExplorationConfig
+from .tracer import PhoenixTracer, TraceContext
+from .discovery import DiscoveryPack, generate_discovery_pack
+
+__all__ = [
+    "TaskMutation",
+    "MutationStrategy",
+    "apply_mutation",
+    "generate_mutation_suite",
+    "Explorer",
+    "ExplorationConfig",
+    "PhoenixTracer",
+    "TraceContext",
+    "DiscoveryPack",
+    "generate_discovery_pack",
+]

probe/discovery.py

@@ -0,0 +1,194 @@
+"""DiscoveryPack generation for Probe layer."""
+
+from dataclasses import dataclass
+from datetime import datetime
+import hashlib
+import json
+from typing import Optional
+
+from probe.explorer import ExplorationResult, ExplorationRun
+
+
+@dataclass
+class FailureCluster:
+    """A cluster of similar failures."""
+    cluster_id: str
+    proposed_name: str
+    frequency: int
+    severity_hint: str
+    exemplar_run_ids: list[str]
+    common_mutation: Optional[str] = None
+    description: str = ""
+
+
+@dataclass
+class DiscoveryPack:
+    """
+    Complete discovery output from Probe exploration.
+
+    Contains failure clusters, metadata, and exemplar links.
+    """
+    pack_id: str
+    timestamp: str
+    task_explored: str
+    failure_clusters: list[FailureCluster]
+    metadata: dict
+    total_runs: int
+    novel_failures_found: int
+
+
+def _cluster_by_exit_code(runs: list[ExplorationRun]) -> dict[str, list[ExplorationRun]]:
+    """Group runs by exit code."""
+    clusters: dict[str, list[ExplorationRun]] = {}
+    for run in runs:
+        code = run.bundle.get("exit_code", "unknown")
+        if code not in clusters:
+            clusters[code] = []
+        clusters[code].append(run)
+    return clusters
+
+
+def _cluster_by_mutation(runs: list[ExplorationRun]) -> dict[str, list[ExplorationRun]]:
+    """Group runs by mutation strategy."""
+    clusters: dict[str, list[ExplorationRun]] = {}
+    for run in runs:
+        strategy = run.mutation.strategy.value
+        if strategy not in clusters:
+            clusters[strategy] = []
+        clusters[strategy].append(run)
+    return clusters
+
+
+def _calculate_severity(runs: list[ExplorationRun]) -> str:
+    """
+    Calculate severity hint based on failure characteristics.
+
+    - critical: crash or halt
+    - high: failures with tool errors
+    - medium: failures with no output
+    - low: minor issues
+    """
+    for run in runs:
+        if run.bundle.get("exit_code") in ("crash", "halt"):
+            return "critical"
+        if run.error:
+            return "high"
+
+    for run in runs:
+        for trace in run.bundle.get("tool_traces", []):
+            result = str(trace.get("result", ""))
+            if "error" in result.lower():
+                return "high"
+
+    for run in runs:
+        if not run.bundle.get("transcript"):
+            return "medium"
+
+    return "low"
+
+
+def _generate_cluster_id(runs: list[ExplorationRun]) -> str:
+    """Generate deterministic cluster ID."""
+    content = json.dumps([run.run_id for run in runs], sort_keys=True)
+    return hashlib.sha256(content.encode()).hexdigest()[:12]
+
+
+def _propose_cluster_name(
+    runs: list[ExplorationRun],
+    common_mutation: Optional[str],
+) -> str:
+    """Generate a proposed name for the cluster."""
+    if not runs:
+        return "unknown-cluster"
+
+    exit_codes = {run.bundle.get("exit_code") for run in runs}
+
+    if "crash" in exit_codes:
+        return "crash-cluster"
+    if "halt" in exit_codes:
+        return "governance-halt-cluster"
+    if "timeout" in exit_codes:
+        return "timeout-cluster"
+
+    if common_mutation == "tool_removal":
+        return "tool-dependency-failure"
+    if common_mutation == "context_reduce":
+        return "context-sensitivity-failure"
+
+    for run in runs:
+        for trace in run.bundle.get("tool_traces", []):
+            if "error" in str(trace.get("result", "")).lower():
+                return "tool-error-cluster"
+
+    return "unclassified-failure"
+
+
+def generate_discovery_pack(
+    exploration_result: ExplorationResult,
+    task: str,
+) -> DiscoveryPack:
+    """
+    Generate a DiscoveryPack from exploration results.
+
+    Clusters failures by:
+    1. Exit code (crash, halt, timeout, success)
+    2. Mutation strategy that triggered failure
+    3. Error patterns (via simple heuristics)
+
+    In production with Phoenix, this would use embedding-based
+    semantic clustering. For MVP, we use rule-based clustering.
+
+    Args:
+        exploration_result: Result from Explorer.explore()
+        task: Original task explored
+
+    Returns:
+        DiscoveryPack with failure clusters
+    """
+    failed_runs = [run for run in exploration_result.runs if not run.success]
+
+    for run in exploration_result.runs:
+        if run.success:
+            for trace in run.bundle.get("tool_traces", []):
+                if "error" in str(trace.get("result", "")).lower():
+                    if run not in failed_runs:
+                        failed_runs.append(run)
+                    break
+
+    mutation_clusters = _cluster_by_mutation(failed_runs)
+
+    failure_clusters: list[FailureCluster] = []
+    for mutation, runs in mutation_clusters.items():
+        if not runs:
+            continue
+
+        cluster = FailureCluster(
+            cluster_id=_generate_cluster_id(runs),
+            proposed_name=_propose_cluster_name(runs, mutation),
+            frequency=len(runs),
+            severity_hint=_calculate_severity(runs),
+            exemplar_run_ids=[runs[0].run_id],
+            common_mutation=mutation,
+            description=f"Failures triggered by {mutation} mutation",
+        )
+        failure_clusters.append(cluster)
+
+    severity_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+    failure_clusters.sort(key=lambda cluster: severity_order.get(cluster.severity_hint, 4))
+
+    return DiscoveryPack(
+        pack_id=hashlib.sha256(
+            f"{task}-{exploration_result.total_runs}".encode()
+        ).hexdigest()[:12],
+        timestamp=datetime.now().isoformat(),
+        task_explored=task,
+        failure_clusters=failure_clusters,
+        metadata={
+            "total_runs": exploration_result.total_runs,
+            "successful_runs": exploration_result.successful_runs,
+            "failed_runs": exploration_result.failed_runs,
+            "strategies_used": list(exploration_result.mutations_applied.keys()),
+        },
+        total_runs=exploration_result.total_runs,
+        novel_failures_found=len(failure_clusters),
+    )

probe/explorer.py

@@ -0,0 +1,236 @@
+"""Exploration runner for Probe layer."""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+from harness.artifacts import ArtifactCollector
+from harness.executor import init_fixture
+from harness.types import RunArtifactBundle
+from probe.mutations import MutationStrategy, TaskMutation, apply_mutation
+from probe.tracer import PhoenixTracer, TraceContext
+
+
+@dataclass
+class ExplorationConfig:
+    """Configuration for exploration runs."""
+    max_runs: int = 10
+    strategies: list[MutationStrategy] = field(
+        default_factory=lambda: [
+            MutationStrategy.NONE,
+            MutationStrategy.TASK_VARIATION,
+            MutationStrategy.TOOL_REMOVAL,
+        ]
+    )
+    available_tools: list[str] = field(
+        default_factory=lambda: ["read_file", "write_file", "bash"]
+    )
+    seed: Optional[int] = 42
+    timeout_ms: int = 60000
+    fixture_path: Optional[str] = None
+
+
+@dataclass
+class ExplorationRun:
+    """Result of a single exploration run."""
+    run_id: str
+    mutation: TaskMutation
+    bundle: RunArtifactBundle
+    trace_context: TraceContext
+    success: bool
+    error: Optional[str] = None
+
+
+@dataclass
+class ExplorationResult:
+    """Complete exploration result."""
+    config: ExplorationConfig
+    runs: list[ExplorationRun]
+    total_runs: int
+    successful_runs: int
+    failed_runs: int
+    mutations_applied: dict[str, int]
+
+
+class Explorer:
+    """
+    Executes exploration runs with mutations and tracing.
+
+    The Explorer:
+    1. Generates task mutations
+    2. Initializes fixtures
+    3. Simulates agent execution (or calls real agent)
+    4. Collects traces via PhoenixTracer
+    5. Aggregates results
+    """
+
+    def __init__(
+        self,
+        config: ExplorationConfig,
+        tracer: Optional[PhoenixTracer] = None,
+    ):
+        """
+        Initialize explorer.
+
+        Args:
+            config: Exploration configuration
+            tracer: Optional PhoenixTracer (created if not provided)
+        """
+        self.config = config
+        self.tracer = tracer or PhoenixTracer()
+        self.runs: list[ExplorationRun] = []
+
+    def _simulate_agent_execution(
+        self,
+        mutation: TaskMutation,
+        collector: ArtifactCollector,
+    ) -> None:
+        """
+        Simulate agent execution for a mutated task.
+
+        In production, this would invoke the actual agent.
+        For MVP, we simulate with mock tool calls.
+        """
+        collector.record_message("user", mutation.mutated_task)
+        self.tracer.record_message("user", mutation.mutated_task)
+
+        collector.record_message(
+            "assistant",
+            f"I'll work on: {mutation.mutated_task[:100]}..."
+        )
+        self.tracer.record_message(
+            "assistant",
+            f"Processing task with mutation: {mutation.strategy.value}"
+        )
+
+        if mutation.strategy == MutationStrategy.TOOL_REMOVAL:
+            removed = mutation.mutation_details.get("removed_tool", "unknown")
+            collector.record_tool_call(
+                removed,
+                {"action": "attempt"},
+                {"error": "Tool unavailable"},
+                0,
+            )
+            self.tracer.record_tool_call(
+                removed,
+                {"action": "attempt"},
+                {"error": "Tool unavailable"},
+                0,
+            )
+        else:
+            collector.record_tool_call(
+                "read_file",
+                {"path": "main.py"},
+                "def hello(): pass",
+                50,
+            )
+            self.tracer.record_tool_call(
+                "read_file",
+                {"path": "main.py"},
+                "def hello(): pass",
+                50,
+            )
+
+    def run_single(
+        self,
+        task: str,
+        strategy: MutationStrategy,
+        run_index: int = 0,
+    ) -> ExplorationRun:
+        """
+        Execute a single exploration run.
+
+        Args:
+            task: Original task description
+            strategy: Mutation strategy to apply
+            run_index: Index for seed calculation
+
+        Returns:
+            ExplorationRun with results
+        """
+        base_seed = self.config.seed
+        seed = base_seed + run_index if base_seed is not None else None
+
+        mutation = apply_mutation(
+            task,
+            strategy,
+            available_tools=self.config.available_tools,
+            seed=seed,
+        )
+
+        trace_ctx = self.tracer.start_trace(
+            task_description=mutation.mutated_task,
+            mutation=strategy.value,
+        )
+
+        if self.config.fixture_path:
+            init_fixture(self.config.fixture_path)
+
+        collector = ArtifactCollector()
+        error = None
+        success = True
+
+        try:
+            self._simulate_agent_execution(mutation, collector)
+            exit_code = "success"
+        except Exception as exc:
+            error = str(exc)
+            success = False
+            exit_code = "crash"
+
+        self.tracer.end_trace(exit_code)
+        bundle = collector.finalize(exit_code)
+
+        run = ExplorationRun(
+            run_id=trace_ctx.run_id,
+            mutation=mutation,
+            bundle=bundle,
+            trace_context=trace_ctx,
+            success=success,
+            error=error,
+        )
+        self.runs.append(run)
+        return run
+
+    def explore(self, task: str) -> ExplorationResult:
+        """
+        Run full exploration with all configured strategies.
+
+        Args:
+            task: Original task to explore
+
+        Returns:
+            ExplorationResult with all runs
+        """
+        self.runs = []
+        mutations_count: dict[str, int] = {}
+
+        run_index = 0
+        for strategy in self.config.strategies:
+            runs_per_strategy = max(
+                1, self.config.max_runs // len(self.config.strategies)
+            )
+
+            for _ in range(runs_per_strategy):
+                if run_index >= self.config.max_runs:
+                    break
+
+                self.run_single(task, strategy, run_index)
+                run_index += 1
+
+                strategy_name = strategy.value
+                mutations_count[strategy_name] = mutations_count.get(strategy_name, 0) + 1
+
+        successful = sum(1 for run in self.runs if run.success)
+
+        return ExplorationResult(
+            config=self.config,
+            runs=self.runs,
+            total_runs=len(self.runs),
+            successful_runs=successful,
+            failed_runs=len(self.runs) - successful,
+            mutations_applied=mutations_count,
+        )
+
+    def get_traces(self) -> list[dict]:
+        """Export collected traces."""
+        return self.tracer.export_traces()