@vertesia/common 0.42.2

package/src/interaction.ts

@@ -0,0 +1,300 @@
+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';
+
+export interface InteractionExecutionError {
+    code: string;
+    message: string;
+    data?: any;
+}
+
+export interface InteractionRef {
+    id: string;
+    name: string;
+    description?: string;
+    status: InteractionStatus;
+    visibility?: InteractionVisibility;
+    version: number;
+    tags: string[];
+    prompts?: PromptSegmentDef<PromptTemplateRef>[];
+    updated_at: Date;
+}
+export const InteractionRefPopulate = "id name description status version visibility tags updated_at 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
+     */
+    name?: string;
+    /*
+     * tags to filter the exported interactions
+     */
+    tags?: string[];
+    /*
+     * if not specified, all versions will be exported
+     */
+    versions?: (number | 'draft' | 'latest')[];
+}
+
+export enum InteractionStatus {
+    draft = "draft",
+    published = "published",
+    archived = "archived",
+}
+
+export enum ExecutionRunStatus {
+    created = "created",
+    processing = "processing",
+    completed = "completed",
+    failed = "failed",
+}
+
+export enum RunDataStorageLevel {
+    STANDARD = "STANDARD",
+    RESTRICTED = "RESTRICTED",
+    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."
+}
+
+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.
+ * 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 Interaction extends ModelOptions {
+    readonly id: string;
+    name: string;
+    endpoint: string;
+    description?: string;
+    status: InteractionStatus;
+    parent?: string;
+    // only used for versions (status === "published")
+    visibility: InteractionVisibility;
+    version: number;
+    tags: string[];
+    test_data?: JSONObject;
+    result_schema?: JSONSchema4 | SchemaRef;
+    cache_policy?: CachePolicy;
+    model: string;
+    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,
+    updated_by: string,
+    created_at: Date;
+    updated_at: Date;
+}
+
+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"
+    > {
+    visibility?: InteractionVisibility;
+}
+
+export interface InteractionUpdatePayload
+    extends Partial<
+        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 {
+    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 proerties of the data will contain the memory pack mapping.
+     */
+    data?: Record<string, any> | `memory:${string}`;
+    config?: InteractionExecutionConfiguration;
+    result_schema?: JSONSchema4;
+    stream?: boolean;
+    do_validate?: boolean;
+    tags?: string | string[]; // tags to be added to the execution run
+}
+
+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 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 ExecutionRun<P = any, R = 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: 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.
+     */
+    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;
+    //TODO a string is returned when execution not the env object
+    environment: ExecutionEnvironmentRef;
+    modelId: string;
+    result_schema: JSONSchema4;
+    ttl: number;
+    status: ExecutionRunStatus;
+    finish_reason?: string;
+    prompt: any;
+    token_use?: ExecutionTokenUsage;
+    chunks?: number;
+    execution_time?: number; //s
+    created_at: Date;
+    updated_at: Date;
+    account: AccountRef;
+    project: ProjectRef;
+    config: InteractionExecutionConfiguration;
+    error?: InteractionExecutionError;
+    source: RunSource;
+    output_modality: Modalities;
+    created_by: string,
+    updated_by: string,
+}
+
+export interface ExecutionRunRef
+    extends Omit<ExecutionRun, "result" | "parameters" | "interaction"> {
+    interaction: InteractionRef;
+}
+
+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"
+};
+
+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."
+}
+
+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 {
+    environment?: string;
+    model?: string;
+    do_validate?: boolean;
+    run_data?: RunDataStorageLevel;
+    configMode?: ConfigModes;
+}
+
+export interface GenerateInteractionPayload {
+    description: string;
+    config: InteractionExecutionConfiguration;
+}
+
+export interface GenerateTestDataPayload {
+    message?: string;
+    count?: number;
+    config: InteractionExecutionConfiguration;
+}
+
+export interface ImprovePromptPayload {
+    config: InteractionExecutionConfiguration;
+}

package/src/payload.ts

@@ -0,0 +1,62 @@
+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;
+}
+
+export interface ComputeFacetPayload {
+    facets: FacetSpec[];
+    query?: SimpleSearchQuery;
+}
+
+export interface InteractionSearchPayload extends SearchPayload {
+    query?: InteractionSearchQuery;
+}
+
+export interface ObjectSearchPayload extends SearchPayload {
+    query?: ObjectSearchQuery;
+}
+
+export interface ObjectTypeSearchPayload extends SearchPayload {
+    query?: ObjectTypeSearchQuery;
+}
+
+export interface PromptSearchPayload extends SearchPayload {
+    query?: PromptSearchQuery;
+}
+
+export interface RunSearchPayload extends SearchPayload {
+    query?: RunSearchQuery;
+}
+
+export interface ComputeInteractionFacetPayload extends ComputeFacetPayload {
+    query?: InteractionSearchQuery;
+}
+
+export interface ComputeObjectFacetPayload extends ComputeFacetPayload {
+    query?: ObjectSearchQuery;
+    vector?: VectorSearchQuery;
+}
+
+export interface ComputePromptFacetPayload extends ComputeFacetPayload {
+    query?: PromptSearchQuery;
+}
+
+export interface ComputeRunFacetPayload extends ComputeFacetPayload {
+    query?: RunSearchQuery;
+}
+
+export interface ExportPropertiesPayload {
+    objectIds: string[];
+    type: string;
+    query?: ComplexSearchQuery;
+}
+
+export interface ExportPropertiesResponse {
+    type: string;
+    name: string;
+    data: Blob;
+}

package/src/project.ts

@@ -0,0 +1,136 @@
+import { SupportedIntegrations } from "./integrations.js";
+import { AccountRef } from "./user.js";
+
+export interface ICreateProjectPayload {
+    name: string;
+    namespace: string;
+    description?: string;
+}
+export enum ProjectRoles {
+    owner = "owner", // all permissions
+    admin = "admin", // all permissions
+    project_admin = "project_admin", // all permissions but manage_account, manage_billing
+    developer = "developer", // all permissions but manage_account, manage_billing, manage_roles, delete
+    application = "application", // executor + request_pk
+    executor = "executor", // can only read and execute interactions
+    reader = "reader", // can only read (browse)
+    billing = "billing", // can only manage billings
+    member = "member", // can only access, but no specific permissions
+}
+
+export function isRoleIncludedIn(role: string, includingRole: string) {
+    switch (includingRole) {
+        case ProjectRoles.owner:
+            return true; // includes billing to?
+        case ProjectRoles.admin:
+            return role !== ProjectRoles.billing && role !== ProjectRoles.owner;
+        case ProjectRoles.developer:
+            return role === ProjectRoles.developer;
+        case ProjectRoles.billing:
+            return role === ProjectRoles.billing;
+        default:
+            return false;
+    }
+}
+
+
+export interface PopulatedProjectRef {
+    id: string;
+    name: string;
+    account: AccountRef
+}
+export interface ProjectRef {
+    id: string;
+    name: string;
+    account: string;
+}
+
+export enum ResourceVisibility {
+    public = "public",
+    account = "account",
+    project = "project"
+}
+
+
+export interface ProjectConfiguration {
+
+    human_context: string;
+
+    default_environment?: string;
+    default_model?: string;
+
+    embeddings: {
+        text?: ProjectConfigurationEmbeddings;
+        image?: ProjectConfigurationEmbeddings;
+        properties?: ProjectConfigurationEmbeddings
+    }
+
+    datacenter?: string;
+    storage_bucket?: string;
+
+}
+
+// export interface ProjectConfigurationEmbeddings {
+//     environment: string;
+//     max_tokens: number;
+//     dimensions: number;
+//     model?: string;
+// }
+
+export enum SupportedEmbeddingTypes {
+    text = "text",
+    image = "image",
+    properties = "properties"
+}
+
+export interface ProjectConfigurationEmbeddings {
+    environment: string;
+    enabled: boolean;
+    dimensions: number;
+    max_tokens?: number;
+    model?: string;
+}
+
+export interface Project {
+    id: string;
+    name: string;
+    namespace: string;
+    description?: string;
+    account: string;
+    configuration: ProjectConfiguration;
+    integrations: Map<string, any>;
+    created_by: string,
+    updated_by: string,
+    created_at: Date;
+    updated_at: Date;
+}
+
+export interface ProjectCreatePayload {
+    name: string;
+    description?: string;
+}
+
+export interface ProjectUpdatePayload extends Partial<Project> { }
+
+
+export const ProjectRefPopulate = "id name account";
+
+
+export interface EmbeddingsStatusResponse {
+    status: string;
+    embeddingRunsInProgress: number;
+    totalRunsInProgress: number;
+    totalIndexableObjects: number;
+    embeddingsModels: string[];
+    objectsWithEmbeddings: number;
+    vectorIndex: {
+        status: "READY" | "PENDING" | "DELETING" | "ABSENT",
+        name?: string,
+        type?: string
+    }
+}
+
+export interface ProjectIntegrationListEntry {
+    id: SupportedIntegrations;
+    enabled: boolean;
+}

package/src/prompt.ts

@@ -0,0 +1,95 @@
+import { JSONSchema4 } from "json-schema";
+import type { JSONObject } from "@llumiverse/core";
+import { ProjectRef } from "./project.js";
+import { PromptRole } from "@llumiverse/core";
+
+export interface ChatPromptSchema {
+    role: PromptRole.user | PromptRole.assistant;
+    content: string;
+}
+
+export enum PromptStatus {
+    draft = "draft",
+    published = "published",
+    archived = "archived",
+}
+
+
+export enum PromptSegmentDefType {
+    chat = "chat",
+    template = "template",
+}
+
+export interface PromptSegmentDef<
+    T = string | PromptTemplate | PromptTemplateRef,
+> {
+    type: PromptSegmentDefType;
+    template?: T; // the template id in case of a prompt template
+    configuration?: any; // the configuration if any in case of builtin prompts
+}
+export interface PopulatedPromptSegmentDef
+    extends Omit<PromptSegmentDef, "template"> {
+    template?: PromptTemplate;
+}
+
+export interface PromptTemplateRef {
+    id: string;
+    name: string;
+    role: PromptRole;
+    version: number;
+    status: PromptStatus;
+    content_type: TemplateType;
+}
+
+export interface PromptTemplateRefWithSchema extends PromptTemplateRef {
+    inputSchema?: JSONSchema4;
+}
+
+export enum TemplateType {
+    text = "text",
+    js = "js",
+    jst = "jst",
+}
+
+export interface PromptTemplate {
+    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 sceham will define the whole input data
+    tags?: string[];
+    // only for drafts - when it was last published
+    last_published_at?: Date;
+    created_by: string,
+    updated_by: string,
+    created_at: Date;
+    updated_at: Date;
+}
+
+export interface PromptTemplateForkPayload {
+    keepTags?: boolean;
+    targetProject?: string;
+}
+
+export interface PromptTemplateCreatePayload
+    extends Omit<
+        PromptTemplate,
+        "id" | "created_at" | "updated_at" | "created_by" | "updated_by" | "project" | "status" | "version"
+    > { }
+
+export interface PromptTemplateUpdatePayload
+    extends Partial<
+        Omit<PromptTemplate, "id" | "created_at" | "updated_at" | "created_by" | "updated_by" | "project">
+    > { }

package/src/query.ts

@@ -0,0 +1,85 @@
+import { ExecutionRunStatus } from './interaction.js';
+import { SupportedEmbeddingTypes } from './project.js';
+
+export interface RunListingQueryOptions {
+    project?: string;
+    interaction?: string;
+    limit?: number;
+    offset?: number;
+    filters?: RunListingFilters;
+}
+
+export interface RunListingFilters {
+    interaction?: string,
+    status?: ExecutionRunStatus,
+    model?: string,
+    environment?: string,
+    tag?: string,
+    fromDate?: string,
+    toDate?: string,
+    parent?: string | false,
+}
+
+export interface VectorSearchQuery {
+    objectId?: string;
+    values?: number[];
+    text?: string;
+    image?: string;
+    threshold?: number;
+    type: SupportedEmbeddingTypes
+}
+
+export interface SimpleSearchQuery {
+    name?: string;
+    status?: string;
+}
+
+export interface ObjectSearchQuery extends SimpleSearchQuery {
+    location?: string;
+    parent?: string;
+    similarTo?: string;
+    embeddingType?: SupportedEmbeddingTypes;
+    type?: string;
+}
+
+export interface ObjectTypeSearchQuery extends SimpleSearchQuery {
+    chunckable?: boolean;
+}
+
+export interface PromptSearchQuery extends SimpleSearchQuery {
+    role?: string;
+}
+
+export interface InteractionSearchQuery extends SimpleSearchQuery {
+    prompt?: string;
+    tags?: string[];
+    version?: number;
+}
+
+export interface RunSearchQuery extends SimpleSearchQuery {
+    offset?: number;
+    interaction?: string;
+    environment?: string;
+    model?: string;
+    status?: ExecutionRunStatus;
+    tags?: string[];
+    query?: string;
+    default_query_path?: string;
+    parent?: string[] | false;
+    object?: string;
+    start?: string;
+    end?: string;
+}
+
+export interface WorkflowExecutionSearchQuery extends SimpleSearchQuery {
+    documentId?: string;
+    eventName?: string;
+    ruleId?: string;
+    start?: string;
+    end?: string;
+    status?: string;
+}
+
+export interface ComplexSearchQuery extends ObjectSearchQuery {
+    vector?: VectorSearchQuery;
+}

package/src/refs.ts

@@ -0,0 +1,27 @@
+
+
+export enum ResolvableRefType {
+    project = "Project",
+    environment = "Environment",
+    user = "User",
+    account = "Account",
+    interaction = "Interaction"
+}
+
+export interface ResolvableRef {
+    type: ResolvableRefType
+    id: string
+}
+
+export interface RefResolutionRequest {
+
+    refs: ResolvableRef[]
+
+}
+
+
+export interface ResourceRef {
+    id: string
+    name: string
+    type: string
+}