htmlgraph 0.26.5__tar.gz → 0.26.6__tar.gz

{htmlgraph-0.26.5 → htmlgraph-0.26.6}/.gitignore

@@ -53,6 +53,14 @@ Thumbs.db
 .htmlgraph/sessions/*.jsonl
 .htmlgraph/events/*.jsonl
 .htmlgraph/parent-activity.json
+.htmlgraph/logs/errors/
+
+# HtmlGraph backup and test files
+.htmlgraph/index.sqlite.backup
+.htmlgraph/*.backup
+.htmlgraph/test_*.db
+.htmlgraph/database.db
+.htmlgraph/.htmlgraph/  # Prevent nested structure corruption
 
 # Keep these (source of truth):
 # - .htmlgraph/features/

{htmlgraph-0.26.5 → htmlgraph-0.26.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htmlgraph
-Version: 0.26.5
+Version: 0.26.6
 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.26.6/examples/demo_agent_planning.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""
+Demo: AI Agent Strategic Planning with HtmlGraph
+
+Shows how AI agents can use the strategic planning features to:
+- Find bottlenecks blocking the most work
+- Identify parallel work opportunities
+- Get smart recommendations on what to work on next
+- Assess project risks
+- Analyze impact of completing tasks
+
+This is the AGENT-FRIENDLY interface - simple dicts, no complex objects.
+"""
+
+from htmlgraph import SDK
+
+
+def main():
+    print("\n" + "🤖 " * 35)
+    print("AI AGENT STRATEGIC PLANNING DEMO")
+    print("🤖 " * 35)
+
+    # Initialize SDK with agent ID
+    sdk = SDK(agent="claude")
+
+    # =========================================================================
+    # 1. FIND BOTTLENECKS
+    # =========================================================================
+    print("\n1. 🚧 Finding Bottlenecks (what's blocking the most work?)")
+    print("=" * 70)
+
+    bottlenecks = sdk.find_bottlenecks(top_n=3)
+
+    if bottlenecks:
+        print(f"\nFound {len(bottlenecks)} bottlenecks:")
+        for i, bn in enumerate(bottlenecks, 1):
+            print(f"\n{i}. {bn['title']}")
+            print(f"   Status: {bn['status']} | Priority: {bn['priority']}")
+            print(f"   Blocking: {bn['blocks_count']} tasks")
+            print(f"   Impact score: {bn['impact_score']:.1f}")
+            if bn["blocked_tasks"]:
+                print(f"   Blocks: {', '.join(bn['blocked_tasks'][:3])}")
+    else:
+        print("  ✓ No bottlenecks found!")
+
+    # =========================================================================
+    # 2. GET PARALLEL WORK OPPORTUNITIES
+    # =========================================================================
+    print("\n2. ⚡ Finding Parallel Work (what can multiple agents do simultaneously?)")
+    print("=" * 70)
+
+    parallel = sdk.get_parallel_work(max_agents=5)
+
+    print(
+        f"\nMax parallelism: {parallel['max_parallelism']} tasks can be worked on at once"
+    )
+    print(f"Total ready now: {parallel['total_ready']} tasks")
+    print(f"Dependency levels: {parallel['level_count']}")
+
+    if parallel["ready_now"]:
+        print(f"\nReady to start immediately ({len(parallel['ready_now'])} tasks):")
+        for task_id in parallel["ready_now"]:
+            feature = sdk.features.get(task_id)
+            if feature:
+                print(f"  - {feature.title} ({feature.priority} priority)")
+
+    # =========================================================================
+    # 3. GET SMART RECOMMENDATIONS
+    # =========================================================================
+    print("\n3. 💡 Smart Recommendations (what should I prioritize?)")
+    print("=" * 70)
+
+    recs = sdk.recommend_next_work(agent_count=3)
+
+    if recs:
+        print(f"\nTop {len(recs)} recommended tasks:")
+        for i, rec in enumerate(recs, 1):
+            print(f"\n{i}. {rec['title']}")
+            print(f"   Priority: {rec['priority']} | Score: {rec['score']:.2f}")
+            if rec["estimated_hours"] > 0:
+                print(f"   Estimated: {rec['estimated_hours']:.1f} hours")
+            print(f"   Unlocks: {rec['unlocks_count']} tasks")
+            print("   Reasons:")
+            for reason in rec["reasons"][:3]:
+                print(f"     - {reason}")
+    else:
+        print("  ✓ No pending tasks to recommend!")
+
+    # =========================================================================
+    # 4. ASSESS RISKS
+    # =========================================================================
+    print("\n4. ⚠️  Risk Assessment (are there dependency issues?)")
+    print("=" * 70)
+
+    risks = sdk.assess_risks()
+
+    if risks["high_risk_count"] > 0:
+        print(f"\n⚠️  {risks['high_risk_count']} high-risk tasks found:")
+        for task in risks["high_risk_tasks"][:3]:
+            print(f"\n  {task['title']} (risk: {task['risk_score']:.2f})")
+            for factor in task["risk_factors"]:
+                print(f"    - {factor}")
+    else:
+        print("  ✓ No high-risk tasks!")
+
+    if risks["circular_dependencies"]:
+        print(f"\n⚠️  {len(risks['circular_dependencies'])} circular dependencies:")
+        for cycle in risks["circular_dependencies"][:3]:
+            print(f"    - {' → '.join(cycle)}")
+    else:
+        print("  ✓ No circular dependencies")
+
+    if risks["orphaned_count"] > 0:
+        print(f"\n⚠️  {risks['orphaned_count']} orphaned tasks (no dependents)")
+    else:
+        print("  ✓ No orphaned tasks")
+
+    if risks["recommendations"]:
+        print("\nRecommendations:")
+        for rec in risks["recommendations"][:3]:
+            print(f"  • {rec}")
+
+    # =========================================================================
+    # 5. ANALYZE IMPACT (if there's a task in progress)
+    # =========================================================================
+    print("\n5. 📊 Impact Analysis (what does completing a task unlock?)")
+    print("=" * 70)
+
+    in_progress = sdk.features.where(status="in-progress")
+    if in_progress:
+        task = in_progress[0]
+        impact = sdk.analyze_impact(task.id)
+
+        print(f"\nAnalyzing: {task.title}")
+        print(f"  Direct dependents: {impact['direct_dependents']}")
+        print(f"  Total downstream impact: {impact['total_impact']} tasks")
+        print(
+            f"  Completion unlocks: {impact['completion_impact']:.1f}% of remaining work"
+        )
+        if impact["affected_tasks"]:
+            print(f"  Unlocks: {', '.join(impact['affected_tasks'][:5])}")
+    else:
+        print("  No in-progress tasks to analyze")
+
+    # =========================================================================
+    # AGENT DECISION-MAKING EXAMPLE
+    # =========================================================================
+    print("\n" + "=" * 70)
+    print("🤖 AGENT DECISION FLOW EXAMPLE")
+    print("=" * 70)
+
+    print("\nHow an AI agent might use these features:")
+    print("\n1. Check for bottlenecks → Focus on unblocking high-impact work")
+    print("2. Get recommendations → See what's most valuable to work on")
+    print("3. Check parallel work → Coordinate with other agents if available")
+    print("4. Assess risks → Be aware of potential issues")
+    print("5. Analyze impact → Understand the value of completing tasks")
+
+    if recs:
+        top_rec = recs[0]
+        print(f"\n💡 SUGGESTED ACTION: Work on '{top_rec['title']}'")
+        print(
+            f"   Why: Score {top_rec['score']:.1f} - {', '.join(top_rec['reasons'][:2])}"
+        )
+
+    print("\n" + "=" * 70)
+    print("✅ Strategic planning features ready for AI agents!")
+    print("=" * 70 + "\n")
+
+
+if __name__ == "__main__":
+    main()

htmlgraph-0.26.6/examples/demo_real_project_analytics.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""
+Demo of dependency analytics on the real HtmlGraph project.
+
+Shows how to use SDK.dep_analytics to analyze the actual project dependencies.
+"""
+
+from htmlgraph import SDK
+
+
+def main():
+    print("\n" + "📊 " * 35)
+    print("HTMLGRAPH PROJECT - DEPENDENCY ANALYTICS")
+    print("📊 " * 35)
+
+    # Initialize SDK
+    sdk = SDK(agent="claude")
+
+    print("\n1. Finding Bottlenecks (features blocking the most work)...")
+    print("=" * 70)
+
+    bottlenecks = sdk.dep_analytics.find_bottlenecks(
+        status_filter=["in-progress", "todo", "blocked"], top_n=5
+    )
+
+    if bottlenecks:
+        for i, bn in enumerate(bottlenecks, 1):
+            print(f"\n{i}. {bn.title}")
+            print(f"   Status: {bn.status} | Priority: {bn.priority}")
+            print(
+                f"   Blocking: {bn.transitive_blocking} features (impact: {bn.weighted_impact:.1f})"
+            )
+            if bn.blocked_nodes:
+                print(f"   Directly blocks: {', '.join(bn.blocked_nodes[:3])}")
+    else:
+        print("  ✓ No bottlenecks found!")
+
+    print("\n2. Parallelization Opportunities (what can we work on simultaneously?)")
+    print("=" * 70)
+
+    parallel = sdk.dep_analytics.find_parallelizable_work(status="todo")
+
+    print(
+        f"\nMax parallelism: {parallel.max_parallelism} features can be worked on at once"
+    )
+
+    if parallel.dependency_levels:
+        print(
+            f"\nCurrent level (ready to start): {len(parallel.dependency_levels[0].nodes)} features"
+        )
+        for node_id in parallel.dependency_levels[0].nodes[:5]:
+            feature = sdk.features.get(node_id)
+            if feature:
+                print(f"  - {feature.title} ({feature.priority} priority)")
+
+    print("\n3. Work Recommendations (what should we prioritize?)")
+    print("=" * 70)
+
+    recs = sdk.dep_analytics.recommend_next_tasks(agent_count=3, lookahead=5)
+
+    if recs.recommendations:
+        print(f"\nTop {len(recs.recommendations)} recommended tasks:")
+        for i, rec in enumerate(recs.recommendations[:5], 1):
+            print(f"\n{i}. {rec.title}")
+            print(f"   Priority: {rec.priority} | Score: {rec.score:.2f}")
+            print(f"   Reasons: {', '.join(rec.reasons[:2])}")
+            if rec.unlocks:
+                print(f"   Unlocks: {len(rec.unlocks)} features")
+    else:
+        print("  ✓ No pending tasks to recommend!")
+
+    print("\n4. Risk Assessment (are there dependency issues?)")
+    print("=" * 70)
+
+    risk = sdk.dep_analytics.assess_dependency_risk(spof_threshold=2)
+
+    if risk.high_risk:
+        print(f"\n⚠️  High-risk nodes: {len(risk.high_risk)}")
+        for node in risk.high_risk[:3]:
+            print(f"\n  {node.title} (risk: {node.risk_score:.2f})")
+            for factor in node.risk_factors:
+                print(f"    - [{factor.severity}] {factor.description}")
+    else:
+        print("  ✓ No high-risk dependencies!")
+
+    if risk.circular_dependencies:
+        print(f"\n⚠️  Circular dependencies: {len(risk.circular_dependencies)}")
+        for cycle in risk.circular_dependencies[:3]:
+            print(f"    - {' -> '.join(cycle)}")
+    else:
+        print("  ✓ No circular dependencies")
+
+    if risk.orphaned_nodes:
+        print(f"\n⚠️  Orphaned nodes (no dependents): {len(risk.orphaned_nodes)}")
+    else:
+        print("  ✓ No orphaned nodes")
+
+    if risk.recommendations:
+        print("\nRecommendations:")
+        for rec in risk.recommendations[:3]:
+            print(f"  • {rec}")
+
+    print("\n5. Impact Analysis (what does completing a feature unlock?)")
+    print("=" * 70)
+
+    # Find a feature to analyze
+    in_progress = sdk.features.where(status="in-progress")
+    if in_progress:
+        feature = in_progress[0]
+        impact = sdk.dep_analytics.impact_analysis(feature.id)
+
+        print(f"\nAnalyzing: {feature.title}")
+        print(f"  Direct dependents: {impact.direct_dependents}")
+        print(f"  Transitive impact: {impact.transitive_dependents} features")
+        print(
+            f"  Completion unlocks: {impact.completion_impact:.1f}% of remaining work"
+        )
+
+        if impact.affected_nodes:
+            print(f"  Affects: {', '.join(impact.affected_nodes[:5])}")
+    else:
+        print("  No in-progress features to analyze")
+
+    print("\n" + "=" * 70)
+    print("✅ Dependency analytics complete!")
+    print("=" * 70 + "\n")
+
+
+if __name__ == "__main__":
+    main()

htmlgraph-0.26.6/examples/demo_sdk_operations.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""
+SDK Operations Demo - Create features, tracks, and spikes for dashboard monitoring
+"""
+
+import time
+from datetime import datetime
+
+from htmlgraph import SDK
+
+# Initialize SDK
+sdk = SDK(agent="demo-agent")
+
+# Track events with timestamps
+events = []
+
+
+def log_event(event_type: str, details: str):
+    """Log event with timestamp"""
+    timestamp = datetime.now().isoformat()
+    event_entry = {"timestamp": timestamp, "type": event_type, "details": details}
+    events.append(event_entry)
+    print(f"[{timestamp}] {event_type}: {details}")
+
+
+# ============================================================================
+# STEP 1: Create a track
+# ============================================================================
+print("\n" + "=" * 80)
+print("STEP 1: Creating Track 'Agent Orchestration Demo'")
+print("=" * 80)
+
+track = sdk.tracks.create("Agent Orchestration Demo").priority("high").save()
+
+log_event("TRACK_CREATED", f"Track created: {track.id} - 'Agent Orchestration Demo'")
+time.sleep(2)  # Wait for event to propagate
+
+# ============================================================================
+# STEP 2: Create 5 features linked to the track
+# ============================================================================
+print("\n" + "=" * 80)
+print("STEP 2: Creating 5 Features linked to track")
+print("=" * 80)
+
+features = []
+for i in range(1, 6):
+    feature = sdk.features.create(f"Demo Feature {i}")
+    feature.set_track(track.id)
+    feature.add_steps(
+        [
+            "Step 1: Setup component",
+            "Step 2: Implement functionality",
+            "Step 3: Run tests",
+        ]
+    )
+    feature.save()
+
+    features.append(feature)
+    log_event("FEATURE_CREATED", f"Feature {i} created: {feature.id}")
+
+    # Space out feature creation events
+    time.sleep(2)
+
+# ============================================================================
+# STEP 3: Update feature statuses to simulate progress
+# ============================================================================
+print("\n" + "=" * 80)
+print("STEP 3: Updating Feature Statuses")
+print("=" * 80)
+
+# Update Feature 1 status to done
+features[0].status = "done"
+sdk.features._ensure_graph().update(features[0])
+log_event("FEATURE_STATUS_CHANGED", f"Feature 1 ({features[0].id}) marked as DONE")
+time.sleep(2)
+
+# Update Feature 2 status to in-progress
+features[1].status = "in-progress"
+sdk.features._ensure_graph().update(features[1])
+log_event(
+    "FEATURE_STATUS_CHANGED", f"Feature 2 ({features[1].id}) marked as IN_PROGRESS"
+)
+time.sleep(2)
+
+# Update Feature 3 status to in-progress
+features[2].status = "in-progress"
+sdk.features._ensure_graph().update(features[2])
+log_event(
+    "FEATURE_STATUS_CHANGED", f"Feature 3 ({features[2].id}) marked as IN_PROGRESS"
+)
+time.sleep(2)
+
+# Update Feature 4 status to done
+features[3].status = "done"
+sdk.features._ensure_graph().update(features[3])
+log_event("FEATURE_STATUS_CHANGED", f"Feature 4 ({features[3].id}) marked as DONE")
+time.sleep(2)
+
+# Feature 5 stays pending (todo status)
+log_event("FEATURE_STATUS_UNCHANGED", f"Feature 5 ({features[4].id}) remaining PENDING")
+time.sleep(2)
+
+# ============================================================================
+# STEP 4: Create spikes for investigation
+# ============================================================================
+print("\n" + "=" * 80)
+print("STEP 4: Creating Spikes")
+print("=" * 80)
+
+spike1 = sdk.spikes.create("Investigate Performance")
+spike1.set_findings(
+    "Performance is excellent with WebSocket updates - achieved 50ms latency"
+)
+spike1.save()
+log_event("SPIKE_CREATED", f"Spike 1 created: {spike1.id} - 'Investigate Performance'")
+time.sleep(2)
+
+spike2 = sdk.spikes.create("Research Dashboard Integration")
+spike2.set_findings(
+    "Dashboard integration pattern verified - real-time event streaming works"
+)
+spike2.save()
+log_event(
+    "SPIKE_CREATED", f"Spike 2 created: {spike2.id} - 'Research Dashboard Integration'"
+)
+time.sleep(2)
+
+spike3 = sdk.spikes.create("Evaluate Scalability")
+spike3.set_findings("System handles 1000+ concurrent connections with graph operations")
+spike3.save()
+log_event("SPIKE_CREATED", f"Spike 3 created: {spike3.id} - 'Evaluate Scalability'")
+time.sleep(2)
+
+# ============================================================================
+# SUMMARY
+# ============================================================================
+print("\n" + "=" * 80)
+print("SDK OPERATIONS COMPLETED")
+print("=" * 80)
+
+print(f"\nTotal Events Generated: {len(events)}")
+print("\nEvent Timeline:")
+print("-" * 80)
+
+for i, event in enumerate(events, 1):
+    print(f"{i:2d}. [{event['timestamp']}] {event['type']:30s} - {event['details']}")
+
+print("\n" + "-" * 80)
+print("Expected Dashboard Activity Feed Updates:")
+print("  - All events should appear on the dashboard within 1-2 seconds")
+print("  - Events are ordered by creation timestamp")
+print("  - Feature/Track/Spike relationships are automatically tracked")
+print("=" * 80)
+
+# Additional summary statistics
+print("\nSummary Statistics:")
+print(f"  Track created: 1 (ID: {track.id})")
+print(f"  Features created: 5 (IDs: {[f.id for f in features]})")
+print("  Features Done: 2 (Features 1, 4)")
+print("  Features In Progress: 2 (Features 2, 3)")
+print("  Features Pending: 1 (Feature 5)")
+print(f"  Spikes created: 3 (IDs: {[spike1.id, spike2.id, spike3.id]})")
+print(f"  Total operations: {len(events)}")

htmlgraph-0.26.6/examples/example_query_compilation.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""
+Example demonstrating query compilation for CSS selector reuse.
+
+This shows how to pre-compile frequently used selectors for better performance.
+"""
+
+import tempfile
+
+from htmlgraph import HtmlGraph
+from htmlgraph.models import Node
+
+
+def main():
+    """Demonstrate query compilation usage."""
+    print("🔍 Query Compilation Example\n")
+    print("=" * 60)
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        # Create graph
+        graph = HtmlGraph(tmpdir, auto_load=False)
+
+        # Add sample nodes
+        print("\n📝 Adding sample nodes...")
+        graph.add(
+            Node(id="feat-001", title="Auth System", status="blocked", priority="high")
+        )
+        graph.add(
+            Node(id="feat-002", title="Database", status="blocked", priority="critical")
+        )
+        graph.add(Node(id="feat-003", title="API", status="todo", priority="high"))
+        graph.add(Node(id="feat-004", title="UI", status="done", priority="medium"))
+        graph.add(Node(id="feat-005", title="Tests", status="blocked", priority="low"))
+
+        # Reset metrics for clean measurement
+        graph.reset_metrics()
+
+        # Example 1: Regular query
+        print("\n📊 Example 1: Regular Query")
+        print("-" * 60)
+        results1 = graph.query("[data-status='blocked']")
+        print(f"Found {len(results1)} blocked items:")
+        for node in results1:
+            print(f"  - {node.id}: {node.title} ({node.priority} priority)")
+
+        # Example 2: Pre-compile for reuse
+        print("\n📊 Example 2: Pre-compiled Query")
+        print("-" * 60)
+        compiled = graph.compile_query("[data-status='blocked']")
+        print(f"Compiled query for selector: {compiled.selector}")
+
+        # Use compiled query multiple times
+        results2 = graph.query_compiled(compiled)
+        results3 = graph.query_compiled(compiled)
+        print(f"First execution: {len(results2)} results")
+        print(f"Second execution: {len(results3)} results (uses cache)")
+
+        # Example 3: Multiple compiled queries
+        print("\n📊 Example 3: Multiple Compiled Queries")
+        print("-" * 60)
+        high_priority = graph.compile_query("[data-priority='high']")
+        critical = graph.compile_query("[data-priority='critical']")
+
+        high_results = graph.query_compiled(high_priority)
+        critical_results = graph.query_compiled(critical)
+
+        print(f"High priority items: {len(high_results)}")
+        print(f"Critical priority items: {len(critical_results)}")
+
+        # Show metrics
+        print("\n📈 Performance Metrics")
+        print("-" * 60)
+        metrics = graph.metrics
+        print(f"Total queries: {metrics['query_count']}")
+        print(f"Cache hits: {metrics['cache_hits']}")
+        print(f"Cache misses: {metrics['cache_misses']}")
+        print(f"Cache hit rate: {metrics['cache_hit_rate']}")
+        print(f"\nCompiled queries created: {metrics['compiled_queries']}")
+        print(f"Compilation cache hits: {metrics['compiled_query_hits']}")
+        print(f"Compilation hit rate: {metrics['compilation_hit_rate']}")
+        print(f"Compiled queries cached: {metrics['compiled_queries_cached']}")
+
+        # Example 4: Compilation cache reuse
+        print("\n📊 Example 4: Compilation Cache Reuse")
+        print("-" * 60)
+        # Compiling the same selector again returns cached instance
+        blocked_query1 = graph.compile_query("[data-status='blocked']")
+        blocked_query2 = graph.compile_query("[data-status='blocked']")
+
+        if blocked_query1 is blocked_query2:
+            print("✅ Compilation cache works - same instance returned")
+        else:
+            print("❌ Unexpected - different instances")
+
+        print("\n" + "=" * 60)
+        print("✅ Query compilation example completed successfully!")
+
+
+if __name__ == "__main__":
+    main()

{htmlgraph-0.26.5 → htmlgraph-0.26.6}/packages/gemini-extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlgraph",
-  "version": "0.26.5",
+  "version": "0.26.6",
   "description": "HtmlGraph session tracking and documentation for Gemini CLI. Ensures proper activity attribution, feature awareness, and continuous work tracking.",
   "author": "Shakes",
   "license": "MIT",

{htmlgraph-0.26.5 → htmlgraph-0.26.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "htmlgraph"
-version = "0.26.5"
+version = "0.26.6"
 description = "HTML is All You Need - Graph database on web standards"
 authors = [{name = "Shakes", email = "shakestzd@gmail.com"}]
 readme = "README.md"
@@ -52,7 +52,7 @@ deploy = [
 ]
 
 [project.scripts]
-htmlgraph = "htmlgraph.cli:main"
+htmlgraph = "htmlgraph.cli.main:main"
 htmlgraph-deploy = "htmlgraph.scripts.deploy:main"
 
 [project.urls]

{htmlgraph-0.26.5 → htmlgraph-0.26.6}/src/python/htmlgraph/.htmlgraph/.session-warning-state.json

@@ -2,5 +2,5 @@
   "dismissed_at": null,
   "dismissed_by": null,
   "session_id": null,
-  "show_count": 30
+  "show_count": 59
 }

{htmlgraph-0.26.5 → htmlgraph-0.26.6}/src/python/htmlgraph/__init__.py

@@ -95,7 +95,7 @@ from htmlgraph.types import (
 )
 from htmlgraph.work_type_utils import infer_work_type, infer_work_type_from_id
 
-__version__ = "0.26.5"
+__version__ = "0.26.6"
 __all__ = [
     # Exceptions
     "HtmlGraphError",