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

htmlgraph/hooks/event_tracker.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 HtmlGraph Event Tracker Module
 
@@ -22,7 +26,6 @@ import json
 import os
 import re
 import subprocess
-import sys
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, cast  # noqa: F401
@@ -149,10 +152,7 @@ def get_parent_user_query(db: HtmlGraphDB, session_id: str) -> str | None:
             return str(row[0])
         return None
     except Exception as e:
-        print(
-            f"Debug: Database query for UserQuery failed: {e}",
-            file=sys.stderr,
-        )
+        logger.warning(f"Debug: Database query for UserQuery failed: {e}")
         return None
 
 
@@ -194,9 +194,8 @@ def load_drift_queue(graph_dir: Path, max_age_hours: int = 48) -> dict[str, Any]
                 queue["activities"] = fresh_activities
                 save_drift_queue(graph_dir, queue)
                 removed = original_count - len(fresh_activities)
-                print(
-                    f"Cleaned {removed} stale drift queue entries (older than {max_age_hours}h)",
-                    file=sys.stderr,
+                logger.warning(
+                    f"Cleaned {removed} stale drift queue entries (older than {max_age_hours}h)"
                 )
 
             return cast(dict[Any, Any], queue)
@@ -212,7 +211,7 @@ def save_drift_queue(graph_dir: Path, queue: dict[str, Any]) -> None:
         with open(queue_path, "w") as f:
             json.dump(queue, f, indent=2, default=str)
     except Exception as e:
-        print(f"Warning: Could not save drift queue: {e}", file=sys.stderr)
+        logger.warning(f"Warning: Could not save drift queue: {e}")
 
 
 def clear_drift_queue_activities(graph_dir: Path) -> None:
@@ -236,7 +235,7 @@ def clear_drift_queue_activities(graph_dir: Path) -> None:
         with open(queue_path, "w") as f:
             json.dump(queue, f, indent=2)
     except Exception as e:
-        print(f"Warning: Could not clear drift queue: {e}", file=sys.stderr)
+        logger.warning(f"Warning: Could not clear drift queue: {e}")
 
 
 def add_to_drift_queue(
@@ -624,7 +623,7 @@ def record_event_to_sqlite(
         return None
 
     except Exception as e:
-        print(f"Warning: Could not record event to SQLite: {e}", file=sys.stderr)
+        logger.warning(f"Warning: Could not record event to SQLite: {e}")
         return None
 
 
@@ -676,7 +675,7 @@ def record_delegation_to_sqlite(
         return None
 
     except Exception as e:
-        print(f"Warning: Could not record delegation to SQLite: {e}", file=sys.stderr)
+        logger.warning(f"Warning: Could not record delegation to SQLite: {e}")
         return None
 
 
@@ -702,7 +701,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
     try:
         manager = SessionManager(graph_dir)
     except Exception as e:
-        print(f"Warning: Could not initialize SessionManager: {e}", file=sys.stderr)
+        logger.warning(f"Warning: Could not initialize SessionManager: {e}")
         return {"continue": True}
 
     # Initialize SQLite database for event recording
@@ -713,7 +712,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
 
         db = HtmlGraphDB(str(get_database_path()))
     except Exception as e:
-        print(f"Warning: Could not initialize SQLite database: {e}", file=sys.stderr)
+        logger.warning(f"Warning: Could not initialize SQLite database: {e}")
         # Continue without SQLite (graceful degradation)
 
     # Detect agent and model from environment
@@ -804,36 +803,28 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                         task_row = cursor.fetchone()
                         if task_row:
                             task_event_id_from_db = task_row[0]
-                            print(
-                                f"DEBUG Method 1 fallback: Found task_delegation={task_event_id_from_db} for {subagent_type}",
-                                file=sys.stderr,
+                            logger.warning(
+                                f"DEBUG Method 1 fallback: Found task_delegation={task_event_id_from_db} for {subagent_type}"
                             )
                         else:
-                            print(
-                                f"DEBUG Method 1: No task_delegation found for subagent_type={subagent_type}",
-                                file=sys.stderr,
+                            logger.warning(
+                                f"DEBUG Method 1: No task_delegation found for subagent_type={subagent_type}"
                             )
                     else:
-                        print(
-                            f"DEBUG Method 1: Found task_delegation={task_event_id_from_db} for subagent {subagent_type}",
-                            file=sys.stderr,
+                        logger.warning(
+                            f"DEBUG Method 1: Found task_delegation={task_event_id_from_db} for subagent {subagent_type}"
                         )
                 except Exception as e:
-                    print(
-                        f"DEBUG: Error finding task_delegation for Method 1: {e}",
-                        file=sys.stderr,
+                    logger.warning(
+                        f"DEBUG: Error finding task_delegation for Method 1: {e}"
                     )
 
-                print(
+                logger.debug(
                     f"DEBUG subagent persistence: Found current session as subagent in sessions table: "
                     f"type={subagent_type}, parent_session={parent_session_id}, task_event={task_event_id_from_db}",
-                    file=sys.stderr,
                 )
         except Exception as e:
-            print(
-                f"DEBUG: Error checking sessions table for subagent: {e}",
-                file=sys.stderr,
-            )
+            logger.warning(f"DEBUG: Error checking sessions table for subagent: {e}")
 
     # Method 2: Environment variables (for first tool call before session table is populated)
     if not subagent_type:
@@ -878,17 +869,13 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                 task_event_id_from_db = (
                     task_event_id  # Store for later use as parent_event_id
                 )
-                print(
+                logger.debug(
                     f"DEBUG subagent detection (database): Detected active task_delegation "
                     f"type={subagent_type}, parent_session={parent_session_id}, "
-                    f"parent_event={task_event_id}",
-                    file=sys.stderr,
+                    f"parent_event={task_event_id}"
                 )
         except Exception as e:
-            print(
-                f"DEBUG: Error detecting subagent from database: {e}",
-                file=sys.stderr,
-            )
+            logger.warning(f"DEBUG: Error detecting subagent from database: {e}")
 
     if subagent_type and parent_session_id:
         # We're in a subagent - create or get subagent session
@@ -899,9 +886,8 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
         existing = manager.session_converter.load(subagent_session_id)
         if existing:
             active_session = existing
-            print(
-                f"Debug: Using existing subagent session: {subagent_session_id}",
-                file=sys.stderr,
+            logger.warning(
+                f"Debug: Using existing subagent session: {subagent_session_id}"
             )
         else:
             # Create new subagent session with parent link
@@ -913,16 +899,12 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                     parent_session_id=parent_session_id,
                     title=f"{subagent_type.capitalize()} Subagent",
                 )
-                print(
+                logger.debug(
                     f"Debug: Created subagent session: {subagent_session_id} "
-                    f"(parent: {parent_session_id})",
-                    file=sys.stderr,
+                    f"(parent: {parent_session_id})"
                 )
             except Exception as e:
-                print(
-                    f"Warning: Could not create subagent session: {e}",
-                    file=sys.stderr,
-                )
+                logger.warning(f"Warning: Could not create subagent session: {e}")
                 return {"continue": True}
 
         # Override detected agent for subagent context
@@ -1004,9 +986,8 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
             )
         except Exception as e:
             # Session may already exist, that's OK - continue
-            print(
-                f"Debug: Could not insert session to SQLite (may already exist): {e}",
-                file=sys.stderr,
+            logger.warning(
+                f"Debug: Could not insert session to SQLite (may already exist): {e}"
             )
 
     # Handle different hook types
@@ -1031,7 +1012,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                     feature_id=result.feature_id if result else None,
                 )
         except Exception as e:
-            print(f"Warning: Could not track stop: {e}", file=sys.stderr)
+            logger.warning(f"Warning: Could not track stop: {e}")
         return {"continue": True}
 
     elif hook_type == "UserPromptSubmit":
@@ -1063,7 +1044,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                 )
 
         except Exception as e:
-            print(f"Warning: Could not track query: {e}", file=sys.stderr)
+            logger.warning(f"Warning: Could not track query: {e}")
         return {"continue": True}
 
     elif hook_type == "PostToolUse":
@@ -1160,14 +1141,12 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                     task_row = cursor.fetchone()
                     if task_row:
                         parent_activity_id = task_row[0]
-                        print(
-                            f"DEBUG: Found active task_delegation={parent_activity_id} in parent_activity_id fallback",
-                            file=sys.stderr,
+                        logger.warning(
+                            f"DEBUG: Found active task_delegation={parent_activity_id} in parent_activity_id fallback"
                         )
                 except Exception as e:
-                    print(
-                        f"DEBUG: Error finding task_delegation in parent_activity_id: {e}",
-                        file=sys.stderr,
+                    logger.warning(
+                        f"DEBUG: Error finding task_delegation in parent_activity_id: {e}"
                     )
 
                 # Only if no active task found, fall back to UserQuery
@@ -1320,7 +1299,7 @@ Or manually create a work item in .htmlgraph/ (bug, feature, spike, or chore).""
                     nudge = f"Drift detected ({drift_score:.2f}): Activity may not align with {feature_id}. Consider refocusing or updating the feature."
 
         except Exception as e:
-            print(f"Warning: Could not track activity: {e}", file=sys.stderr)
+            logger.warning(f"Warning: Could not track activity: {e}")
 
         # Build response
         response: dict[str, Any] = {"continue": True}

htmlgraph/hooks/installer.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Git hooks installation and configuration management.
 """
@@ -52,7 +56,7 @@ class HookConfig:
                 user_config = json.load(f)
                 self.config.update(user_config)
         except Exception as e:
-            print(f"Warning: Failed to load hook config: {e}")
+            logger.info(f"Warning: Failed to load hook config: {e}")
 
     def save(self) -> None:
         """Save configuration to file."""

htmlgraph/hooks/orchestrator.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Orchestrator Enforcement Module
 

htmlgraph/hooks/orchestrator_reflector.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Orchestrator Reflection Module
 

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()