codegraph-nav 0.1.0__py3-none-any.whl

codegraph_nav/hints.py

@@ -0,0 +1,195 @@
+"""Session hints — workflow adjacency suggestions and intent detection.
+
+Tracks tool usage within a session and suggests the next most useful tool
+based on a workflow adjacency graph. Appends a compact hint line to tool
+responses.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+
+# ==============================================================================
+# Workflow Adjacency Graph
+# ==============================================================================
+
+WORKFLOW_GRAPH: dict[str, list[str]] = {
+    "codegraph_scan": [
+        "codegraph_get_minimal_context",
+        "codegraph_search",
+        "codegraph_graph_build",
+    ],
+    "codegraph_get_minimal_context": [
+        "codegraph_search",
+        "codegraph_get_hubs",
+        "codegraph_graph_build",
+    ],
+    "codegraph_search": [
+        "codegraph_read",
+        "codegraph_get_structure",
+        "codegraph_search_graph",
+    ],
+    "codegraph_search_graph": [
+        "codegraph_read",
+        "codegraph_get_structure",
+        "codegraph_blast_radius",
+    ],
+    "codegraph_read": [
+        "codegraph_get_dependencies",
+        "codegraph_blast_radius",
+        "codegraph_search",
+    ],
+    "codegraph_stats": [
+        "codegraph_get_hubs",
+        "codegraph_search",
+        "codegraph_graph_build",
+    ],
+    "codegraph_get_hubs": [
+        "codegraph_get_dependencies",
+        "codegraph_get_structure",
+        "codegraph_list_communities",
+    ],
+    "codegraph_get_structure": [
+        "codegraph_read",
+        "codegraph_search",
+        "codegraph_get_dependencies",
+    ],
+    "codegraph_get_dependencies": [
+        "codegraph_blast_radius",
+        "codegraph_read",
+        "codegraph_get_structure",
+    ],
+    "codegraph_test_gaps": [
+        "codegraph_read",
+        "codegraph_detect_changes",
+        "codegraph_search",
+    ],
+    "codegraph_graph_build": [
+        "codegraph_list_flows",
+        "codegraph_list_communities",
+        "codegraph_detect_changes",
+    ],
+    "codegraph_blast_radius": [
+        "codegraph_read",
+        "codegraph_detect_changes",
+        "codegraph_list_flows",
+    ],
+    "codegraph_list_flows": [
+        "codegraph_read",
+        "codegraph_blast_radius",
+        "codegraph_detect_changes",
+    ],
+    "codegraph_detect_changes": [
+        "codegraph_blast_radius",
+        "codegraph_test_gaps",
+        "codegraph_read",
+    ],
+    "codegraph_list_communities": [
+        "codegraph_get_architecture_overview",
+        "codegraph_get_community",
+        "codegraph_list_flows",
+    ],
+    "codegraph_get_community": [
+        "codegraph_read",
+        "codegraph_list_communities",
+        "codegraph_get_dependencies",
+    ],
+    "codegraph_get_architecture_overview": [
+        "codegraph_list_communities",
+        "codegraph_list_flows",
+        "codegraph_get_hubs",
+    ],
+    "codegraph_list_routes": [
+        "codegraph_read",
+        "codegraph_list_schemas",
+        "codegraph_get_structure",
+    ],
+    "codegraph_list_schemas": [
+        "codegraph_read",
+        "codegraph_list_routes",
+        "codegraph_get_structure",
+    ],
+}
+
+# Intent keywords → intent label
+INTENT_SIGNALS: dict[str, list[str]] = {
+    "reviewing": [
+        "codegraph_detect_changes",
+        "codegraph_blast_radius",
+        "codegraph_test_gaps",
+    ],
+    "debugging": [
+        "codegraph_search",
+        "codegraph_read",
+        "codegraph_search_graph",
+    ],
+    "implementing": [
+        "codegraph_get_structure",
+        "codegraph_list_routes",
+        "codegraph_list_schemas",
+    ],
+    "exploring": [
+        "codegraph_get_hubs",
+        "codegraph_list_communities",
+        "codegraph_get_architecture_overview",
+        "codegraph_list_flows",
+    ],
+}
+
+
+# ==============================================================================
+# Session State
+# ==============================================================================
+
+
+class SessionState:
+    """Tracks tool usage within a session for next-tool suggestions."""
+
+    def __init__(self):
+        self.tools_called: deque[str] = deque(maxlen=20)
+        self.files_touched: set[str] = set()
+        self.inferred_intent: str = "exploring"
+
+    def record(self, tool_name: str, files: list[str] | None = None):
+        """Record a tool call and update intent."""
+        self.tools_called.append(tool_name)
+        if files:
+            self.files_touched.update(files)
+        self._update_intent()
+
+    def get_suggestions(self, tool_name: str) -> list[str]:
+        """Get top 3 next-tool suggestions based on workflow adjacency."""
+        candidates = WORKFLOW_GRAPH.get(tool_name, [])
+        if not candidates:
+            return ["codegraph_search", "codegraph_read", "codegraph_get_minimal_context"]
+
+        # Filter out recently called tools
+        recent = set(list(self.tools_called)[-3:])
+        filtered = [c for c in candidates if c not in recent]
+        if not filtered:
+            filtered = candidates
+
+        return filtered[:3]
+
+    def format_hint(self, tool_name: str) -> str:
+        """Format a compact hint line for appending to tool output."""
+        suggestions = self.get_suggestions(tool_name)
+        if not suggestions:
+            return ""
+        short_names = [s.replace("codegraph_", "") for s in suggestions]
+        return f"_hint: try {' | '.join(short_names)}"
+
+    def _update_intent(self):
+        """Infer session intent from recent tool usage."""
+        recent = list(self.tools_called)[-5:]
+        if not recent:
+            return
+
+        scores: dict[str, int] = {}
+        for intent, signals in INTENT_SIGNALS.items():
+            scores[intent] = sum(1 for t in recent if t in signals)
+
+        if scores:
+            best = max(scores, key=scores.get)
+            if scores[best] > 0:
+                self.inferred_intent = best