htmlgraph 0.9.3__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/.htmlgraph/.session-warning-state.json

@@ -0,0 +1,6 @@
+{
+  "dismissed_at": null,
+  "dismissed_by": null,
+  "session_id": null,
+  "show_count": 59
+}

htmlgraph/.htmlgraph/agents.json

@@ -0,0 +1,72 @@
+{
+  "version": "1.0",
+  "updated": "2026-01-11T04:13:54.354401",
+  "agents": {
+    "claude": {
+      "id": "claude",
+      "name": "Claude",
+      "capabilities": [
+        "python",
+        "javascript",
+        "typescript",
+        "html",
+        "css",
+        "code-review",
+        "testing",
+        "documentation",
+        "debugging",
+        "refactoring",
+        "architecture",
+        "api-design"
+      ],
+      "max_parallel_tasks": 3,
+      "preferred_complexity": [
+        "low",
+        "medium",
+        "high",
+        "very-high"
+      ],
+      "active": true,
+      "metadata": {}
+    },
+    "gemini": {
+      "id": "gemini",
+      "name": "Gemini",
+      "capabilities": [
+        "python",
+        "data-analysis",
+        "documentation",
+        "testing",
+        "code-review",
+        "javascript"
+      ],
+      "max_parallel_tasks": 2,
+      "preferred_complexity": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "active": true,
+      "metadata": {}
+    },
+    "codex": {
+      "id": "codex",
+      "name": "Codex",
+      "capabilities": [
+        "python",
+        "javascript",
+        "debugging",
+        "testing",
+        "code-generation",
+        "documentation"
+      ],
+      "max_parallel_tasks": 2,
+      "preferred_complexity": [
+        "low",
+        "medium"
+      ],
+      "active": true,
+      "metadata": {}
+    }
+  }
+}

htmlgraph/__init__.py

@@ -5,35 +5,131 @@ A lightweight graph database framework using HTML files as nodes,
 hyperlinks as edges, and CSS selectors as the query language.
 """
 
+import logging
+
+from rich.console import Console
+from rich.logging import RichHandler
+
+# Configure Rich logging for entire SDK
+# CRITICAL: Use stderr=True to prevent pollution of stdout (hooks output JSON to stdout)
+logging.basicConfig(
+    handlers=[
+        RichHandler(
+            console=Console(stderr=True),
+            show_time=True,
+            show_level=True,
+            rich_tracebacks=True,
+        )
+    ],
+    level=logging.INFO,
+    format="%(message)s",
+    datefmt="[%X]",
+)
+
+# SDK now lives in sdk/core.py - clean import from sdk package
+from htmlgraph.agent_detection import detect_agent_name, get_agent_display_name
+from htmlgraph.agents import AgentInterface
+from htmlgraph.analytics import Analytics, DependencyAnalytics
+from htmlgraph.atomic_ops import (
+    AtomicFileWriter,
+    DirectoryLocker,
+    atomic_rename,
+    cleanup_orphaned_temp_files,
+    safe_temp_file,
+    validate_atomic_write,
+)
+from htmlgraph.builders import BaseBuilder, FeatureBuilder, SpikeBuilder
+from htmlgraph.collections import BaseCollection, FeatureCollection, SpikeCollection
+from htmlgraph.context_analytics import ContextAnalytics, ContextUsage
+from htmlgraph.decorators import RetryError, retry, retry_async
+from htmlgraph.edge_index import EdgeIndex, EdgeRef
+from htmlgraph.exceptions import (
+    ClaimConflictError,
+    HtmlGraphError,
+    NodeNotFoundError,
+    SessionNotFoundError,
+    ValidationError,
+)
+from htmlgraph.find_api import FindAPI, find, find_all
+from htmlgraph.graph import CompiledQuery, HtmlGraph
+from htmlgraph.ids import (
+    generate_hierarchical_id,
+    generate_id,
+    is_legacy_id,
+    is_valid_id,
+    parse_id,
+)
+from htmlgraph.learning import LearningPersistence, auto_persist_on_session_end
 from htmlgraph.models import (
-    Node,
+    ActivityEntry,
+    AggregatedMetric,
+    Chore,
+    ContextSnapshot,
     Edge,
-    Step,
     Graph,
+    MaintenanceType,
+    Node,
+    Pattern,
     Session,
-    ActivityEntry,
+    SessionInsight,
     Spike,
-    Chore,
-    WorkType,
     SpikeType,
-    MaintenanceType,
+    Step,
+    WorkType,
 )
-from htmlgraph.graph import HtmlGraph
-from htmlgraph.edge_index import EdgeIndex, EdgeRef
-from htmlgraph.query_builder import QueryBuilder, Condition, Operator
-from htmlgraph.find_api import FindAPI, find, find_all
-from htmlgraph.agents import AgentInterface
+from htmlgraph.orchestration import (
+    delegate_with_id,
+    generate_task_id,
+    get_results_by_task_id,
+    parallel_delegate,
+)
+from htmlgraph.orchestrator_mode import OrchestratorMode, OrchestratorModeManager
+from htmlgraph.parallel import AggregateResult, ParallelAnalysis, ParallelWorkflow
+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.server import serve
 from htmlgraph.session_manager import SessionManager
-from htmlgraph.sdk import SDK
-from htmlgraph.analytics import Analytics, DependencyAnalytics
-from htmlgraph.ids import generate_id, generate_hierarchical_id, parse_id, is_valid_id, is_legacy_id
+from htmlgraph.session_registry import SessionRegistry
+from htmlgraph.types import (
+    ActiveWorkItem,
+    AggregateResultsDict,
+    BottleneckDict,
+    FeatureSummary,
+    HighRiskTask,
+    ImpactAnalysisDict,
+    OrchestrationResult,
+    ParallelGuidelines,
+    ParallelPlanResult,
+    ParallelWorkInfo,
+    PlanningContext,
+    ProjectStatus,
+    RiskAssessmentDict,
+    SessionAnalytics,
+    SessionStartInfo,
+    SessionSummary,
+    SmartPlanResult,
+    SubagentPrompt,
+    TaskPrompt,
+    TrackCreationResult,
+    WorkQueueItem,
+    WorkRecommendation,
+)
 from htmlgraph.work_type_utils import infer_work_type, infer_work_type_from_id
-from htmlgraph.builders import BaseBuilder, FeatureBuilder, SpikeBuilder
-from htmlgraph.collections import BaseCollection, FeatureCollection, SpikeCollection
 
-__version__ = "0.9.3"
+__version__ = "0.27.5"
 __all__ = [
+    # Exceptions
+    "HtmlGraphError",
+    "NodeNotFoundError",
+    "SessionNotFoundError",
+    "ClaimConflictError",
+    "ValidationError",
+    "RetryError",
+    # Decorators
+    "retry",
+    "retry_async",
     # Core models
     "Node",
     "Edge",
@@ -41,14 +137,19 @@ __all__ = [
     "Graph",
     "Session",
     "ActivityEntry",
+    "ContextSnapshot",
     "Spike",
     "Chore",
+    "Pattern",
+    "SessionInsight",
+    "AggregatedMetric",
     # Work type classification (Phase 1)
     "WorkType",
     "SpikeType",
     "MaintenanceType",
     # Graph operations
     "HtmlGraph",
+    "CompiledQuery",
     "EdgeIndex",
     "EdgeRef",
     "QueryBuilder",
@@ -59,9 +160,13 @@ __all__ = [
     "find_all",
     "AgentInterface",
     "SessionManager",
+    "SessionRegistry",
+    "RepoHash",
     "SDK",
     "Analytics",  # Phase 2: Work Type Analytics
     "DependencyAnalytics",  # Advanced dependency-aware analytics
+    "ContextAnalytics",  # Context usage tracking and analytics
+    "ContextUsage",  # Context usage data structure
     "serve",
     # ID generation (collision-resistant, multi-agent safe)
     "generate_id",
@@ -80,4 +185,55 @@ __all__ = [
     "BaseCollection",
     "FeatureCollection",
     "SpikeCollection",
+    # Agent detection
+    "detect_agent_name",
+    "get_agent_display_name",
+    # Parallel workflow coordination
+    "ParallelWorkflow",
+    "ParallelAnalysis",
+    "AggregateResult",
+    # Type definitions (TypedDict for SDK return types)
+    "BottleneckDict",
+    "WorkRecommendation",
+    "ParallelWorkInfo",
+    "RiskAssessmentDict",
+    "HighRiskTask",
+    "ImpactAnalysisDict",
+    "SessionStartInfo",
+    "ProjectStatus",
+    "ActiveWorkItem",
+    "FeatureSummary",
+    "SessionSummary",
+    "SessionAnalytics",
+    "WorkQueueItem",
+    "SmartPlanResult",
+    "PlanningContext",
+    "TrackCreationResult",
+    "SubagentPrompt",
+    "OrchestrationResult",
+    "ParallelPlanResult",
+    "TaskPrompt",
+    "ParallelGuidelines",
+    "AggregateResultsDict",
+    # Active Learning Persistence
+    "LearningPersistence",
+    "auto_persist_on_session_end",
+    # Computational Reflection (pre-computed context injection)
+    "ComputationalReflection",
+    "get_reflection_context",
+    # Orchestrator Mode Management
+    "OrchestratorMode",
+    "OrchestratorModeManager",
+    # Orchestration helpers for parallel task coordination
+    "delegate_with_id",
+    "get_results_by_task_id",
+    "parallel_delegate",
+    "generate_task_id",
+    # Atomic file operations (Phase 1.3: Session File Tracking)
+    "AtomicFileWriter",
+    "DirectoryLocker",
+    "atomic_rename",
+    "cleanup_orphaned_temp_files",
+    "safe_temp_file",
+    "validate_atomic_write",
 ]

htmlgraph/__init__.pyi

@@ -0,0 +1,123 @@
+"""
+Type stub for htmlgraph package.
+
+This stub provides type information for mypy when the SDK class
+is loaded dynamically via importlib at runtime.
+"""
+
+from htmlgraph.agent_detection import detect_agent_name as detect_agent_name
+from htmlgraph.agent_detection import get_agent_display_name as get_agent_display_name
+from htmlgraph.agents import AgentInterface as AgentInterface
+from htmlgraph.analytics import Analytics as Analytics
+
+# Analytics
+from htmlgraph.analytics import DependencyAnalytics as DependencyAnalytics
+from htmlgraph.atomic_ops import AtomicFileWriter as AtomicFileWriter
+from htmlgraph.atomic_ops import DirectoryLocker as DirectoryLocker
+from htmlgraph.atomic_ops import atomic_rename as atomic_rename
+from htmlgraph.atomic_ops import (
+    cleanup_orphaned_temp_files as cleanup_orphaned_temp_files,
+)
+from htmlgraph.atomic_ops import safe_temp_file as safe_temp_file
+from htmlgraph.atomic_ops import validate_atomic_write as validate_atomic_write
+from htmlgraph.builders import BaseBuilder as BaseBuilder
+from htmlgraph.builders import FeatureBuilder as FeatureBuilder
+from htmlgraph.builders import SpikeBuilder as SpikeBuilder
+from htmlgraph.collections import BaseCollection as BaseCollection
+
+# Collections
+from htmlgraph.collections import FeatureCollection as FeatureCollection
+from htmlgraph.collections import SpikeCollection as SpikeCollection
+from htmlgraph.context_analytics import ContextAnalytics as ContextAnalytics
+from htmlgraph.context_analytics import ContextUsage as ContextUsage
+from htmlgraph.decorators import RetryError as RetryError
+from htmlgraph.decorators import retry as retry
+from htmlgraph.decorators import retry_async as retry_async
+from htmlgraph.edge_index import EdgeIndex as EdgeIndex
+from htmlgraph.edge_index import EdgeRef as EdgeRef
+from htmlgraph.exceptions import ClaimConflictError as ClaimConflictError
+from htmlgraph.exceptions import HtmlGraphError as HtmlGraphError
+from htmlgraph.exceptions import NodeNotFoundError as NodeNotFoundError
+from htmlgraph.exceptions import SessionNotFoundError as SessionNotFoundError
+from htmlgraph.exceptions import ValidationError as ValidationError
+from htmlgraph.find_api import FindAPI as FindAPI
+from htmlgraph.find_api import find as find
+from htmlgraph.find_api import find_all as find_all
+from htmlgraph.graph import CompiledQuery as CompiledQuery
+from htmlgraph.graph import HtmlGraph as HtmlGraph
+from htmlgraph.ids import generate_hierarchical_id as generate_hierarchical_id
+from htmlgraph.ids import generate_id as generate_id
+from htmlgraph.ids import is_legacy_id as is_legacy_id
+from htmlgraph.ids import is_valid_id as is_valid_id
+from htmlgraph.ids import parse_id as parse_id
+from htmlgraph.learning import LearningPersistence as LearningPersistence
+from htmlgraph.learning import (
+    auto_persist_on_session_end as auto_persist_on_session_end,
+)
+from htmlgraph.models import ActivityEntry as ActivityEntry
+from htmlgraph.models import AggregatedMetric as AggregatedMetric
+from htmlgraph.models import Chore as Chore
+from htmlgraph.models import ContextSnapshot as ContextSnapshot
+from htmlgraph.models import Edge as Edge
+from htmlgraph.models import Graph as Graph
+from htmlgraph.models import MaintenanceType as MaintenanceType
+from htmlgraph.models import Node as Node
+from htmlgraph.models import Pattern as Pattern
+from htmlgraph.models import Session as Session
+from htmlgraph.models import SessionInsight as SessionInsight
+from htmlgraph.models import Spike as Spike
+from htmlgraph.models import SpikeType as SpikeType
+from htmlgraph.models import Step as Step
+from htmlgraph.models import WorkType as WorkType
+from htmlgraph.orchestration import delegate_with_id as delegate_with_id
+from htmlgraph.orchestration import generate_task_id as generate_task_id
+from htmlgraph.orchestration import get_results_by_task_id as get_results_by_task_id
+from htmlgraph.orchestration import parallel_delegate as parallel_delegate
+from htmlgraph.orchestrator_mode import OrchestratorMode as OrchestratorMode
+from htmlgraph.orchestrator_mode import (
+    OrchestratorModeManager as OrchestratorModeManager,
+)
+from htmlgraph.parallel import AggregateResult as AggregateResult
+from htmlgraph.parallel import ParallelAnalysis as ParallelAnalysis
+from htmlgraph.parallel import ParallelWorkflow as ParallelWorkflow
+from htmlgraph.query_builder import Condition as Condition
+from htmlgraph.query_builder import Operator as Operator
+from htmlgraph.query_builder import QueryBuilder as QueryBuilder
+from htmlgraph.reflection import ComputationalReflection as ComputationalReflection
+from htmlgraph.reflection import get_reflection_context as get_reflection_context
+from htmlgraph.repo_hash import RepoHash as RepoHash
+from htmlgraph.sdk.core import SDK as SDK
+from htmlgraph.server import serve as serve
+from htmlgraph.session_manager import SessionManager as SessionManager
+from htmlgraph.session_registry import SessionRegistry as SessionRegistry
+from htmlgraph.types import ActiveWorkItem as ActiveWorkItem
+from htmlgraph.types import AggregateResultsDict as AggregateResultsDict
+from htmlgraph.types import BottleneckDict as BottleneckDict
+from htmlgraph.types import FeatureSummary as FeatureSummary
+from htmlgraph.types import HighRiskTask as HighRiskTask
+from htmlgraph.types import ImpactAnalysisDict as ImpactAnalysisDict
+from htmlgraph.types import OrchestrationResult as OrchestrationResult
+from htmlgraph.types import ParallelGuidelines as ParallelGuidelines
+from htmlgraph.types import ParallelPlanResult as ParallelPlanResult
+from htmlgraph.types import ParallelWorkInfo as ParallelWorkInfo
+from htmlgraph.types import PlanningContext as PlanningContext
+from htmlgraph.types import ProjectStatus as ProjectStatus
+from htmlgraph.types import RiskAssessmentDict as RiskAssessmentDict
+from htmlgraph.types import SessionAnalytics as SessionAnalytics
+from htmlgraph.types import SessionStartInfo as SessionStartInfo
+from htmlgraph.types import SessionSummary as SessionSummary
+from htmlgraph.types import SmartPlanResult as SmartPlanResult
+from htmlgraph.types import SubagentPrompt as SubagentPrompt
+from htmlgraph.types import TaskPrompt as TaskPrompt
+from htmlgraph.types import TrackCreationResult as TrackCreationResult
+from htmlgraph.types import WorkQueueItem as WorkQueueItem
+from htmlgraph.types import WorkRecommendation as WorkRecommendation
+from htmlgraph.work_type_utils import infer_work_type as infer_work_type
+from htmlgraph.work_type_utils import infer_work_type_from_id as infer_work_type_from_id
+
+__version__: str
+
+# SDK is imported from htmlgraph.sdk.core (see import above)
+# Re-exported here for backward compatibility
+
+__all__: list[str]

htmlgraph/agent_detection.py

@@ -0,0 +1,127 @@
+"""
+Agent Detection Utilities
+
+Intelligently detect which AI agent/interface is running HtmlGraph.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+
+def detect_agent_name() -> str:
+    """
+    Detect the current agent/interface name based on environment.
+
+    Returns:
+        Agent name (e.g., "claude-code", "gemini", "cli")
+
+    Detection order:
+        1. HTMLGRAPH_AGENT environment variable (explicit override)
+        2. HTMLGRAPH_PARENT_AGENT (set by hooks for session context)
+        3. Gemini detection (GEMINI environment markers) - checked before Claude to allow override
+        4. Claude Code detection (CLAUDECODE env var, parent process)
+        5. Fall back to "cli" only if no AI agent detected
+    """
+    # 1. Explicit override
+    explicit = os.environ.get("HTMLGRAPH_AGENT")
+    if explicit:
+        return explicit.strip()
+
+    # 2. Parent agent context (set by HtmlGraph hooks)
+    parent_agent = os.environ.get("HTMLGRAPH_PARENT_AGENT")
+    if parent_agent:
+        return parent_agent.strip()
+
+    # 3. Gemini detection (checked before Claude to allow explicit override)
+    if _is_gemini():
+        return "gemini"
+
+    # 4. Claude Code detection
+    if _is_claude_code():
+        return "claude-code"
+
+    # 5. Default to CLI only if no AI agent detected
+    return "cli"
+
+
+def _is_claude_code() -> bool:
+    """Check if running in Claude Code environment."""
+    # Check for Claude Code environment variables
+    # CLAUDECODE=1 is set by Claude Code CLI
+    if os.environ.get("CLAUDECODE"):
+        return True
+
+    # CLAUDE_CODE_ENTRYPOINT indicates the entry point (cli, api, etc.)
+    if os.environ.get("CLAUDE_CODE_ENTRYPOINT"):
+        return True
+
+    if os.environ.get("CLAUDE_CODE_VERSION"):
+        return True
+
+    if os.environ.get("CLAUDE_API_KEY"):
+        return True
+
+    # Check for .claude directory in user home or project
+    claude_config = Path.home() / ".claude"
+    if claude_config.exists():
+        # Check if there's a recent session or settings
+        settings = claude_config / "settings.json"
+        if settings.exists():
+            return True
+
+    # Check parent process name (heuristic)
+    try:
+        import psutil
+
+        current = psutil.Process()
+        parent = current.parent()
+        if parent:
+            parent_name = parent.name().lower()
+            if "claude" in parent_name:
+                return True
+    except (ImportError, Exception):
+        pass
+
+    return False
+
+
+def _is_gemini() -> bool:
+    """Check if running in Gemini environment."""
+    # Check for Gemini-specific environment variables
+    if os.environ.get("GEMINI_API_KEY"):
+        return True
+
+    if os.environ.get("GOOGLE_AI_STUDIO"):
+        return True
+
+    # Check for gemini in command line args
+    if any("gemini" in arg.lower() for arg in sys.argv):
+        return True
+
+    return False
+
+
+def get_agent_display_name(agent: str) -> str:
+    """
+    Get a human-friendly display name for an agent.
+
+    Args:
+        agent: Agent identifier (e.g., "claude", "cli", "gemini")
+
+    Returns:
+        Display name (e.g., "Claude", "CLI", "Gemini")
+    """
+    display_names = {
+        "claude": "Claude",
+        "claude-code": "Claude Code",
+        "gemini": "Gemini",
+        "cli": "CLI",
+        "haiku": "Haiku",
+        "opus": "Opus",
+        "sonnet": "Sonnet",
+        "claude-opus-4-5-20251101": "Claude Opus 4.5",
+        "claude-sonnet-4-20250514": "Claude Sonnet 4",
+    }
+
+    return display_names.get(agent.lower(), agent.title())