@vertesia/common 0.78.0 → 0.79.1

package/package.json

@@ -1,40 +1,40 @@
 {
-  "name": "@vertesia/common",
-  "version": "0.78.0",
-  "type": "module",
-  "types": "./lib/types/index.d.ts",
-  "files": [
-    "lib",
-    "src",
-    "tsconfig.dist.json"
-  ],
-  "exports": {
+    "name": "@vertesia/common",
+    "version": "0.79.1",
+    "type": "module",
     "types": "./lib/types/index.d.ts",
-    "import": "./lib/esm/index.js",
-    "require": "./lib/cjs/index.js"
-  },
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^28.0.3",
-    "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-typescript": "^12.1.2",
-    "@types/json-schema": "^7.0.15",
-    "rollup": "^4.40.2",
-    "rollup-plugin-terser": "^7.0.2",
-    "ts-dual-module": "^0.6.3",
-    "typescript": "^5.0.2",
-    "vitest": "^3.0.9"
-  },
-  "dependencies": {
-    "ajv": "^8.16.0",
-    "json-schema": "^0.4.0",
-    "@llumiverse/common": "0.22.0"
-  },
-  "ts_dual_module": {
-    "outDir": "lib"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "build": "pnpm exec tsmod build && pnpm exec rollup -c",
-    "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo"
-  }
-}
+    "files": [
+        "lib",
+        "src",
+        "tsconfig.dist.json"
+    ],
+    "scripts": {
+        "test": "vitest run",
+        "build": "pnpm exec tsmod build && pnpm exec rollup -c",
+        "clean": "rimraf ./node_modules ./lib ./tsconfig.tsbuildinfo"
+    },
+    "exports": {
+        "types": "./lib/types/index.d.ts",
+        "import": "./lib/esm/index.js",
+        "require": "./lib/cjs/index.js"
+    },
+    "devDependencies": {
+        "@rollup/plugin-commonjs": "^28.0.3",
+        "@rollup/plugin-node-resolve": "^16.0.1",
+        "@rollup/plugin-typescript": "^12.1.2",
+        "@types/json-schema": "^7.0.15",
+        "rollup": "^4.40.2",
+        "rollup-plugin-terser": "^7.0.2",
+        "ts-dual-module": "^0.6.3",
+        "typescript": "^5.0.2",
+        "vitest": "^3.0.9"
+    },
+    "dependencies": {
+        "@llumiverse/common": "workspace:*",
+        "ajv": "^8.16.0",
+        "json-schema": "^0.4.0"
+    },
+    "ts_dual_module": {
+        "outDir": "lib"
+    }
+}

package/src/access-control.ts

@@ -42,6 +42,7 @@ export enum Permission {
 
     workflow_run = "workflow:run",
     workflow_admin = "workflow:admin",
+    workflow_superadmin = "workflow:superadmin",
 
     /**
      * whether the user has access to Sutdio App.

package/src/apikey.ts

@@ -90,6 +90,7 @@ export interface AuthTokenPayload {
 
 export enum PrincipalType {
     User = "user",
+    Group = "group",
     ApiKey = "apikey",
     ServiceAccount = "service_account",
 }

package/src/apps.ts

@@ -1,3 +1,4 @@
+import { JSONSchema } from "@llumiverse/common";
 
 export interface AppUIConfig {
     /**
@@ -36,6 +37,12 @@ export interface AppManifestData {
      */
     icon?: string;
 
+    /**
+     * A color name to be used as the color of the app card (e.g. blue, red, green, etc.)
+     * If not specified a random color will be picked.
+     */
+    color?: string;
+
     status: "beta" | "stable" | "deprecated"
 
     ui?: AppUIConfig
@@ -46,6 +53,11 @@ export interface AppManifestData {
      * If the `?import` query string is used the tool will be imported as a javascript module and not executed through a POST on the collections endpoint.
      */
     tool_collections?: string[]
+
+    /**
+     * A JSON chema for the app installation settings.
+     */
+    settings_schema?: JSONSchema;
 }
 export interface AppManifest extends AppManifestData {
     id: string;
@@ -73,3 +85,23 @@ export interface AppInstallationPayload {
 }
 
 export type AppInstallationKind = 'ui' | 'tools' | 'all';
+
+/**
+ * A descriptiojn of the tools provided by an app
+ */
+export interface AppToolCollection {
+    /**
+     * The collection name
+     */
+    name: string;
+
+    /**
+     * Optional collection description
+     */
+    description?: string;
+
+    /**
+     * the tools provided by this collection
+     */
+    tools: { name: string, description?: string }[]
+}

package/src/index.ts

@@ -17,6 +17,7 @@ export * from "./Progress.js";
 export * from './project.js';
 export * from './prompt.js';
 export * from './query.js';
+export * from './rate-limiter.js';
 export * from './refs.js';
 export * from './runs.js';
 export * from "./store/index.js";
@@ -26,4 +27,6 @@ export * from './transient-tokens.js';
 export * from './user.js';
 export * from './utils/auth.js';
 export * from './utils/schemas.js';
-export type * from './utils/type-helpers.js'
+export type * from './utils/type-helpers.js';
+export * from './versions.js';
+

package/src/interaction.ts

@@ -1,4 +1,5 @@
 import type {
+    CompletionResult,
     JSONObject,
     JSONSchema,
     Modalities,
@@ -284,7 +285,7 @@ export interface NamedInteractionExecutionPayload extends InteractionExecutionPa
 // ================= async execution payloads ====================
 export type ToolRef = string | { name: string; description: string };
 
-interface AsyncExecutionPayloadBase extends Omit<NamedInteractionExecutionPayload,"toolDefinitions" | "stream"> {
+interface AsyncExecutionPayloadBase extends Omit<NamedInteractionExecutionPayload, "toolDefinitions" | "stream"> {
     type: "conversation" | "interaction";
 
     /**
@@ -381,6 +382,10 @@ export interface ToolResultContent {
     content: string;
     is_error: boolean;
     files?: string[];
+    /**
+     * Can contain metadata returned by the tool executor.
+     */
+    meta?: Record<string, any>;
 }
 
 export interface ToolResult extends ToolResultContent {
@@ -398,7 +403,7 @@ export interface UserMessagePayload extends ResumeConversationPayload {
     message: string;
 }
 
-export type CheckpointConversationPayload = Omit<ToolResultsPayload, "results">;
+export type CheckpointConversationPayload = Omit<ToolResultsPayload, "results" | "tools">
 
 // ================= end async execution payloads ====================
 
@@ -419,7 +424,7 @@ export interface RunSource {
     client_ip: string;
 }
 
-export interface ExecutionRun<P = any, R = any> {
+export interface ExecutionRun<P = any> {
     readonly id: string;
     /**
      * Only used by runs that were created by a virtual run to point toward the virtual run parent
@@ -430,7 +435,7 @@ export interface ExecutionRun<P = any, R = any> {
         selected?: boolean;
         scores?: Record<string, number>;
     };
-    result: R;
+    result: CompletionResult[] // Any new result will actually be CompletionResult[], the old typing is R, and R used to default to any.
     /**
      * The parameters used to create the interaction.
      * If the parameters contains the special property "@memory" it will be used
@@ -450,7 +455,7 @@ export interface ExecutionRun<P = any, R = any> {
     prompt: any;
     token_use?: ExecutionTokenUsage;
     chunks?: number;
-    execution_time?: number; //s
+    execution_time?: number; // ms
     created_at: Date;
     updated_at: Date;
     account: AccountRef;
@@ -498,7 +503,7 @@ export interface ExecutionRunWorkflow {
     activity_type?: string;
 }
 
-export interface InteractionExecutionResult<P = any, R = any> extends ExecutionRun<P, R> {
+export interface InteractionExecutionResult<P = any> extends ExecutionRun<P> {
     tool_use?: ToolUse[];
     conversation?: unknown;
     options?: StatelessExecutionOptions;
@@ -551,3 +556,14 @@ export interface GenerateTestDataPayload {
 export interface ImprovePromptPayload {
     config: InteractionExecutionConfiguration;
 }
+
+export interface RateLimitRequestPayload {
+    interaction: string,
+    environment_id?: string,
+    model_id?: string,
+    workflow_run_id?: string
+}
+
+export interface RateLimitRequestResponse {
+    delay_ms: number;
+}

package/src/payload.ts

@@ -13,10 +13,8 @@ import {
 export interface SearchPayload {
     facets?: FacetSpec[];
     /**
-     * If the facets should respect "limit"
-     * If true, the facet count be limited to the number of results in the query.
-     * If false, the facet count will be calculated over all objects.
-     * Default is true.
+     * If the facets should be limited to the current page of results.
+     * Defaults to false. When false, the facets are independent of the search results page.
      */
     limit_facets?: boolean;
     query?: SimpleSearchQuery;

package/src/project.ts

@@ -140,11 +140,11 @@ export const ProjectRefPopulate = "id name account";
 
 export interface EmbeddingsStatusResponse {
     status: string;
-    embeddingRunsInProgress: number;
-    totalRunsInProgress: number;
-    totalIndexableObjects: number;
-    embeddingsModels: string[];
-    objectsWithEmbeddings: number;
+    embeddingRunsInProgress?: number;
+    totalRunsInProgress?: number;
+    totalIndexableObjects?: number;
+    embeddingsModels?: string[];
+    objectsWithEmbeddings?: number;
     vectorIndex: {
         status: "READY" | "PENDING" | "DELETING" | "ABSENT",
         name?: string,

package/src/query.ts

@@ -43,6 +43,7 @@ export interface SimpleSearchQuery {
 }
 
 export interface ObjectSearchQuery extends SimpleSearchQuery {
+    id?: string;
     createdFrom?: string;
     createdTo?: string;
     updatedFrom?: string;
@@ -68,6 +69,8 @@ export interface InteractionSearchQuery extends SimpleSearchQuery {
     prompt?: string;
     tags?: string[];
     version?: string;
+    model?: string;
+    environment?: string;
 }
 
 export interface RunSearchQuery extends SimpleSearchQuery {
@@ -86,6 +89,7 @@ export interface RunSearchQuery extends SimpleSearchQuery {
     finish_reason?: string;
     created_by?: string;
     workflow_run_ids?: string[];
+    run_ids?: string[];
 }
 
 export interface WorkflowExecutionSearchQuery extends SimpleSearchQuery {

package/src/rate-limiter.ts

@@ -0,0 +1,34 @@
+/**
+ * Rate Limiter Types
+ */
+
+export interface RateLimiterCapacity {
+    current: number;
+    base: number;
+    max: number;
+}
+
+export interface RateLimiterBreakerState {
+    state: 'open' | 'closed';
+    is_open: boolean;
+    last_opened_at?: string;
+    consecutive_failures?: number;
+}
+
+export interface RateLimiterModelStatus {
+    model_id: string;
+    admitted: number;
+    delayed: number;
+    capacity: RateLimiterCapacity;
+    breaker: RateLimiterBreakerState;
+    last_updated: string;
+}
+
+export interface RateLimiterStatus {
+    environment_id: string;
+    model_id: string;
+    status: RateLimiterModelStatus;
+}
+
+// Always return an array for consistency
+export type RateLimiterStatusResponse = RateLimiterStatus[];

package/src/store/collections.ts

@@ -31,9 +31,10 @@ export interface CollectionItem extends BaseObject {
     // A ref to the object type
     type?: ContentObjectTypeRef;
     /**
-     * The parent collection if any
+     * The parent collections if any.
+     * A collection can have multiple parents.
      */
-    parent?: string | null;
+    parents?: string[] | null;
     /**
      * The table layout to use for the collection.
      * The layout defined in the type could serve as a fallback if not defined here.
@@ -63,10 +64,12 @@ export interface DynamicCollection extends Collection {
 }
 
 export interface CollectionSearchPayload {
+    parent?: string | null;
     dynamic?: boolean;
     status?: CollectionStatus;
     limit?: number;
     offset?: number;
     name?: string;
     type?: string;
+    types?: string[];
 }

package/src/store/store.ts

@@ -3,6 +3,13 @@ import { SupportedEmbeddingTypes } from "../project.js";
 import { ComplexSearchQuery } from "../query.js";
 import { BaseObject } from "./common.js";
 
+export enum ContentObjectApiHeaders {
+    COLLECTION_ID = 'x-collection-id',
+    PROCESSING_PRIORITY = 'x-processing-priority',
+    CREATE_REVISION = 'x-create-revision',
+    REVISION_LABEL = 'x-revision-label',
+}
+
 export enum ContentObjectStatus {
     created = "created",
     processing = "processing", // the was created and still processing
@@ -27,13 +34,14 @@ export interface ContentObject<T = any> extends ContentObjectItem<T> {
     security?: Record<string, string[]>; // Security field for granular permissions
 }
 
-export type ContentNature =
-    | "video"
-    | "image"
-    | "audio"
-    | "document"
-    | "code"
-    | "other";
+export enum ContentNature {
+    Video = "video",
+    Image = "image",
+    Audio = "audio",
+    Document = "document",
+    Code = "code",
+    Other = "other"
+}
 
 export interface Dimensions {
     width: number;
@@ -69,17 +77,29 @@ export interface TemporalMediaMetadata extends ContentMetadata {
 }
 
 export interface ImageMetadata extends ContentMetadata {
-    type: "image";
+    type: ContentNature.Image;
     dimensions?: Dimensions;
 }
 
 export interface AudioMetadata extends TemporalMediaMetadata {
-    type: "audio";
+    type: ContentNature.Audio;
+}
+
+export interface VideoRendition {
+    name: string;
+    dimensions: Dimensions;
+    content: ContentSource
 }
 
+export const POSTER_RENDITION_NAME = "Poster";
+export const AUDIO_RENDITION_NAME = "Audio";
+export const WEB_VIDEO_RENDITION_NAME = "Web";
+
 export interface VideoMetadata extends TemporalMediaMetadata {
-    type: "video";
+    type: ContentNature.Video;
     dimensions?: Dimensions;
+    renditions?: VideoRendition[];
+    hasAudio?: boolean;
 }
 
 export interface TextSection {
@@ -89,7 +109,7 @@ export interface TextSection {
 }
 
 export interface DocumentMetadata extends ContentMetadata {
-    type: "document";
+    type: ContentNature.Document;
     page_count?: number;
     content_processor?: {
         type?: string;
@@ -331,6 +351,11 @@ export interface WorkflowRule extends WorkflowRuleItem {
      * When set to true the rule will not be updated by the system
      */
     customer_override?: boolean;
+
+    /**
+     * Optional task queue name to use when starting workflows for this rule
+     */
+    task_queue?: string; 
 }
 
 export interface CreateWorkflowRulePayload extends UploadWorkflowRulePayload {

package/src/store/workflow.ts

@@ -1,5 +1,5 @@
 import { JSONSchema4 } from "json-schema";
-import { InteractionRef } from "../interaction.js";
+import { ConversationVisibility, InteractionRef } from "../interaction.js";
 
 export enum ContentEventName {
     create = "create",
@@ -12,6 +12,13 @@ export enum ContentEventName {
     api_request = "api_request",
 }
 
+export interface Queue {
+    name: string;
+    // use either suffix or full name. fullname has precedence over suffix
+    queue_suffix?: string; // suffix to append to the base queue name
+    queue_full_name?: string; // full name
+}
+
 export interface WorkflowExecutionBaseParams<T = Record<string, any>> {
     /**
      * The ref of the user who initiated the workflow.
@@ -59,7 +66,7 @@ export interface WorkflowExecutionBaseParams<T = Record<string, any>> {
      * The list of endpoints to notify when the workflow finishes.
      * It is handled by a sub-workflow execution, so the main workflow will not wait for the notification to be sent.
      */
-    notify_endpoints?: string[];
+    notify_endpoints?: (string | WebHookSpec)[];
 
     /** If this is a child workflow, parent contains parent's ids  */
     parent?: {
@@ -72,14 +79,21 @@ export interface WorkflowExecutionBaseParams<T = Record<string, any>> {
     };
 
     /**
-     * Whether to route resource intensive tasks to a heavy load queue. Managed by the application.
+     *  List of enabled processing queues. Managed by the application.
      */
-    _enable_heavy_task_routing?: boolean;
+    _enabled_queues?: Queue[];
 
+}
+
+export interface WebHookSpec {
+    /**
+     * The webhook URL to call using POST method
+     */
+    url: string;
     /**
-     * The suffix to append to the task queue name for heavy load routing. Managed by the application.
+     * the API version to use if any
      */
-    _heavy_task_queue_suffix?: string;
+    version?: number;
 }
 
 export interface WorkflowExecutionPayload<T = Record<string, any>> extends WorkflowExecutionBaseParams<T> {
@@ -188,6 +202,11 @@ export interface ListWorkflowRunsPayload {
      */
     initiated_by?: string;
 
+    /**
+     * The interaction name used to filter conversations.
+     */
+    interaction?: string;
+
     /**
      * Lucene query string to search for the workflow runs.
      * This is a full text search on the workflow run history.
@@ -287,6 +306,16 @@ export interface WorkflowRun {
      * An interaction is used to start the agent, the data is stored on temporal "vars"
      */
     interactions?: InteractionRef[];
+    /**
+     * The visibility of the workflow run.
+     * - 'private': Only visible to the user who initiated the workflow
+     * - 'project': Visible to all users in the project
+     */
+    visibility?: ConversationVisibility;
+    /**
+     * A brief summary of the conversation workflow.
+     */
+    topic?: string;
 }
 
 export interface WorkflowRunWithDetails extends WorkflowRun {
@@ -321,11 +350,12 @@ export interface WorkflowInteraction {
     tools: [],
     interaction: string,
     environment: string,
-    prompt_data: JSONSchema4,
+    data: JSONSchema4,
     interactive: boolean,
     interactionParamsSchema?: JSONSchema4
     debug_mode?: boolean;
     collection_id?: string;
+    config: Record<string, any>;
 }
 
 export interface MultiDocumentsInteractionParams extends Omit<WorkflowExecutionPayload, "config"> {
@@ -407,3 +437,13 @@ export interface Plan {
 }
 
 export const LOW_PRIORITY_TASK_QUEUE = "low_priority";
+
+/**
+ * Payload for applying actions to a workflow run (e.g., cancel, terminate).
+ */
+export interface WorkflowActionPayload {
+    /**
+     * Optional reason for the action.
+     */
+    reason?: string;
+}

package/src/versions.ts

@@ -0,0 +1,3 @@
+export enum ApiVersions {
+    COMPLETION_RESULT_V1 = 20250925,
+}

package/LICENSE

@@ -1,13 +0,0 @@
-Copyright 2024 Composable
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.