@vertesia/common 0.50.1 → 0.52.0

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,64 @@ 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 omly 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 omly 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;
     visibility?: InteractionVisibility;
@@ -25,10 +94,10 @@ export interface InteractionRef {
     prompts?: PromptSegmentDef<PromptTemplateRef>[];
     updated_at: Date;
 }
-export const InteractionRefPopulate = "id name 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>[];
 }
@@ -45,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 {
@@ -64,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.
@@ -92,8 +161,8 @@ export interface CachePolicy {
     varies_on: string[];
     ttl: number;
 }
-export type InteractionVisibility = 'public' | 'private';
-export interface Interaction extends ModelOptions {
+export type InteractionVisibility = "public" | "private";
+export interface Interaction {
     readonly id: string;
     name: string;
     endpoint: string;
@@ -105,9 +174,11 @@ export interface Interaction extends ModelOptions {
     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;
@@ -115,21 +186,31 @@ export interface Interaction extends ModelOptions {
     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;
 }
@@ -139,21 +220,9 @@ export interface InteractionUpdatePayload
         Omit<
             Interaction,
             "result_schema" | "id" | "created_at" | "updated_at" | "created_by" | "updated_by" | "project"
-            | "temperature" | "max_tokens" | "stop_sequence" | "top_k" | "top_p" | "presence_penalty" | "frequency_penalty" | "top_logprobs"
         >
     > {
     result_schema?: JSONSchema4 | null;
-
-    // Change ModelOptions properties to include null as a possible type
-    // Null values indicate that the property should be cleared.
-    temperature?: number | null;
-    max_tokens?: number | null;
-    stop_sequence?: string[] | null;
-    top_k?: number | null;
-    top_p?: number | null;
-    top_logprobs?: number | null;
-    presence_penalty?: number | null;
-    frequency_penalty?: number | null;
 }
 
 export interface InteractionPublishPayload {
@@ -167,7 +236,6 @@ 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.
@@ -179,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 {
@@ -190,6 +272,115 @@ 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;
+}
+
+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",
@@ -202,7 +393,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;
 }
@@ -214,10 +405,10 @@ 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.
@@ -247,12 +438,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;
 }
 
@@ -261,27 +457,28 @@ 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 extends ModelOptions {
+export interface InteractionExecutionConfiguration {
     environment?: string;
     model?: string;
     do_validate?: boolean;
     run_data?: RunDataStorageLevel;
     configMode?: ConfigModes;
+    model_options?: ModelOptions;
 }
 
 export interface GenerateInteractionPayload {
@@ -297,4 +494,4 @@ export interface GenerateTestDataPayload {
 
 export interface ImprovePromptPayload {
     config: InteractionExecutionConfiguration;
-}
+}

package/src/meters.ts

@@ -0,0 +1,30 @@
+import { BillingMethod } from "./user.js";
+
+
+export interface MeterAdjustment {
+    meter: string;
+    value: string;
+    identifier?: string;
+}
+
+
+export interface AdjustMetersMeterWorkflowParams {
+    adjustments: MeterAdjustment[];
+}
+
+export enum MeterNames {
+    analyzed_pages = 'analyzed_pages',
+    extracted_tables = 'extracted_tables',
+    analyzed_images = 'analyzed_images',
+    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/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 {

package/src/query.ts

@@ -69,6 +69,8 @@ export interface RunSearchQuery extends SimpleSearchQuery {
     object?: string;
     start?: string;
     end?: string;
+    finish_reason?: string;
+    created_by?: string;
 }
 
 export interface WorkflowExecutionSearchQuery extends SimpleSearchQuery {

package/src/runs.ts

@@ -1,6 +1,15 @@
 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

package/src/store/activity-catalog.ts

@@ -1,4 +1,4 @@
-export type TsPropType = "string" | "number" | "boolean" | "record" | "object" | "array" | "enum" | "literal" | "union" | "promise" | "any";
+export type TsPropType = "string" | "number" | "boolean" | "record" | "object" | "array" | "enum" | "literal" | "union" | "promise" | "any" | "void";
 
 // generic types are replaced by "any"
 export interface ActivityTypeDefinition {
@@ -9,7 +9,7 @@ export interface ActivityTypeDefinition {
     // in case of primitive literals will be the value
     // or nested objects / arrays will be "object" or "array"
     // for record this is Record<type,type>
-    value: string | boolean | number;
+    value: string | boolean | number | null;
     // in case of objects
     members?: ActivityPropertyDefinition[];
     // in case of arrays or promises will be innertype (i.e. the element type for arrays)

package/src/store/collections.ts

@@ -0,0 +1,62 @@
+import { BaseObject } from "./common.js";
+import { ColumnLayout, ContentObjectTypeRef } from "./store.js";
+
+export enum CollectionStatus {
+    active = 'active',
+    archived = 'archived'
+}
+
+export interface CreateCollectionPayload {
+    name: string;
+    dynamic: boolean;
+    description?: string;
+    tags?: string[];
+    type?: string;
+    query?: Record<string, any>;
+    properties?: Record<string, any>;
+    parent?: string | null;
+    table_layout?: ColumnLayout[] | null;
+}
+
+export interface CollectionItem extends BaseObject {
+    /**
+     * A flag to indicate if the collection is dynamic or static.
+     * If the collection is dynamic, the members are determined by a query using the query field.
+     * Id the collection is static, the members are explicitly defined jusing the members array.
+     */
+    dynamic: boolean;
+    status: CollectionStatus;
+    // A ref to the object type
+    type?: ContentObjectTypeRef;
+    /**
+     * The parent collection if any
+     */
+    parent?: 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.
+     */
+    table_layout?: ColumnLayout[];
+}
+
+export interface Collection extends CollectionItem {
+    properties: Record<string, any>;
+    query?: Record<string, any>;
+}
+
+export interface StaticCollection extends Collection {
+    dynamic: false;
+    members: string[];
+    query: never;
+}
+
+export interface DynamicCollection extends Collection {
+    dynamic: true;
+}
+
+export interface CollectionSearchPayload {
+    dynamic?: boolean;
+    status?: CollectionStatus;
+    limit?: number;
+    offset?: number;
+}