@vertesia/common 0.81.1 → 1.0.0-dev.20260203.130115Z

package/src/project.ts

@@ -176,6 +176,36 @@ export interface ProjectConfiguration {
     datacenter?: string;
     storage_bucket?: string;
 
+    /**
+     * Enable real-time streaming of agent LLM responses to clients.
+     * When enabled, LLM responses are streamed chunk-by-chunk via Redis pub/sub.
+     * Defaults to true if not specified.
+     */
+    agent_streaming_enabled?: boolean;
+
+    /**
+     * Indexing configuration for this project.
+     * Controls whether indexing and querying are enabled at the project level.
+     */
+    indexing?: {
+        /**
+         * Enable indexing for content objects in this project.
+         * When enabled, content changes trigger indexing workflows.
+         * Defaults to true - indexing is always on when ES infrastructure is available.
+         */
+        enabled?: boolean;
+    };
+
+    /**
+     * Primary language for full-text search analysis.
+     * ISO 639-1 code (e.g., 'en', 'fr', 'ja', 'de').
+     * Determines which Elasticsearch analyzer is used for the text field.
+     * Defaults to 'en' (English/standard analyzer).
+     *
+     * Changing this value requires a full reindex to take effect.
+     */
+    main_language?: string;
+
 }
 
 // export interface ProjectConfigurationEmbeddings {
@@ -239,7 +269,6 @@ export const ProjectRefPopulate = "id name account";
 export interface EmbeddingsStatusResponse {
     status: string;
     embeddingRunsInProgress?: number;
-    totalRunsInProgress?: number;
     totalIndexableObjects?: number;
     embeddingsModels?: string[];
     objectsWithEmbeddings?: number;
@@ -250,6 +279,66 @@ export interface EmbeddingsStatusResponse {
     }
 }
 
+/**
+ * Response from indexing status endpoint
+ */
+export interface IndexingStatusResponse {
+    /** Whether indexing infrastructure is available globally */
+    infrastructureEnabled: boolean;
+    /** Whether indexing is enabled for this project */
+    indexingEnabled: boolean;
+    /** @deprecated Now derived from indexingEnabled - queries automatically route to index when indexing is enabled */
+    query_enabled: boolean;
+    /** Index status */
+    index: {
+        /** Whether the index exists */
+        exists: boolean;
+        /** Alias name (used for queries) */
+        aliasName: string;
+        /** Actual index name (versioned) */
+        indexName: string;
+        /** Index version (timestamp when created) */
+        version: number;
+        /** When the current index was created */
+        createdAt: string | null;
+        /** Number of documents in the index */
+        documentCount: number;
+        /** Index size in bytes */
+        sizeBytes: number;
+    };
+    /** MongoDB document count for comparison */
+    mongoDocumentCount: number;
+    /** Whether a reindex is currently in progress */
+    reindexInProgress: boolean;
+    /** Reindex progress (if reindex is in progress) */
+    reindexProgress?: {
+        /** Total documents to reindex */
+        total: number;
+        /** Documents processed so far */
+        processed: number;
+        /** Successfully indexed documents */
+        successful: number;
+        /** Failed documents */
+        failed: number;
+        /** Current status (e.g., "indexing", "complete") */
+        status: string;
+        /** Current batch number */
+        currentBatch: number;
+        /** Total number of batches */
+        totalBatches: number;
+        /** Percentage complete (0-100) */
+        percentComplete: number;
+        /** Batches processed per second */
+        batchesPerSecond: number;
+        /** Documents processed per second */
+        docsPerSecond: number;
+        /** Elapsed time in seconds */
+        elapsedSeconds: number;
+        /** Estimated seconds remaining (null if unknown) */
+        estimatedSecondsRemaining: number | null;
+    };
+}
+
 export interface ProjectIntegrationListEntry {
     id: SupportedIntegrations;
     enabled: boolean;

package/src/prompt.ts

@@ -53,8 +53,9 @@ export interface PromptTemplateRefWithSchema extends PromptTemplateRef {
 }
 
 export enum TemplateType {
-    text = "text",
     jst = "jst",
+    handlebars = "handlebars",
+    text = "text",
 }
 export interface ExecutablePromptTemplate {
     role: PromptRole;

package/src/skill.ts

@@ -10,6 +10,7 @@
  * These are automatically synced to the sandbox when the skill is used.
  */
 
+
 /**
  * Context provided when searching for relevant skills
  */

package/src/store/conversation-state.ts

@@ -0,0 +1,152 @@
+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[];
+
+    /**
+     * Activity ID from the latest LLM call (for deduplication with streamed content).
+     * Set by streamToRedis when completing async activities.
+     */
+    latest_activity_id?: 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[];
+}

package/src/store/dsl-workflow.ts

@@ -190,11 +190,23 @@ export interface DSLChildWorkflowStep extends DSLWorkflowStepBase {
      * since it may contain references to workflow execution vars.
      */
     output?: string;
+    /**
+     * A JSON expression which evaluates to true or false similar to mongo matches.
+     * The child workflow will only execute if the condition is satisfied.
+     * Example: {$eq: {wfVarName: value}}
+     */
+    condition?: Record<string, any>;
     /**
      * In case the dslWorkflow is used as a child workflow the spec is used to define the child workflow.
      * If spec is defined then the name must be "dslWorkflow"
      */
     spec?: DSLWorkflowSpec;
+    /**
+     * If true, copy the parent's workspace artifacts (scripts/, files/, skills/, docs/, out/)
+     * to the child workflow's agent space before execution. Defaults to true.
+     * conversation.json and tools.json are never copied.
+     */
+    inherit_artifacts?: boolean;
     options?: {
         memo?: Record<string, any>;
         retry?: DSLRetryPolicy;

package/src/store/hive-memory.ts

@@ -0,0 +1,167 @@
+import { BaseObject } from "./common.js";
+
+/**
+ * Tool recommendation within a hive memory unit
+ */
+export interface HiveMemoryToolRecommendation {
+    tool_name: string;
+    guidance: string;
+}
+
+/**
+ * Memory unit scope - project-scoped by default, can be elevated to account
+ */
+export type HiveMemoryScope = 'project' | 'account';
+
+/**
+ * Base interface for hive memory items (list/summary view)
+ */
+export interface HiveMemoryItem extends BaseObject {
+    // Classification
+    task_category: string;  // "document-analysis", "data-extraction", etc.
+    domain?: string;        // "financial", "legal", etc.
+
+    // Summary
+    summary: string;
+
+    // Tools involved in the learnings
+    tools_involved: string[];
+
+    // Quality metrics
+    confidence_score: number;     // 0-1
+    usage_count: number;
+    success_correlation: number;  // correlation with successful runs
+    contribution_count: number;   // number of runs that contributed
+
+    // Scoping
+    scope: HiveMemoryScope;
+}
+
+/**
+ * Full hive memory unit with all learnings and patterns
+ */
+export interface HiveMemory extends HiveMemoryItem {
+    // Objective patterns this memory applies to
+    objective_patterns: string[];
+
+    // Learnings
+    general_learnings: string[];
+    best_practices: string[];
+    pitfalls_to_avoid: string[];
+    tool_recommendations: HiveMemoryToolRecommendation[];
+
+    // Vector search
+    embedding?: number[];
+
+    // Security field for granular permissions
+    security?: Record<string, string[]>;
+}
+
+/**
+ * Payload for creating a new hive memory unit
+ */
+export interface CreateHiveMemoryPayload {
+    // Classification
+    task_category: string;
+    domain?: string;
+
+    // Content
+    summary: string;
+    objective_patterns: string[];
+
+    // Learnings
+    general_learnings: string[];
+    best_practices?: string[];
+    pitfalls_to_avoid?: string[];
+    tool_recommendations?: HiveMemoryToolRecommendation[];
+
+    // Metadata
+    tools_involved?: string[];
+
+    // Quality (optional, defaults applied)
+    confidence_score?: number;
+
+    // Scoping
+    scope?: HiveMemoryScope;
+
+    // Standard fields
+    name?: string;
+    description?: string;
+    tags?: string[];
+}
+
+/**
+ * Payload for updating an existing hive memory unit
+ */
+export interface UpdateHiveMemoryPayload {
+    // Classification updates
+    task_category?: string;
+    domain?: string;
+
+    // Content updates
+    summary?: string;
+
+    // Array additions (merged with existing)
+    add_objective_patterns?: string[];
+    add_general_learnings?: string[];
+    add_best_practices?: string[];
+    add_pitfalls_to_avoid?: string[];
+    add_tool_recommendations?: HiveMemoryToolRecommendation[];
+    add_tools_involved?: string[];
+
+    // Quality updates
+    confidence_score?: number;
+    increment_usage_count?: boolean;
+    increment_contribution_count?: boolean;
+    success_correlation?: number;
+
+    // Scoping
+    scope?: HiveMemoryScope;
+
+    // Standard fields
+    name?: string;
+    description?: string;
+    tags?: string[];
+}
+
+/**
+ * Search parameters for finding relevant memories
+ */
+export interface HiveMemorySearchParams {
+    // Semantic search
+    query?: string;              // Natural language query
+    embedding?: number[];        // Pre-computed embedding for vector search
+
+    // Filters
+    task_category?: string;
+    domain?: string;
+    tools_involved?: string[];
+    scope?: HiveMemoryScope;
+    min_confidence?: number;     // Minimum confidence score (0-1)
+
+    // Pagination
+    limit?: number;              // Default: 5
+    offset?: number;
+}
+
+/**
+ * Response from memory search
+ */
+export interface HiveMemorySearchResult {
+    memories: HiveMemory[];
+    total: number;
+}
+
+/**
+ * Formatted memory for agent consumption
+ */
+export interface FormattedMemoryForAgent {
+    category: string;
+    domain?: string;
+    summary: string;
+    learnings: string[];
+    best_practices: string[];
+    pitfalls_to_avoid: string[];
+    tool_guidance: { tool: string; guidance: string }[];
+    confidence: number;
+}

package/src/store/index.ts

@@ -1,9 +1,12 @@
 export * from "./activity-catalog.js";
 export * from "./collections.js";
 export * from "./common.js";
+export * from "./conversation-state.js";
 export * from "./doc-analyzer.js";
 export * from "./dsl-workflow.js";
+export * from "./hive-memory.js";
 export * from "./object-types.js";
+export * from "./schedule.js";
 export * from "./signals.js";
 export * from "./store.js";
 export * from "./temporalio.js";