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

htmlgraph/orchestrator.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 SubagentOrchestrator for context-preserving delegation.
 
@@ -83,7 +85,6 @@ Key Patterns
 4. Parallel execution: Multiple subagents can work simultaneously
 """
 
-from __future__ import annotations
 
 from dataclasses import dataclass, field
 from datetime import datetime

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

@@ -8,10 +8,15 @@ State is persisted in .htmlgraph/orchestrator-mode.json
 import json
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Literal
+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."""
@@ -34,7 +39,19 @@ class OrchestratorMode(BaseModel):
     disabled_by_user: bool = False
     """Whether user explicitly disabled mode (prevents auto-reactivation)."""
 
-    def to_dict(self) -> dict:
+    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,
@@ -45,10 +62,16 @@ class OrchestratorMode(BaseModel):
             "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) -> "OrchestratorMode":
+    def from_dict(cls, data: dict[str, Any]) -> "OrchestratorMode":
         """Create from dict loaded from JSON."""
         activated_at = data.get("activated_at")
         if activated_at:
@@ -57,6 +80,13 @@ class OrchestratorMode(BaseModel):
                 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,
@@ -64,6 +94,10 @@ class OrchestratorMode(BaseModel):
             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", []),
         )
 
 
@@ -196,7 +230,7 @@ class OrchestratorModeManager:
         mode = self.load()
         return not mode.disabled_by_user
 
-    def status(self) -> dict:
+    def status(self) -> dict[str, Any]:
         """
         Get human-readable status.
 
@@ -214,4 +248,81 @@ class OrchestratorModeManager:
             ),
             "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)

htmlgraph/parallel.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Parallel workflow execution coordinator for multi-agent task processing.
 
@@ -76,7 +78,6 @@ Best Practices:
     - Limit to 3-5 parallel agents for optimal results
 """
 
-from __future__ import annotations
 
 from dataclasses import dataclass, field
 from datetime import datetime

htmlgraph/parser.py

@@ -80,7 +80,8 @@ class HtmlParser:
 
     def get_article(self) -> Any | None:
         """Get the main article element (graph node root)."""
-        return self.query_one("article[id]")
+        results = self.query("article[id]")
+        return results[0] if results else None
 
     def get_node_id(self) -> str | None:
         """Extract node ID from article element."""
@@ -152,6 +153,17 @@ class HtmlParser:
         if auto_generated:
             metadata["auto_generated"] = auto_generated.lower() == "true"
 
+        # Pattern sequence (for pattern nodes)
+        sequence_attr = self.get_data_attribute(article, "sequence")
+        if sequence_attr:
+            try:
+                import json
+
+                metadata["sequence"] = json.loads(sequence_attr)
+            except (json.JSONDecodeError, ValueError):
+                # Invalid JSON, skip
+                pass
+
         # Timestamps (with fallbacks for session-specific attributes)
         claimed_at = self.get_data_attribute(article, "claimed-at")
         if claimed_at:
@@ -189,13 +201,15 @@ class HtmlParser:
     def get_title(self) -> str | None:
         """Get node title from h1 or title element."""
         # Try h1 in header first
-        h1 = self.query_one("article header h1")
+        h1_results = self.query("article header h1")
+        h1 = h1_results[0] if h1_results else None
         if h1:
             text: str = h1.to_text().strip()
             return text
 
         # Fall back to title element
-        title = self.query_one("title")
+        title_results = self.query("title")
+        title = title_results[0] if title_results else None
         if title:
             text2: str = title.to_text().strip()
             return text2
@@ -214,7 +228,8 @@ class HtmlParser:
         """
         edges: dict[str, list[dict[str, Any]]] = {}
 
-        edge_nav = self.query_one("nav[data-graph-edges]")
+        edge_nav_results = self.query("nav[data-graph-edges]")
+        edge_nav = edge_nav_results[0] if edge_nav_results else None
         if not edge_nav:
             return edges
 
@@ -352,7 +367,10 @@ class HtmlParser:
 
     def get_content(self) -> str:
         """Extract main content from section[data-content]."""
-        content_section = self.query_one("section[data-content]")
+        content_section_results = self.query("section[data-content]")
+        content_section = (
+            content_section_results[0] if content_section_results else None
+        )
         if not content_section:
             return ""
 
@@ -368,6 +386,57 @@ class HtmlParser:
 
         return "\n".join(text_parts)
 
+    def get_findings(self) -> str | None:
+        """Extract findings from section[data-findings] (Spike-specific)."""
+        findings_section_results = self.query("section[data-findings]")
+        findings_section = (
+            findings_section_results[0] if findings_section_results else None
+        )
+        if not findings_section:
+            return None
+
+        # Look for findings-content div using full selector
+        content_div_results = self.query("section[data-findings] div.findings-content")
+        content_div = content_div_results[0] if content_div_results else None
+        if content_div:
+            text = content_div.to_text().strip()
+            return text if text else None
+
+        # Fallback: get all text excluding h3 header
+        text_parts = []
+        for child in findings_section.children:
+            if hasattr(child, "name") and child.name == "h3":
+                continue
+            if hasattr(child, "to_text"):
+                text = child.to_text().strip()
+                if text:
+                    text_parts.append(text)
+
+        result = "\n".join(text_parts)
+        return result if result else None
+
+    def get_decision(self) -> str | None:
+        """Extract decision from section[data-decision] (Spike-specific)."""
+        decision_section_results = self.query("section[data-decision]")
+        decision_section = (
+            decision_section_results[0] if decision_section_results else None
+        )
+        if not decision_section:
+            return None
+
+        # Get text content excluding the h3 header
+        text_parts = []
+        for child in decision_section.children:
+            if hasattr(child, "name") and child.name == "h3":
+                continue
+            if hasattr(child, "to_text"):
+                text = child.to_text().strip()
+                if text:
+                    text_parts.append(text)
+
+        result = "\n".join(text_parts)
+        return result if result else None
+
     def parse_full_node(self) -> dict[str, Any]:
         """
         Parse complete node data from HTML.
@@ -377,7 +446,7 @@ class HtmlParser:
         metadata = self.get_node_metadata()
         title = self.get_title()
 
-        return {
+        result = {
             **metadata,
             "title": title or metadata.get("id", "Untitled"),
             "edges": self.get_edges(),
@@ -386,6 +455,17 @@ class HtmlParser:
             "content": self.get_content(),
         }
 
+        # Add Spike-specific fields if present
+        findings = self.get_findings()
+        if findings is not None:
+            result["findings"] = findings
+
+        decision = self.get_decision()
+        if decision is not None:
+            result["decision"] = decision
+
+        return result
+
 
 def parse_html_file(filepath: Path | str) -> dict[str, Any]:
     """