@vertesia/common 0.77.0 → 0.78.0-dev-9372725

package/package.json

@@ -1,40 +1,45 @@
 {
-  "name": "@vertesia/common",
-  "version": "0.77.0",
-  "type": "module",
-  "types": "./lib/types/index.d.ts",
-  "files": [
-    "lib",
-    "src",
-    "tsconfig.dist.json"
-  ],
-  "exports": {
+    "name": "@vertesia/common",
+    "version": "0.78.0-dev-9372725",
+    "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

@@ -43,9 +43,9 @@ export enum Permission {
     workflow_run = "workflow:run",
     workflow_admin = "workflow:admin",
 
-    /**
-     * whether the user has access to Sutdio App.
-     */
+    iam_impersonate = "iam:impersonate",
+
+    /** whether the user has access to Sutdio App. */
     studio_access = "studio:access",
 }
 
@@ -60,6 +60,7 @@ export enum AccessControlResourceType {
 export enum AccessControlPrincipalType {
     user = "user",
     group = "group",
+    apikey = "apikey",
 }
 
 
@@ -93,4 +94,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,19 +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

@@ -1,3 +1,4 @@
+import { JSONSchema } from "@llumiverse/common";
 
 export interface AppUIConfig {
     /**
@@ -14,6 +15,33 @@ export interface AppUIConfig {
     isolation?: "shadow" | "css";
 }
 
+export interface AppInteractionRef {
+    /**
+     * The interaction code name
+     */
+    name: string;
+
+    /**
+     * The url to get the interaction specification
+    */
+    url: string;
+
+    /**
+     * The interaction title. Optional. To be used in studio UI when the interaction is displayed
+     */
+    title?: string;
+
+    /**
+     * The interaction description. Optional. To be used in studio UI when the interaction is displayed
+     */
+    description?: string;
+}
+export interface ResolvedAppInteractionRef extends AppInteractionRef {
+    /**
+     * The interaction unique name (can also be used as an ID) that can be used to execute the interaction.
+     */
+    id: string;
+}
 export interface AppManifestData {
     /**
      * The name of the app, used as the id in the system.
@@ -36,6 +64,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 +80,18 @@ 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[]
+
+    /**
+     * An URL providing interactions definitions in JSON format.
+     * GET interactions_url should return a JSON object with the interactions definitions.
+     * GET `${interactions_url}/${endpoint}` should return a JSON object with the interaction definition for the specified endpoint.
+     */
+    interactions?: AppInteractionRef[];
+
+    /**
+     * A JSON chema for the app installation settings.
+     */
+    settings_schema?: JSONSchema;
 }
 export interface AppManifest extends AppManifestData {
     id: string;
@@ -73,3 +119,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,5 @@ 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 './sts-token-types.js';

package/src/interaction.ts

@@ -1,8 +1,10 @@
 import type {
+    CompletionResult,
     JSONObject,
     JSONSchema,
     Modalities,
     ModelOptions,
+    PromptRole,
     StatelessExecutionOptions,
     ToolDefinition,
     ToolUse,
@@ -14,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";
@@ -28,6 +32,79 @@ export interface InteractionExecutionError {
     data?: any;
 }
 
+
+// ------------------ in code interactions -----------------
+export interface InCodePrompt {
+    role: PromptRole,
+    content: string,
+    content_type: TemplateType;
+    schema?: JSONSchema;
+}
+export interface InCodeInteraction {
+    /**
+     * 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;
+
+    /**
+     * 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;
+
+    /**
+     * 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[];
+
+    /**
+     * 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[]
+
+}
+export interface InteractionSpec extends Omit<InCodeInteraction, 'id'> {
+}
+// ---------------------------------------------------------
+
 /**
  * The payload to query the interaction endpoints
  */
@@ -166,28 +243,31 @@ 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[];
+    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;
@@ -200,6 +280,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,
@@ -270,6 +358,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 {
@@ -284,7 +378,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 +475,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 +496,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 +517,7 @@ export interface RunSource {
     client_ip: string;
 }
 
-export interface ExecutionRun<P = any, R = 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
@@ -430,7 +528,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
@@ -438,8 +536,12 @@ export interface ExecutionRun<P = any, R = 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;
@@ -450,7 +552,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;
@@ -472,6 +574,14 @@ export interface ExecutionRun<P = any, R = any> {
     workflow?: ExecutionRunWorkflow;
 }
 
+export interface ExecutionRun<P = any> extends BaseExecutionRun<P> {
+    interaction?: string;
+}
+
+export interface PopulatedExecutionRun<P = any> extends BaseExecutionRun<P> {
+    interaction?: Interaction;
+}
+
 export interface ExecutionRunWorkflow {
     /**
      * The Temporal Workflow Run ID related to this Interaction Run.
@@ -498,14 +608,15 @@ 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;
 }
 
 export interface ExecutionRunRef extends Omit<ExecutionRun, "result" | "parameters" | "interaction"> {
-    interaction: InteractionRef;
+    interaction?: InteractionRef;
+    interaction_code?: string;
 }
 
 export const ExecutionRunRefSelect = "-result -parameters -result_schema -prompt";
@@ -551,3 +662,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

@@ -142,9 +142,7 @@ export interface EmbeddingsStatusResponse {
     status: string;
     embeddingRunsInProgress: number;
     totalRunsInProgress: number;
-    totalIndexableObjects: number;
     embeddingsModels: string[];
-    objectsWithEmbeddings: number;
     vectorIndex: {
         status: "READY" | "PENDING" | "DELETING" | "ABSENT",
         name?: string,

package/src/prompt.ts

@@ -1,7 +1,7 @@
-import type { JSONSchema4 } from "json-schema";
 import type { JSONObject } from "@llumiverse/common";
-import { ProjectRef } from "./project.js";
 import { PromptRole } from "@llumiverse/common";
+import type { JSONSchema4 } from "json-schema";
+import { ProjectRef } from "./project.js";
 
 export interface ChatPromptSchema {
     role: PromptRole.user | PromptRole.assistant;
@@ -31,6 +31,13 @@ export interface PopulatedPromptSegmentDef
     extends Omit<PromptSegmentDef, "template"> {
     template?: PromptTemplate;
 }
+/**
+ * Used for prompt rendering at interaction execution
+ */
+export interface ExecutablePromptSegmentDef
+    extends Omit<PromptSegmentDef, "template"> {
+    template?: ExecutablePromptTemplate;
+}
 
 export interface PromptTemplateRef {
     id: string;
@@ -47,25 +54,25 @@ export interface PromptTemplateRefWithSchema extends PromptTemplateRef {
 
 export enum TemplateType {
     text = "text",
-    js = "js",
     jst = "jst",
 }
-
-export interface PromptTemplate {
+export interface ExecutablePromptTemplate {
+    role: PromptRole;
+    content: string;
+    content_type: TemplateType;
+    inputSchema?: JSONSchema4;
+}
+export interface PromptTemplate extends ExecutablePromptTemplate {
     id: string;
     name: string;
-    role: PromptRole;
     status: PromptStatus;
     version: number;
     // only to be used by published versions
     // the id draft version which is the source of this published version (only when published)
     parent?: string;
     description?: string;
-    content_type: TemplateType;
-    content: string;
     test_data?: JSONObject; // optional test data satisfying the schema
     script?: string; // cache the template output
-    inputSchema?: JSONSchema4;
     project: string | ProjectRef; // or projectRef? ObjectIdType;
     // The name of a field in the input data that is of the specified schema and on each the template will iterate.
     // If not specified then the schema will define the whole input data