fix: ai generates markdown for google docs rich text (#10312)

Author: ryunsong-contentful

apps/google-docs/functions/agents/documentParserAgent/documentParser.agent.ts

@@ -39,15 +39,12 @@ export async function createDocument(config: DocumentParserConfig): Promise<Fina
 
   const { document, openAiApiKey, contentTypes, locale = 'en-US' } = config;
 
-  // Extract text content from Google Docs JSON structure
-  const documentContent = extractTextFromGoogleDocsJson(document);
-
   const openaiClient = createOpenAI({
     apiKey: openAiApiKey,
   });
 
-  console.log('Document Parser Agent document content Input:', documentContent);
-  const prompt = buildExtractionPrompt({ contentTypes, documentContent, locale });
+  console.log('Document Parser Agent document content Input:', document);
+  const prompt = buildExtractionPrompt({ contentTypes, document, locale });
   const result = await generateObject({
     model: openaiClient(modelVersion),
     schema: FinalEntriesResultSchema,
@@ -57,7 +54,7 @@ export async function createDocument(config: DocumentParserConfig): Promise<Fina
   });
 
   const finalResult = result.object as FinalEntriesResult;
-  console.log('Document Parser Agent Result:', result);
+  console.log('Document Parser Agent Result:', JSON.stringify(result, null, 2));
 
   return finalResult;
 }
@@ -111,72 +108,13 @@ EXTRACTION GUIDELINES:
 - Focus on simple fields: Symbol, Text, Number, Boolean, Date`;
 }
 
-/**
- * Extracts plain text content from Google Docs JSON structure
- */
-// TODO: Update this to be more robust and bulletproof
-function extractTextFromGoogleDocsJson(document: unknown): string {
-  if (!document || typeof document !== 'object') {
-    return '';
-  }
-
-  const doc = document as Record<string, unknown>;
-  const textParts: string[] = [];
-
-  // Extract title if available
-  if (typeof doc.title === 'string') {
-    textParts.push(doc.title);
-  }
-
-  // Navigate through tabs -> documentTab -> body -> content
-  if (Array.isArray(doc.tabs)) {
-    for (const tab of doc.tabs) {
-      if (typeof tab === 'object' && tab !== null) {
-        const tabObj = tab as Record<string, unknown>;
-        if (tabObj.documentTab && typeof tabObj.documentTab === 'object') {
-          const docTab = tabObj.documentTab as Record<string, unknown>;
-          if (docTab.body && typeof docTab.body === 'object') {
-            const body = docTab.body as Record<string, unknown>;
-            if (Array.isArray(body.content)) {
-              for (const item of body.content) {
-                if (typeof item === 'object' && item !== null) {
-                  const itemObj = item as Record<string, unknown>;
-                  // Extract text from paragraphs
-                  if (itemObj.paragraph && typeof itemObj.paragraph === 'object') {
-                    const para = itemObj.paragraph as Record<string, unknown>;
-                    if (Array.isArray(para.elements)) {
-                      for (const elem of para.elements) {
-                        if (typeof elem === 'object' && elem !== null) {
-                          const elemObj = elem as Record<string, unknown>;
-                          if (elemObj.textRun && typeof elemObj.textRun === 'object') {
-                            const textRun = elemObj.textRun as Record<string, unknown>;
-                            if (typeof textRun.content === 'string') {
-                              textParts.push(textRun.content);
-                            }
-                          }
-                        }
-                      }
-                    }
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-
-  return textParts.join(' ').trim();
-}
-
 function buildExtractionPrompt({
   contentTypes,
-  documentContent,
+  document,
   locale,
 }: {
   contentTypes: ContentTypeProps[];
-  documentContent: string;
+  document: unknown;
   locale: string;
 }): string {
   const contentTypeList = contentTypes.map((ct) => `${ct.name} (ID: ${ct.sys.id})`).join(', ');
@@ -216,7 +154,7 @@ function buildExtractionPrompt({
     };
   });
 
-  return `Extract structured entries from the following document based on the provided Contentful content type definitions.
+  return `Extract structured entries from the following Google Docs JSON document based on the provided Contentful content type definitions.
 
 AVAILABLE CONTENT TYPES: ${contentTypeList}
 TOTAL CONTENT TYPES: ${contentTypes.length}
@@ -226,29 +164,143 @@ LOCALE TO USE: ${locale}
 CONTENT TYPE DEFINITIONS:
 ${JSON.stringify(contentTypeDefinitions, null, 2)}
 
-DOCUMENT CONTENT:
-${documentContent}
+=== GOOGLE DOCS JSON PARSING GUIDE ===
+
+The document is in Google Docs API JSON format. Here's how to interpret the structure:
+
+**DOCUMENT STRUCTURE:**
+- \`documentId\`: Unique identifier for the document
+- \`tabs[].documentTab.body.content[]\`: Array of content elements (paragraphs, tables, sections)
+- \`tabs[].documentTab.inlineObjects\`: Object mapping inlineObjectId → image/embedded object data
+- \`tabs[].documentTab.lists\`: Object mapping listId → list configuration (bullet/numbered)
+
+**CONTENT ELEMENT TYPES:**
+
+1. **Paragraphs** - Main text content:
+   \`\`\`
+   {
+     "paragraph": {
+       "elements": [{ "textRun": { "content": "text\\n", "textStyle": {...} } }],
+       "paragraphStyle": { "namedStyleType": "HEADING_1" | "HEADING_2" | "NORMAL_TEXT" | ... },
+       "bullet": { "listId": "kix.xxx", "nestingLevel": 0 }  // if it's a list item
+     }
+   }
+   \`\`\`
+   - \`namedStyleType\`: HEADING_1, HEADING_2, HEADING_3, HEADING_4, HEADING_5, HEADING_6, NORMAL_TEXT, TITLE, SUBTITLE
+   - \`bullet.listId\`: References list definition in \`lists\` object (indicates bullet/numbered list)
+   - \`bullet.nestingLevel\`: Indentation level (0 = top level)
+
+2. **Text Runs** - Inline text with formatting:
+   \`\`\`
+   {
+     "textRun": {
+       "content": "the actual text content",
+       "textStyle": {
+         "bold": true/false,
+         "italic": true/false,
+         "underline": true/false,
+         "strikethrough": true/false,
+         "link": { "url": "https://..." },
+         "foregroundColor": { "color": { "rgbColor": { "red": 0-1, "green": 0-1, "blue": 0-1 } } },
+         "fontSize": { "magnitude": 11, "unit": "PT" }
+       }
+     }
+   }
+   \`\`\`
+
+3. **Inline Object Elements** - References to images:
+   \`\`\`
+   { "inlineObjectElement": { "inlineObjectId": "kix.xxx" } }
+   \`\`\`
+   - Look up the actual image in \`inlineObjects["kix.xxx"]\`
+   - Image URL is at: \`inlineObjects[id].inlineObjectProperties.embeddedObject.imageProperties.contentUri\`
+
+4. **Rich Links** - Embedded links with previews (YouTube, etc.):
+   \`\`\`
+   { "richLink": { "richLinkId": "kix.xxx", "richLinkProperties": { "title": "...", "uri": "..." } } }
+   \`\`\`
+
+5. **Tables** - Structured tabular data:
+   \`\`\`
+   {
+     "table": {
+       "rows": number,
+       "columns": number,
+       "tableRows": [{
+         "tableCells": [{
+           "content": [/* paragraphs */]
+         }]
+       }]
+     }
+   }
+   \`\`\`
+   - Each cell contains an array of paragraph elements
+   - First row is typically headers
+
+6. **Lists** - Bullet and numbered lists:
+   - Paragraphs with \`bullet\` property are list items
+   - \`bullet.listId\` references the list definition in \`lists\`
+   - Check \`lists[listId].listProperties.nestingLevels[0].glyphSymbol\` for bullet character
+   - Check \`lists[listId].listProperties.nestingLevels[0].glyphType\` for numbered list type (DECIMAL, ALPHA, ROMAN)
+
+**EXTRACTING TEXT CONTENT:**
+1. Navigate to \`tabs[0].documentTab.body.content\`
+2. For each element, check if it has \`paragraph\`, \`table\`, or \`sectionBreak\`
+3. For paragraphs:
+   - Get heading level from \`paragraphStyle.namedStyleType\`
+   - Concatenate all \`elements[].textRun.content\` values
+   - Apply formatting based on \`textStyle\` (bold → **, italic → *, underline → _)
+   - Check for \`bullet\` to identify list items
+4. For tables:
+   - Iterate through \`tableRows[].tableCells[].content\` to get cell text
+   - Use first row as headers if appropriate
+
+**FORMATTING CONVERSION:**
+When extracting RichText fields, convert Google Docs formatting to Markdown:
+- textStyle.bold: true → **text**
+- textStyle.italic: true → *text*
+- textStyle.underline: true → _text_ or <u>text</u>
+- textStyle.strikethrough: true → ~~text~~
+- textStyle.link.url → [text](url)
+- HEADING_1 → # heading
+- HEADING_2 → ## heading
+- HEADING_3 → ### heading
+- Bullet lists → - item
+- Numbered lists → 1. item
+
+=== END PARSING GUIDE ===
+
+GOOGLE DOCS JSON DOCUMENT:
+${JSON.stringify(document, null, 2)}
 
 CRITICAL INSTRUCTIONS:
-1. **SKIP ALL FIELDS WHERE "SKIP": true** - Do NOT include these fields in your output
-2. Look at each field definition - if it has "SKIP": true, completely ignore that field
-3. Only include fields where "SKIP" is false or not present
-4. Analyze the document and identify content that matches the provided content type structures
-5. Extract all relevant entries from the document
-6. For each entry, use the contentTypeId that best matches the content
-7. Format fields correctly: { "fieldId": { "${locale}": value } }
-8. Match field types exactly:
+1. **PARSE THE GOOGLE DOCS JSON** - Use the parsing guide above to extract text and structure
+2. **SKIP ALL FIELDS WHERE "SKIP": true** - Do NOT include these fields in your output
+3. Look at each field definition - if it has "SKIP": true, completely ignore that field
+4. Only include fields where "SKIP" is false or not present
+5. Analyze the document and identify content that matches the provided content type structures
+6. Extract all relevant entries from the document
+7. For each entry, use the contentTypeId that best matches the content
+8. Format fields correctly: { "fieldId": { "${locale}": value } }
+9. Match field types exactly:
    - Symbol: string (max 256 chars)
    - Text: string (any length)
-   - RichText: string in Markdown (preserve bold **, italics *, underline _)
+   - RichText: string in Markdown (convert Google Docs formatting using the guide above)
    - Number: number
    - Boolean: boolean
    - Date: ISO 8601 string
    - Array: array of primitives (strings or numbers ONLY)
    - Object: JSON object
-9. For required fields (required: true) that are NOT marked SKIP: true, ensure they are populated
-10. If you cannot populate a required field from the document, use a sensible default or placeholder
-11. Be thorough - extract all valid content from the document
+10. For required fields (required: true) that are NOT marked SKIP: true, ensure they are populated
+11. If you cannot populate a required field from the document, use a sensible default or placeholder
+12. Be thorough - extract all valid content from the document
+
+**CONTENT EXTRACTION TIPS:**
+- Look for HEADING_1 or HEADING_2 paragraphs as entry titles
+- Normal paragraphs following headings are typically body content
+- Tables may contain structured data that maps to entry fields
+- Lists can be extracted as array fields (if type is Array of Symbol/Text)
+- Image URLs from inlineObjects can populate URL/Symbol fields
 
 Return the extracted entries in the specified JSON schema format.`;
 }