@vertesia/common 0.51.0 → 0.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "0.51.0",
+  "version": "0.54.0",
   "type": "module",
   "types": "./lib/types/index.d.ts",
   "files": [
@@ -16,13 +16,13 @@
     "@types/json-schema": "^7.0.15",
     "ts-dual-module": "^0.6.3",
     "typescript": "^5.0.2",
-    "vitest": "^2.1.9"
+    "vitest": "^3.0.9"
   },
   "dependencies": {
     "ajv": "^8.16.0",
     "json-schema": "^0.4.0",
     "mime": "^4.0.4",
-    "@llumiverse/core": "0.15.0"
+    "@llumiverse/core": "0.17.0"
   },
   "ts_dual_module": {
     "outDir": "lib"

package/src/apikey.ts

@@ -64,5 +64,5 @@ export interface AuthTokenPayload {
 export enum PrincipalType {
     User = "user",
     ApiKey = "apikey",
-    ServiceAcount = "service_account",
+    ServiceAccount = "service_account",
 }

package/src/common.ts

@@ -1,7 +1,10 @@
 export interface FindPayload {
     query: Record<string, any>;
+    offset?: number;
     limit?: number;
     select?: string;
+    show_all_revisions?: boolean;
+    from_root?: string;
 }
 
 

package/src/index.ts

@@ -8,6 +8,7 @@ export * from './integrations.js';
 export * from './interaction.js';
 export * from './meters.js';
 export * from './payload.js';
+export * from "./plugin.js";
 export * from "./Progress.js";
 export * from './project.js';
 export * from './prompt.js';
@@ -21,4 +22,3 @@ export * from './user.js';
 export * from './utils/advanced-content-processing.js';
 export * from './utils/auth.js';
 export * from './utils/schemas.js';
-

package/src/integrations.ts

@@ -18,7 +18,7 @@ export interface AwsConfiguration extends IntegrationConfigurationBase {
     s3_role_arn: string;
 }
 
-export interface MacgicPdfConfiguration extends IntegrationConfigurationBase {
+export interface MagicPdfConfiguration extends IntegrationConfigurationBase {
     // No additional configuration
     default_features?: string[];
     default_zones?: string[];

package/src/interaction.ts

@@ -1,12 +1,26 @@
-import type { JSONObject, Modalities, ModelOptions } from "@llumiverse/core";
-import { JSONSchema4 } from 'json-schema';
-
-import { ExecutionTokenUsage } from '@llumiverse/core';
-
-import { ExecutionEnvironmentRef } from './environment.js';
-import { ProjectRef } from './project.js';
-import { PopulatedPromptSegmentDef, PromptSegmentDef, PromptTemplateRef, PromptTemplateRefWithSchema } from './prompt.js';
-import { AccountRef } from './user.js';
+import type {
+    JSONObject,
+    JSONSchema,
+    Modalities,
+    ModelOptions,
+    StatelessExecutionOptions,
+    ToolDefinition,
+    ToolUse,
+} from "@llumiverse/core";
+import { JSONSchema4 } from "json-schema";
+
+import { ExecutionTokenUsage } from "@llumiverse/core";
+
+import { ExecutionEnvironmentRef } from "./environment.js";
+import { ProjectRef } from "./project.js";
+import {
+    PopulatedPromptSegmentDef,
+    PromptSegmentDef,
+    PromptTemplateRef,
+    PromptTemplateRefWithSchema,
+} from "./prompt.js";
+import { ExecutionRunDocRef } from "./runs.js";
+import { AccountRef } from "./user.js";
 
 export interface InteractionExecutionError {
     code: string;
@@ -14,9 +28,63 @@ export interface InteractionExecutionError {
     data?: any;
 }
 
+/**
+ * The payload to query the interaction endpoints
+ */
+export interface InteractionEndpointQuery {
+    limit?: number;
+    offset?: number;
+
+    status?: InteractionStatus;
+    visibility?: InteractionVisibility;
+    version?: number;
+    tags?: string[];
+
+    /**
+     * Filter by interaction endpoint name to include only the specified endpoints
+     * * If both includes and excludes are specified then only the includes filter will be used.
+     */
+    includes?: string[];
+
+    /**
+     * Filter by interaction endpoint name to excludes the specified endpoints.
+     * If both includes and excludes are specified then only the includes filter will be used.
+     */
+    excludes?: string[];
+
+    /**
+     * Whether or not to return the parameters schema.
+     * The parameters schema is an array of JSON schemas.
+     * Each schema is a JSON schema that describes the parameters of an interaction prompt.
+     */
+    include_params_schema?: boolean;
+
+    /**
+     * Whether or not to return the result schema
+     */
+    include_result_schema?: boolean;
+}
+
+/**
+ * A description of an interaction endpoint.
+ */
+export interface InteractionEndpoint {
+    id: string;
+    name: string;
+    endpoint: string;
+    description?: string;
+    status: InteractionStatus;
+    visibility?: InteractionVisibility;
+    version: number;
+    tags: string[];
+    result_schema?: JSONSchema;
+    params_schema?: JSONSchema;
+}
+
 export interface InteractionRef {
     id: string;
     name: string;
+    endpoint: string;
     parent?: string;
     description?: string;
     status: InteractionStatus;
@@ -26,17 +94,17 @@ export interface InteractionRef {
     prompts?: PromptSegmentDef<PromptTemplateRef>[];
     updated_at: Date;
 }
-export const InteractionRefPopulate = "id name parent description status version visibility tags updated_at prompts";
+export const InteractionRefPopulate =
+    "id name endpoint parent description status version visibility tags updated_at prompts";
 
-export interface InteractionRefWithSchema
-    extends Omit<InteractionRef, "prompts"> {
+export interface InteractionRefWithSchema extends Omit<InteractionRef, "prompts"> {
     result_schema?: JSONSchema4;
     prompts?: PromptSegmentDef<PromptTemplateRefWithSchema>[];
 }
 
 export interface InteractionsExportPayload {
     /**
-     * The name of the interaction. If not spcified all the interactions in the current project will be exported
+     * The name of the interaction. If not specified all the interactions in the current project will be exported
      */
     name?: string;
     /*
@@ -46,7 +114,7 @@ export interface InteractionsExportPayload {
     /*
      * if not specified, all versions will be exported
      */
-    versions?: (number | 'draft' | 'latest')[];
+    versions?: (number | "draft" | "latest")[];
 }
 
 export enum InteractionStatus {
@@ -65,20 +133,20 @@ export enum ExecutionRunStatus {
 export enum RunDataStorageLevel {
     STANDARD = "STANDARD",
     RESTRICTED = "RESTRICTED",
-    DEBUG = "DEBUG"
+    DEBUG = "DEBUG",
 }
 
 export enum RunDataStorageDescription {
     STANDARD = "Run data is stored for both the model inputs and output.",
     RESTRICTED = "No run data is stored for the model inputs — only the model output.",
-    DEBUG = "Run data is stored for the model inputs and output, schema, and final prompt."
+    DEBUG = "Run data is stored for the model inputs and output, schema, and final prompt.",
 }
 
 export const RunDataStorageOptions: Record<RunDataStorageLevel, RunDataStorageDescription> = {
     [RunDataStorageLevel.STANDARD]: RunDataStorageDescription.STANDARD,
     [RunDataStorageLevel.RESTRICTED]: RunDataStorageDescription.RESTRICTED,
     [RunDataStorageLevel.DEBUG]: RunDataStorageDescription.DEBUG,
-}
+};
 
 /**
  * Schema can be stored or specified as a reference to an external schema.
@@ -93,7 +161,7 @@ export interface CachePolicy {
     varies_on: string[];
     ttl: number;
 }
-export type InteractionVisibility = 'public' | 'private';
+export type InteractionVisibility = "public" | "private";
 export interface Interaction {
     readonly id: string;
     name: string;
@@ -118,21 +186,31 @@ export interface Interaction {
     project: string | ProjectRef;
     // only for drafts - when it was last published
     last_published_at?: Date;
-    created_by: string,
-    updated_by: string,
+    created_by: string;
+    updated_by: string;
     created_at: Date;
     updated_at: Date;
 }
 
-export interface PopulatedInteraction
-    extends Omit<Interaction, "prompts"> {
+export interface PopulatedInteraction extends Omit<Interaction, "prompts"> {
     prompts: PopulatedPromptSegmentDef[];
 }
 
 export interface InteractionCreatePayload
     extends Omit<
         Interaction,
-        "id" | "created_at" | "updated_at" | "created_by" | "updated_by" | "project" | "formatter" | "tags" | "parent" | "version" | "visibility" | "endpoint"
+        | "id"
+        | "created_at"
+        | "updated_at"
+        | "created_by"
+        | "updated_by"
+        | "project"
+        | "formatter"
+        | "tags"
+        | "parent"
+        | "version"
+        | "visibility"
+        | "endpoint"
     > {
     visibility?: InteractionVisibility;
 }
@@ -158,11 +236,10 @@ export interface InteractionForkPayload {
     targetProject?: string;
 }
 
-
 export interface InteractionExecutionPayload {
     /**
      * If a `@memory` property exists on the input data then the value will be used as the value of a memory pack location.
-     * and the other proerties of the data will contain the memory pack mapping.
+     * and the other properties of the data will contain the memory pack mapping.
      */
     data?: Record<string, any> | `memory:${string}`;
     config?: InteractionExecutionConfiguration;
@@ -170,6 +247,20 @@ export interface InteractionExecutionPayload {
     stream?: boolean;
     do_validate?: boolean;
     tags?: string | string[]; // tags to be added to the execution run
+
+    /**
+     * The conversation state to be used in the execution if any.
+     * If the `true` is passed then the conversation will be returned in the result.
+     * The true value must be used for the first execution that starts the conversation.
+     * If conversation is falsy then no conversation is returned back.
+     * For regular executions the conversation is not returned back to save memory.
+     */
+    conversation?: true | unknown;
+
+    /**
+     * The tools to be used in the execution
+     */
+    tools?: ToolDefinition[];
 }
 
 export interface NamedInteractionExecutionPayload extends InteractionExecutionPayload {
@@ -181,6 +272,133 @@ export interface NamedInteractionExecutionPayload extends InteractionExecutionPa
     interaction: string;
 }
 
+// ================= async execution payloads ====================
+export type ToolRef = string | { name: string; description: string };
+
+interface AsyncExecutionPayloadBase {
+    type: "conversation" | "interaction";
+
+    /**
+     * The interaction endpoint to execute to start the conversation.
+     */
+    interaction: string;
+
+    /**
+     * The environment ID to use.
+     */
+    environment?: string;
+
+    /**
+     * The model to use
+     */
+    model?: string;
+
+    /**
+     * The options to use on the first execution
+     */
+    model_options?: ModelOptions;
+
+    /**
+     * The initial prompt input data
+     */
+    prompt_data?: Record<string, any>;
+
+    /**
+     * Optional result schema
+     */
+    result_schema?: JSONSchema;
+
+    /**
+     * Optional tags to add to the execution run
+     */
+    tags?: string[];
+}
+
+export interface AsyncConversationExecutionPayload extends AsyncExecutionPayloadBase {
+    type: "conversation";
+
+    /**
+     * The tools to use
+     */
+    tools?: ToolRef[];
+
+    /**
+     * The maximum number of iterations in case of a conversation. If <=0 the default of 20 will be used.
+     */
+    max_iterations?: number;
+
+    /**
+     * Whether the conversation should be interactive or not
+     */
+    interactive?: boolean;
+
+    /**
+     * Whether to disable the generation of interaction tools or not.
+     */
+    disable_interaction_tools?: boolean;
+
+    /**
+     * On which scope should the searched by applied, by the search_tool.
+     * Only supports collection scope or null for now.
+     */
+    search_scope?: string;
+
+    /**
+     * The collection in which this workflow is executing
+     */
+    collection_id?: string;
+
+    /**
+     * The token threshold in thousands (K) for creating checkpoints.
+     * If total tokens exceed this value, a checkpoint will be created.
+     * If not specified, default value of 150K tokens will be used.
+     */
+    checkpoint_tokens?: number;
+}
+
+export interface AsyncInteractionExecutionPayload extends AsyncExecutionPayloadBase {
+    type: "interaction";
+
+    /**
+     * The tools to use
+     */
+    tools?: ToolDefinition[];
+
+    /**
+     * Only used for non conversation workflows to include the error on next retry.
+     * If tools is defined this is not used
+     */
+    include_previous_error?: boolean;
+}
+
+export type AsyncExecutionPayload = AsyncConversationExecutionPayload | AsyncInteractionExecutionPayload;
+
+interface ResumeConversationPayload {
+    run: ExecutionRunDocRef; // the run created by the first execution.
+    environment: string; // the environment ID
+    options: StatelessExecutionOptions; // the options used on the first execution
+    conversation: unknown; // the conversation state
+    tools: ToolDefinition[]; // the tools to be used
+}
+
+/**
+ * The payload to sent the tool responses back to the target LLM
+ */
+export interface ToolResultsPayload extends ResumeConversationPayload {
+    results: {
+        tool_use_id: string;
+        content: string;
+    }[];
+}
+
+export interface UserMessagePayload extends ResumeConversationPayload {
+    message: string;
+}
+
+export type CheckpointConversationPayload = Omit<ToolResultsPayload, "results">;
+
+// ================= end async execution payloads ====================
+
 export enum RunSourceTypes {
     api = "api",
     cli = "cli",
@@ -193,7 +411,7 @@ export enum RunSourceTypes {
 export interface RunSource {
     type: RunSourceTypes;
     label: string;
-    principal_type: 'user' | 'apikey';
+    principal_type: "user" | "apikey";
     principal_id: string;
     client_ip: string;
 }
@@ -205,15 +423,15 @@ export interface ExecutionRun<P = any, R = any> {
      */
     parent?: string | ExecutionRun;
     evaluation?: {
-        score?: number,
-        selected?: boolean,
-        scores?: Record<string, number>
-    }
+        score?: number;
+        selected?: boolean;
+        scores?: Record<string, number>;
+    };
     result: R;
     /**
      * The parameters used to create the interaction.
      * If the parameters contains the special property "@memory" it will be used
-     * to locate a meory pack and the other properties will be used as the memory pack mapping.
+     * to locate a memory pack and the other properties will be used as the memory pack mapping.
      */
     parameters: P; //params used to create the interaction, only in varies on?
     tags?: string[];
@@ -238,12 +456,17 @@ export interface ExecutionRun<P = any, R = any> {
     error?: InteractionExecutionError;
     source: RunSource;
     output_modality: Modalities;
-    created_by: string,
-    updated_by: string,
+    created_by: string;
+    updated_by: string;
 }
 
-export interface ExecutionRunRef
-    extends Omit<ExecutionRun, "result" | "parameters" | "interaction"> {
+export interface InteractionExecutionResult<P = any, R = any> extends ExecutionRun<P, R> {
+    tool_use?: ToolUse[];
+    conversation?: unknown;
+    options?: StatelessExecutionOptions;
+}
+
+export interface ExecutionRunRef extends Omit<ExecutionRun, "result" | "parameters" | "interaction"> {
     interaction: InteractionRef;
 }
 
@@ -252,20 +475,20 @@ export const ExecutionRunRefSelect = "-result -parameters -result_schema -prompt
 export enum ConfigModes {
     RUN_AND_INTERACTION_CONFIG = "RUN_AND_INTERACTION_CONFIG",
     RUN_CONFIG_ONLY = "RUN_CONFIG_ONLY",
-    INTERACTION_CONFIG_ONLY = "INTERACTION_CONFIG_ONLY"
-};
+    INTERACTION_CONFIG_ONLY = "INTERACTION_CONFIG_ONLY",
+}
 
 export enum ConfigModesDescription {
     RUN_AND_INTERACTION_CONFIG = "This run configuration is used. Undefined options are filled with interaction configuration.",
     RUN_CONFIG_ONLY = "Only this run configuration is used. Undefined options remain undefined.",
-    INTERACTION_CONFIG_ONLY = "Only interaction configuration is used."
+    INTERACTION_CONFIG_ONLY = "Only interaction configuration is used.",
 }
 
 export const ConfigModesOptions: Record<ConfigModes, ConfigModesDescription> = {
     [ConfigModes.RUN_AND_INTERACTION_CONFIG]: ConfigModesDescription.RUN_AND_INTERACTION_CONFIG,
     [ConfigModes.RUN_CONFIG_ONLY]: ConfigModesDescription.RUN_CONFIG_ONLY,
     [ConfigModes.INTERACTION_CONFIG_ONLY]: ConfigModesDescription.INTERACTION_CONFIG_ONLY,
-}
+};
 
 export interface InteractionExecutionConfiguration {
     environment?: string;
@@ -289,4 +512,4 @@ export interface GenerateTestDataPayload {
 
 export interface ImprovePromptPayload {
     config: InteractionExecutionConfiguration;
-}
+}

package/src/meters.ts

@@ -1,6 +1,4 @@
-
-
-
+import { BillingMethod } from "./user.js";
 
 
 export interface MeterAdjustment {
@@ -21,4 +19,12 @@ export enum MeterNames {
     input_token_used = 'input_token_used',
     output_token_used = 'output_token_used',
     task_run = 'task_run',
+}
+
+
+export interface StripeBillingStatusResponse {
+    status: 'enabled' | 'disabled',
+    billing_method: BillingMethod | null,
+    portal_url?: string,
+    reason?: string
 }

package/src/payload.ts

@@ -1,10 +1,22 @@
-import { FacetSpec } from './facets.js';
-import { ComplexSearchQuery, InteractionSearchQuery, ObjectSearchQuery, ObjectTypeSearchQuery, PromptSearchQuery, RunSearchQuery, SimpleSearchQuery, VectorSearchQuery } from './query.js';
+import { FacetSpec } from "./facets.js";
+import {
+    ComplexSearchQuery,
+    InteractionSearchQuery,
+    ObjectSearchQuery,
+    ObjectTypeSearchQuery,
+    PromptSearchQuery,
+    RunSearchQuery,
+    SimpleSearchQuery,
+    VectorSearchQuery,
+} from "./query.js";
 
 export interface SearchPayload {
     query?: SimpleSearchQuery;
     limit?: number;
     offset?: number;
+    select?: string;
+    show_all_revisions?: boolean;
+    from_root?: string;
 }
 
 export interface ComputeFacetPayload {
@@ -59,4 +71,4 @@ export interface ExportPropertiesResponse {
     type: string;
     name: string;
     data: Blob;
-}
+}

package/src/plugin.ts

@@ -0,0 +1,12 @@
+/**
+ * A vertesia plugin manifest
+ */
+export interface PluginManifest {
+    id: string;
+    src: string;
+    name: string;
+    version: string;
+    publisher: string;
+    description?: string;
+    icon?: string;
+}

package/src/project.ts

@@ -5,6 +5,7 @@ export interface ICreateProjectPayload {
     name: string;
     namespace: string;
     description?: string;
+    auto_config?: boolean;
 }
 export enum ProjectRoles {
     owner = "owner", // all permissions
@@ -43,6 +44,12 @@ export interface ProjectRef {
     id: string;
     name: string;
     account: string;
+    /**
+     * Only set when fetching the list of projects visible to an user which is an org admin or owner.
+     * If present and true, it means that the project is not accessible to the user.(even if it visible in listing)
+     * If not present or false then the project is accessible to the user.
+     */
+    restricted?: boolean;
 }
 
 export enum ResourceVisibility {
@@ -99,6 +106,7 @@ export interface Project {
     account: string;
     configuration: ProjectConfiguration;
     integrations: Map<string, any>;
+    plugins: string[];
     created_by: string,
     updated_by: string,
     created_at: Date;

package/src/prompt.ts

@@ -68,7 +68,7 @@ export interface PromptTemplate {
     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 sceham will define the whole input data
+    // If not specified then the schema will define the whole input data
     tags?: string[];
     // only for drafts - when it was last published
     last_published_at?: Date;

package/src/query.ts

@@ -3,14 +3,14 @@ import { SupportedEmbeddingTypes } from './project.js';
 
 export interface RunListingQueryOptions {
     project?: string;
-    interaction?: string;
+    interaction?: string | string[];
     limit?: number;
     offset?: number;
     filters?: RunListingFilters;
 }
 
 export interface RunListingFilters {
-    interaction?: string,
+    interaction?: string | string[],
     status?: ExecutionRunStatus,
     model?: string,
     environment?: string,
@@ -43,11 +43,12 @@ export interface ObjectSearchQuery extends SimpleSearchQuery {
 }
 
 export interface ObjectTypeSearchQuery extends SimpleSearchQuery {
-    chunckable?: boolean;
+    chunkable?: boolean;
 }
 
 export interface PromptSearchQuery extends SimpleSearchQuery {
     role?: string;
+    matchInteractions?: boolean;
 }
 
 export interface InteractionSearchQuery extends SimpleSearchQuery {
@@ -84,4 +85,5 @@ export interface WorkflowExecutionSearchQuery extends SimpleSearchQuery {
 
 export interface ComplexSearchQuery extends ObjectSearchQuery {
     vector?: VectorSearchQuery;
+    match?: Record<string, any>;
 }

package/src/runs.ts

@@ -1,9 +1,18 @@
 import { FacetResult } from './facets.js';
 import { NamedInteractionExecutionPayload } from './interaction.js';
 
+/**
+ * The run ref is used to identify a run document in the storage
+ */
+export interface ExecutionRunDocRef {
+    id: string,
+    account: string,
+    project: string,
+}
+
 /**
  * Interaction execution payload for creating a new run
- * It uses interaction field (from NamedInteractionExecutionPayload) to pass the intercation ID to run
+ * It uses interaction field (from NamedInteractionExecutionPayload) to pass the interaction ID to run
  */
 export interface RunCreatePayload extends NamedInteractionExecutionPayload {
 }
@@ -18,7 +27,7 @@ export interface RangeValue {
     lte?: number | string,
 }
 
-export interface RunSearchMetaRepsonse {
+export interface RunSearchMetaResponse {
     count: {
         lower_bound?: number,
         total?: number,