content-moderation-sdk 0.0.1 → 0.1.1

package/src/mistral.ts

@@ -0,0 +1,124 @@
+import { ModerationAdapterError, ModerationValidationError } from "./errors.js";
+import { requestJson } from "./http.js";
+import type {
+  ModerationAdapter,
+  ModerationAdapterResult,
+  ModerationCategoryAssessment,
+} from "./types.js";
+import { normalizeHttpEndpoint } from "./utils.js";
+
+export type MistralModeration = {
+  categories: Record<string, boolean>;
+  category_scores: Record<string, number>;
+};
+
+export type MistralModerationResponse = {
+  id: string;
+  model: string;
+  results: MistralModeration[];
+};
+
+export type MistralOptions = {
+  apiKey: string;
+  model?: string;
+  baseUrl?: string;
+  headers?: Readonly<Record<string, string>>;
+  fetch?: typeof fetch;
+};
+
+export type MistralAdapter = ModerationAdapter<
+  "mistral",
+  { baseUrl: string; model: string },
+  MistralModerationResponse
+>;
+
+export function mistral(options: MistralOptions): MistralAdapter {
+  if (typeof options.apiKey !== "string" || options.apiKey.trim().length === 0) {
+    throw new ModerationValidationError("Mistral apiKey is required.");
+  }
+
+  const model = options.model ?? "mistral-moderation-latest";
+  if (typeof model !== "string" || model.trim().length === 0) {
+    throw new ModerationValidationError("Mistral model must be a non-empty string.");
+  }
+  const baseUrl = normalizeHttpEndpoint(
+    options.baseUrl ?? "https://api.mistral.ai/v1",
+    "Mistral baseUrl",
+  );
+  const fetcher = options.fetch ?? fetch;
+
+  return {
+    name: "mistral",
+    capabilities: {
+      text: true,
+      image: false,
+      conversation: "native",
+    },
+    raw: { baseUrl, model },
+    async moderate(input, context) {
+      if (input.type === "image") {
+        throw new ModerationValidationError("Mistral moderation does not support image input.");
+      }
+
+      const conversation = input.type === "conversation";
+      const body = await requestJson<MistralModerationResponse>({
+        adapter: "mistral",
+        provider: "Mistral",
+        fetcher,
+        url: `${baseUrl}/${conversation ? "chat/moderations" : "moderations"}`,
+        init: {
+          method: "POST",
+          signal: context.signal,
+          headers: {
+            Authorization: `Bearer ${options.apiKey}`,
+            "Content-Type": "application/json",
+            ...options.headers,
+          },
+          body: JSON.stringify({
+            model,
+            input: conversation ? input.messages : input.text,
+          }),
+        },
+      });
+
+      const result = body.results?.[0];
+      if (!result || !result.categories || !result.category_scores) {
+        throw new ModerationAdapterError("Mistral returned an invalid moderation response.", {
+          adapter: "mistral",
+          code: "invalid_response",
+          details: body,
+        });
+      }
+
+      const categories = toCategoryAssessments(result);
+      return {
+        adapter: "mistral",
+        id: body.id,
+        model: body.model,
+        flagged: Object.values(result.categories).some(Boolean),
+        categories,
+        raw: body,
+      } satisfies ModerationAdapterResult<"mistral", MistralModerationResponse>;
+    },
+  };
+}
+
+function toCategoryAssessments(
+  result: MistralModeration,
+): Readonly<Record<string, ModerationCategoryAssessment>> {
+  const names = new Set([
+    ...Object.keys(result.categories ?? {}),
+    ...Object.keys(result.category_scores ?? {}),
+  ]);
+  return Object.fromEntries(
+    [...names].map((name) => [
+      name,
+      {
+        flagged: result.categories?.[name] ?? null,
+        ...(typeof result.category_scores?.[name] === "number"
+          ? { score: result.category_scores[name] }
+          : {}),
+      },
+    ]),
+  );
+}

package/src/openai.ts

@@ -0,0 +1,162 @@
+import { ModerationAdapterError, ModerationValidationError } from "./errors.js";
+import { requestJson } from "./http.js";
+import type {
+  ModerationAdapter,
+  ModerationAdapterResult,
+  ModerationCategoryAssessment,
+  ModerationImageSource,
+} from "./types.js";
+import { imageSourceToDataUrl, normalizeHttpEndpoint } from "./utils.js";
+
+export type OpenAIModerationModel =
+  | "omni-moderation-latest"
+  | "omni-moderation-2024-09-26"
+  | "text-moderation-latest"
+  | "text-moderation-stable"
+  | (string & {});
+
+export type OpenAIModeration = {
+  flagged: boolean;
+  categories: Record<string, boolean | null>;
+  category_scores: Record<string, number>;
+  category_applied_input_types?: Record<string, ("text" | "image")[]>;
+};
+
+export type OpenAIModerationResponse = {
+  id: string;
+  model: string;
+  results: OpenAIModeration[];
+};
+
+export type OpenAIOptions = {
+  apiKey: string;
+  model?: OpenAIModerationModel;
+  baseUrl?: string;
+  organization?: string;
+  project?: string;
+  headers?: Readonly<Record<string, string>>;
+  fetch?: typeof fetch;
+};
+
+export type OpenAIAdapter = ModerationAdapter<
+  "openai",
+  { baseUrl: string; model: OpenAIModerationModel },
+  OpenAIModerationResponse
+>;
+
+export function openai(options: OpenAIOptions): OpenAIAdapter {
+  assertCredential(options.apiKey);
+  const model = options.model ?? "omni-moderation-latest";
+  if (typeof model !== "string" || model.trim().length === 0) {
+    throw new ModerationValidationError("OpenAI model must be a non-empty string.");
+  }
+  const baseUrl = normalizeHttpEndpoint(
+    options.baseUrl ?? "https://api.openai.com/v1",
+    "OpenAI baseUrl",
+  );
+  const fetcher = options.fetch ?? fetch;
+  const supportsImages = model !== "text-moderation-latest" && model !== "text-moderation-stable";
+
+  return {
+    name: "openai",
+    capabilities: {
+      text: true,
+      image: supportsImages,
+      conversation: "flattened",
+    },
+    raw: { baseUrl, model },
+    async moderate(input, context) {
+      const body = await requestJson<OpenAIModerationResponse>({
+        adapter: "openai",
+        provider: "OpenAI",
+        fetcher,
+        url: `${baseUrl}/moderations`,
+        init: {
+          method: "POST",
+          signal: context.signal,
+          headers: {
+            Authorization: `Bearer ${options.apiKey}`,
+            "Content-Type": "application/json",
+            ...(options.organization ? { "OpenAI-Organization": options.organization } : {}),
+            ...(options.project ? { "OpenAI-Project": options.project } : {}),
+            ...options.headers,
+          },
+          body: JSON.stringify({
+            model,
+            input: await toOpenAIInput(input),
+          }),
+        },
+      });
+
+      const result = body.results?.[0];
+      if (!result || typeof result.flagged !== "boolean") {
+        throw new ModerationAdapterError("OpenAI returned an invalid moderation response.", {
+          adapter: "openai",
+          code: "invalid_response",
+          details: body,
+        });
+      }
+
+      return {
+        adapter: "openai",
+        id: body.id,
+        model: body.model,
+        flagged: result.flagged,
+        categories: toCategoryAssessments(result),
+        raw: body,
+      } satisfies ModerationAdapterResult<"openai", OpenAIModerationResponse>;
+    },
+  };
+}
+
+async function toOpenAIInput(input: Parameters<OpenAIAdapter["moderate"]>[0]) {
+  if (input.type === "text") return input.text;
+  if (input.type === "conversation") {
+    throw new ModerationValidationError(
+      "OpenAI receives conversations through the client's flattened text path.",
+    );
+  }
+
+  return [
+    {
+      type: "image_url",
+      image_url: {
+        url: await toImageUrl(input.source),
+      },
+    },
+  ];
+}
+
+async function toImageUrl(source: ModerationImageSource): Promise<string> {
+  if (source.type === "url") return source.url;
+  return imageSourceToDataUrl(source);
+}
+
+function toCategoryAssessments(
+  result: OpenAIModeration,
+): Readonly<Record<string, ModerationCategoryAssessment>> {
+  const names = new Set([
+    ...Object.keys(result.categories ?? {}),
+    ...Object.keys(result.category_scores ?? {}),
+  ]);
+  return Object.fromEntries(
+    [...names].map((name) => [
+      name,
+      {
+        flagged: result.categories?.[name] ?? null,
+        ...(typeof result.category_scores?.[name] === "number"
+          ? { score: result.category_scores[name] }
+          : {}),
+        ...(result.category_applied_input_types?.[name]
+          ? { inputTypes: result.category_applied_input_types[name] }
+          : {}),
+      },
+    ]),
+  );
+}
+
+function assertCredential(apiKey: string): void {
+  if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
+    throw new ModerationValidationError("OpenAI apiKey is required.");
+  }
+}

package/src/testing.ts

@@ -0,0 +1,85 @@
+import type {
+  MaybePromise,
+  ModerationAdapter,
+  ModerationAdapterCapabilities,
+  ModerationAdapterContext,
+  ModerationAdapterResult,
+  ModerationInput,
+} from "./types.js";
+
+const ALL_CAPABILITIES: ModerationAdapterCapabilities = {
+  text: true,
+  image: true,
+  conversation: "native",
+};
+
+export type MemoryModerationRequest<Raw = unknown> = {
+  input: ModerationInput;
+  context: ModerationAdapterContext;
+  result: ModerationAdapterResult<string, Raw>;
+};
+
+export type MemoryAdapterOptions<Name extends string, Raw = unknown> = {
+  name?: Name;
+  capabilities?: ModerationAdapterCapabilities;
+  handler?: (
+    input: ModerationInput,
+    context: ModerationAdapterContext,
+  ) => MaybePromise<ModerationAdapterResult<Name, Raw>>;
+};
+
+export type MemoryAdapter<Name extends string = "memory", Raw = unknown> = ModerationAdapter<
+  Name,
+  {
+    requests: MemoryModerationRequest<Raw>[];
+    clear(): void;
+  },
+  Raw
+>;
+
+export function memoryAdapter<const Name extends string = "memory", Raw = unknown>(
+  options: MemoryAdapterOptions<Name, Raw> = {},
+): MemoryAdapter<Name, Raw> {
+  const name = (options.name ?? "memory") as Name;
+  const requests: MemoryModerationRequest<Raw>[] = [];
+
+  return {
+    name,
+    capabilities: options.capabilities ?? ALL_CAPABILITIES,
+    raw: {
+      requests,
+      clear() {
+        requests.length = 0;
+      },
+    },
+    async moderate(input, context) {
+      const result = options.handler
+        ? await options.handler(input, context)
+        : ({
+            adapter: name,
+            flagged: false,
+            categories: {},
+          } as ModerationAdapterResult<Name, Raw>);
+      requests.push({
+        input,
+        context,
+        result: result as ModerationAdapterResult<string, Raw>,
+      });
+      return result;
+    },
+  };
+}
+
+export function failingAdapter<const Name extends string>(
+  name: Name,
+  error: Error = new Error("Moderation adapter failed."),
+  capabilities: ModerationAdapterCapabilities = ALL_CAPABILITIES,
+): ModerationAdapter<Name> {
+  return {
+    name,
+    capabilities,
+    moderate() {
+      throw error;
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,241 @@
+import type { ModerationAdapterError, ModerationSdkError } from "./errors.js";
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type ModerationInputType = "text" | "image" | "conversation";
+
+export type ModerationTextInput = {
+  type: "text";
+  text: string;
+};
+
+export type ModerationImageSource =
+  | {
+      type: "url";
+      url: string;
+    }
+  | {
+      type: "base64";
+      data: string;
+      mediaType: string;
+    }
+  | {
+      type: "bytes";
+      data: Uint8Array | ArrayBuffer | Blob;
+      mediaType: string;
+    };
+
+export type ModerationImageInput = {
+  type: "image";
+  source: ModerationImageSource;
+};
+
+export type ModerationMessageRole = "system" | "user" | "assistant" | "tool";
+
+export type ModerationMessage = {
+  role: ModerationMessageRole;
+  content: string;
+};
+
+export type ModerationConversationInput = {
+  type: "conversation";
+  messages: readonly ModerationMessage[];
+};
+
+export type ModerationInput =
+  | ModerationTextInput
+  | ModerationImageInput
+  | ModerationConversationInput;
+
+export type ModerationProcessingMode = "native" | "flattened";
+
+export type ModerationCategoryAssessment = {
+  flagged: boolean | null;
+  score?: number;
+  severity?: {
+    value: number;
+    max: number;
+  };
+  inputTypes?: readonly ("text" | "image")[];
+};
+
+export type ModerationAdapterResult<Name extends string = string, Raw = unknown> = {
+  adapter: Name;
+  flagged: boolean;
+  categories: Readonly<Record<string, ModerationCategoryAssessment>>;
+  id?: string;
+  model?: string;
+  raw?: Raw;
+};
+
+export type ModerationResult<Name extends string = string, Raw = unknown> = ModerationAdapterResult<
+  Name,
+  Raw
+> & {
+  inputType: ModerationInputType;
+  mode: ModerationProcessingMode;
+};
+
+export type ModerationAdapterCapabilities = {
+  text: boolean;
+  image: boolean;
+  conversation: "native" | "flattened" | "unsupported";
+};
+
+export type ModerationAdapterValidationContext = {
+  adapter: string;
+  inputType: ModerationInputType;
+  mode: ModerationProcessingMode;
+};
+
+export type ModerationAdapterContext = ModerationAdapterValidationContext & {
+  attempt: number;
+  signal?: AbortSignal;
+  metadata?: Readonly<Record<string, unknown>>;
+};
+
+export type ModerationAdapter<
+  Name extends string = string,
+  RawClient = unknown,
+  RawResult = unknown,
+> = {
+  readonly name: Name;
+  readonly capabilities: ModerationAdapterCapabilities;
+  readonly raw?: RawClient;
+  validate?(
+    input: ModerationInput,
+    context: ModerationAdapterValidationContext,
+  ): MaybePromise<void>;
+  moderate(
+    input: ModerationInput,
+    context: ModerationAdapterContext,
+  ): MaybePromise<ModerationAdapterResult<Name, RawResult>>;
+};
+
+export type ModerationRetryConfig = {
+  maxAttempts?: number;
+  delay?: (attempt: number, error: ModerationAdapterError) => number;
+  shouldRetry?: (error: ModerationAdapterError, attempt: number) => boolean;
+};
+
+export type ModerationFallbackConfig<Name extends string = string> = {
+  adapters: readonly Name[];
+  shouldFallback?: (error: ModerationAdapterError, nextAdapter: Name) => MaybePromise<boolean>;
+};
+
+export type ModerationOptions<Name extends string = string> = {
+  adapter?: Name;
+  fallback?: ModerationFallbackConfig<Name>;
+  retry?: ModerationRetryConfig;
+  signal?: AbortSignal;
+  metadata?: Readonly<Record<string, unknown>>;
+};
+
+export type ModerationHookEvent = {
+  adapter: string;
+  input: ModerationInput;
+  inputType: ModerationInputType;
+  mode: ModerationProcessingMode;
+  attempt: number;
+  metadata?: Readonly<Record<string, unknown>>;
+};
+
+export type ModerationAfterEvent = ModerationHookEvent & {
+  result: ModerationResult;
+};
+
+export type ModerationErrorEvent = ModerationHookEvent & {
+  error: ModerationAdapterError;
+};
+
+export type ModerationHooks = {
+  beforeModerate?: (event: ModerationHookEvent) => MaybePromise<void>;
+  afterModerate?: (event: ModerationAfterEvent) => MaybePromise<void>;
+  onError?: (event: ModerationErrorEvent) => MaybePromise<void>;
+  onRetry?: (
+    event: ModerationErrorEvent & {
+      nextAttempt: number;
+      delayMs: number;
+    },
+  ) => MaybePromise<void>;
+};
+
+export type ModerationClientOptions<
+  TAdapters extends readonly ModerationAdapter[] = readonly ModerationAdapter[],
+> = {
+  adapters: TAdapters;
+  defaultAdapter?: TAdapters[number]["name"];
+  fallback?: ModerationFallbackConfig<TAdapters[number]["name"]>;
+  retry?: ModerationRetryConfig;
+  hooks?: ModerationHooks;
+};
+
+export type ModerationRouteName<Routes extends readonly ModerationAdapter[]> =
+  Routes[number]["name"];
+
+export type ModerationAdapterForName<
+  Routes extends readonly ModerationAdapter[],
+  Name extends ModerationRouteName<Routes>,
+> = Extract<Routes[number], { name: Name }>;
+
+export type ModerationResultForAdapter<TAdapter extends ModerationAdapter> =
+  TAdapter extends ModerationAdapter<infer Name, unknown, infer Raw>
+    ? ModerationResult<Name, Raw>
+    : never;
+
+export type ModerationValidationRoute<Name extends string = string> = {
+  adapter: Name;
+  mode: ModerationProcessingMode;
+};
+
+export type ModerationValidationResult<Name extends string = string> = {
+  adapter: Name;
+  routes: readonly ModerationValidationRoute<Name>[];
+};
+
+export type ModerationItem<Name extends string = string> = {
+  input: ModerationInput;
+  options?: ModerationOptions<Name>;
+};
+
+export type ModerationSettledResult<Result extends ModerationResult = ModerationResult> =
+  | { ok: true; index: number; result: Result }
+  | { ok: false; index: number; error: ModerationSdkError };
+
+export type BoundModerationClient<TAdapter extends ModerationAdapter> = {
+  validate(
+    input: ModerationInput,
+    options?: Omit<ModerationOptions<TAdapter["name"]>, "adapter">,
+  ): Promise<ModerationValidationResult<TAdapter["name"]>>;
+  moderate(
+    input: ModerationInput,
+    options?: Omit<ModerationOptions<TAdapter["name"]>, "adapter">,
+  ): Promise<ModerationResultForAdapter<TAdapter>>;
+  moderateMany(
+    items: readonly ModerationItem<TAdapter["name"]>[],
+    options?: Omit<ModerationOptions<TAdapter["name"]>, "adapter">,
+  ): Promise<readonly ModerationSettledResult<ModerationResultForAdapter<TAdapter>>[]>;
+};
+
+export type ModerationClient<Routes extends readonly ModerationAdapter[]> = {
+  readonly adapters: ReadonlyMap<ModerationRouteName<Routes>, Routes[number]>;
+  readonly defaultAdapter: ModerationRouteName<Routes>;
+  validate(
+    input: ModerationInput,
+    options?: ModerationOptions<ModerationRouteName<Routes>>,
+  ): Promise<ModerationValidationResult<ModerationRouteName<Routes>>>;
+  moderate(
+    input: ModerationInput,
+    options?: ModerationOptions<ModerationRouteName<Routes>>,
+  ): Promise<ModerationResultForAdapter<Routes[number]>>;
+  moderateMany(
+    items: readonly ModerationItem<ModerationRouteName<Routes>>[],
+    options?: ModerationOptions<ModerationRouteName<Routes>>,
+  ): Promise<readonly ModerationSettledResult<ModerationResultForAdapter<Routes[number]>>[]>;
+  adapter<Name extends ModerationRouteName<Routes>>(
+    name: Name,
+  ): ModerationAdapterForName<Routes, Name>;
+  withAdapter<Name extends ModerationRouteName<Routes>>(
+    name: Name,
+  ): BoundModerationClient<ModerationAdapterForName<Routes, Name>>;
+};