feat(AI-179): implement /fiona search — browse raw sources without synthesized answer

apps/fiona-slack/.env.sample

@@ -15,6 +15,12 @@
 # Defaults to www.ed-fi.org,docs.ed-fi.org
 # PERPLEXITY_DOMAIN_FILTER=www.ed-fi.org,docs.ed-fi.org
 
+# Optional, /fiona search settings.
+# Maximum number of sources returned per search (default 5, hard cap 10).
+# SEARCH_MAX_SOURCES=5
+# Maximum words per source snippet before truncation (default 160).
+# SEARCH_SNIPPET_MAX_WORDS=160
+
 # Deployment type label recorded with feedback in Cosmos DB (local, insiders, production).
 DEPLOYMENT_TYPE=local
 

apps/fiona-slack/package.json

@@ -30,6 +30,7 @@
   "dependencies": {
     "@azure/cosmos": "^4.9.1",
     "@azure/identity": "^4.13.0",
+    "@perplexity-ai/perplexity_ai": "^0.37.0",
     "@slack/bolt": "^4.6.0",
     "dotenv": "~17.3.1",
     "openai": "^6.25.0"

apps/fiona-slack/src/agent/feedback-response-types.js

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+// Licensed to the Ed-Fi Alliance under one or more agreements.
+// The Ed-Fi Alliance licenses this file to you under the Apache License, Version 2.0.
+// See the LICENSE and NOTICES files in the project root for more information.
+
+export const FEEDBACK_RESPONSE_TYPES = Object.freeze({
+  SYNTHESIS: 'synthesis',
+  SEARCH: 'search',
+  ASK: 'ask',
+});

apps/fiona-slack/src/agent/feedback-store.js

@@ -5,6 +5,7 @@
 
 import { CosmosClient } from '@azure/cosmos';
 import { DefaultAzureCredential } from '@azure/identity';
+import { FEEDBACK_RESPONSE_TYPES } from './feedback-response-types.js';
 
 const COSMOS_ENDPOINT = process.env.COSMOS_ENDPOINT;
 const COSMOS_KEY = process.env.COSMOS_KEY;
@@ -146,6 +147,7 @@ async function getContainer(logger) {
  * @param {string|null} [feedback.reason] - Optional reason for the feedback
  * @param {string|null} feedback.userMessage - The user's message that prompted the response
  * @param {string|null} feedback.botResponse - The bot's response being rated
+ * @param {'synthesis'|'search'|'ask'} [feedback.responseType] - Response category for the feedback
  * @param {string} [feedback.interactionType] - Optional interaction type (e.g., 'slash_escalate')
  * @param {{ warn?: (msg: string) => void }} [feedback.logger] - Optional logger for warnings
  */
@@ -157,12 +159,17 @@ export async function recordFeedback({
   reason,
   userMessage,
   botResponse,
+  responseType,
   interactionType,
   logger,
 }) {
   const c = await getContainer(logger);
   if (!c) return;
 
+  const normalizedResponseType = Object.values(FEEDBACK_RESPONSE_TYPES).includes(responseType)
+    ? responseType
+    : FEEDBACK_RESPONSE_TYPES.SYNTHESIS;
+
   const doc = {
     id: `${userId}_${messageTs}`,
     // feedbackId duplicates id because the partition key path requires /feedbackId;
@@ -175,6 +182,7 @@ export async function recordFeedback({
     reason: reason?.trim() ? reason.trim() : null,
     userMessage,
     botResponse,
+    responseType: normalizedResponseType,
     ...(interactionType ? { interactionType } : {}),
     deploymentType: process.env.DEPLOYMENT_TYPE || 'local',
     timestamp: new Date().toISOString(),

apps/fiona-slack/src/agent/llm-caller.js

@@ -3,6 +3,7 @@
 // The Ed-Fi Alliance licenses this file to you under the Apache License, Version 2.0.
 // See the LICENSE and NOTICES files in the project root for more information.
 
+import Perplexity from '@perplexity-ai/perplexity_ai';
 import { OpenAI } from 'openai';
 import {
   incrementDegradedNoMetadataCount,
@@ -88,12 +89,16 @@ const SYSTEM_PROMPT = process.env.SYSTEM_PROMPT || DEFAULT_SYSTEM_PROMPT;
 // use the OpenAI SDK with a custom baseURL.
 /** @type {OpenAI | undefined} */
 let perplexityClient;
+// Dedicated Perplexity SDK client for the Search API (POST /search).
+/** @type {Perplexity | undefined} */
+let perplexitySearchClient;
 
 if (PERPLEXITY_API_KEY) {
   perplexityClient = new OpenAI({
     apiKey: PERPLEXITY_API_KEY,
     baseURL: 'https://api.perplexity.ai',
   });
+  perplexitySearchClient = new Perplexity({ apiKey: PERPLEXITY_API_KEY });
 }
 
 /**
@@ -485,6 +490,52 @@ export async function callLLM(streamer, prompts, logger) {
   return { metadata, botText, systemPromptVersion: SYSTEM_PROMPT_VERSION };
 }
 
+// ─── Source Search ─────────────────────────────────────────────────────────
+// Read from env (default 5). Hard-capped at SEARCH_ABSOLUTE_MAX before the API call.
+const SEARCH_MAX_SOURCES = parsePositiveIntEnv(process.env.SEARCH_MAX_SOURCES, 5);
+const SEARCH_ABSOLUTE_MAX = 10;
+
+/**
+ * Call the Perplexity Search API to retrieve source documents for a query.
+ * Returns a list of normalized sources (URL, title, optional snippet) with no
+ * synthesized answer. Used by the `/fiona search` command.
+ *
+ * Uses POST /search (not chat completions) so the API handles result ranking
+ * and count limiting natively via `max_results`.
+ *
+ * @param {string} query - Search query from the user (unsanitized)
+ * @param {Object} [options]
+ * @param {number} [options.maxSources] - Maximum sources to return (defaults to SEARCH_MAX_SOURCES env, capped at 10)
+ * @param {import('@slack/logger').Logger} [options.logger]
+ * @returns {Promise<Array<import('./utils/source-normalizer.js').NormalizedSource>>}
+ */
+export async function searchForSources(query, { maxSources = SEARCH_MAX_SOURCES, logger } = {}) {
+  if (!perplexitySearchClient) return [];
+  if (!query || !query.trim()) return [];
+
+  const cappedMaxSources = Math.min(maxSources, SEARCH_ABSOLUTE_MAX);
+
+  try {
+    const response = await perplexitySearchClient.search.create({
+      query,
+      max_results: cappedMaxSources,
+      search_domain_filter: PERPLEXITY_DOMAIN_FILTER,
+    });
+
+    const rawResults = response?.results;
+
+    if (Array.isArray(rawResults) && rawResults.length > 0) {
+      const { sources } = normalizeSources(rawResults, { maxSources: cappedMaxSources });
+      return sources;
+    }
+
+    return [];
+  } catch (error) {
+    logger?.warn?.(`Search failed: ${error.message}`);
+    return [];
+  }
+}
+
 // ─── Escalation Summary ─────────────────────────────────────────────────────
 const ESCALATION_SUMMARY_SYSTEM_PROMPT =
   'You summarize a Slack conversation between a user and Fiona (an Ed-Fi AI assistant) for a human support team. ' +

apps/fiona-slack/src/agent/search-caller.js

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: Apache-2.0
+// Licensed to the Ed-Fi Alliance under one or more agreements.
+// The Ed-Fi Alliance licenses this file to you under the Apache License, Version 2.0.
+// See the LICENSE and NOTICES files in the project root for more information.
+
+/**
+ * Search abstraction layer for the `/fiona search` skill.
+ * Wraps the LLM-layer search call and provides Slack-specific formatting.
+ * Imported by fiona.js so the slash command handler never depends on llm-caller
+ * directly (preserving the architectural separation of concerns).
+ */
+
+import { searchForSources } from './llm-caller.js';
+
+export { searchForSources };
+
+const SEARCH_NO_RESULTS_TEXT = '🔍 No sources found for _"{{query}}"_. Try rephrasing your query.';
+// Exported so slash and say()-based handlers can share a single error string.
+export const SEARCH_ERROR_TEXT = ':warning: Search encountered an error. Please try again later.';
+
+// Read snippet max word count from SEARCH_SNIPPET_MAX_WORDS env var.
+// Falls back to 160 when the env var is absent, non-numeric, or not a positive integer.
+const _snippetMaxRaw = Number.parseInt(process.env.SEARCH_SNIPPET_MAX_WORDS ?? '', 10);
+const SNIPPET_MAX_WORDS = Number.isFinite(_snippetMaxRaw) && _snippetMaxRaw > 0 ? _snippetMaxRaw : 160;
+
+/**
+ * Strip common markdown syntax from a snippet and truncate to the configured
+ * maximum word count (SNIPPET_MAX_WORDS).
+ * Perplexity Search API snippets can contain bold markers, headings, and multi-
+ * paragraph text; stripping and truncating keeps the Slack source list compact.
+ *
+ * Only `**bold**` and `### heading` patterns are removed; single-asterisk italic
+ * is intentionally left untouched to avoid false positives on maths/code notation
+ * (e.g. `a * b`).
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function truncateSnippet(text) {
+  if (!text || typeof text !== 'string') return '';
+  // Collapse newlines and runs of whitespace to a single space
+  let cleaned = text
+    .replace(/\n+/g, ' ')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+  // Strip bold markers (**text**) and heading markers (## …)
+  cleaned = cleaned.replace(/\*\*([\s\S]*?)\*\*/g, '$1').replace(/#{1,6}\s+/g, '');
+  const words = cleaned.split(/\s+/);
+  if (words.length <= SNIPPET_MAX_WORDS) return cleaned;
+  return `${words.slice(0, SNIPPET_MAX_WORDS).join(' ')}…`;
+}
+
+/**
+ * Escape user-supplied text before embedding it in a Slack mrkdwn message.
+ * Only `&`, `<`, and `>` need HTML-entity encoding per the Slack API spec.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function escapeMrkdwn(text) {
+  if (!text || typeof text !== 'string') return '';
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/**
+ * Format a list of normalized sources into a Slack Block Kit message with
+ * a mrkdwn plain-text fallback. Each result is rendered as a section block
+ * (title link) and an optional context block (snippet), separated by dividers.
+ *
+ * @param {string} query - The original search query (unsanitized)
+ * @param {Array<import('./llm-caller.js').NormalizedSource>} sources - Normalized source list
+ * @returns {{ text: string, blocks: Array<object> | null }} Slack message payload
+ */
+export function formatSearchResults(query, sources) {
+  const safeQuery = escapeMrkdwn(query);
+
+  if (!Array.isArray(sources) || sources.length === 0) {
+    return { text: SEARCH_NO_RESULTS_TEXT.replace('{{query}}', safeQuery), blocks: null };
+  }
+
+  const headerText = `🔍 *Search results for:* _"${safeQuery}"_`;
+
+  // ── Block Kit layout ───────────────────────────────────────────────────────
+  const blocks = [{ type: 'section', text: { type: 'mrkdwn', text: headerText } }, { type: 'divider' }];
+
+  for (let i = 0; i < sources.length; i++) {
+    const source = sources[i];
+    const link = `*<${source.url}|${escapeMrkdwn(source.title || source.hostname)}>*`;
+    blocks.push({ type: 'section', text: { type: 'mrkdwn', text: `${i + 1}. ${link}` } });
+
+    const rawSnippet = truncateSnippet(source.snippet);
+    if (rawSnippet) {
+      blocks.push({
+        type: 'context',
+        elements: [{ type: 'mrkdwn', text: `_"${escapeMrkdwn(rawSnippet)}"_` }],
+      });
+    }
+
+    if (i < sources.length - 1) {
+      blocks.push({ type: 'divider' });
+    }
+  }
+
+  // ── Plain-text fallback (used by Slack notifications / accessibility) ──────
+  const items = sources.map((source, i) => {
+    const rawSnippet = truncateSnippet(source.snippet);
+    const snippet = rawSnippet ? `\n${rawSnippet}` : '';
+    return `${i + 1}. ${source.title || source.hostname} — ${source.url}${snippet}`;
+  });
+  const text = `${headerText}\n\n${items.join('\n\n')}`;
+
+  return { text, blocks };
+}

apps/fiona-slack/src/listeners/actions/feedback.js

@@ -3,6 +3,38 @@
 // The Ed-Fi Alliance licenses this file to you under the Apache License, Version 2.0.
 // See the LICENSE and NOTICES files in the project root for more information.
 
+import { FEEDBACK_RESPONSE_TYPES, parseFeedbackBlockId } from '../views/feedback_block.js';
+
+const SEARCH_QUERY_PATTERN = /^🔍 \*Search results for:\* _"([\s\S]+?)"_/;
+
+/**
+ * Resolve the contextual feedback block id from the action payload.
+ *
+ * @param {import("@slack/bolt").SlackAction} body
+ * @param {Record<string, any>} action
+ * @returns {string|null}
+ */
+function getFeedbackBlockId(body, action) {
+  if (typeof action?.block_id === 'string' && action.block_id.length > 0) {
+    return action.block_id;
+  }
+
+  if (!Array.isArray(body?.message?.blocks)) return null;
+  return body.message.blocks.find((block) => block?.type === 'context_actions')?.block_id ?? null;
+}
+
+/**
+ * Extract the original query from a formatted Fiona search response.
+ *
+ * @param {string} messageText
+ * @returns {string|null}
+ */
+function extractSearchQuery(messageText) {
+  if (typeof messageText !== 'string') return null;
+  const match = messageText.match(SEARCH_QUERY_PATTERN);
+  return match?.[1] ?? null;
+}
+
 /**
  * The `feedbackActionCallback` action responds to the `feedbackBlock` that displays
  * positive and negative feedback icons. This block is attached to the bottom of LLM
@@ -34,6 +66,7 @@ export const feedbackActionCallback = async ({ ack, body, client, logger }) => {
     const channel_id = body.channel.id;
     const user_id = body.user.id;
     const value = action.value;
+    const { responseType, interactionType } = parseFeedbackBlockId(getFeedbackBlockId(body, action));
 
     if (value !== 'good-feedback' && value !== 'bad-feedback') {
       logger.warn('Received unexpected feedback value', { value, channel_id, user_id, message_ts });
@@ -61,6 +94,11 @@ export const feedbackActionCallback = async ({ ack, body, client, logger }) => {
           userId: user_id,
           value,
           thread_ts,
+          responseType,
+          interactionType,
+          ...(responseType === FEEDBACK_RESPONSE_TYPES.SEARCH
+            ? { searchQuery: extractSearchQuery(body.message?.text) }
+            : {}),
         }),
         blocks: [
           {

apps/fiona-slack/src/listeners/assistant/message.js

@@ -17,7 +17,7 @@ import { buildThreadHistory } from '../../agent/thread-history.js';
 import { generateResponseId, shouldFinalize } from '../../agent/utils/idempotent-finalize.js';
 import { dispatchKeywordViaSay } from '../commands/command-dispatch.js';
 import { parseCommandKeyword } from '../commands/command-handler.js';
-import { feedbackBlock } from '../views/feedback_block.js';
+import { createFeedbackBlock, FEEDBACK_RESPONSE_TYPES } from '../views/feedback_block.js';
 
 /**
  * Handles when users send messages or select a prompt in an assistant thread
@@ -113,6 +113,7 @@ export const message = async ({ client, context, logger, message, say, setStatus
           threadTs: thread_ts,
           messageTs,
           source: 'assistant_escalate',
+          interactionType: 'assistant_message',
         });
         return;
       }
@@ -211,7 +212,12 @@ export const message = async ({ client, context, logger, message, say, setStatus
               text: 'The crowd appears to be astounded and applauds :popcorn:',
             },
           ],
-          blocks: [feedbackBlock],
+          blocks: [
+            createFeedbackBlock({
+              responseType: FEEDBACK_RESPONSE_TYPES.SYNTHESIS,
+              interactionType: 'assistant_message',
+            }),
+          ],
         });
       } else {
         // This second example shows a generated text response for the provided prompt
@@ -253,7 +259,14 @@ export const message = async ({ client, context, logger, message, say, setStatus
           logger.info(`[citations] state=${metadata.finalize_state} sources=${metadata.sources?.length ?? 0}`);
         }
 
-        await streamer.stop({ blocks: [feedbackBlock] });
+        await streamer.stop({
+          blocks: [
+            createFeedbackBlock({
+              responseType: FEEDBACK_RESPONSE_TYPES.SYNTHESIS,
+              interactionType: 'assistant_message',
+            }),
+          ],
+        });
         finalizeMetadataEnvelope(metadata);
 
         try {