@simpleplatform/sdk 2.1.0 → 2.2.0

package/dist/ai.d.ts

@@ -65,6 +65,52 @@ export interface JSONSchemaArray extends JSONSchemaBase {
  * This provides developers with precise autocompletion and type-checking.
  */
 export type JSONSchema = JSONSchemaArray | JSONSchemaBoolean | JSONSchemaNumber | JSONSchemaObject | JSONSchemaString;
+/**
+ * A stored file handed to an AI operation, together with what should be done
+ * with it.
+ *
+ * A PDF travels to the model as a PDF, because the model reads one: its tables,
+ * its layout and its figures survive the trip, and none of them survive being
+ * turned into text. Asking for text is therefore opt-in.
+ *
+ * The page range and `deliver_as` are two questions, asked in that order. The
+ * range says WHICH DOCUMENT the call is about: those pages are taken out of
+ * the PDF first, and everything after that is about them and nothing else.
+ * `deliver_as` then says how that document should reach the model.
+ *
+ * Refused, before the file is read or anything is spent:
+ * - `first_page` or `last_page` on anything that is not a PDF;
+ * - one of the pair without the other, a `first_page` below 1, a `last_page`
+ *   before `first_page`, or either one not a whole number;
+ * - a range that runs past the end of the document;
+ * - `deliver_as: 'text'` on an image, which is not read as text;
+ * - `deliver_as: 'document'` on a Word, Excel, PowerPoint, CSV, RTF or text
+ *   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.
+ *
+ * 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
+ * they were, rather than the numbers being rewritten inside the text: a page
+ * number printed in a header or a cross-reference cannot be told apart from a
+ * page label, so editing them would corrupt the document's own words.
+ */
+export type AIDocumentInput = DocumentHandle & {
+    /** The first page to use, counted from 1. Named with `last_page`. PDF only. */
+    first_page?: number;
+    /** The last page to use, included. Named with `first_page`. PDF only. */
+    last_page?: number;
+    /**
+     * How the document reaches the model: `'document'`, the default, sends the
+     * document itself; `'text'` sends the text the platform reads out of it.
+     *
+     * Both answers are sayable, so the default can be written down rather than
+     * left to the absence of a key.
+     */
+    deliver_as?: 'document' | 'text';
+};
 /**
  * A set of common configuration options shared across all AI operations.
  * This adheres to the DRY principle, ensuring a consistent API surface.
@@ -200,22 +246,26 @@ export interface AIExecutionResult {
  * Extracts structured data from a given input using the Simple AI engine.
  *
  * @param input The source data for the extraction (string, document handle, or object).
+ *   A document handle may carry `deliver_as`, `first_page` and `last_page`; see
+ *   `AIDocumentInput`.
  * @param options The configuration for the extraction operation.
  * @param context The execution context provided by the host.
  * @returns A promise that resolves to an `AIExecutionResult` object.
  * @throws Will throw an error if the operation fails or inputs are invalid.
  */
-export declare function extract(input: DocumentHandle | object | string, options: AIExtractOptions, context: Context): Promise<AIExecutionResult>;
+export declare function extract(input: AIDocumentInput | DocumentHandle | object | string, options: AIExtractOptions, context: Context): Promise<AIExecutionResult>;
 /**
  * Generates a summary for a given input using the Simple AI engine.
  *
  * @param input The source data for the summarization (string, document handle, or object).
+ *   A document handle may carry `deliver_as`, `first_page` and `last_page`; see
+ *   `AIDocumentInput`.
  * @param options The configuration for the summarization operation.
  * @param context The execution context provided by the host.
  * @returns A promise that resolves to an `AIExecutionResult` object containing the summary.
  * @throws Will throw an error if the operation fails or inputs are invalid.
  */
-export declare function summarize(input: DocumentHandle | object | string, options: AISummarizeOptions, context: Context): Promise<AIExecutionResult>;
+export declare function summarize(input: AIDocumentInput | DocumentHandle | object | string, options: AISummarizeOptions, context: Context): Promise<AIExecutionResult>;
 /**
  * Transcribes audio or video from a document handle using the Simple AI engine.
  *

package/dist/ai.js

@@ -5,8 +5,9 @@ import { execute as hostExecute } from './host';
 /**
  * Recursively processes an object to detect and upload pending files.
  * When a pending DocumentHandle is detected (has `pending: true` and `file_hash`),
- * it calls the ephemeral upload host function and replaces the pending handle
- * with the ephemeral handle returned from the upload.
+ * it calls the ephemeral upload host function and hands the operation the
+ * stored handle the upload answered with, carrying over the keys the caller
+ * put on the handle.
  *
  * @internal
  */
@@ -19,7 +20,23 @@ async function _uploadPendingFiles(obj, context) {
         if (!response.ok) {
             throw new Error(response.error?.message || 'Failed to upload pending file');
         }
-        return response.data;
+        // The upload answers with the stored file's own reference: where it is,
+        // what it hashes to, its name, its type and its size. Every one of those
+        // keys describes the file, so every one of them is taken from the upload
+        // and none is carried over — a value from before the upload would name a
+        // file that is no longer the one being read.
+        //
+        // Everything else on the handle is the caller's: how the file is to be
+        // sent, which of its pages, and any key added to a file reference later.
+        // Those describe the request, not the file, and the upload knows nothing
+        // about them, so they are carried over. A caller reads a pending file and
+        // a stored one the same way.
+        //
+        // `pending` is the one key that is neither: it said the bytes had not been
+        // stored yet. They have been now, so it is dropped. A handle that still
+        // called itself pending would be uploaded a second time on the next pass.
+        const { pending: _pending, ...caller } = obj;
+        return { ...caller, ...response.data };
     }
     if (Array.isArray(obj)) {
         return Promise.all(obj.map(item => _uploadPendingFiles(item, context)));
@@ -82,6 +99,8 @@ async function _executeAIOperation(operation, input, options, context) {
  * Extracts structured data from a given input using the Simple AI engine.
  *
  * @param input The source data for the extraction (string, document handle, or object).
+ *   A document handle may carry `deliver_as`, `first_page` and `last_page`; see
+ *   `AIDocumentInput`.
  * @param options The configuration for the extraction operation.
  * @param context The execution context provided by the host.
  * @returns A promise that resolves to an `AIExecutionResult` object.
@@ -105,6 +124,8 @@ export async function extract(input, options, context) {
  * Generates a summary for a given input using the Simple AI engine.
  *
  * @param input The source data for the summarization (string, document handle, or object).
+ *   A document handle may carry `deliver_as`, `first_page` and `last_page`; see
+ *   `AIDocumentInput`.
  * @param options The configuration for the summarization operation.
  * @param context The execution context provided by the host.
  * @returns A promise that resolves to an `AIExecutionResult` object containing the summary.

package/package.json

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