sea-dev 1.0.0

package/libs/schemas/src/core/data-extraction.ts

@@ -0,0 +1,184 @@
+import { z } from "zod/v4";
+
+// Model types
+export const ExtractionModelSchema = z.enum([
+  "general",
+  "smart",
+  "expert",
+  "bank_statement",
+  "agentic",
+  "agentic_analyst",
+  "direct",
+  "financials",
+]);
+export type ExtractionModel = z.infer<typeof ExtractionModelSchema>;
+
+export const ReasoningEffortSchema = z.enum(["none", "minimal", "low", "medium", "high"]);
+export type ReasoningEffort = z.infer<typeof ReasoningEffortSchema>;
+
+// Document extraction request
+export const DocumentExtractionRequestSchema = z.object({
+  documentExtractionId: z.string(),
+  userPrompt: z.string().optional(),
+  context: z.string().optional(),
+  options: z.object({
+    extractionModel: ExtractionModelSchema,
+    reasoningEffort: ReasoningEffortSchema.optional(),
+  }),
+});
+export type DocumentExtractionRequest = z.infer<typeof DocumentExtractionRequestSchema>;
+
+// Value with reference types for citations
+export const ReferenceSchema = z.object({
+  refId: z.string().describe("Reference ID of the appropriate object in the source data"),
+});
+
+export const StringValueWithRefSchema = ReferenceSchema.extend({
+  value: z.string().describe("String value"),
+});
+
+export const NumberValueWithRefSchema = ReferenceSchema.extend({
+  value: z
+    .number()
+    .describe("Numeric value. Numbers in parentheses denote negatives (e.g. (100) -> -100)."),
+});
+
+export const BooleanValueWithRefSchema = ReferenceSchema.extend({
+  value: z.boolean().describe("Boolean value"),
+});
+
+export const DateValueWithRefSchema = ReferenceSchema.extend({
+  value: z.iso.date().describe("Date value"),
+});
+
+export const EmailValueWithRefSchema = ReferenceSchema.extend({
+  value: z.email().describe("Email string value"),
+});
+
+export const MoneyValueWithRefSchema = ReferenceSchema.extend({
+  value: z
+    .number()
+    .describe("Numeric money value. Numbers in parentheses denote negatives (e.g. (100) -> -100)."),
+});
+
+export const UrlValueWithRefSchema = ReferenceSchema.extend({
+  value: z.url().describe("URL string value"),
+});
+
+export const ValueWithReferenceSchema = z
+  .union([
+    StringValueWithRefSchema,
+    NumberValueWithRefSchema,
+    BooleanValueWithRefSchema,
+    DateValueWithRefSchema,
+    EmailValueWithRefSchema,
+    MoneyValueWithRefSchema,
+    UrlValueWithRefSchema,
+  ])
+  .nullable()
+  .default(null);
+
+export type ValueWithReference = z.infer<typeof ValueWithReferenceSchema>;
+
+export type StructuredGroup =
+  | Record<string, ValueWithReference>
+  | Record<string, ValueWithReference>[]
+  | null;
+
+export type StructuredData = Record<string, StructuredGroup> | null;
+
+// Bank statement reconciliation
+export const BankStatementReconciliationSchema = z.object({
+  statementPeriodStart: z.string(),
+  statementPeriodEnd: z.string(),
+  openingBalance: z.number().nullable(),
+  closingBalance: z.number().nullable(),
+  totalCredits: z.number(),
+  totalDebits: z.number(),
+  calculatedClosingBalance: z.number(),
+  balanceDifference: z.number(),
+  isReconciled: z.boolean(),
+});
+
+export type BankStatementReconciliation = z.infer<typeof BankStatementReconciliationSchema>;
+
+// Validation data
+export type ValidationData = Record<string, { index: number; message: string }[]>;
+
+// Structured response
+export type StructuredResponse = {
+  data: StructuredData;
+  validationData?: ValidationData;
+  reconciliationData?: BankStatementReconciliation;
+};
+
+// Citation types
+export type CitationRef = {
+  id: string;
+  sourceRef: string;
+  path: string;
+  value?: string | number;
+};
+
+export type SourceAnnotation = {
+  key: string;
+  boundingRegions: {
+    polygon: [number, number, number, number, number, number, number, number];
+    pageNumber: number;
+  }[];
+  linkedCitations: CitationRef[];
+};
+
+// Document classification schemas
+/**
+ * Schema for a single classification result
+ */
+export const ClassificationResultSchema = z.object({
+  /** The document type/class label */
+  docType: z.string(),
+  /** Confidence score for this classification (0-1) */
+  confidence: z.number().min(0).max(1),
+  /** Page ranges for this document (for multi-document classification) */
+  pages: z
+    .array(
+      z.object({
+        /** Starting page number (1-indexed) */
+        pageNumber: z.number(),
+        /** Ending page number (1-indexed, inclusive) */
+        endPageNumber: z.number().optional(),
+      }),
+    )
+    .optional(),
+});
+
+export type ClassificationResult = z.infer<typeof ClassificationResultSchema>;
+
+/**
+ * Schema for document classification response
+ */
+export const DocumentClassificationResponseSchema = z.object({
+  /** API version used */
+  apiVersion: z.string().optional(),
+  /** Model ID used for classification */
+  modelId: z.string(),
+  /** Array of classification results (one per document in the input) */
+  documents: z.array(ClassificationResultSchema),
+});
+
+export type DocumentClassificationResponse = z.infer<typeof DocumentClassificationResponseSchema>;
+
+/**
+ * Schema for classification request
+ */
+export const DocumentClassificationRequestSchema = z.object({
+  /** Base64-encoded document data */
+  base64Source: z.string().optional(),
+  /** URL to the document */
+  urlSource: z.string().url().optional(),
+  /** Pages to classify (optional, defaults to all pages) */
+  pages: z.string().optional(),
+  /** Split mode for multi-document classification */
+  splitMode: z.enum(["auto", "none", "perPage"]).optional(),
+});
+
+export type DocumentClassificationRequest = z.infer<typeof DocumentClassificationRequestSchema>;

package/libs/schemas/src/core/layout.ts

@@ -0,0 +1,478 @@
+// ============================================================================
+// Layout Configuration Types
+// ============================================================================
+
+export type LayoutModelType = "custom" | "bank_statement";
+export type LayoutModelProvider = "gcp" | "azure";
+
+export type LayoutExtractionOptions = {
+  extractionModel: LayoutModelType;
+  provider: LayoutModelProvider;
+};
+
+// ============================================================================
+// Spatial Reference Types
+// ============================================================================
+
+export type Polygon = [number, number, number, number, number, number, number, number];
+
+export type BoundingRegion = {
+  polygon: Polygon;
+  pageNumber: number;
+};
+
+export type DataReference = {
+  text: string;
+  boundingRegions: BoundingRegion[];
+};
+
+export type ReferenceMap = Record<string, DataReference>;
+
+// ============================================================================
+// Core Document Structure
+// ============================================================================
+
+/**
+ * Base interface for serializable document elements
+ */
+export interface Serializable {
+  serialize(): string;
+  serializeAsText(): string;
+}
+
+/**
+ * DocumentLayout class representing the complete document structure
+ */
+export class DocumentLayout implements Serializable {
+  constructor(
+    public documentLayout: LayoutItemType[],
+    public entities: Record<string, PretrainedEntity>,
+    public referenceMap: ReferenceMap,
+  ) {}
+
+  static fromJSON(data: unknown): DocumentLayout {
+    const obj = data as Record<string, unknown>;
+    return new DocumentLayout(
+      ((obj.documentLayout as unknown[]) || []).map((item) => layoutItemFromJSON(item)),
+      (obj.entities as Record<string, PretrainedEntity>) || {},
+      (obj.referenceMap as ReferenceMap) || {},
+    );
+  }
+
+  serialize(): string {
+    const contentHtml = this.documentLayout.map((item) => item.serialize()).join("");
+    return `<html>${contentHtml}</html>`;
+  }
+
+  serializeAsText(): string {
+    const text = this.documentLayout.map((item) => item.serializeAsText()).join("");
+    return text;
+  }
+}
+
+export type LayoutItemType = Section | Paragraph | Table | List | Heading;
+
+// ============================================================================
+// Pretrained Entity Extraction Types
+// ============================================================================
+
+export type EntityType = "string" | "date" | "number" | "boolean" | "array" | "object";
+
+export type SpanOutputType = {
+  offset: number;
+  length: number;
+};
+
+export type PretrainedEntity = {
+  id: string;
+  type: EntityType;
+  valueBoolean?: boolean;
+  valueString?: string;
+  valueDate?: string;
+  valueNumber?: number;
+  valueArray?: Array<PretrainedEntity>;
+  valueObject?: Record<string, PretrainedEntity>;
+  boundingRegions?: BoundingRegion[];
+  spans?: Array<SpanOutputType>;
+  content?: string;
+  confidence?: number;
+};
+
+// ============================================================================
+// Layout Element Classes
+// ============================================================================
+
+/**
+ * Paragraph class representing a paragraph element
+ */
+export class Paragraph implements Serializable {
+  constructor(
+    public id: string,
+    public content: string,
+    public type: string = "paragraph",
+  ) {}
+
+  static fromJSON(data: unknown): Paragraph {
+    const obj = data as Record<string, unknown>;
+    return new Paragraph(obj.id as string, obj.content as string, obj.type as string);
+  }
+
+  serialize(): string {
+    return `<p id="${this.id}">${this.content}</p>`;
+  }
+
+  serializeAsText(): string {
+    return `\n${this.content}\n`;
+  }
+}
+
+// ============================================================================
+// Table Structure Classes
+// ============================================================================
+
+/**
+ * Table class representing a table element
+ */
+export class Table implements Serializable {
+  constructor(
+    public id: string,
+    public content: Row[],
+    public type: string = "table",
+  ) {}
+
+  static fromJSON(data: unknown): Table {
+    const obj = data as Record<string, unknown>;
+    return new Table(
+      obj.id as string,
+      ((obj.content as unknown[]) || []).map((row) => Row.fromJSON(row)),
+    );
+  }
+
+  serialize(): string {
+    const rowsHtml = this.content.map((row) => row.serialize()).join("");
+    return `<table>${rowsHtml}</table>`;
+  }
+
+  serializeAsText(): string {
+    const text = this.content.map((row) => row.serializeAsText()).join("\n");
+    return text;
+  }
+}
+
+/**
+ * Row class representing a table row
+ */
+export class Row implements Serializable {
+  constructor(
+    public type: "head" | "body",
+    public cells: Cell[],
+  ) {}
+
+  static fromJSON(data: unknown): Row {
+    const obj = data as Record<string, unknown>;
+    return new Row(
+      obj.type as "head" | "body",
+      ((obj.cells as unknown[]) || []).map((cell) => Cell.fromJSON(cell)),
+    );
+  }
+
+  serialize(): string {
+    const cellsHtml = this.cells
+      .map((cell) => (this.type === "head" ? cell.serializeAsHeader() : cell.serialize()))
+      .join("");
+    return `<tr>${cellsHtml}</tr>`;
+  }
+
+  serializeAsText(): string {
+    const text = this.cells.map((cell) => cell.serializeAsText()).join(",");
+    return text;
+  }
+}
+
+/**
+ * Cell class representing a table cell
+ */
+export class Cell implements Serializable {
+  constructor(
+    public id: string,
+    public content: string,
+    public colspan?: number,
+    public rowspan?: number,
+  ) {}
+
+  static fromJSON(data: unknown): Cell {
+    const obj = data as Record<string, unknown>;
+    return new Cell(
+      obj.id as string,
+      obj.content as string,
+      obj.colspan as number | undefined,
+      obj.rowspan as number | undefined,
+    );
+  }
+
+  serialize(): string {
+    const attrs = this.buildSpanAttributes();
+    return `<td id="${this.id}"${attrs}>${this.content}</td>`;
+  }
+
+  serializeAsHeader(): string {
+    const spanAttributes = this.buildSpanAttributes();
+    return `<th id="${this.id}"${spanAttributes}>${this.content}</th>`;
+  }
+
+  private buildSpanAttributes(): string {
+    const parts: string[] = [];
+    if (this.colspan && this.colspan > 1) {
+      parts.push(`colspan="${this.colspan}"`);
+    }
+    if (this.rowspan && this.rowspan > 1) {
+      parts.push(`rowspan="${this.rowspan}"`);
+    }
+    return parts.length > 0 ? ` ${parts.join(" ")}` : "";
+  }
+
+  serializeAsText(): string {
+    return this.content;
+  }
+}
+
+// ============================================================================
+// Section Container Class
+// ============================================================================
+
+/**
+ * Section class representing a document section with nested content
+ */
+export class Section implements Serializable {
+  constructor(
+    public id: string,
+    public content: LayoutItemType[],
+    public header: Header,
+    public footer: Footer,
+    public type: string = "section",
+  ) {}
+
+  static fromJSON(data: unknown): Section {
+    const obj = data as Record<string, unknown>;
+    return new Section(
+      obj.id as string,
+      ((obj.content as unknown[]) || []).map((item) => layoutItemFromJSON(item)),
+      Header.fromJSON(obj.header),
+      Footer.fromJSON(obj.footer),
+    );
+  }
+
+  serialize(): string {
+    const headerHtml = this.header ? this.header.serialize() : "";
+    const contentHtml = this.content.map((item) => item.serialize()).join("");
+    const footerHtml = this.footer ? this.footer.serialize() : "";
+    return `<section>${headerHtml}${contentHtml}${footerHtml}</section>`;
+  }
+
+  serializeAsText(): string {
+    const text = this.content.map((item) => item.serializeAsText()).join("\n");
+    return text;
+  }
+}
+
+// ============================================================================
+// Section Component Classes
+// ============================================================================
+
+/**
+ * PageHeader class representing a section or document header
+ */
+export class Header implements Serializable {
+  constructor(
+    public id: string,
+    public content: Paragraph[],
+    public type: string = "header",
+  ) {}
+
+  static fromJSON(data: unknown): Header {
+    const obj = data as Record<string, unknown>;
+    return new Header(
+      obj.id as string,
+      ((obj.content as unknown[]) || []).map((item) => Paragraph.fromJSON(item)),
+    );
+  }
+
+  serialize(): string {
+    return `<header>${this.content.map((p) => p.serialize()).join("")}</header>`;
+  }
+
+  serializeAsText(): string {
+    const text = this.content.map((p) => p.serializeAsText()).join("\n");
+    return text;
+  }
+}
+
+/**
+ * PageFooter class representing a section or document footer
+ */
+export class Footer implements Serializable {
+  constructor(
+    public id: string,
+    public content: Paragraph[],
+    public type: string = "footer",
+  ) {}
+
+  static fromJSON(data: unknown): Footer {
+    const obj = data as Record<string, unknown>;
+    return new Footer(
+      obj.id as string,
+      ((obj.content as unknown[]) || []).map((item) => Paragraph.fromJSON(item)),
+    );
+  }
+
+  serialize(): string {
+    return `<footer>${this.content.map((p) => p.serialize()).join("")}</footer>`;
+  }
+
+  serializeAsText(): string {
+    const text = this.content.map((p) => p.serializeAsText()).join("\n");
+    return text;
+  }
+}
+
+/**
+ * Footnote class representing a footnote
+ */
+export class Footnote implements Serializable {
+  constructor(
+    public id: string,
+    public content: string,
+    public type: string = "footnote",
+  ) {}
+
+  serialize(): string {
+    return `<aside id="${this.id}">${this.content}</aside>`;
+  }
+
+  serializeAsText(): string {
+    return this.content;
+  }
+}
+
+// ============================================================================
+// Text Formatting Classes
+// ============================================================================
+
+/**
+ * SectionTitle class representing a section title/heading
+ */
+export class Heading implements Serializable {
+  constructor(
+    public id: string,
+    public level: 1 | 2 | 3 | 4 | 5,
+    public content: string,
+    public type: string = "heading",
+  ) {}
+
+  static fromJSON(data: unknown): Heading {
+    const obj = data as Record<string, unknown>;
+    return new Heading(
+      obj.id as string,
+      (obj.level as 1 | 2 | 3 | 4 | 5) || 1,
+      obj.content as string,
+    );
+  }
+
+  serialize(): string {
+    return `<h${this.level} id="${this.id}">${this.content}</h${this.level}>`;
+  }
+
+  serializeAsText(): string {
+    return this.content;
+  }
+}
+
+// ============================================================================
+// List Structure Classes
+// ============================================================================
+
+/**
+ * ListItem class representing a list item
+ */
+export class ListItem implements Serializable {
+  constructor(
+    public id: string,
+    public content: string,
+    public type: string = "listitem",
+  ) {}
+
+  static fromJSON(data: unknown): ListItem {
+    const obj = data as Record<string, unknown>;
+    return new ListItem(obj.id as string, obj.content as string);
+  }
+
+  serialize(): string {
+    return `<li id="${this.id}">${this.content}</li>`;
+  }
+
+  serializeAsText(): string {
+    return this.content;
+  }
+}
+
+/**
+ * List class representing an ordered or unordered list
+ */
+export class List implements Serializable {
+  constructor(
+    public id: string,
+    public ordered: boolean,
+    public items: ListItem[],
+    public type: string = "list",
+  ) {}
+
+  static fromJSON(data: unknown): List {
+    const obj = data as Record<string, unknown>;
+    return new List(
+      obj.id as string,
+      (obj.ordered as boolean) || false,
+      ((obj.items as unknown[]) || []).map((item) => ListItem.fromJSON(item)),
+    );
+  }
+
+  serialize(): string {
+    const tag = this.ordered ? "ol" : "ul";
+    const itemsHtml = this.items.map((item) => item.serialize()).join("");
+    return `<${tag} id="${this.id}">${itemsHtml}</${tag}>`;
+  }
+
+  serializeAsText(): string {
+    const text = this.items.map((item) => item.serializeAsText()).join("\n");
+    return text;
+  }
+}
+
+// ============================================================================
+// Deserialization Utilities
+// ============================================================================
+
+/**
+ * Helper function for deserializing layout items based on their type
+ */
+export function layoutItemFromJSON(data: unknown): LayoutItemType {
+  if (typeof data !== "object" || data === null || !("type" in data)) {
+    throw new Error("Invalid layout item: missing type property");
+  }
+
+  const item = data as { type: unknown };
+
+  switch (item.type) {
+    case "section":
+      return Section.fromJSON(data);
+    case "paragraph":
+      return Paragraph.fromJSON(data);
+    case "table":
+      return Table.fromJSON(data);
+    case "list":
+      return List.fromJSON(data);
+    case "heading":
+      return Heading.fromJSON(data);
+    default:
+      throw new Error(`Unknown layout item type: ${item.type}`);
+  }
+}