htmlgraph 0.1.0__tar.gz

htmlgraph-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+
+# Playwright
+.playwright-mcp/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local development
+*.log
+
+# HtmlGraph analytics index (rebuildable cache)
+.htmlgraph/index.sqlite
+.htmlgraph/index.sqlite-wal
+.htmlgraph/index.sqlite-shm

htmlgraph-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: htmlgraph
+Version: 0.1.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
+Project-URL: Repository, https://github.com/Shakes-tzd/htmlgraph
+Project-URL: Issues, https://github.com/Shakes-tzd/htmlgraph/issues
+Author-email: Shakes <shakes@example.com>
+License: MIT
+Keywords: agents,ai,css,database,graph,html
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: justhtml>=0.6.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: watchdog>=3.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: sqlite
+Requires-Dist: aiosqlite>=0.19.0; extra == 'sqlite'
+Description-Content-Type: text/markdown
+
+# HtmlGraph
+
+**"HTML is All You Need"**
+
+A lightweight graph database framework built entirely on web standards. Use HTML files as nodes, hyperlinks as edges, and CSS selectors as the query language.
+
+## Why HtmlGraph?
+
+Modern AI agent systems are drowning in complexity:
+- Neo4j/Memgraph → Docker, JVM, learn Cypher
+- Redis/PostgreSQL → More infrastructure
+- Custom protocols → More learning curves
+
+**HtmlGraph uses what you already know:**
+- ✅ HTML files = Graph nodes
+- ✅ `<a href>` = Graph edges
+- ✅ CSS selectors = Query language
+- ✅ Any browser = Visual interface
+- ✅ Git = Version control (diffs work!)
+
+## Installation
+
+```bash
+pip install htmlgraph
+```
+
+## Quick Start
+
+### Python
+
+```python
+from htmlgraph import HtmlGraph, Node, Edge, Step
+
+# Initialize graph from directory
+graph = HtmlGraph("features/")
+
+# Create a node
+node = Node(
+    id="feature-001",
+    title="User Authentication",
+    type="feature",
+    status="in-progress",
+    priority="high",
+    steps=[
+        Step(description="Create auth routes"),
+        Step(description="Add middleware"),
+        Step(description="Implement OAuth"),
+    ],
+    edges={
+        "blocked_by": [Edge(target_id="feature-002", title="Database Schema")]
+    }
+)
+
+# Add to graph (creates HTML file)
+graph.add(node)
+
+# Query with CSS selectors
+blocked = graph.query("[data-status='blocked']")
+high_priority = graph.query("[data-priority='high']")
+
+# Graph traversal
+path = graph.shortest_path("feature-001", "feature-010")
+deps = graph.transitive_deps("feature-001")
+bottlenecks = graph.find_bottlenecks()
+
+# Get lightweight context for AI agents (~50 tokens)
+print(node.to_context())
+# Output:
+# # feature-001: User Authentication
+# Status: in-progress | Priority: high
+# Progress: 0/3 steps (0%)
+# ⚠️  Blocked by: Database Schema
+# Next: Create auth routes
+```
+
+### Agent Interface
+
+```python
+from htmlgraph.agents import AgentInterface
+
+agent = AgentInterface("features/", agent_id="claude")
+
+# Get next available task
+task = agent.get_next_task(priority="high")
+
+# Get lightweight context
+context = agent.get_context(task.id)
+
+# Update progress
+agent.complete_step(task.id, step_index=0)
+
+# Complete task
+agent.complete_task(task.id)
+```
+
+### HTML File Format
+
+HtmlGraph nodes are standard HTML files:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>User Authentication</title>
+</head>
+<body>
+    <article id="feature-001"
+             data-type="feature"
+             data-status="in-progress"
+             data-priority="high">
+
+        <header>
+            <h1>User Authentication</h1>
+        </header>
+
+        <nav data-graph-edges>
+            <section data-edge-type="blocked_by">
+                <h3>Blocked By:</h3>
+                <ul>
+                    <li><a href="feature-002.html">Database Schema</a></li>
+                </ul>
+            </section>
+        </nav>
+
+        <section data-steps>
+            <h3>Steps</h3>
+            <ol>
+                <li data-completed="true">✅ Create auth routes</li>
+                <li data-completed="false">⏳ Add middleware</li>
+            </ol>
+        </section>
+    </article>
+</body>
+</html>
+```
+
+## Features
+
+- **Zero dependencies** beyond `justhtml` and `pydantic`
+- **CSS selector queries** - no new query language to learn
+- **Version control friendly** - git diff works perfectly
+- **Human readable** - open in any browser
+- **AI agent optimized** - lightweight context generation
+- **Graph algorithms** - BFS, shortest path, cycle detection, topological sort
+
+## Comparison
+
+| Feature | Neo4j | JSON | HtmlGraph |
+|---------|-------|------|-----------|
+| Setup | Docker + JVM | None | None |
+| Query Language | Cypher | jq | CSS selectors |
+| Human Readable | ❌ Browser needed | 🟡 Text editor | ✅ Any browser |
+| Version Control | ❌ Binary | ✅ JSON diff | ✅ HTML diff |
+| Visual UI | ❌ Separate tool | ❌ Build it | ✅ Built-in |
+| Graph Native | ✅ | ❌ | ✅ |
+
+## Use Cases
+
+1. **AI Agent Coordination** - Task tracking, dependencies, progress
+2. **Knowledge Bases** - Linked notes with visual navigation
+3. **Documentation** - Interconnected docs with search
+4. **Task Management** - Todo lists with dependencies
+
+## License
+
+MIT
+
+## Links
+
+- [GitHub](https://github.com/Shakes-tzd/htmlgraph)
+- [Documentation](https://github.com/Shakes-tzd/htmlgraph#readme)
+- [Examples](https://github.com/Shakes-tzd/htmlgraph/tree/main/examples)

htmlgraph-0.1.0/README.md

@@ -0,0 +1,173 @@
+# HtmlGraph
+
+**"HTML is All You Need"**
+
+A lightweight graph database framework built entirely on web standards. Use HTML files as nodes, hyperlinks as edges, and CSS selectors as the query language.
+
+## Why HtmlGraph?
+
+Modern AI agent systems are drowning in complexity:
+- Neo4j/Memgraph → Docker, JVM, learn Cypher
+- Redis/PostgreSQL → More infrastructure
+- Custom protocols → More learning curves
+
+**HtmlGraph uses what you already know:**
+- ✅ HTML files = Graph nodes
+- ✅ `<a href>` = Graph edges
+- ✅ CSS selectors = Query language
+- ✅ Any browser = Visual interface
+- ✅ Git = Version control (diffs work!)
+
+## Installation
+
+```bash
+pip install htmlgraph
+```
+
+## Quick Start
+
+### Python
+
+```python
+from htmlgraph import HtmlGraph, Node, Edge, Step
+
+# Initialize graph from directory
+graph = HtmlGraph("features/")
+
+# Create a node
+node = Node(
+    id="feature-001",
+    title="User Authentication",
+    type="feature",
+    status="in-progress",
+    priority="high",
+    steps=[
+        Step(description="Create auth routes"),
+        Step(description="Add middleware"),
+        Step(description="Implement OAuth"),
+    ],
+    edges={
+        "blocked_by": [Edge(target_id="feature-002", title="Database Schema")]
+    }
+)
+
+# Add to graph (creates HTML file)
+graph.add(node)
+
+# Query with CSS selectors
+blocked = graph.query("[data-status='blocked']")
+high_priority = graph.query("[data-priority='high']")
+
+# Graph traversal
+path = graph.shortest_path("feature-001", "feature-010")
+deps = graph.transitive_deps("feature-001")
+bottlenecks = graph.find_bottlenecks()
+
+# Get lightweight context for AI agents (~50 tokens)
+print(node.to_context())
+# Output:
+# # feature-001: User Authentication
+# Status: in-progress | Priority: high
+# Progress: 0/3 steps (0%)
+# ⚠️  Blocked by: Database Schema
+# Next: Create auth routes
+```
+
+### Agent Interface
+
+```python
+from htmlgraph.agents import AgentInterface
+
+agent = AgentInterface("features/", agent_id="claude")
+
+# Get next available task
+task = agent.get_next_task(priority="high")
+
+# Get lightweight context
+context = agent.get_context(task.id)
+
+# Update progress
+agent.complete_step(task.id, step_index=0)
+
+# Complete task
+agent.complete_task(task.id)
+```
+
+### HTML File Format
+
+HtmlGraph nodes are standard HTML files:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>User Authentication</title>
+</head>
+<body>
+    <article id="feature-001"
+             data-type="feature"
+             data-status="in-progress"
+             data-priority="high">
+
+        <header>
+            <h1>User Authentication</h1>
+        </header>
+
+        <nav data-graph-edges>
+            <section data-edge-type="blocked_by">
+                <h3>Blocked By:</h3>
+                <ul>
+                    <li><a href="feature-002.html">Database Schema</a></li>
+                </ul>
+            </section>
+        </nav>
+
+        <section data-steps>
+            <h3>Steps</h3>
+            <ol>
+                <li data-completed="true">✅ Create auth routes</li>
+                <li data-completed="false">⏳ Add middleware</li>
+            </ol>
+        </section>
+    </article>
+</body>
+</html>
+```
+
+## Features
+
+- **Zero dependencies** beyond `justhtml` and `pydantic`
+- **CSS selector queries** - no new query language to learn
+- **Version control friendly** - git diff works perfectly
+- **Human readable** - open in any browser
+- **AI agent optimized** - lightweight context generation
+- **Graph algorithms** - BFS, shortest path, cycle detection, topological sort
+
+## Comparison
+
+| Feature | Neo4j | JSON | HtmlGraph |
+|---------|-------|------|-----------|
+| Setup | Docker + JVM | None | None |
+| Query Language | Cypher | jq | CSS selectors |
+| Human Readable | ❌ Browser needed | 🟡 Text editor | ✅ Any browser |
+| Version Control | ❌ Binary | ✅ JSON diff | ✅ HTML diff |
+| Visual UI | ❌ Separate tool | ❌ Build it | ✅ Built-in |
+| Graph Native | ✅ | ❌ | ✅ |
+
+## Use Cases
+
+1. **AI Agent Coordination** - Task tracking, dependencies, progress
+2. **Knowledge Bases** - Linked notes with visual navigation
+3. **Documentation** - Interconnected docs with search
+4. **Task Management** - Todo lists with dependencies
+
+## License
+
+MIT
+
+## Links
+
+- [GitHub](https://github.com/Shakes-tzd/htmlgraph)
+- [Documentation](https://github.com/Shakes-tzd/htmlgraph#readme)
+- [Examples](https://github.com/Shakes-tzd/htmlgraph/tree/main/examples)

htmlgraph-0.1.0/examples/todo-list/demo.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""
+HtmlGraph Todo List Demo
+
+Demonstrates basic HtmlGraph usage with a simple todo list.
+Run this script from the examples/todo-list directory.
+"""
+
+import sys
+from pathlib import Path
+
+# Add src to path for development
+sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src" / "python"))
+
+from htmlgraph import HtmlGraph, Node, Edge, Step
+from htmlgraph.agents import AgentInterface
+
+
+def main():
+    """Demonstrate HtmlGraph todo list operations."""
+    print("=" * 60)
+    print("HtmlGraph Todo List Demo")
+    print("'HTML is All You Need'")
+    print("=" * 60)
+
+    # Initialize graph from current directory
+    graph = HtmlGraph(".")
+    print(f"\n📂 Loaded {len(graph)} tasks from HTML files")
+
+    # Show stats
+    stats = graph.stats()
+    print(f"\n📊 Statistics:")
+    print(f"   Total tasks: {stats['total']}")
+    print(f"   Completion: {stats['completion_rate']}%")
+    print(f"   By status: {stats['by_status']}")
+
+    # Query examples
+    print("\n🔍 Query Examples:")
+
+    # Find blocked tasks
+    blocked = graph.query("[data-status='blocked']")
+    print(f"\n   Blocked tasks ({len(blocked)}):")
+    for task in blocked:
+        print(f"   - {task.id}: {task.title}")
+
+    # Find high priority tasks
+    high_priority = graph.query("[data-priority='high']")
+    print(f"\n   High priority tasks ({len(high_priority)}):")
+    for task in high_priority:
+        print(f"   - {task.id}: {task.title} [{task.status}]")
+
+    # Graph traversal
+    print("\n🔗 Graph Traversal:")
+
+    # Find dependencies
+    deps = graph.transitive_deps("task-003", relationship="blocked_by")
+    print(f"\n   task-003 depends on: {deps}")
+
+    # Find bottlenecks
+    bottlenecks = graph.find_bottlenecks(top_n=3)
+    print(f"\n   Bottleneck tasks (blocking most others):")
+    for task_id, count in bottlenecks:
+        task = graph.get(task_id)
+        name = task.title if task else task_id
+        print(f"   - {task_id}: {name} (blocks {count} others)")
+
+    # Agent interface demo
+    print("\n🤖 Agent Interface Demo:")
+
+    agent = AgentInterface(".", agent_id="demo-agent")
+
+    # Get summary
+    print(f"\n   {agent.get_summary()}")
+
+    # Get next available task
+    next_task = agent.get_next_task()
+    if next_task:
+        print(f"\n   Next available task:")
+        print(f"   {agent.get_context(next_task.id)}")
+
+    # Create a new task programmatically
+    print("\n✨ Creating new task programmatically...")
+
+    new_task = Node(
+        id="task-005",
+        title="Write documentation",
+        type="task",
+        status="todo",
+        priority="medium",
+        content="<p>Create comprehensive documentation for HtmlGraph.</p>",
+        steps=[
+            Step(description="Write README.md"),
+            Step(description="Create API reference"),
+            Step(description="Add usage examples"),
+        ],
+        edges={
+            "blocked_by": [Edge(target_id="task-002", title="Implement core models")]
+        }
+    )
+
+    # Save to HTML file
+    filepath = graph.add(new_task)
+    print(f"   Created: {filepath}")
+
+    # Show the generated HTML
+    print(f"\n   Generated HTML preview (first 500 chars):")
+    html_content = filepath.read_text()[:500]
+    print(f"   {html_content}...")
+
+    # Generate context for AI agent
+    print("\n📝 AI Agent Context (lightweight ~50 tokens):")
+    print(new_task.to_context())
+
+    # Export as Mermaid diagram
+    print("\n📈 Mermaid Diagram:")
+    print(graph.to_mermaid(relationship="blocked_by"))
+
+    print("\n" + "=" * 60)
+    print("Demo complete! Check the generated HTML files.")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()