htmlgraph 0.24.2__tar.gz → 0.26.1__tar.gz

{htmlgraph-0.24.2 → htmlgraph-0.26.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: htmlgraph
-Version: 0.24.2
+Version: 0.26.1
 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
@@ -19,11 +19,14 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Database
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: fastapi>=0.104.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: justhtml>=0.6.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typing-extensions>=4.0.0; python_version < '3.11'
+Requires-Dist: uvicorn>=0.24.0
 Requires-Dist: watchdog>=3.0.0
 Provides-Extra: deploy
 Requires-Dist: invoke>=2.2.0; extra == 'deploy'
@@ -35,7 +38,9 @@ Requires-Dist: pdoc>=14.0.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
 Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
 Provides-Extra: sqlite
 Requires-Dist: aiosqlite>=0.19.0; extra == 'sqlite'
 Description-Content-Type: text/markdown
@@ -81,71 +86,47 @@ This bootstraps:
 - `.htmlgraph/index.sqlite` analytics cache (rebuildable; gitignored via `.gitignore`)
 - versioned hook scripts under `.htmlgraph/hooks/` (installed into `.git/hooks/` with `--install-hooks`)
 
-### Python
+### Python (SDK - Recommended)
 
 ```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)
+from htmlgraph import SDK
+
+# Initialize (auto-discovers .htmlgraph directory)
+sdk = SDK(agent="claude")
+
+# Create and configure a feature with fluent API
+feature = sdk.features.create("User Authentication") \
+    .set_priority("high") \
+    .set_description("Implement OAuth 2.0 login") \
+    .add_steps([
+        "Create login endpoint",
+        "Add JWT middleware",
+        "Write integration tests"
+    ]) \
+    .save()
+
+print(f"Created: {feature.id}")
+
+# Work on features
+with sdk.features.edit(feature.id) as f:
+    f.status = "in-progress"
+    f.agent_assigned = "claude"
+    f.steps[0].completed = True
+
+# Query features
+high_priority_todos = sdk.features.where(status="todo", priority="high")
+for feat in high_priority_todos:
+    print(f"- {feat.id}: {feat.title}")
+
+# Create and configure a track with TrackBuilder
+track = sdk.tracks.builder() \
+    .title("Q1 Security Initiative") \
+    .priority("high") \
+    .add_feature("feature-001") \
+    .add_feature("feature-002") \
+    .create()
+
+print(f"Created track: {track.id}")
 ```
 
 ### HTML File Format
@@ -203,6 +184,43 @@ HtmlGraph nodes are standard HTML files:
 - **Deployment Automation** - One-command releases with version management
 - **Unified Backend** - Operations layer shared by CLI and SDK for consistency
 
+## Orchestrator Architecture: Flexible Multi-Agent Coordination
+
+HtmlGraph implements an orchestrator pattern that coordinates multiple AI agents in parallel, preserving context efficiency while maintaining complete flexibility in model selection. Instead of rigid rules, the pattern uses **capability-first thinking** to choose the right tool (and model) for each task.
+
+**Key Principles:**
+- ✅ **Flexible model selection** - Any model can do any work; choose based on task fit and cost
+- ✅ **Dynamic spawner composition** - Mix and match spawner types (Gemini, Copilot, Codex, Claude) within the same workflow
+- ✅ **Cost optimization** - Use cheaper models for exploratory work, expensive models only for reasoning
+- ✅ **Parallel execution** - Independent tasks run simultaneously, reducing total time
+
+**Example: Parallel Exploration with Multiple Spawners**
+
+```python
+# All run in parallel - each uses the best tool for the job
+Task(subagent_type="gemini-spawner",    # FREE exploration
+     prompt="Find all authentication patterns in src/auth/")
+
+Task(subagent_type="copilot-spawner",   # GitHub integration
+     prompt="Check GitHub issues related to auth",
+     allow_tools=["github(*)"])
+
+Task(subagent_type="claude-spawner",    # Deep reasoning
+     prompt="Analyze auth patterns for security issues")
+
+# Orchestrator coordinates, subagents work in parallel
+# Total time = slowest task (not sum of all)
+# Cost = optimized (cheap exploration + expensive reasoning only)
+```
+
+**Spawner Types:**
+- **Gemini Spawner** - FREE exploratory research, batch analysis (2M tokens/min)
+- **Copilot Spawner** - GitHub-integrated workflows, git operations
+- **Codex Spawner** - Code generation, coding completions
+- **Claude Spawner** - Deep reasoning, analysis, strategic planning (any Claude model)
+
+→ [Complete Orchestrator Architecture Guide](docs/orchestrator-architecture.md) - Detailed patterns, cost optimization, decision framework, and advanced examples
+
 ## Comparison
 
 | Feature | Neo4j | JSON | HtmlGraph |
@@ -257,6 +275,15 @@ uv run python
 
 MIT
 
+## System Prompt & Delegation Documentation
+
+For Claude Code users and teams using HtmlGraph for AI agent coordination:
+
+- **[System Prompt Quick Start](docs/SYSTEM_PROMPT_QUICK_START.md)** - Setup your system prompt in 5 minutes (start here!)
+- **[System Prompt Architecture](docs/SYSTEM_PROMPT_ARCHITECTURE.md)** - Technical deep dive + troubleshooting
+- **[Delegation Enforcement Admin Guide](docs/DELEGATION_ENFORCEMENT_ADMIN_GUIDE.md)** - Setup cost-optimal delegation for your team
+- **[System Prompt Developer Guide](docs/SYSTEM_PROMPT_DEVELOPER_GUIDE.md)** - Extend with custom layers, hooks, and skills
+
 ## Links
 
 - [GitHub](https://github.com/Shakes-tzd/htmlgraph)

{htmlgraph-0.24.2 → htmlgraph-0.26.1}/README.md

@@ -39,71 +39,47 @@ This bootstraps:
 - `.htmlgraph/index.sqlite` analytics cache (rebuildable; gitignored via `.gitignore`)
 - versioned hook scripts under `.htmlgraph/hooks/` (installed into `.git/hooks/` with `--install-hooks`)
 
-### Python
+### Python (SDK - Recommended)
 
 ```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)
+from htmlgraph import SDK
+
+# Initialize (auto-discovers .htmlgraph directory)
+sdk = SDK(agent="claude")
+
+# Create and configure a feature with fluent API
+feature = sdk.features.create("User Authentication") \
+    .set_priority("high") \
+    .set_description("Implement OAuth 2.0 login") \
+    .add_steps([
+        "Create login endpoint",
+        "Add JWT middleware",
+        "Write integration tests"
+    ]) \
+    .save()
+
+print(f"Created: {feature.id}")
+
+# Work on features
+with sdk.features.edit(feature.id) as f:
+    f.status = "in-progress"
+    f.agent_assigned = "claude"
+    f.steps[0].completed = True
+
+# Query features
+high_priority_todos = sdk.features.where(status="todo", priority="high")
+for feat in high_priority_todos:
+    print(f"- {feat.id}: {feat.title}")
+
+# Create and configure a track with TrackBuilder
+track = sdk.tracks.builder() \
+    .title("Q1 Security Initiative") \
+    .priority("high") \
+    .add_feature("feature-001") \
+    .add_feature("feature-002") \
+    .create()
+
+print(f"Created track: {track.id}")
 ```
 
 ### HTML File Format
@@ -161,6 +137,43 @@ HtmlGraph nodes are standard HTML files:
 - **Deployment Automation** - One-command releases with version management
 - **Unified Backend** - Operations layer shared by CLI and SDK for consistency
 
+## Orchestrator Architecture: Flexible Multi-Agent Coordination
+
+HtmlGraph implements an orchestrator pattern that coordinates multiple AI agents in parallel, preserving context efficiency while maintaining complete flexibility in model selection. Instead of rigid rules, the pattern uses **capability-first thinking** to choose the right tool (and model) for each task.
+
+**Key Principles:**
+- ✅ **Flexible model selection** - Any model can do any work; choose based on task fit and cost
+- ✅ **Dynamic spawner composition** - Mix and match spawner types (Gemini, Copilot, Codex, Claude) within the same workflow
+- ✅ **Cost optimization** - Use cheaper models for exploratory work, expensive models only for reasoning
+- ✅ **Parallel execution** - Independent tasks run simultaneously, reducing total time
+
+**Example: Parallel Exploration with Multiple Spawners**
+
+```python
+# All run in parallel - each uses the best tool for the job
+Task(subagent_type="gemini-spawner",    # FREE exploration
+     prompt="Find all authentication patterns in src/auth/")
+
+Task(subagent_type="copilot-spawner",   # GitHub integration
+     prompt="Check GitHub issues related to auth",
+     allow_tools=["github(*)"])
+
+Task(subagent_type="claude-spawner",    # Deep reasoning
+     prompt="Analyze auth patterns for security issues")
+
+# Orchestrator coordinates, subagents work in parallel
+# Total time = slowest task (not sum of all)
+# Cost = optimized (cheap exploration + expensive reasoning only)
+```
+
+**Spawner Types:**
+- **Gemini Spawner** - FREE exploratory research, batch analysis (2M tokens/min)
+- **Copilot Spawner** - GitHub-integrated workflows, git operations
+- **Codex Spawner** - Code generation, coding completions
+- **Claude Spawner** - Deep reasoning, analysis, strategic planning (any Claude model)
+
+→ [Complete Orchestrator Architecture Guide](docs/orchestrator-architecture.md) - Detailed patterns, cost optimization, decision framework, and advanced examples
+
 ## Comparison
 
 | Feature | Neo4j | JSON | HtmlGraph |
@@ -215,6 +228,15 @@ uv run python
 
 MIT
 
+## System Prompt & Delegation Documentation
+
+For Claude Code users and teams using HtmlGraph for AI agent coordination:
+
+- **[System Prompt Quick Start](docs/SYSTEM_PROMPT_QUICK_START.md)** - Setup your system prompt in 5 minutes (start here!)
+- **[System Prompt Architecture](docs/SYSTEM_PROMPT_ARCHITECTURE.md)** - Technical deep dive + troubleshooting
+- **[Delegation Enforcement Admin Guide](docs/DELEGATION_ENFORCEMENT_ADMIN_GUIDE.md)** - Setup cost-optimal delegation for your team
+- **[System Prompt Developer Guide](docs/SYSTEM_PROMPT_DEVELOPER_GUIDE.md)** - Extend with custom layers, hooks, and skills
+
 ## Links
 
 - [GitHub](https://github.com/Shakes-tzd/htmlgraph)

{htmlgraph-0.24.2 → htmlgraph-0.26.1}/packages/gemini-extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlgraph",
-  "version": "0.24.2",
+  "version": "0.26.1",
   "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.24.2 → htmlgraph-0.26.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "htmlgraph"
-version = "0.24.2"
+version = "0.26.1"
 description = "HTML is All You Need - Graph database on web standards"
 authors = [{name = "Shakes", email = "shakestzd@gmail.com"}]
 readme = "README.md"
@@ -26,6 +26,9 @@ dependencies = [
     "rich>=13.0.0",
     "jinja2>=3.1.0",
     "typing_extensions>=4.0.0; python_version < '3.11'",
+    "fastapi>=0.104.0",
+    "uvicorn>=0.24.0",
+    "aiosqlite>=0.19.0",
 ]
 
 [project.optional-dependencies]
@@ -38,6 +41,8 @@ dev = [
     "ruff>=0.1.0",
     "invoke>=2.2.0",
     "pdoc>=14.0.0",
+    "tomli>=2.0.0; python_version < '3.11'",
+    "pyyaml>=6.0",
 ]
 sqlite = [
     "aiosqlite>=0.19.0",
@@ -105,8 +110,19 @@ python_version = "3.10"
 warn_return_any = true
 warn_unused_ignores = false  # Disabled due to environment differences between local and CI
 disallow_untyped_defs = true
+disallow_any_unimported = false  # Allow untyped third-party libraries
 ignore_missing_imports = true
 
+# Per-module options for strict checking
+[[tool.mypy.overrides]]
+module = "htmlgraph.collections.task_delegation"
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+
+[[tool.mypy.overrides]]
+module = "htmlgraph.server"
+disallow_incomplete_defs = true
+
 [tool.pdoc]
 output-directory = "docs/api-pdoc"
 docformat = "google"

{htmlgraph-0.24.2 → htmlgraph-0.26.1}/src/python/htmlgraph/__init__.py

@@ -8,6 +8,14 @@ hyperlinks as edges, and CSS selectors as the query language.
 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
@@ -56,9 +64,11 @@ from htmlgraph.orchestrator_mode import OrchestratorMode, OrchestratorModeManage
 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.session_registry import SessionRegistry
 from htmlgraph.types import (
     ActiveWorkItem,
     AggregateResultsDict,
@@ -85,7 +95,7 @@ from htmlgraph.types import (
 )
 from htmlgraph.work_type_utils import infer_work_type, infer_work_type_from_id
 
-__version__ = "0.24.2"
+__version__ = "0.26.1"
 __all__ = [
     # Exceptions
     "HtmlGraphError",
@@ -123,6 +133,8 @@ __all__ = [
     "find_all",
     "AgentInterface",
     "SessionManager",
+    "SessionRegistry",
+    "RepoHash",
     "SDK",
     "Analytics",  # Phase 2: Work Type Analytics
     "DependencyAnalytics",  # Advanced dependency-aware analytics
@@ -190,4 +202,11 @@ __all__ = [
     "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-0.24.2 → htmlgraph-0.26.1}/src/python/htmlgraph/agent_detection.py

@@ -14,34 +14,48 @@ def detect_agent_name() -> str:
     Detect the current agent/interface name based on environment.
 
     Returns:
-        Agent name (e.g., "claude", "gemini", "cli")
+        Agent name (e.g., "claude-code", "gemini", "cli")
 
     Detection order:
         1. HTMLGRAPH_AGENT environment variable (explicit override)
-        2. Claude Code detection (CLAUDE_CODE_VERSION, parent process)
-        3. Gemini detection (GEMINI environment markers)
-        4. Fall back to "cli"
+        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. Claude Code detection
-    if _is_claude_code():
-        return "claude"
+    # 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
+    # 3. Gemini detection (checked before Claude to allow explicit override)
     if _is_gemini():
         return "gemini"
 
-    # 4. Default to CLI
+    # 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
 
@@ -100,12 +114,14 @@ def get_agent_display_name(agent: str) -> str:
     """
     display_names = {
         "claude": "Claude",
-        "claude-code": "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())

{htmlgraph-0.24.2 → htmlgraph-0.26.1}/src/python/htmlgraph/analytics/cross_session.py

@@ -51,6 +51,7 @@ if TYPE_CHECKING:
     from htmlgraph import SDK
 
 from htmlgraph.event_log import JsonlEventLog
+from htmlgraph.models import utc_now
 
 
 @dataclass
@@ -598,7 +599,7 @@ class CrossSessionAnalytics:
     def _parse_timestamp(self, timestamp: str | datetime | None) -> datetime:
         """Parse timestamp from various formats."""
         if timestamp is None:
-            return datetime.now()
+            return utc_now()
 
         if isinstance(timestamp, datetime):
             return timestamp
@@ -607,6 +608,6 @@ class CrossSessionAnalytics:
             try:
                 return datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
             except (ValueError, AttributeError):
-                return datetime.now()
+                return utc_now()
 
-        return datetime.now()
+        return utc_now()