@simpleplatform/sdk 2.3.0 → 2.4.1

package/README.md

@@ -308,6 +308,63 @@ yet; attach its handle through the workflow that owns the record.
 
 ## API Documentation
 
+### Describing an Action
+
+What an action is, and when to reach for it, is written where the code is — in
+the JSDoc comment above the handler, the same comment that carries its
+description:
+
+```typescript
+/**
+ * Close a duplicate lead and point it at the record that survives.
+ *
+ * The surviving lead keeps its activity; the duplicate is marked closed and
+ * linked to it, so a later report still reaches both records.
+ *
+ * @tool
+ * @shortdesc Close a duplicate lead, pointing it at the surviving record.
+ * @usewhen A lead is a duplicate of one already in the system.
+ * @usewhen Two leads share a contact and one should be retired.
+ */
+simple.Handle(async (request) => {
+  // ...
+})
+```
+
+| Tag             | Shape                                           | What it says                                                                                                                              |
+| --------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `@tool`         | bare, no value                                  | This action can be reached as a tool                                                                                                      |
+| `@shortdesc`    | one line, up to 300 characters, written once    | What this is, read in a listing of tools                                                                                                  |
+| `@usewhen`      | one line, up to 100 characters, up to ten times | One occasion for reaching for this rather than something else                                                                             |
+| `@parallelsafe` | bare, no value, only alongside `@tool`          | This tool changes no stored data and sends nothing, so it may run at the same time as the other parallel-safe calls next to it in a batch |
+
+`@parallelsafe` is a claim you make about your own action; the platform does
+not verify it. It changes only which calls of a batch may overlap — consecutive
+parallel-safe calls may run at the same time, and every other call still runs
+alone, in the order asked. It never changes whether a failed call is retried,
+nor the platform's assumption that a failed call may have changed stored data.
+The build refuses it without `@tool`, with a value, or written twice. Write it
+only when the action is read-only:
+
+```typescript
+/**
+ * Look up a lead's open activity.
+ *
+ * @tool
+ * @shortdesc Look up a lead's open activity.
+ * @usewhen A caller wants a lead's current open activity.
+ * @parallelsafe
+ */
+simple.Handle(async (request) => {
+  // reads only — no writes, no outbound calls
+})
+```
+
+The prose above the tags is the full description, and stays exactly as
+written. Each tag is declared in `tsdoc.json` (`{"tagName": "@parallelsafe",
+"syntaxKind": "modifier"}` alongside `@tool`, `@shortdesc` and `@usewhen`), so
+an editor with TSDoc support recognizes it instead of flagging it as unknown.
+
 ### AI Module
 
 The AI module provides powerful capabilities for working with unstructured data.
@@ -382,6 +439,60 @@ console.log(result.data.summary) // "Customer called regarding..."
 console.log(result.data.participants) // ["Customer", "Support Agent"]
 ```
 
+#### Transcribe PDF Pages
+
+Read the pages of a PDF that have no usable text of their own — scans,
+image-only exhibits — from their images. Each such page is transcribed once,
+and it is the same transcription an `extract` or `summarize` that asks for text
+is given in the page's place, so a quote on an image page can be checked
+against the text the answer was built on. Pages with a readable text layer are
+not returned.
+
+```typescript
+import { transcribePages } from '@simpleplatform/sdk/ai'
+
+const { data } = await transcribePages(
+  { ...contract, first_page: 40, last_page: 52 },
+  {},
+  request.context
+)
+
+for (const page of data.pages) {
+  if ('error' in page) {
+    console.log(`page ${page.page} could not be read: ${page.error}`)
+    continue
+  }
+
+  console.log(page.page, page.text.includes(quote))
+}
+```
+
+Pages are numbered in the original document. Transcriptions are kept per
+version of the file and page, so a page already read for an `extract` or
+`summarize` that asked for text (`deliver_as: 'text'`) is not read again.
+
+A page is not transcribed twice to check itself: that would be the same model
+reading the same image again, doubling the cost of every scanned page without
+adding independence. To check an answer independently, read the pages a second
+way — as the document itself (`deliver_as: 'document'`) — and compare.
+
+#### How Files Travelled
+
+Every AI result says how each file it carried reached the model, in
+`metadata.delivery`: `deliveredAs` (`'document'`, `'text'` or `'image'`), the
+range it was cut to, the pages transcribed from their images, and — when text
+was asked for and the document was sent instead — a `fallback` naming the pages
+that could not be read and why.
+
+```typescript
+const result = await extract({ ...contract, deliver_as: 'text' }, { prompt, schema }, request.context)
+
+for (const file of result.metadata.delivery ?? []) {
+  if (file.fallback)
+    console.log(`${file.filename} was read as a PDF: ${file.fallback.message}`)
+}
+```
+
 ### GraphQL Module
 
 Execute type-safe database operations with GraphQL:

package/dist/ai.d.ts

@@ -88,8 +88,12 @@ export type JSONSchema = JSONSchemaArray | JSONSchemaBoolean | JSONSchemaNumber
  *   file,
  *   which only ever travels as text.
  *
- * A page the platform cannot read as text sends the pages asked for as a PDF
- * instead, so an answer is never built on text with a hole in it.
+ * A page with no usable text of its own — a scan, or text that reads as noise
+ * — is read from its image instead, and that text stands in its place, marked
+ * `[Transcribed from the page image.]` under its page label. Only if that
+ * reading fails are the pages asked for sent as a PDF, so an answer is never
+ * built on text with a hole in it. The answer's `metadata.delivery` says which
+ * happened.
  *
  * Pages asked for as text arrive numbered from 1, because by then they are a
  * document of their own. A line above them says which pages of which document
@@ -203,6 +207,62 @@ export interface AITranscribeOptions extends Omit<AICommonOptions, 'prompt'> {
      */
     summarize?: boolean;
 }
+/**
+ * A PDF whose pages are to be transcribed, and optionally which of them.
+ *
+ * `first_page` and `last_page` work as they do for any AI operation: counted
+ * from 1, both ends included, named together or not at all, and cut out first.
+ * `deliver_as` has no meaning here, because the pages are answered as text.
+ */
+export type AITranscribePagesInput = DocumentHandle & Omit<AIDocumentInput, 'deliver_as' | keyof DocumentHandle>;
+/**
+ * Configuration options for `transcribePages`. There is no prompt and no
+ * reasoning switch: the instructions are the platform's, and every page is
+ * read at the platform's own accuracy-first effort.
+ */
+export interface AITranscribePagesOptions {
+    /**
+     * If true, runs the operation again rather than serving its kept answer.
+     * A page already read is still served from its kept read, which is tied to
+     * this version of the file and to the platform's instructions.
+     */
+    regenerate?: boolean;
+    /** (Optional) The maximum time in milliseconds to wait for the operation. */
+    timeout?: number;
+}
+/**
+ * One page's transcription, or why it has none. Pages are numbered in the
+ * original document.
+ */
+export type AIPageTranscription = {
+    /** Why the page could not be read. No partial text is given. */
+    error: string;
+    /** The page's number in the original document. */
+    page: number;
+} | {
+    /** The page's number in the original document. */
+    page: number;
+    /**
+     * The page's text as read from its image: verbatim markdown, in reading
+     * order, tables as markdown tables, `[illegible]` where a word could not
+     * be read. An empty string is a read that found the page blank.
+     */
+    text: string;
+};
+/**
+ * The response of `transcribePages`.
+ */
+export interface AITranscriptionResult {
+    /** Every page of the document, or of the range, that has no usable text layer. */
+    data: {
+        pages: AIPageTranscription[];
+    };
+    /**
+     * The operation's metadata. Its token counts are zero: each page read is
+     * charged where it was made, once, whichever operation asked for it.
+     */
+    metadata: AIExecutionResult['metadata'];
+}
 /**
  * Options for searching faces within the Face Engine.
  */
@@ -218,6 +278,34 @@ export interface AIFaceSearchOptions {
      */
     similarityThreshold?: number;
 }
+/**
+ * How one file an AI operation carried reached the model. Page numbers are
+ * the original document's, whatever range was cut from it.
+ */
+export interface AIFileDelivery {
+    /** How the file travelled: as the document itself, as its text, or as an image. */
+    deliveredAs: 'document' | 'image' | 'text';
+    /**
+     * Present only when text was asked for and the document was sent instead:
+     * the pages whose images could not be read, and why.
+     */
+    fallback?: {
+        /** What went wrong, page by page, in the platform's words. */
+        message: string;
+        /** The pages that could not be transcribed. */
+        pages: number[];
+        /** Why the document travelled instead of its text. */
+        reason: 'transcription_failed';
+    };
+    /** The file's name. */
+    filename: string;
+    /** The first page of the range the file was cut to, when one was named. */
+    firstPage?: number;
+    /** The last page of the range the file was cut to, when one was named. */
+    lastPage?: number;
+    /** The pages whose text was read from their images rather than their text layer. */
+    transcribedPages: number[];
+}
 /**
  * The response structure from a successful AI `extract` or `summarize` operation.
  */
@@ -232,6 +320,12 @@ export interface AIExecutionResult {
      * providing context to the user.
      */
     metadata: {
+        /**
+         * How each file the operation carried reached the model, in input order.
+         * Absent when the operation carried no file, and on an answer kept from
+         * before the platform reported it.
+         */
+        delivery?: AIFileDelivery[];
         /** The number of tokens in the input prompt. */
         inputTokens: number;
         /** The number of tokens in the generated output. */
@@ -301,6 +395,48 @@ export declare function summarize(input: AIDocumentInput | DocumentHandle | obje
  * // Returns: { language: "en", summary: "...", participants: ["Participant 1", "Participant 2"] }
  */
 export declare function transcribe(input: DocumentHandle, options: AITranscribeOptions, context: Context): Promise<AIExecutionResult>;
+/**
+ * Transcribes the pages of a PDF that have no usable text of their own — scans,
+ * image-only exhibits, text that reads as noise — from their images.
+ *
+ * Every such page is read once, and it is the same transcription an `extract`
+ * or `summarize` that asked for text is given in the page's place, so a caller
+ * can check that a quote on an image page is really there by looking for it in
+ * the text the answer was built on. Pages the platform reads as text are
+ * neither read nor returned.
+ *
+ * A page is not transcribed a second time to check the first: that would be
+ * the same model reading the same image again, doubling the cost of every
+ * scanned page without being independent of the first read. An independent
+ * check reads the pages a second way — as the document itself
+ * (`deliver_as: 'document'`) — and compares the answers.
+ *
+ * Transcriptions are kept per version of the file and page, and shared with
+ * every other AI operation: a page already read for an `extract` or
+ * `summarize` that asked for text is not read again.
+ *
+ * @param document The PDF, as a DocumentHandle. Add `first_page` and
+ *   `last_page` to transcribe only those pages; they are counted from 1 and
+ *   the answer numbers pages in the original document.
+ * @param options Optional `regenerate` and `timeout`.
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to each page's transcription, or why it has none.
+ * @throws Will throw an error if the operation fails or the input is not a PDF.
+ *
+ * @example
+ * const { data } = await transcribePages(
+ *   { ...contract, first_page: 40, last_page: 52 },
+ *   {},
+ *   context,
+ * )
+ *
+ * for (const page of data.pages) {
+ *   if ('error' in page)
+ *     continue
+ *   const quoted = page.text.includes(quote)
+ * }
+ */
+export declare function transcribePages(document: AITranscribePagesInput, options: AITranscribePagesOptions, context: Context): Promise<AITranscriptionResult>;
 /**
  * Enrolls a face for a subject. The face is associated with the given `subjectId`
  * within the tenant's secure collection.

package/dist/ai.js

@@ -85,6 +85,7 @@ async function _executeAIOperation(operation, input, options, context) {
     return {
         data,
         metadata: {
+            ...(Array.isArray(metadata.delivery) && { delivery: metadata.delivery.map(_fileDelivery) }),
             inputTokens: metadata.input_tokens,
             outputTokens: metadata.output_tokens,
             reasoning: metadata.reasoning,
@@ -92,6 +93,38 @@ async function _executeAIOperation(operation, input, options, context) {
         },
     };
 }
+/**
+ * One file's delivery as the platform reports it, in the SDK's own casing.
+ * A key the platform sends as `null` is left out rather than carried as one.
+ *
+ * @internal
+ */
+function _fileDelivery(file) {
+    return {
+        deliveredAs: file.delivered_as,
+        ...(file.fallback && { fallback: file.fallback }),
+        filename: file.filename,
+        ...(typeof file.first_page === 'number' && { firstPage: file.first_page }),
+        ...(typeof file.last_page === 'number' && { lastPage: file.last_page }),
+        transcribedPages: Array.isArray(file.transcribed_pages) ? file.transcribed_pages : [],
+    };
+}
+/**
+ * One page's transcription as the platform reports it: its text or its error,
+ * never both. An error wins, so no partial text is handed on, and a page that
+ * carries no text is reported as unread rather than as text that is not there.
+ *
+ * @internal
+ */
+function _pageTranscription(page) {
+    if (typeof page.text === 'string' && typeof page.error !== 'string') {
+        return { page: page.page, text: page.text };
+    }
+    return {
+        error: typeof page.error === 'string' ? page.error : 'no transcription was returned for this page',
+        page: page.page,
+    };
+}
 // ============================================================================
 // Public SDK Functions
 // ============================================================================
@@ -284,6 +317,61 @@ export async function transcribe(input, options, context) {
         schema,
     }, context);
 }
+/**
+ * Transcribes the pages of a PDF that have no usable text of their own — scans,
+ * image-only exhibits, text that reads as noise — from their images.
+ *
+ * Every such page is read once, and it is the same transcription an `extract`
+ * or `summarize` that asked for text is given in the page's place, so a caller
+ * can check that a quote on an image page is really there by looking for it in
+ * the text the answer was built on. Pages the platform reads as text are
+ * neither read nor returned.
+ *
+ * A page is not transcribed a second time to check the first: that would be
+ * the same model reading the same image again, doubling the cost of every
+ * scanned page without being independent of the first read. An independent
+ * check reads the pages a second way — as the document itself
+ * (`deliver_as: 'document'`) — and compares the answers.
+ *
+ * Transcriptions are kept per version of the file and page, and shared with
+ * every other AI operation: a page already read for an `extract` or
+ * `summarize` that asked for text is not read again.
+ *
+ * @param document The PDF, as a DocumentHandle. Add `first_page` and
+ *   `last_page` to transcribe only those pages; they are counted from 1 and
+ *   the answer numbers pages in the original document.
+ * @param options Optional `regenerate` and `timeout`.
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to each page's transcription, or why it has none.
+ * @throws Will throw an error if the operation fails or the input is not a PDF.
+ *
+ * @example
+ * const { data } = await transcribePages(
+ *   { ...contract, first_page: 40, last_page: 52 },
+ *   {},
+ *   context,
+ * )
+ *
+ * for (const page of data.pages) {
+ *   if ('error' in page)
+ *     continue
+ *   const quoted = page.text.includes(quote)
+ * }
+ */
+export async function transcribePages(document, options, context) {
+    if (!document || typeof document !== 'object' || !document.file_hash) {
+        throw new Error('The `document` parameter must be a valid DocumentHandle for `transcribePages`.');
+    }
+    const mimeType = (document.mime_type || '').split(';')[0].trim().toLowerCase();
+    if (mimeType !== 'application/pdf') {
+        throw new Error('`transcribePages` reads the pages of a PDF.');
+    }
+    const result = await _executeAIOperation('transcribe', document, options, context);
+    return {
+        data: { pages: Array.isArray(result.data?.pages) ? result.data.pages.map(_pageTranscription) : [] },
+        metadata: result.metadata,
+    };
+}
 // ============================================================================
 // Face Recognition API
 // ============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleplatform/sdk",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "Simple Platform Typescript SDK",
   "license": "Apache-2.0",
   "homepage": "https://docs.simple.dev",