@simpleplatform/sdk 1.0.0

package/dist/ai.d.ts

@@ -0,0 +1,239 @@
+/**
+ * @file Simple Platform AI SDK
+ *
+ * This module provides a high-level, developer-friendly interface for interacting
+ * with the platform's powerful, asynchronous AI engine. It abstracts away the
+ * underlying complexity of calling the trusted `ai-orchestrator` primitive,
+ * handling payload construction and response transformation automatically.
+ *
+ * This makes AI a first-class, reusable primitive, available to any developer
+ * in any logic module they build on the Simple platform.
+ */
+import type { Context, DocumentHandle } from './types';
+/**
+ * Base properties common to all JSON Schema definitions.
+ */
+interface JSONSchemaBase {
+    description?: string;
+}
+/**
+ * JSON Schema definition for a string type.
+ */
+export interface JSONSchemaString extends JSONSchemaBase {
+    format?: 'date' | 'date-time' | 'email' | 'uri';
+    maxLength?: number;
+    minLength?: number;
+    pattern?: string;
+    type: 'string';
+}
+/**
+ * JSON Schema definition for a number or integer type.
+ */
+export interface JSONSchemaNumber extends JSONSchemaBase {
+    exclusiveMaximum?: number;
+    exclusiveMinimum?: number;
+    maximum?: number;
+    minimum?: number;
+    multipleOf?: number;
+    type: 'integer' | 'number';
+}
+/**
+ * JSON Schema definition for a boolean type.
+ */
+export interface JSONSchemaBoolean extends JSONSchemaBase {
+    type: 'boolean';
+}
+/**
+ * JSON Schema definition for an object type.
+ */
+export interface JSONSchemaObject extends JSONSchemaBase {
+    properties: Record<string, JSONSchema>;
+    required?: string[];
+    type: 'object';
+}
+/**
+ * JSON Schema definition for an array type.
+ */
+export interface JSONSchemaArray extends JSONSchemaBase {
+    items: JSONSchema;
+    maxItems?: number;
+    minItems?: number;
+    type: 'array';
+}
+/**
+ * A discriminated union representing a complete and strongly-typed JSON Schema.
+ * This provides developers with precise autocompletion and type-checking.
+ */
+export type JSONSchema = JSONSchemaArray | JSONSchemaBoolean | JSONSchemaNumber | JSONSchemaObject | JSONSchemaString;
+/**
+ * A set of common configuration options shared across all AI operations.
+ * This adheres to the DRY principle, ensuring a consistent API surface.
+ */
+export interface AICommonOptions {
+    /**
+     * The kind of model to use for this execution.
+     * Example: "medium", "large".
+     * If omitted, the platform chooses a sensible default model.
+     */
+    model?: 'large' | 'lite' | 'medium' | 'xl';
+    /** A natural language prompt to guide the AI's process. */
+    prompt: string;
+    /**
+     * If true, forces the AI to provide a detailed, multi-step reasoning
+     * process in the generated output. Defaults to false.
+     */
+    reasoning?: boolean;
+    /**
+     * The maximum number of tokens to spend on the reasoning process.
+     * If omitted, the platform chooses a sensible default.
+     * Ignored if `reasoning` is false.
+     */
+    reasoningBudget?: number;
+    /**
+     * If true, forces the AI to re-process the input, ignoring
+     * any previously cached results in the AI Memcache. Defaults to false.
+     */
+    regenerate?: boolean;
+    /**
+     * (Optional) A system prompt to define the AI's role, personality, or
+     * high-level instructions for the entire task.
+     */
+    systemPrompt?: string;
+    /**
+     * (Optional) Controls the creativity of the model. A value from 0.0 (most
+     * deterministic) to 1.0 (most creative). Defaults to the model's standard.
+     */
+    temperature?: number;
+    /**
+     * (Optional) The maximum time in milliseconds to wait for the AI operation.
+     * If this timeout is exceeded, the promise will reject. Defaults to 30,000ms.
+     */
+    timeout?: number;
+}
+/**
+ * The configuration options for an AI `extract` operation.
+ * Extends the common options with a required `schema`.
+ */
+export interface AIExtractOptions extends AICommonOptions {
+    /**
+     * The desired JSON schema of the output. This provides a strong contract
+     * for the AI to follow when generating its response.
+     */
+    schema: JSONSchema;
+}
+/**
+ * The configuration options for an AI `summarize` operation.
+ * Extends the common options. No additional properties are needed.
+ */
+export interface AISummarizeOptions extends AICommonOptions {
+}
+/**
+ * Configuration options for audio/video transcription.
+ * Extends common options but excludes `prompt` as it's generated internally.
+ */
+export interface AITranscribeOptions extends Omit<AICommonOptions, 'prompt'> {
+    /**
+     * If true, includes timestamps in the transcript (format: [MM:SS]).
+     * Only applicable when `includeTranscript` is true.
+     */
+    includeTimestamps?: boolean;
+    /**
+     * If true, includes the full transcript in the response.
+     * At least one of `includeTranscript` or `summarize` must be true.
+     */
+    includeTranscript?: boolean;
+    /**
+     * Participant identification configuration:
+     * - `true`: Auto-detect participants and label as "Participant 1", "Participant 2", etc.
+     * - `string[]`: Array of participant names/roles to identify (e.g., ['Customer', 'Agent'])
+     * - `undefined`: No participant identification (default)
+     *
+     * When provided, the transcript will include participant labels for each segment.
+     */
+    participants?: boolean | string[];
+    /**
+     * If true, includes a summary of the audio/video content.
+     * At least one of `includeTranscript` or `summarize` must be true.
+     */
+    summarize?: boolean;
+}
+/**
+ * The response structure from a successful AI `extract` or `summarize` operation.
+ */
+export interface AIExecutionResult {
+    /**
+     * The primary data returned by the AI. For `extract`, this is the structured
+     * object matching the requested schema. For `summarize`, it's the summary string.
+     */
+    data: any;
+    /**
+     * Rich metadata about the AI execution, useful for auditing, debugging, and
+     * providing context to the user.
+     */
+    metadata: {
+        /** The number of tokens in the input prompt. */
+        inputTokens: number;
+        /** The number of tokens in the generated output. */
+        outputTokens: number;
+        /** A summary of the AI's internal reasoning process, if provided. */
+        reasoning?: string;
+        /** The number of tokens used for internal "thinking", if applicable. */
+        reasoningTokens?: number;
+    };
+}
+/**
+ * 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).
+ * @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>;
+/**
+ * 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).
+ * @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>;
+/**
+ * Transcribes audio or video from a document handle using the Simple AI engine.
+ *
+ * This function internally uses the `extract` operation with a dynamically generated
+ * schema based on the requested options. It supports participant identification,
+ * timestamps, and summarization.
+ *
+ * @param input The audio or video file as a DocumentHandle.
+ * @param options The configuration for the transcription operation.
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to an `AIExecutionResult` with structured transcription data.
+ * @throws Will throw an error if the operation fails or inputs are invalid.
+ *
+ * @example
+ * // Basic transcript
+ * const result = await transcribe(audioHandle, { includeTranscript: true }, context)
+ * // Returns: { language: "en", transcript: "..." }
+ *
+ * @example
+ * // Transcript with participant identification
+ * const result = await transcribe(audioHandle, {
+ *   includeTranscript: true,
+ *   participants: ['Customer', 'Support Agent']
+ * }, context)
+ * // Returns: { language: "en", transcript: "Customer: Hello...\nSupport Agent: Hi...", participants: [...] }
+ *
+ * @example
+ * // Summary with auto-detected participants
+ * const result = await transcribe(videoHandle, {
+ *   summarize: true,
+ *   participants: true
+ * }, context)
+ * // Returns: { language: "en", summary: "...", participants: ["Participant 1", "Participant 2"] }
+ */
+export declare function transcribe(input: DocumentHandle, options: AITranscribeOptions, context: Context): Promise<AIExecutionResult>;
+export {};

package/dist/ai.js

@@ -0,0 +1,265 @@
+import { execute as hostExecute } from './host';
+// ============================================================================
+// Internal Implementation
+// ============================================================================
+/**
+ * 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.
+ *
+ * @internal
+ */
+async function _uploadPendingFiles(obj, context) {
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    if (obj.pending === true && obj.file_hash) {
+        const response = await hostExecute('action:documents/upload-ephemeral', obj, context);
+        if (!response.ok) {
+            throw new Error(response.error?.message || 'Failed to upload pending file');
+        }
+        return response.data;
+    }
+    if (Array.isArray(obj)) {
+        return Promise.all(obj.map(item => _uploadPendingFiles(item, context)));
+    }
+    return obj;
+}
+/**
+ * The internal, shared logic for executing any AI operation. This function
+ * is not exported and serves as the single, DRY implementation for all
+ * public-facing AI functions.
+ *
+ * @internal
+ */
+async function _executeAIOperation(operation, input, options, context) {
+    const { model, prompt, reasoning, reasoningBudget, regenerate = false, systemPrompt, temperature, timeout, } = options;
+    const processedInput = await _uploadPendingFiles(input, context);
+    // 1. Construct the universal options payload for caching and execution.
+    const universalOptions = {
+        ...(temperature !== undefined && { temperature }),
+        ...(reasoningBudget !== undefined && { reasoningBudget }),
+        ...({ reasoning }),
+    };
+    // 2. Construct the full payload for the `ai-orchestrator` Go primitive.
+    //    This includes the operation-specific `schema` if it exists.
+    const payload = {
+        input: processedInput,
+        model,
+        operation,
+        options: universalOptions,
+        prompt,
+        regenerate,
+        schema: options.schema, // Will be undefined for summarize, which is correct
+        systemPrompt,
+        timeout,
+    };
+    // 3. Call the trusted primitive. The SDK's `hostExecute` handles the complexity
+    //    of the underlying `logic:` call and the async execution.
+    const response = await hostExecute('logic:dev.simple.system/ai-orchestrator', payload, context);
+    if (!response.ok) {
+        throw new Error(response.error?.message || `AI '${operation}' operation failed.`);
+    }
+    // 4. Transform the raw backend response into the clean, developer-facing API contract.
+    const aioData = response.data;
+    const data = aioData?.data;
+    const metadata = aioData?.metadata || {};
+    return {
+        data,
+        metadata: {
+            inputTokens: metadata.input_tokens,
+            outputTokens: metadata.output_tokens,
+            reasoning: metadata.reasoning,
+            reasoningTokens: metadata.reasoning_tokens,
+        },
+    };
+}
+// ============================================================================
+// Public SDK Functions
+// ============================================================================
+/**
+ * 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).
+ * @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 async function extract(input, options, context) {
+    // Perform client-side validation specific to the `extract` operation.
+    if (!input) {
+        throw new Error('The `input` parameter is required for `extract`.');
+    }
+    if (!options.schema || typeof options.schema !== 'object') {
+        throw new Error('The `schema` parameter must be a valid JSONSchema object for `extract`.');
+    }
+    if (!options.prompt || typeof options.prompt !== 'string') {
+        throw new Error('The `prompt` parameter must be a non-empty string for `extract`.');
+    }
+    // Delegate to the shared internal execution logic.
+    return _executeAIOperation('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).
+ * @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 async function summarize(input, options, context) {
+    // Perform client-side validation specific to the `summarize` operation.
+    if (!input) {
+        throw new Error('The `input` parameter is required for `summarize`.');
+    }
+    if (!options.prompt || typeof options.prompt !== 'string') {
+        throw new Error('The `prompt` parameter must be a non-empty string for `summarize`.');
+    }
+    // Delegate to the shared internal execution logic.
+    return _executeAIOperation('summarize', input, options, context);
+}
+/**
+ * Transcribes audio or video from a document handle using the Simple AI engine.
+ *
+ * This function internally uses the `extract` operation with a dynamically generated
+ * schema based on the requested options. It supports participant identification,
+ * timestamps, and summarization.
+ *
+ * @param input The audio or video file as a DocumentHandle.
+ * @param options The configuration for the transcription operation.
+ * @param context The execution context provided by the host.
+ * @returns A promise that resolves to an `AIExecutionResult` with structured transcription data.
+ * @throws Will throw an error if the operation fails or inputs are invalid.
+ *
+ * @example
+ * // Basic transcript
+ * const result = await transcribe(audioHandle, { includeTranscript: true }, context)
+ * // Returns: { language: "en", transcript: "..." }
+ *
+ * @example
+ * // Transcript with participant identification
+ * const result = await transcribe(audioHandle, {
+ *   includeTranscript: true,
+ *   participants: ['Customer', 'Support Agent']
+ * }, context)
+ * // Returns: { language: "en", transcript: "Customer: Hello...\nSupport Agent: Hi...", participants: [...] }
+ *
+ * @example
+ * // Summary with auto-detected participants
+ * const result = await transcribe(videoHandle, {
+ *   summarize: true,
+ *   participants: true
+ * }, context)
+ * // Returns: { language: "en", summary: "...", participants: ["Participant 1", "Participant 2"] }
+ */
+export async function transcribe(input, options, context) {
+    // Validation
+    if (!input || typeof input !== 'object' || !input.file_hash) {
+        throw new Error('The `input` parameter must be a valid DocumentHandle for `transcribe`.');
+    }
+    const { includeTimestamps = false, includeTranscript = false, participants, summarize = false, } = options;
+    if (!includeTranscript && !summarize) {
+        throw new Error('At least one of `includeTranscript` or `summarize` must be true for `transcribe`.');
+    }
+    // Validate mime type is audio or video
+    const mimeType = input.mime_type?.toLowerCase() || '';
+    if (!mimeType.startsWith('audio/') && !mimeType.startsWith('video/')) {
+        throw new Error('The input file must be an audio or video file for `transcribe`.');
+    }
+    // Build the dynamic schema based on user options
+    const schemaProperties = {
+        language: {
+            description: 'The detected language of the audio (ISO 639-1 code, e.g., "en", "es")',
+            type: 'string',
+        },
+    };
+    const requiredFields = ['language'];
+    if (includeTranscript) {
+        let transcriptDesc = 'The full transcript of the audio';
+        if (participants) {
+            if (includeTimestamps) {
+                transcriptDesc = 'The full transcript with participant labels and timestamps. Format: [MM:SS] Participant Name: text';
+            }
+            else {
+                transcriptDesc = 'The full transcript with participant labels. Format: Participant Name: text';
+            }
+        }
+        else if (includeTimestamps) {
+            transcriptDesc = 'The full transcript with timestamps. Format: [MM:SS] text';
+        }
+        schemaProperties.transcript = {
+            description: transcriptDesc,
+            type: 'string',
+        };
+        requiredFields.push('transcript');
+    }
+    if (summarize) {
+        schemaProperties.summary = {
+            description: participants
+                ? 'A concise summary of the audio content, including key points from each participant'
+                : 'A concise summary of the audio content',
+            type: 'string',
+        };
+        requiredFields.push('summary');
+    }
+    // Add participants array to schema if participant identification is requested
+    if (participants) {
+        schemaProperties.participants = {
+            description: 'List of identified participants in the audio',
+            items: { type: 'string' },
+            type: 'array',
+        };
+        requiredFields.push('participants');
+    }
+    const schema = {
+        properties: schemaProperties,
+        required: requiredFields,
+        type: 'object',
+    };
+    // Build the prompt
+    let prompt = 'Analyze this audio/video file and provide:\n';
+    if (includeTranscript) {
+        if (participants) {
+            if (Array.isArray(participants)) {
+                prompt += `- A complete transcript identifying these participants: ${participants.join(', ')}. `;
+            }
+            else {
+                prompt += '- A complete transcript with participant identification (label participants as Participant 1, Participant 2, etc.). ';
+            }
+            if (includeTimestamps) {
+                prompt += 'Include timestamps in [MM:SS] format before each participant segment.\n';
+            }
+            else {
+                prompt += 'Format each line as "Participant Name: text".\n';
+            }
+        }
+        else {
+            prompt += includeTimestamps
+                ? '- A complete transcript with timestamps in [MM:SS] format before each segment\n'
+                : '- A complete transcript of all spoken content\n';
+        }
+    }
+    if (summarize) {
+        prompt += participants
+            ? '- A concise summary highlighting key points from each participant\n'
+            : '- A concise summary of the main points and key information\n';
+    }
+    if (participants) {
+        if (Array.isArray(participants)) {
+            prompt += `- Identify and distinguish between these participants: ${participants.join(', ')}\n`;
+        }
+        else {
+            prompt += '- Identify and list all distinct participants in the audio\n';
+        }
+    }
+    prompt += '- The detected language code (ISO 639-1 format)\n';
+    // Delegate to extract with our generated schema
+    return extract(input, {
+        ...options,
+        prompt,
+        schema,
+    }, context);
+}

package/dist/build.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs/promises')
+const os = require('node:os')
+const path = require('node:path')
+const esbuild = require('esbuild')
+
+async function main() {
+  // eslint-disable-next-line node/prefer-global/process
+  const [entryPoint, outFile] = process.argv.slice(2)
+
+  if (!entryPoint || !outFile) {
+    console.error('Usage: simple-sdk-build <entryPoint> <outFile>')
+    // eslint-disable-next-line node/prefer-global/process
+    process.exit(1)
+  }
+
+  const entryPointAbs = path.resolve(entryPoint)
+  const outFileAbs = path.resolve(outFile)
+
+  /**
+   * This is a local esbuild plugin to solve our specific problem.
+   * It intercepts module resolution. When it sees a file inside the
+   * @simple/sdk package trying to import the exact relative path './host',
+   * it redirects the bundler to our worker-override.js script instead.
+   * This is the robust way to swap implementations at build time.
+   */
+  const simpleSdkHostAliasPlugin = {
+    name: 'simple-sdk-host-alias',
+    setup(build) {
+      // Find the absolute path to the SDK's dist directory.
+      // We need this to check if an import is coming from our SDK.
+      const sdkDistPath = path.dirname(require.resolve('@simple/sdk'))
+
+      // The 'onResolve' hook intercepts module lookups.
+      build.onResolve({ filter: /^\.\/host$/ }, (args) => {
+        // `filter` matches the exact import path string: './host'.
+        // `args.importer` is the absolute path of the file doing the import.
+
+        // If the file doing the import is NOT inside our SDK's dist folder,
+        // we ignore it and let esbuild handle it normally.
+        if (!args.importer.startsWith(sdkDistPath)) {
+          return
+        }
+
+        // It's a match! Redirect the import to our override file.
+        const overridePath = path.resolve(__dirname, 'worker-override.js')
+        return { path: overridePath }
+      })
+    },
+  }
+
+  // We will now create a temporary entry file that esbuild will use.
+  // This allows us to bundle and minify everything in a single, efficient step.
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'simple-sdk-build-'))
+  const tempEntryFile = path.join(tempDir, 'entry.js')
+
+  try {
+    /**
+     * This is the content of our new, dynamic entry point. It controls the
+     * precise order of operations.
+     */
+    const entryPointContent = `
+      // This is the only module we need to define the main handler.
+      // The user's code will be bundled into it via the dynamic import.
+
+      export default async function() {
+        const channel = { promise: null };
+
+        try {
+          // STEP 1: Create the promise channel and place it on the global scope.
+          globalThis.__SIMPLE_PROMISE_CHANNEL__ = channel;
+
+          // STEP 2: Dynamically import the user's application. This is a critical change.
+          // The 'import()' statement executes the user's top-level code, which will
+          // call simple.Handle and populate the channel.promise.
+          await import('${entryPointAbs.replace(/\\/g, '/')}');
+
+          // STEP 3: Now that the user's code has run, check the channel for the promise.
+          if (channel.promise) {
+            // Await the promise to get the final result of the async handler.
+            return await channel.promise;
+          } else {
+            console.warn('SDK build warning: simple.Handle was not called by the user application.');
+            return undefined;
+          }
+        } finally {
+          // STEP 4: Always clean up the global scope to maintain the sandbox.
+          delete globalThis.__SIMPLE_PROMISE_CHANNEL__;
+        }
+      };
+    `
+
+    await fs.writeFile(tempEntryFile, entryPointContent)
+
+    // Read the contents of the temp file to pass via stdin.
+    const tempFileContents = await fs.readFile(tempEntryFile, 'utf8')
+
+    // --- STAGE 1: Build the user's application and the wrapper together ---
+    const appBundleResult = await esbuild.build({
+      bundle: true,
+      define: {
+        __ASYNC_BUILD__: 'true',
+        __IS_WORKER_BUILD__: 'true',
+      },
+      format: 'iife',
+      globalName: '__SIMPLE_MAIN_HANDLER__', // Assign the IIFE result to a global
+      minify: true, // Minify the entire bundle
+      plugins: [simpleSdkHostAliasPlugin],
+      stdin: {
+        contents: tempFileContents,
+        // eslint-disable-next-line node/prefer-global/process
+        resolveDir: process.cwd(),
+        sourcefile: 'simple-sdk-virtual-entry.js', // Provide a fake filename for better error messages
+      },
+      write: false,
+    })
+
+    // The result is a minified IIFE that returns our async handler function.
+    const userScriptBundle = appBundleResult.outputFiles[0].text
+
+    // The final script for the worker just needs to execute this handler.
+    // The IIFE returns an object with a `default` property containing our async function.
+    const finalWorkerScript = `
+      ${userScriptBundle}
+      return __SIMPLE_MAIN_HANDLER__.default();
+    `
+
+    // --- STAGE 2: Build the final WASM loader with the correctly-built user script injected ---
+    await esbuild.build({
+      bundle: true,
+      define: {
+        __ASYNC_BUILD__: 'true',
+        // Inject the minified, wrapped script.
+        __USER_SCRIPT_BUNDLE__: JSON.stringify(finalWorkerScript),
+      },
+      minify: true,
+      outfile: outFileAbs,
+      stdin: {
+        contents: `import simple from '@simple/sdk'; simple.Handle(() => {});`,
+        // eslint-disable-next-line node/prefer-global/process
+        resolveDir: process.cwd(),
+      },
+    })
+
+    console.log(`✅ Simple SDK async build successful! Output: ${outFile}`)
+  }
+  catch (error) {
+    console.error('❌ Simple SDK async build failed:')
+    console.error(error)
+
+    // eslint-disable-next-line node/prefer-global/process
+    process.exit(1)
+  }
+  finally {
+    // Clean up the temporary directory
+    await fs.rm(tempDir, { force: true, recursive: true })
+  }
+}
+
+main()