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

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

@@ -1385,7 +1385,12 @@ class Session(BaseModel):
 
         # Build handoff HTML
         handoff_html = ""
-        if self.handoff_notes or self.recommended_next or self.blockers:
+        if (
+            self.handoff_notes
+            or self.recommended_next
+            or self.blockers
+            or self.recommended_context
+        ):
             handoff_section = """
         <section data-handoff>
             <h3>Handoff Context</h3>"""
@@ -1408,6 +1413,18 @@ class Session(BaseModel):
                 </ul>
             </div>"""
 
+            if self.recommended_context:
+                context_items = "\n                ".join(
+                    f"<li>{file_path}</li>" for file_path in self.recommended_context
+                )
+                handoff_section += f"""
+            <div data-recommended-context>
+                <strong>Recommended Context:</strong>
+                <ul>
+                    {context_items}
+                </ul>
+            </div>"""
+
             handoff_section += "\n        </section>"
             handoff_html = handoff_section
 

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

@@ -9,6 +9,7 @@ from .model_selection import (
     get_fallback_chain,
     select_model,
 )
+from .spawner_event_tracker import SpawnerEventTracker, create_tracker_from_env
 
 # Export modular spawners for advanced usage
 from .spawners import (
@@ -37,6 +38,9 @@ __all__ = [
     "CodexSpawner",
     "CopilotSpawner",
     "ClaudeSpawner",
+    # Spawner event tracking
+    "SpawnerEventTracker",
+    "create_tracker_from_env",
     # Model selection
     "ModelSelection",
     "TaskType",

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
 
@@ -22,7 +25,7 @@ class PluginManager:
         """Get the plugin directory path.
 
         Returns:
-            Path to packages/claude-plugin/.claude-plugin
+            Path to packages/claude-plugin (the plugin root, not .claude-plugin)
         """
         # Path(__file__) = .../src/python/htmlgraph/orchestration/plugin_manager.py
         # Need to go up 5 levels to reach project root
@@ -30,7 +33,6 @@ class PluginManager:
             Path(__file__).parent.parent.parent.parent.parent
             / "packages"
             / "claude-plugin"
-            / ".claude-plugin"
         )
 
     @staticmethod
@@ -41,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,
@@ -55,7 +57,7 @@ class PluginManager:
             )
             if result.returncode == 0:
                 if verbose:
-                    print("    ✓ Marketplace updated")
+                    logger.info("    ✓ Marketplace updated")
             else:
                 # Non-blocking errors
                 if (
@@ -63,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,
@@ -85,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 (
@@ -93,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,
@@ -102,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:
@@ -128,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,