@vertesia/common 0.80.0-dev.20251121 → 0.80.0

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@vertesia/common",
-  "version": "0.80.0-dev.20251121",
+  "version": "0.80.0",
+  "license": "Apache-2.0",
   "type": "module",
   "types": "./lib/types/index.d.ts",
   "files": [
@@ -27,13 +28,21 @@
   "dependencies": {
     "ajv": "^8.16.0",
     "json-schema": "^0.4.0",
-    "@llumiverse/common": "0.23.0-dev.20251121"
+    "@llumiverse/common": "0.23.0"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/vertesia/composableai.git",
     "directory": "packages/common"
   },
+  "keywords": [
+    "vertesia",
+    "common",
+    "types",
+    "llm",
+    "ai",
+    "typescript"
+  ],
   "ts_dual_module": {
     "outDir": "lib"
   },

package/src/index.ts

@@ -20,6 +20,7 @@ export * from './query.js';
 export * from './rate-limiter.js';
 export * from './refs.js';
 export * from './runs.js';
+export * from './skill.js';
 export * from "./store/index.js";
 export * from './tenant.js';
 export * from "./training.js";

package/src/interaction.ts

@@ -269,11 +269,20 @@ export interface InteractionEndpoint {
     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;
@@ -373,6 +382,9 @@ export interface InteractionData {
     model?: string;
     model_options?: ModelOptions;
     restriction?: RunDataStorageLevel;
+    /**
+     * @deprecated This is deprecated. Use CompletionResult.type information instead.
+     */
     output_modality?: Modalities;
 }
 export interface Interaction extends InteractionData {
@@ -453,7 +465,8 @@ export interface InteractionExecutionPayload {
      */
     data?: Record<string, any> | `memory:${string}`;
     config?: InteractionExecutionConfiguration;
-    result_schema?: JSONSchema4;
+    //Use null to explicitly state no schema, will not fallback to interaction schema
+    result_schema?: JSONSchema4 | null;
     stream?: boolean;
     do_validate?: boolean;
     tags?: string | string[]; // tags to be added to the execution run
@@ -519,6 +532,27 @@ export enum AgentSearchScope {
     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.
@@ -534,6 +568,24 @@ export interface AgentRunnerOptions {
      */
     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.
@@ -725,7 +777,11 @@ export interface BaseExecutionRun<P = any> {
     config: InteractionExecutionConfiguration;
     error?: InteractionExecutionError;
     source: RunSource;
-    output_modality: Modalities;
+
+    /**
+     * @deprecated This is deprecated. Use CompletionResult.type information instead.
+     */
+    output_modality?: Modalities;
     created_by: string;
     updated_by: string;
 
@@ -773,6 +829,11 @@ export interface ExecutionRunWorkflow {
     activity_type?: string;
 }
 
+export interface PromptModalities {
+    hasVideo: boolean;
+    hasImage: boolean;
+}
+
 export interface InteractionExecutionResult<P = any> extends ExecutionRun<P> {
     tool_use?: ToolUse[];
     conversation?: unknown;
@@ -839,7 +900,8 @@ export interface RateLimitRequestPayload {
     interaction: string,
     environment_id?: string,
     model_id?: string,
-    workflow_run_id?: string
+    workflow_run_id?: string,
+    modalities?: PromptModalities;
 }
 
 export interface RateLimitRequestResponse {

package/src/project.ts

@@ -62,13 +62,109 @@ export enum ResourceVisibility {
 }
 
 
+// ==========================================
+// Project Model Defaults Types
+// ==========================================
+
+/**
+ * Environment and model pair for a default configuration.
+ */
+export interface ModelDefault {
+    environment: string;
+    model: string;
+}
+
+/**
+ * Modality-specific default model overrides.
+ * These override the base default when specific input modalities are detected.
+ */
+export interface ModalityDefaults {
+    /** Override for inputs containing images */
+    image?: ModelDefault;
+    /** Override for inputs containing video (requires video-capable model) */
+    video?: ModelDefault;
+}
+
+/**
+ * System interaction category enum.
+ * Categories group one or more system interactions for default model assignment.
+ */
+export enum SystemInteractionCategory {
+    content_type = "content_type",
+    intake = "intake",
+    analysis = "analysis",
+    non_applicable = "non_applicable"
+}
+
+/**
+ * Map system interaction endpoints to categories.
+ */
+export const SYSTEM_INTERACTION_CATEGORIES: Record<string, SystemInteractionCategory> = {
+    "ExtractInformation": SystemInteractionCategory.intake,
+    "SelectDocumentType": SystemInteractionCategory.intake,
+    "GenerateMetadataModel": SystemInteractionCategory.content_type,
+    "ChunkDocument": SystemInteractionCategory.intake,
+    "IdentifyTextSections": SystemInteractionCategory.intake,
+    "AnalyzeDocument": SystemInteractionCategory.analysis,
+    "ReduceTextSections": SystemInteractionCategory.analysis,
+    "GenericAgent": SystemInteractionCategory.non_applicable,
+    "AdhocTaskAgent": SystemInteractionCategory.non_applicable,
+    "Mediator": SystemInteractionCategory.non_applicable,
+    "AnalyzeConversation": SystemInteractionCategory.analysis,
+    "GetAgentConversationTopic": SystemInteractionCategory.analysis,
+};
+
+/**
+ * Get category for a system interaction endpoint.
+ * Returns undefined if category is non-applicable or endpoint is not recognized.
+ * Note: Caller is responsible for determining if the interaction is a system interaction.
+ * @param endpoint - The interaction endpoint name
+ */
+export function getSystemInteractionCategory(endpoint: string): SystemInteractionCategory | undefined {
+    if (endpoint.startsWith("sys:")) {
+        // Strip sys: prefix
+        endpoint = endpoint.substring(4);
+    }
+    const category = SYSTEM_INTERACTION_CATEGORIES[endpoint];
+    if (category === SystemInteractionCategory.non_applicable) {
+        return undefined;
+    }
+    return category || undefined;
+}
+
+export type SystemDefaults = {
+    [K in SystemInteractionCategory]?: ModelDefault;
+};
+
+/**
+ * Extensible project defaults using map/dictionary pattern.
+ */
+export interface ProjectModelDefaults {
+    /** Base default model - used when no other default applies */
+    base?: ModelDefault;
+    /** Modality-based overrides (image, video) - override base when specific input modalities detected */
+    modality?: ModalityDefaults;
+    /** System interaction category defaults */
+    system?: SystemDefaults;
+}
+
+// ==========================================
+// Project Configuration
+// ==========================================
+
 export interface ProjectConfiguration {
 
     human_context: string;
 
+    /** @deprecated Use defaults.base - kept for backward compatibility */
     default_environment?: string;
+    /** @deprecated Use defaults.base - kept for backward compatibility */
     default_model?: string;
 
+    defaults?: ProjectModelDefaults;
+
+    default_visibility?: ResourceVisibility;
+
     sync_content_properties?: boolean;
 
     embeddings: {

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/doc-analyzer.ts

@@ -55,11 +55,18 @@ export interface DocTableJson extends DocTable {
     data: Object[];
 }
 
+/**
+ * Output format for document processing workflows
+ */
+export type DocProcessorOutputFormat = "xml" | "markdown";
+
 /**
  * Represents a document analysis run status
  */
 export interface DocAnalyzeRunStatusResponse extends WorkflowRunStatus {
     progress?: DocAnalyzerProgress;
+    /** The output format being used for processing (markdown or xml) */
+    output_format?: DocProcessorOutputFormat;
 }
 
 export interface DocAnalyzerResultResponse {
@@ -76,6 +83,8 @@ export interface DocAnalyzerProgress {
     visuals: DocAnalyzerProgressStatus;
     started_at?: number;
     percent: number;
+    /** The output format being used for processing (markdown or xml) */
+    output_format?: DocProcessorOutputFormat;
 }
 
 interface DocAnalyzerProgressStatus {

package/src/store/store.ts

@@ -13,6 +13,7 @@ export enum ContentObjectApiHeaders {
 export enum ContentObjectStatus {
     created = "created",
     processing = "processing", // the was created and still processing
+    ready = "ready", // the object is rendered and ready to be used
     completed = "completed",
     failed = "failed",
     archived = "archived",
@@ -75,6 +76,27 @@ export interface GenerationRunMetadata {
     target?: string;
 }
 
+// Base rendition interface for document and audio
+export interface Rendition {
+    name: string;
+    content: ContentSource;
+}
+
+// Rendition with dimensions for video and image
+export interface RenditionWithDimensions extends Rendition {
+    dimensions: Dimensions;
+}
+
+/**
+ * @deprecated Use RenditionWithDimensions instead
+ */
+export type VideoRendition = RenditionWithDimensions;
+
+export const POSTER_RENDITION_NAME = "Poster";
+export const AUDIO_RENDITION_NAME = "Audio";
+export const WEB_VIDEO_RENDITION_NAME = "Web";
+export const PDF_RENDITION_NAME = "PDF";
+
 export interface ContentMetadata {
     // Common fields for all media types
     type?: ContentNature;
@@ -83,9 +105,10 @@ export interface ContentMetadata {
     location?: Location;
     generation_runs: GenerationRunMetadata[];
     etag?: string;
+    renditions?: Rendition[];
 }
 
-// Example of type-specific metadata interfaces (optional, for better type safety)
+// Type-specific metadata interfaces
 export interface TemporalMediaMetadata extends ContentMetadata {
     duration?: number; // in seconds
     transcript?: Transcript;
@@ -94,26 +117,17 @@ export interface TemporalMediaMetadata extends ContentMetadata {
 export interface ImageMetadata extends ContentMetadata {
     type: ContentNature.Image;
     dimensions?: Dimensions;
+    renditions?: RenditionWithDimensions[];
 }
 
 export interface AudioMetadata extends TemporalMediaMetadata {
     type: ContentNature.Audio;
 }
 
-export interface VideoRendition {
-    name: string;
-    dimensions: Dimensions;
-    content: ContentSource
-}
-
-export const POSTER_RENDITION_NAME = "Poster";
-export const AUDIO_RENDITION_NAME = "Audio";
-export const WEB_VIDEO_RENDITION_NAME = "Web";
-
 export interface VideoMetadata extends TemporalMediaMetadata {
     type: ContentNature.Video;
     dimensions?: Dimensions;
-    renditions?: VideoRendition[];
+    renditions?: RenditionWithDimensions[];
     hasAudio?: boolean;
 }
 
@@ -398,6 +412,7 @@ export interface GetRenditionParams {
     max_hw?: number;
     generate_if_missing?: boolean;
     sign_url?: boolean;
+    block_on_generation?: boolean;
 }
 
 export interface GetRenditionResponse {
@@ -428,6 +443,13 @@ export interface GetFileUrlResponse {
     path: string;
 }
 
+export interface SetFileMetadataPayload {
+    /** The file path (relative to bucket) or full URI */
+    file: string;
+    /** Custom metadata key-value pairs to set on the file */
+    metadata: Record<string, string>;
+}
+
 export enum ContentObjectProcessingPriority {
     normal = "normal",
     low = "low",

package/src/user.ts

@@ -38,21 +38,16 @@ export enum BillingMethod {
     invoice = 'invoice'
 }
 
-
-interface AccountBilling {
+export interface AccountBilling {
     method: BillingMethod;
     stripe_customer_id?: string;
 }
+
 export interface Account {
     id: string;
     name: string;
 
     email_domains: string[];
-    members: {
-        role: ProjectRoles;
-        user: UserRef;
-        disabled: boolean;
-    }[];
 
     onboarding: {
         completed: boolean,

package/src/utils/schemas.ts

@@ -5,6 +5,28 @@ import { InCodePrompt, InteractionRefWithSchema, PopulatedInteraction } from "..
 import { ExecutablePromptSegmentDef, PromptSegmentDefType } from "../prompt.js";
 
 
+// Remove custom properties from the JSON before sending further down execution pipeline
+export function removeExtraProperties<T>(schema: T): T {
+    if (!schema) return schema;
+    if (Array.isArray(schema)) {
+        for (const item of schema) {
+            removeExtraProperties(item);
+        }
+    } else if (typeof schema === 'object') {
+        const obj = schema as Record<string, any>;
+        for (const [key, value] of Object.entries(obj)) {
+            if (key === 'editor' && (value === 'textarea' || value === 'document' || value === 'media')) {
+                delete obj[key];
+            } else if (key === 'format' && (value === 'textarea' || value === 'document' || value === 'media')) {
+                delete obj[key];
+            } else if (typeof value === 'object') {
+                removeExtraProperties(value)
+            }
+        }
+    }
+    return schema;
+}
+
 export function mergeJSONSchemas(schemas: JSONSchema[]) {
     const props: Record<string, JSONSchema4> = {};
     let required: string[] = [];