feat: integrate react-force-graph-2d for enhanced graph visualization

- Added dynamic import for ForceGraph2D to enable client-side rendering.
- Refactored BasicGraphView to utilize ForceGraph2D for rendering graphs.
- Implemented responsive dimensions for the graph container using ResizeObserver.
- Enhanced graph data structure to include color mapping and node properties.
- Added a legend to display group colors for better visualization context.
- Updated package.json and package-lock.json to include react-force-graph-2d dependency.

Author: Robbie1977

app/api/chat/route.js

@@ -745,13 +745,12 @@ function getToolConfig() {
   tools.push({
     type: 'function',
     name: 'create_basic_graph',
-    description: 'Create a lightweight graph specification for UI rendering. Use this to visualise connectivity as nodes and edges.',
+    description: 'Create a lightweight graph specification for UI rendering. Use this to visualise connectivity as nodes and edges. IMPORTANT: Always set the "group" field on every node to a shared biological category (e.g. neurotransmitter type like "cholinergic", "GABAergic", "glutamatergic"; or system/region like "visual system", "central complex"; or cell class like "sensory neuron", "interneuron") so that nodes are colour-coded meaningfully. Choose the most informative grouping for the specific query context.',
     parameters: {
       type: 'object',
       properties: {
         title: { type: 'string', description: 'Optional graph title' },
         directed: { type: 'boolean', description: 'Whether edges are directed (default true)' },
-        layout: { type: 'string', enum: ['circle', 'radial'], description: 'Simple layout hint (default circle)' },
         nodes: {
           type: 'array',
           description: 'Graph nodes',
@@ -760,11 +759,10 @@ function getToolConfig() {
             properties: {
               id: { type: 'string', description: 'Unique node identifier' },
               label: { type: 'string', description: 'Display label for the node' },
-              group: { type: 'string', description: 'Optional group/type' },
-              color: { type: 'string', description: 'Optional color in #RRGGBB format' },
+              group: { type: 'string', description: 'REQUIRED: Shared biological category for colour-coding. Use neurotransmitter type (cholinergic, GABAergic, glutamatergic), system/region (visual system, central complex), cell class (sensory neuron, interneuron, projection neuron), or other contextually meaningful grouping.' },
               size: { type: 'number', description: 'Optional relative node size (1-3 recommended)' }
             },
-            required: ['id']
+            required: ['id', 'group']
           }
         },
         edges: {
@@ -2517,7 +2515,8 @@ TOOL SELECTION:
 - Questions about FlyBase genes/alleles/insertions/stocks: use vfb_resolve_entity first (if unresolved), then vfb_find_stocks
 - Questions about split-GAL4 combination names/synonyms (for example MB002B, SS04495): use vfb_resolve_combination first, then vfb_find_combo_publications (and optionally vfb_find_stocks if the user asks for lines)
 - Questions about comparative connectivity between neuron classes across datasets: use vfb_query_connectivity (optionally vfb_list_connectome_datasets first to pick valid dataset symbols)
-- For connectivity questions, call vfb_query_connectivity directly with the neuron class labels or FBbt IDs the user mentions — do NOT manually run NeuronsPartHere or vfb_search_terms first. The server handles term resolution and will return requires_user_selection if disambiguation is needed.
+- For connectivity questions, call vfb_query_connectivity directly with the FULL neuron class labels or FBbt IDs the user mentions — do NOT manually run NeuronsPartHere or vfb_search_terms first. The server handles term resolution and will return requires_user_selection if disambiguation is needed.
+- IMPORTANT: When the user gives a multi-word neuron name like "adult ellipsoid body ring neuron", pass the ENTIRE phrase as the label. Do NOT break it into sub-terms (e.g. do NOT search for "ellipsoid body" separately). Always use the longest, most specific term the user provides.
 - For directional requests like "connections from X to Y" or "between X and Y", treat X as upstream (presynaptic) and Y as downstream (postsynaptic), and prefer vfb_query_connectivity over a single-term run_query.
 - Do not infer identity from examples in this prompt. Only map IDs to labels (or labels to IDs) using tool outputs from this turn.
 - Never claim "TERM_A (ID) is TERM_B" unless vfb_get_term_info confirms that exact mapping.
@@ -2543,7 +2542,7 @@ TOOL ERRORS AND TIMEOUTS:
 - VFB MCP queries (especially non-cached ones like vfb_query_connectivity and live vfb_run_query) can take considerable time. Do NOT treat slow responses as failures.
 - If a tool returns a timeout error, try an alternative approach (e.g. narrower query, different tool) rather than giving up. Always present whatever partial results you have gathered so far.
 - Never tell the user a query "failed" or "timed out" without first attempting at least one alternative path.
-- CRITICAL: When vfb_query_connectivity returns connectivity data successfully, present those results immediately. Do NOT make additional tool calls (vfb_run_query, vfb_get_term_info) to "enrich" the connectivity answer — this wastes time and risks timeouts that obscure the successful results.
+- CRITICAL: When vfb_query_connectivity returns connectivity data successfully, present those results immediately AND call create_basic_graph with the top connections. Do NOT make additional tool calls (vfb_run_query, vfb_get_term_info) to "enrich" the connectivity answer — this wastes time and risks timeouts that obscure the successful results.
 - If supplementary tool calls fail but the primary query succeeded, present the successful results and ignore the supplementary failures. Never lead your response with error messages when you have valid data to show.
 
 TOOL ECONOMY:
@@ -2566,10 +2565,14 @@ FORMATTING VFB REFERENCES (response text only — NOT for tool parameters):
 - Only use thumbnail URLs that actually appear in tool results
 
 GRAPH VISUALS:
-- Graph rendering is optional and should be used only when it improves clarity for this specific answer.
-- For connectivity answers, use at most one concise graph (typically 4-20 nodes) when a visual summary is clearer than text alone.
-- Keep graph specs focused on the strongest relationships and avoid very dense or exhaustive graphs.
-- Skip graph output when a short table or plain-language summary is clearer.
+- ALWAYS call create_basic_graph when vfb_query_connectivity returns connectivity data. Do not wait for the user to ask for a graph — include it automatically alongside the text summary.
+- For connectivity answers, create one concise graph (typically 4-20 nodes) highlighting the strongest relationships.
+- Keep graph specs focused and avoid very dense or exhaustive graphs — pick the top connections by weight.
+- Every node MUST have a meaningful "group" field for colour-coding. Choose the most informative biological grouping for the context:
+  * Neurotransmitter type (cholinergic, GABAergic, glutamatergic, etc.) when NT data is available
+  * Brain region/system (visual system, central complex, mushroom body, etc.) when comparing across regions
+  * Cell class (sensory neuron, interneuron, projection neuron, motor neuron, etc.) as a general fallback
+  * The LLM should use its knowledge of Drosophila neurobiology to assign the most useful grouping
 
 TOOL RELAY:
 - You can request server-side tool execution using the tool relay protocol.
@@ -3009,7 +3012,7 @@ function buildToolPolicyCorrectionMessage({
     '- Choose the smallest set of tools that best answers the user request.',
     '- For VFB query-type questions, prefer vfb_get_term_info + vfb_run_query as the first pass because vfb_run_query is typically cached and fast.',
     '- Use more specialized tools (for example vfb_query_connectivity, vfb_resolve_entity, vfb_find_stocks, vfb_resolve_combination, vfb_find_combo_publications) when deeper refinement is needed.',
-    '- If the result is connectivity-heavy and a graph would help, consider create_basic_graph for a compact node/edge view.',
+    '- When connectivity data is returned, ALWAYS call create_basic_graph to visualise the connections as a node/edge graph with meaningful group labels for colour-coding.',
     '- Prefer direct data tools over documentation search when the question asks for concrete VFB data.',
     '- If existing tool outputs already answer the question, provide the final answer instead of requesting more tools.'
   ]

app/page.js

@@ -2,9 +2,12 @@
 
 import { useState, useEffect, useRef, memo, useCallback, useMemo } from 'react'
 import { useSearchParams } from 'next/navigation'
+import dynamic from 'next/dynamic'
 import ReactMarkdown from 'react-markdown'
 import { NEGATIVE_FEEDBACK_REASON_CODES } from '../lib/feedback.js'
 
+const ForceGraph2D = dynamic(() => import('react-force-graph-2d'), { ssr: false })
+
 const FEEDBACK_REASON_LABELS = {
   helpful: 'Helpful',
   wrong: 'Wrong',
@@ -26,47 +29,84 @@ function hashString(value = '') {
   return Math.abs(hash)
 }
 
-const BasicGraphView = memo(function BasicGraphView({ graph, graphKey }) {
-  const width = 640
-  const height = 360
-  const centerX = width / 2
-  const centerY = height / 2
+const BasicGraphView = memo(function BasicGraphView({ graph }) {
+  const containerRef = useRef(null)
+  const fgRef = useRef(null)
+  const [dimensions, setDimensions] = useState({ width: 640, height: 400 })
 
   const nodes = Array.isArray(graph?.nodes) ? graph.nodes : []
   const edges = Array.isArray(graph?.edges) ? graph.edges : []
-  if (nodes.length === 0 || edges.length === 0) return null
-
-  const radius = Math.max(90, Math.min(width, height) / 2 - 64)
-  const positionedNodes = nodes.map((node, index) => {
-    const angle = nodes.length === 1
-      ? 0
-      : ((2 * Math.PI * index) / nodes.length) - (Math.PI / 2)
 
+  // Build color map from groups
+  const groupColorMap = useMemo(() => {
+    const map = {}
+    const groups = [...new Set(nodes.map(n => n.group || '').filter(Boolean))]
+    groups.forEach((g, i) => { map[g] = GRAPH_PALETTE[i % GRAPH_PALETTE.length] })
+    return map
+  }, [nodes])
+
+  // Build graph data for force-graph (must use fresh objects each render to avoid mutation issues)
+  const graphData = useMemo(() => {
+    const nodeIds = new Set(nodes.map(n => String(n.id)))
     return {
-      ...node,
-      x: centerX + (radius * Math.cos(angle)),
-      y: centerY + (radius * Math.sin(angle))
+      nodes: nodes.map(n => ({
+        id: String(n.id),
+        label: n.label || n.id,
+        group: n.group || '',
+        color: n.color || groupColorMap[n.group] || GRAPH_PALETTE[hashString(n.label || n.id) % GRAPH_PALETTE.length],
+        size: n.size || 1
+      })),
+      links: edges
+        .filter(e => nodeIds.has(String(e.source)) && nodeIds.has(String(e.target)))
+        .map(e => ({
+          source: String(e.source),
+          target: String(e.target),
+          label: e.label || (Number.isFinite(Number(e.weight)) ? String(e.weight) : ''),
+          weight: Number(e.weight) || 1
+        }))
     }
-  })
-
-  const nodeById = new Map(positionedNodes.map(node => [String(node.id), node]))
-  const visibleEdges = edges
-    .map(edge => ({
-      ...edge,
-      source: String(edge.source),
-      target: String(edge.target)
-    }))
-    .filter(edge => nodeById.has(edge.source) && nodeById.has(edge.target))
+  }, [nodes, edges, groupColorMap])
+
+  // Measure container width
+  useEffect(() => {
+    if (!containerRef.current) return
+    const ro = new ResizeObserver(entries => {
+      for (const entry of entries) {
+        const w = entry.contentRect.width
+        if (w > 0) setDimensions({ width: w, height: Math.max(350, Math.min(500, w * 0.6)) })
+      }
+    })
+    ro.observe(containerRef.current)
+    return () => ro.disconnect()
+  }, [])
+
+  // Zoom to fit after initial layout settles
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      if (fgRef.current) fgRef.current.zoomToFit(300, 40)
+    }, 800)
+    return () => clearTimeout(timer)
+  }, [graphData])
+
+  if (nodes.length === 0 || edges.length === 0) return null
+
+  const isDirected = graph?.directed !== false
+  const maxWeight = Math.max(1, ...graphData.links.map(l => l.weight))
 
-  const markerId = `arrow-${hashString(String(graphKey || graph?.title || 'graph'))}`
+  // Build legend entries from groups
+  const legendEntries = [...new Set(nodes.map(n => n.group).filter(Boolean))].map(g => ({
+    group: g,
+    color: groupColorMap[g] || '#888'
+  }))
 
   return (
-    <div style={{
+    <div ref={containerRef} style={{
       marginTop: '10px',
       border: '1px solid #2a2a2a',
       borderRadius: '8px',
       backgroundColor: '#0f0f12',
-      padding: '10px'
+      padding: '10px',
+      overflow: 'hidden'
     }}>
       {graph?.title && (
         <div style={{
@@ -78,91 +118,62 @@ const BasicGraphView = memo(function BasicGraphView({ graph, graphKey }) {
           {graph.title}
         </div>
       )}
-      <svg viewBox={`0 0 ${width} ${height}`} role="img" aria-label={graph?.title || 'Network graph visualization'} style={{ width: '100%', height: 'auto', display: 'block' }}>
-        {graph?.directed !== false && (
-          <defs>
-            <marker
-              id={markerId}
-              viewBox="0 0 10 10"
-              refX="8"
-              refY="5"
-              markerWidth="6"
-              markerHeight="6"
-              orient="auto-start-reverse"
-            >
-              <path d="M 0 0 L 10 5 L 0 10 z" fill="#6b7280" />
-            </marker>
-          </defs>
-        )}
-
-        {visibleEdges.map((edge, index) => {
-          const sourceNode = nodeById.get(edge.source)
-          const targetNode = nodeById.get(edge.target)
-          const rawWeight = Number(edge.weight)
-          const strokeWidth = Number.isFinite(rawWeight)
-            ? Math.min(4, Math.max(1, 1 + (Math.log10(rawWeight + 1))))
-            : 1.4
-          const midX = (sourceNode.x + targetNode.x) / 2
-          const midY = (sourceNode.y + targetNode.y) / 2
-          const edgeText = edge.label || (Number.isFinite(rawWeight) ? `${rawWeight}` : '')
-
-          return (
-            <g key={`edge-${index}-${edge.source}-${edge.target}`}>
-              <line
-                x1={sourceNode.x}
-                y1={sourceNode.y}
-                x2={targetNode.x}
-                y2={targetNode.y}
-                stroke="#6b7280"
-                strokeWidth={strokeWidth}
-                opacity={0.9}
-                markerEnd={graph?.directed === false ? undefined : `url(#${markerId})`}
-              />
-              {edgeText && (
-                <text
-                  x={midX}
-                  y={midY - 5}
-                  fill="#cbd5e1"
-                  fontSize="11"
-                  textAnchor="middle"
-                  style={{ paintOrder: 'stroke', stroke: '#0f0f12', strokeWidth: 3 }}
-                >
-                  {edgeText}
-                </text>
-              )}
-            </g>
-          )
-        })}
-
-        {positionedNodes.map((node, index) => {
-          const groupKey = String(node.group || node.label || node.id)
-          const color = (typeof node.color === 'string' && /^#[0-9a-f]{6}$/i.test(node.color))
-            ? node.color
-            : GRAPH_PALETTE[hashString(groupKey) % GRAPH_PALETTE.length]
-          const nodeRadius = Math.min(18, Math.max(7, 8 + (Number(node.size) || 1)))
-          return (
-            <g key={`node-${node.id}-${index}`}>
-              <circle
-                cx={node.x}
-                cy={node.y}
-                r={nodeRadius}
-                fill={color}
-                stroke="#111827"
-                strokeWidth="1.5"
-              />
-              <text
-                x={node.x}
-                y={node.y + nodeRadius + 13}
-                fill="#e5e7eb"
-                fontSize="12"
-                textAnchor="middle"
-              >
-                {node.label || node.id}
-              </text>
-            </g>
-          )
-        })}
-      </svg>
+      {legendEntries.length > 1 && (
+        <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', marginBottom: '6px', fontSize: '0.72em' }}>
+          {legendEntries.map(e => (
+            <span key={e.group} style={{ display: 'inline-flex', alignItems: 'center', gap: '4px', color: '#ccc' }}>
+              <span style={{ width: 10, height: 10, borderRadius: '50%', backgroundColor: e.color, display: 'inline-block' }} />
+              {e.group}
+            </span>
+          ))}
+        </div>
+      )}
+      <ForceGraph2D
+        ref={fgRef}
+        graphData={graphData}
+        width={dimensions.width - 20}
+        height={dimensions.height}
+        backgroundColor="#0f0f12"
+        nodeRelSize={6}
+        nodeVal={n => Math.max(1, (n.size || 1) * 1.5)}
+        nodeColor={n => n.color}
+        nodeLabel={n => `${n.label}${n.group ? ` (${n.group})` : ''}`}
+        nodeCanvasObject={(node, ctx, globalScale) => {
+          const r = Math.max(3, 4 + (node.size || 1) * 2)
+          ctx.beginPath()
+          ctx.arc(node.x, node.y, r, 0, 2 * Math.PI)
+          ctx.fillStyle = node.color
+          ctx.fill()
+          ctx.strokeStyle = '#1a1a2e'
+          ctx.lineWidth = 0.5
+          ctx.stroke()
+          // Draw label when zoomed in enough
+          if (globalScale > 0.7) {
+            const label = node.label || node.id
+            const fontSize = Math.max(3, 10 / globalScale)
+            ctx.font = `${fontSize}px sans-serif`
+            ctx.textAlign = 'center'
+            ctx.textBaseline = 'top'
+            ctx.fillStyle = '#e5e7eb'
+            ctx.fillText(label, node.x, node.y + r + 2)
+          }
+        }}
+        linkColor={() => '#4b5563'}
+        linkWidth={link => Math.max(0.5, 1 + (link.weight / maxWeight) * 3)}
+        linkDirectionalArrowLength={isDirected ? 5 : 0}
+        linkDirectionalArrowRelPos={1}
+        linkLabel={link => link.label}
+        linkCurvature={link => {
+          // Curve parallel edges between same node pairs
+          const key = [link.source?.id || link.source, link.target?.id || link.target].sort().join('-')
+          const rev = [link.target?.id || link.target, link.source?.id || link.source].sort().join('-')
+          return key === rev ? 0 : 0.15
+        }}
+        d3VelocityDecay={0.3}
+        cooldownTicks={80}
+        enableZoomInteraction={true}
+        enablePanInteraction={true}
+      />
     </div>
   )
 })
@@ -224,7 +235,6 @@ const ChatMessage = memo(function ChatMessage({
             <BasicGraphView
               key={`${msg.id}-graph-${graphIndex}`}
               graph={graph}
-              graphKey={`${msg.id}-${graphIndex}`}
             />
           ))}
         </div>