@sogni-ai/sogni-client 5.1.0 → 5.2.0

package/src/Chat/index.ts

@@ -21,6 +21,8 @@ import {
   HostedChatCompletionParams,
   ConfirmChatRunCostParams,
   HostedChatCompletionResult,
+  HostedToolExecutionParams,
+  HostedToolExecutionResult,
   LLMCostEstimation,
   LLMEstimateResponse,
   LLMModelInfo,
@@ -249,6 +251,7 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
    */
   hosted: {
     create: (params: HostedChatCompletionParams) => Promise<HostedChatCompletionResult>;
+    executeTool: (params: HostedToolExecutionParams) => Promise<HostedToolExecutionResult>;
   };
 
   /**
@@ -295,7 +298,8 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
       create: this.createCompletion.bind(this) as any
     };
     this.hosted = {
-      create: this.createHostedCompletion.bind(this)
+      create: this.createHostedCompletion.bind(this),
+      executeTool: this.executeHostedTool.bind(this)
     };
     this.runs = {
       create: this.createChatRun.bind(this),
@@ -531,6 +535,9 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
           task_profile: params.task_profile ?? params.taskProfile,
           media_references: params.media_references ?? params.mediaReferences,
           api_media_references: params.api_media_references ?? params.apiMediaReferences,
+          ...(params.safe_content_filter !== undefined || params.safeContentFilter !== undefined
+            ? { safe_content_filter: params.safe_content_filter ?? params.safeContentFilter }
+            : {}),
           ...(chatTemplateKwargs && { chat_template_kwargs: chatTemplateKwargs }),
           ...(params.response_format && { response_format: params.response_format })
         },
@@ -559,6 +566,24 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
     }
   }
 
+  private async executeHostedTool(
+    params: HostedToolExecutionParams
+  ): Promise<HostedToolExecutionResult> {
+    return this.client.rest.post<HostedToolExecutionResult>(
+      '/v1/creative-agent/tools/execute',
+      {
+        tool: params.tool,
+        arguments: params.arguments,
+        app_source: params.app_source ?? params.appSource ?? this.client.appSource,
+        token_type: params.token_type ?? params.tokenType,
+        ...(params.safe_content_filter !== undefined || params.safeContentFilter !== undefined
+          ? { safe_content_filter: params.safe_content_filter ?? params.safeContentFilter }
+          : {})
+      },
+      { timeoutMs: 300000 }
+    );
+  }
+
   private async chatRunFetch(path: string, options: RequestInit = {}): Promise<Response> {
     const url = new URL(path, this.client.rest.baseUrl).toString();
     const authenticated = await this.client.auth.authenticateRequest(options);
@@ -793,6 +818,9 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
       presence_penalty: params.presence_penalty,
       stop: params.stop,
       tokenType: params.tokenType,
+      ...(params.safeContentFilter !== undefined
+        ? { safeContentFilter: params.safeContentFilter }
+        : {}),
       ...(params.billingMode && { billingMode: params.billingMode }),
       tools: params.tools,
       tool_choice: params.tool_choice,

package/src/Chat/modelRouting.ts

@@ -77,7 +77,9 @@ export const PREFERRED_MODEL_IDS = {
     flux2: 'flux2_dev_fp8',
     chromaFlash: 'chroma-v.46-flash_fp8',
     zTurbo: 'z_image_turbo_bf16',
-    krea2Turbo: 'krea2_turbo_fp8_scaled'
+    krea2Turbo: 'krea2_turbo_fp8_scaled',
+    krea2IdentityEdit: 'krea2_identity_edit_v1_2',
+    darkBeastKrea2IdentityEdit: 'dark_beast_krea2_identity_edit_v1_2'
   },
   video: {
     t2v: 'ltx23-22b-fp8_t2v_distilled',
@@ -180,7 +182,16 @@ const EDIT_IMAGE_MODEL_SELECTORS: Record<string, string> = {
   ),
   'qwen-lightning': 'qwen_image_edit_2511_fp8_lightning',
   qwen: 'qwen_image_edit_2511_fp8',
-  flux2: PREFERRED_MODEL_IDS.image.flux2
+  flux2: PREFERRED_MODEL_IDS.image.flux2,
+  'krea-2-identity-edit': PREFERRED_MODEL_IDS.image.krea2IdentityEdit,
+  'krea2-identity-edit': PREFERRED_MODEL_IDS.image.krea2IdentityEdit,
+  'krea-identity-edit': PREFERRED_MODEL_IDS.image.krea2IdentityEdit,
+  'krea-2-identity-edit-lora': PREFERRED_MODEL_IDS.image.krea2IdentityEdit,
+  'krea-2-identity-edit-lora-v1-2': PREFERRED_MODEL_IDS.image.krea2IdentityEdit,
+  'dark-beast-krea-2-identity-edit': PREFERRED_MODEL_IDS.image.darkBeastKrea2IdentityEdit,
+  'dark-beast-krea2-identity-edit': PREFERRED_MODEL_IDS.image.darkBeastKrea2IdentityEdit,
+  'dark-beast-krea-2-identity-edit-lora': PREFERRED_MODEL_IDS.image.darkBeastKrea2IdentityEdit,
+  'dark-beast-krea-2-identity-edit-lora-v1-2': PREFERRED_MODEL_IDS.image.darkBeastKrea2IdentityEdit
 };
 
 const TEXT_VIDEO_MODEL_SELECTORS: Record<string, string> = {
@@ -383,6 +394,8 @@ export function isEditImageModel(modelId: string): boolean {
   return (
     modelId === PREFERRED_MODEL_IDS.image.gptImage2 ||
     modelId.startsWith('qwen_image_edit_') ||
+    modelId === PREFERRED_MODEL_IDS.image.krea2IdentityEdit ||
+    modelId === PREFERRED_MODEL_IDS.image.darkBeastKrea2IdentityEdit ||
     modelId.startsWith('flux2_') ||
     modelId.includes('kontext')
   );

package/src/Chat/types.ts

@@ -108,6 +108,12 @@ export interface ChatCompletionParams {
   stop?: string | string[];
   /** Token type to use for billing. Defaults to 'sogni'. */
   tokenType?: 'sogni' | 'spark';
+  /**
+   * Whether the caller wants Sogni's safe-content filter applied for this
+   * request context. `false` allows backend routing to adult-capable text LLMs
+   * for prompt expansion when the request itself is text-only.
+   */
+  safeContentFilter?: boolean;
   /**
    * Billing mode for this request. `'subscription'` bills the job against the
    * active subscription entitlement, `'tokens'` forces token billing, and
@@ -192,6 +198,8 @@ export interface ChatRequestMessage {
   presence_penalty?: number;
   stop?: string | string[];
   tokenType?: 'sogni' | 'spark';
+  /** Safe-content filter state forwarded to the socket server. */
+  safeContentFilter?: boolean;
   /** Billing mode read by the socket server (`data.billingMode`) — see {@link ChatCompletionParams.billingMode}. */
   billingMode?: BillingMode;
   tools?: ToolDefinition[];
@@ -270,6 +278,43 @@ export interface HostedChatCompletionResult {
   sogni_tool_results?: Record<string, unknown>[];
 }
 
+export type HostedSynchronousToolName =
+  | 'enhance_prompt'
+  | 'compose_script'
+  | 'compose_lyrics'
+  | 'compose_instrumental'
+  | 'compose_workflow'
+  | 'compose_workflow_template';
+
+export interface HostedToolExecutionParams {
+  /** Synchronous hosted composition/planning tool to execute directly. */
+  tool: HostedSynchronousToolName | string;
+  /** Exact JSON arguments for the selected tool. */
+  arguments: Record<string, unknown>;
+  /** Optional source label for this hosted REST request. Defaults to the client appSource when configured. */
+  app_source?: string;
+  /** camelCase alias for {@link HostedToolExecutionParams.app_source}. */
+  appSource?: string;
+  /** Token type to use for hosted REST billing. */
+  token_type?: 'sogni' | 'spark' | 'auto';
+  /** camelCase alias for {@link HostedToolExecutionParams.token_type}. */
+  tokenType?: 'sogni' | 'spark' | 'auto';
+  /** Public snake_case safe-content filter state. */
+  safe_content_filter?: boolean;
+  /** camelCase alias for {@link HostedToolExecutionParams.safe_content_filter}. */
+  safeContentFilter?: boolean;
+}
+
+export interface HostedToolExecutionResult {
+  status: 'success';
+  data: {
+    toolCallId: string;
+    tool: string;
+    result: Record<string, unknown>;
+    message: string | null;
+  };
+}
+
 export type HostedChatCompletionParams = Omit<
   ChatCompletionParams,
   'stream' | 'autoExecuteTools' | 'onToolCall' | 'onToolProgress' | 'maxToolRounds'
@@ -292,6 +337,10 @@ export type HostedChatCompletionParams = Omit<
   mediaReferences?: unknown[];
   api_media_references?: unknown[];
   apiMediaReferences?: unknown[];
+  /** Public snake_case safe-content filter state. */
+  safe_content_filter?: boolean;
+  /** camelCase alias for {@link HostedChatCompletionParams.safe_content_filter}. */
+  safeContentFilter?: boolean;
 };
 
 /**

package/src/Projects/createJobRequestMessage.ts

@@ -21,7 +21,8 @@ import {
   isComfyModel,
   validateVideoDuration,
   validateSampler,
-  validateScheduler
+  validateScheduler,
+  validateVae
 } from '../lib/validation.js';
 import {
   getVideoWorkflowType,
@@ -420,6 +421,7 @@ function applyImageParams(
     // ComfyUI models use comfySampler/comfyScheduler fields
     keyFrame.comfySampler = validateSampler(params.sampler, options);
     keyFrame.comfyScheduler = validateScheduler(params.scheduler, options);
+    keyFrame.vae = validateVae(params.vae, options);
   } else {
     // Legacy Forge models use scheduler/timeStepSpacing fields
     keyFrame.scheduler = validateSampler(params.sampler, options);

package/src/Projects/index.ts

@@ -287,7 +287,8 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
           workerName: data.workerName,
           positivePrompt: data.positivePrompt,
           negativePrompt: data.negativePrompt,
-          jobIndex: data.jobIndex
+          jobIndex: data.jobIndex,
+          preparation: data.preparation
         });
         return;
       case 'jobStarted': {
@@ -698,7 +699,7 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
       await this.uploadCNImage(project.id, data.controlNet.image);
     }
 
-    // Context images (GPT Image 2 supports up to 16; Flux.2 Dev supports up to 6; Qwen Image Edit Plus supports up to 3; Flux Kontext supports up to 2)
+    // Context images (GPT Image 2 supports up to 16; Flux.2 Dev supports up to 6; Qwen Image Edit supports up to 3; Krea 2 Identity Edit and Flux Kontext support up to 2)
     if (data.contextImages?.length) {
       const maxContextImages = getMaxContextImages(data.modelId);
       if (data.contextImages.length > maxContextImages) {

package/src/Projects/types/ModelOptions.ts

@@ -31,6 +31,7 @@ export interface ImageModelOptions {
   guidance: NumRange;
   scheduler: Options<string>;
   sampler: Options<string>;
+  vae?: Options<string>;
 }
 
 export interface VideoModelOptions {
@@ -99,7 +100,8 @@ export function mapComfyImageTier(tier: ComfyImageTier): ImageModelOptions {
     steps: mapRange(tier.steps),
     guidance: mapRange(tier.guidance),
     scheduler: mapOptions(tier.comfyScheduler, schedulerValueToAlias),
-    sampler: mapOptions(tier.comfySampler, samplerValueToAlias)
+    sampler: mapOptions(tier.comfySampler, samplerValueToAlias),
+    vae: tier.vae ? mapOptions(tier.vae) : undefined
   };
 }
 

package/src/Projects/types/ModelTiersRaw.ts

@@ -10,6 +10,7 @@ export interface ComfyImageTier {
   guidance: NumericDefaults;
   steps: NumericDefaults;
   type: 'image';
+  vae?: StringDefaults;
 }
 
 export function isComfyImageTier(t: ModelTier): t is ComfyImageTier {

package/src/Projects/types/events.ts

@@ -1,5 +1,8 @@
 import { AvailableModel } from './index.js';
 import ErrorData from '../../types/ErrorData.js';
+import type { JobPreparation } from '../../ApiClient/WebSocketClient/events.js';
+
+export type { JobPreparation } from '../../ApiClient/WebSocketClient/events.js';
 
 export interface ProjectEventBase {
   projectId: string;
@@ -32,6 +35,7 @@ export interface JobInitiating extends JobEventBase {
   positivePrompt?: string;
   negativePrompt?: string;
   jobIndex?: number;
+  preparation?: JobPreparation;
 }
 
 export interface JobStarted extends JobEventBase {

package/src/Projects/types/index.ts

@@ -100,17 +100,31 @@ export interface BaseProjectParams {
    */
   appSource?: string;
   /**
-   * Array of LoRA IDs to apply.
-   * Available LoRAs are model-specific. The worker will download the LoRA
-   * if not already present on the persistent volume.
-   * LoRA IDs are resolved to filenames via the worker config API.
-   * Example: ['multiple_angles']
+   * LoRA IDs to apply, in the order they should be chained.
+   *
+   * Which LoRAs are available depends on the model; the Krea 2 family carries
+   * the largest set. Workers download a LoRA on first use, so the first render
+   * with an uncached one takes longer to start.
+   *
+   * Order is significant. The LoRAs are applied in sequence and the same set in
+   * a different order produces a measurably different image, because these
+   * models run fp8-quantized and the patches do not commute.
+   *
+   * Up to 8 per render. IDs are resolved to filenames by the worker.
+   * Example: ['krea2-detail-enhancer', 'krea2-amateur']
    */
   loras?: string[];
   /**
-   * Array of LoRA strengths corresponding to each LoRA in the loras array.
-   * Values should be between 0.0 and 2.0. Defaults to 1.0 if not specified.
-   * Example: [0.9]
+   * Strength for each entry in `loras`, positionally matched. Defaults to 1.0.
+   *
+   * Not restricted to positive values. Most Krea 2 LoRAs are bipolar sliders
+   * where a negative strength applies the inverse effect and 0 does nothing -
+   * Warm Light warms at 2 and cools at -2. Each LoRA has its own valid range
+   * and its author's recommended band; values outside the valid range are
+   * clamped server-side, and pushing past the recommended band usually costs
+   * detail rather than adding effect.
+   *
+   * Example: [3, -2]
    */
   loraStrengths?: number[];
 }
@@ -378,7 +392,8 @@ export interface ImageProjectParams extends BaseProjectParams {
    * Context images for multi-reference image generation.
    * GPT Image 2 supports up to 16 context images.
    * Flux.2 Dev supports up to 6 context images.
-   * Qwen Image Edit Plus supports up to 3 context images.
+   * Qwen Image Edit supports up to 3 context images.
+   * Krea 2 Identity Edit supports up to 2 context images.
    * Flux Kontext supports up to 2 context images.
    */
   contextImages?: InputMedia[];
@@ -392,6 +407,11 @@ export interface ImageProjectParams extends BaseProjectParams {
    * to get the list of available schedulers.
    */
   scheduler?: string;
+  /**
+   * VAE filename, available options depend on the model. Use `sogni.projects.getModelOptions(modelId)`
+   * to get the list of available VAEs.
+   */
+  vae?: string;
   /**
    * Size preset ID to use. You can query available size presets
    * from `sogni.projects.sizePresets(network, modelId)`

package/src/index.ts

@@ -42,7 +42,7 @@ import {
   CostEstimation,
   InputMedia
 } from './Projects/types/index.js';
-import type { ProjectEvent, JobEvent } from './Projects/types/events.js';
+import type { ProjectEvent, JobEvent, JobPreparation } from './Projects/types/events.js';
 import type { RawProject } from './Projects/types/RawProject.js';
 import type { Balances, Reward, TxHistoryEntry } from './Account/types.js';
 import type {
@@ -92,6 +92,9 @@ import {
   HostedChatCompletionChoice,
   HostedChatCompletionMessage,
   HostedCreativeWorkflowReference,
+  HostedSynchronousToolName,
+  HostedToolExecutionParams,
+  HostedToolExecutionResult,
   TextContentPart,
   ImageUrlContentPart,
   TokenUsage as ChatTokenUsage,
@@ -199,6 +202,9 @@ export type {
   HostedChatCompletionParams,
   HostedChatCompletionResult,
   HostedCreativeWorkflowReference,
+  HostedSynchronousToolName,
+  HostedToolExecutionParams,
+  HostedToolExecutionResult,
   CreativeWorkflowArtifact,
   CreativeWorkflowEvent,
   CreativeWorkflowRecord,
@@ -303,6 +309,7 @@ export type {
   CostEstimation,
   ProjectEvent,
   JobEvent,
+  JobPreparation,
   RawProject,
   ToastMessage,
   DataEntity,

package/src/lib/validation.ts

@@ -12,28 +12,37 @@ const EXTENDED_IMAGE_SIZE_MODEL_IDS = new Set([
   'flux2_dev_fp8'
 ]);
 
+const KREA_IDENTITY_EDIT_MODEL_IDS = new Set([
+  'krea2_identity_edit_v1_2',
+  'dark_beast_krea2_identity_edit_v1_2'
+]);
+
 interface ImageSizeValidationOptions {
   modelId?: string;
   propertyName?: string;
 }
 
-function getMaxCustomImageSize(modelId?: string): number {
+function getCustomImageSizeBounds(modelId?: string): { min: number; max: number } {
+  if (modelId && KREA_IDENTITY_EDIT_MODEL_IDS.has(modelId)) {
+    return { min: 512, max: 2048 };
+  }
   if (modelId === 'gpt-image-2') {
-    return 3840;
+    return { min: 256, max: 3840 };
   }
   if (modelId && EXTENDED_IMAGE_SIZE_MODEL_IDS.has(modelId)) {
-    return 2560;
+    return { min: 256, max: 2560 };
   }
-  return 2048;
+  return { min: 256, max: 2048 };
 }
 
 export function validateCustomImageSize(
   value: any,
   { modelId, propertyName = 'Width and height' }: ImageSizeValidationOptions = {}
 ): number {
+  const bounds = getCustomImageSizeBounds(modelId);
   return validateNumber(value, {
-    min: 256,
-    max: getMaxCustomImageSize(modelId),
+    min: bounds.min,
+    max: bounds.max,
     propertyName
   });
 }
@@ -106,7 +115,16 @@ export function validateTeacacheThreshold(value?: number): number | undefined {
 }
 
 export function isComfyModel(modelId: string): boolean {
-  const COMFY_PREFIXES = ['z_image_', 'krea2_', 'qwen_image_', 'flux2_', 'wan_', 'ace_step'];
+  const COMFY_PREFIXES = [
+    'z_image_',
+    'dark_beast_z_image_',
+    'krea2_',
+    'dark_beast_krea2_',
+    'qwen_image_',
+    'flux2_',
+    'wan_',
+    'ace_step'
+  ];
   return COMFY_PREFIXES.some((prefix) => modelId.startsWith(prefix));
 }
 
@@ -115,6 +133,7 @@ export function isComfyModel(modelId: string): boolean {
  * - GPT Image 2: 16 images
  * - Flux.2 Dev: 6 images
  * - Qwen Image Edit: 3 images
+ * - Krea 2 Identity Edit: 2 images
  * - Flux Kontext: 2 images
  * - Default: 3 images
  */
@@ -128,6 +147,9 @@ export function getMaxContextImages(modelId: string): number {
   if (modelId.startsWith('qwen_image_')) {
     return 3;
   }
+  if (KREA_IDENTITY_EDIT_MODEL_IDS.has(modelId)) {
+    return 2;
+  }
   if (modelId.includes('kontext')) {
     return 2;
   }
@@ -175,3 +197,18 @@ export function validateScheduler(value: string | undefined, options: ModelOptio
     `Invalid scheduler ${value}. Must be one of "${options.scheduler.allowed.join('", "')}".`
   );
 }
+
+/**
+ * Validate a model-specific VAE value against allowed options.
+ * Returns the validated value unchanged; sogni-socket passes the filename to ComfyUI.
+ */
+export function validateVae(value: string | undefined, options: ModelOptions) {
+  if (!('vae' in options) || !options.vae?.allowed.length || !value) {
+    return null;
+  }
+  return validateOption(
+    value,
+    options.vae.allowed,
+    `Invalid VAE ${value}. Must be one of "${options.vae.allowed.join('", "')}".`
+  );
+}

package/src/version.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED by scripts/generate-version.mjs — do not edit.
 // Source of truth: package.json version.
-export const LIB_VERSION = '5.1.0';
+export const LIB_VERSION = '5.2.0';