@modelprofile.com/flexharness 1.0.0

package/ts/utils.prompt.ts

@@ -0,0 +1,193 @@
+import { FlexHarnessValidationError } from './errors.js';
+import type {
+  IFlexFilePromptPart,
+  IFlexImagePromptPart,
+  TFlexAgentModelMessage,
+  TFlexAgentPrompt,
+  TFlexPrompt,
+  TFlexPromptPart,
+} from './interfaces.js';
+import { cloneSerializable } from './utils.json.js';
+import { assertJsonSerializable } from './utils.json.js';
+
+export interface INormalizedFlexPrompt {
+  agentPrompt: TFlexAgentPrompt;
+  modelMessage: TFlexAgentModelMessage;
+  parts: TFlexPromptPart[];
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function requireNonEmptyString(value: unknown, path: string): string {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new FlexHarnessValidationError(`${path} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function validateOptionalString(value: unknown, path: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  return requireNonEmptyString(value, path);
+}
+
+function toAgentData(data: string): string | URL {
+  try {
+    const url = new URL(data);
+    if (url.protocol === 'http:' || url.protocol === 'https:') {
+      return url;
+    }
+  } catch {
+    // Plain base64 and data URLs stay strings at the SmartAgent boundary.
+  }
+  return data;
+}
+
+function validatePart(value: unknown, index: number): TFlexPromptPart {
+  const path = `prompt[${index}]`;
+  if (!isPlainObject(value)) {
+    throw new FlexHarnessValidationError(`${path} must be a plain object.`);
+  }
+  if (value.type === 'text') {
+    rejectUnknownKeys(value, ['type', 'text'], path);
+    return {
+      type: 'text',
+      text: requireNonEmptyString(value.text, `${path}.text`),
+    };
+  }
+  if (value.type === 'image') {
+    rejectUnknownKeys(value, ['type', 'data', 'mediaType', 'name'], path);
+    const part: IFlexImagePromptPart = {
+      type: 'image',
+      data: requireNonEmptyString(value.data, `${path}.data`),
+    };
+    const mediaType = validateOptionalString(value.mediaType, `${path}.mediaType`);
+    const name = validateOptionalString(value.name, `${path}.name`);
+    if (mediaType) part.mediaType = mediaType;
+    if (name) part.name = name;
+    return part;
+  }
+  if (value.type === 'file') {
+    rejectUnknownKeys(value, ['type', 'data', 'mediaType', 'name'], path);
+    const part: IFlexFilePromptPart = {
+      type: 'file',
+      data: requireNonEmptyString(value.data, `${path}.data`),
+      mediaType: requireNonEmptyString(value.mediaType, `${path}.mediaType`),
+    };
+    const name = validateOptionalString(value.name, `${path}.name`);
+    if (name) part.name = name;
+    return part;
+  }
+  throw new FlexHarnessValidationError(`${path}.type must be text, image, or file.`);
+}
+
+function rejectUnknownKeys(
+  value: Record<string, unknown>,
+  allowedKeys: string[],
+  path: string,
+): void {
+  const unknownKey = Object.keys(value).find((key) => !allowedKeys.includes(key));
+  if (unknownKey) {
+    throw new FlexHarnessValidationError(`${path}.${unknownKey} is not a supported prompt field.`);
+  }
+}
+
+function toAgentParts(parts: TFlexPromptPart[]): TFlexAgentPrompt {
+  return parts.map((part) => {
+    if (part.type === 'text') {
+      return { type: 'text' as const, text: part.text };
+    }
+    if (part.type === 'image') {
+      return {
+        type: 'image' as const,
+        image: toAgentData(part.data),
+        ...(part.mediaType ? { mediaType: part.mediaType } : {}),
+      };
+    }
+    return {
+      type: 'file' as const,
+      data: toAgentData(part.data),
+      mediaType: part.mediaType,
+      ...(part.name ? { filename: part.name } : {}),
+    };
+  }) as TFlexAgentPrompt;
+}
+
+function toStoredModelParts(parts: TFlexPromptPart[]): TFlexAgentPrompt {
+  return parts.map((part) => {
+    if (part.type === 'text') {
+      return { type: 'text' as const, text: part.text };
+    }
+    if (part.type === 'image') {
+      return {
+        type: 'image' as const,
+        image: part.data,
+        ...(part.mediaType ? { mediaType: part.mediaType } : {}),
+      };
+    }
+    return {
+      type: 'file' as const,
+      data: part.data,
+      mediaType: part.mediaType,
+      ...(part.name ? { filename: part.name } : {}),
+    };
+  }) as TFlexAgentPrompt;
+}
+
+export function normalizeFlexPrompt(prompt: TFlexPrompt): INormalizedFlexPrompt {
+  try {
+    assertJsonSerializable(prompt, '$prompt');
+  } catch (error) {
+    throw new FlexHarnessValidationError('prompt must contain only JSON-safe values.', {
+      cause: error,
+    });
+  }
+  if (typeof prompt === 'string') {
+    if (prompt.length === 0) {
+      throw new FlexHarnessValidationError('prompt must not be empty.');
+    }
+    return {
+      agentPrompt: prompt,
+      modelMessage: { role: 'user', content: prompt },
+      parts: [{ type: 'text', text: prompt }],
+    };
+  }
+  if (!Array.isArray(prompt) || prompt.length === 0) {
+    throw new FlexHarnessValidationError('prompt must be a string or a non-empty array of parts.');
+  }
+  const parts = prompt.map(validatePart);
+  return {
+    agentPrompt: toAgentParts(parts),
+    modelMessage: {
+      role: 'user',
+      content: toStoredModelParts(parts),
+    },
+    parts: cloneSerializable(parts),
+  };
+}
+
+export function hydrateAgentMessages(
+  messages: TFlexAgentModelMessage[],
+): TFlexAgentModelMessage[] {
+  const hydrated = cloneSerializable(messages);
+  for (const message of hydrated) {
+    if (!Array.isArray(message.content)) {
+      continue;
+    }
+    for (const part of message.content) {
+      if (message.role === 'user' && part.type === 'image' && typeof part.image === 'string') {
+        part.image = toAgentData(part.image);
+      } else if (part.type === 'file' && typeof part.data === 'string') {
+        part.data = toAgentData(part.data);
+      }
+    }
+  }
+  return hydrated;
+}