@0dai-dev/cli 4.3.6 → 4.3.7

package/lib/python/graph_slicer.py

@@ -0,0 +1,576 @@
+#!/usr/bin/env python3
+"""Graph-aware context slicing — agents get relevant graph subsets, not everything.
+
+Given a task type and file scope, performs BFS traversal from seed nodes,
+applies task-type relevance scoring, enforces a token budget, and produces
+a structured ContextSlice with nodes, edges, insights, and warnings.
+
+Tier gate: Pro/Team get full traversal + insights. Free gets nodes only.
+
+Issue: #73
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import hashlib
+import json
+import logging
+import pathlib
+from collections import deque
+
+log = logging.getLogger("0dai.graph_slicer")
+
+# ---------------------------------------------------------------------------
+# Token estimation
+# ---------------------------------------------------------------------------
+
+CHARS_PER_TOKEN = 3  # conservative: 1 token ~ 3 chars for mixed code/English
+
+
+def estimate_tokens(text: str) -> int:
+    """Rough token estimate. 1 token ~ 3 chars (conservative for code)."""
+    return max(1, len(text) // CHARS_PER_TOKEN)
+
+
+# ---------------------------------------------------------------------------
+# Task-type relevance weights
+# ---------------------------------------------------------------------------
+
+# Higher weight = more relevant for this task type.
+# Node types map to graph NODE_TYPES but we use lowercase keys for matching.
+RELEVANCE_WEIGHTS: dict[str, dict[str, float]] = {
+    "feat": {"Decision": 1.0, "Outcome": 0.8, "Component": 0.6, "Technology": 0.5, "Requirement": 0.7, "Risk": 0.4},
+    "fix": {"Outcome": 1.0, "Decision": 0.7, "Component": 0.9, "Risk": 0.8, "Technology": 0.5, "Endpoint": 0.6},
+    "refactor": {"Decision": 1.0, "Component": 0.8, "Outcome": 0.7, "Technology": 0.6, "Risk": 0.5},
+    "test": {"Component": 1.0, "TestPlan": 0.9, "Outcome": 0.5, "Decision": 0.3, "Endpoint": 0.7},
+    "docs": {"Component": 0.8, "Decision": 0.6, "Outcome": 0.3, "Endpoint": 0.5, "Technology": 0.4},
+}
+
+# Default weight for node types not explicitly listed
+DEFAULT_RELEVANCE = 0.2
+
+
+def _relevance_score(node_type: str, task_type: str) -> float:
+    """Return relevance score for a node type given a task type."""
+    weights = RELEVANCE_WEIGHTS.get(task_type, RELEVANCE_WEIGHTS["feat"])
+    return weights.get(node_type, DEFAULT_RELEVANCE)
+
+
+# ---------------------------------------------------------------------------
+# Seed node resolution
+# ---------------------------------------------------------------------------
+
+def _find_seed_nodes(graph: dict, scope: list[str]) -> list[str]:
+    """Find graph nodes matching the given file paths / module names.
+
+    Matching strategy:
+    1. Exact node name match
+    2. Node name ends with scope path component
+    3. Node description contains the scope path
+    """
+    nodes = graph.get("nodes", {})
+    seeds: list[str] = []
+    seen: set[str] = set()
+
+    for scope_path in scope:
+        # Normalize: strip leading ./ or /
+        normalized = scope_path.lstrip("./").rstrip("/")
+        basename = pathlib.PurePosixPath(normalized).name
+
+        for nid, node in nodes.items():
+            if nid in seen:
+                continue
+            name = node.get("name", "")
+            desc = node.get("description", "")
+
+            # Exact name match
+            if name == normalized or name == basename:
+                seeds.append(nid)
+                seen.add(nid)
+                continue
+
+            # Name ends with scope component
+            if normalized and name.endswith(normalized):
+                seeds.append(nid)
+                seen.add(nid)
+                continue
+
+            # Description contains scope path
+            if normalized and normalized in desc:
+                seeds.append(nid)
+                seen.add(nid)
+                continue
+
+            # Slug-based match (node id contains filename slug)
+            slug = basename.replace(".", "_").replace("-", "_").lower()
+            if slug and len(slug) > 2 and slug in nid.lower():
+                seeds.append(nid)
+                seen.add(nid)
+
+    return seeds
+
+
+# ---------------------------------------------------------------------------
+# BFS traversal with relevance scoring
+# ---------------------------------------------------------------------------
+
+def _build_adjacency(edges: list[dict]) -> dict[str, list[tuple[str, dict]]]:
+    """Build bidirectional adjacency list from edges."""
+    adj: dict[str, list[tuple[str, dict]]] = {}
+    for edge in edges:
+        src = edge.get("from", "")
+        tgt = edge.get("to", "")
+        if src:
+            adj.setdefault(src, []).append((tgt, edge))
+        if tgt:
+            adj.setdefault(tgt, []).append((src, edge))
+    return adj
+
+
+def _bfs_traverse(
+    graph: dict,
+    seed_ids: list[str],
+    max_depth: int,
+    task_type: str,
+    token_budget: int,
+) -> tuple[list[dict], list[dict]]:
+    """BFS from seeds, prioritized by relevance, bounded by depth and tokens.
+
+    Returns (selected_nodes_with_hop, selected_edges).
+    Each node dict includes a 'hop' field indicating distance from seed.
+    """
+    nodes = graph.get("nodes", {})
+    edges = graph.get("edges", [])
+    adj = _build_adjacency(edges)
+
+    # BFS state
+    visited: dict[str, int] = {}  # node_id -> hop
+    queue: deque[tuple[str, int]] = deque()
+
+    # Initialize with seeds
+    for sid in seed_ids:
+        if sid in nodes and sid not in visited:
+            visited[sid] = 0
+            queue.append((sid, 0))
+
+    # BFS expansion
+    while queue:
+        current_id, current_hop = queue.popleft()
+        if current_hop >= max_depth:
+            continue
+
+        for neighbor_id, edge in adj.get(current_id, []):
+            if neighbor_id in visited:
+                continue
+            if neighbor_id not in nodes:
+                continue
+            visited[neighbor_id] = current_hop + 1
+            queue.append((neighbor_id, current_hop + 1))
+
+    # Score and sort nodes by relevance (seeds first, then by score descending)
+    scored_nodes: list[tuple[str, int, float]] = []
+    for nid, hop in visited.items():
+        node = nodes[nid]
+        node_type = node.get("type", "")
+        relevance = _relevance_score(node_type, task_type)
+        # Seeds get max score, others decay by hop distance
+        score = 10.0 if hop == 0 else relevance / (hop * 0.5 + 0.5)
+        scored_nodes.append((nid, hop, score))
+
+    scored_nodes.sort(key=lambda x: (-x[2], x[1]))
+
+    # Token budget enforcement
+    used_tokens = 0
+    selected_ids: set[str] = set()
+    result_nodes: list[dict] = []
+
+    for nid, hop, score in scored_nodes:
+        node = nodes[nid]
+        # Estimate tokens for this node
+        node_text = f"{node.get('type', '')} {node.get('name', '')} {node.get('description', '')[:100]}"
+        node_tokens = estimate_tokens(node_text)
+
+        if used_tokens + node_tokens > token_budget and hop > 0:
+            # Don't skip seed nodes even if over budget
+            break
+
+        selected_ids.add(nid)
+        result_nodes.append({
+            "id": nid,
+            "type": node.get("type", ""),
+            "name": node.get("name", ""),
+            "hop": hop,
+            "data": {
+                k: v for k, v in node.items()
+                if k not in ("id", "type", "name", "created_at", "updated_at")
+                and v  # skip empty values
+            },
+        })
+        used_tokens += node_tokens
+
+    # Collect edges between selected nodes
+    result_edges: list[dict] = []
+    for edge in edges:
+        if edge.get("from") in selected_ids and edge.get("to") in selected_ids:
+            result_edges.append({
+                "source": edge["from"],
+                "target": edge["to"],
+                "type": edge.get("type", ""),
+            })
+
+    return result_nodes, result_edges
+
+
+# ---------------------------------------------------------------------------
+# Insight generation
+# ---------------------------------------------------------------------------
+
+def _generate_insights(
+    graph: dict,
+    selected_nodes: list[dict],
+    selected_edges: list[dict],
+    task_type: str,
+) -> list[str]:
+    """Generate human-readable insights from the selected subgraph."""
+    insights: list[str] = []
+    nodes_by_id = {n["id"]: n for n in selected_nodes}
+    all_nodes = graph.get("nodes", {})
+
+    for edge in selected_edges:
+        src_id = edge["source"]
+        tgt_id = edge["target"]
+        etype = edge["type"]
+        src = nodes_by_id.get(src_id, {})
+        tgt = nodes_by_id.get(tgt_id, {})
+        src_name = src.get("name", src_id)
+        tgt_name = tgt.get("name", tgt_id)
+
+        if etype == "depends_on":
+            insights.append(f"{src_name} depends on {tgt_name} — changes may cascade")
+        elif etype == "uses":
+            insights.append(f"{src_name} uses {tgt_name}")
+        elif etype == "affects":
+            insights.append(f"Decision '{src_name}' affects {tgt_name}")
+        elif etype == "evaluates":
+            # Outcome evaluates Decision
+            status = src.get("data", {}).get("status", "")
+            lessons = src.get("data", {}).get("lessons", "")
+            if status:
+                insights.append(f"Outcome for '{tgt_name}': {status}" + (f" — {lessons[:80]}" if lessons else ""))
+        elif etype == "chose":
+            insights.append(f"Previous decision: chose {tgt_name}")
+        elif etype == "mitigates":
+            insights.append(f"Decision '{src_name}' mitigates risk: {tgt_name}")
+        elif etype == "blocks":
+            insights.append(f"Risk '{src_name}' blocks {tgt_name}")
+
+    # Add outcome insights for Decision nodes
+    for node in selected_nodes:
+        if node["type"] == "Outcome":
+            data = node.get("data", {})
+            status = data.get("status", "unknown")
+            agent = data.get("agent", "")
+            cost = data.get("cost", "")
+            duration = data.get("duration", "")
+            parts = [f"Outcome: {node['name']} — {status}"]
+            if agent:
+                parts.append(f"agent: {agent}")
+            if cost:
+                parts.append(f"${cost}")
+            if duration:
+                parts.append(f"{duration}s")
+            insights.append(" ".join(parts))
+
+    return insights[:10]  # Cap at 10 insights
+
+
+# ---------------------------------------------------------------------------
+# Warning generation
+# ---------------------------------------------------------------------------
+
+def _generate_warnings(
+    graph: dict,
+    selected_nodes: list[dict],
+    task_type: str,
+) -> list[str]:
+    """Generate warnings based on graph patterns."""
+    warnings: list[str] = []
+    all_nodes = graph.get("nodes", {})
+
+    for node in selected_nodes:
+        nid = node["id"]
+        full_node = all_nodes.get(nid, {})
+
+        # Check for frequent modifications (if updated_at is recent)
+        updated_at = full_node.get("updated_at", "")
+        if updated_at:
+            try:
+                updated = _dt.datetime.fromisoformat(updated_at.replace("Z", "+00:00"))
+                now = _dt.datetime.now(_dt.timezone.utc)
+                if (now - updated).total_seconds() < 86400:  # 24h
+                    warnings.append(f"{node['name']} was modified in the last 24h")
+            except (ValueError, TypeError):
+                pass
+
+        # Check for blocking risks
+        if node["type"] == "Risk":
+            status = full_node.get("status", "")
+            if status in ("open", "active", ""):
+                severity = full_node.get("severity", "medium")
+                warnings.append(f"Open risk: {node['name']} (severity: {severity})")
+
+    return warnings[:5]  # Cap at 5 warnings
+
+
+# ---------------------------------------------------------------------------
+# Main context slice function
+# ---------------------------------------------------------------------------
+
+class ContextSlice:
+    """Structured result of graph context slicing."""
+
+    def __init__(
+        self,
+        seed_nodes: list[str],
+        task_type: str,
+        depth_reached: int,
+        token_count: int,
+        nodes: list[dict],
+        edges: list[dict],
+        insights: list[str],
+        warnings: list[str],
+    ):
+        self.slice_id = "slice_" + hashlib.sha256(
+            json.dumps(seed_nodes + [task_type]).encode()
+        ).hexdigest()[:12]
+        self.created_at = _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+        self.seed_nodes = seed_nodes
+        self.task_type = task_type
+        self.depth_reached = depth_reached
+        self.token_count = token_count
+        self.nodes = nodes
+        self.edges = edges
+        self.insights = insights
+        self.warnings = warnings
+
+    def to_dict(self) -> dict:
+        return {
+            "slice_id": self.slice_id,
+            "created_at": self.created_at,
+            "seed_nodes": self.seed_nodes,
+            "task_type": self.task_type,
+            "depth_reached": self.depth_reached,
+            "token_count": self.token_count,
+            "nodes": self.nodes,
+            "edges": self.edges,
+            "insights": self.insights,
+            "warnings": self.warnings,
+        }
+
+    def format_for_agent(self) -> str:
+        """Format slice as compact text for agent context injection."""
+        lines = ["## Project Context (from graph)"]
+
+        if self.insights:
+            for insight in self.insights:
+                lines.append(f"- {insight}")
+
+        if self.warnings:
+            lines.append("")
+            for warning in self.warnings:
+                lines.append(f"- \u26a0 {warning}")
+
+        if not self.insights and not self.warnings:
+            lines.append("- No relevant context found in project graph")
+
+        return "\n".join(lines)
+
+
+def get_context_slice(
+    graph: dict,
+    task_type: str = "feat",
+    scope: list[str] | None = None,
+    max_depth: int = 3,
+    token_budget: int = 4000,
+    agent: str | None = None,
+) -> ContextSlice:
+    """Get a relevant context slice from the project graph.
+
+    Args:
+        graph: The full project graph dict (nodes, edges, meta).
+        task_type: One of "feat", "fix", "refactor", "test", "docs".
+        scope: File paths involved in the task (used to find seed nodes).
+        max_depth: Maximum BFS hops from seed nodes (default 3).
+        token_budget: Maximum tokens for the output context (default 4000).
+        agent: Optional agent name to tailor output.
+
+    Returns:
+        ContextSlice with nodes, edges, insights, and warnings.
+    """
+    if scope is None:
+        scope = []
+
+    nodes = graph.get("nodes", {})
+    edges = graph.get("edges", [])
+
+    if not nodes:
+        return ContextSlice(
+            seed_nodes=[], task_type=task_type, depth_reached=0,
+            token_count=0, nodes=[], edges=[], insights=[], warnings=[],
+        )
+
+    # Step 1: Find seed nodes from scope
+    seed_ids = _find_seed_nodes(graph, scope)
+
+    # If no seeds found, try to use all nodes matching task-relevant types
+    if not seed_ids and scope:
+        # Fallback: return empty slice with a note
+        return ContextSlice(
+            seed_nodes=[], task_type=task_type, depth_reached=0,
+            token_count=0, nodes=[], edges=[],
+            insights=["No matching nodes found for scope: " + ", ".join(scope)],
+            warnings=[],
+        )
+
+    # If no scope at all, use top-level component nodes as seeds
+    if not seed_ids:
+        for nid, node in nodes.items():
+            if node.get("type") == "Component" and "root" in nid:
+                seed_ids.append(nid)
+                break
+        if not seed_ids and nodes:
+            # Just pick first few nodes
+            seed_ids = list(nodes.keys())[:3]
+
+    # Step 2: BFS traversal with relevance scoring
+    selected_nodes, selected_edges = _bfs_traverse(
+        graph, seed_ids, max_depth, task_type, token_budget,
+    )
+
+    # Calculate actual depth reached
+    depth_reached = max((n["hop"] for n in selected_nodes), default=0)
+
+    # Calculate token count
+    total_tokens = sum(
+        estimate_tokens(f"{n['type']} {n['name']} {n.get('data', {}).get('description', '')[:100]}")
+        for n in selected_nodes
+    )
+
+    # Step 3: Generate insights
+    insights = _generate_insights(graph, selected_nodes, selected_edges, task_type)
+
+    # Step 4: Generate warnings
+    warnings = _generate_warnings(graph, selected_nodes, task_type)
+
+    # Add insight tokens to count
+    for text in insights + warnings:
+        total_tokens += estimate_tokens(text)
+
+    return ContextSlice(
+        seed_nodes=seed_ids,
+        task_type=task_type,
+        depth_reached=depth_reached,
+        token_count=total_tokens,
+        nodes=selected_nodes,
+        edges=selected_edges,
+        insights=insights,
+        warnings=warnings,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Free-tier slice: nodes only, no traversal, no insights
+# ---------------------------------------------------------------------------
+
+def get_free_tier_slice(
+    graph: dict,
+    scope: list[str] | None = None,
+) -> dict:
+    """Return a minimal slice for free-tier users: matched nodes only."""
+    if scope is None:
+        scope = []
+    nodes = graph.get("nodes", {})
+    seed_ids = _find_seed_nodes(graph, scope)
+
+    result_nodes = []
+    for nid in seed_ids:
+        node = nodes.get(nid)
+        if node:
+            result_nodes.append({
+                "id": nid,
+                "type": node.get("type", ""),
+                "name": node.get("name", ""),
+            })
+
+    return {
+        "nodes": result_nodes,
+        "edges": [],
+        "insights": [],
+        "warnings": [],
+        "tier": "free",
+        "hint": "Upgrade to Pro for traversal, insights, and warnings: 0dai upgrade",
+    }
+
+
+# ---------------------------------------------------------------------------
+# CLI formatting
+# ---------------------------------------------------------------------------
+
+def format_cli_output(slice_data: ContextSlice | dict) -> str:
+    """Format a context slice for CLI display."""
+    if isinstance(slice_data, ContextSlice):
+        d = slice_data.to_dict()
+    else:
+        d = slice_data
+
+    lines = []
+
+    # Header
+    task_type = d.get("task_type", "unknown")
+    seeds = d.get("seed_nodes", [])
+    if seeds:
+        lines.append(f"Graph context for {task_type} of {', '.join(seeds[:3])}:")
+    else:
+        lines.append(f"Graph context for {task_type}:")
+    lines.append("")
+
+    # Nodes
+    node_list = d.get("nodes", [])
+    if node_list:
+        depth = d.get("depth_reached", 0)
+        tokens = d.get("token_count", 0)
+        lines.append(f"Related nodes (depth {depth}, {tokens} tokens):")
+        for node in node_list:
+            ntype = node.get("type", "")
+            name = node.get("name", node.get("id", ""))
+            hop = node.get("hop", "?")
+            icon = {"Component": "\U0001f4c1", "Decision": "\U0001f4a1", "Outcome": "\u2705",
+                    "Technology": "\U0001f527", "Risk": "\u26a0\ufe0f", "Requirement": "\U0001f4cb",
+                    "Endpoint": "\U0001f310", "TestPlan": "\U0001f9ea"}.get(ntype, "\U0001f4c4")
+            label = "seed" if hop == 0 else f"hop {hop}"
+            lines.append(f"  {icon} {name} ({label})")
+    else:
+        lines.append("No related nodes found.")
+
+    # Insights
+    insights = d.get("insights", [])
+    if insights:
+        lines.append("")
+        lines.append("Insights:")
+        for insight in insights:
+            lines.append(f"  \u2022 {insight}")
+
+    # Warnings
+    warnings = d.get("warnings", [])
+    if warnings:
+        lines.append("")
+        lines.append("\u26a0 Warnings:")
+        for warning in warnings:
+            lines.append(f"  \u2022 {warning}")
+
+    # Free tier hint
+    if d.get("tier") == "free":
+        lines.append("")
+        lines.append(d.get("hint", ""))
+
+    return "\n".join(lines)

package/lib/python/graph_slicer_cli.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""CLI wrapper for graph context slicing.
+
+Called by: 0dai graph context --scope FILE --task TYPE --depth N --budget N --json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent))
+
+import graph_slicer
+from graph import load_graph
+
+MISSING_GRAPH_HINT = (
+    "No project graph found. Create ai/manifest/project_graph.json, or from a "
+    "repo checkout run: python3 scripts/generate_project_graph.py --target ."
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Graph-aware context slicing")
+    parser.add_argument("--target", type=str, default=".", help="Project root directory")
+    parser.add_argument("--scope", action="append", default=[], help="File paths (repeatable)")
+    parser.add_argument("--task", type=str, default="feat", help="Task type: feat|fix|refactor|test|docs")
+    parser.add_argument("--depth", type=int, default=3, help="Max BFS hops (default: 3)")
+    parser.add_argument("--budget", type=int, default=4000, help="Token budget (default: 4000)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args(argv)
+
+    target = pathlib.Path(args.target).resolve()
+    graph_path = target / "ai" / "manifest" / "project_graph.json"
+
+    if not graph_path.exists():
+        print(MISSING_GRAPH_HINT, file=sys.stderr)
+        return 1
+
+    graph = load_graph(graph_path, track_usage=False)
+
+    ctx = graph_slicer.get_context_slice(
+        graph=graph,
+        task_type=args.task,
+        scope=args.scope,
+        max_depth=args.depth,
+        token_budget=args.budget,
+    )
+
+    if args.json:
+        print(json.dumps(ctx.to_dict(), indent=2, ensure_ascii=False))
+    else:
+        print(graph_slicer.format_cli_output(ctx))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/lib/python/graph_validation.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Graph validation helpers."""
+
+from __future__ import annotations
+
+from graph_core import EDGE_TYPES, NODE_TYPES, SCHEMA_VERSION, log
+
+
+class GraphValidationError(ValueError):
+    """Raised when a graph fails structural validation."""
+
+
+def validate_graph(graph: dict) -> list[str]:
+    errors: list[str] = []
+
+    for key in ("nodes", "edges", "meta"):
+        if key not in graph:
+            errors.append(f"missing top-level key: {key}")
+    if errors:
+        return errors
+
+    if not isinstance(graph["nodes"], dict):
+        errors.append("nodes must be a dict")
+    if not isinstance(graph["edges"], list):
+        errors.append("edges must be a list")
+    if errors:
+        return errors
+
+    meta_version = graph["meta"].get("schema_version")
+    if meta_version != SCHEMA_VERSION:
+        errors.append(
+            f"schema_version mismatch: expected {SCHEMA_VERSION}, got {meta_version}"
+        )
+
+    for node_id, node in graph["nodes"].items():
+        if node.get("id") != node_id:
+            errors.append(f"node id mismatch: key={node_id}, node.id={node.get('id')}")
+        node_type = node.get("type")
+        if node_type not in NODE_TYPES:
+            errors.append(f"node {node_id} has unknown type: {node_type!r}")
+        for field in ("name", "status", "created_at", "updated_at"):
+            if field not in node:
+                errors.append(f"node {node_id} missing required field: {field}")
+
+    seen_edges: set[tuple] = set()
+    for i, edge in enumerate(graph["edges"]):
+        for field in ("from", "to", "type"):
+            if field not in edge:
+                errors.append(f"edge[{i}] missing field: {field}")
+                continue
+        edge_type = edge.get("type")
+        if edge_type not in EDGE_TYPES:
+            errors.append(f"edge[{i}] has unknown type: {edge_type!r}")
+        src, tgt = edge.get("from"), edge.get("to")
+        if src not in graph["nodes"]:
+            log.warning("edge[%d] dangling source: %s", i, src)
+        if tgt not in graph["nodes"]:
+            log.warning("edge[%d] dangling target: %s", i, tgt)
+        key = (src, tgt, edge_type)
+        if key in seen_edges:
+            log.warning("edge[%d] duplicate: %s -> %s [%s]", i, src, tgt, edge_type)
+        seen_edges.add(key)
+
+    return errors