Skip to content

DocumentAttachment

DocumentAttachment bridges document content to LLM consumption. It determines the appropriate handling strategy for each document based on MIME type and content, then prepares documents for inclusion in Gemini prompts -- either as inline text, tabular previews, binary attachments, or Files API references.

Import

import {
  DocumentAttachment,
  PreparedDocument,
  DocumentContentType,
  PrepareDocumentOptions,
} from "@modernpath/agent-framework";

Constructor

new DocumentAttachment(
  sharepointAuth: SharePointAuth,
  sharepointGraph: SharePointGraphClient,
  parser: DocumentParser,
  gemini: GeminiClient,
  fileSyncService?: FileSyncService,
)
Parameter Type Description
sharepointAuth SharePointAuth Authentication provider for SharePoint access.
sharepointGraph SharePointGraphClient Graph API client for downloading documents.
parser DocumentParser Parser for CSV/Excel files.
gemini GeminiClient Gemini client for Files API uploads.
fileSyncService FileSyncService Optional service for tracking synced files.

DocumentContentType

type DocumentContentType =
  | "text"        // Read as UTF-8, include directly in prompt
  | "tabular"     // CSV/Excel - parsed for SQL queries
  | "attachment"  // Binary attachment (PDF, images, Office docs)
  | "filesApi";   // Large file uploaded to Files API

Content type is determined automatically from the MIME type and file extension:

Content Type File Types
text .md, .txt, .json, .yaml, .html, .xml, .py, .ts, .js, and other code files
tabular .csv, .xlsx, .xls
attachment .pdf, .docx, .pptx, .png, .jpg, .webp, .gif
filesApi Any file exceeding maxInlineSizeBytes (default 20MB)

Static Methods

buildPromptWithDocuments

static buildPromptWithDocuments(
  basePrompt: string,
  prepared: PreparedDocument | PreparedDocument[],
  options?: {
    maxTextLength?: number;
    tabularPreviewRows?: number;
  },
): {
  prompt: string;
  documents?: GeminiDocument[];
  fileReferences?: GeminiFileReference[];
}

Constructs an LLM prompt with document context. Text documents are included inline in the prompt. Tabular data gets a preview. Binary attachments and Files API references are returned separately for the Gemini options.

Parameter Type Default Description
basePrompt string -- The base prompt text.
prepared PreparedDocument \| PreparedDocument[] -- One or more prepared documents.
options.maxTextLength number 100000 Maximum characters for inline text documents.
options.tabularPreviewRows number 20 Maximum rows in tabular preview.

Returns: An object with the augmented prompt, optional documents array for inline attachments, and optional fileReferences array for Files API references.

tabularPreview

static tabularPreview(
  parsed: ParsedDocumentData,
  maxRows?: number,
  maxCols?: number,
): string

Generates a text preview of tabular data suitable for prompt inclusion.

Parameter Type Default Description
parsed ParsedDocumentData -- Parsed document data.
maxRows number 20 Maximum rows to include.
maxCols number 12 Maximum columns to include.

getGeminiOptions

static getGeminiOptions(
  prepared: PreparedDocument | PreparedDocument[],
): {
  documents?: GeminiDocument[];
  fileReferences?: GeminiFileReference[];
}

Extracts Gemini-compatible attachment options from prepared documents. Prefer buildPromptWithDocuments() for new code.

Instance Methods

downloadAndPrepareDocument

async downloadAndPrepareDocument(
  ctx: AttachmentContext,
  documentId: string,
  options?: PrepareDocumentOptions,
): Promise<PreparedDocument>

Downloads a document from SharePoint and prepares it for LLM processing.

prepareInlineDocument

async prepareInlineDocument(
  content: Buffer,
  mimeType: string,
  name: string,
  options?: PrepareDocumentOptions,
): Promise<PreparedDocument>

Prepares a document from inline content (not from SharePoint).

PreparedDocument

interface PreparedDocument {
  documentId: string;
  name: string;
  mimeType: string;
  content: Buffer;
  contentType: DocumentContentType;
  textContent?: string;
  parsedData?: ParsedDocumentData;
  geminiDocument?: GeminiDocument;
  geminiFileReference?: GeminiFileReference;
  syncedFile?: SyncedFile;
}
Field Type Description
documentId string Unique identifier for the document.
name string Original file name.
mimeType string MIME type.
content Buffer Raw file bytes.
contentType DocumentContentType How this document should be used.
textContent string For text-based documents: UTF-8 content for direct prompt inclusion.
parsedData ParsedDocumentData For tabular documents: parsed data for SQL querying.
geminiDocument GeminiDocument For binary documents: inline Gemini attachment.
geminiFileReference GeminiFileReference For large files: Files API reference.

PrepareDocumentOptions

interface PrepareDocumentOptions {
  useFilesApi?: "auto" | "always" | "never";
  maxInlineSizeBytes?: number;
  forceContentType?: DocumentContentType;
}
Option Type Default Description
useFilesApi string "auto" "auto": use Files API for files > maxInlineSizeBytes. "always": always use Files API. "never": always inline.
maxInlineSizeBytes number 20971520 (20MB) Threshold for auto Files API usage.
forceContentType DocumentContentType -- Override automatic content type detection.

Code Example

import { DocumentAttachment } from "@modernpath/agent-framework";

// Prepare a document from SharePoint
const prepared = await attachment.downloadAndPrepareDocument(
  { userId: 1, auditingId: 100, siteId: "site-123" },
  "document-456",
);

// Build prompt with document context
const { prompt, documents, fileReferences } = DocumentAttachment.buildPromptWithDocuments(
  "Analyze the attached document and summarize the key findings.",
  prepared,
);

// Pass to Gemini
const response = await geminiClient.generateContent(prompt, {
  documents,
  fileReferences,
});

// Handle multiple documents
const docs = await Promise.all([
  attachment.prepareInlineDocument(csvBuffer, "text/csv", "data.csv"),
  attachment.prepareInlineDocument(pdfBuffer, "application/pdf", "report.pdf"),
]);

const result = DocumentAttachment.buildPromptWithDocuments(
  "Compare the data file with the report.",
  docs,
  { maxTextLength: 50000, tabularPreviewRows: 10 },
);