@sogni-ai/sogni-client 5.2.0 → 5.3.0

package/src/Chat/index.ts

@@ -34,6 +34,8 @@ import {
 import getUUID from '../lib/getUUID.js';
 import type ProjectsApi from '../Projects/index.js';
 import { mediaInputToInlineDataUri } from '../lib/mediaValidation.js';
+import { workloadAttributionToWireFields } from '../lib/attribution.js';
+import type { WorkloadAttributionInput } from '../types/attribution.js';
 
 const MAX_VISION_IMAGE_COUNT = 20;
 const MAX_VISION_IMAGE_BYTES = 10 * 1024 * 1024;
@@ -510,13 +512,15 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
     const normalizedMessages = await normalizeVisionMessages(params.messages);
     const chatTemplateKwargs =
       params.chat_template_kwargs ?? this.buildChatTemplateKwargs(params.think);
+    const appSource = params.app_source ?? params.appSource ?? this.client.appSource;
+    const attributionHeaders = this.attributionHeaders(appSource, params.attribution, getUUID());
     try {
       return await this.client.rest.post<HostedChatCompletionResult>(
         '/v1/chat/completions',
         {
           model: params.model,
           messages: normalizedMessages,
-          app_source: params.app_source ?? params.appSource ?? this.client.appSource,
+          app_source: appSource,
           max_tokens: params.max_tokens,
           temperature: params.temperature,
           top_p: params.top_p,
@@ -541,7 +545,7 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
           ...(chatTemplateKwargs && { chat_template_kwargs: chatTemplateKwargs }),
           ...(params.response_format && { response_format: params.response_format })
         },
-        { timeoutMs: 300000 }
+        { timeoutMs: 300000, headers: attributionHeaders }
       );
     } catch (error) {
       // Re-throw recognized chat-job error bodies (e.g. subscription
@@ -569,18 +573,22 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
   private async executeHostedTool(
     params: HostedToolExecutionParams
   ): Promise<HostedToolExecutionResult> {
+    const appSource = params.app_source ?? params.appSource ?? this.client.appSource;
     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,
+        app_source: 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 }
+      {
+        timeoutMs: 300000,
+        headers: this.attributionHeaders(appSource, params.attribution, getUUID())
+      }
     );
   }
 
@@ -633,6 +641,7 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
   private async createChatRun(params: StartChatRunParams): Promise<ChatRunRecord> {
     assertChatRunUsesExternalMedia(params);
     const appSource = params.appSource ?? this.client.appSource;
+    const operationId = getUUID();
     const body: Record<string, unknown> = {
       messages: params.messages,
       ...(params.tools ? { tools: params.tools } : {}),
@@ -652,7 +661,10 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
       ...(appSource ? { app_source: appSource } : {}),
       ...(params.runtimeConfig ? { runtime_config: params.runtimeConfig } : {})
     };
-    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...this.attributionHeaders(appSource, params.attribution, operationId)
+    };
     if (params.idempotencyKey) headers['Idempotency-Key'] = params.idempotencyKey;
     const response = await this.chatRunJson<{
       status: string;
@@ -828,7 +840,8 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
       sogni_tool_execution: params.sogni_tool_execution,
       taskProfile: params.taskProfile,
       ...(chatTemplateKwargs && { chat_template_kwargs: chatTemplateKwargs }),
-      ...(params.response_format && { response_format: params.response_format })
+      ...(params.response_format && { response_format: params.response_format }),
+      ...workloadAttributionToWireFields(this.resolveWorkloadAttribution(params.attribution, jobID))
     };
 
     const stream = new ChatStream(jobID);
@@ -891,13 +904,18 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
     const maxRounds = params.maxToolRounds || 5;
     const toolHistory: ToolHistoryEntry[] = [];
     let messages = [...params.messages];
+    const logicalOperation = this.resolveWorkloadAttribution(params.attribution, getUUID());
+    const autoToolChildAttribution = this.createAutoToolChildAttribution(logicalOperation);
 
     for (let round = 0; round < maxRounds; round++) {
       const result = (await this.createSingleCompletion({
         ...params,
         messages,
         stream: false,
-        autoExecuteTools: false
+        autoExecuteTools: false,
+        // The first LLM admission represents the logical auto-tool request.
+        // Later rounds and tool/media work are compute children of that root.
+        attribution: round === 0 ? logicalOperation : autoToolChildAttribution
       })) as ChatCompletionResult;
 
       // If model didn't request tools, return final result
@@ -911,6 +929,7 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
       // Execute tool calls
       const toolResults = await this.tools.executeAll(result.tool_calls, {
         tokenType: params.tokenType,
+        attribution: autoToolChildAttribution,
         onToolCall: params.onToolCall,
         onToolProgress: params.onToolProgress
       });
@@ -942,6 +961,26 @@ class ChatApi extends ApiGroup<ChatApiEvents> {
     throw new Error(`Max tool calling rounds (${maxRounds}) exceeded`);
   }
 
+  /**
+   * Build attribution for compute spawned by one logical auto-tool operation.
+   * Each child receives its own transport operation ID while retaining the
+   * logical operation as its immediate parent.
+   */
+  private createAutoToolChildAttribution(
+    attribution: WorkloadAttributionInput | undefined
+  ): WorkloadAttributionInput | undefined {
+    const logicalOperation = this.resolveWorkloadAttribution(attribution, getUUID());
+    if (!logicalOperation?.operationId) return undefined;
+    const rootOperationId = logicalOperation.rootOperationId ?? logicalOperation.operationId;
+    return {
+      ...logicalOperation,
+      operationScope: 'child',
+      operationId: undefined,
+      rootOperationId,
+      parentOperationId: logicalOperation.operationId
+    };
+  }
+
   private handleJobTokens(data: JobTokensData): void {
     const stream = this.activeStreams.get(data.jobID);
     if (!stream) return;

package/src/Chat/types.ts

@@ -1,4 +1,5 @@
 import type { BillingMode } from '../Projects/types/index.js';
+import type { WorkloadAttributionInput } from '../types/attribution.js';
 
 export interface ToolFunction {
   name: string;
@@ -96,6 +97,8 @@ export interface ChatCompletionParams {
   messages: ChatMessage[];
   /** Optional source label for this request. Defaults to the client appSource when configured. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   max_tokens?: number;
   temperature?: number;
   top_p?: number;
@@ -181,7 +184,7 @@ export interface ChatCompletionParams {
   maxToolRounds?: number;
 }
 
-export interface ChatRequestMessage {
+export interface ChatRequestMessage extends WorkloadAttributionInput {
   jobID: string;
   type: 'llm';
   model: string;
@@ -295,6 +298,8 @@ export interface HostedToolExecutionParams {
   app_source?: string;
   /** camelCase alias for {@link HostedToolExecutionParams.app_source}. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   /** Token type to use for hosted REST billing. */
   token_type?: 'sogni' | 'spark' | 'auto';
   /** camelCase alias for {@link HostedToolExecutionParams.token_type}. */
@@ -457,6 +462,8 @@ export interface StartChatRunParams {
   billingMode?: BillingMode;
   /** Optional source label for attribution. Defaults to the client appSource when configured. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   /** Idempotency key (also accepted via `Idempotency-Key` header). */
   idempotencyKey?: string;
   /**
@@ -647,6 +654,8 @@ export interface ToolExecutionOptions {
   network?: 'fast' | 'relaxed';
   /** Number of media items to generate per tool call. Default: 1. */
   numberOfMedia?: number;
+  /** Optional workload attribution for media projects executed by the tool. */
+  attribution?: WorkloadAttributionInput;
   /** Progress callback fired during media generation. */
   onProgress?: (progress: ToolExecutionProgress) => void;
   /**

package/src/CreativeWorkflows/index.ts

@@ -16,6 +16,7 @@ import {
   StartCreativeWorkflowParams,
   StreamCreativeWorkflowEventsOptions
 } from './types.js';
+import getUUID from '../lib/getUUID.js';
 
 interface CreativeWorkflowEnvelope {
   workflow?: CreativeWorkflowRecord;
@@ -187,7 +188,8 @@ class CreativeWorkflowsApi extends ApiGroup {
     if (mediaReferences !== undefined) body.media_references = mediaReferences;
 
     const headers: Record<string, string> = {
-      'Content-Type': 'application/json'
+      'Content-Type': 'application/json',
+      ...this.attributionHeaders(appSource, params.attribution, getUUID())
     };
     if (idempotencyKey) {
       headers['Idempotency-Key'] = idempotencyKey;
@@ -226,7 +228,10 @@ class CreativeWorkflowsApi extends ApiGroup {
       `/v1/creative-agent/workflows/${encodeURIComponent(workflowId)}/resume`,
       {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: {
+          'Content-Type': 'application/json',
+          ...this.attributionHeaders(appSource, params.attribution, getUUID())
+        },
         body: JSON.stringify(body),
         signal: options.signal
       }
@@ -261,7 +266,10 @@ class CreativeWorkflowsApi extends ApiGroup {
       `/v1/creative-agent/workflows/${encodeURIComponent(workflowId)}/reseed`,
       {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers: {
+          'Content-Type': 'application/json',
+          ...this.attributionHeaders(appSource, params.attribution, getUUID())
+        },
         body: JSON.stringify(body),
         signal: options.signal
       }

package/src/CreativeWorkflows/types.ts

@@ -1,5 +1,6 @@
 import { TokenType } from '../types/token.js';
 import type { BillingMode } from '../Projects/types/index.js';
+import type { WorkloadAttributionInput } from '../types/attribution.js';
 
 export type CreativeWorkflowStatus =
   | 'queued'
@@ -144,6 +145,8 @@ export interface StartCreativeWorkflowParams {
   billingMode?: BillingMode;
   /** Optional source label for attribution. Defaults to the client appSource when configured. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   idempotencyKey?: string;
   /** Durable workflows require uploaded HTTP(S) URLs, not inline data URIs. */
   mediaReferences?: unknown[];
@@ -174,6 +177,8 @@ export interface ResumeCreativeWorkflowParams {
   billingMode?: BillingMode;
   /** Optional source label for attribution. Defaults to the client appSource when configured. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   /** @internal Undocumented compatibility alias. Use tokenType. */
   token_type?: TokenType;
   /** @internal Undocumented compatibility alias. Use billingMode. */
@@ -203,6 +208,8 @@ export interface ReseedCreativeWorkflowParams {
   billingMode?: BillingMode;
   /** Optional source label for attribution. Defaults to the client appSource when configured. */
   appSource?: string;
+  /** Optional workload attribution overriding this client's defaults. */
+  attribution?: WorkloadAttributionInput;
   /** @internal Undocumented compatibility alias. Use seedOverrides. */
   seed_overrides?: Record<string, number>;
   /** @internal Undocumented compatibility alias. Use tokenType. */

package/src/Projects/createJobRequestMessage.ts

@@ -43,6 +43,7 @@ import {
   ModelOptions,
   VideoModelOptions
 } from './types/ModelOptions.js';
+import { workloadAttributionToWireFields } from '../lib/attribution.js';
 
 /**
  * Validate that the provided assets match the workflow requirements.
@@ -735,7 +736,9 @@ function createJobRequestMessage(id: string, params: ProjectParams, options: Mod
     tokenType: params.tokenType,
     billingMode: params.billingMode,
     outputFormat:
-      params.outputFormat || (isAudioParams(params) ? 'mp3' : isVideoParams(params) ? 'mp4' : 'png')
+      params.outputFormat ||
+      (isAudioParams(params) ? 'mp3' : isVideoParams(params) ? 'mp4' : 'png'),
+    ...workloadAttributionToWireFields(params.attribution)
   };
 
   if (params.network) {

package/src/Projects/index.ts

@@ -667,7 +667,8 @@ class ProjectsApi extends ApiGroup<ProjectApiEvents> {
     const modelOptions = await this.getModelOptions(data.modelId);
     const requestParams = {
       ...data,
-      appSource: data.appSource || this.client.appSource
+      appSource: data.appSource || this.client.appSource,
+      attribution: this.resolveWorkloadAttribution(data.attribution, project.id)
     } as ProjectParams;
     const request = createJobRequestMessage(project.id, requestParams, modelOptions);
 

package/src/Projects/types/index.ts

@@ -1,6 +1,7 @@
 import { SupernetType } from '../../ApiClient/WebSocketClient/types.js';
 import { ControlNetParams, VideoControlNetParams } from './ControlNetParams.js';
 import { TokenType } from '../../types/token.js';
+import type { WorkloadAttributionInput } from '../../types/attribution.js';
 
 export interface SupportedModel {
   id: string;
@@ -99,6 +100,11 @@ export interface BaseProjectParams {
    * Optional client app/source label to attach to the project request for server-side attribution.
    */
   appSource?: string;
+  /**
+   * Optional workload attribution for this project. Fields override the
+   * immutable defaults configured on SogniClient.
+   */
+  attribution?: WorkloadAttributionInput;
   /**
    * LoRA IDs to apply, in the order they should be chained.
    *

package/src/index.ts

@@ -176,6 +176,20 @@ import {
   TokenAuthManager
 } from './lib/AuthManager/index.js';
 import { MeData } from './Account/types.js';
+import type {
+  AgentAttributionMetadata,
+  AgentSurface,
+  ConnectionAttribution,
+  ExecutionMode,
+  InteractionKind,
+  OperationLineage,
+  OperationScope,
+  SogniAttributionConfig,
+  WorkloadAttribution,
+  WorkloadAttributionDefaults,
+  WorkloadAttributionInput,
+  WorkloadKind
+} from './types/attribution.js';
 
 export type {
   AudioFormat,
@@ -313,7 +327,19 @@ export type {
   RawProject,
   ToastMessage,
   DataEntity,
-  InputMedia
+  InputMedia,
+  AgentAttributionMetadata,
+  AgentSurface,
+  ConnectionAttribution,
+  ExecutionMode,
+  InteractionKind,
+  OperationLineage,
+  OperationScope,
+  SogniAttributionConfig,
+  WorkloadAttribution,
+  WorkloadAttributionDefaults,
+  WorkloadAttributionInput,
+  WorkloadKind
 };
 
 export {
@@ -346,6 +372,13 @@ export interface SogniClientConfig {
    * The socket server uses this as the default source for project and chat requests from this client.
    */
   appSource?: string;
+  /**
+   * Optional immutable connection and per-workload attribution defaults.
+   *
+   * Individual project, chat, tool, and workflow calls can override workload
+   * fields without mutating other concurrent requests.
+   */
+  attribution?: SogniAttributionConfig;
   /**
    * Initial WebSocket event subscriptions for this connection.
    *
@@ -538,6 +571,7 @@ export class SogniClient {
       socketUrl: socketEndpoint,
       appId: config.appId,
       appSource: config.appSource,
+      attribution: config.attribution,
       socketEventSubscriptions: config.socketEventSubscriptions,
       networkType: network,
       logger,

package/src/lib/RestClient.ts

@@ -8,6 +8,11 @@ interface RestRequestInit extends RequestInit {
   timeoutMs?: number;
 }
 
+interface RestPostOptions {
+  timeoutMs?: number;
+  headers?: Record<string, string>;
+}
+
 class RestClient<E extends EventMap = never> extends TypedEventEmitter<E> {
   readonly baseUrl: string;
   protected _auth: AuthManager;
@@ -120,15 +125,17 @@ class RestClient<E extends EventMap = never> extends TypedEventEmitter<E> {
   post<T = JSONValue>(
     path: string,
     body: Record<string, unknown> = {},
-    options: Pick<RestRequestInit, 'timeoutMs'> = {}
+    options: RestPostOptions = {}
   ): Promise<T> {
+    const { headers = {}, ...requestOptions } = options;
     return this.request<T>(this.formatUrl(path), {
       method: 'POST',
       headers: {
-        'Content-Type': 'application/json'
+        'Content-Type': 'application/json',
+        ...headers
       },
       body: JSON.stringify(body),
-      ...options
+      ...requestOptions
     });
   }
 }