htmlgraph 0.23.5__py3-none-any.whl → 0.24.0__py3-none-any.whl

htmlgraph/cigs/posttool_analyzer.py

@@ -0,0 +1,234 @@
+"""
+CIGSPostToolAnalyzer for PostToolUse Hook Integration
+
+Provides cost accounting and reinforcement messages for PostToolUse hook.
+Integrates with ViolationTracker and CostCalculator to analyze actual costs
+and generate appropriate feedback (positive reinforcement or cost accounting).
+
+Design Reference:
+- CIGS Design Doc: .htmlgraph/spikes/computational-imperative-guidance-system-design.md
+- Part 2.4: PostToolUse Hook Enhancement
+"""
+
+from pathlib import Path
+from typing import Any
+
+from htmlgraph.cigs.cost import CostCalculator
+from htmlgraph.cigs.messaging import PositiveReinforcementGenerator
+from htmlgraph.cigs.models import TokenCost
+from htmlgraph.cigs.tracker import ViolationTracker
+
+
+class CIGSPostToolAnalyzer:
+    """
+    Analyze tool execution results and provide cost-aware feedback.
+
+    Integrates with PostToolUse hook to:
+    1. Calculate actual cost using CostCalculator
+    2. Load prediction from ViolationTracker (if violation was recorded)
+    3. Determine if operation was delegation (Task, spawn_*)
+    4. Generate positive reinforcement for delegations
+    5. Generate cost accounting for direct executions
+    6. Update violation tracker with actual costs
+    """
+
+    def __init__(self, graph_dir: Path | None = None):
+        """
+        Initialize CIGSPostToolAnalyzer.
+
+        Args:
+            graph_dir: Root directory for HtmlGraph (defaults to .htmlgraph)
+        """
+        if graph_dir is None:
+            graph_dir = Path.cwd() / ".htmlgraph"
+
+        self.graph_dir = Path(graph_dir)
+        self.cost_calculator = CostCalculator()
+        self.tracker = ViolationTracker(self.graph_dir)
+        self.positive_gen = PositiveReinforcementGenerator()
+
+    def analyze(self, tool: str, params: dict, result: dict) -> dict[str, Any]:
+        """
+        Analyze tool execution and provide feedback.
+
+        Args:
+            tool: Tool that was executed (Read, Task, Edit, etc.)
+            params: Tool parameters
+            result: Tool execution result
+
+        Returns:
+            Hook response dict with feedback:
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PostToolUse",
+                    "additionalContext": "Feedback message"
+                }
+            }
+        """
+        # Calculate actual cost
+        actual_cost = self.cost_calculator.calculate_actual_cost(tool, result)
+
+        # Determine if this was a delegation or direct execution
+        was_delegation = self._is_delegation(tool)
+
+        if was_delegation:
+            return self._positive_reinforcement(tool, actual_cost)
+        else:
+            return self._cost_accounting(tool, actual_cost)
+
+    def _is_delegation(self, tool: str) -> bool:
+        """
+        Check if tool represents delegation.
+
+        Args:
+            tool: Tool name
+
+        Returns:
+            True if tool is a delegation operation
+        """
+        return tool == "Task" or tool.startswith("spawn_")
+
+    def _positive_reinforcement(self, tool: str, cost: TokenCost) -> dict[str, Any]:
+        """
+        Provide positive reinforcement for correct delegation.
+
+        Args:
+            tool: Delegation tool used (Task, spawn_gemini, etc.)
+            cost: Actual token cost breakdown
+
+        Returns:
+            Hook response with positive reinforcement message
+        """
+        # Get current session stats
+        violations = self.tracker.get_session_violations()
+        compliance_rate = self._calculate_compliance_rate(violations.total_violations)
+        session_waste = violations.total_waste_tokens
+
+        # Generate positive message
+        message = self.positive_gen.generate(
+            tool=tool,
+            cost_savings=cost.estimated_savings,
+            compliance_rate=compliance_rate,
+            session_waste=session_waste,
+        )
+
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": message,
+            }
+        }
+
+    def _cost_accounting(self, tool: str, cost: TokenCost) -> dict[str, Any]:
+        """
+        Account for cost of direct execution.
+
+        Args:
+            tool: Tool that was executed directly
+            cost: Actual token cost breakdown
+
+        Returns:
+            Hook response with cost accounting message
+        """
+        # Update violation tracker with actual cost
+        self.tracker.record_actual_cost(tool, cost)
+
+        # Get session violations for context
+        violations = self.tracker.get_session_violations()
+
+        # Check if this was a warned violation (look for recent violation with this tool)
+        has_violation = any(
+            v.tool == tool for v in violations.violations[-3:] if violations.violations
+        )
+
+        if has_violation or violations.total_violations > 0:
+            # This was likely a warned violation - provide cost impact
+            message = self._generate_violation_cost_message(
+                tool, cost, violations.total_violations, violations.total_waste_tokens
+            )
+        else:
+            # Allowed operation - just informational
+            message = f"Operation completed. Cost: {cost.total_tokens} tokens."
+
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PostToolUse",
+                "additionalContext": message,
+            }
+        }
+
+    def _generate_violation_cost_message(
+        self, tool: str, cost: TokenCost, violation_count: int, total_waste: int
+    ) -> str:
+        """
+        Generate cost impact message for violation.
+
+        Args:
+            tool: Tool that was executed
+            cost: Actual token cost
+            violation_count: Total violations in session
+            total_waste: Total wasted tokens in session
+
+        Returns:
+            Formatted cost impact message
+        """
+        # Calculate optimal cost for this tool
+        optimal_cost = cost.subagent_tokens + cost.orchestrator_tokens
+        waste = cost.total_tokens - optimal_cost
+
+        # Calculate compliance rate
+        compliance_rate = self._calculate_compliance_rate(violation_count)
+
+        message_parts = [
+            "📊 Direct execution completed.",
+            "",
+            "**Cost Impact (Violation):**",
+            f"- Actual cost: {cost.total_tokens:,} tokens",
+            f"- If delegated: ~{optimal_cost:,} tokens",
+            f"- Waste: {waste:,} tokens ({(waste / cost.total_tokens * 100):.0f}% overhead)",
+            "",
+            "**Session Statistics:**",
+            f"- Violations: {violation_count}",
+            f"- Total waste: {total_waste:,} tokens",
+            f"- Delegation compliance: {compliance_rate:.0%}",
+            "",
+            "REFLECTION: Was this delegation worth the context cost?",
+            f"The same operation via Task() would have cost ~{optimal_cost:,} tokens",
+            "with full isolation of tactical details.",
+        ]
+
+        return "\n".join(message_parts)
+
+    def _calculate_compliance_rate(self, violation_count: int) -> float:
+        """
+        Calculate delegation compliance rate.
+
+        Args:
+            violation_count: Number of violations
+
+        Returns:
+            Compliance rate from 0.0 to 1.0
+        """
+        # For simplicity: (max_violations - actual) / max_violations
+        # where max_violations = 5 (violation rate saturates)
+        max_violations = 5
+        return max(0.0, 1.0 - (violation_count / max_violations))
+
+    def get_session_summary(self) -> dict[str, Any]:
+        """
+        Get session summary for Stop hook.
+
+        Returns:
+            Summary dict with metrics
+        """
+        violations = self.tracker.get_session_violations()
+
+        return {
+            "total_violations": violations.total_violations,
+            "violations_by_type": {
+                str(k): v for k, v in violations.violations_by_type.items()
+            },
+            "total_waste_tokens": violations.total_waste_tokens,
+            "circuit_breaker_triggered": violations.circuit_breaker_triggered,
+            "compliance_rate": violations.compliance_rate,
+        }

htmlgraph/cigs/tracker.py

@@ -0,0 +1,317 @@
+"""
+ViolationTracker for CIGS (Computational Imperative Guidance System)
+
+Tracks delegation violations in JSONL format, providing thread-safe access
+to violation records and session metrics.
+
+Reference: .htmlgraph/spikes/computational-imperative-guidance-system-design.md (Part 3)
+"""
+
+import json
+import os
+import threading
+from datetime import datetime
+from pathlib import Path
+from uuid import uuid4
+
+from htmlgraph.cigs.models import (
+    OperationClassification,
+    SessionViolationSummary,
+    TokenCost,
+    ViolationRecord,
+    ViolationType,
+)
+
+
+class ViolationTracker:
+    """
+    Thread-safe tracker for delegation violations.
+
+    Stores violations in JSONL format at `.htmlgraph/cigs/violations.jsonl`
+    """
+
+    def __init__(self, graph_dir: Path | None = None):
+        """
+        Initialize ViolationTracker.
+
+        Args:
+            graph_dir: Root directory for HtmlGraph (defaults to .htmlgraph)
+        """
+        if graph_dir is None:
+            graph_dir = Path.cwd() / ".htmlgraph"
+
+        self.graph_dir = Path(graph_dir)
+        self.cigs_dir = self.graph_dir / "cigs"
+        self.violations_file = self.cigs_dir / "violations.jsonl"
+
+        # Create directory if needed
+        self.cigs_dir.mkdir(parents=True, exist_ok=True)
+
+        # Thread-safe access
+        self._lock = threading.RLock()
+
+        # Current session ID (set externally or detect from environment)
+        self._session_id: str | None = self._detect_session_id()
+
+    def _detect_session_id(self) -> str | None:
+        """Detect current session ID from environment or HtmlGraph session manager."""
+        # First check environment variable
+        if "HTMLGRAPH_SESSION_ID" in os.environ:
+            return os.environ["HTMLGRAPH_SESSION_ID"]
+
+        # Try to get from session manager if available
+        try:
+            from htmlgraph.session_manager import SessionManager
+
+            sm = SessionManager(self.graph_dir)
+            current = sm.get_active_session()
+            if current:
+                return str(current.id)
+        except Exception:
+            pass
+
+        return None
+
+    def record_violation(
+        self,
+        tool: str,
+        params: dict,
+        classification: OperationClassification,
+        predicted_waste: int,
+    ) -> str:
+        """
+        Record a violation.
+
+        Args:
+            tool: Tool name (Read, Grep, Edit, etc.)
+            params: Tool parameters passed
+            classification: OperationClassification with context
+            predicted_waste: Predicted wasted tokens
+
+        Returns:
+            Violation ID
+        """
+        with self._lock:
+            violation_id = f"viol-{uuid4().hex[:12]}"
+            timestamp = datetime.utcnow()
+
+            # Get current session
+            session_id = self._session_id or "unknown"
+
+            record = ViolationRecord(
+                id=violation_id,
+                session_id=session_id,
+                timestamp=timestamp,
+                tool=tool,
+                tool_params=params,
+                violation_type=self._classify_violation(tool, classification),
+                context_before=None,
+                should_have_delegated_to=classification.suggested_delegation,
+                actual_cost_tokens=classification.predicted_cost,
+                optimal_cost_tokens=classification.optimal_cost,
+                waste_tokens=predicted_waste,
+                warning_level=1,
+                was_warned=False,
+                warning_ignored=False,
+                agent="claude-code",
+                feature_id=None,
+            )
+
+            # Append to JSONL file
+            self._append_violation(record)
+
+            return violation_id
+
+    def _classify_violation(
+        self, tool: str, classification: OperationClassification
+    ) -> ViolationType:
+        """Classify the violation type based on tool and context."""
+        if classification.is_exploration_sequence:
+            return ViolationType.EXPLORATION_SEQUENCE
+
+        # Map tools to violation types
+        if tool in ("Read", "Grep", "Glob"):
+            return ViolationType.DIRECT_EXPLORATION
+        elif tool in ("Edit", "Write", "NotebookEdit"):
+            return ViolationType.DIRECT_IMPLEMENTATION
+        elif tool == "Bash" and "git" in str(classification.reason).lower():
+            return ViolationType.DIRECT_GIT
+        elif tool == "Bash":
+            return ViolationType.DIRECT_TESTING
+
+        return ViolationType.DIRECT_EXPLORATION
+
+    def _append_violation(self, record: ViolationRecord) -> None:
+        """Append violation record to JSONL file (thread-safe)."""
+        with self._lock:
+            try:
+                with open(self.violations_file, "a") as f:
+                    f.write(json.dumps(record.to_dict()) + "\n")
+            except Exception as e:
+                # Log but don't crash on storage errors
+                print(f"Warning: Failed to record violation: {e}")
+
+    def get_session_violations(
+        self, session_id: str | None = None
+    ) -> SessionViolationSummary:
+        """
+        Get violations for current or specific session.
+
+        Args:
+            session_id: Session ID (defaults to current session)
+
+        Returns:
+            SessionViolationSummary with aggregated metrics
+        """
+        if session_id is None:
+            session_id = self._session_id or "unknown"
+
+        with self._lock:
+            violations = self._load_violations()
+
+        # Filter to session
+        session_violations = [v for v in violations if v.session_id == session_id]
+
+        # Aggregate by type
+        violations_by_type = {}
+        for vtype in ViolationType:
+            count = sum(1 for v in session_violations if v.violation_type == vtype)
+            if count > 0:
+                violations_by_type[vtype] = count
+
+        # Calculate totals
+        total_violations = len(session_violations)
+        total_waste = sum(v.waste_tokens for v in session_violations)
+        circuit_breaker = total_violations >= 3
+
+        # Compliance rate: 1.0 = no violations, 0.0 = many violations
+        # For simplicity: (max_violations - actual) / max_violations
+        # where max_violations = 5 (violation rate saturates)
+        compliance_rate = max(0.0, 1.0 - (total_violations / 5.0))
+
+        return SessionViolationSummary(
+            session_id=session_id,
+            total_violations=total_violations,
+            violations_by_type=violations_by_type,
+            total_waste_tokens=total_waste,
+            circuit_breaker_triggered=circuit_breaker,
+            compliance_rate=compliance_rate,
+            violations=session_violations,
+        )
+
+    def get_recent_violations(self, sessions: int = 5) -> list[ViolationRecord]:
+        """
+        Get violations from last N sessions.
+
+        Args:
+            sessions: Number of sessions to include
+
+        Returns:
+            List of violation records from recent sessions
+        """
+        with self._lock:
+            violations = self._load_violations()
+
+        # Group by session and get N most recent
+        session_ids = set(v.session_id for v in violations)
+        recent_sessions = sorted(session_ids)[-sessions:]
+
+        return [v for v in violations if v.session_id in recent_sessions]
+
+    def record_actual_cost(self, tool: str, cost: TokenCost) -> None:
+        """
+        Update violation with actual cost after execution.
+
+        This updates the most recent violation for the given tool.
+
+        Args:
+            tool: Tool name
+            cost: TokenCost with actual metrics
+        """
+        with self._lock:
+            violations = self._load_violations()
+
+        if not violations:
+            return
+
+        # Find most recent violation for this tool (in current session)
+        session_id = self._session_id or "unknown"
+        matching = [
+            v for v in violations if v.tool == tool and v.session_id == session_id
+        ]
+
+        if not matching:
+            return
+
+        # Update most recent
+        latest = matching[-1]
+        latest.actual_cost_tokens = cost.total_tokens
+        latest.waste_tokens = cost.total_tokens - latest.optimal_cost_tokens
+
+        # Rewrite file (simple approach - replace entire file)
+        self._write_violations(violations)
+
+    def _write_violations(self, violations: list[ViolationRecord]) -> None:
+        """Write violations back to JSONL file."""
+        with self._lock:
+            try:
+                with open(self.violations_file, "w") as f:
+                    for v in violations:
+                        f.write(json.dumps(v.to_dict()) + "\n")
+            except Exception as e:
+                print(f"Warning: Failed to write violations: {e}")
+
+    def _load_violations(self) -> list[ViolationRecord]:
+        """Load all violations from JSONL file."""
+        violations: list[ViolationRecord] = []
+
+        if not self.violations_file.exists():
+            return violations
+
+        try:
+            with open(self.violations_file) as f:
+                for line in f:
+                    if not line.strip():
+                        continue
+                    try:
+                        data = json.loads(line)
+                        violations.append(ViolationRecord.from_dict(data))
+                    except (json.JSONDecodeError, ValueError) as e:
+                        print(f"Warning: Failed to parse violation record: {e}")
+                        continue
+        except Exception as e:
+            print(f"Warning: Failed to load violations: {e}")
+
+        return violations
+
+    def get_session_waste(self) -> int:
+        """
+        Get total wasted tokens for current session.
+
+        Returns:
+            Total waste tokens
+        """
+        summary = self.get_session_violations()
+        return summary.total_waste_tokens
+
+    def set_session_id(self, session_id: str) -> None:
+        """
+        Set the current session ID.
+
+        Args:
+            session_id: Session ID to use for subsequent violations
+        """
+        self._session_id = session_id
+
+    def clear_session_file(self) -> None:
+        """
+        Clear the violations file (useful for testing).
+
+        WARNING: This deletes all violation records!
+        """
+        with self._lock:
+            try:
+                if self.violations_file.exists():
+                    self.violations_file.unlink()
+            except Exception as e:
+                print(f"Warning: Failed to clear violations file: {e}")