@vertesia/common 0.79.0 → 0.80.0-dev-20251118

package/package.json

@@ -1,40 +1,45 @@
 {
-  "name": "@vertesia/common",
-  "version": "0.79.0",
-  "type": "module",
-  "types": "./lib/types/index.d.ts",
-  "files": [
-    "lib",
-    "src",
-    "tsconfig.dist.json"
-  ],
-  "exports": {
+    "name": "@vertesia/common",
+    "version": "0.80.0-dev-20251118",
+    "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"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/vertesia/composableai.git",
+        "directory": "packages/common"
+    },
+    "ts_dual_module": {
+        "outDir": "lib"
+    }
+}

package/src/access-control.ts

@@ -42,10 +42,11 @@ export enum Permission {
 
     workflow_run = "workflow:run",
     workflow_admin = "workflow:admin",
+    workflow_superadmin = "workflow:superadmin",
 
-    /**
-     * whether the user has access to Sutdio App.
-     */
+    iam_impersonate = "iam:impersonate",
+
+    /** whether the user has access to Sutdio App. */
     studio_access = "studio:access",
 }
 
@@ -94,4 +95,4 @@ export interface AcesQueryOptions {
     role?: string
     type?: AccessControlResourceType
 
-}
+}

package/src/apikey.ts

@@ -2,9 +2,8 @@ import { UserGroupRef } from "./group.js";
 import { ProjectRef, ProjectRoles } from "./project.js";
 import { AccountRef } from "./user.js";
 
-
 export enum ApiKeyTypes {
-    secret = 'sk'
+    secret = "sk",
 }
 export interface ApiKey {
     id: string;
@@ -15,27 +14,23 @@ export interface ApiKey {
     account: string; // the account id
     project: ProjectRef; // the project id if any
     enabled: boolean;
-    created_by: string,
-    updated_by: string,
+    created_by: string;
+    updated_by: string;
     created_at: Date;
     updated_at: Date;
     expires_at?: Date; // in case of public key only
 }
 
+export interface CreateOrUpdateApiKeyPayload extends Partial<ApiKey> {}
 
-export interface CreateOrUpdateApiKeyPayload extends Partial<ApiKey> {
-
-}
-
-export interface ApiKeyWithValue extends Omit<ApiKey, 'maskedValue'> {
+export interface ApiKeyWithValue extends Omit<ApiKey, "maskedValue"> {
     value: string;
 }
 
-
 export interface CreatePublicKeyPayload {
-    name?: string,
-    projectId?: string,
-    ttl?: number,
+    name?: string;
+    projectId?: string;
+    ttl?: number;
 }
 
 export interface AuthTokenResponse {
@@ -43,12 +38,12 @@ export interface AuthTokenResponse {
 }
 
 export interface AuthTokenPayload {
-    sub: string
+    sub: string;
     name: string;
     email?: string;
     picture?: string;
 
-    type: PrincipalType
+    type: PrincipalType;
     account: AccountRef;
 
     account_roles: ProjectRoles[];
@@ -77,20 +72,26 @@ export interface AuthTokenPayload {
      * Either a n API domain like 'api.vertesia.io' | 'api-preview.vertesia.io' | 'api-staging.vertesia.io' | 'local'
      * or explicit studio and store URLs.
      */
-    endpoints?: string | {
-        studio: string,
-        store: string
-    }
+    endpoints?:
+        | string
+        | {
+              studio: string;
+              store: string;
+          };
 
     iss: string; //issuer
     aud: string; //audience
     exp: number; //expires in (EPOC seconds)
-}
+    tags?: string[]; //tags
 
+    permissions?: string[]; //permissions
+    scopes?: string[]; //scopes
+}
 
 export enum PrincipalType {
     User = "user",
     Group = "group",
     ApiKey = "apikey",
     ServiceAccount = "service_account",
-}
+    Agent = "agent",
+}

package/src/apps.ts

@@ -54,6 +54,14 @@ export interface AppManifestData {
      */
     tool_collections?: string[]
 
+    /**
+     * An URL providing interactions definitions in JSON format.
+     * The URL must provide 2 endpoints:
+     * 1. GET URL - must return a JSON array with the list of interactions (as AppInteractionRef[])
+     * 2. GET URL/{interaction_name} - must return the full interaction definition for the specified interaction.
+     */
+    interactions?: string;
+
     /**
      * A JSON chema for the app installation settings.
      */

package/src/index.ts

@@ -28,5 +28,6 @@ export * from './user.js';
 export * from './utils/auth.js';
 export * from './utils/schemas.js';
 export type * from './utils/type-helpers.js';
+export * from './sts-token-types.js';
 export * from './versions.js';
 

package/src/interaction.ts

@@ -4,6 +4,7 @@ import type {
     JSONSchema,
     Modalities,
     ModelOptions,
+    PromptRole,
     StatelessExecutionOptions,
     ToolDefinition,
     ToolUse,
@@ -15,10 +16,12 @@ import { ExecutionTokenUsage } from "@llumiverse/common";
 import { ExecutionEnvironmentRef } from "./environment.js";
 import { ProjectRef } from "./project.js";
 import {
+    ExecutablePromptSegmentDef,
     PopulatedPromptSegmentDef,
     PromptSegmentDef,
     PromptTemplateRef,
     PromptTemplateRefWithSchema,
+    TemplateType,
 } from "./prompt.js";
 import { ExecutionRunDocRef } from "./runs.js";
 import { AccountRef } from "./user.js";
@@ -29,6 +32,193 @@ export interface InteractionExecutionError {
     data?: any;
 }
 
+
+// ------------------ in code interactions -----------------
+/**
+ * Reference to an interaction in the catalog.
+ * Used in catalog listing. The id is composed of the namespace and the interaction name.
+ * Stored interactions can use `oid:` prefix.
+ * If no prefix is used it fallback on `oid:`.
+ */
+export interface CatalogInteractionRef {
+    /**
+     * The type of interaction
+     */
+    type: "sys" | "app" | "stored" | "draft";
+
+    /**
+     * the interaction id that can be used to execute the interaction.
+     */
+    id: string;
+
+    /**
+     * The interaction name which identify the interaction in the provider interaction list.
+     * For the stored interactions this is the same as the endpoint property.
+     * For other types of interactions this is the local name of the interaction.
+     */
+    name: string;
+
+    /**
+     * Only applies for stored interactions. The version of the interaction.
+     * Undefined for non stored interactions
+     */
+    version?: number;
+
+    /**
+     * Only applies for stored interactions. Whether the interaction is published or not.
+     */
+    published?: boolean;
+
+    /**
+     * The tags associated with the interaction.
+     */
+    tags: string[];
+
+    /**
+     * Agent Runner configuration options.
+     */
+    agent_runner_options?: AgentRunnerOptions;
+
+    /**
+     * The name of the interaction. For display purposes only.
+     */
+    title: string;
+
+    /**
+     * Optional description of the interaction.
+     */
+    description?: string;
+}
+
+export interface InCodePrompt {
+    role: PromptRole,
+    content: string,
+    content_type: TemplateType;
+    schema?: JSONSchema;
+    /**
+     * optional name of the prompt segment. Use kebab case for prompt names
+     */
+    name?: string;
+    /**
+     * optional reference to an external resource if any.
+     * Used internally by the system to synchronize stored prompts with in-code prompts.
+     */
+    externalId?: string;
+}
+export interface InCodeInteraction {
+    /**
+     * The interaction type.
+     */
+    type: "sys" | "app" | "stored" | "draft";
+
+    /**
+     * The id of the interaction. Required.
+     * The id is a unique identifier for the interaction.
+     * It is recommended to use a URL safe string and not include spaces. 
+     * The id composaed  by some namespace or prefix and the interaction name.
+     * Example: sys:generic_question, app:review_contract, tmp:my_temp_interaction
+     */
+    id: string;
+
+    /**
+     * The interaction code name. Required. 
+     * Should be a URL safe string and not include spaces. It is recommended to use kebab-case or camel-case.
+     * The endpoints must satisfy the following regexp: /^[a-zA-Z0-9-_]+$/. No whitespaces or special characters are allowed.
+     */
+    name: string;
+
+    /**
+     * Only applies for stored interactions. The version of the interaction.
+     * Undefined for non stored interactions
+     */
+    version?: number;
+
+    /**
+     * Only applies for stored interactions. Whether the interaction is published or not.
+     */
+    published?: boolean;
+
+    /**
+     * A title for the interaction. If not provided, the endpoint will be used.
+     */
+    title?: string;
+
+    /**
+     * An optional description of the interaction.
+     */
+    description?: string;
+
+    /**
+     * The JSON schema to be used for the result if any.
+     */
+    result_schema?: JSONSchema | SchemaRef;
+
+    /**
+     * The modality of the interaction output. 
+     * If not specified Modalities.Text is assumed.
+     */
+    output_modality?: Modalities,
+
+    /**
+     * How to store the run data for executions of this interaction.
+     * Defaults to STANDARD.
+     */
+    storage?: RunDataStorageLevel;
+
+    /**
+     * Optional tags for the interaction.
+     */
+    tags?: string[];
+
+    /**
+     * Agent Runner configuration options.
+     */
+    agent_runner_options?: AgentRunnerOptions;
+
+    /**
+     * Default options for the model to be used when executing this interaction.
+     * (like temperature etc)
+     */
+    model_options?: ModelOptions;
+
+    /**
+     * The prompts composing the interaction. Required.
+     */
+    prompts: InCodePrompt[]
+
+    /**
+     * Optional reference to an external resource if any.
+     * Used internally by the system to synchronize stored interactions with in-code interactions. 
+     */
+    externalId?: string;
+
+    /**
+     * Runtime configuration (system use only)
+     *
+     * This field is populated by the system when converting stored interactions
+     * and contains runtime-specific defaults like target model/environment IDs.
+     *
+     * DO NOT set this field manually when writing interaction definitions.
+     * These values are environment-specific and not portable.
+     *
+     * @internal
+     */
+    runtime?: {
+        /**
+         * Default target environment for the interaction execution         
+         */
+        environment?: string;
+
+        /**
+         * Default (recommended) target model for the interaction execution
+         */
+        model?: string;
+    }
+}
+export interface InteractionSpec extends Omit<InCodeInteraction, 'id' | 'runtime' | 'type' | 'published' | 'version'> {
+}
+// ---------------------------------------------------------
+
 /**
  * The payload to query the interaction endpoints
  */
@@ -78,6 +268,7 @@ export interface InteractionEndpoint {
     visibility?: InteractionVisibility;
     version: number;
     tags: string[];
+    agent_runner_options?: AgentRunnerOptions;
     output_modality?: Modalities;
     result_schema?: JSONSchema;
     params_schema?: JSONSchema;
@@ -93,11 +284,12 @@ export interface InteractionRef {
     visibility?: InteractionVisibility;
     version: number;
     tags: string[];
+    agent_runner_options?: AgentRunnerOptions;
     prompts?: PromptSegmentDef<PromptTemplateRef>[];
     updated_at: Date;
 }
 export const InteractionRefPopulate =
-    "id name endpoint parent description status version visibility tags updated_at prompts";
+    "id name endpoint parent description status version visibility tags agent_runner_options updated_at prompts";
 
 export const InteractionRefWithSchemaPopulate =
     `${InteractionRefPopulate} result_schema`;
@@ -167,28 +359,32 @@ export interface CachePolicy {
     ttl: number;
 }
 export type InteractionVisibility = "public" | "private";
-export interface Interaction {
+
+export interface InteractionData {
     readonly id: string;
     name: string;
     endpoint: string;
     description?: string;
+    project: string | ProjectRef;
+    tags: string[];
+    agent_runner_options?: AgentRunnerOptions;
+    result_schema?: JSONSchema4 | SchemaRef;
+    environment?: string | ExecutionEnvironmentRef;
+    model?: string;
+    model_options?: ModelOptions;
+    restriction?: RunDataStorageLevel;
+    output_modality?: Modalities;
+}
+export interface Interaction extends InteractionData {
     status: InteractionStatus;
     parent?: string;
     // only used for versions (status === "published")
     visibility: InteractionVisibility;
     version: number;
-    tags: string[];
     test_data?: JSONObject;
     interaction_schema?: JSONSchema4 | SchemaRef;
-    result_schema?: JSONSchema4 | SchemaRef;
     cache_policy?: CachePolicy;
-    model: string;
-    model_options?: ModelOptions;
     prompts: PromptSegmentDef[];
-    output_modality?: Modalities;
-    environment: string | ExecutionEnvironmentRef;
-    restriction?: RunDataStorageLevel;
-    project: string | ProjectRef;
     // only for drafts - when it was last published
     last_published_at?: Date;
     created_by: string;
@@ -201,6 +397,14 @@ export interface PopulatedInteraction extends Omit<Interaction, "prompts"> {
     prompts: PopulatedPromptSegmentDef[];
 }
 
+/**
+ * Used to describe an interaction that can be executed. Contains only the interaction data useful
+ * to execute the interaction plus the prompt templates
+ */
+export interface ExecutableInteraction extends InteractionData {
+    prompts: ExecutablePromptSegmentDef[];
+}
+
 export interface InteractionCreatePayload
     extends Omit<
         Interaction,
@@ -218,6 +422,7 @@ export interface InteractionCreatePayload
         | "endpoint"
     > {
     visibility?: InteractionVisibility;
+    tags?: string[];
 }
 
 export interface InteractionUpdatePayload
@@ -271,6 +476,12 @@ export interface InteractionExecutionPayload {
      * The workflow related to this Interaction Run.
      */
     workflow?: ExecutionRunWorkflow;
+
+    /**
+     * Only used by ad-hoc interactions which defines the prompt in the execution payload itself
+     * These are temporary interactions using "tmp:" suffix.
+     */
+    prompts?: InCodePrompt[];
 }
 
 export interface NamedInteractionExecutionPayload extends InteractionExecutionPayload {
@@ -298,11 +509,58 @@ interface AsyncExecutionPayloadBase extends Omit<NamedInteractionExecutionPayloa
 
 export type ConversationVisibility = 'private' | 'project';
 
+/**
+ * Defines the scope for agent search operations.
+ */
+export enum AgentSearchScope {
+    /**
+     * Search is scoped to a specific collection.
+     */
+    Collection = 'collection'
+}
+
+/**
+ * Configuration options for Agent Runner functionality.
+ * These options control how interactions are exposed and executed in the Agent Runner.
+ */
+export interface AgentRunnerOptions {
+    /**
+     * Whether this interaction is an agent (executable in Agent Runner).
+     */
+    is_agent?: boolean;
+
+    /**
+     * Whether this interaction is available as a tool (sub-agent).
+     */
+    is_tool?: boolean;
+
+    /**
+     * Array of default tool names available to this agent.
+     * For interactions: defines default tools.
+     * For execution payloads: you can use + and - to add or remove from default,
+     * if no sign, then list replaces default.
+     */
+    tool_names?: string[];
+
+    /**
+     * On which scope should the search be applied by the search_tool.
+     * Only supports 'collection' scope or undefined for now.
+     */
+    search_scope?: AgentSearchScope;
+
+    /**
+     * The ID of the collection to restrict agent operations to.
+     * When specified, the agent's search and retrieval operations are limited to documents
+     * within this collection'.
+     */
+    collection_id?: string;
+}
+
 export interface AsyncConversationExecutionPayload extends AsyncExecutionPayloadBase {
     type: "conversation";
 
-    /** 
-    * Visibility determine if the conversation should be seen by the user only or by anyone with access to the project 
+    /**
+    * Visibility determine if the conversation should be seen by the user only or by anyone with access to the project
     * If not specified, the default is project
     **/
     visibility?: ConversationVisibility;
@@ -332,7 +590,7 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
      * On which scope should the searched by applied, by the search_tool.
      * Only supports collection scope or null for now.
      */
-    search_scope?: string;
+    search_scope?: AgentSearchScope.Collection;
 
     /**
      * The collection in which this workflow is executing
@@ -424,7 +682,7 @@ export interface RunSource {
     client_ip: string;
 }
 
-export interface ExecutionRun<P = any> {
+export interface BaseExecutionRun<P = any> {
     readonly id: string;
     /**
      * Only used by runs that were created by a virtual run to point toward the virtual run parent
@@ -443,8 +701,12 @@ export interface ExecutionRun<P = any> {
      */
     parameters: P; //params used to create the interaction, only in varies on?
     tags?: string[];
-    //TODO a string is returned when executing not the interaction object
-    interaction: Interaction;
+    // only set when the target interaction is a stored interaction
+    //TODO check the code where Interaction type is used (should be in run details)
+    // TODO when execution string is passed as the type of interaction
+    interaction?: string | Interaction;
+    // only set when the target interaction is an in-code interaction
+    interaction_code?: string; // Interaction code name in case of in-code interaction (not stored in the DB as an Interaction document)
     //TODO a string is returned when execution not the env object
     environment: ExecutionEnvironmentRef;
     modelId: string;
@@ -477,6 +739,14 @@ export interface ExecutionRun<P = any> {
     workflow?: ExecutionRunWorkflow;
 }
 
+export interface ExecutionRun<P = any> extends BaseExecutionRun<P> {
+    interaction?: Interaction;
+}
+
+export interface PopulatedExecutionRun<P = any> extends BaseExecutionRun<P> {
+    interaction?: Interaction;
+}
+
 export interface ExecutionRunWorkflow {
     /**
      * The Temporal Workflow Run ID related to this Interaction Run.
@@ -510,7 +780,8 @@ export interface InteractionExecutionResult<P = any> extends ExecutionRun<P> {
 }
 
 export interface ExecutionRunRef extends Omit<ExecutionRun, "result" | "parameters" | "interaction"> {
-    interaction: InteractionRef;
+    interaction?: InteractionRef;
+    interaction_code?: string;
 }
 
 export const ExecutionRunRefSelect = "-result -parameters -result_schema -prompt";
@@ -553,10 +824,17 @@ export interface GenerateTestDataPayload {
     config: InteractionExecutionConfiguration;
 }
 
-export interface ImprovePromptPayload {
+export interface ImprovePromptPayloadConfig {
     config: InteractionExecutionConfiguration;
 }
 
+export interface ImprovePromptPayload extends ImprovePromptPayloadConfig {
+    interaction_name: string; // name of the interaction to improve
+    context?: string,
+    prompt: { name: string, content: string }[]; // prompt array
+    result_schema?: JSONSchema, // optional interactionr result schema
+}
+
 export interface RateLimitRequestPayload {
     interaction: string,
     environment_id?: string,

package/src/project.ts

@@ -69,6 +69,8 @@ export interface ProjectConfiguration {
     default_environment?: string;
     default_model?: string;
 
+    sync_content_properties?: boolean;
+
     embeddings: {
         text?: ProjectConfigurationEmbeddings;
         image?: ProjectConfigurationEmbeddings;
@@ -140,11 +142,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,