@vertesia/common 0.24.0-dev.202601221707

package/src/query.ts

@@ -0,0 +1,137 @@
+import { ExecutionRunStatus } from './interaction.js';
+import { CollectionSearchPayload } from './store/collections.js';
+import { SearchTypes, SupportedEmbeddingTypes } from "./project.js";
+
+export type EmbeddingSearchConfig = Partial<Record<SupportedEmbeddingTypes, boolean>>;
+
+export interface RunListingQueryOptions {
+    project?: string;
+    interaction?: string | string[];
+    limit?: number;
+    offset?: number;
+    filters?: RunListingFilters;
+}
+
+export interface RunListingFilters {
+    interaction?: string | string[],
+    status?: ExecutionRunStatus,
+    model?: string,
+    environment?: string,
+    tag?: string,
+    fromDate?: string,
+    toDate?: string,
+    parent?: string | false,
+    workflow_run_ids?: string[],
+}
+
+export type scoreAggregationTypes = 'rrf' | 'rsf' | 'smart';
+export type dynamicScalingTypes = 'off' | 'on';
+
+export interface VectorSearchQuery {
+    objectId?: string;
+    values?: number[];
+    text?: string;
+    image?: string;
+    config?: EmbeddingSearchConfig;
+}
+
+export interface SimpleSearchQuery {
+    name?: string;
+    status?: string | string[];
+    limit?: number;
+    offset?: number;
+}
+
+export interface ObjectSearchQuery extends SimpleSearchQuery {
+    id?: string;
+    createdFrom?: string;
+    createdTo?: string;
+    updatedFrom?: string;
+    updatedTo?: string;
+    location?: string;
+    parent?: string;
+    type?: string;
+    types?: string[];
+    all_revisions?: boolean;
+    from_root?: string;
+}
+
+export interface ObjectTypeSearchQuery extends SimpleSearchQuery {
+    chunkable?: boolean;
+}
+
+export interface PromptSearchQuery extends SimpleSearchQuery {
+    role?: string;
+    matchInteractions?: boolean;
+}
+
+export interface InteractionSearchQuery extends SimpleSearchQuery {
+    prompt?: string;
+    tags?: string[];
+    version?: string;
+    model?: string;
+    environment?: string;
+}
+
+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;
+    finish_reason?: string;
+    created_by?: string;
+    workflow_run_ids?: string[];
+    run_ids?: string[];
+}
+
+export interface WorkflowExecutionSearchQuery extends SimpleSearchQuery {
+    documentId?: string;
+    eventName?: string;
+    ruleId?: string;
+    start?: string;
+    end?: string;
+    status?: string;
+}
+
+/**
+ * ComplexSearchQuery is used for full-text search and vector embedding search.
+ */
+export interface ComplexSearchQuery extends ObjectSearchQuery {
+    vector?: VectorSearchQuery;
+
+    /**
+     * If present, do a full text search (snake_case version).
+     */
+    full_text?: string;
+
+    weights?: Record<SearchTypes, number>;
+
+    /**
+     * dynamicScaling rescales the weights when a particular search type is not present in the results, per object.
+     * e.g. Weights of 5,3,2 will be treated as 0,3,2 if the first search type is not present in the results.
+     * Ignored when scoreAggregation is 'smart'
+     * Default is 'on'
+    */
+    dynamic_scaling?: dynamicScalingTypes;   // Move to top level
+
+    /**
+     * rrf: Reciprocal Rank Fusion
+     * rsf: Reciprocal Score Fusion
+     * smart: Our own algorithm (default and recommended)
+     */
+    score_aggregation?: scoreAggregationTypes;
+
+    match?: Record<string, any>;
+}
+
+export interface ComplexCollectionSearchQuery extends CollectionSearchPayload {
+    match?: Record<string, any>;
+}

package/src/rate-limiter.ts

@@ -0,0 +1,34 @@
+/**
+ * Rate Limiter Types
+ */
+
+export interface RateLimiterCapacity {
+    current: number;
+    base: number;
+    max: number;
+}
+
+export interface RateLimiterBreakerState {
+    state: 'open' | 'closed';
+    is_open: boolean;
+    last_opened_at?: string;
+    consecutive_failures?: number;
+}
+
+export interface RateLimiterModelStatus {
+    model_id: string;
+    admitted: number;
+    delayed: number;
+    capacity: RateLimiterCapacity;
+    breaker: RateLimiterBreakerState;
+    last_updated: string;
+}
+
+export interface RateLimiterStatus {
+    environment_id: string;
+    model_id: string;
+    status: RateLimiterModelStatus;
+}
+
+// Always return an array for consistency
+export type RateLimiterStatusResponse = RateLimiterStatus[];

package/src/refs.ts

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

package/src/runs.ts

@@ -0,0 +1,36 @@
+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 interaction ID to run
+ */
+export interface RunCreatePayload extends NamedInteractionExecutionPayload {
+}
+
+/**
+ * To be used as a value for a numeric or date filters
+ */
+export interface RangeValue {
+    gt?: number | string,
+    gte?: number | string,
+    lt?: number | string,
+    lte?: number | string,
+}
+
+export interface RunSearchMetaResponse {
+    count: {
+        lower_bound?: number,
+        total?: number,
+    },
+    facet: Record<string, FacetResult>
+}

package/src/skill.ts

@@ -0,0 +1,90 @@
+/**
+ * Skill types for interaction-based skills.
+ *
+ * Skills are interactions with `agent_runner_options.is_skill = true`.
+ * They provide contextual instructions to agents without executing code.
+ * When a skill is called, its rendered prompt is returned as instructions.
+ *
+ * Skills can have associated scripts stored at:
+ *   skills/{skill_name}/*.py, *.js, etc.
+ * These are automatically synced to the sandbox when the skill is used.
+ */
+
+/**
+ * Context provided when searching for relevant skills
+ */
+export interface SkillContext {
+    /**
+     * The task description or user prompt
+     */
+    task_description?: string;
+
+    /**
+     * Tools currently being used or available
+     */
+    tool_names?: string[];
+
+    /**
+     * Sample of input data for pattern matching
+     */
+    data_sample?: string;
+
+    /**
+     * Additional keywords to consider
+     */
+    keywords?: string[];
+}
+
+/**
+ * Payload for finding relevant skills
+ */
+export interface FindRelevantSkillsPayload {
+    context: SkillContext;
+    limit?: number;
+}
+
+/**
+ * Result from skill injection into agent context.
+ * Contains the rendered prompt/instructions from a skill interaction.
+ */
+export interface InjectedSkill {
+    /**
+     * The skill/interaction name
+     */
+    name: string;
+
+    /**
+     * The skill's rendered instructions (from the interaction prompt)
+     */
+    instructions: string;
+
+    /**
+     * Tools related to this skill
+     */
+    related_tools?: string[];
+
+    /**
+     * UI module for rendering results
+     */
+    ui_module?: string;
+
+    /**
+     * Match score (0-1) indicating relevance
+     */
+    match_score?: number;
+}
+
+/**
+ * Result from generateTools activity with skills
+ */
+export interface ToolsWithSkills {
+    /**
+     * Array of tool definitions
+     */
+    tools: unknown[]; // ToolDefinition[]
+
+    /**
+     * Skills injected based on context
+     */
+    injected_skills: InjectedSkill[];
+}

package/src/store/activity-catalog.ts

@@ -0,0 +1,44 @@
+export type TsPropType = "string" | "number" | "boolean" | "record" | "object" | "array" | "enum" | "literal" | "union" | "promise" | "any" | "void";
+
+// generic types are replaced by "any"
+export interface ActivityTypeDefinition {
+    name: TsPropType;
+    // in case of primitives will be the type name: string, boolean number.
+    // in case of objects or enums will be the object name
+    // in case of arrays will be String(itemType.value)+"[]"
+    // 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 | null;
+    // in case of objects
+    members?: ActivityPropertyDefinition[];
+    // in case of arrays or promises will be innerType (i.e. the element type for arrays)
+    innerType?: ActivityTypeDefinition;
+    // in case of enums the enum values will be here
+    enum?: string[] | number[] | undefined;
+    // in case of unions
+    union?: ActivityTypeDefinition[];
+}
+
+export interface ActivityPropertyDefinition {
+    name: string;
+    type: ActivityTypeDefinition;
+    optional: boolean;
+    // the JSDoc comment for the activity property
+    doc?: string;
+}
+
+export interface ActivityDefinition {
+    name: string;
+    // generated from name
+    title: string;
+    // the JSDoc comment for the activity function
+    doc?: string;
+    paramsType: string;
+    params: ActivityPropertyDefinition[];
+    returnType?: ActivityTypeDefinition | undefined;
+}
+
+export interface ActivityCatalog {
+    activities: ActivityDefinition[];
+}

package/src/store/collections.ts

@@ -0,0 +1,87 @@
+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;
+    skip_head_sync?: boolean;
+    tags?: string[];
+    type?: string;
+    query?: Record<string, any>;
+    properties?: Record<string, any>;
+    parent?: string | null;
+    table_layout?: ColumnLayout[] | null;
+    allowed_types?: string[];
+    updated_by?: string,
+    shared_properties?: string[];
+}
+
+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.
+     * If the collection is static, the members are explicitly defined using the members array.
+     */
+    dynamic: boolean;
+    status: CollectionStatus;
+    // A ref to the object type
+    type?: ContentObjectTypeRef;
+    /**
+     * A flag to indicate whether to track and sync member HEAD revisions. 
+     * The default is to sync HEAD revisions for collection members (skip_head_sync: false)
+     */
+    skip_head_sync: boolean;
+    /**
+     * The parent collections if any.
+     * A collection can have multiple parents.
+     */
+    parents?: 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[];
+
+    /**
+     * The allowed types for the collection.
+     */
+    allowed_types?: string[];
+}
+
+export interface Collection extends CollectionItem {
+    properties: Record<string, any>;
+    query?: Record<string, any>;
+    security?: Record<string, string[]>; // ACL for collection access
+    /**
+     * List of property names from the collection's properties that should be shared with (injected into) member objects.
+     * These properties will be propagated to all members of this collection and merged as arrays.
+     */
+    shared_properties?: string[];
+}
+
+export interface StaticCollection extends Collection {
+    dynamic: false;
+    members: string[];
+    query: never;
+}
+
+export interface DynamicCollection extends Collection {
+    dynamic: true;
+}
+
+export interface CollectionSearchPayload {
+    parent?: string | null;
+    dynamic?: boolean;
+    status?: CollectionStatus;
+    limit?: number;
+    offset?: number;
+    name?: string;
+    type?: string;
+    types?: string[];
+}

package/src/store/common.ts

@@ -0,0 +1,30 @@
+/**
+ * Base interface for all domain objects in the system.
+ * Provides common properties shared across all business entities.
+ */
+export interface BaseObject {
+    /** Unique identifier for the object */
+    id: string;
+
+    /** Human-readable name or title */
+    name: string;
+
+    /** Optional detailed description of the object */
+    description?: string;
+
+    /** Optional array of categorization tags */
+    tags?: string[];
+
+    /** Identifier of the user who last modified the object */
+    updated_by: string;
+
+    /** Identifier of the user who created the object */
+    created_by: string;
+
+    /** ISO timestamp of when the object was created */
+    created_at: string;
+
+    /** ISO timestamp of when the object was last updated */
+    updated_at: string;
+
+}

package/src/store/conversation-state.ts

@@ -0,0 +1,146 @@
+import { CompletionResult, ExecutionTokenUsage, StatelessExecutionOptions, ToolUse } from "@llumiverse/common";
+import { ConversationStripOptions, ResolvedInteractionExecutionInfo, UserChannel } from "../interaction.js";
+import { ExecutionRunDocRef } from "../runs.js";
+import { Plan, WorkflowAncestor } from "./workflow.js";
+
+/**
+ * Lightweight tool reference for activity payloads.
+ * References tools stored in GCP instead of embedding full tool definitions.
+ */
+export interface ToolReference {
+    storage_key: string;
+    tool_count: number;
+    stored_at: string;
+}
+
+/**
+ * Conversation state passed between workflow activities.
+ * Contains all context needed to continue a multi-turn agent conversation.
+ */
+export interface ConversationState {
+    /**
+     * A reference to the run that started the conversation
+     */
+    run: ExecutionRunDocRef;
+
+    /**
+     * The execution environment with provider info for LLM calls.
+     */
+    environment: string;
+
+    /**
+     * The options to use on the next call.
+     */
+    options: StatelessExecutionOptions;
+
+    /**
+     * The tools to call next.
+     */
+    tool_use?: ToolUse[];
+
+    /**
+     * The output of the this conversation step
+     */
+    output: CompletionResult[];
+
+    /**
+     * The token usage of the this conversation step
+     */
+    token_usage?: ExecutionTokenUsage;
+
+    /** If a sub workflow execution, contains the parent's info */
+    parent?: WorkflowAncestor;
+
+    /** Full ancestry chain from root to immediate parent (for hierarchical aggregation) */
+    ancestors: WorkflowAncestor[];
+
+    /** If part of a larger agentic workflow, task id of this task */
+    task_id?: string;
+
+    /** Stores the most recent plan for reference by plan-related tools */
+    plan?: Plan;
+
+    /** Debug mode (more logs and persisted artifacts) */
+    debug?: boolean;
+
+    /**
+     * Configuration for stripping large data from conversation history.
+     * Passed to llumiverse ExecutionOptions.stripImagesAfterTurns.
+     */
+    strip_options?: ConversationStripOptions;
+
+    /** Conversation artifacts base url */
+    conversation_artifacts_base_url?: string;
+
+    /** Reference to tools stored in GCP instead of embedding full tool definitions */
+    tool_reference?: ToolReference;
+
+    /** Names of currently active tools (base + unlocked). Tool definitions loaded from tool_reference. */
+    active_tool_names?: string[];
+
+    /** Skills that have been used in this conversation (for auto-syncing scripts and package installation) */
+    used_skills?: UsedSkill[];
+
+    /** All available skills from registered tool collections (for upfront hydration in sandbox) */
+    available_skills?: AvailableSkill[];
+
+    /** Whether to stream LLM responses to Redis (cached from project config) */
+    streaming_enabled?: boolean;
+
+    /**
+     * Active communication channels with their current state.
+     * Channels can be updated as conversation progresses (e.g., email threading info).
+     */
+    user_channels?: UserChannel[];
+
+    /**
+     * The resolved interaction execution info.
+     * Contains interaction ID, name, version, and environment details.
+     */
+    resolvedInteraction?: ResolvedInteractionExecutionInfo;
+
+    /**
+     * End conversation metadata set when end_conversation tool is called.
+     * Signals the workflow to terminate gracefully.
+     */
+    end_conversation?: {
+        final_result?: string;
+        status?: 'success' | 'failure';
+        reason?: string;
+    };
+
+    /**
+     * Tools that have been unlocked by skills during the conversation.
+     * These tools were initially hidden (default: false) but became available
+     * when a skill with related_tools was called.
+     */
+    unlocked_tools?: string[];
+
+    /**
+     * Mapping of skill names to their related tools.
+     * When a skill is called, its related tools are added to unlocked_tools.
+     */
+    skill_tool_map?: Record<string, string[]>;
+}
+
+/** Skill metadata collected at workflow start for upfront sandbox hydration */
+export interface AvailableSkill {
+    /** Skill name (e.g., "analyze_data") - without the "learn_" prefix */
+    name: string;
+    /** Source URL of the skill collection (e.g., "https://tools.vertesia.io/api/skills/data-analysis") */
+    src: string;
+}
+
+/** Skill metadata tracked when a skill is used */
+export interface UsedSkill {
+    /** Skill name (e.g., "analyze_data") */
+    name: string;
+    /** Source URL of the skill collection (e.g., "https://tools.vertesia.io/api/skills/data-analysis") */
+    src: string;
+    /** Programming language (e.g., "python") */
+    language?: string;
+    /** Required packages (e.g., ["pandas", "numpy"]) */
+    packages?: string[];
+    /** System-level packages to install via sudo apt-get (e.g., ["poppler-utils"]) */
+    system_packages?: string[];
+}