htmlgraph 0.28.8__py3-none-any.whl → 0.28.9__py3-none-any.whl

htmlgraph/__init__.py

@@ -89,6 +89,20 @@ from htmlgraph.query_builder import Condition, Operator, QueryBuilder
 from htmlgraph.reflection import ComputationalReflection, get_reflection_context
 from htmlgraph.repo_hash import RepoHash
 from htmlgraph.sdk import SDK
+from htmlgraph.sdk.auto_help import (
+    AutoHelpWrapper,
+    enable_auto_help,
+    get_help_for_exception,
+    show_help_on_error,
+)
+from htmlgraph.sdk.delegation_warnings import (
+    get_delegation_warning,
+    is_in_subagent_context,
+    is_orchestrator_mode_active,
+    should_show_delegation_warning,
+    show_delegation_warning,
+    track_tool_execution,
+)
 from htmlgraph.server import serve
 from htmlgraph.session_context import (
     GitHooksInstaller,
@@ -123,7 +137,7 @@ from htmlgraph.types import (
 )
 from htmlgraph.work_type_utils import infer_work_type, infer_work_type_from_id
 
-__version__ = "0.28.8"
+__version__ = "0.28.9"
 __all__ = [
     # Exceptions
     "HtmlGraphError",
@@ -244,4 +258,16 @@ __all__ = [
     "cleanup_orphaned_temp_files",
     "safe_temp_file",
     "validate_atomic_write",
+    # Auto-help system (Feature 1: Auto-Help on Failure)
+    "AutoHelpWrapper",
+    "enable_auto_help",
+    "get_help_for_exception",
+    "show_help_on_error",
+    # Delegation warnings (Feature 2: Orchestrator Mode Warnings)
+    "get_delegation_warning",
+    "is_in_subagent_context",
+    "is_orchestrator_mode_active",
+    "should_show_delegation_warning",
+    "show_delegation_warning",
+    "track_tool_execution",
 ]

htmlgraph/operations/initialization.py

@@ -484,9 +484,24 @@ def create_dashboard_index(base_dir: Path) -> str | None:
         import htmlgraph
 
         htmlgraph_dir = Path(htmlgraph.__file__).parent
-        dashboard_path = htmlgraph_dir / "dashboard.html"
 
-        if not dashboard_path.exists():
+        # Try multiple possible locations for dashboard.html
+        # Try archive first (preferred, has COLOR SYSTEM & THEME), then API templates, then package root
+        possible_paths = [
+            htmlgraph_dir.parent.parent.parent
+            / "_archive"
+            / "dashboard.html",  # In project archive (preferred)
+            htmlgraph_dir / "dashboard.html",  # In package root
+            htmlgraph_dir / "api" / "templates" / "dashboard.html",  # In API templates
+        ]
+
+        dashboard_path = None
+        for path in possible_paths:
+            if path.exists():
+                dashboard_path = path
+                break
+
+        if dashboard_path is None:
             return None
 
         # Copy to root as index.html

htmlgraph/sdk/__init__.py

@@ -148,6 +148,7 @@ class SDK(
         agent: str | None = None,
         parent_session: str | None = None,
         db_path: str | None = None,
+        auto_help: bool = True,
     ):
         """
         Initialize SDK.
@@ -162,6 +163,7 @@ class SDK(
                 Raises ValueError if not provided and cannot be detected
             parent_session: Parent session ID to log activities to (for nested contexts)
             db_path: Path to SQLite database file (optional, defaults to ~/.htmlgraph/htmlgraph.db)
+            auto_help: Enable automatic help display on operation failures (default: True)
         """
         if directory is None:
             directory = self._discover_htmlgraph()
@@ -283,6 +285,12 @@ class SDK(
             session_id=None,  # Will be set by session manager if available
         )
 
+        # Enable auto-help on operation failures (Feature 1)
+        if auto_help:
+            from htmlgraph.sdk.auto_help import enable_auto_help
+
+            enable_auto_help(self)
+
     @staticmethod
     def _discover_htmlgraph() -> Path:
         """

htmlgraph/sdk/auto_help.py

@@ -0,0 +1,183 @@
+"""
+Auto-help system for SDK operations.
+
+Provides automatic help display when SDK operations fail,
+showing relevant documentation for the failed operation.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+logger = logging.getLogger(__name__)
+
+
+def get_help_for_exception(sdk: SDK, exception: Exception, context: str = "") -> str:
+    """
+    Generate helpful error message with SDK documentation.
+
+    Args:
+        sdk: SDK instance to get help from
+        exception: The exception that was raised
+        context: Context string (e.g., "features.create", "bugs.where")
+
+    Returns:
+        Formatted help text with error and relevant documentation
+    """
+    # Extract topic from context (e.g., "features" from "features.create")
+    topic = context.split(".")[0] if "." in context else context
+
+    # Get base error message
+    error_msg = str(exception)
+
+    # Get relevant help
+    help_text = ""
+    if topic:
+        try:
+            help_text = sdk.help(topic)
+        except Exception:
+            # Fallback to general help if topic-specific help fails
+            help_text = sdk.help()
+
+    # Format combined message
+    output = f"""
+❌ SDK Operation Failed: {error_msg}
+
+{"=" * 60}
+📚 RELEVANT DOCUMENTATION
+{"=" * 60}
+
+{help_text}
+
+💡 TIP: Use sdk.help('{topic}') for more details on this collection.
+"""
+    return output
+
+
+def show_help_on_error(sdk: SDK, exception: Exception, context: str = "") -> None:
+    """
+    Display help message for exception to stderr.
+
+    Args:
+        sdk: SDK instance
+        exception: The exception that occurred
+        context: Context string for the operation
+    """
+    help_msg = get_help_for_exception(sdk, exception, context)
+    # Use logger to output to stderr (configured with Rich in __init__.py)
+    logger.error(help_msg)
+
+
+class AutoHelpWrapper:
+    """
+    Wrapper for collection methods that automatically shows help on errors.
+
+    This wrapper catches exceptions from collection operations and displays
+    relevant SDK documentation to help users understand what went wrong.
+    """
+
+    def __init__(self, sdk: SDK, collection_name: str):
+        """
+        Initialize wrapper.
+
+        Args:
+            sdk: Parent SDK instance
+            collection_name: Name of the collection (e.g., "features", "bugs")
+        """
+        self._sdk = sdk
+        self._collection_name = collection_name
+
+    def wrap_method(self, method: Any, method_name: str) -> Any:
+        """
+        Wrap a method to show help on exceptions.
+
+        Args:
+            method: The method to wrap
+            method_name: Name of the method
+
+        Returns:
+            Wrapped method
+        """
+
+        def wrapped(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return method(*args, **kwargs)
+            except Exception as e:
+                # Show help automatically
+                context = f"{self._collection_name}.{method_name}"
+                show_help_on_error(self._sdk, e, context)
+                # Re-raise the original exception
+                raise
+
+        return wrapped
+
+
+def enable_auto_help(sdk: SDK) -> None:
+    """
+    Enable auto-help for all SDK collections.
+
+    This wraps common collection methods to automatically show help on errors.
+
+    Args:
+        sdk: SDK instance to enable auto-help for
+    """
+    # Collections to wrap
+    collections = [
+        "features",
+        "bugs",
+        "spikes",
+        "chores",
+        "epics",
+        "phases",
+        "tracks",
+        "sessions",
+        "patterns",
+        "insights",
+        "metrics",
+        "todos",
+    ]
+
+    # Methods to wrap (common operations that might fail)
+    methods_to_wrap = [
+        "create",
+        "get",
+        "edit",
+        "where",
+        "claim",
+        "release",
+        "mark_done",
+        "assign",
+        "batch_update",
+        "batch_delete",
+    ]
+
+    for collection_name in collections:
+        if not hasattr(sdk, collection_name):
+            continue
+
+        collection = getattr(sdk, collection_name)
+        wrapper = AutoHelpWrapper(sdk, collection_name)
+
+        for method_name in methods_to_wrap:
+            if not hasattr(collection, method_name):
+                continue
+
+            original_method = getattr(collection, method_name)
+            wrapped_method = wrapper.wrap_method(original_method, method_name)
+
+            # Store original method for testing
+            setattr(collection, f"_{method_name}_original", original_method)
+            # Replace with wrapped version
+            setattr(collection, method_name, wrapped_method)
+
+
+__all__ = [
+    "get_help_for_exception",
+    "show_help_on_error",
+    "AutoHelpWrapper",
+    "enable_auto_help",
+]

htmlgraph/sdk/delegation_warnings.py

@@ -0,0 +1,232 @@
+"""
+Delegation warnings for orchestrator mode.
+
+Provides warnings when orchestrators execute tools directly instead of delegating,
+with automatic suppression when running in subagent contexts.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def is_orchestrator_mode_active() -> bool:
+    """
+    Check if orchestrator mode is active.
+
+    Returns:
+        True if orchestrator mode is enabled
+    """
+    # Check environment variable override
+    if os.environ.get("HTMLGRAPH_ORCHESTRATOR_DISABLED") == "1":
+        return False
+
+    # Check orchestrator mode file
+    try:
+        from pathlib import Path
+
+        from htmlgraph.orchestrator_mode import OrchestratorModeManager
+
+        # Find .htmlgraph directory
+        cwd = Path.cwd()
+        graph_dir = cwd / ".htmlgraph"
+
+        if not graph_dir.exists():
+            for parent in [cwd.parent, cwd.parent.parent, cwd.parent.parent.parent]:
+                candidate = parent / ".htmlgraph"
+                if candidate.exists():
+                    graph_dir = candidate
+                    break
+
+        if not graph_dir.exists():
+            return False
+
+        manager = OrchestratorModeManager(graph_dir)
+        return manager.is_enabled()
+    except Exception:
+        return False
+
+
+def is_in_subagent_context() -> bool:
+    """
+    Check if running in a subagent context.
+
+    Subagents are spawned via Task() and should be allowed to execute
+    tools directly without delegation warnings.
+
+    Returns:
+        True if in subagent context
+    """
+    # Check for subagent environment variable
+    subagent_type = os.environ.get("HTMLGRAPH_SUBAGENT_TYPE")
+    if subagent_type:
+        return True
+
+    # Check for general subagent marker
+    if os.environ.get("HTMLGRAPH_IS_SUBAGENT") == "1":
+        return True
+
+    # Check if spawned by Task tool (Claude Code sets this)
+    if os.environ.get("CLAUDE_SPAWNED_BY_TASK") == "1":
+        return True
+
+    return False
+
+
+def should_show_delegation_warning() -> bool:
+    """
+    Determine if delegation warnings should be shown.
+
+    Warnings are shown when:
+    - Orchestrator mode is active
+    - NOT running in subagent context
+    - Warnings are not explicitly disabled
+
+    Returns:
+        True if warnings should be shown
+    """
+    # Check explicit disable
+    if os.environ.get("HTMLGRAPH_DISABLE_DELEGATION_WARNINGS") == "1":
+        return False
+
+    # Don't warn in subagent contexts
+    if is_in_subagent_context():
+        return False
+
+    # Only warn if orchestrator mode is active
+    return is_orchestrator_mode_active()
+
+
+def get_delegation_warning(tool_name: str, context: str = "") -> str:
+    """
+    Generate delegation warning message.
+
+    Args:
+        tool_name: Name of the tool being executed directly
+        context: Additional context about the operation
+
+    Returns:
+        Formatted warning message
+    """
+    # Map tools to suggested subagent types
+    tool_to_agent = {
+        "Read": "Explore",
+        "Grep": "Explore",
+        "Glob": "Explore",
+        "Edit": "general-purpose",
+        "Write": "general-purpose",
+        "NotebookEdit": "general-purpose",
+        "Bash": "general-purpose",
+    }
+
+    suggested_agent = tool_to_agent.get(tool_name, "general-purpose")
+
+    warning = f"""
+⚠️  ORCHESTRATOR MODE: Direct tool execution detected
+
+Tool: {tool_name}
+Suggestion: Delegate to subagent using Task()
+
+Recommended subagent type: {suggested_agent}
+
+Example delegation:
+  Task(
+      prompt='''<describe task>
+
+      🔴 CRITICAL - Report Results:
+      from htmlgraph import SDK
+      sdk = SDK(agent='subagent')
+      sdk.spikes.create('Task Results') \\
+          .set_findings('...') \\
+          .save()
+      ''',
+      subagent_type='{suggested_agent}'
+  )
+
+Why delegate?
+  - Reduces orchestrator context usage
+  - Enables parallel execution
+  - Improves cost efficiency
+  - Follows delegation pattern
+
+To disable warnings:
+  - Set HTMLGRAPH_DISABLE_DELEGATION_WARNINGS=1
+  - Or: uv run htmlgraph orchestrator disable
+"""
+
+    if context:
+        warning += f"\nContext: {context}\n"
+
+    return warning
+
+
+def show_delegation_warning(
+    tool_name: str, params: dict[str, Any] | None = None
+) -> None:
+    """
+    Display delegation warning if appropriate.
+
+    Args:
+        tool_name: Name of the tool being executed
+        params: Tool parameters (optional, for context)
+    """
+    if not should_show_delegation_warning():
+        return
+
+    # Extract context from params
+    context = ""
+    if params:
+        if "file_path" in params:
+            context = f"File: {params['file_path']}"
+        elif "pattern" in params:
+            context = f"Pattern: {params['pattern']}"
+        elif "command" in params:
+            cmd = params["command"]
+            if len(cmd) > 80:
+                cmd = cmd[:77] + "..."
+            context = f"Command: {cmd}"
+
+    warning = get_delegation_warning(tool_name, context)
+    # Use logger to output to stderr
+    logger.warning(warning)
+
+
+def track_tool_execution(tool_name: str, params: dict[str, Any] | None = None) -> None:
+    """
+    Track tool execution and show delegation warning if needed.
+
+    This is the main entry point for tracking tool usage in orchestrator mode.
+
+    Args:
+        tool_name: Name of the tool being executed
+        params: Tool parameters (optional)
+    """
+    # Only track direct tool execution, not SDK operations
+    tracked_tools = [
+        "Read",
+        "Write",
+        "Edit",
+        "NotebookEdit",
+        "Grep",
+        "Glob",
+        "Bash",
+    ]
+
+    if tool_name not in tracked_tools:
+        return
+
+    show_delegation_warning(tool_name, params)
+
+
+__all__ = [
+    "is_orchestrator_mode_active",
+    "is_in_subagent_context",
+    "should_show_delegation_warning",
+    "get_delegation_warning",
+    "show_delegation_warning",
+    "track_tool_execution",
+]

{htmlgraph-0.28.8.dist-info → htmlgraph-0.28.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htmlgraph
-Version: 0.28.8
+Version: 0.28.9
 Summary: HTML is All You Need - Graph database on web standards
 Project-URL: Homepage, https://github.com/Shakes-tzd/htmlgraph
 Project-URL: Documentation, https://github.com/Shakes-tzd/htmlgraph#readme

{htmlgraph-0.28.8.dist-info → htmlgraph-0.28.9.dist-info}/RECORD

@@ -1,4 +1,4 @@
-htmlgraph/__init__.py,sha256=V0B14PG5igDUlgy7oLF90EXzfPf_B_HXmrqo4YnB9qU,6595
+htmlgraph/__init__.py,sha256=h74L3yWUw2IJ523jruD2AjQB7tTOXef3Gx06pz8-JKw,7378
 htmlgraph/__init__.pyi,sha256=8JuFVuDll9jMx9s8ZQHt2tXic-geOJHiXUMB2YjmHhU,6683
 htmlgraph/agent_detection.py,sha256=wEmrDv4hssPX2OkEnJZBHPbalxcaloiJF_hOOow_5WE,3511
 htmlgraph/agent_registry.py,sha256=80TPYr4P0YMizPUbTH4N5wH6D84IKs-HPBLHGeeP6bY,9449
@@ -260,7 +260,7 @@ htmlgraph/operations/bootstrap.py,sha256=PK0DNw7Mop-B9tE7yBEJYw-KDyCz2AYsbfGHMVs
 htmlgraph/operations/events.py,sha256=LIMn16qfgwolf8L7DIzBbqivxP-kLrHdzEz4y4a50_U,6843
 htmlgraph/operations/fastapi_server.py,sha256=ITHX4clotCHNiLjfNfLw3KYUMfVKKIukPypJZdQ_6OU,5802
 htmlgraph/operations/hooks.py,sha256=SlZcEtLPIysVmBPtO2bV-z3CnBx_mmYT5ia9R5bdGZw,10038
-htmlgraph/operations/initialization.py,sha256=aOUVB0YULVlRzkqXQKY3GT_PWX51H9QRPvhwTIMZ1t0,17059
+htmlgraph/operations/initialization.py,sha256=ebpuOdsMak2rB4LCicxWw109FPms6ndT9e8VJQZbtI4,17648
 htmlgraph/operations/initialization.py.backup,sha256=U0ZibrAUFMgx8fhD_6rh-Ifve9e0eUDK8a-IxQ9i3Is,7067
 htmlgraph/operations/server.py,sha256=ls3_3ULB2ktFN0WNbJrVCvWRPrzXpQuNuNy76tbyTI8,8747
 htmlgraph/orchestration/__init__.py,sha256=udK-EtJ49wONOWc8S0pkZn40q9Io8BjB45xkC7AO4nY,1337
@@ -297,11 +297,13 @@ htmlgraph/repositories/track_repository_memory.py,sha256=KFbo3rJDEGCa-kWqR7U7ULx
 htmlgraph/repositories/track_repository_sqlite.py,sha256=72Xy3nttrz1bQ6-UDgBNuMFstjLgLO7WF_SOr4kaRtc,20881
 htmlgraph/scripts/__init__.py,sha256=a_ef7jnypTH3fzjutKYtUquJospdbA6IOR4o9dgv8Gk,48
 htmlgraph/scripts/deploy.py,sha256=TAdUvnHRuWHgoyUgif8Eln-aY9JWLbXAhkMpzQ1kC9A,4191
-htmlgraph/sdk/__init__.py,sha256=46lfnkdtj8A7Sr_gg0N7v_kwlCHUqEzx58lyJJaEL3Y,14656
+htmlgraph/sdk/__init__.py,sha256=IO2y4gbEKZkRiouN42he0F70ChJlvzPayvYG_fDpWnw,14964
 htmlgraph/sdk/__init__.pyi,sha256=Xpe64vXTg7XzURXoP6sPexsHSvdJR5pKVgp8ptLPcMU,495
+htmlgraph/sdk/auto_help.py,sha256=2BqqvJ_CubyRthhCDPQDMKD8wh_pTDLDnb5czWESwjo,4803
 htmlgraph/sdk/base.py,sha256=aw4rz6iykefHs2rLMsYlEXzmnV8Dvtz554oA5xDVwLA,17124
 htmlgraph/sdk/constants.py,sha256=puZ-QPk9OWI9JgNca9kEldu1O9CN6dVjF0q7F-l4USs,6467
 htmlgraph/sdk/core.pyi,sha256=Kk5kAS--qwqsnzszFNB3MIlrnQ1fXIhjDkuNUjJlt8g,9793
+htmlgraph/sdk/delegation_warnings.py,sha256=HGubXpvqqgywQUjNt-A1M_BH-TRC0lO1-kd5LbhzjX4,5932
 htmlgraph/sdk/discovery.py,sha256=4CT6D3AY2ydFgUtYkJyDyhE4gOMcC3AWzzv3NicdyMY,3181
 htmlgraph/sdk/analytics/__init__.py,sha256=cPx54IQZrmREHE-p69R4ZlhsxJMS7Wr23HmLCSzEXvU,526
 htmlgraph/sdk/analytics/engine.py,sha256=T3PW7PHZH5D1bRtUfEqLVYohBYz-wV7pUDLu-72AB9I,4970
@@ -341,11 +343,11 @@ htmlgraph/templates/AGENTS.md.template,sha256=f96h7V6ygwj-v-fanVI48eYMxR6t_se4be
 htmlgraph/templates/CLAUDE.md.template,sha256=h1kG2hTX2XYig2KszsHBfzrwa_4Cfcq2Pj4SwqzeDlM,1984
 htmlgraph/templates/GEMINI.md.template,sha256=gAGzE53Avki87BM_otqy5HdcYCoLsHgqaKjVzNzPMX8,1622
 htmlgraph/templates/orchestration-view.html,sha256=DlS7LlcjH0oO_KYILjuF1X42t8QhKLH4F85rkO54alY,10472
-htmlgraph-0.28.8.data/data/htmlgraph/styles.css,sha256=oDUSC8jG-V-hKojOBO9J88hxAeY2wJrBYTq0uCwX_Y4,7135
-htmlgraph-0.28.8.data/data/htmlgraph/templates/AGENTS.md.template,sha256=f96h7V6ygwj-v-fanVI48eYMxR6t_se4bet1H4ZsDpI,7642
-htmlgraph-0.28.8.data/data/htmlgraph/templates/CLAUDE.md.template,sha256=h1kG2hTX2XYig2KszsHBfzrwa_4Cfcq2Pj4SwqzeDlM,1984
-htmlgraph-0.28.8.data/data/htmlgraph/templates/GEMINI.md.template,sha256=gAGzE53Avki87BM_otqy5HdcYCoLsHgqaKjVzNzPMX8,1622
-htmlgraph-0.28.8.dist-info/METADATA,sha256=IPfCuODE1MboouvO5Y9AnXPSOaYrpjAC4zyKtOIACn0,10220
-htmlgraph-0.28.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-htmlgraph-0.28.8.dist-info/entry_points.txt,sha256=Wmdo5cx8pt6NoMsssVE2mZH1CZLSUsrg_3iSWatiyn0,103
-htmlgraph-0.28.8.dist-info/RECORD,,
+htmlgraph-0.28.9.data/data/htmlgraph/styles.css,sha256=oDUSC8jG-V-hKojOBO9J88hxAeY2wJrBYTq0uCwX_Y4,7135
+htmlgraph-0.28.9.data/data/htmlgraph/templates/AGENTS.md.template,sha256=f96h7V6ygwj-v-fanVI48eYMxR6t_se4bet1H4ZsDpI,7642
+htmlgraph-0.28.9.data/data/htmlgraph/templates/CLAUDE.md.template,sha256=h1kG2hTX2XYig2KszsHBfzrwa_4Cfcq2Pj4SwqzeDlM,1984
+htmlgraph-0.28.9.data/data/htmlgraph/templates/GEMINI.md.template,sha256=gAGzE53Avki87BM_otqy5HdcYCoLsHgqaKjVzNzPMX8,1622
+htmlgraph-0.28.9.dist-info/METADATA,sha256=pSO2X9sHT-bWOaZ9cr0mLY7X55eGGhlaLfMgbHhgYKY,10220
+htmlgraph-0.28.9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+htmlgraph-0.28.9.dist-info/entry_points.txt,sha256=Wmdo5cx8pt6NoMsssVE2mZH1CZLSUsrg_3iSWatiyn0,103
+htmlgraph-0.28.9.dist-info/RECORD,,