htmlgraph 0.9.3__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/orchestrator_config.py

@@ -0,0 +1,357 @@
+"""
+Orchestrator Configuration Management
+
+Provides configurable thresholds for delegation enforcement instead of hardcoded values.
+Supports:
+- Threshold configuration (exploration, circuit breaker)
+- Time-based violation decay
+- Rapid sequence collapsing
+- CLI commands to view/edit config
+"""
+
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml  # type: ignore[import-untyped]
+from pydantic import BaseModel
+
+
+class ThresholdsConfig(BaseModel):
+    """Threshold configuration for orchestrator enforcement."""
+
+    exploration_calls: int = 5
+    """How many consecutive Grep/Read/Glob calls before warning."""
+
+    circuit_breaker_violations: int = 3
+    """How many violations before blocking all operations."""
+
+    violation_decay_seconds: int = 120
+    """How old violations can be before they don't count (seconds)."""
+
+    rapid_sequence_window: int = 0
+    """Time window for collapsing rapid violations (seconds). 0 = disabled."""
+
+
+class AntiPatternsConfig(BaseModel):
+    """Anti-pattern detection thresholds."""
+
+    consecutive_bash: int = 5
+    consecutive_edit: int = 4
+    consecutive_grep: int = 4
+    consecutive_read: int = 5
+
+
+class ModeConfig(BaseModel):
+    """Configuration for an enforcement mode."""
+
+    block_after_violations: bool = True
+    require_work_items: bool = True
+    warn_on_patterns: bool = True
+
+
+class ModesConfig(BaseModel):
+    """All enforcement mode configurations."""
+
+    strict: ModeConfig = ModeConfig(
+        block_after_violations=True,
+        require_work_items=True,
+        warn_on_patterns=True,
+    )
+    moderate: ModeConfig = ModeConfig(
+        block_after_violations=False,
+        require_work_items=False,
+        warn_on_patterns=True,
+    )
+    guidance: ModeConfig = ModeConfig(
+        block_after_violations=False,
+        require_work_items=False,
+        warn_on_patterns=False,
+    )
+
+
+class OrchestratorConfig(BaseModel):
+    """Complete orchestrator configuration."""
+
+    thresholds: ThresholdsConfig = ThresholdsConfig()
+    anti_patterns: AntiPatternsConfig = AntiPatternsConfig()
+    modes: ModesConfig = ModesConfig()
+
+
+def get_config_paths() -> list[Path]:
+    """
+    Get list of config file paths to check (in priority order).
+
+    Returns:
+        List of paths to check for config file
+    """
+    return [
+        Path.cwd() / ".htmlgraph" / "orchestrator-config.yaml",
+        Path.home() / ".config" / "htmlgraph" / "orchestrator-config.yaml",
+    ]
+
+
+def load_orchestrator_config() -> OrchestratorConfig:
+    """
+    Load orchestrator configuration from file or use defaults.
+
+    Checks multiple locations:
+    1. .htmlgraph/orchestrator-config.yaml (project-specific)
+    2. ~/.config/htmlgraph/orchestrator-config.yaml (user defaults)
+
+    Returns:
+        OrchestratorConfig with loaded or default values
+    """
+    for config_path in get_config_paths():
+        if config_path.exists():
+            try:
+                with open(config_path) as f:
+                    data = yaml.safe_load(f)
+                    if data:
+                        return OrchestratorConfig(**data)
+            except Exception:
+                # If file is corrupted, continue to next location
+                pass
+
+    # No valid config found, return defaults
+    return OrchestratorConfig()
+
+
+def save_orchestrator_config(
+    config: OrchestratorConfig, path: Path | None = None
+) -> None:
+    """
+    Save orchestrator configuration to file.
+
+    Args:
+        config: Configuration to save
+        path: Optional path to save to. If None, uses first config path.
+    """
+    if path is None:
+        path = get_config_paths()[0]
+
+    # Ensure directory exists
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Convert to dict for YAML serialization
+    data = config.model_dump()
+
+    # Write YAML with comments
+    with open(path, "w") as f:
+        f.write("# HtmlGraph Orchestrator Configuration\n")
+        f.write("# Controls delegation enforcement behavior\n\n")
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+
+def filter_recent_violations(
+    violations: list[dict[str, Any]], decay_seconds: int
+) -> list[dict[str, Any]]:
+    """
+    Filter violations to only include recent ones within decay window.
+
+    Args:
+        violations: List of violation dicts with 'timestamp' field
+        decay_seconds: How old violations can be (in seconds)
+
+    Returns:
+        Filtered list of recent violations only
+    """
+    cutoff = datetime.now(timezone.utc) - timedelta(seconds=decay_seconds)
+
+    recent = []
+    for v in violations:
+        try:
+            # Parse timestamp (handle both ISO format and timestamp float)
+            ts = v.get("timestamp")
+            if isinstance(ts, str):
+                violation_time = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+            elif isinstance(ts, (int, float)):
+                violation_time = datetime.fromtimestamp(ts, tz=timezone.utc)
+            else:
+                continue
+
+            if violation_time > cutoff:
+                recent.append(v)
+        except Exception:
+            # Skip violations with invalid timestamps
+            continue
+
+    return recent
+
+
+def collapse_rapid_sequences(
+    violations: list[dict[str, Any]], window_seconds: int
+) -> list[dict[str, Any]]:
+    """
+    Collapse violations within rapid sequence window to one.
+
+    This prevents "violation spam" when user makes multiple rapid mistakes.
+
+    Args:
+        violations: List of violation dicts with 'timestamp' field
+        window_seconds: Time window for collapsing (seconds)
+
+    Returns:
+        Collapsed list where rapid sequences count as one
+    """
+    if not violations:
+        return []
+
+    collapsed = [violations[0]]
+
+    for v in violations[1:]:
+        try:
+            # Get timestamps
+            last_ts = collapsed[-1].get("timestamp")
+            curr_ts = v.get("timestamp")
+
+            # Parse timestamps
+            if isinstance(last_ts, str):
+                last_time = datetime.fromisoformat(last_ts.replace("Z", "+00:00"))
+            elif isinstance(last_ts, (int, float)):
+                last_time = datetime.fromtimestamp(last_ts, tz=timezone.utc)
+            else:
+                collapsed.append(v)
+                continue
+
+            if isinstance(curr_ts, str):
+                curr_time = datetime.fromisoformat(curr_ts.replace("Z", "+00:00"))
+            elif isinstance(curr_ts, (int, float)):
+                curr_time = datetime.fromtimestamp(curr_ts, tz=timezone.utc)
+            else:
+                collapsed.append(v)
+                continue
+
+            # Only add if outside rapid sequence window
+            if (curr_time - last_time).total_seconds() > window_seconds:
+                collapsed.append(v)
+        except Exception:
+            # On error, include the violation
+            collapsed.append(v)
+
+    return collapsed
+
+
+def get_effective_violation_count(
+    violations: list[dict[str, Any]], config: OrchestratorConfig
+) -> int:
+    """
+    Get effective violation count after applying decay and collapsing.
+
+    Args:
+        violations: Raw list of all violations
+        config: Configuration with thresholds
+
+    Returns:
+        Effective violation count (after decay and collapsing)
+    """
+    # Apply time-based decay
+    recent = filter_recent_violations(
+        violations, config.thresholds.violation_decay_seconds
+    )
+
+    # Collapse rapid sequences
+    collapsed = collapse_rapid_sequences(
+        recent, config.thresholds.rapid_sequence_window
+    )
+
+    return len(collapsed)
+
+
+def get_config_value(config: OrchestratorConfig, key_path: str) -> Any:
+    """
+    Get a config value by dot-separated path.
+
+    Args:
+        config: Configuration object
+        key_path: Dot-separated path (e.g., "thresholds.exploration_calls")
+
+    Returns:
+        Value at that path
+
+    Raises:
+        KeyError: If path doesn't exist
+    """
+    parts = key_path.split(".")
+    value: Any = config
+
+    for part in parts:
+        if hasattr(value, part):
+            value = getattr(value, part)
+        else:
+            raise KeyError(f"Config path not found: {key_path}")
+
+    return value
+
+
+def set_config_value(config: OrchestratorConfig, key_path: str, value: Any) -> None:
+    """
+    Set a config value by dot-separated path.
+
+    Args:
+        config: Configuration object to modify
+        key_path: Dot-separated path (e.g., "thresholds.exploration_calls")
+        value: Value to set
+
+    Raises:
+        KeyError: If path doesn't exist
+    """
+    parts = key_path.split(".")
+    obj: Any = config
+
+    # Navigate to parent object
+    for part in parts[:-1]:
+        if hasattr(obj, part):
+            obj = getattr(obj, part)
+        else:
+            raise KeyError(f"Config path not found: {key_path}")
+
+    # Set the final attribute
+    final_key = parts[-1]
+    if hasattr(obj, final_key):
+        setattr(obj, final_key, value)
+    else:
+        raise KeyError(f"Config path not found: {key_path}")
+
+
+def format_config_display(config: OrchestratorConfig) -> str:
+    """
+    Format configuration for human-readable display.
+
+    Args:
+        config: Configuration to format
+
+    Returns:
+        Formatted string representation
+    """
+    lines = [
+        "HtmlGraph Orchestrator Configuration",
+        "=" * 50,
+        "",
+        "Thresholds:",
+        f"  exploration_calls: {config.thresholds.exploration_calls}",
+        f"  circuit_breaker_violations: {config.thresholds.circuit_breaker_violations}",
+        f"  violation_decay_seconds: {config.thresholds.violation_decay_seconds}",
+        f"  rapid_sequence_window: {config.thresholds.rapid_sequence_window}",
+        "",
+        "Anti-patterns:",
+        f"  consecutive_bash: {config.anti_patterns.consecutive_bash}",
+        f"  consecutive_edit: {config.anti_patterns.consecutive_edit}",
+        f"  consecutive_grep: {config.anti_patterns.consecutive_grep}",
+        f"  consecutive_read: {config.anti_patterns.consecutive_read}",
+        "",
+        "Modes:",
+        "  strict:",
+        f"    block_after_violations: {config.modes.strict.block_after_violations}",
+        f"    require_work_items: {config.modes.strict.require_work_items}",
+        f"    warn_on_patterns: {config.modes.strict.warn_on_patterns}",
+        "  moderate:",
+        f"    block_after_violations: {config.modes.moderate.block_after_violations}",
+        f"    require_work_items: {config.modes.moderate.require_work_items}",
+        f"    warn_on_patterns: {config.modes.moderate.warn_on_patterns}",
+        "  guidance:",
+        f"    block_after_violations: {config.modes.guidance.block_after_violations}",
+        f"    require_work_items: {config.modes.guidance.require_work_items}",
+        f"    warn_on_patterns: {config.modes.guidance.warn_on_patterns}",
+    ]
+    return "\n".join(lines)

htmlgraph/orchestrator_mode.py

@@ -0,0 +1,328 @@
+"""
+Orchestrator Mode State Management
+
+Manages orchestrator mode state for enforcement hooks.
+State is persisted in .htmlgraph/orchestrator-mode.json
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+from htmlgraph.orchestrator_config import (
+    get_effective_violation_count,
+    load_orchestrator_config,
+)
+
+
+class OrchestratorMode(BaseModel):
+    """Orchestrator mode state."""
+
+    enabled: bool = False
+    """Whether orchestrator mode is currently active."""
+
+    activated_at: datetime | None = None
+    """When orchestrator mode was last activated."""
+
+    session_id: str | None = None
+    """Session ID that activated orchestrator mode."""
+
+    enforcement_level: Literal["strict", "guidance"] = "strict"
+    """Enforcement level: 'strict' blocks operations, 'guidance' warns only."""
+
+    auto_activated: bool = False
+    """Whether mode was auto-activated (vs manually activated)."""
+
+    disabled_by_user: bool = False
+    """Whether user explicitly disabled mode (prevents auto-reactivation)."""
+
+    violations: int = 0
+    """Count of delegation violations in current session."""
+
+    last_violation_at: datetime | None = None
+    """Timestamp of most recent violation."""
+
+    circuit_breaker_triggered: bool = False
+    """Whether circuit breaker has been triggered (N+ violations, configurable)."""
+
+    violation_history: list[dict[str, Any]] = []
+    """Full history of violations with timestamps for time-based decay."""
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dict for JSON serialization."""
+        return {
+            "enabled": self.enabled,
+            "activated_at": (
+                self.activated_at.isoformat() if self.activated_at else None
+            ),
+            "session_id": self.session_id,
+            "enforcement_level": self.enforcement_level,
+            "auto_activated": self.auto_activated,
+            "disabled_by_user": self.disabled_by_user,
+            "violations": self.violations,
+            "last_violation_at": (
+                self.last_violation_at.isoformat() if self.last_violation_at else None
+            ),
+            "circuit_breaker_triggered": self.circuit_breaker_triggered,
+            "violation_history": self.violation_history,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "OrchestratorMode":
+        """Create from dict loaded from JSON."""
+        activated_at = data.get("activated_at")
+        if activated_at:
+            # Handle both 'Z' suffix and '+00:00' timezone format
+            if activated_at.endswith("Z"):
+                activated_at = activated_at[:-1] + "+00:00"
+            activated_at = datetime.fromisoformat(activated_at)
+
+        last_violation_at = data.get("last_violation_at")
+        if last_violation_at:
+            # Handle both 'Z' suffix and '+00:00' timezone format
+            if last_violation_at.endswith("Z"):
+                last_violation_at = last_violation_at[:-1] + "+00:00"
+            last_violation_at = datetime.fromisoformat(last_violation_at)
+
+        return cls(
+            enabled=data.get("enabled", False),
+            activated_at=activated_at,
+            session_id=data.get("session_id"),
+            enforcement_level=data.get("enforcement_level", "strict"),
+            auto_activated=data.get("auto_activated", False),
+            disabled_by_user=data.get("disabled_by_user", False),
+            violations=data.get("violations", 0),
+            last_violation_at=last_violation_at,
+            circuit_breaker_triggered=data.get("circuit_breaker_triggered", False),
+            violation_history=data.get("violation_history", []),
+        )
+
+
+class OrchestratorModeManager:
+    """Manages orchestrator mode state with persistence."""
+
+    def __init__(self, graph_dir: Path | str | None = None):
+        """
+        Initialize mode manager.
+
+        Args:
+            graph_dir: Path to .htmlgraph directory. If None, uses current directory's .htmlgraph
+        """
+        if graph_dir is None:
+            graph_dir = Path.cwd() / ".htmlgraph"
+        else:
+            graph_dir = Path(graph_dir)
+
+        self.graph_dir = graph_dir
+        self.state_file = graph_dir / "orchestrator-mode.json"
+
+    def load(self) -> OrchestratorMode:
+        """
+        Load orchestrator mode state from disk.
+
+        Returns:
+            OrchestratorMode with current state, or default (disabled) if file doesn't exist
+        """
+        if not self.state_file.exists():
+            return OrchestratorMode()
+
+        try:
+            data = json.loads(self.state_file.read_text())
+            return OrchestratorMode.from_dict(data)
+        except Exception:
+            # If file is corrupted, return default state
+            return OrchestratorMode()
+
+    def save(self, mode: OrchestratorMode) -> None:
+        """
+        Save orchestrator mode state to disk.
+
+        Args:
+            mode: OrchestratorMode to persist
+        """
+        # Ensure directory exists
+        self.graph_dir.mkdir(parents=True, exist_ok=True)
+
+        # Write state
+        self.state_file.write_text(json.dumps(mode.to_dict(), indent=2))
+
+    def is_enabled(self) -> bool:
+        """Check if orchestrator mode is currently enabled."""
+        mode = self.load()
+        return mode.enabled
+
+    def get_enforcement_level(self) -> Literal["strict", "guidance"]:
+        """Get current enforcement level."""
+        mode = self.load()
+        return mode.enforcement_level
+
+    def enable(
+        self,
+        session_id: str | None = None,
+        level: Literal["strict", "guidance"] = "strict",
+        auto: bool = False,
+    ) -> OrchestratorMode:
+        """
+        Enable orchestrator mode.
+
+        Args:
+            session_id: Session ID enabling the mode
+            level: Enforcement level ('strict' or 'guidance')
+            auto: Whether this is an auto-activation
+
+        Returns:
+            Updated OrchestratorMode
+        """
+        mode = self.load()
+        mode.enabled = True
+        mode.activated_at = datetime.now(timezone.utc)
+        mode.session_id = session_id
+        mode.enforcement_level = level
+        mode.auto_activated = auto
+        mode.disabled_by_user = False
+        self.save(mode)
+        return mode
+
+    def disable(self, by_user: bool = False) -> OrchestratorMode:
+        """
+        Disable orchestrator mode.
+
+        Args:
+            by_user: Whether user explicitly disabled (prevents auto-reactivation)
+
+        Returns:
+            Updated OrchestratorMode
+        """
+        mode = self.load()
+        mode.enabled = False
+        if by_user:
+            mode.disabled_by_user = True
+        self.save(mode)
+        return mode
+
+    def set_level(self, level: Literal["strict", "guidance"]) -> OrchestratorMode:
+        """
+        Change enforcement level without enabling/disabling.
+
+        Args:
+            level: New enforcement level
+
+        Returns:
+            Updated OrchestratorMode
+        """
+        mode = self.load()
+        mode.enforcement_level = level
+        self.save(mode)
+        return mode
+
+    def can_auto_activate(self) -> bool:
+        """
+        Check if auto-activation is allowed.
+
+        Auto-activation is blocked if user explicitly disabled mode.
+
+        Returns:
+            True if auto-activation is allowed
+        """
+        mode = self.load()
+        return not mode.disabled_by_user
+
+    def status(self) -> dict[str, Any]:
+        """
+        Get human-readable status.
+
+        Returns:
+            Dict with status information
+        """
+        mode = self.load()
+        return {
+            "enabled": mode.enabled,
+            "enforcement_level": mode.enforcement_level,
+            "activated_at": (
+                mode.activated_at.strftime("%Y-%m-%d %H:%M:%S")
+                if mode.activated_at
+                else None
+            ),
+            "auto_activated": mode.auto_activated,
+            "disabled_by_user": mode.disabled_by_user,
+            "violations": mode.violations,
+            "circuit_breaker_triggered": mode.circuit_breaker_triggered,
+        }
+
+    def increment_violation(self, tool: str | None = None) -> OrchestratorMode:
+        """
+        Increment violation counter and update timestamp.
+
+        Uses configurable thresholds and time-based decay.
+
+        Args:
+            tool: Optional tool name that caused violation
+
+        Returns:
+            Updated OrchestratorMode with incremented violations
+        """
+        mode = self.load()
+        config = load_orchestrator_config()
+
+        # Add to violation history with timestamp
+        violation = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "tool": tool,
+        }
+        mode.violation_history.append(violation)
+
+        # Calculate effective violation count with decay and collapsing
+        effective_count = get_effective_violation_count(mode.violation_history, config)
+
+        # Update counters
+        mode.violations = effective_count
+        mode.last_violation_at = datetime.now(timezone.utc)
+
+        # Trigger circuit breaker if threshold reached (configurable)
+        threshold = config.thresholds.circuit_breaker_violations
+        if effective_count >= threshold:
+            mode.circuit_breaker_triggered = True
+
+        self.save(mode)
+        return mode
+
+    def reset_violations(self) -> OrchestratorMode:
+        """
+        Reset violation counter and circuit breaker.
+
+        Returns:
+            Updated OrchestratorMode with reset violations
+        """
+        mode = self.load()
+        mode.violations = 0
+        mode.last_violation_at = None
+        mode.circuit_breaker_triggered = False
+        mode.violation_history = []
+        self.save(mode)
+        return mode
+
+    def is_circuit_breaker_triggered(self) -> bool:
+        """
+        Check if circuit breaker is currently triggered.
+
+        Returns:
+            True if circuit breaker is active
+        """
+        mode = self.load()
+        return mode.circuit_breaker_triggered
+
+    def get_violation_count(self) -> int:
+        """
+        Get current violation count (with time-based decay applied).
+
+        Returns:
+            Effective number of violations in current session
+        """
+        mode = self.load()
+        config = load_orchestrator_config()
+
+        # Return effective count with decay and collapsing
+        return get_effective_violation_count(mode.violation_history, config)