sea-dev 1.0.0

package/libs/core/src/data-extraction/layout/gcp.ts

@@ -0,0 +1,1071 @@
+import type { v1beta3 } from "@google-cloud/documentai";
+import { type protos } from "@google-cloud/documentai";
+import type { Storage } from "@google-cloud/storage";
+import type { GCPConfig } from "@sea/config";
+import {
+  type LayoutItemType,
+  type PretrainedEntity,
+  type EntityType,
+  type ReferenceMap,
+  type Polygon,
+  Cell,
+  DocumentLayout,
+  Header,
+  Footer,
+  Heading,
+  List,
+  ListItem,
+  Paragraph,
+  Row,
+  Section,
+  Table,
+} from "@sea/schemas/core/layout";
+import { MAX_PAGES_PER_CHUNK } from "../pdf-utils";
+import { sequential } from "@sea/util/id";
+
+export type GCPDocument = protos.google.cloud.documentai.v1beta3.IDocument;
+export type GCPEntity = protos.google.cloud.documentai.v1beta3.Document.IEntity;
+export type GCPPage = protos.google.cloud.documentai.v1beta3.Document.IPage;
+export type GCPLayoutBlock =
+  protos.google.cloud.documentai.v1beta3.Document.DocumentLayout.IDocumentLayoutBlock;
+export type GCPLayoutTextBlock =
+  protos.google.cloud.documentai.v1beta3.Document.DocumentLayout.DocumentLayoutBlock.ILayoutTextBlock;
+export type GCPLayoutTableBlock =
+  protos.google.cloud.documentai.v1beta3.Document.DocumentLayout.DocumentLayoutBlock.ILayoutTableBlock;
+export type GCPLayoutTableCell =
+  protos.google.cloud.documentai.v1beta3.Document.DocumentLayout.DocumentLayoutBlock.ILayoutTableCell;
+export type GCPLayoutListBlock =
+  protos.google.cloud.documentai.v1beta3.Document.DocumentLayout.DocumentLayoutBlock.ILayoutListBlock;
+export type GCPLayoutImageBlock =
+  protos.google.cloud.documentai.v1beta3.Document.DocumentLayout.DocumentLayoutBlock.ILayoutImageBlock;
+export type GCPPageItemLayout =
+  protos.google.cloud.documentai.v1beta3.Document.Page.ILayout;
+
+/**
+ * Google Cloud Document AI adapter for document extraction
+ * Handles document processing using GCP's Document AI API
+ */
+export class GCPDocumentProcessor {
+  private documentProcessorClient?: v1beta3.DocumentProcessorServiceClient;
+  private storageClient?: Storage;
+  private config: GCPConfig;
+
+  constructor(config: GCPConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Lazy-loads and returns a Google Cloud Storage client instance
+   * Uses dynamic import to avoid bundling the entire package until needed
+   * @returns Promise<Storage> - The Google Cloud Storage client
+   * @private
+   */
+  private async getStorageClient(): Promise<Storage> {
+    if (!this.storageClient) {
+      const { Storage } = await import("@google-cloud/storage");
+      this.storageClient = new Storage({
+        projectId: this.config.projectId,
+        keyFilename: this.config.serviceAccountCredentials,
+      });
+    }
+    return this.storageClient;
+  }
+
+  /**
+   * Lazy-loads and returns a Google Cloud Document AI client instance
+   * Uses dynamic import to avoid bundling the entire package until needed
+   * @returns Promise<v1beta3.DocumentProcessorServiceClient> - The Document AI client
+   * @private
+   */
+  private async getDocumentAIClient(): Promise<v1beta3.DocumentProcessorServiceClient> {
+    if (!this.documentProcessorClient) {
+      const { v1beta3 } = await import("@google-cloud/documentai");
+      this.documentProcessorClient = new v1beta3.DocumentProcessorServiceClient(
+        {
+          keyFilename: this.config.serviceAccountCredentials,
+          apiEndpoint: this.config.documentProcessor.apiEndpoint,
+        },
+      );
+    }
+    return this.documentProcessorClient;
+  }
+
+  /**
+   * Performs document extraction on a list of input files
+   * @param inputFiles - Array of file paths in GCS to process
+   * @param modelId - The model ID to use for extraction
+   * @param mimeType - The MIME type of the documents
+   * @returns Promise<GCPDocument[]> - Array of extracted documents (one per input)
+   */
+  public async runExtraction(
+    inputFiles: string[],
+    modelId: string,
+    mimeType: string,
+  ): Promise<GCPDocument[]> {
+    return await this.runBatchExtraction(inputFiles, modelId, mimeType);
+  }
+
+  /**
+   * Runs synchronous extraction on a list of GCS URIs
+   * @param inputFiles - Array of file paths to process
+   * @param modelId - The model ID to use for extraction
+   * @param mimeType - The MIME type of the documents
+   * @returns Promise<GCPDocument[]> - Array of extracted documents (one per input)
+   * @private
+   */
+  private async runSyncExtraction(
+    inputFiles: string[],
+    modelId: string,
+    mimeType: string,
+  ): Promise<GCPDocument[]> {
+    const documentProcessorClient = await this.getDocumentAIClient();
+    const processorName = `projects/${this.config.projectId}/locations/${this.config.documentProcessor.location}/processors/${modelId}`;
+
+    const processing = inputFiles.map(async (f) => {
+      const request = {
+        name: processorName,
+        gcsDocument: {
+          gcsUri: `gs://${this.config.storage.documentBucketName}/${f}`,
+          mimeType,
+        },
+        ...(modelId === this.config.documentProcessor.layoutParserModelId
+          ? {
+              processOptions: {
+                layoutConfig: {
+                  returnBoundingBoxes: true,
+                },
+              },
+            }
+          : {}),
+      };
+      const [result] = await documentProcessorClient.processDocument(request);
+      if (!result.document) {
+        throw new Error(
+          `No document returned from synchronous processing for ${f}`,
+        );
+      }
+      console.log("RESULT:", result.document);
+      return result.document as GCPDocument;
+    });
+    const results = await Promise.all(processing);
+
+    return results;
+  }
+
+  /**
+   * Runs batch extraction on a list of GCS URIs (fallback for sync)
+   * @param inputFiles - Array of file paths to process
+   * @param modelId - The model ID to use for extraction
+   * @param mimeType - The MIME type of the documents
+   * @returns Promise<GCPDocument[]> - Array of extracted documents (one per input)
+   * @private
+   */
+  private async runBatchExtraction(
+    inputFiles: string[],
+    modelId: string,
+    mimeType: string,
+  ): Promise<GCPDocument[]> {
+    const outputGcsUri = `gs://${this.config.storage.outputBucketName}`;
+    const documentProcessorClient = await this.getDocumentAIClient();
+    const processorName = `projects/${this.config.projectId}/locations/${this.config.documentProcessor.location}/processors/${modelId}`;
+
+    // Build documents array for batch processing
+    const documents = inputFiles.map((f) => ({
+      gcsUri: `gs://${this.config.storage.documentBucketName}/${f}`,
+      mimeType,
+    }));
+
+    const [operation] = await documentProcessorClient.batchProcessDocuments({
+      name: processorName,
+      inputDocuments: {
+        gcsDocuments: { documents },
+      },
+      documentOutputConfig: {
+        gcsOutputConfig: {
+          gcsUri: outputGcsUri,
+        },
+      },
+      ...(modelId === this.config.documentProcessor.layoutParserModelId
+        ? {
+            processOptions: {
+              layoutConfig: {
+                returnBoundingBoxes: true,
+              },
+            },
+          }
+        : {}),
+    });
+
+    const metadata = (await operation.promise())[1];
+    const results = await Promise.all(
+      inputFiles.map(async (f) => {
+        const status = metadata.individualProcessStatuses?.find(
+          (s) =>
+            s.inputGcsSource ===
+            `gs://${this.config.storage.documentBucketName}/${f}`,
+        );
+        const outputUri = status?.outputGcsDestination;
+        if (!outputUri) {
+          throw new Error(`No batch processing output found for ${f}`);
+        }
+
+        return await this.mergeGcpShards(outputUri);
+      }),
+    );
+
+    return results;
+  }
+
+  /**
+   * Merges GCP's internal shards from a single batch processing operation
+   * @private
+   */
+  private async mergeGcpShards(outputUri: string): Promise<GCPDocument> {
+    const storageClient = await this.getStorageClient();
+    const { bucket, prefix } = this.parseGcsUri(outputUri);
+    const [files] = await storageClient.bucket(bucket).getFiles({ prefix });
+    const jsonFiles = files.filter((file) => file.name.endsWith(".json"));
+
+    if (jsonFiles.length === 0) {
+      throw new Error(`No JSON files found in ${prefix}`);
+    }
+
+    const downloads = jsonFiles.map((file) =>
+      file.download().then((data) => JSON.parse(data[0].toString("utf8"))),
+    );
+    const allJsonContents = await Promise.all(downloads);
+    const mainDocument: GCPDocument = allJsonContents[0];
+
+    if (allJsonContents.length > 1) {
+      for (let i = 1; i < allJsonContents.length; i++) {
+        const shard = allJsonContents[i];
+        if (shard.pages && Array.isArray(shard.pages)) {
+          mainDocument.pages!.push(...shard.pages);
+        }
+      }
+    }
+
+    return mainDocument;
+  }
+
+  /**
+   * Parses a GCS URI into bucket and fileName components
+   * @param gcsUri - GCS URI in format gs://bucket/path/to/file
+   * @returns Object with bucket and fileName
+   * @throws Error if URI format is invalid
+   */
+  private parseGcsUri(gcsUri: string): { bucket: string; prefix: string } {
+    const match = gcsUri.match(/^gs:\/\/([^\/]+)\/(.*)$/);
+    if (!match) {
+      throw new Error(`Invalid GCS URI: ${gcsUri}`);
+    }
+    const [, bucket, prefix] = match;
+    if (!bucket || !prefix) {
+      throw new Error(`Invalid GCS URI: ${gcsUri}`);
+    }
+    return { bucket, prefix };
+  }
+}
+
+/**
+ * Merges multiple GCP document chunks into a single document with corrected page offsets.
+ *
+ * Each chunk's pages are offset by their position multiplied by MAX_PAGES_PER_CHUNK
+ * to maintain correct page numbering across document chunks. All bounding boxes and
+ * page references are updated in-place.
+ *
+ * @param layouts - Array of GCP document chunks to merge
+ * @returns Single merged GCP document with corrected page references
+ */
+export function mergeChunkedLayoutsGCP(layouts: GCPDocument[]): GCPDocument {
+  const [mergedDocument] = layouts;
+  if (!mergedDocument) {
+    throw new Error("Cannot merge empty layouts array");
+  }
+
+  for (const [i, layout] of layouts.slice(1).entries()) {
+    const pageOffset = (i + 1) * MAX_PAGES_PER_CHUNK;
+
+    // merge text from all chunks
+    mergedDocument.text += layout.text ?? "";
+
+    // Merge blocks with offset applied to bounding boxes
+    if (layout.documentLayout?.blocks) {
+      layout.documentLayout.blocks.forEach((block) =>
+        offsetBlockPages(block, pageOffset),
+      );
+      mergedDocument.documentLayout?.blocks?.push(
+        ...layout.documentLayout.blocks,
+      );
+    }
+
+    // Merge pages with offset
+    if (layout.pages) {
+      layout.pages.forEach((page) => {
+        page.pageNumber = page.pageNumber
+          ? page.pageNumber + pageOffset
+          : page.pageNumber;
+      });
+      mergedDocument.pages?.push(...layout.pages);
+    }
+
+    // Merge pretrained entities with offset applied to page anchors
+    if (layout.entities) {
+      layout.entities.forEach((entity) =>
+        offsetEntityPages(entity, pageOffset),
+      );
+      mergedDocument.entities?.push(...layout.entities);
+    }
+  }
+
+  return mergedDocument;
+}
+
+/**
+ * Recursively offsets all page references in a GCP layout block in place.
+ *
+ * Modifies the block's pageSpan and recursively processes all nested blocks
+ * (text blocks, table cells, list entries) to ensure all page references are
+ * correctly offset.
+ *
+ * @param block - GCP layout block to offset (modified in place)
+ * @param pageOffset - Number of pages to add to all page references
+ */
+function offsetBlockPages(block: GCPLayoutBlock, pageOffset: number): void {
+  // offset pageSpan for a block
+  if (block.pageSpan) {
+    block.pageSpan.pageStart = (block.pageSpan.pageStart ?? 0) + pageOffset;
+    block.pageSpan.pageEnd = (block.pageSpan.pageEnd ?? 0) + pageOffset;
+  }
+
+  // recursively offset nested blocks for different block types
+  block.textBlock?.blocks?.forEach((b) => offsetBlockPages(b, pageOffset));
+
+  // offset table block cells
+  block.tableBlock?.headerRows?.forEach((row) => {
+    row.cells?.forEach((cell) => {
+      cell.blocks?.forEach((b) => offsetBlockPages(b, pageOffset));
+    });
+  });
+  block.tableBlock?.bodyRows?.forEach((row) => {
+    row.cells?.forEach((cell) => {
+      cell.blocks?.forEach((b) => offsetBlockPages(b, pageOffset));
+    });
+  });
+
+  // offset list block entries
+  block.listBlock?.listEntries?.forEach((entry) => {
+    entry.blocks?.forEach((b) => offsetBlockPages(b, pageOffset));
+  });
+}
+
+/**
+ * Offsets all page references in a GCP entity in place.
+ *
+ * Modifies page anchor references and recursively processes nested entity
+ * properties to ensure all page references are correctly offset.
+ *
+ * @param entity - GCP entity to offset (modified in place)
+ * @param pageOffset - Number of pages to add to all page references
+ */
+function offsetEntityPages(entity: GCPEntity, pageOffset: number): void {
+  // Offset page anchor
+  entity.pageAnchor?.pageRefs?.forEach((ref) => {
+    if (ref.page) {
+      ref.page = ((parseInt(ref.page.toString()) || 0) + pageOffset).toString();
+    }
+  });
+
+  // Recursively offset nested properties
+  entity.properties?.forEach((prop) => offsetEntityPages(prop, pageOffset));
+}
+
+/**
+ * Transforms GCP-specific extraction output into a hierarchical document structure.
+ *
+ * @param doc - GCP Document AI extraction result
+ * @returns Hierarchical document layout with entities and reference map
+ */
+export function serializeLayoutGCP(doc: GCPDocument): DocumentLayout {
+  // // Save raw GCP output
+  // writeFileSync(
+  //   ".claude/debug/gcp-raw-output.json",
+  //   JSON.stringify(doc, null, 2),
+  // );
+  // console.log("GCP raw output saved to .claude/debug/gcp-raw-output.json");
+
+  const referenceMap: ReferenceMap = {};
+  const entities: Record<string, PretrainedEntity> = {};
+  const currentLayout: LayoutItemType[] = [];
+  const sectionStack: Section[] = [];
+
+  if (
+    doc.documentLayout &&
+    doc.documentLayout.blocks &&
+    doc.documentLayout.blocks.length > 0
+  ) {
+    // this is used to get layout from generic layout parser
+    for (const block of doc.documentLayout.blocks) {
+      parseBlock(block, currentLayout, referenceMap, sectionStack);
+    }
+  } else {
+    // this is used to get layout and entities from pretrained model
+    const getText = (layout?: GCPPageItemLayout | null) => {
+      return (
+        layout?.textAnchor?.textSegments
+          ?.map(
+            ({ startIndex, endIndex }) =>
+              doc.text?.slice(startIndex as number, endIndex as number) ?? "",
+          )
+          .join("") ?? ""
+      );
+    };
+    for (const page of doc.pages ?? []) {
+      parsePage(page, currentLayout, referenceMap, getText);
+    }
+    Object.assign(entities, serializePretrainedEntities(doc, referenceMap));
+  }
+
+  return new DocumentLayout(currentLayout, entities, referenceMap);
+}
+
+/**
+ * Transforms GCP-specific extraction output into a standardized entity format.
+ *
+ * Processes all entities from the GCP document and converts them to the standardized
+ * PretrainedEntity format. When multiple entities share the same type, they are
+ * automatically grouped into an array.
+ *
+ * @param content - GCP Document AI extraction result
+ * @param referenceMap - Reference map to register entity bounding regions
+ * @returns Record mapping entity types to their converted PretrainedEntity objects
+ */
+function serializePretrainedEntities(
+  content: GCPDocument,
+  referenceMap: ReferenceMap,
+): Record<string, PretrainedEntity> {
+  const entities: Record<string, PretrainedEntity> = {};
+  console.info(
+    `[serializePretrainedEntities] Processing ${content.entities?.length ?? 0} entities`,
+  );
+  const idGen = sequential();
+  for (const entity of content.entities ?? []) {
+    const entityType = entity.type;
+    if (!entityType) continue;
+    const convertedEntity = convertGCPEntity(entity, referenceMap, idGen);
+
+    // If an entity with this type already exists, convert to array or append to existing array
+    if (entities[entityType]) {
+      const existing = entities[entityType];
+      if (existing.type === "array") {
+        existing.valueArray = existing.valueArray || [];
+        existing.valueArray.push(convertedEntity);
+      } else {
+        // Convert to array
+        entities[entityType] = {
+          id: convertedEntity.id,
+          type: "array",
+          valueArray: [existing, convertedEntity],
+        };
+      }
+    } else {
+      entities[entityType] = convertedEntity;
+    }
+  }
+
+  return entities;
+}
+
+/**
+ * Converts a GCP Document AI entity into the standardized PretrainedEntity format.
+ *
+ * Handles type inference, value normalization, nested properties, and bounding region
+ * extraction from GCP's entity structure. Processes normalized values (dates, money,
+ * booleans, text), nested properties/objects, page anchors, bounding polygons, and
+ * confidence scores.
+ *
+ * @param entity - GCP entity object from Document AI extraction
+ * @param referenceMap - Reference map to register entity bounding regions
+ * @param idGen - ID generator for creating unique entity IDs
+ * @returns Standardized PretrainedEntity with typed values and metadata
+ */
+function convertGCPEntity(
+  entity: GCPEntity,
+  referenceMap: ReferenceMap,
+  idGen: Generator<number, void, unknown>,
+): PretrainedEntity {
+  const result: PretrainedEntity = {
+    id: `/pe/${idGen.next().value}`,
+    type: inferEntityType(entity),
+    content: entity.mentionText ?? "",
+    confidence: entity.confidence ?? 0,
+  };
+
+  result.boundingRegions =
+    entity.pageAnchor?.pageRefs?.map((p) => {
+      return {
+        pageNumber: p.page ? parseInt(p.page.toString()) + 1 : 1,
+        polygon: p.boundingPoly?.normalizedVertices
+          ?.map((v) => [v.x ?? 0, v.y ?? 0])
+          .flat() as [
+          number,
+          number,
+          number,
+          number,
+          number,
+          number,
+          number,
+          number,
+        ],
+      };
+    }) ?? [];
+
+  if (result.boundingRegions?.length) {
+    referenceMap[result.id] = {
+      text: result.content ?? "",
+      boundingRegions: result.boundingRegions,
+    };
+  }
+
+  // Convert normalized values to standardized format
+  if (entity.normalizedValue) {
+    if (entity.normalizedValue.text) {
+      result.type = "string";
+      result.valueString = entity.normalizedValue.text;
+    }
+
+    if (entity.normalizedValue.dateValue) {
+      result.type = "date";
+      const { year, month, day } = entity.normalizedValue.dateValue;
+      if (year && month && day) {
+        result.valueDate = `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+      }
+    }
+
+    if (entity.normalizedValue.moneyValue) {
+      result.type = "number";
+      const units = entity.normalizedValue.moneyValue.units?.toString() ?? "0";
+      const nanos = entity.normalizedValue.moneyValue.nanos ?? 0;
+      result.valueNumber = parseFloat(units) + nanos / 1e9;
+    }
+
+    if (
+      entity.normalizedValue.booleanValue !== undefined &&
+      entity.normalizedValue.booleanValue !== null
+    ) {
+      result.type = "boolean";
+      result.valueBoolean = entity.normalizedValue.booleanValue;
+    }
+  }
+
+  // Handle properties/nested entities as object
+  if (
+    entity.properties &&
+    Array.isArray(entity.properties) &&
+    entity.properties.length > 0
+  ) {
+    result.type = "object";
+    result.valueObject = {};
+    for (const prop of entity.properties) {
+      const propType = prop.type ?? "unknown";
+      result.valueObject[propType] = convertGCPEntity(
+        prop,
+        referenceMap,
+        idGen,
+      );
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Determines the appropriate standardized type for a GCP entity.
+ *
+ * Examines the entity's normalizedValue and properties to infer whether it represents
+ * a date, number (money), boolean, string, or complex object type.
+ *
+ * @param entity - GCP entity to analyze
+ * @returns The inferred EntityType
+ */
+function inferEntityType(entity: GCPEntity): EntityType {
+  if (entity.normalizedValue) {
+    if (entity.normalizedValue.dateValue) return "date";
+    if (entity.normalizedValue.moneyValue) return "number";
+    if (entity.normalizedValue.booleanValue !== undefined) return "boolean";
+    if (entity.normalizedValue.text) return "string";
+  }
+  if (entity.properties && entity.properties.length > 0) return "object";
+  return "string";
+}
+
+/**
+ * Registers a layout block in the reference map with its text content and bounding regions.
+ *
+ * The reference map allows looking up the original text and spatial location of any
+ * content element by its ID. This is essential for highlighting, extraction validation,
+ * and UI rendering of extracted data.
+ *
+ * @param referenceMap - The map to add this block to
+ * @param id - Unique identifier for this block (e.g., "/p/123")
+ * @param block - GCP layout block containing text and bounding box
+ */
+function addBlockToRefMap(
+  referenceMap: ReferenceMap,
+  id: string,
+  block: GCPLayoutBlock,
+): void {
+  if ("boundingBox" in block && block.boundingBox) {
+    const vertices = block.boundingBox.normalizedVertices;
+    const polygon = (
+      vertices && vertices.length > 0
+        ? [
+            vertices[0]?.x ?? 0,
+            vertices[0]?.y ?? 0,
+            ...vertices
+              .slice(1)
+              .reverse()
+              .flatMap((v) => [v.x ?? 0, v.y ?? 0]),
+          ]
+        : [0, 0, 0, 0, 0, 0, 0, 0]
+    ) as Polygon;
+
+    referenceMap[id] = {
+      text: block.textBlock?.text ?? "",
+      boundingRegions: [
+        {
+          pageNumber: block.pageSpan?.pageStart ?? 0,
+          polygon,
+        },
+      ],
+    };
+  }
+}
+
+/**
+ * Parses a GCP layout block and adds it to the document structure.
+ *
+ * Handles different block types (text, table, list) and manages nested sections.
+ * Text blocks with nested content create new sections in the hierarchy.
+ *
+ * @param block - GCP layout block to parse
+ * @param currentLayout - Top-level layout array
+ * @param sectionStack - Stack of nested sections for hierarchy management
+ * @param referenceMap - Reference map to register block locations
+ * @param pageOffset - Page offset to apply to page numbers (default: 0)
+ */
+function parseBlock(
+  block: GCPLayoutBlock,
+  currentLayout: LayoutItemType[],
+  referenceMap: ReferenceMap,
+  sectionStack: Section[] = [],
+): void {
+  if (block.textBlock) {
+    const { type, text } = block.textBlock;
+    const textContent = text ?? "";
+
+    // process nested blocks as nested sections
+    if (block.textBlock.blocks?.length) {
+      const parentSection = sectionStack[sectionStack.length - 1];
+      const sectionCount = (parentSection?.content ?? currentLayout).filter(
+        (item) => item instanceof Section,
+      ).length;
+      const sectionId = `${parentSection?.id ?? ""}/s${sectionCount}`;
+      const newSection = new Section(
+        sectionId,
+        [],
+        new Header(`${sectionId}/h`, []),
+        new Footer(`${sectionId}/f`, []),
+      );
+
+      // attach the container text to the child section to preserve semantics
+      placeTextBlockInSection(
+        type,
+        textContent,
+        block,
+        newSection,
+        currentLayout,
+        referenceMap,
+      );
+
+      // recurse into nested blocks within the new section's context
+      sectionStack.push(newSection);
+      for (const b of block.textBlock.blocks) {
+        parseBlock(b, currentLayout, referenceMap, sectionStack);
+      }
+      sectionStack.pop();
+
+      // append the fully built section to its parent container
+      (sectionStack[sectionStack.length - 1]?.content ?? currentLayout).push(
+        newSection,
+      );
+      return;
+    }
+    const currentSection = sectionStack[sectionStack.length - 1];
+    placeTextBlockInSection(
+      type,
+      textContent,
+      block,
+      currentSection,
+      currentLayout,
+      referenceMap,
+    );
+  } else if (block.tableBlock) {
+    const currentSection = sectionStack[sectionStack.length - 1];
+    const parentId = `${currentSection?.id ?? ""}`;
+    const tableCount = (currentSection?.content ?? currentLayout).filter(
+      (item) => item instanceof Table,
+    ).length;
+    const blockId = `${parentId}/t${tableCount}`;
+    const table = parseGCPTable(block.tableBlock, blockId, referenceMap);
+    const currentSectionContent =
+      sectionStack[sectionStack.length - 1]?.content ?? currentLayout;
+    currentSectionContent.push(table);
+  } else if (block.listBlock) {
+    const currentSection = sectionStack[sectionStack.length - 1];
+    const parentId = `${currentSection?.id ?? ""}`;
+    const listCount = (currentSection?.content ?? currentLayout).filter(
+      (item) => item instanceof List,
+    ).length;
+    const blockId = `${parentId}/l${listCount}`;
+    const list = parseGCPList(block.listBlock, blockId, referenceMap);
+    const currentSectionContent =
+      sectionStack[sectionStack.length - 1]?.content ?? currentLayout;
+    currentSectionContent.push(list);
+  }
+}
+
+/**
+ * Parses a GCP page and adds its content to the document structure. This is
+ * used to get layout from a pretrained model, not genertic layout parser.
+ *
+ * Processes page-level elements (paragraphs, tables, etc.) and adds them
+ * to the document layout. Page number is used to calculate bounding region offsets.
+ *
+ * @param page - GCP page object containing layout elements
+ * @param baseText - Base text of the document
+ * @param currentLayout - Top-level layout array
+ * @param referenceMap - Reference map to register element locations
+ */
+function parsePage(
+  page: GCPPage,
+  currentLayout: LayoutItemType[],
+  referenceMap: ReferenceMap,
+  getText: (layout?: GCPPageItemLayout | null) => string,
+): void {
+  const pageNumber = page.pageNumber ?? 1;
+
+  // Process paragraphs - these are the main text content elements from page structure
+  for (const paragraph of page.paragraphs ?? []) {
+    const text = getText(paragraph.layout);
+    const paragraphCount = currentLayout.filter(
+      (i) => i instanceof Paragraph,
+    ).length;
+    const paragraphId = `/p${paragraphCount}`;
+
+    // Add to reference map with bounding region
+    if (paragraph.layout?.boundingPoly?.normalizedVertices) {
+      const vertices = paragraph.layout.boundingPoly.normalizedVertices;
+      const polygon = (
+        vertices.length > 0
+          ? vertices.flatMap((v) => [v.x ?? 0, v.y ?? 0])
+          : [0, 0, 0, 0, 0, 0, 0, 0]
+      ) as Polygon;
+
+      referenceMap[paragraphId] = {
+        text: text ?? "",
+        boundingRegions: [{ pageNumber, polygon }],
+      };
+    }
+
+    currentLayout.push(new Paragraph(paragraphId, text ?? ""));
+  }
+
+  // Process tables from page structure
+  for (const table of page.tables ?? []) {
+    const tableCount = currentLayout.filter((i) => i instanceof Table).length;
+    const tableId = `/t${tableCount}`;
+
+    const rows: Row[] = [];
+    for (const headerRow of table.headerRows ?? []) {
+      const cells: Cell[] = [];
+      for (const [i, cell] of (headerRow.cells ?? []).entries()) {
+        const cellId = `${tableId}/${rows.length}/${i}`;
+        const cellText = getText(cell.layout);
+
+        // Add cell to reference map
+        if (cell.layout?.boundingPoly?.normalizedVertices) {
+          const vertices = cell.layout.boundingPoly.normalizedVertices;
+          const polygon = (
+            vertices.length > 0
+              ? vertices.flatMap((v) => [v.x ?? 0, v.y ?? 0])
+              : [0, 0, 0, 0, 0, 0, 0, 0]
+          ) as Polygon;
+
+          referenceMap[cellId] = {
+            text: cellText,
+            boundingRegions: [{ pageNumber, polygon }],
+          };
+        }
+
+        cells.push(
+          new Cell(
+            cellId,
+            cellText,
+            cell.colSpan ?? undefined,
+            cell.rowSpan ?? undefined,
+          ),
+        );
+      }
+      rows.push(new Row("head", cells));
+    }
+
+    // Process body rows
+    for (const bodyRow of table.bodyRows ?? []) {
+      const cells: Cell[] = [];
+      for (const [i, cell] of bodyRow.cells?.entries() ?? []) {
+        const cellId = `${tableId}/${rows.length}/${i}`;
+        const cellText = getText(cell.layout);
+
+        // add cell to reference map
+        if (cell.layout?.boundingPoly?.normalizedVertices) {
+          const vertices = cell.layout.boundingPoly.normalizedVertices;
+          const polygon = (
+            vertices.length > 0
+              ? vertices.flatMap((v) => [v.x ?? 0, v.y ?? 0])
+              : [0, 0, 0, 0, 0, 0, 0, 0]
+          ) as Polygon;
+
+          referenceMap[cellId] = {
+            text: cellText,
+            boundingRegions: [{ pageNumber, polygon }],
+          };
+        }
+
+        cells.push(
+          new Cell(
+            cellId,
+            cellText,
+            cell.colSpan ?? undefined,
+            cell.rowSpan ?? undefined,
+          ),
+        );
+      }
+      rows.push(new Row("body", cells));
+    }
+
+    currentLayout.push(new Table(tableId, rows));
+  }
+
+  // TODO: order the elements by their y-coordinate to ensure they are in the correct order
+}
+
+/**
+ * Places a GCP text block into the appropriate part of the document structure.
+ *
+ * Routes text blocks to the correct location based on their type (header, footer,
+ * heading, paragraph) within the target section or top-level layout. Centralizes
+ * the routing logic for both regular blocks and container blocks.
+ *
+ * @param type - GCP block type (e.g., "header", "paragraph", "heading-1")
+ * @param textContent - Text content of the block
+ * @param block - GCP layout block for reference map registration
+ * @param targetSection - Target section to add content to (undefined for top-level)
+ * @param currentLayout - Top-level layout array
+ * @param referenceMap - Reference map to register block locations
+ * @param pageOffset - Page offset to apply to page numbers (default: 0)
+ */
+function placeTextBlockInSection(
+  type: string | null | undefined,
+  textContent: string,
+  block: GCPLayoutBlock,
+  targetSection: Section | undefined,
+  currentLayout: LayoutItemType[],
+  referenceMap: ReferenceMap,
+): void {
+  const parentId = `${targetSection?.id ?? ""}`;
+  switch (type) {
+    case "header":
+    case "subtitle": {
+      if (targetSection) {
+        const paragraphCount = targetSection.header.content.filter(
+          (item) => item instanceof Paragraph,
+        ).length;
+        const paragraphId = `${parentId}/hp${paragraphCount}`; // header paragraph
+        addBlockToRefMap(referenceMap, paragraphId, block);
+        targetSection.header.content.unshift(
+          new Paragraph(paragraphId, textContent),
+        );
+      }
+      break;
+    }
+    case "footer": {
+      if (targetSection) {
+        const paragraphCount = targetSection.footer.content.filter(
+          (item) => item instanceof Paragraph,
+        ).length;
+        const paragraphId = `${parentId}/fp${paragraphCount}`; // footer paragraph
+        addBlockToRefMap(referenceMap, paragraphId, block);
+        targetSection.footer.content.push(
+          new Paragraph(paragraphId, textContent),
+        );
+      }
+      break;
+    }
+    case "heading-1":
+    case "heading-2":
+    case "heading-3":
+    case "heading-4":
+    case "heading-5": {
+      const level = parseInt(type.match(/^heading-(\d)$/)?.[1] ?? "1") as
+        | 1
+        | 2
+        | 3
+        | 4
+        | 5;
+      const container = targetSection?.content ?? currentLayout;
+      const headingCount = container.filter((i) => i instanceof Heading).length;
+      const headingId = `${parentId}/h${headingCount}`;
+      addBlockToRefMap(referenceMap, headingId, block);
+      container.push(new Heading(headingId, level, textContent));
+      break;
+    }
+    case "paragraph": {
+      const container = targetSection?.content ?? currentLayout;
+      const paragraphCount = container.filter(
+        (i) => i instanceof Paragraph,
+      ).length;
+      const paragraphId = `${parentId}/p${paragraphCount}`;
+      addBlockToRefMap(referenceMap, paragraphId, block);
+      container.push(new Paragraph(paragraphId, textContent));
+      break;
+    }
+    default: {
+      console.warn(`[placeTextBlockInSection] Unknown block type: ${type}`);
+      break;
+    }
+  }
+}
+
+/**
+ * Converts a GCP table block into the standardized Table structure.
+ *
+ * Processes header rows and body rows separately, parsing all cells and maintaining
+ * row/column structure. Registers each cell in the reference map for spatial lookups.
+ *
+ * @param tableBlock - GCP table block from Document AI
+ * @param blockId - Unique identifier for this table
+ * @param referenceMap - Map to register cell locations
+ * @returns Structured Table object with rows and cells
+ */
+function parseGCPTable(
+  tableBlock: GCPLayoutTableBlock,
+  blockId: string,
+  referenceMap: ReferenceMap,
+): Table {
+  const rows: Row[] = [];
+  for (const row of tableBlock.headerRows || []) {
+    rows.push(
+      new Row(
+        "head",
+        parseGCPTableCells(
+          row.cells ?? [],
+          referenceMap,
+          `${blockId}/${rows.length}`,
+        ),
+      ),
+    );
+  }
+  for (const row of tableBlock.bodyRows || []) {
+    rows.push(
+      new Row(
+        "body",
+        parseGCPTableCells(
+          row.cells ?? [],
+          referenceMap,
+          `${blockId}/${rows.length}`,
+        ),
+      ),
+    );
+  }
+
+  return new Table(blockId, rows);
+}
+
+/**
+ * Extracts cell data from a row of GCP table cells.
+ *
+ * Each cell may contain multiple text blocks that are concatenated together.
+ * All blocks within each cell are registered in the reference map.
+ *
+ * @param cells - Array of GCP cell structures from a table row
+ * @param referenceMap - Map to register cell block locations
+ * @param parentId - Parent ID for cell identification
+ * @returns Array of structured Cell objects with IDs and content
+ */
+function parseGCPTableCells(
+  cells: GCPLayoutTableCell[],
+  referenceMap: ReferenceMap,
+  parentId: string,
+): Cell[] {
+  return cells.map((c, i) => {
+    const cell = new Cell(
+      "",
+      "",
+      c.colSpan ?? undefined,
+      c.rowSpan ?? undefined,
+    );
+    c.blocks?.forEach((b) => {
+      if (b.blockId) {
+        cell.id = `${parentId}/${i}`;
+        addBlockToRefMap(referenceMap, cell.id, b);
+      }
+      if (b.textBlock?.text) {
+        cell.content += b.textBlock.text;
+      }
+    });
+
+    return cell;
+  });
+}
+
+/**
+ * Converts a GCP list block into the standardized List structure.
+ *
+ * Handles both ordered and unordered lists. Extracts all list entries and their
+ * text content, registering each entry's blocks in the reference map.
+ *
+ * @param listBlock - GCP list block from Document AI
+ * @param blockId - Unique identifier for this list
+ * @param referenceMap - Map to register list item locations
+ * @returns Structured List object with ordered flag and list items
+ */
+function parseGCPList(
+  listBlock: GCPLayoutListBlock,
+  blockId: string,
+  referenceMap: ReferenceMap,
+): List {
+  const ordered = listBlock.type === "ordered";
+  const items: ListItem[] = [];
+
+  if (listBlock.listEntries) {
+    for (const entry of listBlock.listEntries) {
+      const li = new ListItem("", "");
+      // Extract text from all blocks in the list entry
+      for (const entryBlock of entry.blocks || []) {
+        if (entryBlock.blockId) {
+          const refId = `/b/${entryBlock.blockId}`;
+          if (!li.id) li.id = refId; // set once per list item
+          addBlockToRefMap(referenceMap, refId, entryBlock);
+        }
+        if (entryBlock.textBlock?.text) {
+          li.content += entryBlock.textBlock.text + " ";
+        }
+      }
+      li.content = li.content.trim();
+      items.push(li);
+    }
+  }
+
+  return new List(blockId, ordered, items);
+}