@modelprofile.com/flexharness 8.1.0 → 8.3.0

package/ts/utils.json.ts

@@ -1,3 +1,4 @@
+import * as plugins from './plugins.js';
 import { FlexHarnessStoreFormatError, FlexHarnessValidationError } from './errors.js';
 import {
   FLEX_REVERSION_MAX_AFFECTED_WORKSPACES,
@@ -406,6 +407,12 @@ function requireOptionalString(value: unknown, path: string): string | undefined
   return value === undefined ? undefined : requireString(value, path);
 }
 
+function requireOptionalModelLimit(value: unknown, path: string): void {
+  if (value !== undefined && !plugins.isModelLimitInfo(value)) {
+    throw new FlexHarnessStoreFormatError(`${path} is invalid.`);
+  }
+}
+
 function requireNonNegativeNumber(value: unknown, path: string): void {
   if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
     throw new FlexHarnessStoreFormatError(`${path} must be a non-negative finite number.`);
@@ -501,7 +508,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
     throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
   }
   const activity = requireRecord(session.activity, `${path}.activity`);
-  requireOnlyKeys(activity, ['runId', 'status', 'startedAt', 'completedAt', 'error'], `${path}.activity`);
+  requireOnlyKeys(activity, ['runId', 'status', 'startedAt', 'completedAt', 'error', 'limit'], `${path}.activity`);
   if (!activityStatuses.includes(activity.status as (typeof activityStatuses)[number])) {
     throw new FlexHarnessStoreFormatError(`${path}.activity.status is invalid.`);
   }
@@ -509,6 +516,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   requireOptionalString(activity.startedAt, `${path}.activity.startedAt`);
   requireOptionalString(activity.completedAt, `${path}.activity.completedAt`);
   requireOptionalString(activity.error, `${path}.activity.error`);
+  requireOptionalModelLimit(activity.limit, `${path}.activity.limit`);
   const relationship = [
     session.parentSessionId,
     session.parentRunId,
@@ -667,6 +675,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       'model',
       'usage',
       'error',
+      'limit',
     ],
     path,
   );
@@ -682,6 +691,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
   requireString(message.createdAt, `${path}.createdAt`);
   requireOptionalString(message.completedAt, `${path}.completedAt`);
   requireOptionalString(message.error, `${path}.error`);
+  requireOptionalModelLimit(message.limit, `${path}.limit`);
   if (message.model !== undefined) validateModel(message.model, `${path}.model`);
   if (message.usage !== undefined) validateUsage(message.usage, `${path}.usage`);
   if (!Array.isArray(message.parts)) {

package/ts/utils.validation.ts

@@ -1,3 +1,4 @@
+import * as plugins from './plugins.js';
 import { FlexHarnessValidationError } from './errors.js';
 import {
   FLEX_PROJECT_MANAGEMENT_LIMITS,
@@ -162,30 +163,30 @@ export function validateDeleteSessionGenerationCohortInput(
   return { root, authorizedBySessionId };
 }
 
-export function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
+/** A plain object whose own properties are all string-keyed data properties, so reading them runs no code. */
+function isPlainDataObject(value: unknown): value is Record<string, unknown> {
   if (
     !value
     || typeof value !== 'object'
     || Array.isArray(value)
     || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
-  ) {
+  ) return false;
+  return Reflect.ownKeys(value).every((key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return typeof key === 'string' && descriptor !== undefined && 'value' in descriptor;
+  });
+}
+
+export function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
+  if (!isPlainDataObject(value)) {
     throw new FlexHarnessValidationError('External error projection is invalid.');
   }
-  const descriptors = Object.getOwnPropertyDescriptors(value);
-  const unsupportedKey = Reflect.ownKeys(descriptors).find(
-    (key) => typeof key !== 'string' || !['name', 'message', 'code'].includes(key),
-  );
-  const name = descriptors.name?.value;
-  const message = descriptors.message?.value;
-  const code = descriptors.code?.value;
+  const unsupportedKey = Object.getOwnPropertyNames(value)
+    .find((key) => !['name', 'message', 'code', 'limit'].includes(key));
+  const { name, message, code, limit } = value;
   if (
     unsupportedKey
-    || descriptors.name?.get !== undefined
-    || descriptors.name?.set !== undefined
-    || descriptors.message?.get !== undefined
-    || descriptors.message?.set !== undefined
-    || descriptors.code?.get !== undefined
-    || descriptors.code?.set !== undefined
+    || (limit !== undefined && !(isPlainDataObject(limit) && plugins.isModelLimitInfo(limit)))
     || typeof name !== 'string'
     || !name
     || Buffer.byteLength(name, 'utf8') > maxProjectedErrorNameBytes
@@ -199,7 +200,12 @@ export function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
   ) {
     throw new FlexHarnessValidationError('External error projection is invalid.');
   }
-  return Object.freeze({ name, message, ...(code === undefined ? {} : { code }) });
+  return Object.freeze({
+    name,
+    message,
+    ...(code === undefined ? {} : { code }),
+    ...(limit === undefined ? {} : { limit: Object.freeze({ ...limit }) }),
+  });
 }
 
 export function validateUpdateSessionOptions(options: IFlexUpdateSessionOptions): void {

package/ts_document/index.ts

@@ -1,18 +1,44 @@
 import * as plugins from './plugins.js';
 import type { ModelMessage } from 'ai';
-import type { TSmartAiLanguageModel } from '@modelprofile.com/flexharness-models';
+import type { TSmartAiLanguageModel, TSmartAiProviderOptions } from '@modelprofile.com/flexharness-models';
 
-let smartpdfInstance: InstanceType<typeof plugins.smartpdf.SmartPdf> | null = null;
+type TSmartPdf = InstanceType<typeof plugins.smartpdf.SmartPdf>;
 
-async function ensureSmartpdf(): Promise<InstanceType<typeof plugins.smartpdf.SmartPdf>> {
-  if (!smartpdfInstance) {
-    smartpdfInstance = new plugins.smartpdf.SmartPdf();
-    await smartpdfInstance.start();
+/** The one start of the shared SmartPDF instance; every request awaits it, and a failed start is forgotten. */
+let smartpdfStart: Promise<TSmartPdf> | null = null;
+
+function ensureSmartpdf(): Promise<TSmartPdf> {
+  if (!smartpdfStart) {
+    const instance = new plugins.smartpdf.SmartPdf();
+    const start = instance.start().then(() => instance);
+    smartpdfStart = start;
+    start.catch(() => {
+      if (smartpdfStart === start) {
+        smartpdfStart = null;
+      }
+    });
   }
-  return smartpdfInstance;
+  return smartpdfStart;
+}
+
+/** Options every document request accepts in addition to its model and messages. */
+export interface IDocumentRequestOptions {
+  /** Passed to the model call unchanged, for example `{ openai: { store: false } }`. */
+  providerOptions?: TSmartAiProviderOptions;
+  /**
+   * Checked before each document is rendered and before the model call, and passed to the model
+   * call. SmartPDF cannot stop a document it is rendering, so that render finishes first.
+   */
+  abortSignal?: AbortSignal;
+  /**
+   * The most rendered pages one request may send to the model. A request with more pages rejects
+   * with `DocumentPageLimitError` before the model is called; documents after the one that
+   * exceeded the limit are not rendered.
+   */
+  maxPages?: number;
 }
 
-export interface IDocumentOptions {
+export interface IDocumentOptions extends IDocumentRequestOptions {
   model: TSmartAiLanguageModel;
   systemMessage?: string;
   userMessage: string;
@@ -20,34 +46,111 @@ export interface IDocumentOptions {
   messageHistory?: ModelMessage[];
 }
 
-export interface IPdfTextExtractionOptions {
+export interface IPdfTextExtractionOptions extends IDocumentRequestOptions {
   model: TSmartAiLanguageModel;
   systemMessage?: string;
   userMessage?: string;
   messageHistory?: ModelMessage[];
 }
 
+/** Token usage of a document request, summed over its model steps; usage a provider leaves out counts as zero. */
+export interface IDocumentUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+}
+
+export interface IDocumentAnalysisResult {
+  text: string;
+  usage: IDocumentUsage;
+  /** Rendered pages sent to the model. A page that renders to an empty image is not sent. */
+  pageCount: number;
+}
+
+export interface IDocumentPageLimitErrorDetails {
+  renderedPages: number;
+  maxPages: number;
+  documentCount: number;
+  allDocumentsRendered: boolean;
+}
+
+/** A request whose documents render to more pages than its `maxPages`; the model was not called. */
+export class DocumentPageLimitError extends Error {
+  /** Pages rendered before the request stopped; with several documents, later documents are not counted. */
+  public readonly renderedPages: number;
+  public readonly maxPages: number;
+
+  constructor(details: IDocumentPageLimitErrorDetails) {
+    const subject = details.documentCount === 1
+      ? `The document has ${details.renderedPages} pages`
+      : details.allDocumentsRendered
+        ? `The documents have ${details.renderedPages} pages`
+        : `The documents have at least ${details.renderedPages} pages`;
+    super(`${subject}, more than the ${details.maxPages} allowed.`);
+    this.name = 'DocumentPageLimitError';
+    this.renderedPages = details.renderedPages;
+    this.maxPages = details.maxPages;
+  }
+}
+
+const DEFAULT_OCR_SYSTEM_MESSAGE = 'You are a precise OCR engine. Extract text faithfully and do not summarize.';
+const DEFAULT_OCR_USER_MESSAGE = 'Extract all readable text from this PDF. Preserve page order, line breaks, table structure, and obvious headings. Return only the extracted text.';
+
 /** The model-based PDF OCR recipe formerly provided by SmartOCR. */
 export async function extractTextFromPdf(
   pdfDocument: Uint8Array,
   options: IPdfTextExtractionOptions,
 ): Promise<string> {
-  return analyzeDocuments({
+  return (await extractTextFromPdfWithUsage(pdfDocument, options)).text;
+}
+
+/** `extractTextFromPdf` that also returns the request's token usage and the pages sent. */
+export async function extractTextFromPdfWithUsage(
+  pdfDocument: Uint8Array,
+  options: IPdfTextExtractionOptions,
+): Promise<IDocumentAnalysisResult> {
+  return analyzeDocumentsWithUsage({
     model: options.model,
-    systemMessage: options.systemMessage ?? 'You are a precise OCR engine. Extract text faithfully and do not summarize.',
-    userMessage: options.userMessage ?? 'Extract all readable text from this PDF. Preserve page order, line breaks, table structure, and obvious headings. Return only the extracted text.',
+    systemMessage: options.systemMessage ?? DEFAULT_OCR_SYSTEM_MESSAGE,
+    userMessage: options.userMessage ?? DEFAULT_OCR_USER_MESSAGE,
     pdfDocuments: [pdfDocument],
     messageHistory: options.messageHistory,
+    providerOptions: options.providerOptions,
+    abortSignal: options.abortSignal,
+    maxPages: options.maxPages,
   });
 }
 
 export async function analyzeDocuments(options: IDocumentOptions): Promise<string> {
-  const pdf = await ensureSmartpdf();
+  return (await analyzeDocumentsWithUsage(options)).text;
+}
+
+/** `analyzeDocuments` that also returns the request's token usage and the pages sent. */
+export async function analyzeDocumentsWithUsage(options: IDocumentOptions): Promise<IDocumentAnalysisResult> {
+  const maxPages = options.maxPages;
+  if (maxPages !== undefined && (!Number.isSafeInteger(maxPages) || maxPages < 1)) {
+    throw new RangeError('maxPages must be a positive whole number.');
+  }
+  const abortSignal = options.abortSignal;
+  abortSignal?.throwIfAborted();
 
   const imagePages: Uint8Array[] = [];
-  for (const doc of options.pdfDocuments) {
+  for (const [index, doc] of options.pdfDocuments.entries()) {
+    const pdf = await ensureSmartpdf();
+    abortSignal?.throwIfAborted();
     const pages = await pdf.convertPDFToPngBytes(doc);
+    abortSignal?.throwIfAborted();
     imagePages.push(...pages);
+    if (maxPages !== undefined && imagePages.length > maxPages) {
+      throw new DocumentPageLimitError({
+        renderedPages: imagePages.length,
+        maxPages,
+        documentCount: options.pdfDocuments.length,
+        allDocumentsRendered: index === options.pdfDocuments.length - 1,
+      });
+    }
   }
 
   // Filter out empty buffers
@@ -70,13 +173,39 @@ export async function analyzeDocuments(options: IDocumentOptions): Promise<strin
         ],
       },
     ],
+    providerOptions: options.providerOptions,
+    abortSignal,
   });
-  return result.text;
+  const usage = result.totalUsage;
+  const inputTokens = usage.inputTokens ?? 0;
+  const outputTokens = usage.outputTokens ?? 0;
+  return {
+    text: result.text,
+    usage: {
+      inputTokens,
+      outputTokens,
+      totalTokens: inputTokens + outputTokens,
+      cacheReadTokens: usage.inputTokenDetails.cacheReadTokens ?? 0,
+      cacheWriteTokens: usage.inputTokenDetails.cacheWriteTokens ?? 0,
+    },
+    pageCount: validPages.length,
+  };
 }
 
 export async function stopSmartpdf(): Promise<void> {
-  if (smartpdfInstance) {
-    await smartpdfInstance.stop();
-    smartpdfInstance = null;
+  const start = smartpdfStart;
+  if (!start) {
+    return;
+  }
+  // forget the instance before waiting on anything, so a request made from now on starts a fresh one
+  // instead of receiving the instance that is being stopped
+  smartpdfStart = null;
+  let instance: TSmartPdf;
+  try {
+    instance = await start;
+  } catch {
+    // a failed start left no started instance that could be stopped
+    return;
   }
+  await instance.stop();
 }

package/ts_document/readme.md

@@ -23,6 +23,32 @@ Supply a model from your selected FlexHarness provider. `extractTextFromPdf` rep
 
 `analyzeDocuments({ model, userMessage, pdfDocuments, systemMessage?, messageHistory? })` supports general analysis across multiple PDFs. This component owns a shared SmartPDF instance; call `stopSmartpdf()` when all document work has finished. Image-only OCR is available independently in `flexharness/ocr`.
 
+Both functions accept three request options:
+
+- `providerOptions` is passed to the model call unchanged, for example `{ openai: { store: false } }` so the provider does not keep the request as application state.
+- `abortSignal` is checked before each document is rendered and before the model call, and is passed to the model call. SmartPDF cannot stop a document it is already rendering, so that render finishes first.
+- `maxPages` is the most rendered pages one request may send to the model. A request with more pages rejects with `DocumentPageLimitError` (`renderedPages`, `maxPages`) before the model is called, and documents after the one that exceeded the limit are not rendered.
+
+`extractTextFromPdfWithUsage` and `analyzeDocumentsWithUsage` take the same arguments and return `{ text, usage, pageCount }`. `usage` has the shape of an agent run's usage (`inputTokens`, `outputTokens`, `totalTokens`, `cacheReadTokens`, `cacheWriteTokens`), summed over the request's model steps, with usage the provider leaves out counted as zero; `pageCount` is the number of rendered pages sent to the model.
+
+```typescript
+import { extractTextFromPdfWithUsage, DocumentPageLimitError } from '@modelprofile.com/flexharness/documents';
+
+try {
+  const { text, usage, pageCount } = await extractTextFromPdfWithUsage(pdfBytes, {
+    model,
+    providerOptions: { openai: { store: false } },
+    abortSignal,
+    maxPages: 20,
+  });
+} catch (error) {
+  if (error instanceof DocumentPageLimitError) {
+    console.log(`${error.renderedPages} pages, at most ${error.maxPages}`);
+  }
+  throw error;
+}
+```
+
 ## Issue Reporting and Security
 
 Report issues and security concerns through [community.foss.global](https://community.foss.global).