htmlgraph 0.20.9__py3-none-any.whl → 0.22.0__py3-none-any.whl

htmlgraph/docs/templates/base_agents.md.j2

@@ -0,0 +1,78 @@
+{# Base template for AGENTS.md - Package provides this #}
+---
+version: "{{ sdk_version }}"
+platform: "{{ platform }}"
+generated: "{{ generated_at }}"
+---
+
+{% block header %}
+# HtmlGraph Agent Documentation
+{% endblock %}
+
+{% block introduction %}
+## Introduction
+
+HtmlGraph is a lightweight graph database framework built entirely on web standards (HTML, CSS, JavaScript) for AI agent coordination and human observability.
+
+**Tagline**: "HTML is All You Need"
+{% endblock %}
+
+{% block quick_start %}
+## Quick Start
+
+```python
+from htmlgraph import SDK
+
+# Initialize SDK for your agent
+sdk = SDK(agent="{{ platform }}")
+
+# Create a feature
+feature = sdk.features.create("Add authentication") \
+    .set_priority("high") \
+    .add_steps(["Setup OAuth", "Add JWT", "Test login"]) \
+    .save()
+
+# Track progress
+sdk.features.get(feature.id).complete_step(0).save()
+```
+{% endblock %}
+
+{% block core_concepts %}
+{% include "_sections/core_concepts.md.j2" %}
+{% endblock %}
+
+{% block sdk_reference %}
+{% include "_sections/sdk_basics.md.j2" %}
+{% endblock %}
+
+{% block cli_reference %}
+{% include "_sections/cli_reference.md.j2" %}
+{% endblock %}
+
+{% block custom_workflows %}
+{# Users can override this block in .htmlgraph/docs/templates/agents.md.j2 #}
+{% if custom_workflows %}
+## Custom Workflows
+
+{{ custom_workflows }}
+{% endif %}
+{% endblock %}
+
+{% block deployment %}
+## Deployment
+
+For deployment instructions, see the deployment guide:
+
+```bash
+# Build and publish package
+./scripts/deploy-all.sh 0.21.0 --no-confirm
+
+# Documentation changes only
+./scripts/deploy-all.sh --docs-only
+```
+{% endblock %}
+
+{% block footer %}
+---
+*Generated by HtmlGraph v{{ sdk_version }} on {{ generated_at }}*
+{% endblock %}

htmlgraph/docs/templates/example_user_override.md.j2

@@ -0,0 +1,47 @@
+{# Example user override template - copy to .htmlgraph/docs/templates/agents.md.j2 #}
+{% extends "base_agents.md.j2" %}
+
+{# Override the header to customize branding #}
+{% block header %}
+# 🤖 {{ platform|title }} Agent - Our Team Documentation
+{% endblock %}
+
+{# Add custom team workflows #}
+{% block custom_workflows %}
+## Our Team Conventions
+
+### Daily Workflow
+1. **Morning Standup** - Review `sdk.summary()` for overnight progress
+2. **Pick Task** - Use `sdk.analytics.recommend_next_work()` for priorities
+3. **Daily Feature** - Create with template: `feat-{YYYYMMDD}-{description}`
+4. **End of Day** - Commit with `./scripts/git-commit-push.sh`
+
+### Commit Message Format
+```
+type(scope): description
+
+Examples:
+- feat(auth): add OAuth provider integration
+- fix(api): resolve session timeout bug
+- docs(readme): update installation steps
+```
+
+### Branch Strategy
+- `main` - Production-ready code
+- `feature/*` - New features
+- `fix/*` - Bug fixes
+- `spike/*` - Research and experimentation
+
+### Code Review Checklist
+- [ ] All tests pass
+- [ ] Documentation updated
+- [ ] No sensitive data in code
+- [ ] Ruff and mypy pass
+- [ ] Feature tracked in HtmlGraph
+{% endblock %}
+
+{# You can also override other blocks:
+   - introduction: Project-specific intro
+   - deployment: Team-specific deployment process
+   - footer: Custom footer with team info
+#}

htmlgraph/docs/version_check.py

@@ -0,0 +1,161 @@
+"""
+Version checking and interactive upgrade workflows.
+"""
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from htmlgraph.docs.docs_version import get_current_doc_version, is_compatible
+from htmlgraph.docs.metadata import DocsMetadata
+from htmlgraph.docs.migrations import get_migration
+
+if TYPE_CHECKING:
+    from htmlgraph.docs.migrations import MigrationScript
+
+
+def check_docs_version(htmlgraph_dir: Path) -> tuple[bool, str | None]:
+    """Check if docs version is compatible.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+
+    Returns:
+        Tuple of (is_compatible, message)
+        - is_compatible: True if compatible
+        - message: Optional warning/error message
+    """
+    metadata = DocsMetadata.load(htmlgraph_dir)
+    current_version = get_current_doc_version()
+
+    if metadata.schema_version == current_version:
+        return True, None
+
+    if is_compatible(metadata.schema_version, current_version):
+        return (
+            True,
+            f"⚠️  Docs version {metadata.schema_version} is supported but outdated (current: {current_version})",
+        )
+
+    return (
+        False,
+        f"❌ Docs version {metadata.schema_version} is incompatible with package (requires: {current_version})",
+    )
+
+
+def upgrade_docs_interactive(htmlgraph_dir: Path) -> None:
+    """Interactive upgrade workflow with user prompts.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+    """
+    metadata = DocsMetadata.load(htmlgraph_dir)
+    current_version = get_current_doc_version()
+
+    if metadata.schema_version == current_version:
+        print("✅ Docs are up to date")
+        return
+
+    # Get migration script
+    migration = get_migration(metadata.schema_version, current_version)
+    if not migration:
+        print(
+            f"❌ No migration available from v{metadata.schema_version} to v{current_version}"
+        )
+        return
+
+    # Show user their options
+    print(
+        f"""
+📋 Documentation Upgrade Available
+  Current: v{metadata.schema_version}
+  Target:  v{current_version}
+
+  Options:
+    1. Auto-migrate (preserves customizations)
+    2. Side-by-side (test before committing)
+    3. Manual migration (view diff first)
+    4. Skip (stay on v{metadata.schema_version})
+  """
+    )
+
+    choice = input("Choose option (1-4): ").strip()
+
+    if choice == "1":
+        _auto_migrate(htmlgraph_dir, migration)
+    elif choice == "2":
+        _side_by_side_migrate(htmlgraph_dir, migration)
+    elif choice == "3":
+        _show_diff_for_manual(htmlgraph_dir, migration)
+    else:
+        print("⏭️  Skipping migration")
+
+
+def _auto_migrate(htmlgraph_dir: Path, migration: "MigrationScript") -> None:  # type: ignore[name-defined]
+    """Automatically migrate with backup.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        migration: MigrationScript instance
+    """
+    backup_dir = htmlgraph_dir / ".docs-backups"
+    backup_dir.mkdir(exist_ok=True)
+
+    print("🚀 Starting auto-migration...")
+    success = migration.migrate(htmlgraph_dir, backup_dir)
+
+    if success:
+        print("✅ Migration complete!")
+        print(f"📦 Backup saved to {backup_dir}")
+    else:
+        print("❌ Migration failed. Docs unchanged.")
+
+
+def _side_by_side_migrate(htmlgraph_dir: Path, migration: "MigrationScript") -> None:  # type: ignore[name-defined]
+    """Create side-by-side versions for testing.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        migration: MigrationScript instance
+    """
+    print("📋 Creating side-by-side versions...")
+    print("⚠️  Side-by-side migration not yet implemented")
+    print("    Use option 1 (auto-migrate) or 3 (manual) instead")
+
+
+def _show_diff_for_manual(htmlgraph_dir: Path, migration: "MigrationScript") -> None:  # type: ignore[name-defined]
+    """Show diff preview for manual migration.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        migration: MigrationScript instance
+    """
+    print("📊 Showing migration preview...")
+    print("⚠️  Diff preview not yet implemented")
+    print("    Use option 1 (auto-migrate) instead")
+
+
+def check_version_on_init(htmlgraph_dir: Path, auto_upgrade: bool = False) -> bool:
+    """Check version compatibility on SDK initialization.
+
+    Args:
+        htmlgraph_dir: Path to .htmlgraph directory
+        auto_upgrade: If True, automatically upgrade if safe
+
+    Returns:
+        True if compatible or upgraded successfully
+    """
+    compatible, message = check_docs_version(htmlgraph_dir)
+
+    if compatible and message:
+        # Compatible but outdated
+        print(message)
+        if auto_upgrade:
+            upgrade_docs_interactive(htmlgraph_dir)
+        return True
+
+    if not compatible:
+        print(message)
+        print("\nRun `uv run htmlgraph docs upgrade` to migrate.")
+        return False
+
+    return True

htmlgraph/learning.py

@@ -150,68 +150,86 @@ class LearningPersistence:
         return health
 
     def persist_patterns(self, min_count: int = 2) -> list[str]:
-        """Detect and persist workflow patterns from sessions.
+        """Detect and persist workflow patterns IN SESSIONS (not as separate files).
+
+        This refactored version stores patterns inline within session HTML files
+        to avoid creating 2,890+ individual pattern files.
 
         Args:
             min_count: Minimum occurrences to persist a pattern
 
         Returns:
-            List of persisted pattern IDs
+            List of session IDs that had patterns updated
         """
-        # Collect tool sequences from all sessions
-        # Use session_manager to get full Session objects with activity_log
-        sequences: list[tuple[Any, ...]] = []
+        # Collect tool sequences per session (not globally)
+        session_ids_updated: list[str] = []
+
         for session in self.sdk.session_manager.session_converter.load_all():
-            if session.activity_log:
-                tools = [
-                    a.tool if not isinstance(a, dict) else a.get("tool", "")
-                    for a in session.activity_log
-                ]
-                # Extract 3-tool sequences
-                for i in range(len(tools) - 2):
-                    seq = tools[i : i + 3]
-                    if all(seq):  # No empty tools
-                        sequences.append(tuple(seq))
-
-        # Count sequences
-        seq_counts = Counter(sequences)
-
-        # Persist patterns with min_count
-        pattern_ids: list[str | Any] = []
-        for seq, count in seq_counts.items():  # type: ignore[assignment]
-            if count >= min_count:
-                # Check if pattern already exists
-                existing = self.sdk.patterns.find_by_sequence(list(seq))
-                if existing:
-                    # Update count - use properties dict for updates
-                    pattern = existing[0]
-                    pattern.properties["detection_count"] = count
-                    pattern.properties["last_detected"] = datetime.now().isoformat()
-                    self.sdk.patterns.update(pattern)
-                    pattern_ids.append(pattern.id)
-                else:
-                    # Create new pattern using builder methods
-                    pattern_type = self._classify_pattern(list(seq))
-                    now = datetime.now()
-                    pattern = (
-                        self.sdk.patterns.create(f"Pattern: {' -> '.join(seq)}")
-                        .set_sequence(list(seq))
-                        .set_pattern_type(pattern_type)
-                        .set_detection_count(count)
-                        .set_first_detected(now)
-                        .set_last_detected(now)
-                        .save()
+            if not session.activity_log:
+                continue
+
+            # Extract 3-tool sequences from this session
+            tools = [
+                a.tool if not isinstance(a, dict) else a.get("tool", "")
+                for a in session.activity_log
+            ]
+
+            # Count sequences in this session
+            sequences: list[tuple[Any, ...]] = []
+            for i in range(len(tools) - 2):
+                seq = tools[i : i + 3]
+                if all(seq):  # No empty tools
+                    sequences.append(tuple(seq))
+
+            seq_counts = Counter(sequences)
+
+            # Update session's detected_patterns
+            patterns_updated = False
+            for seq, count in seq_counts.items():  # type: ignore[assignment]
+                if count >= min_count:
+                    # Check if pattern already exists in this session
+                    existing = next(
+                        (
+                            p
+                            for p in session.detected_patterns
+                            if p.get("sequence") == list(seq)
+                        ),
+                        None,
                     )
-                    pattern_ids.append(pattern.id)
+
+                    if existing:
+                        # Update existing pattern
+                        existing["detection_count"] = count
+                        existing["last_detected"] = datetime.now().isoformat()
+                        patterns_updated = True
+                    else:
+                        # Add new pattern to session
+                        pattern_type = self._classify_pattern(list(seq))
+                        now = datetime.now()
+                        session.detected_patterns.append(
+                            {
+                                "sequence": list(seq),
+                                "pattern_type": pattern_type,
+                                "detection_count": count,
+                                "first_detected": now.isoformat(),
+                                "last_detected": now.isoformat(),
+                            }
+                        )
+                        patterns_updated = True
+
+            # Save updated session if patterns were modified
+            if patterns_updated:
+                self.sdk.session_manager.session_converter.save(session)
+                session_ids_updated.append(session.id)
 
         # Also persist parallel patterns
-        parallel_pattern_ids = self.persist_parallel_patterns(min_count=min_count)
-        pattern_ids.extend(parallel_pattern_ids)
+        parallel_session_ids = self.persist_parallel_patterns(min_count=min_count)
+        session_ids_updated.extend(parallel_session_ids)
 
-        return pattern_ids
+        return session_ids_updated
 
     def persist_parallel_patterns(self, min_count: int = 2) -> list[str]:
-        """Detect and persist parallel execution patterns from sessions.
+        """Detect and persist parallel execution patterns IN SESSIONS.
 
         Identifies when multiple tools are invoked in parallel (same parent_activity_id).
         This is especially useful for detecting orchestrator patterns like parallel Task delegation.
@@ -220,12 +238,11 @@ class LearningPersistence:
             min_count: Minimum occurrences to persist a pattern
 
         Returns:
-            List of persisted pattern IDs
+            List of session IDs that had parallel patterns updated
         """
         from collections import defaultdict
 
-        # Collect parallel execution groups from all sessions
-        parallel_patterns: list[tuple[str, ...]] = []
+        session_ids_updated: list[str] = []
 
         for session in self.sdk.session_manager.session_converter.load_all():
             if not session.activity_log:
@@ -242,12 +259,12 @@ class LearningPersistence:
                 if parent_id:  # Only track activities with a parent
                     parent_groups[parent_id].append(activity)
 
-            # Detect parallel patterns (2+ activities with same parent)
+            # Collect parallel patterns for this session
+            parallel_patterns: list[tuple[str, ...]] = []
             for parent_id, activities in parent_groups.items():
                 if len(activities) < 2:
                     continue
 
-                # Check if activities overlap in time (parallel execution)
                 # Sort by timestamp
                 sorted_activities = sorted(
                     activities,
@@ -268,50 +285,57 @@ class LearningPersistence:
                 if all(tools):
                     parallel_patterns.append(tools)
 
-        # Count parallel patterns
-        pattern_counts = Counter(parallel_patterns)
-
-        # Persist patterns with min_count
-        pattern_ids: list[str | Any] = []
-        for tools, count in pattern_counts.items():
-            if count >= min_count:
-                # Create a pattern name that indicates parallelism
-                tool_names = list(tools)
-                pattern_name = f"Parallel[{len(tools)}]: {' || '.join(tools)}"
-
-                # Check if pattern already exists
-                existing = self.sdk.patterns.find_by_sequence(tool_names)
-                if existing:
-                    # Update existing pattern
-                    pattern = existing[0]
-                    pattern.properties = pattern.properties or {}
-                    pattern.properties["detection_count"] = count
-                    pattern.properties["last_detected"] = datetime.now().isoformat()
-                    pattern.properties["parallel_count"] = len(tools)
-                    pattern.properties["is_parallel"] = True
-                    self.sdk.patterns.update(pattern)
-                    pattern_ids.append(pattern.id)
-                else:
-                    # Create new parallel pattern
-                    pattern_type = self._classify_pattern(tool_names, is_parallel=True)
-                    now = datetime.now()
-                    pattern = (
-                        self.sdk.patterns.create(pattern_name)
-                        .set_sequence(tool_names)
-                        .set_pattern_type(pattern_type)
-                        .set_detection_count(count)
-                        .set_first_detected(now)
-                        .set_last_detected(now)
-                        .save()
+            # Count parallel patterns in this session
+            pattern_counts = Counter(parallel_patterns)
+
+            # Update session's detected_patterns with parallel patterns
+            patterns_updated = False
+            for tools, count in pattern_counts.items():
+                if count >= min_count:
+                    tool_names = list(tools)
+
+                    # Check if pattern already exists in this session
+                    # Parallel patterns have special naming: "Parallel[N]: tool1 || tool2"
+                    existing = next(
+                        (
+                            p
+                            for p in session.detected_patterns
+                            if p.get("sequence") == tool_names
+                            and p.get("is_parallel", False)
+                        ),
+                        None,
                     )
-                    # Mark as parallel in properties
-                    pattern.properties = pattern.properties or {}
-                    pattern.properties["parallel_count"] = len(tools)
-                    pattern.properties["is_parallel"] = True
-                    self.sdk.patterns.update(pattern)
-                    pattern_ids.append(pattern.id)
-
-        return pattern_ids
+
+                    if existing:
+                        # Update existing parallel pattern
+                        existing["detection_count"] = count
+                        existing["last_detected"] = datetime.now().isoformat()
+                        patterns_updated = True
+                    else:
+                        # Add new parallel pattern to session
+                        pattern_type = self._classify_pattern(
+                            tool_names, is_parallel=True
+                        )
+                        now = datetime.now()
+                        session.detected_patterns.append(
+                            {
+                                "sequence": tool_names,
+                                "pattern_type": pattern_type,
+                                "detection_count": count,
+                                "first_detected": now.isoformat(),
+                                "last_detected": now.isoformat(),
+                                "is_parallel": True,
+                                "parallel_count": len(tools),
+                            }
+                        )
+                        patterns_updated = True
+
+            # Save updated session if patterns were modified
+            if patterns_updated:
+                self.sdk.session_manager.session_converter.save(session)
+                session_ids_updated.append(session.id)
+
+        return session_ids_updated
 
     def _classify_pattern(self, sequence: list[str], is_parallel: bool = False) -> str:
         """Classify a pattern as optimal, anti-pattern, or neutral.

htmlgraph/models.py

@@ -937,6 +937,21 @@ class Session(BaseModel):
     transcript_synced_at: datetime | None = None  # Last sync timestamp
     transcript_git_branch: str | None = None  # Git branch from transcript
 
+    # Pattern detection (inline storage to avoid file bloat)
+    detected_patterns: list[dict[str, Any]] = Field(default_factory=list)
+    """
+    Patterns detected during this session.
+
+    Format:
+    {
+        "sequence": ["Bash", "Read", "Edit"],
+        "pattern_type": "neutral",  # or "optimal", "anti_pattern"
+        "detection_count": 3,
+        "first_detected": "2026-01-02T10:00:00",
+        "last_detected": "2026-01-02T10:30:00"
+    }
+    """
+
     def add_activity(self, entry: ActivityEntry) -> None:
         """Add an activity entry to the log."""
         self.activity_log.append(entry)
@@ -1378,6 +1393,43 @@ class Session(BaseModel):
             </dl>
         </section>"""
 
+        # Build detected patterns section
+        patterns_html = ""
+        if self.detected_patterns:
+            patterns_html = f"""
+        <section data-detected-patterns>
+            <h3>Detected Patterns ({len(self.detected_patterns)})</h3>
+            <table class="patterns-table">
+                <thead>
+                    <tr>
+                        <th>Sequence</th>
+                        <th>Type</th>
+                        <th>Count</th>
+                        <th>First/Last Detected</th>
+                    </tr>
+                </thead>
+                <tbody>"""
+
+            for pattern in self.detected_patterns:
+                seq_str = " → ".join(pattern.get("sequence", []))
+                pattern_type = pattern.get("pattern_type", "neutral")
+                count = pattern.get("detection_count", 0)
+                first = pattern.get("first_detected", "")
+                last = pattern.get("last_detected", "")
+
+                patterns_html += f"""
+                    <tr data-pattern-type="{pattern_type}">
+                        <td class="sequence">{seq_str}</td>
+                        <td><span class="badge pattern-{pattern_type}">{pattern_type}</span></td>
+                        <td>{count}</td>
+                        <td>{first} / {last}</td>
+                    </tr>"""
+
+            patterns_html += """
+                </tbody>
+            </table>
+        </section>"""
+
         title = self.title or f"Session {self.id}"
 
         return f'''<!DOCTYPE html>
@@ -1406,7 +1458,7 @@ class Session(BaseModel):
                 <span class="badge">{self.event_count} events</span>
             </div>
         </header>
-{edges_html}{handoff_html}{context_html}{activity_html}
+{edges_html}{handoff_html}{context_html}{patterns_html}{activity_html}
     </article>
 </body>
 </html>

htmlgraph/sdk.py

@@ -44,7 +44,7 @@ from typing import Any
 
 from htmlgraph.agent_detection import detect_agent_name
 from htmlgraph.agents import AgentInterface
-from htmlgraph.analytics import Analytics, DependencyAnalytics
+from htmlgraph.analytics import Analytics, CrossSessionAnalytics, DependencyAnalytics
 from htmlgraph.collections import (
     BaseCollection,
     BugCollection,
@@ -242,6 +242,9 @@ class SDK:
         # Dependency analytics interface (Advanced graph analytics)
         self.dep_analytics = DependencyAnalytics(self._graph)
 
+        # Cross-session analytics interface (Git commit-based analytics)
+        self.cross_session_analytics = CrossSessionAnalytics(self)
+
         # Context analytics interface (Context usage tracking)
         self.context = ContextAnalytics(self)
 

{htmlgraph-0.20.9.dist-info → htmlgraph-0.22.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htmlgraph
-Version: 0.20.9
+Version: 0.22.0
 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