@vertesia/client 0.78.0 → 0.79.1

package/src/InteractionResult.example.ts

@@ -0,0 +1,72 @@
+/**
+ * Example usage of InteractionOutput
+ * This file demonstrates the Proxy-based approach where the result acts as both
+ * an array and has convenience methods.
+ */
+
+import { CompletionResult } from '@llumiverse/common';
+import { InteractionOutput } from './InteractionOutput.js';
+
+// Sample data
+const sampleResults: CompletionResult[] = [
+    { type: 'text', value: 'Hello, ' },
+    { type: 'text', value: 'World!' },
+    { type: 'json', value: { name: 'Alice', age: 30 } },
+    { type: 'json', value: { title: 'Engineer', level: 'Senior' } },
+    { type: 'image', value: 'data:image/png;base64,iVBORw0K...' }
+];
+
+// Example 1: Using InteractionOutput.from() (Proxy approach - RECOMMENDED)
+console.log('=== Example 1: Proxy Approach ===');
+interface Person { name: string; age: number; }
+const output = InteractionOutput.from<Person>(sampleResults);
+
+// Works as an array
+console.log('Array length:', output.length);           // 5
+console.log('First item:', output[0]);                 // { type: 'text', value: 'Hello, ' }
+console.log('Types:', output.map(r => r.type));        // ['text', 'text', 'json', 'json', 'image']
+
+// Has convenience methods
+console.log('All text:', output.text);                 // 'Hello, World!'
+console.log('First object:', output.object());         // { name: 'Alice', age: 30 } (typed as Person)
+console.log('All objects:', output.objects());         // [{ name: 'Alice', age: 30 }, { title: 'Engineer', level: 'Senior' }]
+console.log('First image:', output.image);             // 'data:image/png;base64,iVBORw0K...'
+
+// Override type for specific objects
+interface Job { title: string; level: string; }
+console.log('Second object:', output.objectAt<Job>(1)); // { title: 'Engineer', level: 'Senior' } (typed as Job)
+
+// Example 2: Using InteractionOutput class directly
+console.log('\n=== Example 2: Class Approach ===');
+const wrapper = new InteractionOutput<Person>(sampleResults);
+
+// Access through wrapper properties (no array access)
+console.log('All text:', wrapper.text);
+console.log('Raw results:', wrapper.results);          // Original array
+console.log('First object:', wrapper.object());
+
+// Example 3: Type safety demonstration
+console.log('\n=== Example 3: Type Safety ===');
+
+interface Contract { title: string; parties: string[]; }
+const contractResults: CompletionResult[] = [
+    { type: 'json', value: { title: 'Sales Agreement', parties: ['Alice', 'Bob'] } }
+];
+
+const contractOutput = InteractionOutput.from<Contract>(contractResults);
+const contract = contractOutput.object(); // TypeScript knows this is Contract
+console.log('Contract title:', contract.title);
+console.log('Parties:', contract.parties.join(', '));
+
+// Example 4: Mixed content
+console.log('\n=== Example 4: Mixed Content ===');
+const mixedResults: CompletionResult[] = [
+    { type: 'text', value: 'Analysis complete. Results: ' },
+    { type: 'json', value: { score: 0.95, confidence: 'high' } },
+    { type: 'text', value: '\nThank you!' }
+];
+
+const mixed = InteractionOutput.from(mixedResults);
+console.log('Full text:', mixed.text);                 // 'Analysis complete. Results: \nThank you!'
+console.log('Analysis:', mixed.object());              // { score: 0.95, confidence: 'high' }
+console.log('Text parts:', mixed.texts);               // ['Analysis complete. Results: ', '\nThank you!']

package/src/InteractionsApi.ts

@@ -1,7 +1,13 @@
 import { ApiTopic, ClientBase, ServerError } from "@vertesia/api-fetch-client";
-import { AsyncExecutionPayload, ComputeInteractionFacetPayload, ExecutionRun, GenerateInteractionPayload, GenerateTestDataPayload, ImprovePromptPayload, Interaction, InteractionCreatePayload, InteractionEndpoint, InteractionEndpointQuery, InteractionExecutionPayload, InteractionExecutionResult, InteractionForkPayload, InteractionPublishPayload, InteractionRef, InteractionRefWithSchema, InteractionSearchPayload, InteractionSearchQuery, InteractionUpdatePayload, InteractionsExportPayload } from "@vertesia/common";
+import {
+    AsyncExecutionPayload, ComputeInteractionFacetPayload, GenerateInteractionPayload, GenerateTestDataPayload, ImprovePromptPayload,
+    Interaction, InteractionCreatePayload, InteractionEndpoint, InteractionEndpointQuery, InteractionExecutionPayload, InteractionForkPayload,
+    InteractionPublishPayload, InteractionRef, InteractionRefWithSchema, InteractionSearchPayload, InteractionSearchQuery,
+    InteractionsExportPayload, InteractionUpdatePayload, RateLimitRequestPayload, RateLimitRequestResponse
+} from "@vertesia/common";
 import { VertesiaClient } from "./client.js";
-import { executeInteraction, executeInteractionAsync, executeInteractionByName } from "./execute.js";
+import { checkRateLimit, executeInteraction, executeInteractionAsync, executeInteractionByName } from "./execute.js";
+import { EnhancedExecutionRun, EnhancedInteractionExecutionResult, enhanceExecutionRun, enhanceInteractionExecutionResult } from "./InteractionOutput.js";
 
 export interface ComputeInteractionFacetsResponse {
     tags?: { _id: string, count: number }[];
@@ -132,15 +138,16 @@ export default class InteractionsApi extends ApiTopic {
      * @throws 500 if interaction execution fails
      * @throws 500 if interaction execution times out
      **/
-    execute<P = any, R = any>(id: string, payload: InteractionExecutionPayload = {},
-        onChunk?: (chunk: string) => void): Promise<ExecutionRun<P, R>> {
-        return executeInteraction(this.client as VertesiaClient, id, payload, onChunk).catch(err => {
+    async execute<ResultT = any, ParamsT = any>(id: string, payload: InteractionExecutionPayload = {},
+        onChunk?: (chunk: string) => void): Promise<EnhancedInteractionExecutionResult<ResultT, ParamsT>> {
+        const r = await executeInteraction<ParamsT>(this.client as VertesiaClient, id, payload, onChunk).catch(err => {
             if (err instanceof ServerError && err.payload?.id) {
                 throw err.updateDetails({ run_id: err.payload.id });
             } else {
                 throw err;
             }
         });
+        return enhanceInteractionExecutionResult<ResultT, ParamsT>(r);
     }
 
     /**
@@ -158,15 +165,16 @@ export default class InteractionsApi extends ApiTopic {
      * @param onChunk
      * @returns
      */
-    executeByName<P = any, R = any>(nameWithTag: string, payload: InteractionExecutionPayload = {},
-        onChunk?: (chunk: string) => void): Promise<InteractionExecutionResult<P, R>> {
-        return executeInteractionByName(this.client as VertesiaClient, nameWithTag, payload, onChunk).catch(err => {
+    async executeByName<ResultT = any, ParamsT = any>(nameWithTag: string, payload: InteractionExecutionPayload = {},
+        onChunk?: (chunk: string) => void): Promise<EnhancedInteractionExecutionResult<ResultT, ParamsT>> {
+        const r = await executeInteractionByName<ParamsT>(this.client as VertesiaClient, nameWithTag, payload, onChunk).catch(err => {
             if (err instanceof ServerError && err.payload?.id) {
                 throw err.updateDetails({ run_id: err.payload.id });
             } else {
                 throw err;
             }
         });
+        return enhanceInteractionExecutionResult<ResultT, ParamsT>(r);
     }
 
     /**
@@ -214,10 +222,11 @@ export default class InteractionsApi extends ApiTopic {
     /**
      * Suggest Improvement for a prompt
      */
-    suggestImprovements(id: string, payload: ImprovePromptPayload): Promise<{ result: string; }> {
-        return this.post(`${id}/suggest-prompt-improvements`, {
+    async suggestImprovements<ResultT = any, ParamsT = any>(id: string, payload: ImprovePromptPayload): Promise<EnhancedExecutionRun<ResultT, ParamsT>> {
+        const r = await this.post(`${id}/suggest-prompt-improvements`, {
             payload
         });
+        return enhanceExecutionRun<ResultT, ParamsT>(r);
     }
 
     /**
@@ -238,4 +247,13 @@ export default class InteractionsApi extends ApiTopic {
         return this.get(`/${id}/forks`);
     }
 
+    /**
+     * Request a time slot to execute an interaction with a given environment / model
+     * @param payload RateLimitRequestPayload
+     * @returns RateLimitRequestResponse with delay_ms
+     */
+    requestSlot(payload: RateLimitRequestPayload): Promise<RateLimitRequestResponse> {
+        return checkRateLimit(this.client as VertesiaClient, payload);
+    }
+
 }

package/src/RunsApi.ts

@@ -14,6 +14,7 @@ import {
 } from "@vertesia/common";
 import { VertesiaClient } from "./client.js";
 import type { ExecutionResponse } from "@llumiverse/common";
+import { EnhancedExecutionRun, enhanceExecutionRun } from "./InteractionOutput.js";
 
 export interface FilterOption {
     id: string;
@@ -63,8 +64,9 @@ export class RunsApi extends ApiTopic {
      * @param id
      * @returns InteractionResult
      **/
-    retrieve<P = any, R = any>(id: string): Promise<ExecutionRun<P, R>> {
-        return this.get("/" + id);
+    async retrieve<ResultT = any, ParamsT = any>(id: string): Promise<EnhancedExecutionRun<ResultT, ParamsT>> {
+        const r = await this.get("/" + id);
+        return enhanceExecutionRun<ResultT, ParamsT>(r);
     }
 
     /**
@@ -78,7 +80,7 @@ export class RunsApi extends ApiTopic {
         return this.get(`/filter-options/${field}`, { query });
     }
 
-    create(payload: RunCreatePayload): Promise<ExecutionRun> {
+    async create<ResultT = any, ParamsT = any>(payload: RunCreatePayload): Promise<EnhancedExecutionRun<ResultT, ParamsT>> {
         const sessionTags = (this.client as VertesiaClient).sessionTags;
         if (sessionTags) {
             let tags = Array.isArray(sessionTags) ? sessionTags : [sessionTags];
@@ -89,9 +91,10 @@ export class RunsApi extends ApiTopic {
             }
             payload = { ...payload, tags };
         }
-        return this.post("/", {
+        const r = await this.post("/", {
             payload,
         });
+        return enhanceExecutionRun<ResultT, ParamsT>(r);
     }
 
     /**

package/src/client.ts

@@ -16,6 +16,8 @@ import { RunsApi } from "./RunsApi.js";
 import { ZenoClient } from "./store/client.js";
 import TrainingApi from "./TrainingApi.js";
 import UsersApi from "./UsersApi.js";
+import { VERSION, VERSION_HEADER } from "./store/version.js";
+
 
 /**
  * 1 min threshold constant in ms
@@ -130,6 +132,15 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         this.sessionTags = opts.sessionTags;
     }
 
+    withApiVersion(version: string | number | null) {
+        if (!version) {
+            delete this.headers[VERSION_HEADER];
+        } else {
+            this.headers[VERSION_HEADER] = String(version);
+        }
+        return this;
+    }
+
     /**
      * Overwrite to keep store and composable clients synchronized on the auth callback
      * @param authCb
@@ -227,6 +238,13 @@ export class VertesiaClient extends AbstractFetchClient<VertesiaClient> {
         return this.get('/auth/token', { query: query, headers: { "authorization": undefined } as any });
     }
 
+    get initialHeaders() {
+        return {
+            ...super.initialHeaders,
+            [VERSION_HEADER]: VERSION
+        }
+    }
+
     projects = new ProjectsApi(this);
     environments = new EnvironmentsApi(this);
     interactions = new InteractionsApi(this);

package/src/execute.ts

@@ -1,4 +1,4 @@
-import { AsyncExecutionPayload, ExecutionRunStatus, InteractionExecutionPayload, InteractionExecutionResult, NamedInteractionExecutionPayload } from '@vertesia/common';
+import { AsyncExecutionPayload, ExecutionRunStatus, InteractionExecutionPayload, InteractionExecutionResult, NamedInteractionExecutionPayload, RateLimitRequestPayload, RateLimitRequestResponse } from '@vertesia/common';
 import { VertesiaClient } from './client.js';
 
 export async function EventSourceProvider(): Promise<typeof EventSource> {
@@ -19,10 +19,10 @@ export async function EventSourceProvider(): Promise<typeof EventSource> {
  * @param payload InteractionExecutionPayload
  * @param onChunk callback to be called when the next chunk of the response is available
  */
-export async function executeInteraction<P = any, R = any>(client: VertesiaClient,
+export async function executeInteraction<P = any>(client: VertesiaClient,
     interactionId: string,
     payload: InteractionExecutionPayload = {},
-    onChunk?: (chunk: string) => void): Promise<InteractionExecutionResult<P, R>> {
+    onChunk?: (chunk: string) => void): Promise<InteractionExecutionResult<P>> {
     const stream = !!onChunk;
     const response = await client.runs.create({
         ...payload, interaction: interactionId, stream
@@ -52,10 +52,10 @@ export async function executeInteraction<P = any, R = any>(client: VertesiaClien
  * @param onChunk
  * @returns
  */
-export async function executeInteractionByName<P = any, R = any>(client: VertesiaClient,
+export async function executeInteractionByName<P = any>(client: VertesiaClient,
     interaction: string,
     payload: InteractionExecutionPayload = {},
-    onChunk?: (chunk: string) => void): Promise<InteractionExecutionResult<P, R>> {
+    onChunk?: (chunk: string) => void): Promise<InteractionExecutionResult<P>> {
     const stream = !!onChunk;
     const response = await client.post('/api/v1/execute', {
         payload: {
@@ -117,4 +117,10 @@ export async function executeInteractionAsync(client: VertesiaClient, payload: A
     return await client.post('/api/v1/execute/async', {
         payload,
     });
+}
+
+export async function checkRateLimit(client: VertesiaClient, payload: RateLimitRequestPayload): Promise<RateLimitRequestResponse> {
+    return await client.post('/api/v1/execute/rate-limit/request', {
+        payload
+    });
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from './client.js';
 export * from './InteractionBase.js';
+export * from './InteractionOutput.js';
 export type { AsyncExecutionResult, ComputeInteractionFacetsResponse } from './InteractionsApi.js';
 export type { ComputePromptFacetsResponse, ListInteractionsResponse } from './PromptsApi.js';
 export type { ComputeRunFacetsResponse, FilterOption } from './RunsApi.js';

package/src/store/CollectionsApi.ts

@@ -91,6 +91,30 @@ export class CollectionsApi extends ApiTopic {
         });
     }
 
+    addChildren(collectionId: string, children: string[]): Promise<{ count: number }> {
+        return this.post(`/${collectionId}/children`, {
+            payload: {
+                action: 'add',
+                children
+            }
+        });
+    }
+
+    deleteChildren(collectionId: string, children: string[]): Promise<{ count: number }> {
+        return this.post(`/${collectionId}/children`, {
+            payload: {
+                action: 'delete',
+                children
+            }
+        });
+    }
+
+    searchChildren(collectionId: string, query: ComplexCollectionSearchQuery = {}): Promise<CollectionItem[]> {
+        return this.post(`/${collectionId}/children/search`, {
+            payload: query
+        });
+    }
+
     delete(id: string) {
         return this.del(`/${id}`);
     }

package/src/store/ObjectsApi.ts

@@ -1,5 +1,6 @@
 import { ApiTopic, ClientBase } from "@vertesia/api-fetch-client";
 import {
+    ContentObjectApiHeaders,
     ComplexSearchPayload,
     ComputeObjectFacetPayload,
     ContentObject,
@@ -48,7 +49,7 @@ export interface ComputeFacetsResponse {
     type?: { _id: string; count: number }[];
     location?: { _id: string; count: number }[];
     status?: { _id: string; count: number }[];
-    total?: { count: number }[];
+    total?: number;
 }
 
 export interface SearchResponse {
@@ -231,9 +232,18 @@ export class ObjectsApi extends ApiTopic {
         ) {
             createPayload.content = await this.upload(payload.content);
         }
+
+        const headers: Record<string, string> = {};
+        if (options?.processing_priority) {
+            headers[ContentObjectApiHeaders.PROCESSING_PRIORITY] = options.processing_priority;
+        } 
+        if (options?.collection_id) {
+            headers[ContentObjectApiHeaders.COLLECTION_ID] = options.collection_id;
+        }
+
         return await this.post("/", {
             payload: createPayload,
-            query: options || {},
+            headers: headers,
         });
     }
 
@@ -243,11 +253,16 @@ export class ObjectsApi extends ApiTopic {
      * For the s3 blobs you must use a hash with the blob #region. Ex: s3://bucket/path/to/file#us-east-1
      * @param uri
      * @param payload
+     * @param options
      * @returns
      */
     async createFromExternalSource(
         uri: string,
         payload: CreateContentObjectPayload = {},
+        options?: {
+            collection_id?: string;
+            processing_priority?: ContentObjectProcessingPriority;
+        },
     ): Promise<ContentObject> {
         const metadata = await (this.client as ZenoClient).files.getMetadata(
             uri,
@@ -261,8 +276,18 @@ export class ObjectsApi extends ApiTopic {
                 etag: metadata.etag,
             },
         };
+
+        const headers: Record<string, string> = {};
+        if (options?.processing_priority) {
+            headers[ContentObjectApiHeaders.PROCESSING_PRIORITY] = options.processing_priority;
+        } 
+        if (options?.collection_id) {
+            headers[ContentObjectApiHeaders.COLLECTION_ID] = options.collection_id;
+        }
+
         return await this.post("/", {
             payload: createPayload,
+            headers: headers,
         });
     }
 
@@ -298,19 +323,21 @@ export class ObjectsApi extends ApiTopic {
             updatePayload.content = await this.upload(payload.content);
         }
 
+        const headers: Record<string, string> = {};
+        if (options?.processing_priority) {
+            headers[ContentObjectApiHeaders.PROCESSING_PRIORITY] = options.processing_priority;
+        }
         if (options?.createRevision) {
-            return this.put(`/${id}`, {
-                payload: updatePayload,
-                headers: {
-                    "x-create-revision": "true",
-                    "x-revision-label": options.revisionLabel || "",
-                },
-            });
-        } else {
-            return this.put(`/${id}`, {
-                payload: updatePayload,
-            });
+            headers[ContentObjectApiHeaders.CREATE_REVISION] = "true";
+            if (options.revisionLabel) {
+                headers[ContentObjectApiHeaders.REVISION_LABEL] = options.revisionLabel;
+            }
         }
+
+        return this.put(`/${id}`, {
+            payload: updatePayload,
+            headers,
+        });
     }
 
     /**

package/src/store/TypesApi.ts

@@ -17,7 +17,7 @@ export class TypesApi extends ApiTopic {
      * @returns
      */
     list(payload: ObjectTypeSearchPayload = {}, options?: { layout?: boolean, schema?: boolean }): Promise<ContentObjectTypeItem[]> {
-        const limit = payload.limit || 100;
+        const limit = payload.limit || 2000;
         const offset = payload.offset || 0;
         const query = payload.query || {} as ObjectTypeSearchQuery;
 

package/src/store/WorkflowsApi.ts

@@ -10,6 +10,7 @@ import {
     ListWorkflowInteractionsResponse,
     ListWorkflowRunsPayload,
     ListWorkflowRunsResponse,
+    WorkflowActionPayload,
     WorkflowDefinitionRef,
     WorkflowRule,
     WorkflowRuleItem,
@@ -56,11 +57,13 @@ export class WorkflowsApi extends ApiTopic {
     }
 
     terminate(workflowId: string, runId: string, reason?: string): Promise<{ message: string }> {
-        return this.post(`/runs/${workflowId}/${runId}/actions/terminate`, { payload: { reason } });
+        const payload: WorkflowActionPayload = { reason };
+        return this.post(`/runs/${workflowId}/${runId}/actions/terminate`, { payload });
     }
 
     cancel(workflowId: string, runId: string, reason?: string): Promise<{ message: string }> {
-        return this.post(`/runs/${workflowId}/${runId}/actions/cancel`, { payload: { reason } });
+        const payload: WorkflowActionPayload = { reason };
+        return this.post(`/runs/${workflowId}/${runId}/actions/cancel`, { payload });
     }
 
     execute(

package/src/store/client.ts

@@ -1,14 +1,15 @@
 import { AbstractFetchClient, RequestError } from "@vertesia/api-fetch-client";
 import { BulkOperationPayload, BulkOperationResult } from "@vertesia/common";
 import { AgentsApi } from "./AgentsApi.js";
+import { CollectionsApi } from "./CollectionsApi.js";
 import { CommandsApi } from "./CommandsApi.js";
 import { EmbeddingsApi } from "./EmbeddingsApi.js";
 import { ZenoClientNotFoundError } from "./errors.js";
 import { FilesApi } from "./FilesApi.js";
 import { ObjectsApi } from "./ObjectsApi.js";
 import { TypesApi } from "./TypesApi.js";
+import { VERSION, VERSION_HEADER } from "./version.js";
 import { WorkflowsApi } from "./WorkflowsApi.js";
-import { CollectionsApi } from "./CollectionsApi.js";
 
 export interface ZenoClientProps {
     serverUrl?: string;
@@ -44,6 +45,15 @@ export class ZenoClient extends AbstractFetchClient<ZenoClient> {
         }
     }
 
+    withApiVersion(version: string | number | null) {
+        if (!version) {
+            delete this.headers[VERSION_HEADER];
+        } else {
+            this.headers[VERSION_HEADER] = String(version);
+        }
+        return this;
+    }
+
     withApiKey(apiKey: string | null) {
         return this.withAuthCallback(
             apiKey ? () => Promise.resolve(`Bearer ${apiKey}`) : undefined
@@ -56,6 +66,13 @@ export class ZenoClient extends AbstractFetchClient<ZenoClient> {
         });
     }
 
+    get initialHeaders() {
+        return {
+            ...super.initialHeaders,
+            [VERSION_HEADER]: VERSION
+        }
+    }
+
     objects = new ObjectsApi(this);
     types = new TypesApi(this);
     workflows = new WorkflowsApi(this);

package/src/store/version.ts

@@ -0,0 +1,2 @@
+export const VERSION = '20250925' // YYYYMMDD, client versioning for API endpoints. Increment manually for breaking changes
+export const VERSION_HEADER = 'x-api-version';