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

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(

htmlgraph/orchestration/spawners/copilot.py

@@ -1,12 +1,14 @@
 """Copilot spawner implementation."""
 
+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
 
@@ -129,15 +131,11 @@ class CopilotSpawner(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 Copilot...",
-                    file=sys.stderr,
-                )
+                logger.debug("Recording subprocess invocation for Copilot...")
                 try:
                     subprocess_event = tracker.record_tool_call(
                         tool_name="subprocess.copilot",
@@ -147,23 +145,20 @@ class CopilotSpawner(BaseSpawner):
                     )
                     if subprocess_event:
                         subprocess_event_id = subprocess_event.get("event_id")
-                        print(
-                            f"DEBUG: Subprocess event created for Copilot: {subprocess_event_id}",
-                            file=sys.stderr,
+                        logger.warning(
+                            f"DEBUG: Subprocess event created for Copilot: {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 Copilot subprocess: {e}",
-                        file=sys.stderr,
+                    logger.warning(
+                        f"DEBUG: Exception recording Copilot subprocess: {e}"
                     )
                     pass
             else:
-                print(
-                    f"DEBUG: Skipping Copilot subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                    file=sys.stderr,
+                logger.warning(
+                    f"DEBUG: Skipping Copilot subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}"
                 )
 
             result = subprocess.run(

htmlgraph/orchestration/spawners/gemini.py

@@ -1,13 +1,15 @@
 """Gemini 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
 
@@ -220,15 +222,11 @@ class GeminiSpawner(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 Gemini...",
-                    file=sys.stderr,
-                )
+                logger.debug("Recording subprocess invocation for Gemini...")
                 try:
                     subprocess_event = tracker.record_tool_call(
                         tool_name="subprocess.gemini",
@@ -238,23 +236,18 @@ class GeminiSpawner(BaseSpawner):
                     )
                     if subprocess_event:
                         subprocess_event_id = subprocess_event.get("event_id")
-                        print(
-                            f"DEBUG: Subprocess event created for Gemini: {subprocess_event_id}",
-                            file=sys.stderr,
+                        logger.warning(
+                            f"DEBUG: Subprocess event created for Gemini: {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 Gemini subprocess: {e}",
-                        file=sys.stderr,
-                    )
+                    logger.warning(f"DEBUG: Exception recording Gemini subprocess: {e}")
                     pass
             else:
-                print(
-                    f"DEBUG: Skipping Gemini subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
-                    file=sys.stderr,
+                logger.warning(
+                    f"DEBUG: Skipping Gemini subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}"
                 )
 
             # Execute with timeout and stderr redirection

htmlgraph/orchestration/subprocess_runner.py

@@ -1,13 +1,16 @@
+from __future__ import annotations
+
 """Subprocess execution with standardized error handling.
 
 Provides consistent error handling for Claude Code CLI invocations.
 """
 
-from __future__ import annotations
-
+import logging
 import subprocess
 import sys
 
+logger = logging.getLogger(__name__)
+
 
 class SubprocessRunner:
     """Execute subprocess commands with error handling."""
@@ -25,7 +28,7 @@ class SubprocessRunner:
         try:
             subprocess.run(cmd, check=False)
         except FileNotFoundError:
-            print("Error: 'claude' command not found.", file=sys.stderr)
+            logger.warning("Error: 'claude' command not found.")
             print(
                 "Please install Claude Code CLI: https://code.claude.com",
                 file=sys.stderr,

htmlgraph/orchestration/task_coordination.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Orchestration helpers for reliable parallel task coordination.
 
@@ -7,9 +11,13 @@ Provides Task ID pattern for retrieving results from parallel delegations.
 import time
 import uuid
 from datetime import datetime, timedelta
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from htmlgraph.sdk import SDK
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+else:
+    # Avoid circular import during module initialization
+    SDK = None
 
 
 def generate_task_id() -> str:
@@ -72,7 +80,7 @@ Provide detailed findings in your response.
 
 
 def get_results_by_task_id(
-    sdk: SDK,
+    sdk: "SDK",
     task_id: str,
     timeout: int = 60,
     poll_interval: int = 2,
@@ -138,7 +146,7 @@ def get_results_by_task_id(
 
 
 def parallel_delegate(
-    sdk: SDK,
+    sdk: "SDK",
     tasks: list[dict[str, str]],
     timeout: int = 120,
 ) -> dict[str, dict[str, Any]]:
@@ -161,7 +169,7 @@ def parallel_delegate(
         ])
 
         for task_id, result in results.items():
-            print(f"{task_id}: {result['findings']}")
+            logger.info(f"{task_id}: {result['findings']}")
     """
     # Generate task IDs and enhanced prompts
     task_mapping = {}
@@ -189,7 +197,7 @@ def parallel_delegate(
 
 
 def save_task_results(
-    sdk: SDK,
+    sdk: "SDK",
     task_id: str,
     description: str,
     results: str,
@@ -263,7 +271,7 @@ def save_task_results(
 
 
 def validate_and_save(
-    sdk: SDK,
+    sdk: "SDK",
     task_id: str,
     description: str,
     results: str,
@@ -303,7 +311,7 @@ def validate_and_save(
         )
 
         if outcome["validated"]:
-            print(f"✅ Saved to spike: {outcome['spike_id']}")
+            logger.info(f"✅ Saved to spike: {outcome['spike_id']}")
     """
     validated = True
     validation_results = None

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/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/query_builder.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Fluent Query Builder for HtmlGraph.
 
@@ -24,7 +26,6 @@ Example:
         .execute()
 """
 
-from __future__ import annotations
 
 import re
 from collections.abc import Callable, Iterator

htmlgraph/reflection.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Computational Reflection Module.
 
@@ -23,7 +25,6 @@ Usage:
     # }
 """
 
-from __future__ import annotations
 
 from dataclasses import dataclass
 from datetime import datetime, timedelta

htmlgraph/refs.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Short reference manager for graph nodes.
 
@@ -5,7 +7,6 @@ Manages persistent mapping of short refs (@f1, @t2, @b5) to full node IDs,
 enabling AI-friendly snapshots and queries.
 """
 
-from __future__ import annotations
 
 import json
 from datetime import datetime

htmlgraph/repo_hash.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Repository Hashing and Git Awareness Module.
 
@@ -22,7 +24,6 @@ Architecture:
     - monorepo_project: "project-name" (if in monorepo)
 """
 
-from __future__ import annotations
 
 import hashlib
 import logging