Merge pull request #6779 from FlowFuse/ff-expert

FlowFuse Expert Document for Chat Interface

Author: PabloFilomeno83

docs/admin/introduction.md

@@ -186,10 +186,10 @@ including what Instance Types are available and any limits that should be applie
     Provides a Team scoped shared SQL Relational Database (Requires specific configuration). More details [here](../user/ff-tables.md)
  - **Assistant Inline Code Completion**
 
-    Allows LLM assistance when writing Functions nodes (requires a token from FlowFuse Support and available to Enterprise License holders). More details [here](../user/expert.md)
+    Allows LLM assistance when writing Functions nodes (requires a token from FlowFuse Support and available to Enterprise License holders). More details [here](/docs/user/expert/)
  - **Generated Snapshot Descriptions**
 
-    Enables the creation of Generative AI descriptions of Snapshots (requires a token from FlowFuse Support and available to Enterprise License holders). More details [here](../user/expert.md)
+    Enables the creation of Generative AI descriptions of Snapshots (requires a token from FlowFuse Support and available to Enterprise License holders). More details [here](/docs/user/expert/)
 
 ### Managing Instance Types
 

docs/user/expert/chat.md

@@ -0,0 +1,225 @@
+---
+navTitle: Chat Interface
+---
+
+# Chat Interface
+
+The FlowFuse Expert chat interface is your conversational AI companion that you can open directly in the Node-RED editor. While other FlowFuse Expert features (like inline code completions and next-node prediction) work passively in the Node-RED Editor, the chat interface is where you actively engage the AI - asking questions, exploring your flows, and gaining insights from your live data.
+
+## Opening the Chat Interface
+
+To open the chat, first open your Node-RED instance using the Open Editor button. This launches Immersive Mode.
+
+## Chat Modes
+
+The chat interface operates in two distinct modes. You can switch between them using the **Mode Selector** at the top of the Expert panel.
+
+<div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 12px; margin: 20px 0;">
+
+  <a class="assistant-feature" href="#support-mode">
+    <svg width="48" height="48" viewBox="0 0 24 24" class="icon-stroke" xmlns="http://www.w3.org/2000/svg">
+      <path d="M21 15a2 2 0 01-2 2H7l-4 4V5a2 2 0 012-2h14a2 2 0 012 2z" stroke-width="2"/>
+      <path d="M8 9h8M8 13h6" stroke-width="1.5" stroke-linecap="round"/>
+    </svg>
+    <label style="margin: 10px 0; font-size: 16px; color: #333;">Support Mode</label>
+  </a>
+
+  <a class="assistant-feature" href="#insights-mode">
+    <svg width="48" height="48" viewBox="0 0 24 24" class="icon-stroke" xmlns="http://www.w3.org/2000/svg">
+      <circle cx="12" cy="12" r="3" stroke-width="2"/>
+      <path d="M12 2v3M12 19v3M4.22 4.22l2.12 2.12M17.66 17.66l2.12 2.12M2 12h3M19 12h3M4.22 19.78l2.12-2.12M17.66 6.34l2.12-2.12" stroke-width="2" stroke-linecap="round"/>
+    </svg>
+    <label style="margin: 10px 0; font-size: 16px; color: #333;">Insights Mode</label>
+  </a>
+
+</div>
+
+### Support Mode
+
+**Support mode** is for flow-building assistance. Use it when you need help understanding, building, or debugging your Node-RED flows. In this mode, the Expert draws on its knowledge of Node-RED, your installed palette, and the context of your current flows to answer questions and provide guidance.
+
+Typical use cases in Support mode:
+- "How do I convert data to CSV for writing to file & do you have any flow examples?"
+- "Explain what this flow is doing"
+- "Why is this node outputting a number instead of a string?"
+- "Is `node-red-contrib-string` node installed on this instance?"
+
+#### Context: What the Expert Can See
+
+Support mode becomes significantly more helpful when the Expert has context about your environment. Context is not automatic, you choose what to share with the Expert depending on what you need help with.
+
+<div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 12px; margin: 20px 0;">
+
+  <a class="assistant-feature" href="#palette-context">
+    <svg width="48" height="48" viewBox="0 0 24 24" class="icon-stroke" xmlns="http://www.w3.org/2000/svg">
+      <rect x="3" y="3" width="7" height="7" stroke-width="2" rx="1"/>
+      <rect x="14" y="3" width="7" height="7" stroke-width="2" rx="1"/>
+      <rect x="3" y="14" width="7" height="7" stroke-width="2" rx="1"/>
+      <rect x="14" y="14" width="7" height="7" stroke-width="2" rx="1"/>
+    </svg>
+    <label style="margin: 10px 0; font-size: 16px; color: #333;">Palette Context</label>
+  </a>
+
+  <a class="assistant-feature" href="#flow-context">
+    <svg width="48" height="48" viewBox="0 0 24 24" class="icon-stroke" xmlns="http://www.w3.org/2000/svg">
+      <path d="M5 12h14M12 5l7 7-7 7" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+    </svg>
+    <label style="margin: 10px 0; font-size: 16px; color: #333;">Flow Context</label>
+  </a>
+
+  <a class="assistant-feature" href="#debug-context">
+    <svg width="48" height="48" viewBox="0 0 24 24" class="icon-stroke" xmlns="http://www.w3.org/2000/svg">
+      <path d="M12 8v4l3 3" stroke-width="2" stroke-linecap="round"/>
+      <circle cx="12" cy="12" r="9" stroke-width="2"/>
+      <path d="M8 2l1.5 2M16 2l-1.5 2" stroke-width="1.5" stroke-linecap="round"/>
+    </svg>
+    <label style="margin: 10px 0; font-size: 16px; color: #333;">Debug Context</label>
+  </a>
+
+</div>
+
+##### Palette Context
+
+To add Palette Context, click the **Resource Selector** button (paperclip icon) in the chat interface and select **Palette**. Once added, the Expert has access to information about the nodes installed in your Node-RED instance - including installed packages and their versions.
+
+This allows you to ask questions like:
+- "Is my palette up to date?"
+- "What version of node-red-dashboard is installed?"
+- "Do I have a node available for reading from a PostgreSQL database?"
+
+The Expert can use palette context to tailor its suggestions - for example, recommending nodes you actually have installed rather than suggesting ones that are not available.
+
+![Palette Context discussion with the FlowFuse Expert.](../images/assistant/palette-context.gif){data-zoomable}
+
+##### Flow Context
+
+To add Flow Context, select the flow you want the Expert to reference from the flow tabs in the Node-RED editor. The selected flow is then added as context for the Expert to read and reason about.
+
+This makes it possible to ask questions directly about your flows without having to copy and paste JSON or describe your configuration manually.
+
+This allows you to ask questions like:
+- "What does this flow do?"
+- "Why does this flow output a number instead of a string?"
+- "Is there something wrong with this flow? I don't seem to get an output from the debug node!"
+
+Flow Context is what makes the Expert genuinely useful as a debugging and code review tool - it can see the same flow you're looking at and reason about it directly.
+
+![FlowFuse Context discussion with the FlowFuse Expert.](../images/assistant/flow-context.gif){data-zoomable}
+
+##### Debug Context
+
+To add Debug Context, you have 2 options:
+1. Add individual log entries by clicking the ➕ button that appears over your debug message
+2. Click the **Resource Selector** button (paperclip icon) in the chat interface and select **Add Debug Logs**. 
+
+Once added, the Expert has access to the messages and output currently captured in your Node-RED debug panel.
+
+This allows the Expert to reason directly about the data or errors you are getting from your nodes at runtime, not just the structure of the flow itself.
+
+This allows you to ask questions like:
+- "Why is this debug output a number instead of a string?"
+- "What does this error message in the debug panel mean?"
+- "Is the payload structure here what my downstream node expects?"
+
+Debug Context is especially useful in combination with Flow Context - together they give the Expert both the structure of your flow and the actual data it is producing, making debugging significantly more effective.
+
+![Debug Context discussion with the FlowFuse Expert.](../images/assistant/expert-debug-context.gif){data-zoomable}
+
+#### Resetting Context
+
+If the Expert starts giving unexpected or inconsistent answers, it may be due to accumulated context from earlier in the conversation influencing its responses. Use the **Start Over** button to clear the conversation and start fresh with a clean context.
+
+### Insights Mode
+
+**Insights mode** connects the Expert to your live data via **Model Context Protocol (MCP)**. Use it when you want to query, analyze, or interact with real-world data - not just your Node-RED flows.
+
+In Insights mode, you first select an MCP Server that you've built using [FlowFuse MCP Server Nodes](https://flowfuse.com/node-red/flowfuse/mcp/). The Expert can then use the tools and resources exposed by that server to answer questions against your live operational data. If you haven't built an MCP Server yet, see the guide on [building an MCP Server using FlowFuse](https://flowfuse.com/blog/2025/10/building-mcp-server-using-flowfuse/).
+
+Typical use cases in Insights mode:
+- You have an MCP Resource named `production_lines_facilities_list` that returns a list of your production lines, their facility names and the facility types (stamping, assembly, packaging etc)
+    - You can ask: "List all stamping facilities on our production lines"
+- You have added an MCP Tool named `get_production_live_state`
+    -You can ask: "Tell me which of any of my assembly facilities are running and at what speed"
+- You have added an MCP tool named `get_production_oee` that
+    - You can ask: "Show me the worst 3 OEE results for all production line facilities"
+
+> **Note:** Insights mode is currently in Beta. Capabilities are actively being expanded.
+
+**To switch to Insights mode:**
+1. Open the FlowFuse Expert panel
+2. Use the **Mode Selector** to switch from "Chat" to "Insights"
+3. Select the MCP Server you want to query
+4. Ask your question
+
+## Writing Better Queries
+
+The quality of the Expert's responses depends heavily on how your questions are phrased. The more specific and contextual your query, the more accurate and actionable the answer.
+
+Here are some common patterns to improve your queries:
+
+### Be specific about what you're referring to
+
+Vague references like "it", "this", or "that" require the Expert to guess what you mean. Name the thing explicitly.
+
+| Less effective | More effective |
+|---|---|
+| "Is it up to date?" | "Is my palette up to date?" |
+| "What does this mean?" | "What does this log entry mean?" |
+| "Why did this happen?" | "Why did this error log occur?" |
+
+### Describe the actual problem, not just a symptom
+
+If something isn't behaving as expected, describe what you expected versus what you got.
+
+| Less effective | More effective |
+|---|---|
+| "This doesn't work" | "My flow should output a string but it is outputting a number" |
+| "The node is broken" | "The HTTP Request node is returning a 401 status code" |
+
+### Include relevant details upfront
+
+The Expert works best when it doesn't have to ask clarifying questions. Include relevant context - the node type, the message property, the protocol, or the error - in your initial query.
+
+| Less effective | More effective |
+|---|---|
+| "How do I connect to a database?" | "How do I connect to a PostgreSQL database using the node-red-contrib-postgresql node?" |
+| "How do I format this?" | "How do I format a Unix timestamp as an ISO 8601 string in a Function node?" |
+
+### Ask one question at a time for complex topics
+
+If you have multiple questions, consider asking them separately so the Expert can give a focused answer to each rather than a broad response that covers everything superficially.
+
+*See also: [Node-RED Embedded AI](/docs/user/expert/node-red-embedded-ai/) for AI features built directly into the Node-RED editor.*
+
+<style>
+  .assistant-feature {
+    border: 1px solid #ddd;
+    border-radius: 6px;
+    padding: 18px;
+    text-align: center;
+    background: #f9f9f9;
+    display: flex;
+    align-items: center;
+    justify-content: flex-start;
+    gap: 12px;
+    text-decoration: none;
+  }
+  .assistant-feature svg.icon-stroke path,
+  .assistant-feature svg.icon-stroke line,
+  .assistant-feature svg.icon-stroke circle,
+  .assistant-feature svg.icon-stroke polyline,
+  .assistant-feature svg.icon-stroke rect {
+    stroke: #2563eb;
+    fill: none;
+  }
+  .assistant-feature:hover {
+    border-color: #2563eb;
+    color: #2563eb;
+    cursor: pointer;
+    text-decoration: none;
+  }
+  .assistant-feature label {
+    font-size: 1.15rem;
+    pointer-events: none;
+  }
+</style>

docs/user/expert/index.md

@@ -0,0 +1,37 @@
+---
+navTitle: FlowFuse Expert
+---
+
+# FlowFuse Expert
+
+FlowFuse Expert is the AI built into FlowFuse and the Node-RED editor. It is not a generic AI assistant bolted onto the side of your workflow, it understands your flows, your installed nodes, your live data, and your environment in real time.
+
+**FlowFuse Expert is automatically installed and available in all hosted and remote instances running within or connected to FlowFuse**, no manual installation or configuration required.
+
+## What FlowFuse Expert Can Do
+
+FlowFuse Expert works in two distinct ways inside your environment.
+
+### Chat Interface
+
+The Chat Interface is a conversational AI panel built into the FlowFuse Platform and accessible directly within the Node-RED editor. You can ask questions, get help building and debugging flows, query live operational data via MCP, and explore your environment using context-aware tools.
+
+The Chat Interface supports two modes - **Support** for flow-building assistance, and **Insights** for querying live data via MCP tools and resources.
+
+[Learn more about the Chat Interface](/docs/user/expert/chat/)
+
+### AI in Node-RED
+
+FlowFuse Expert brings AI assistance directly into the Node-RED editor itself. It works where you already are - inside node editors, on the canvas, without requiring you to open a separate panel.
+
+AI features within the Node-RED editor include inline code completions, flow autocomplete, function builder, flow explainer, JSON generation, and CSS and HTML generation for FlowFuse Dashboard.
+
+> **Note:** FlowFuse Expert's in-editor AI features can also be installed as a plugin into Node-RED instances running outside of FlowFuse, using the `@flowfuse/nr-assistant` package from the Node-RED Palette Manager. This requires a FlowFuse Cloud account but does not require a paid subscription for the current release. The Chat Interface is exclusive to FlowFuse and cannot be installed externally.
+
+[Learn more about AI in Node-RED](/docs/user/expert/node-red-embedded-ai/)
+
+## Data Privacy
+
+No data from FlowFuse is used by third-party AI service providers for training models.
+
+Some features utilize the OpenAI API, and as such some data is sent to OpenAI to process requests. In accordance with the [OpenAI Terms of Service](https://help.openai.com/en/articles/5722486-how-your-data-is-used-to-improve-model-performance) no data is used for training of future models. OpenAI will retain data sent via its APIs for 30 days for abuse monitoring, after which it is permanently deleted.