@mastra/rag 0.1.19-alpha.2 → 0.1.19-alpha.4

package/src/document/extractors/questions.ts

@@ -0,0 +1,126 @@
+import type { MastraLanguageModel } from '@mastra/core/agent';
+import { PromptTemplate, defaultQuestionExtractPrompt, TextNode, BaseExtractor } from 'llamaindex';
+import type { QuestionExtractPrompt, BaseNode } from 'llamaindex';
+import { baseLLM, STRIP_REGEX } from './types';
+import type { QuestionAnswerExtractArgs } from './types';
+
+type ExtractQuestion = {
+  /**
+   * Questions extracted from the node as a string (may be empty if extraction fails).
+   */
+  questionsThisExcerptCanAnswer: string;
+};
+
+/**
+ * Extract questions from a list of nodes.
+ */
+export class QuestionsAnsweredExtractor extends BaseExtractor {
+  /**
+   * MastraLanguageModel instance.
+   * @type {MastraLanguageModel}
+   */
+  llm: MastraLanguageModel;
+
+  /**
+   * Number of questions to generate.
+   * @type {number}
+   * @default 5
+   */
+  questions: number = 5;
+
+  /**
+   * The prompt template to use for the question extractor.
+   * @type {string}
+   */
+  promptTemplate: QuestionExtractPrompt;
+
+  /**
+   * Wheter to use metadata for embeddings only
+   * @type {boolean}
+   * @default false
+   */
+  embeddingOnly: boolean = false;
+
+  /**
+   * Constructor for the QuestionsAnsweredExtractor class.
+   * @param {MastraLanguageModel} llm MastraLanguageModel instance.
+   * @param {number} questions Number of questions to generate.
+   * @param {QuestionExtractPrompt['template']} promptTemplate Optional custom prompt template (should include {context}).
+   * @param {boolean} embeddingOnly Whether to use metadata for embeddings only.
+   */
+  constructor(options?: QuestionAnswerExtractArgs) {
+    if (options?.questions && options.questions < 1) throw new Error('Questions must be greater than 0');
+
+    super();
+
+    this.llm = options?.llm ?? baseLLM;
+    this.questions = options?.questions ?? 5;
+    this.promptTemplate = options?.promptTemplate
+      ? new PromptTemplate({
+          templateVars: ['numQuestions', 'context'],
+          template: options.promptTemplate,
+        }).partialFormat({
+          numQuestions: '5',
+        })
+      : defaultQuestionExtractPrompt;
+    this.embeddingOnly = options?.embeddingOnly ?? false;
+  }
+
+  /**
+   * Extract answered questions from a node.
+   * @param {BaseNode} node Node to extract questions from.
+   * @returns {Promise<Array<ExtractQuestion> | Array<{}>>} Questions extracted from the node.
+   */
+  async extractQuestionsFromNode(node: BaseNode): Promise<ExtractQuestion> {
+    const text = node.getContent(this.metadataMode);
+    if (!text || text.trim() === '') {
+      return { questionsThisExcerptCanAnswer: '' };
+    }
+    if (this.isTextNodeOnly && !(node instanceof TextNode)) {
+      return { questionsThisExcerptCanAnswer: '' };
+    }
+
+    const contextStr = node.getContent(this.metadataMode);
+
+    const prompt = this.promptTemplate.format({
+      context: contextStr,
+      numQuestions: this.questions.toString(),
+    });
+
+    const questions = await this.llm.doGenerate({
+      inputFormat: 'messages',
+      mode: { type: 'regular' },
+      prompt: [
+        {
+          role: 'user',
+          content: [{ type: 'text', text: prompt }],
+        },
+      ],
+    });
+
+    let result = '';
+    try {
+      if (typeof questions.text === 'string') {
+        result = questions.text.replace(STRIP_REGEX, '').trim();
+      } else {
+        console.warn('Question extraction LLM output was not a string:', questions.text);
+      }
+    } catch (err) {
+      console.warn('Question extraction failed:', err);
+    }
+    return {
+      questionsThisExcerptCanAnswer: result,
+    };
+  }
+
+  /**
+   * Extract answered questions from a list of nodes.
+   * @param {BaseNode[]} nodes Nodes to extract questions from.
+   * @returns {Promise<Array<ExtractQuestion> | Array<{}>>} Questions extracted from the nodes.
+   */
+  async extract(nodes: BaseNode[]): Promise<Array<ExtractQuestion> | Array<object>> {
+    const results = await Promise.all(nodes.map(node => this.extractQuestionsFromNode(node)));
+
+    return results;
+  }
+}

package/src/document/extractors/summary.test.ts

@@ -0,0 +1,107 @@
+import { createOpenAI } from '@ai-sdk/openai';
+import { TextNode } from 'llamaindex';
+import { describe, it, expect, vi } from 'vitest';
+import { SummaryExtractor } from './summary';
+
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const model = openai('gpt-4o');
+
+vi.setConfig({ testTimeout: 10_000, hookTimeout: 10_000 });
+
+describe('SummaryExtractor', () => {
+  it('can use a custom model from the test suite', async () => {
+    const extractor = new SummaryExtractor({ llm: model });
+    const node = new TextNode({ text: 'A summary test using a custom model.' });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(typeof summary).toBe('string');
+    expect(summary.length).toBeGreaterThan(0);
+  });
+  it('extracts summary from normal text', async () => {
+    const extractor = new SummaryExtractor();
+    const node = new TextNode({ text: 'This is a test document.' });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(typeof summary).toBe('string');
+    expect(summary.length).toBeGreaterThan(0);
+  });
+
+  it('handles empty input gracefully', async () => {
+    const extractor = new SummaryExtractor();
+    const node = new TextNode({ text: '' });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(summary).toBe('');
+  });
+
+  it('supports prompt customization', async () => {
+    const extractor = new SummaryExtractor({ promptTemplate: 'Summarize: {context}' });
+    const node = new TextNode({ text: 'Test document for prompt customization.' });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(typeof summary).toBe('string');
+    expect(summary.length).toBeGreaterThan(0);
+  });
+
+  it('handles very long input', async () => {
+    const extractor = new SummaryExtractor();
+    const longText = 'A'.repeat(1000);
+    const node = new TextNode({ text: longText });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(typeof summary).toBe('string');
+  });
+
+  it('handles whitespace only input', async () => {
+    const extractor = new SummaryExtractor();
+    const node = new TextNode({ text: '    ' });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(summary).toBe('');
+  });
+
+  it('handles special characters and emojis', async () => {
+    const extractor = new SummaryExtractor();
+    const node = new TextNode({ text: '🚀✨🔥' });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(typeof summary).toBe('string');
+    expect(summary.length).toBeGreaterThan(0);
+  });
+
+  it('handles numbers only', async () => {
+    const extractor = new SummaryExtractor();
+    const node = new TextNode({ text: '1234567890' });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(typeof summary).toBe('string');
+    expect(summary.length).toBeGreaterThan(0);
+  });
+
+  it('handles HTML tags', async () => {
+    const extractor = new SummaryExtractor();
+    const node = new TextNode({ text: '<h1>Test</h1>' });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(typeof summary).toBe('string');
+    expect(summary.length).toBeGreaterThan(0);
+  });
+
+  it('handles non-English text', async () => {
+    const extractor = new SummaryExtractor();
+    const node = new TextNode({ text: '这是一个测试文档。' });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(typeof summary).toBe('string');
+    expect(summary.length).toBeGreaterThan(0);
+  });
+
+  it('handles duplicate/repeated text', async () => {
+    const extractor = new SummaryExtractor();
+    const node = new TextNode({ text: 'repeat repeat repeat' });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(typeof summary).toBe('string');
+    expect(summary.length).toBeGreaterThan(0);
+  });
+
+  it('handles only punctuation', async () => {
+    const extractor = new SummaryExtractor();
+    const node = new TextNode({ text: '!!!???...' });
+    const summary = await extractor.generateNodeSummary(node);
+    expect(typeof summary).toBe('string');
+    expect(summary.length).toBeGreaterThan(0);
+  });
+});

package/src/document/extractors/summary.ts

@@ -0,0 +1,130 @@
+import type { MastraLanguageModel } from '@mastra/core/agent';
+import { PromptTemplate, defaultSummaryPrompt, TextNode, BaseExtractor } from 'llamaindex';
+import type { SummaryPrompt, BaseNode } from 'llamaindex';
+import { baseLLM, STRIP_REGEX } from './types';
+import type { SummaryExtractArgs } from './types';
+
+type ExtractSummary = {
+  sectionSummary?: string;
+  prevSectionSummary?: string;
+  nextSectionSummary?: string;
+};
+
+/**
+ * Summarize an array of nodes using a custom LLM.
+ *
+ * @param nodes Array of node-like objects
+ * @param options Summary extraction options
+ * @returns Array of summary results
+ */
+export class SummaryExtractor extends BaseExtractor {
+  /**
+   * MastraLanguageModel instance.
+   * @type {MastraLanguageModel}
+   */
+  private llm: MastraLanguageModel;
+  /**
+   * List of summaries to extract: 'self', 'prev', 'next'
+   * @type {string[]}
+   */
+  summaries: string[];
+
+  /**
+   * The prompt template to use for the summary extractor.
+   * @type {string}
+   */
+  promptTemplate: SummaryPrompt;
+
+  private selfSummary: boolean;
+  private prevSummary: boolean;
+  private nextSummary: boolean;
+
+  constructor(options?: SummaryExtractArgs) {
+    const summaries = options?.summaries ?? ['self'];
+
+    if (summaries && !summaries.some(s => ['self', 'prev', 'next'].includes(s)))
+      throw new Error("Summaries must be one of 'self', 'prev', 'next'");
+
+    super();
+
+    this.llm = options?.llm ?? baseLLM;
+    this.summaries = summaries;
+    this.promptTemplate = options?.promptTemplate
+      ? new PromptTemplate({
+          templateVars: ['context'],
+          template: options.promptTemplate,
+        })
+      : defaultSummaryPrompt;
+
+    this.selfSummary = summaries?.includes('self') ?? false;
+    this.prevSummary = summaries?.includes('prev') ?? false;
+    this.nextSummary = summaries?.includes('next') ?? false;
+  }
+
+  /**
+   * Extract summary from a node.
+   * @param {BaseNode} node Node to extract summary from.
+   * @returns {Promise<string>} Summary extracted from the node.
+   */
+  async generateNodeSummary(node: BaseNode): Promise<string> {
+    const text = node.getContent(this.metadataMode);
+    if (!text || text.trim() === '') {
+      return '';
+    }
+    if (this.isTextNodeOnly && !(node instanceof TextNode)) {
+      return '';
+    }
+    const context = node.getContent(this.metadataMode);
+
+    const prompt = this.promptTemplate.format({
+      context,
+    });
+
+    const result = await this.llm.doGenerate({
+      inputFormat: 'messages',
+      mode: { type: 'regular' },
+      prompt: [
+        {
+          role: 'user',
+          content: [{ type: 'text', text: prompt }],
+        },
+      ],
+    });
+
+    let summary = '';
+    if (typeof result.text === 'string') {
+      summary = result.text.trim();
+    } else {
+      console.warn('Summary extraction LLM output was not a string:', result.text);
+    }
+
+    return summary.replace(STRIP_REGEX, '');
+  }
+
+  /**
+   * Extract summaries from a list of nodes.
+   * @param {BaseNode[]} nodes Nodes to extract summaries from.
+   * @returns {Promise<ExtractSummary[]>} Summaries extracted from the nodes.
+   */
+  async extract(nodes: BaseNode[]): Promise<ExtractSummary[]> {
+    if (!nodes.every(n => n instanceof TextNode)) throw new Error('Only `TextNode` is allowed for `Summary` extractor');
+
+    const nodeSummaries = await Promise.all(nodes.map(node => this.generateNodeSummary(node)));
+
+    const metadataList: ExtractSummary[] = nodes.map(() => ({}));
+
+    for (let i = 0; i < nodes.length; i++) {
+      if (i > 0 && this.prevSummary && nodeSummaries[i - 1]) {
+        metadataList[i]!['prevSectionSummary'] = nodeSummaries[i - 1];
+      }
+      if (i < nodes.length - 1 && this.nextSummary && nodeSummaries[i + 1]) {
+        metadataList[i]!['nextSectionSummary'] = nodeSummaries[i + 1];
+      }
+      if (this.selfSummary && nodeSummaries[i]) {
+        metadataList[i]!['sectionSummary'] = nodeSummaries[i];
+      }
+    }
+
+    return metadataList;
+  }
+}

package/src/document/extractors/title.test.ts

@@ -0,0 +1,121 @@
+import { createOpenAI } from '@ai-sdk/openai';
+import { TextNode } from 'llamaindex';
+import { describe, it, expect, vi } from 'vitest';
+import { TitleExtractor } from './title';
+
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+const model = openai('gpt-4o');
+
+vi.setConfig({ testTimeout: 10_000, hookTimeout: 10_000 });
+
+describe('TitleExtractor', () => {
+  it('can use a custom model from the test suite', async () => {
+    const extractor = new TitleExtractor({ llm: model });
+    const node = new TextNode({ text: 'A title test using a custom model.' });
+    const titles = await extractor.extract([node]);
+    expect(Array.isArray(titles)).toBe(true);
+    expect(titles[0]).toHaveProperty('documentTitle');
+    expect(typeof titles[0].documentTitle).toBe('string');
+    expect(titles[0].documentTitle.length).toBeGreaterThan(0);
+  });
+
+  it('extracts title', async () => {
+    const extractor = new TitleExtractor({ llm: model });
+    const node = new TextNode({ text: 'This is a test document.' });
+    const titles = await extractor.extract([node]);
+    expect(Array.isArray(titles)).toBe(true);
+    expect(titles[0]).toHaveProperty('documentTitle');
+    expect(typeof titles[0].documentTitle).toBe('string');
+    expect(titles[0].documentTitle.length).toBeGreaterThan(0);
+  });
+
+  it('handles empty input gracefully', async () => {
+    const extractor = new TitleExtractor({ llm: model });
+    const node = new TextNode({ text: '' });
+    const titles = await extractor.extract([node]);
+    expect(titles[0].documentTitle).toBe('');
+  });
+
+  it('supports prompt customization', async () => {
+    const extractor = new TitleExtractor({ llm: model, nodeTemplate: 'Title for: {context}' });
+    const node = new TextNode({ text: 'Test document for prompt customization.' });
+    const titles = await extractor.extract([node]);
+    expect(titles[0]).toHaveProperty('documentTitle');
+    expect(typeof titles[0].documentTitle).toBe('string');
+    expect(titles[0].documentTitle.length).toBeGreaterThan(0);
+  });
+
+  it('handles very long input', async () => {
+    const extractor = new TitleExtractor({ llm: model });
+    const longText = 'A'.repeat(1000);
+    const node = new TextNode({ text: longText });
+    const titles = await extractor.extract([node]);
+    expect(titles[0]).toHaveProperty('documentTitle');
+    expect(typeof titles[0].documentTitle).toBe('string');
+    expect(titles[0].documentTitle.length).toBeGreaterThan(0);
+  });
+
+  it('handles whitespace only input', async () => {
+    const extractor = new TitleExtractor({ llm: model });
+    const node = new TextNode({ text: '    ' });
+    const titles = await extractor.extract([node]);
+    expect(titles[0].documentTitle).toBe('');
+  });
+
+  it('handles special characters and emojis', async () => {
+    const extractor = new TitleExtractor({ llm: model });
+    const node = new TextNode({ text: '🚀✨🔥' });
+    const titles = await extractor.extract([node]);
+    expect(titles[0]).toHaveProperty('documentTitle');
+    expect(typeof titles[0].documentTitle).toBe('string');
+    expect(titles[0].documentTitle.length).toBeGreaterThan(0);
+  });
+
+  it('handles numbers only', async () => {
+    const extractor = new TitleExtractor({ llm: model });
+    const node = new TextNode({ text: '1234567890' });
+    const titles = await extractor.extract([node]);
+    expect(titles[0]).toHaveProperty('documentTitle');
+    expect(typeof titles[0].documentTitle).toBe('string');
+    expect(titles[0].documentTitle.length).toBeGreaterThan(0);
+  });
+
+  it('handles HTML tags', async () => {
+    const extractor = new TitleExtractor({ llm: model });
+    const node = new TextNode({ text: '<h1>Test</h1>' });
+    const titles = await extractor.extract([node]);
+    expect(titles[0]).toHaveProperty('documentTitle');
+    expect(typeof titles[0].documentTitle).toBe('string');
+    expect(titles[0].documentTitle.length).toBeGreaterThan(0);
+  });
+
+  it('handles non-English text', async () => {
+    const extractor = new TitleExtractor({ llm: model });
+    const node = new TextNode({ text: '这是一个测试文档。' });
+    const titles = await extractor.extract([node]);
+    expect(titles[0]).toHaveProperty('documentTitle');
+    expect(typeof titles[0].documentTitle).toBe('string');
+    expect(titles[0].documentTitle.length).toBeGreaterThan(0);
+  });
+
+  it('handles duplicate/repeated text', async () => {
+    const extractor = new TitleExtractor({ llm: model });
+    const node = new TextNode({ text: 'repeat repeat repeat' });
+    const titles = await extractor.extract([node]);
+    expect(titles[0]).toHaveProperty('documentTitle');
+    expect(typeof titles[0].documentTitle).toBe('string');
+    expect(titles[0].documentTitle.length).toBeGreaterThan(0);
+  });
+
+  it('handles only punctuation', async () => {
+    const extractor = new TitleExtractor({ llm: model });
+    const node = new TextNode({ text: '!!!???...' });
+    const titles = await extractor.extract([node]);
+    expect(titles[0]).toHaveProperty('documentTitle');
+    expect(typeof titles[0].documentTitle).toBe('string');
+    expect(titles[0].documentTitle.length).toBeGreaterThan(0);
+  });
+});

package/src/document/extractors/title.ts

@@ -0,0 +1,210 @@
+import type { MastraLanguageModel } from '@mastra/core/agent';
+import {
+  PromptTemplate,
+  defaultTitleCombinePromptTemplate,
+  defaultTitleExtractorPromptTemplate,
+  MetadataMode,
+  TextNode,
+  BaseExtractor,
+} from 'llamaindex';
+import type { TitleCombinePrompt, TitleExtractorPrompt, BaseNode } from 'llamaindex';
+import { baseLLM } from './types';
+import type { TitleExtractorsArgs } from './types';
+
+type ExtractTitle = {
+  documentTitle: string;
+};
+
+/**
+ * Extract title from a list of nodes.
+ */
+export class TitleExtractor extends BaseExtractor {
+  /**
+   * MastraLanguageModel instance.
+   * @type {MastraLanguageModel}
+   */
+  llm: MastraLanguageModel;
+
+  /**
+   * Can work for mixture of text and non-text nodes
+   * @type {boolean}
+   * @default false
+   */
+  isTextNodeOnly: boolean = false;
+
+  /**
+   * Number of nodes to extrct titles from.
+   * @type {number}
+   * @default 5
+   */
+  nodes: number = 5;
+
+  /**
+   * The prompt template to use for the title extractor.
+   * @type {string}
+   */
+  nodeTemplate: TitleExtractorPrompt;
+
+  /**
+   * The prompt template to merge title with..
+   * @type {string}
+   */
+  combineTemplate: TitleCombinePrompt;
+
+  /**
+   * Constructor for the TitleExtractor class.
+   * @param {MastraLanguageModel} llm MastraLanguageModel instance.
+   * @param {number} nodes Number of nodes to extract titles from.
+   * @param {TitleExtractorPrompt} nodeTemplate The prompt template to use for the title extractor.
+   * @param {string} combineTemplate The prompt template to merge title with..
+   */
+  constructor(options?: TitleExtractorsArgs) {
+    super();
+
+    this.llm = options?.llm ?? baseLLM;
+    this.nodes = options?.nodes ?? 5;
+
+    this.nodeTemplate = options?.nodeTemplate
+      ? new PromptTemplate({
+          templateVars: ['context'],
+          template: options.nodeTemplate,
+        })
+      : defaultTitleExtractorPromptTemplate;
+
+    this.combineTemplate = options?.combineTemplate
+      ? new PromptTemplate({
+          templateVars: ['context'],
+          template: options.combineTemplate,
+        })
+      : defaultTitleCombinePromptTemplate;
+  }
+
+  /**
+   * Extract titles from a list of nodes.
+   * @param {BaseNode[]} nodes Nodes to extract titles from.
+   * @returns {Promise<BaseNode<ExtractTitle>[]>} Titles extracted from the nodes.
+   */
+  async extract(nodes: BaseNode[]): Promise<Array<ExtractTitle>> {
+    // Prepare output array in original node order
+    const results: ExtractTitle[] = new Array(nodes.length);
+    // Keep track of nodes with content to extract
+    const nodesToExtractTitle: BaseNode[] = [];
+    const nodeIndexes: number[] = [];
+
+    nodes.forEach((node, idx) => {
+      const text = node.getContent(this.metadataMode);
+      if (!text || text.trim() === '') {
+        results[idx] = { documentTitle: '' };
+      } else {
+        nodesToExtractTitle.push(node);
+        nodeIndexes.push(idx);
+      }
+    });
+
+    if (nodesToExtractTitle.length) {
+      const filteredNodes = this.filterNodes(nodesToExtractTitle);
+      if (filteredNodes.length) {
+        const nodesByDocument = this.separateNodesByDocument(filteredNodes);
+        const titlesByDocument = await this.extractTitles(nodesByDocument);
+        filteredNodes.forEach((node, i) => {
+          const nodeIndex = nodeIndexes[i];
+          const groupKey = node.sourceNode?.nodeId ?? node.id_;
+          if (typeof nodeIndex === 'number') {
+            results[nodeIndex] = {
+              documentTitle: titlesByDocument[groupKey] ?? '',
+            };
+          }
+        });
+      }
+    }
+    return results;
+  }
+
+  private filterNodes(nodes: BaseNode[]): BaseNode[] {
+    return nodes.filter(node => {
+      if (this.isTextNodeOnly && !(node instanceof TextNode)) {
+        return false;
+      }
+      return true;
+    });
+  }
+
+  private separateNodesByDocument(nodes: BaseNode[]): Record<string, BaseNode[]> {
+    const nodesByDocument: Record<string, BaseNode[]> = {};
+
+    for (const node of nodes) {
+      const groupKey = node.sourceNode?.nodeId ?? node.id_;
+      nodesByDocument[groupKey] = nodesByDocument[groupKey] || [];
+      nodesByDocument[groupKey].push(node);
+    }
+
+    return nodesByDocument;
+  }
+
+  private async extractTitles(nodesByDocument: Record<string, BaseNode[]>): Promise<Record<string, string>> {
+    const titlesByDocument: Record<string, string> = {};
+
+    for (const [key, nodes] of Object.entries(nodesByDocument)) {
+      const titleCandidates = await this.getTitlesCandidates(nodes);
+      const combinedTitles = titleCandidates.join(', ');
+      const completion = await this.llm.doGenerate({
+        inputFormat: 'messages',
+        mode: { type: 'regular' },
+        prompt: [
+          {
+            role: 'user',
+            content: [
+              {
+                type: 'text',
+                text: this.combineTemplate.format({
+                  context: combinedTitles,
+                }),
+              },
+            ],
+          },
+        ],
+      });
+
+      let title = '';
+      if (typeof completion.text === 'string') {
+        title = completion.text.trim();
+      } else {
+        console.warn('Title extraction LLM output was not a string:', completion.text);
+      }
+      titlesByDocument[key] = title;
+    }
+
+    return titlesByDocument;
+  }
+
+  private async getTitlesCandidates(nodes: BaseNode[]): Promise<string[]> {
+    const titleJobs = nodes.map(async node => {
+      const completion = await this.llm.doGenerate({
+        inputFormat: 'messages',
+        mode: { type: 'regular' },
+        prompt: [
+          {
+            role: 'user',
+            content: [
+              {
+                type: 'text',
+                text: this.nodeTemplate.format({
+                  context: node.getContent(MetadataMode.ALL),
+                }),
+              },
+            ],
+          },
+        ],
+      });
+
+      if (typeof completion.text === 'string') {
+        return completion.text.trim();
+      } else {
+        console.warn('Title candidate extraction LLM output was not a string:', completion.text);
+        return '';
+      }
+    });
+
+    return await Promise.all(titleJobs);
+  }
+}