@vertesia/common 0.24.0-dev.202601221707

package/src/json-schema.ts

@@ -0,0 +1,7 @@
+export type {
+    JSONSchema,
+    JSONSchemaArray,
+    JSONSchemaObject,
+    JSONSchemaType,
+    JSONSchemaTypeName,
+} from "@llumiverse/common";

package/src/json.ts

@@ -0,0 +1,4 @@
+export type {
+    JSONArray, JSONComposite, JSONObject,
+    JSONPrimitive, JSONValue
+} from "@llumiverse/common";

package/src/meters.ts

@@ -0,0 +1,30 @@
+import { BillingMethod } from "./user.js";
+
+
+export interface MeterAdjustment {
+    meter: string;
+    value: string;
+    identifier?: string;
+}
+
+
+export interface AdjustMetersMeterWorkflowParams {
+    adjustments: MeterAdjustment[];
+}
+
+export enum MeterNames {
+    analyzed_pages = 'analyzed_pages',
+    extracted_tables = 'extracted_tables',
+    analyzed_images = 'analyzed_images',
+    input_token_used = 'input_token_used',
+    output_token_used = 'output_token_used',
+    task_run = 'task_run',
+}
+
+
+export interface StripeBillingStatusResponse {
+    status: 'enabled' | 'disabled',
+    billing_method: BillingMethod | null,
+    portal_url?: string,
+    reason?: string
+}

package/src/model_utility.ts

@@ -0,0 +1 @@
+export { supportsToolUse } from "@llumiverse/common";

package/src/payload.ts

@@ -0,0 +1,83 @@
+import { FacetSpec } from "./facets.js";
+import {
+    ComplexCollectionSearchQuery,
+    ComplexSearchQuery,
+    InteractionSearchQuery,
+    ObjectSearchQuery,
+    ObjectTypeSearchQuery,
+    PromptSearchQuery,
+    RunSearchQuery,
+    SimpleSearchQuery
+} from "./query.js";
+
+export interface SearchPayload {
+    facets?: FacetSpec[];
+    /**
+     * If the facets should be limited to the current page of results.
+     * Defaults to false. When false, the facets are independent of the search results page.
+     */
+    limit_facets?: boolean;
+    query?: SimpleSearchQuery;
+    limit?: number;
+    offset?: number;
+    select?: string;
+    all_revisions?: boolean;
+    from_root?: string;
+}
+
+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 ComputeCollectionFacetPayload extends Omit<ComputeFacetPayload, 'query'> {
+    query?: ComplexCollectionSearchQuery;
+}
+
+export interface ComputeInteractionFacetPayload extends ComputeFacetPayload {
+    query?: InteractionSearchQuery;
+}
+
+export interface ComputeObjectFacetPayload extends ComputeFacetPayload {
+    query?: ComplexSearchQuery;
+}
+
+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/pending-asks.ts

@@ -0,0 +1,106 @@
+/**
+ * Types for tracking pending ask_user requests and webhook notifications.
+ * Used to notify external systems when agents are waiting for user input.
+ */
+
+import { UserChannel } from "./email.js";
+
+// ================= Pending Ask Data ====================
+
+/**
+ * Status of a pending ask request.
+ */
+export type PendingAskStatus = 'pending' | 'resolved' | 'expired';
+
+/**
+ * Data stored in Redis for pending ask_user requests.
+ * Tracks which agents are waiting for user input and enables
+ * both webhook notifications and portal views.
+ */
+export interface PendingAskData {
+    /** Unique identifier for this ask (10-char alphanumeric) */
+    askId: string;
+    /** Temporal workflow run ID */
+    runId: string;
+    /** Temporal workflow ID */
+    workflowId: string;
+    /** Project ID */
+    projectId: string;
+    /** Account ID */
+    accountId: string;
+    /** Name of the agent/interaction that asked */
+    agentName: string;
+    /** Questions asked by the agent */
+    questions: string[];
+    /** Timeout in hours (default 48) */
+    timeoutHours: number;
+    /** Communication channels configured for the conversation */
+    userChannels: UserChannel[];
+    /** Timestamp when the ask was created (ms since epoch) */
+    createdAt: number;
+    /** Timestamp when the ask expires (ms since epoch) */
+    expiresAt: number;
+    /** Current status of the ask */
+    status: PendingAskStatus;
+    /** Timestamp when resolved (ms since epoch) */
+    resolvedAt?: number;
+    /** User's response (after resolution) */
+    response?: string;
+}
+
+// ================= Webhook Events ====================
+
+/**
+ * Event types for ask_user webhooks.
+ */
+export type AskUserWebhookEventType = 'ask_user.requested' | 'ask_user.resolved';
+
+/**
+ * Simplified channel info for webhook payloads.
+ */
+export interface WebhookChannelInfo {
+    type: 'email' | 'interactive';
+    /** Email address (only for email channels) */
+    email?: string;
+}
+
+/**
+ * Webhook payload sent when ask_user events occur.
+ * Sent to configured webhook endpoints when agents request user input
+ * or when users respond.
+ */
+export interface AskUserWebhookEvent {
+    /** Event type */
+    event: AskUserWebhookEventType;
+    /** Timestamp of the event (ms since epoch) */
+    timestamp: number;
+    /** Unique identifier for this ask */
+    askId: string;
+    /** Temporal workflow run ID */
+    runId: string;
+    /** Temporal workflow ID */
+    workflowId: string;
+    /** Project ID */
+    projectId: string;
+    /** Name of the agent/interaction */
+    agentName: string;
+    /** Questions asked by the agent */
+    questions: string[];
+    /** Communication channels available */
+    userChannels: WebhookChannelInfo[];
+    /** User's response (only for resolved events) */
+    response?: string;
+    /** Timestamp when resolved (only for resolved events) */
+    resolvedAt?: number;
+    /** How long the agent waited for response in ms (only for resolved events) */
+    waitDurationMs?: number;
+}
+
+// ================= API Types ====================
+
+/**
+ * Response from listing pending asks.
+ */
+export interface ListPendingAsksResponse {
+    asks: PendingAskData[];
+}

package/src/project.ts

@@ -0,0 +1,263 @@
+import { SupportedIntegrations } from "./integrations.js";
+import { AccountRef } from "./user.js";
+
+export interface ICreateProjectPayload {
+    name: string;
+    namespace: string;
+    description?: string;
+    auto_config?: boolean;
+}
+export enum ProjectRoles {
+    owner = "owner", // all permissions
+    admin = "admin", // all permissions
+    manager = "manager", // all permissions but manage_account, manage_billing
+    developer = "developer", // all permissions but manage_account, manage_billing, manage_roles, delete
+    application = "application", // executor + request_pk
+    consumer = "consumer", // required permissions for users of micro apps
+    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
+    app_member = "app_member", // used to mark an user have access to an application. does not provide any permission on its own
+    content_superadmin = "content_superadmin", // can see all content objects and collections
+}
+
+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;
+    /**
+     * Only set when fetching the list of projects visible to an user which is an org admin or owner.
+     * If present and true, it means that the project is not accessible to the user.(even if it visible in listing)
+     * If not present or false then the project is accessible to the user.
+     */
+    restricted?: boolean;
+}
+
+export enum ResourceVisibility {
+    public = "public",
+    account = "account",
+    project = "project"
+}
+
+
+// ==========================================
+// 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: {
+        text?: ProjectConfigurationEmbeddings;
+        image?: ProjectConfigurationEmbeddings;
+        properties?: ProjectConfigurationEmbeddings
+    }
+
+    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;
+
+}
+
+// export interface ProjectConfigurationEmbeddings {
+//     environment: string;
+//     max_tokens: number;
+//     dimensions: number;
+//     model?: string;
+// }
+
+export enum SupportedEmbeddingTypes {
+    text = "text",
+    image = "image",
+    properties = "properties"
+}
+
+export enum FullTextType {
+    full_text = "full_text"
+}
+
+export type SearchTypes = SupportedEmbeddingTypes | FullTextType;
+
+export const SearchTypes = {
+    ...SupportedEmbeddingTypes,
+    ...FullTextType
+} as const;
+
+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>;
+    plugins: string[];
+    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,103 @@
+import type { JSONObject } from "@llumiverse/common";
+import { PromptRole } from "@llumiverse/common";
+import type { JSONSchema4 } from "json-schema";
+import { ProjectRef } from "./project.js";
+
+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;
+}
+/**
+ * Used for prompt rendering at interaction execution
+ */
+export interface ExecutablePromptSegmentDef
+    extends Omit<PromptSegmentDef, "template"> {
+    template?: ExecutablePromptTemplate;
+}
+
+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 {
+    jst = "jst",
+    handlebars = "handlebars",
+    text = "text",
+}
+export interface ExecutablePromptTemplate {
+    role: PromptRole;
+    content: string;
+    content_type: TemplateType;
+    inputSchema?: JSONSchema4;
+}
+export interface PromptTemplate extends ExecutablePromptTemplate {
+    id: string;
+    name: string;
+    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;
+    test_data?: JSONObject; // optional test data satisfying the schema
+    script?: string; // cache the template output
+    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 schema 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">
+    > { }