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

htmlgraph/sdk/__init__.py

@@ -0,0 +1,398 @@
+"""
+HtmlGraph SDK - Modular Architecture
+
+This package provides a fluent, ergonomic API for AI agents with:
+- Auto-discovery of .htmlgraph directory
+- Method chaining for all operations
+- Context managers for auto-save
+- Batch operations
+- Minimal boilerplate
+
+The SDK is composed from specialized mixins:
+- AnalyticsRegistry: Analytics properties (analytics, dep_analytics, context, etc.)
+- SessionManagerMixin: Session lifecycle (start_session, end_session)
+- SessionHandoffMixin: Handoff operations (set_session_handoff, end_session_with_handoff)
+- SessionContinuityMixin: Continuity (continue_from_last)
+- SessionInfoMixin: Session info (get_session_start_info, get_active_work_item)
+- PlanningMixin: Planning methods (find_bottlenecks, recommend_next_work, etc.)
+- OrchestrationMixin: Subagent spawning (spawn_explorer, spawn_coder, orchestrate)
+- OperationsMixin: Server, hooks, events (start_server, install_hooks, etc.)
+- CoreMixin: Database, refs, utilities (db, query, ref, reload, etc.)
+- TaskAttributionMixin: Task attribution (get_task_attribution, get_subagent_work)
+- HelpMixin: Help system (help, __dir__)
+
+Public API exports maintain backward compatibility.
+All existing imports continue to work:
+    from htmlgraph import SDK  # Still works
+    from htmlgraph.sdk import SDK  # Also works
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from htmlgraph.agent_detection import detect_agent_name
+from htmlgraph.agents import AgentInterface
+from htmlgraph.collections import (
+    BaseCollection,
+    BugCollection,
+    ChoreCollection,
+    EpicCollection,
+    FeatureCollection,
+    PhaseCollection,
+    SpikeCollection,
+    TaskDelegationCollection,
+    TodoCollection,
+)
+from htmlgraph.collections.insight import InsightCollection
+from htmlgraph.collections.metric import MetricCollection
+from htmlgraph.collections.pattern import PatternCollection
+from htmlgraph.collections.session import SessionCollection
+from htmlgraph.db.schema import HtmlGraphDB
+from htmlgraph.graph import HtmlGraph
+from htmlgraph.sdk.analytics import AnalyticsRegistry
+from htmlgraph.sdk.base import BaseSDK
+from htmlgraph.sdk.constants import SDKSettings
+from htmlgraph.sdk.discovery import (
+    auto_discover_agent,
+    discover_htmlgraph_dir,
+    find_project_root,
+)
+from htmlgraph.sdk.help import HelpMixin
+from htmlgraph.sdk.mixins import CoreMixin, TaskAttributionMixin
+from htmlgraph.sdk.operations import OperationsMixin
+from htmlgraph.sdk.orchestration import OrchestrationMixin
+from htmlgraph.sdk.planning import PlanningMixin
+from htmlgraph.sdk.session import (
+    SessionContinuityMixin,
+    SessionHandoffMixin,
+    SessionInfoMixin,
+    SessionManagerMixin,
+)
+from htmlgraph.session_manager import SessionManager
+from htmlgraph.session_warning import check_and_show_warning
+from htmlgraph.system_prompts import SystemPromptManager
+from htmlgraph.track_builder import TrackCollection
+
+
+class SDK(
+    AnalyticsRegistry,
+    SessionManagerMixin,
+    SessionHandoffMixin,
+    SessionContinuityMixin,
+    SessionInfoMixin,
+    PlanningMixin,
+    OrchestrationMixin,
+    OperationsMixin,
+    CoreMixin,
+    TaskAttributionMixin,
+    HelpMixin,
+):
+    """
+    Main SDK interface for AI agents.
+
+    Auto-discovers .htmlgraph directory and provides fluent API for all collections.
+
+    Available Collections:
+        - features: Feature work items with builder support
+        - bugs: Bug reports
+        - chores: Maintenance and chore tasks
+        - spikes: Investigation and research spikes
+        - epics: Large bodies of work
+        - phases: Project phases
+        - sessions: Agent sessions
+        - tracks: Work tracks
+        - agents: Agent information
+        - todos: Persistent task tracking (mirrors TodoWrite API)
+        - patterns: Workflow patterns (optimal/anti-pattern)
+        - insights: Session health insights
+        - metrics: Aggregated time-series metrics
+
+    This SDK class is a thin composition layer that inherits from specialized mixins:
+    - AnalyticsRegistry: analytics, dep_analytics, context, pattern_learning properties
+    - SessionManagerMixin: start_session, end_session, _ensure_session_exists
+    - SessionHandoffMixin: set_session_handoff, end_session_with_handoff
+    - SessionContinuityMixin: continue_from_last
+    - SessionInfoMixin: get_session_start_info, get_active_work_item, track_activity
+    - PlanningMixin: find_bottlenecks, recommend_next_work, get_parallel_work, etc.
+    - OrchestrationMixin: orchestrator, spawn_explorer, spawn_coder, orchestrate
+    - OperationsMixin: start_server, install_hooks, analyze_session, etc.
+    - CoreMixin: db, query, ref, reload, summary, my_work, next_task, etc.
+    - TaskAttributionMixin: get_task_attribution, get_subagent_work
+    - HelpMixin: help, __dir__
+
+    Example:
+        sdk = SDK(agent="claude")
+
+        # Work with features (has builder support)
+        feature = sdk.features.create("User Auth")
+            .set_priority("high")
+            .add_steps(["Login", "Logout"])
+            .save()
+
+        # Work with bugs
+        high_bugs = sdk.bugs.where(status="todo", priority="high")
+        with sdk.bugs.edit("bug-001") as bug:
+            bug.status = "in-progress"
+
+        # Strategic analytics
+        bottlenecks = sdk.find_bottlenecks(top_n=5)
+        recommendations = sdk.recommend_next_work(agent_count=3)
+    """
+
+    def __init__(
+        self,
+        directory: Path | str | None = None,
+        agent: str | None = None,
+        parent_session: str | None = None,
+        db_path: str | None = None,
+    ):
+        """
+        Initialize SDK.
+
+        Args:
+            directory: Path to .htmlgraph directory (auto-discovered if not provided)
+            agent: REQUIRED - Agent identifier for operations.
+                Used to attribute work items (features, spikes, bugs, etc) to the agent.
+                Examples: agent='explorer', agent='coder', agent='tester'
+                Critical for: Work attribution, result retrieval, orchestrator tracking
+                Falls back to: CLAUDE_AGENT_NAME env var, then detect_agent_name()
+                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)
+        """
+        if directory is None:
+            directory = self._discover_htmlgraph()
+
+        if agent is None:
+            # Try environment variable fallback
+            agent = os.getenv("CLAUDE_AGENT_NAME")
+
+        if agent is None:
+            # Try automatic detection
+            detected = detect_agent_name()
+            if detected and detected != "cli":
+                # Only accept detected if it's not the default fallback
+                agent = detected
+            else:
+                # No valid agent found - fail fast with helpful error message
+                raise ValueError(
+                    "Agent identifier is required for work attribution. "
+                    "Pass agent='name' to SDK() initialization. "
+                    "Examples: SDK(agent='explorer'), SDK(agent='coder'), SDK(agent='tester')\n"
+                    "Alternatively, set CLAUDE_AGENT_NAME environment variable.\n"
+                    "Critical for: Work attribution, result retrieval, orchestrator tracking"
+                )
+
+        self._directory = Path(directory)
+        self._agent_id = agent
+        self._parent_session = parent_session or os.getenv("HTMLGRAPH_PARENT_SESSION")
+
+        # Initialize SQLite database (Phase 2)
+        self._db = HtmlGraphDB(
+            db_path or str(Path.home() / ".htmlgraph" / "htmlgraph.db")
+        )
+        self._db.connect()
+        self._db.create_tables()
+
+        # Initialize underlying HtmlGraphs first (for backward compatibility and sharing)
+        # These are shared with SessionManager to avoid double-loading features
+        self._graph = HtmlGraph(self._directory / "features")
+        self._bugs_graph = HtmlGraph(self._directory / "bugs")
+
+        # Initialize SessionManager with shared graph instances to avoid double-loading
+        self.session_manager = SessionManager(
+            self._directory,
+            features_graph=self._graph,
+            bugs_graph=self._bugs_graph,
+        )
+
+        # Agent interface (for backward compatibility)
+        self._agent_interface = AgentInterface(
+            self._directory / "features", agent_id=agent
+        )
+
+        # Collection interfaces - all work item types (all with builder support)
+        self.features = FeatureCollection(self)
+        self.bugs = BugCollection(self)
+        self.chores = ChoreCollection(self)
+        self.spikes = SpikeCollection(self)
+        self.epics = EpicCollection(self)
+        self.phases = PhaseCollection(self)
+
+        # Non-work collections
+        self.sessions: SessionCollection = SessionCollection(self)
+        self.tracks: TrackCollection = TrackCollection(
+            self
+        )  # Use specialized collection with builder support
+        self.agents: BaseCollection[Any] = BaseCollection(self, "agents", "agent")
+
+        # Learning collections (Active Learning Persistence)
+        self.patterns = PatternCollection(self)
+        self.insights = InsightCollection(self)
+        self.metrics = MetricCollection(self)
+
+        # Todo collection (persistent task tracking)
+        self.todos = TodoCollection(self)
+
+        # Task delegation collection (observability for spawned agents)
+        self.task_delegations = TaskDelegationCollection(self)
+
+        # Create learning directories if needed
+        (self._directory / "patterns").mkdir(exist_ok=True)
+        (self._directory / "insights").mkdir(exist_ok=True)
+        (self._directory / "metrics").mkdir(exist_ok=True)
+        (self._directory / "todos").mkdir(exist_ok=True)
+        (self._directory / "task-delegations").mkdir(exist_ok=True)
+
+        # Initialize RefManager and set on all collections
+        from htmlgraph.refs import RefManager
+
+        self.refs = RefManager(self._directory)
+
+        # Set ref manager on all work item collections
+        self.features.set_ref_manager(self.refs)
+        self.bugs.set_ref_manager(self.refs)
+        self.chores.set_ref_manager(self.refs)
+        self.spikes.set_ref_manager(self.refs)
+        self.epics.set_ref_manager(self.refs)
+        self.phases.set_ref_manager(self.refs)
+        self.tracks.set_ref_manager(self.refs)
+        self.todos.set_ref_manager(self.refs)
+
+        # Analytics engine (centralized analytics management with lazy loading)
+        from htmlgraph.sdk.analytics.helpers import create_analytics_engine
+
+        self._analytics_engine = create_analytics_engine(
+            sdk=self, graph=self._graph, directory=self._directory
+        )
+
+        # Lazy-loaded orchestrator for subagent management
+        self._orchestrator: Any = None
+
+        # System prompt manager (lazy-loaded)
+        self._system_prompts: SystemPromptManager | None = None
+
+        # Session warning system (workaround for Claude Code hook bug #10373)
+        # Shows orchestrator instructions on first SDK usage per session
+        self._session_warning = check_and_show_warning(
+            self._directory,
+            agent=self._agent_id,
+            session_id=None,  # Will be set by session manager if available
+        )
+
+    @staticmethod
+    def _discover_htmlgraph() -> Path:
+        """
+        Auto-discover .htmlgraph directory.
+
+        Searches current directory and parents.
+        """
+        current = Path.cwd()
+
+        # Check current directory
+        if (current / ".htmlgraph").exists():
+            return current / ".htmlgraph"
+
+        # Check parent directories
+        for parent in current.parents:
+            if (parent / ".htmlgraph").exists():
+                return parent / ".htmlgraph"
+
+        # Default to current directory
+        return current / ".htmlgraph"
+
+    @property
+    def agent(self) -> str | None:
+        """Get current agent ID."""
+        return self._agent_id
+
+    @property
+    def system_prompts(self) -> SystemPromptManager:
+        """
+        Access system prompt management.
+
+        Provides methods to:
+        - Get active prompt (project override OR plugin default)
+        - Create/delete project-level overrides
+        - Validate token counts
+        - Get prompt statistics
+
+        Lazy-loaded on first access.
+
+        Returns:
+            SystemPromptManager instance
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+
+            # Get active prompt
+            >>> prompt = sdk.system_prompts.get_active()
+
+            # Create project override
+            >>> sdk.system_prompts.create("## Custom prompt\\n...")
+
+            # Validate token count
+            >>> result = sdk.system_prompts.validate()
+            >>> print(result['message'])
+
+            # Get statistics
+            >>> stats = sdk.system_prompts.get_stats()
+            >>> print(f"Source: {stats['source']}")
+        """
+        if self._system_prompts is None:
+            self._system_prompts = SystemPromptManager(self._directory)
+        return self._system_prompts
+
+    def dismiss_session_warning(self) -> bool:
+        """
+        Dismiss the session warning after reading it.
+
+        IMPORTANT: Call this as your FIRST action after seeing the orchestrator
+        warning. This confirms you've read the instructions.
+
+        Returns:
+            True if warning was dismissed, False if already dismissed
+
+        Example:
+            sdk = SDK(agent="claude")
+            # Warning shown automatically...
+
+            # First action: dismiss to confirm you read it
+            sdk.dismiss_session_warning()
+
+            # Now proceed with orchestration
+            sdk.spawn_coder(feature_id="feat-123", ...)
+        """
+        if self._session_warning:
+            return self._session_warning.dismiss(
+                agent=self._agent_id,
+                session_id=None,
+            )
+        return False
+
+    def get_warning_status(self) -> dict[str, Any]:
+        """
+        Get current session warning status.
+
+        Returns:
+            Dict with dismissed status, timestamp, and show count
+        """
+        if self._session_warning:
+            return self._session_warning.get_status()
+        return {"dismissed": True, "show_count": 0}
+
+
+__all__ = [
+    # Core SDK class
+    "SDK",
+    "BaseSDK",
+    # Discovery utilities
+    "find_project_root",
+    "discover_htmlgraph_dir",
+    "auto_discover_agent",
+    # Constants and configuration
+    "SDKSettings",
+]

htmlgraph/sdk/__init__.pyi

@@ -0,0 +1,14 @@
+"""
+Type stub for htmlgraph.sdk package.
+
+Exports SDK from the core module.
+"""
+
+from htmlgraph.sdk.base import BaseSDK as BaseSDK
+from htmlgraph.sdk.constants import SDKSettings as SDKSettings
+from htmlgraph.sdk.core import SDK as SDK
+from htmlgraph.sdk.discovery import auto_discover_agent as auto_discover_agent
+from htmlgraph.sdk.discovery import discover_htmlgraph_dir as discover_htmlgraph_dir
+from htmlgraph.sdk.discovery import find_project_root as find_project_root
+
+__all__: list[str]

htmlgraph/sdk/analytics/__init__.py

@@ -0,0 +1,19 @@
+"""
+Analytics submodule for SDK.
+
+Provides lazy-loaded analytics interfaces:
+- Analytics: Work type distribution and session analytics
+- DependencyAnalytics: Graph-based dependency analysis
+- CrossSessionAnalytics: Git commit-based cross-session tracking
+- ContextAnalytics: Context usage tracking
+
+Exported for backward compatibility.
+"""
+
+from htmlgraph.sdk.analytics.engine import AnalyticsEngine
+from htmlgraph.sdk.analytics.registry import AnalyticsRegistry
+
+__all__ = [
+    "AnalyticsEngine",
+    "AnalyticsRegistry",
+]

htmlgraph/sdk/analytics/engine.py

@@ -0,0 +1,155 @@
+"""
+Analytics Engine for SDK.
+
+Centralized management of all analytics interfaces with lazy loading.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.analytics import (
+        Analytics,
+        CrossSessionAnalytics,
+        DependencyAnalytics,
+    )
+    from htmlgraph.context_analytics import ContextAnalytics
+    from htmlgraph.graph import HtmlGraph
+
+
+class AnalyticsEngine:
+    """
+    Centralized analytics engine with lazy loading.
+
+    Manages all analytics interfaces:
+    - analytics: Work type distribution and session analytics
+    - dep_analytics: Dependency-aware graph analysis
+    - cross_session_analytics: Git commit-based tracking
+    - context: Context usage tracking
+    - pattern_learning: Pattern learning (lazy-loaded)
+
+    All analytics are lazy-loaded to improve SDK initialization performance.
+
+    Example:
+        >>> from htmlgraph import SDK
+        >>> sdk = SDK(agent="claude")
+        >>>
+        >>> # Analytics are lazy-loaded on first access
+        >>> dist = sdk.analytics.work_type_distribution()
+        >>> bottlenecks = sdk.dep_analytics.find_bottlenecks()
+        >>> usage = sdk.context.get_session_usage("session-123")
+    """
+
+    def __init__(self, sdk: Any, graph: HtmlGraph, directory: Any):
+        """
+        Initialize analytics engine.
+
+        Args:
+            sdk: SDK instance (parent)
+            graph: HtmlGraph instance
+            directory: .htmlgraph directory path
+        """
+        self._sdk = sdk
+        self._graph = graph
+        self._directory = directory
+
+        # Lazy-loaded analytics instances
+        self._analytics: Analytics | None = None
+        self._dep_analytics: DependencyAnalytics | None = None
+        self._cross_session_analytics: CrossSessionAnalytics | None = None
+        self._context_analytics: ContextAnalytics | None = None
+        self._pattern_learning: Any = None
+
+    @property
+    def analytics(self) -> Analytics:
+        """
+        Get work type analytics interface (lazy-loaded).
+
+        Provides:
+        - work_type_distribution(): Analyze work type distribution
+        - spike_to_feature_ratio(): Calculate spike/feature ratio
+        - maintenance_burden(): Calculate maintenance percentage
+        - get_sessions_by_work_type(): Filter sessions by work type
+
+        Returns:
+            Analytics instance
+        """
+        if self._analytics is None:
+            from htmlgraph.analytics import Analytics
+
+            self._analytics = Analytics(self._sdk)
+        return self._analytics
+
+    @property
+    def dep_analytics(self) -> DependencyAnalytics:
+        """
+        Get dependency analytics interface (lazy-loaded).
+
+        Provides:
+        - find_bottlenecks(): Identify blocking work
+        - find_critical_path(): Find longest dependency chain
+        - find_parallelization_opportunities(): Find parallel work
+        - recommend_next_tasks(): Prioritize work
+        - assess_risk(): Identify high-risk dependencies
+
+        Returns:
+            DependencyAnalytics instance
+        """
+        if self._dep_analytics is None:
+            from htmlgraph.analytics import DependencyAnalytics
+
+            self._dep_analytics = DependencyAnalytics(self._graph)
+        return self._dep_analytics
+
+    @property
+    def cross_session_analytics(self) -> CrossSessionAnalytics:
+        """
+        Get cross-session analytics interface (lazy-loaded).
+
+        Provides:
+        - work_in_commit_range(): Get work between commits
+        - sessions_for_feature(): Find sessions for a feature
+        - work_by_author(): Analyze work by author
+
+        Returns:
+            CrossSessionAnalytics instance
+        """
+        if self._cross_session_analytics is None:
+            from htmlgraph.analytics import CrossSessionAnalytics
+
+            self._cross_session_analytics = CrossSessionAnalytics(self._sdk)
+        return self._cross_session_analytics
+
+    @property
+    def context(self) -> ContextAnalytics:
+        """
+        Get context analytics interface (lazy-loaded).
+
+        Provides:
+        - get_session_usage(): Get session context usage
+        - get_feature_usage(): Get feature context usage
+        - get_track_usage(): Get track context usage
+
+        Returns:
+            ContextAnalytics instance
+        """
+        if self._context_analytics is None:
+            from htmlgraph.context_analytics import ContextAnalytics
+
+            self._context_analytics = ContextAnalytics(self._sdk)
+        return self._context_analytics
+
+    @property
+    def pattern_learning(self) -> Any:
+        """
+        Get pattern learning interface (lazy-loaded).
+
+        Returns:
+            PatternLearner instance
+        """
+        if self._pattern_learning is None:
+            from htmlgraph.analytics.pattern_learning import PatternLearner
+
+            self._pattern_learning = PatternLearner(self._directory)
+        return self._pattern_learning