htmlgraph 0.26.25__py3-none-any.whl → 0.27.0__py3-none-any.whl

htmlgraph/hooks/post_tool_use_failure.py

@@ -1,4 +1,8 @@
 #!/usr/bin/env python3
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 PostToolUseFailure Hook - Automatic Error Tracking and Debug Spike Creation
 
@@ -109,7 +113,7 @@ def run(hook_input: dict[str, Any]) -> dict[str, Any]:
 
     except Exception as e:
         # Never raise - log and continue
-        print(f"PostToolUseFailure hook error: {e}", file=sys.stderr)
+        logger.warning(f"PostToolUseFailure hook error: {e}")
         return {"continue": True}
 
 
@@ -238,10 +242,10 @@ def create_debug_spike(tool: str, error: str, log_path: Path) -> None:
         with open(spike_marker, "w") as f:
             json.dump(existing_spikes, f, indent=2)
 
-        print(f"Created debug spike: {spike.id}", file=sys.stderr)
+        logger.warning(f"Created debug spike: {spike.id}")
 
     except Exception as e:
-        print(f"Failed to create debug spike: {e}", file=sys.stderr)
+        logger.warning(f"Failed to create debug spike: {e}")
 
 
 def main() -> None:

htmlgraph/hooks/posttooluse.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Unified PostToolUse Hook - Parallel Execution of Multiple Tasks
 

htmlgraph/hooks/prompt_analyzer.py

@@ -259,7 +259,7 @@ def get_session_violation_count(context: HookContext) -> tuple[int, int]:
     Example:
         >>> violation_count, waste_tokens = get_session_violation_count(context)
         >>> if violation_count > 0:
-        ...     print(f"Violations this session: {violation_count}")
+        ...     logger.info(f"Violations this session: {violation_count}")
     """
     try:
         from htmlgraph.cigs import ViolationTracker
@@ -289,7 +289,7 @@ def get_active_work_item(context: HookContext) -> dict[str, Any] | None:
     Example:
         >>> active = get_active_work_item(context)
         >>> if active and active['type'] == 'feature':
-        ...     print(f"Active feature: {active['title']}")
+        ...     logger.info(f"Active feature: {active['title']}")
     """
     try:
         from htmlgraph import SDK
@@ -326,7 +326,7 @@ def generate_guidance(
         >>> classification = classify_prompt("Implement new API endpoint")
         >>> guidance = generate_guidance(classification, None, prompt)
         >>> if guidance:
-        ...     print(guidance)
+        ...     logger.info("%s", guidance)
     """
 
     # If continuing and has active work, no guidance needed
@@ -467,7 +467,7 @@ def generate_cigs_guidance(
         >>> cigs = classify_cigs_intent("Search for all error handling")
         >>> guidance = generate_cigs_guidance(cigs, 0, 0)
         >>> if guidance:
-        ...     print(guidance)
+        ...     logger.info("%s", guidance)
     """
     imperatives = []
 
@@ -544,7 +544,7 @@ def create_user_query_event(context: HookContext, prompt: str) -> str | None:
         >>> context = HookContext.from_input(hook_input)
         >>> event_id = create_user_query_event(context, "Implement feature X")
         >>> if event_id:
-        ...     print(f"Created event: {event_id}")
+        ...     logger.info(f"Created event: {event_id}")
     """
     try:
         session_id = context.session_id

htmlgraph/hooks/session_handler.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 HtmlGraph Session Handler Module
 
@@ -24,7 +26,6 @@ Public API:
         Check if HtmlGraph has updates available
 """
 
-from __future__ import annotations
 
 import json
 import logging

htmlgraph/hooks/session_summary.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Session Summary Module - CIGS Integration
 
@@ -353,7 +357,7 @@ class CIGSSessionSummarizer:
             with open(summary_file, "w") as f:
                 json.dump(summary_data, f, indent=2, default=str)
         except Exception as e:
-            print(f"Warning: Failed to persist summary: {e}", file=sys.stderr)
+            logger.warning(f"Warning: Failed to persist summary: {e}")
 
 
 def main() -> None:
@@ -387,5 +391,5 @@ def main() -> None:
         result = summarizer.summarize(session_id)
         print(json.dumps(result))
     except Exception as e:
-        print(f"Warning: Could not generate CIGS summary: {e}", file=sys.stderr)
+        logger.warning(f"Warning: Could not generate CIGS summary: {e}")
         print(json.dumps({"continue": True}))

htmlgraph/hooks/validator.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Work Validation Module for HtmlGraph Hooks
 
@@ -22,9 +26,9 @@ Example:
     result = validate_tool_call("Edit", {"file_path": "test.py"}, config, history)
 
     if result["decision"] == "block":
-        print(result["reason"])
+        logger.debug("Validation reason: %s", result["reason"])
     elif "guidance" in result:
-        print(result["guidance"])
+        logger.debug("Validation guidance: %s", result["guidance"])
 """
 
 import json
@@ -448,9 +452,9 @@ def validate_tool_call(
         history = load_tool_history(session_id)
         result = validate_tool_call("Edit", {"file_path": "test.py"}, config, history)
         if result["decision"] == "block":
-            print(result["reason"])
+            logger.debug("Validation reason: %s", result["reason"])
         elif "guidance" in result:
-            print(result["guidance"])
+            logger.debug("Validation guidance: %s", result["guidance"])
     """
     # Check if this is a subagent context - subagents have unrestricted tool access
     if is_subagent_context():

htmlgraph/ids.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Hash-based ID generation for HtmlGraph.
 
@@ -15,7 +17,6 @@ collision probability is effectively zero even with thousands
 of concurrent agents creating tasks simultaneously.
 """
 
-from __future__ import annotations
 
 import hashlib
 import os

htmlgraph/learning.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Active Learning Persistence Module.
 
@@ -5,7 +7,6 @@ Bridges TranscriptAnalytics to the HtmlGraph for persistent learning.
 Analyzes sessions and persists patterns, insights, and metrics to the graph.
 """
 
-from __future__ import annotations
 
 from collections import Counter
 from datetime import datetime

htmlgraph/mcp_server.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Minimal MCP (Model Context Protocol) server for HtmlGraph.
 
@@ -24,7 +26,6 @@ Example SDK usage:
         f.status = "done"
 """
 
-from __future__ import annotations
 
 import json
 import os

htmlgraph/operations/analytics.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """Analytics operations for HtmlGraph."""
 
-from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path

htmlgraph/operations/bootstrap.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph bootstrap operations.
 
 One-command setup to go from installation to first value in under 60 seconds.
@@ -13,7 +15,6 @@ The bootstrap process includes:
 This is designed for simplicity and speed - the minimal viable setup.
 """
 
-from __future__ import annotations
 
 import json
 import subprocess

htmlgraph/operations/events.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """Event and analytics index operations for HtmlGraph."""
 
-from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path

htmlgraph/operations/fastapi_server.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """FastAPI-based server for HtmlGraph dashboard with real-time observability."""
 
-from __future__ import annotations
 
 import logging
 from dataclasses import dataclass

htmlgraph/operations/hooks.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """Git hook operations for HtmlGraph."""
 
-from __future__ import annotations
 
 import json
 import shutil

htmlgraph/operations/initialization.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph initialization operations.
 
 This module provides functions for initializing the .htmlgraph directory structure,
@@ -13,7 +15,6 @@ The initialization process includes:
 Extracted from monolithic cmd_init() implementation for better maintainability.
 """
 
-from __future__ import annotations
 
 import json
 import sqlite3

htmlgraph/operations/server.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """Server operations for HtmlGraph."""
 
-from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path

htmlgraph/orchestration/claude_launcher.py

@@ -1,11 +1,12 @@
+from __future__ import annotations
+
 """Claude Code launcher with multiple integration modes.
 
 Coordinates launching Claude Code with various HtmlGraph integration options.
 """
 
-from __future__ import annotations
-
 import argparse
+import logging
 import sys
 from pathlib import Path
 
@@ -14,6 +15,8 @@ from htmlgraph.orchestration.plugin_manager import PluginManager
 from htmlgraph.orchestration.prompts import get_orchestrator_prompt
 from htmlgraph.orchestration.subprocess_runner import SubprocessRunner
 
+logger = logging.getLogger(__name__)
+
 
 class ClaudeLauncher:
     """Launch Claude Code with various HtmlGraph integration modes.
@@ -50,7 +53,7 @@ class ClaudeLauncher:
             else:
                 self._launch_default_mode()
         except Exception as e:
-            print(f"Error: Failed to start Claude Code: {e}", file=sys.stderr)
+            logger.warning(f"Error: Failed to start Claude Code: {e}")
             sys.exit(1)
 
     def _launch_orchestrator_mode(self) -> None:
@@ -92,8 +95,8 @@ class ClaudeLauncher:
 
         # Show status
         if self.interactive:
-            print("Resuming last Claude Code session...")
-            print("  ✓ Multi-AI delegation rules injected")
+            logger.info("Resuming last Claude Code session...")
+            logger.info("  ✓ Multi-AI delegation rules injected")
 
         # Build command
         builder = ClaudeCommandBuilder().with_resume().with_system_prompt(prompt)
@@ -102,7 +105,7 @@ class ClaudeLauncher:
         if plugin_dir.exists():
             builder.with_plugin_dir(str(plugin_dir))
             if self.interactive:
-                print(f"  ✓ Loading plugin from: {plugin_dir}")
+                logger.info(f"  ✓ Loading plugin from: {plugin_dir}")
 
         cmd = builder.build()
 
@@ -147,7 +150,7 @@ class ClaudeLauncher:
 
         # Show status
         if self.interactive:
-            print("Starting Claude Code with multi-AI delegation rules...")
+            logger.info("Starting Claude Code with multi-AI delegation rules...")
 
         # Build command
         cmd = ClaudeCommandBuilder().with_system_prompt(prompt).build()
@@ -158,14 +161,14 @@ class ClaudeLauncher:
     def _print_orchestrator_banner(self) -> None:
         """Print orchestrator mode banner."""
         print("=" * 60)
-        print("🤖 HtmlGraph Orchestrator Mode")
+        logger.info("🤖 HtmlGraph Orchestrator Mode")
         print("=" * 60)
-        print("\nStarting Claude Code with orchestrator system prompt...")
-        print("Key directives:")
-        print("  ✓ Delegate to Gemini (FREE), Codex, Copilot first")
-        print("  ✓ Use Task() only as fallback")
-        print("  ✓ Create work items before delegating")
-        print("  ✓ Track all work in .htmlgraph/")
+        logger.info("\nStarting Claude Code with orchestrator system prompt...")
+        logger.info("Key directives:")
+        logger.info("  ✓ Delegate to Gemini (FREE), Codex, Copilot first")
+        logger.info("  ✓ Use Task() only as fallback")
+        logger.info("  ✓ Create work items before delegating")
+        logger.info("  ✓ Track all work in .htmlgraph/")
         print()
 
     def _print_dev_mode_banner(self, plugin_dir: Path) -> None:
@@ -175,11 +178,11 @@ class ClaudeLauncher:
             plugin_dir: Path to local plugin directory
         """
         print("=" * 60)
-        print("🔧 HtmlGraph Development Mode")
+        logger.info("🔧 HtmlGraph Development Mode")
         print("=" * 60)
-        print(f"\nLoading plugin from: {plugin_dir}")
-        print("  ✓ Skills, agents, and hooks will be loaded from local files")
-        print("  ✓ Orchestrator system prompt will be appended")
-        print("  ✓ Multi-AI delegation rules will be injected")
-        print("  ✓ Changes to plugin files will take effect after restart")
+        logger.info(f"\nLoading plugin from: {plugin_dir}")
+        logger.info("  ✓ Skills, agents, and hooks will be loaded from local files")
+        logger.info("  ✓ Orchestrator system prompt will be appended")
+        logger.info("  ✓ Multi-AI delegation rules will be injected")
+        logger.info("  ✓ Changes to plugin files will take effect after restart")
         print()

htmlgraph/orchestration/command_builder.py

@@ -1,9 +1,10 @@
+from __future__ import annotations
+
 """Command builder for Claude Code CLI invocations.
 
 Provides fluent interface for constructing Claude CLI commands.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/orchestration/headless_spawner.py

@@ -1,5 +1,9 @@
 """Headless AI spawner for multi-AI orchestration.
 
+import logging
+
+logger = logging.getLogger(__name__)
+
 This module provides backward compatibility by delegating to modular spawner implementations.
 """
 
@@ -263,8 +267,8 @@ class HeadlessSpawner:
             >>> spawner = HeadlessSpawner()
             >>> result = spawner.spawn_claude("What is 2+2?")
             >>> if result.success:
-            ...     print(result.response)  # "4"
-            ...     print(f"Cost: ${result.raw_output['total_cost_usd']}")
+            ...     logger.info("%s", result.response)  # "4"
+            ...     logger.info(f"Cost: ${result.raw_output['total_cost_usd']}")
         """
         return self._claude_spawner.spawn(
             prompt=prompt,

htmlgraph/orchestration/model_selection.py

@@ -1,5 +1,9 @@
 """Intelligent model selection for task routing.
 
+import logging
+
+logger = logging.getLogger(__name__)
+
 This module provides functionality to select the best AI model for a given task
 based on task type, complexity, and budget constraints.
 
@@ -179,7 +183,7 @@ class ModelSelection:
 
         Example:
             >>> model = ModelSelection.select_model("implementation", "high", "balanced")
-            >>> print(model)
+            >>> logger.info("%s", model)
             'claude-opus'
         """
         # Normalize inputs
@@ -218,7 +222,7 @@ class ModelSelection:
 
         Example:
             >>> fallbacks = ModelSelection.get_fallback_chain("gemini")
-            >>> print(fallbacks)
+            >>> logger.info("%s", fallbacks)
             ['claude-haiku', 'claude-sonnet', 'claude-opus']
         """
         return ModelSelection.FALLBACK_CHAINS.get(primary_model, ["claude-sonnet"])
@@ -305,7 +309,7 @@ def select_model(
 
     Example:
         >>> model = select_model("implementation", "high")
-        >>> print(model)
+        >>> logger.info("%s", model)
     """
     return ModelSelection.select_model(task_type, complexity, budget)
 

htmlgraph/orchestration/plugin_manager.py

@@ -1,15 +1,18 @@
+from __future__ import annotations
+
 """Plugin management for HtmlGraph Claude Code integration.
 
 Centralizes plugin installation, directory management, and validation.
 """
 
-from __future__ import annotations
-
+import logging
 import subprocess
 import sys
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     pass
 
@@ -40,12 +43,12 @@ class PluginManager:
             verbose: Whether to show progress messages
         """
         if verbose:
-            print("\n📦 Installing/upgrading HtmlGraph plugin...\n")
+            logger.info("\n📦 Installing/upgrading HtmlGraph plugin...\n")
 
         # Step 1: Update marketplace
         try:
             if verbose:
-                print("  Updating marketplace...")
+                logger.info("  Updating marketplace...")
             result = subprocess.run(
                 ["claude", "plugin", "marketplace", "update", "htmlgraph"],
                 capture_output=True,
@@ -54,7 +57,7 @@ class PluginManager:
             )
             if result.returncode == 0:
                 if verbose:
-                    print("    ✓ Marketplace updated")
+                    logger.info("    ✓ Marketplace updated")
             else:
                 # Non-blocking errors
                 if (
@@ -62,20 +65,20 @@ class PluginManager:
                     or "no marketplace" in result.stderr.lower()
                 ):
                     if verbose:
-                        print("    ℹ Marketplace not configured (OK, continuing)")
+                        logger.info("    ℹ Marketplace not configured (OK, continuing)")
                 elif verbose:
-                    print(f"    ⚠ Marketplace update: {result.stderr.strip()}")
+                    logger.info(f"    ⚠ Marketplace update: {result.stderr.strip()}")
         except FileNotFoundError:
             if verbose:
-                print("    ⚠ 'claude' command not found")
+                logger.info("    ⚠ 'claude' command not found")
         except Exception as e:
             if verbose:
-                print(f"    ⚠ Error updating marketplace: {e}")
+                logger.info(f"    ⚠ Error updating marketplace: {e}")
 
         # Step 2: Try update, fallback to install
         try:
             if verbose:
-                print("  Updating plugin to latest version...")
+                logger.info("  Updating plugin to latest version...")
             result = subprocess.run(
                 ["claude", "plugin", "update", "htmlgraph"],
                 capture_output=True,
@@ -84,7 +87,7 @@ class PluginManager:
             )
             if result.returncode == 0:
                 if verbose:
-                    print("    ✓ Plugin updated successfully")
+                    logger.info("    ✓ Plugin updated successfully")
             else:
                 # Fallback to install
                 if (
@@ -92,7 +95,7 @@ class PluginManager:
                     or "not found" in result.stderr.lower()
                 ):
                     if verbose:
-                        print("    ℹ Plugin not yet installed, installing...")
+                        logger.info("    ℹ Plugin not yet installed, installing...")
                     install_result = subprocess.run(
                         ["claude", "plugin", "install", "htmlgraph"],
                         capture_output=True,
@@ -101,20 +104,22 @@ class PluginManager:
                     )
                     if install_result.returncode == 0:
                         if verbose:
-                            print("    ✓ Plugin installed successfully")
+                            logger.info("    ✓ Plugin installed successfully")
                     elif verbose:
-                        print(f"    ⚠ Plugin install: {install_result.stderr.strip()}")
+                        logger.info(
+                            f"    ⚠ Plugin install: {install_result.stderr.strip()}"
+                        )
                 elif verbose:
-                    print(f"    ⚠ Plugin update: {result.stderr.strip()}")
+                    logger.info(f"    ⚠ Plugin update: {result.stderr.strip()}")
         except FileNotFoundError:
             if verbose:
-                print("    ⚠ 'claude' command not found")
+                logger.info("    ⚠ 'claude' command not found")
         except Exception as e:
             if verbose:
-                print(f"    ⚠ Error updating plugin: {e}")
+                logger.info(f"    ⚠ Error updating plugin: {e}")
 
         if verbose:
-            print("\n✓ Plugin installation complete\n")
+            logger.info("\n✓ Plugin installation complete\n")
 
     @staticmethod
     def validate_plugin_dir(plugin_dir: Path) -> None:
@@ -127,7 +132,7 @@ class PluginManager:
             SystemExit: If plugin directory doesn't exist
         """
         if not plugin_dir.exists():
-            print(f"Error: Plugin directory not found: {plugin_dir}", file=sys.stderr)
+            logger.warning(f"Error: Plugin directory not found: {plugin_dir}")
             print(
                 "Expected location: packages/claude-plugin/.claude-plugin",
                 file=sys.stderr,

htmlgraph/orchestration/spawners/claude.py

@@ -1,11 +1,14 @@
 """Claude spawner implementation."""
 
 import json
+import logging
 import subprocess
 from typing import TYPE_CHECKING
 
 from .base import AIResult, BaseSpawner
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     pass
 
@@ -64,8 +67,8 @@ class ClaudeSpawner(BaseSpawner):
             >>> spawner = ClaudeSpawner()
             >>> result = spawner.spawn("What is 2+2?")
             >>> if result.success:
-            ...     print(result.response)  # "4"
-            ...     print(f"Cost: ${result.raw_output['total_cost_usd']}")
+            ...     logger.info("%s", result.response)  # "4"
+            ...     logger.info(f"Cost: ${result.raw_output['total_cost_usd']}")
         """
         cmd = ["claude", "-p"]
 

htmlgraph/orchestration/spawners/codex.py

@@ -1,13 +1,15 @@
 """Codex spawner implementation."""
 
 import json
+import logging
 import subprocess
-import sys
 import time
 from typing import TYPE_CHECKING, Any
 
 from .base import AIResult, BaseSpawner
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     from htmlgraph.sdk import SDK
 
@@ -232,15 +234,11 @@ class CodexSpawner(BaseSpawner):
 
             # Record subprocess invocation if tracker is available
             subprocess_event_id = None
-            print(
-                f"DEBUG: tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                file=sys.stderr,
+            logger.warning(
+                f"DEBUG: tracker={tracker is not None}, parent_event_id={parent_event_id}"
             )
             if tracker and parent_event_id:
-                print(
-                    "DEBUG: Recording subprocess invocation for Codex...",
-                    file=sys.stderr,
-                )
+                logger.debug("Recording subprocess invocation for Codex...")
                 try:
                     subprocess_event = tracker.record_tool_call(
                         tool_name="subprocess.codex",
@@ -250,23 +248,18 @@ class CodexSpawner(BaseSpawner):
                     )
                     if subprocess_event:
                         subprocess_event_id = subprocess_event.get("event_id")
-                        print(
-                            f"DEBUG: Subprocess event created for Codex: {subprocess_event_id}",
-                            file=sys.stderr,
+                        logger.warning(
+                            f"DEBUG: Subprocess event created for Codex: {subprocess_event_id}"
                         )
                     else:
-                        print("DEBUG: subprocess_event was None", file=sys.stderr)
+                        logger.debug("subprocess_event was None")
                 except Exception as e:
                     # Tracking failure should not break execution
-                    print(
-                        f"DEBUG: Exception recording Codex subprocess: {e}",
-                        file=sys.stderr,
-                    )
+                    logger.warning(f"DEBUG: Exception recording Codex subprocess: {e}")
                     pass
             else:
-                print(
-                    f"DEBUG: Skipping Codex subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                    file=sys.stderr,
+                logger.warning(
+                    f"DEBUG: Skipping Codex subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}"
                 )
 
             result = subprocess.run(