@od-oneapp/ai-platform 0.1.0

package/src/tools/generic/tiptap-context.ts

@@ -0,0 +1,619 @@
+/**
+ * @fileoverview TipTap documentation context tool for AI SDK agents.
+ *
+ * Provides a search tool that answers questions about TipTap v3 capabilities
+ * by searching curated documentation chunks with semantic keyword matching.
+ *
+ * Migrated from @repo/ai/tools/tiptap-context-tool.ts
+ *
+ * @module @od-oneapp/ai-platform/tools/generic/tiptap-context
+ */
+
+import 'server-only';
+
+import { existsSync, promises as fs } from 'node:fs';
+import path from 'node:path';
+
+import { z } from 'zod/v4';
+
+import { tool } from '../../shared';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+type TiptapDocChunk = {
+  id: string;
+  category: string;
+  title: string;
+  content: string;
+  summary: string;
+  keywords: string[];
+  tokens: number;
+};
+
+type TiptapDocIndex = {
+  chunks: TiptapDocChunk[];
+  categories: Record<string, { chunkCount: number; keywords: string[] }>;
+};
+
+type SearchMatch = TiptapDocChunk & { score: number };
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const WORKSPACE_ROOT = process.cwd();
+
+function resolveDocPath(relativePath: string): string {
+  let current = WORKSPACE_ROOT;
+
+  while (true) {
+    const candidate = path.resolve(current, relativePath);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+
+  return path.resolve(WORKSPACE_ROOT, relativePath);
+}
+
+const TIPTAP_DOC_PATH = resolveDocPath('docs/llms/tiptap.txt');
+
+const DEFAULT_CHUNK_TOKEN_TARGET = 500;
+const MAX_KEYWORDS = 12;
+const MAX_RESULTS = 4;
+
+const STOP_WORDS = new Set([
+  'the',
+  'and',
+  'for',
+  'with',
+  'that',
+  'this',
+  'from',
+  'your',
+  'into',
+  'when',
+  'tiptap',
+  'editor',
+  'docs',
+  'learn',
+  'guide',
+  'using',
+  'about',
+  'more',
+  'how',
+  'api',
+  'overview',
+  'getting',
+  'started',
+]);
+
+const SYNONYM_MAP: Record<string, string[]> = {
+  react: ['next', 'nextjs', 'jsx'],
+  next: ['nextjs', 'react'],
+  collaboration: ['yjs', 'multiplayer', 'awareness'],
+  ai: ['assistant', 'generation', 'content'],
+  export: ['conversion', 'markdown', 'html', 'json', 'docx'],
+  import: ['conversion', 'docx', 'odt'],
+  formatting: ['style', 'styling', 'theme', 'css'],
+  extension: ['node', 'mark', 'custom extension'],
+  command: ['keyboard', 'shortcut', 'action'],
+  schema: ['nodes', 'marks', 'structure'],
+};
+
+// =============================================================================
+// Code Examples
+// =============================================================================
+
+const CODE_EXAMPLES: Array<{
+  id: string;
+  title: string;
+  description: string;
+  language: string;
+  code: string;
+  keywords: string[];
+}> = [
+  {
+    id: 'react-basic-editor',
+    title: 'Initialize TipTap in React',
+    description: 'Create a basic TipTap editor using StarterKit and controlled content.',
+    language: 'tsx',
+    keywords: ['react', 'starterkit', 'basic'],
+    code: `import { useEditor, EditorContent } from '@tiptap/react';
+import StarterKit from '@tiptap/starter-kit';
+
+export function BasicEditor() {
+  const editor = useEditor({
+    extensions: [StarterKit],
+    content: '<p>Hello TipTap!</p>',
+  });
+
+  if (!editor) return null;
+
+  return <EditorContent editor={editor} />;
+}`,
+  },
+  {
+    id: 'nextjs-ssr-setup',
+    title: 'Use TipTap inside Next.js App Router',
+    description:
+      'Wrap the TipTap editor in a Client Component and load configuration from the server.',
+    language: 'tsx',
+    keywords: ['next', 'react', 'app-router'],
+    code: `'use client';
+
+import { Suspense } from 'react';
+import dynamic from 'next/dynamic';
+
+const RichEditor = dynamic(() => import('./RichEditor').then(m => m.RichEditor), {
+  ssr: false,
+  loading: () => <p>Loading editor\u2026</p>,
+});
+
+export default function TiptapCanvas() {
+  return (
+    <section className="space-y-6">
+      <h1 className="text-xl font-semibold">Canvas Document</h1>
+      <Suspense fallback={<p>Preparing TipTap\u2026</p>}>
+        <RichEditor enableAI enableToolbar />
+      </Suspense>
+    </section>
+  );
+}
+`,
+  },
+  {
+    id: 'collaboration-setup',
+    title: 'Enable Collaboration Extensions',
+    description:
+      'Configure the Collaboration and CollaborationCursor extensions with a shared Yjs document.',
+    language: 'ts',
+    keywords: ['collaboration', 'yjs', 'multiplayer'],
+    code: `import Collaboration from '@tiptap/extension-collaboration';
+import CollaborationCursor from '@tiptap/extension-collaboration-cursor';
+import { Doc } from 'yjs';
+
+const ydoc = new Doc();
+
+const editor = new Editor({
+  extensions: [
+    StarterKit,
+    Collaboration.configure({ document: ydoc }),
+    CollaborationCursor.configure({
+      provider: providerInstance,
+      user: { name: userName, color: userColor },
+    }),
+  ],
+});
+`,
+  },
+  {
+    id: 'content-export',
+    title: 'Convert TipTap JSON to Markdown',
+    description: 'Serialize the editor state to Markdown for downstream systems.',
+    language: 'ts',
+    keywords: ['export', 'markdown', 'json'],
+    code: `import { generateJSON } from '@tiptap/html';
+import StarterKit from '@tiptap/starter-kit';
+
+export function toMarkdown(html: string) {
+  const json = generateJSON(html, [StarterKit]);
+  return json.content?.map(block => block.text).join('\\n') ?? '';
+}
+`,
+  },
+];
+
+const CATEGORY_EXAMPLE_MAP: Record<string, string[]> = {
+  Overview: ['react-basic-editor'],
+  Docs: ['react-basic-editor', 'nextjs-ssr-setup'],
+  'Editor Docs': ['react-basic-editor', 'nextjs-ssr-setup'],
+  'Editor Extensions Docs': ['collaboration-setup'],
+  'Content AI Docs': ['react-basic-editor'],
+  'Import / Export Docs': ['content-export'],
+  'Commands Docs': ['react-basic-editor'],
+};
+
+// =============================================================================
+// Tokenization & Indexing Helpers
+// =============================================================================
+
+let cachedIndexPromise: Promise<TiptapDocIndex> | null = null;
+
+function normalizeHeading(rawHeading: string): string {
+  return rawHeading.replace(/^#+\s*/, '').trim();
+}
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function tokenize(text: string): string[] {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function countTokens(text: string): number {
+  return tokenize(text).length;
+}
+
+function extractKeywords(text: string, maxKeywords = MAX_KEYWORDS): string[] {
+  const frequencies = new Map<string, number>();
+
+  for (const token of tokenize(text)) {
+    if (STOP_WORDS.has(token)) {
+      continue;
+    }
+
+    const synonyms = SYNONYM_MAP[token] ?? [];
+
+    frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+    for (const synonym of synonyms) {
+      frequencies.set(synonym, (frequencies.get(synonym) ?? 0) + 0.5);
+    }
+  }
+
+  return Array.from(frequencies.entries())
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, maxKeywords)
+    .map(([token]) => token);
+}
+
+function createSummary(content: string): string {
+  const lines = content
+    .split('\n')
+    .map(line => line.trim())
+    .filter(Boolean);
+
+  const bulletHighlights = lines
+    .filter(line => /^[-*]/.test(line))
+    .map(line => line.replace(/^[-*]\s*/, ''))
+    .slice(0, 3);
+
+  if (bulletHighlights.length > 0) {
+    return bulletHighlights.join(' ');
+  }
+
+  const sentences = content
+    .split(/(?<=[.!?])\s+/)
+    .map(sentence => sentence.trim())
+    .filter(Boolean)
+    .slice(0, 2);
+
+  return sentences.join(' ');
+}
+
+// =============================================================================
+// Document Parsing
+// =============================================================================
+
+function parseTiptapSections(
+  doc: string,
+): Array<{ category: string; title: string; content: string[] }> {
+  const sections: Array<{ category: string; title: string; content: string[] }> = [];
+  const lines = doc.split('\n');
+
+  let currentCategory = 'Overview';
+  let currentTitle = 'Overview';
+  let buffer: string[] = [];
+
+  function flush(): void {
+    if (buffer.length === 0) {
+      return;
+    }
+
+    const content = buffer.join('\n').trim();
+    if (!content) {
+      buffer = [];
+      return;
+    }
+
+    sections.push({ category: currentCategory, title: currentTitle, content: [content] });
+    buffer = [];
+  }
+
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd();
+
+    if (/^#\s/.test(line)) {
+      flush();
+      currentCategory = 'Overview';
+      currentTitle = normalizeHeading(line);
+      continue;
+    }
+
+    if (/^##\s/.test(line)) {
+      flush();
+      currentCategory = normalizeHeading(line);
+      currentTitle = currentCategory;
+      continue;
+    }
+
+    if (/^###\s/.test(line)) {
+      flush();
+      currentTitle = normalizeHeading(line);
+      continue;
+    }
+
+    buffer.push(line);
+  }
+
+  flush();
+
+  return sections;
+}
+
+function chunkSection(
+  section: { category: string; title: string; content: string[] },
+  chunkTokenTarget = DEFAULT_CHUNK_TOKEN_TARGET,
+): TiptapDocChunk[] {
+  const chunks: TiptapDocChunk[] = [];
+  const paragraphs = section.content
+    .join('\n')
+    .split(/\n{2,}/)
+    .map(paragraph => paragraph.trim())
+    .filter(Boolean);
+
+  let currentChunk: string[] = [];
+  let currentTokens = 0;
+  let chunkIndex = 0;
+
+  const pushChunk = (): void => {
+    if (currentChunk.length === 0) {
+      return;
+    }
+
+    const content = currentChunk.join('\n\n');
+    const tokens = countTokens(content);
+    const summary = createSummary(content);
+    const keywords = extractKeywords(content);
+
+    chunks.push({
+      id: `${slugify(section.category)}-${slugify(section.title)}-${chunkIndex}`,
+      category: section.category,
+      title: section.title,
+      content,
+      summary,
+      keywords,
+      tokens,
+    });
+
+    chunkIndex += 1;
+    currentChunk = [];
+    currentTokens = 0;
+  };
+
+  for (const paragraph of paragraphs) {
+    const paragraphTokens = countTokens(paragraph);
+
+    if (currentTokens + paragraphTokens > chunkTokenTarget && currentChunk.length > 0) {
+      pushChunk();
+    }
+
+    currentChunk.push(paragraph);
+    currentTokens += paragraphTokens;
+  }
+
+  pushChunk();
+
+  return chunks;
+}
+
+async function buildTiptapDocIndex(): Promise<TiptapDocIndex> {
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const doc = await fs.readFile(TIPTAP_DOC_PATH, 'utf8');
+  const sections = parseTiptapSections(doc);
+
+  const chunks = sections.flatMap(section => chunkSection(section));
+
+  const categories: TiptapDocIndex['categories'] = {};
+
+  for (const chunk of chunks) {
+    const categoryEntry = categories[chunk.category] ?? {
+      chunkCount: 0,
+      keywords: [],
+    };
+
+    categoryEntry.chunkCount += 1;
+    categoryEntry.keywords = Array.from(
+      new Set([...categoryEntry.keywords, ...chunk.keywords]),
+    ).slice(0, MAX_KEYWORDS);
+
+    categories[chunk.category] = categoryEntry;
+  }
+
+  return { chunks, categories };
+}
+
+async function getTiptapDocIndex(): Promise<TiptapDocIndex> {
+  if (!cachedIndexPromise) {
+    cachedIndexPromise = (async () => {
+      try {
+        return await buildTiptapDocIndex();
+      } catch (error) {
+        cachedIndexPromise = null;
+        throw error;
+      }
+    })();
+  }
+
+  return cachedIndexPromise;
+}
+
+// =============================================================================
+// Scoring & Ranking
+// =============================================================================
+
+function expandQueryTokens(tokens: string[]): Set<string> {
+  const expanded = new Set<string>(tokens);
+
+  for (const token of tokens) {
+    const synonyms = SYNONYM_MAP[token];
+    if (synonyms) {
+      for (const synonym of synonyms) {
+        expanded.add(synonym);
+      }
+    }
+  }
+
+  return expanded;
+}
+
+function scoreChunk(query: string, chunk: TiptapDocChunk): number {
+  const queryTokens = tokenize(query).filter(token => !STOP_WORDS.has(token));
+  const expandedTokens = expandQueryTokens(queryTokens);
+  const chunkTokens = new Set(chunk.keywords);
+
+  let overlapScore = 0;
+  for (const token of expandedTokens) {
+    if (chunkTokens.has(token)) {
+      overlapScore += 2;
+    }
+
+    if (chunk.content.toLowerCase().includes(token)) {
+      overlapScore += 1;
+    }
+
+    if (chunk.title.toLowerCase().includes(token)) {
+      overlapScore += 1.5;
+    }
+
+    if (chunk.category.toLowerCase().includes(token)) {
+      overlapScore += 1.5;
+    }
+  }
+
+  const lengthPenalty = Math.max(1, chunk.tokens / DEFAULT_CHUNK_TOKEN_TARGET);
+
+  return overlapScore / lengthPenalty;
+}
+
+function rankChunks(query: string, chunks: TiptapDocChunk[]): SearchMatch[] {
+  return chunks
+    .map(chunk => ({ ...chunk, score: scoreChunk(query, chunk) }))
+    .filter(match => match.score > 0)
+    .sort((a, b) => b.score - a.score);
+}
+
+function createAnswer(query: string, matches: SearchMatch[]): string {
+  if (matches.length === 0) {
+    return `No TipTap documentation matches were found for "${query}". Try broadening the query or referencing supported features like React integration, collaboration, or conversions.`;
+  }
+
+  const bullets = matches.map(match => {
+    return `\u2022 ${match.title} (${match.category}): ${match.summary}`;
+  });
+
+  return bullets.join('\n');
+}
+
+function selectCodeExamples(
+  includeExamples: boolean,
+  query: string,
+  matches: SearchMatch[],
+): typeof CODE_EXAMPLES {
+  if (!includeExamples) {
+    return [];
+  }
+
+  const matchedCategories = new Set(matches.map(match => match.category));
+  const queryTokens = new Set(tokenize(query));
+
+  const suggestedExampleIds = new Set<string>();
+
+  for (const category of matchedCategories) {
+    const exampleIds = CATEGORY_EXAMPLE_MAP[category];
+    if (exampleIds) {
+      exampleIds.forEach(id => suggestedExampleIds.add(id));
+    }
+  }
+
+  for (const example of CODE_EXAMPLES) {
+    if (example.keywords.some(keyword => queryTokens.has(keyword))) {
+      suggestedExampleIds.add(example.id);
+    }
+  }
+
+  return CODE_EXAMPLES.filter(example => suggestedExampleIds.has(example.id)).slice(0, 3);
+}
+
+// =============================================================================
+// Tool Export
+// =============================================================================
+
+/**
+ * TipTap documentation context tool.
+ *
+ * Answers questions about TipTap v3 capabilities by searching curated
+ * documentation chunks with semantic keyword matching.
+ *
+ * @example
+ * ```ts
+ * import { tiptapContextTool } from '@od-oneapp/ai-platform/tools';
+ *
+ * const result = await streamText({
+ *   model,
+ *   tools: { tiptapContext: tiptapContextTool },
+ *   messages,
+ * });
+ * ```
+ */
+export const tiptapContextTool = tool({
+  description:
+    'Answer questions about TipTap v3 capabilities by searching curated documentation chunks with semantic keyword matching.',
+  inputSchema: z.object({
+    query: z.string().min(1, 'query is required'),
+    context: z.string().optional(),
+    includeExamples: z.boolean().optional().default(true),
+    limit: z.number().int().min(1).max(MAX_RESULTS).optional().default(3),
+  }),
+  execute: async ({ query, context, includeExamples = true, limit = 3 }) => {
+    const index = await getTiptapDocIndex();
+
+    const searchQuery = [query, context].filter(Boolean).join('\n');
+
+    const ranked = rankChunks(searchQuery, index.chunks);
+    const topMatches = ranked.slice(0, limit);
+
+    const answer = createAnswer(searchQuery, topMatches);
+
+    return {
+      answer,
+      query,
+      matchedCount: ranked.length,
+      relevantSections: topMatches.map(match => ({
+        id: match.id,
+        category: match.category,
+        title: match.title,
+        summary: match.summary,
+        keywords: match.keywords,
+        score: Number(match.score.toFixed(3)),
+        content: match.content,
+      })),
+      codeExamples: selectCodeExamples(includeExamples, searchQuery, topMatches),
+      metadata: {
+        categories: topMatches.map(match => match.category),
+        indexSize: index.chunks.length,
+      },
+    };
+  },
+});
+
+/** Input type for the tiptapContextTool. */
+export type TiptapContextToolInput = z.infer<typeof tiptapContextTool.inputSchema>;

package/src/tools/generic/web-search-tool.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Pre-configured web search tool.
+ *
+ * Drop-in replacement for the legacy @repo/ai webSearchTool.
+ * Auto-configures from environment (EXA_API_KEY).
+ */
+
+import { z } from 'zod';
+
+import { tool } from '../../shared';
+
+import { createExaSearchTool, type ExaClient } from './web-search';
+
+let cachedExaTool: ReturnType<typeof createExaSearchTool> | null = null;
+
+const webSearchInputSchema = z.object({
+  query: z.string().min(1).describe('Search query'),
+  maxResults: z.number().int().positive().default(5).describe('Maximum results'),
+  timeRange: z.string().optional().describe('Time range filter'),
+  region: z.string().optional().describe('Geographic region'),
+});
+
+/**
+ * Pre-configured web search tool that auto-detects Exa API key from environment.
+ *
+ * @example
+ * ```ts
+ * import { webSearchTool } from '@od-oneapp/ai-platform/tools';
+ *
+ * const result = await generateText({
+ *   model,
+ *   tools: { webSearch: webSearchTool },
+ *   prompt: 'Search for...',
+ * });
+ * ```
+ */
+export const webSearchTool = tool({
+  description: 'Search the web using Exa when configured',
+  inputSchema: webSearchInputSchema,
+  execute: async ({ query, maxResults, timeRange, region }) => {
+    const apiKey = process.env.EXA_API_KEY;
+
+    if (apiKey) {
+      if (!cachedExaTool) {
+        cachedExaTool = createExaSearchTool(
+          { apiKey, numResults: maxResults ?? 5 },
+          undefined as unknown as ExaClient,
+        );
+      }
+
+      try {
+        const timeoutMs = Number(process.env.AI_WEBSEARCH_TIMEOUT_MS) || 15000;
+        const result = await Promise.race([
+          cachedExaTool.execute?.({ query }, {} as never),
+          new Promise((_resolve, reject) =>
+            setTimeout(() => reject(new Error('Web search timeout')), timeoutMs),
+          ),
+        ]);
+        const results = Array.isArray(result) ? result : [];
+        return {
+          query,
+          results,
+          totalResults: results.length,
+          timeRange,
+          region,
+          source: 'exa' as const,
+        };
+      } catch {
+        // Fall through to empty results
+      }
+    }
+
+    return {
+      query,
+      results: [] as unknown[],
+      totalResults: 0,
+      timeRange,
+      region,
+      source: 'none' as const,
+    };
+  },
+});