@vertesia/common 0.80.1 → 0.81.0

package/lib/types/interaction.d.ts

@@ -0,0 +1,726 @@
+import type { CompletionResult, JSONObject, JSONSchema, Modalities, ModelOptions, PromptRole, StatelessExecutionOptions, ToolDefinition, ToolUse } from "@llumiverse/common";
+import type { JSONSchema4 } from "json-schema";
+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";
+export interface InteractionExecutionError {
+    code: string;
+    message: string;
+    data?: any;
+}
+/**
+ * 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
+ */
+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[];
+    agent_runner_options?: AgentRunnerOptions;
+    /**
+     * @deprecated This is deprecated. Use CompletionResult.type information instead.
+     */
+    output_modality?: Modalities;
+    result_schema?: JSONSchema;
+    params_schema?: JSONSchema;
+}
+export interface InteractionTags {
+    tag: string;
+    count: number;
+    interactions: InteractionRef[];
+}
+export interface InteractionRef {
+    id: string;
+    name: string;
+    endpoint: string;
+    parent?: string;
+    description?: string;
+    status: InteractionStatus;
+    visibility?: InteractionVisibility;
+    version: number;
+    tags: string[];
+    agent_runner_options?: AgentRunnerOptions;
+    prompts?: PromptSegmentDef<PromptTemplateRef>[];
+    updated_at: Date;
+}
+export declare const InteractionRefPopulate = "id name endpoint parent description status version visibility tags agent_runner_options updated_at prompts";
+export declare const InteractionRefWithSchemaPopulate = "id name endpoint parent description status version visibility tags agent_runner_options updated_at prompts result_schema";
+export interface InteractionRefWithSchema extends Omit<InteractionRef, "prompts"> {
+    result_schema?: JSONSchema4;
+    prompts?: PromptSegmentDef<PromptTemplateRefWithSchema>[];
+}
+export interface InteractionsExportPayload {
+    /**
+     * The name of the interaction. If not specified all the interactions in the current project will be exported
+     */
+    name?: string;
+    tags?: string[];
+    versions?: (number | "draft" | "latest")[];
+}
+export declare enum InteractionStatus {
+    draft = "draft",
+    published = "published",
+    archived = "archived"
+}
+export declare enum ExecutionRunStatus {
+    created = "created",
+    processing = "processing",
+    completed = "completed",
+    failed = "failed"
+}
+export declare enum RunDataStorageLevel {
+    STANDARD = "STANDARD",
+    RESTRICTED = "RESTRICTED",
+    DEBUG = "DEBUG"
+}
+export declare enum RunDataStorageDescription {
+    STANDARD = "Run data is stored for both the model inputs and output.",
+    RESTRICTED = "No run data is stored for the model inputs \u2014 only the model output.",
+    DEBUG = "Run data is stored for the model inputs and output, schema, and final prompt."
+}
+export declare const RunDataStorageOptions: Record<RunDataStorageLevel, RunDataStorageDescription>;
+/**
+ * Schema can be stored or specified as a reference to an external schema.
+ * We only support "store:" references for now
+ */
+export interface SchemaRef {
+    $uri: string;
+}
+export interface CachePolicy {
+    type: "cache" | "no_cache" | "cache_and_refresh";
+    refresh_probability: number;
+    varies_on: string[];
+    ttl: number;
+}
+export type InteractionVisibility = "public" | "private";
+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;
+    /**
+     * @deprecated This is deprecated. Use CompletionResult.type information instead.
+     */
+    output_modality?: Modalities;
+}
+export interface Interaction extends InteractionData {
+    status: InteractionStatus;
+    parent?: string;
+    visibility: InteractionVisibility;
+    version: number;
+    test_data?: JSONObject;
+    interaction_schema?: JSONSchema4 | SchemaRef;
+    cache_policy?: CachePolicy;
+    prompts: PromptSegmentDef[];
+    last_published_at?: Date;
+    created_by: string;
+    updated_by: string;
+    created_at: Date;
+    updated_at: Date;
+}
+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, "id" | "created_at" | "updated_at" | "created_by" | "updated_by" | "project" | "formatter" | "tags" | "parent" | "version" | "visibility" | "endpoint"> {
+    visibility?: InteractionVisibility;
+    tags?: string[];
+}
+export interface InteractionUpdatePayload extends Partial<Omit<Interaction, "result_schema" | "id" | "created_at" | "updated_at" | "created_by" | "updated_by" | "project">> {
+    result_schema?: JSONSchema4 | null;
+}
+export interface InteractionPublishPayload {
+    visibility?: InteractionVisibility;
+    tags?: string[];
+}
+export interface InteractionForkPayload {
+    keepTags?: boolean;
+    forkPrompts?: boolean;
+    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 properties of the data will contain the memory pack mapping.
+     */
+    data?: Record<string, any> | `memory:${string}`;
+    config?: InteractionExecutionConfiguration;
+    result_schema?: JSONSchema4 | null;
+    stream?: boolean;
+    do_validate?: boolean;
+    tags?: string | string[];
+    /**
+     * 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
+     */
+    tool_definitions?: ToolDefinition[];
+    /**
+     * 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 {
+    /**
+     * The interaction name and suffixed by an optional tag or version separated from the name using a @ character
+     * If no version/tag part is specified then the latest version is used.
+     * Example: ReviewContract, ReviewContract@draft, ReviewContract@1, ReviewContract@some-tag
+     */
+    interaction: string;
+}
+export type ToolRef = string | {
+    name: string;
+    description: string;
+};
+interface AsyncExecutionPayloadBase extends Omit<NamedInteractionExecutionPayload, "toolDefinitions" | "stream"> {
+    type: "conversation" | "interaction";
+    /**
+     * An array of endpoint URLs to be notified upon execution
+     */
+    notify_endpoints?: string[];
+    task_queue?: string;
+}
+export type ConversationVisibility = 'private' | 'project';
+/**
+ * Defines the scope for agent search operations.
+ */
+export declare enum AgentSearchScope {
+    /**
+     * Search is scoped to a specific collection.
+     */
+    Collection = "collection"
+}
+/**
+ * Context triggers for auto-injection of skills.
+ * When these conditions match, the skill is automatically injected into the agent context.
+ */
+export interface SkillContextTriggers {
+    /**
+     * Keywords in user input that should trigger this skill
+     */
+    keywords?: string[];
+    /**
+     * If these tools are being used, suggest this skill
+     */
+    tool_names?: string[];
+    /**
+     * Regex patterns to match against input data
+     */
+    data_patterns?: string[];
+}
+/**
+ * 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;
+    /**
+     * Whether this interaction is a skill (provides instructions without execution).
+     * Skills are injected into the agent's context based on context_triggers.
+     */
+    is_skill?: boolean;
+    /**
+     * Context triggers for auto-injection of this skill.
+     * Only used when is_skill is true.
+     */
+    context_triggers?: SkillContextTriggers;
+    /**
+     * Injection priority for skills (higher = more likely to be selected when multiple match).
+     * Only used when is_skill is true.
+     */
+    skill_priority?: number;
+    /**
+     * 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
+    * If not specified, the default is project
+    **/
+    visibility?: ConversationVisibility;
+    /**
+     * The tools to use, list of tool or function names.
+     * You can use + and - to add or remove from default, if no sign, then list replaces default
+     */
+    tool_names?: string[];
+    /**
+     * 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?: AgentSearchScope.Collection;
+    /**
+     * 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;
+    /** In child execution workflow, this is the curent task_id */
+    task_id?: string;
+    /** Whether to enable debug mode */
+    debug_mode?: boolean;
+    /** Maximum depth for nested conversations to prevent infinite recursion (default: 5) */
+    max_nested_conversation_depth?: number;
+}
+export interface AsyncInteractionExecutionPayload extends AsyncExecutionPayloadBase {
+    type: "interaction";
+    /**
+     * 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;
+    environment: string;
+    options: StatelessExecutionOptions;
+    conversation: unknown;
+    tools: ToolDefinition[];
+}
+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 {
+    tool_use_id: string;
+}
+/**
+ * The payload to sent the tool responses back to the target LLM
+ */
+export interface ToolResultsPayload extends ResumeConversationPayload {
+    results: ToolResult[];
+}
+export interface UserMessagePayload extends ResumeConversationPayload {
+    message: string;
+}
+export type CheckpointConversationPayload = Omit<ToolResultsPayload, "results" | "tools">;
+export declare enum RunSourceTypes {
+    api = "api",
+    cli = "cli",
+    ui = "ui",
+    webhook = "webhook",
+    test = "test-data",
+    system = "system"
+}
+export interface RunSource {
+    type: RunSourceTypes;
+    label: string;
+    principal_type: "user" | "apikey";
+    principal_id: string;
+    client_ip: string;
+}
+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
+     */
+    parent?: string | ExecutionRun;
+    evaluation?: {
+        score?: number;
+        selected?: boolean;
+        scores?: Record<string, number>;
+    };
+    result: CompletionResult[];
+    /**
+     * The parameters used to create the interaction.
+     * If the parameters contains the special property "@memory" it will be used
+     * to locate a memory pack and the other properties will be used as the memory pack mapping.
+     */
+    parameters: P;
+    tags?: string[];
+    interaction?: string | Interaction;
+    interaction_code?: string;
+    environment: ExecutionEnvironmentRef;
+    modelId: string;
+    result_schema: JSONSchema4;
+    ttl: number;
+    status: ExecutionRunStatus;
+    finish_reason?: string;
+    prompt: any;
+    token_use?: ExecutionTokenUsage;
+    chunks?: number;
+    execution_time?: number;
+    created_at: Date;
+    updated_at: Date;
+    account: AccountRef;
+    project: ProjectRef;
+    config: InteractionExecutionConfiguration;
+    error?: InteractionExecutionError;
+    source: RunSource;
+    /**
+     * @deprecated This is deprecated. Use CompletionResult.type information instead.
+     */
+    output_modality?: Modalities;
+    created_by: string;
+    updated_by: string;
+    /**
+     * The Vertesia Workflow related to this Interaction Run.
+     *
+     * This is only set when the interaction is executed as part of a workflow.
+     *
+     * @since 0.60.0
+     */
+    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.
+     *
+     * A Run ID is a globally unique, platform-level identifier for a Workflow Execution.
+     *
+     * @example 01970d37-a890-70c0-9f44-1256d063e69a
+     * @see https://docs.temporal.io/workflow-execution/workflowid-runid
+     */
+    run_id: string;
+    /**
+     * The Temporal Workflow ID related to this Interaction Run.
+     *
+     * @example Standard Document Intake:6834841e4f828d4e36192796
+     * @see https://docs.temporal.io/workflow-execution/workflowid-runid
+     */
+    workflow_id: string;
+    /**
+     * The Temporal Activity Type used for executing this Interaction. Undefined if the interaction
+     * was not executed as part of a workflow (such as Agent Runner).
+     *
+     * @example generateDocumentProperties
+     */
+    activity_type?: string;
+}
+export interface PromptModalities {
+    hasVideo: boolean;
+    hasImage: boolean;
+}
+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_code?: string;
+}
+export declare const ExecutionRunRefSelect = "-result -parameters -result_schema -prompt";
+export declare enum ConfigModes {
+    RUN_AND_INTERACTION_CONFIG = "RUN_AND_INTERACTION_CONFIG",
+    RUN_CONFIG_ONLY = "RUN_CONFIG_ONLY",
+    INTERACTION_CONFIG_ONLY = "INTERACTION_CONFIG_ONLY"
+}
+export declare 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."
+}
+export declare const ConfigModesOptions: Record<ConfigModes, ConfigModesDescription>;
+export interface InteractionExecutionConfiguration {
+    environment?: string;
+    model?: string;
+    do_validate?: boolean;
+    run_data?: RunDataStorageLevel;
+    configMode?: ConfigModes;
+    model_options?: ModelOptions;
+}
+export interface GenerateInteractionPayload {
+    description: string;
+    config: InteractionExecutionConfiguration;
+}
+export interface GenerateTestDataPayload {
+    message?: string;
+    count?: number;
+    config: InteractionExecutionConfiguration;
+}
+export interface ImprovePromptPayloadConfig {
+    config: InteractionExecutionConfiguration;
+}
+export interface ImprovePromptPayload extends ImprovePromptPayloadConfig {
+    interaction_name: string;
+    context?: string;
+    prompt: {
+        name: string;
+        content: string;
+    }[];
+    result_schema?: JSONSchema;
+}
+export interface RateLimitRequestPayload {
+    interaction: string;
+    environment_id?: string;
+    model_id?: string;
+    workflow_run_id?: string;
+    modalities?: PromptModalities;
+}
+export interface RateLimitRequestResponse {
+    delay_ms: number;
+}
+export {};