@vertesia/workflow 0.42.2

package/src/iterative-generation/activities/generateToc.ts

@@ -0,0 +1,98 @@
+import { WorkflowExecutionPayload } from "@vertesia/common";
+import { getClient } from "../../utils/client.js";
+import { buildAndPublishMemoryPack } from "../../utils/memory.js";
+import { IterativeGenerationPayload, OutputMemoryMeta, Toc, TocIndex } from "../types.js";
+import { executeWithVars, tocIndex } from "../utils.js";
+
+const defaultTocSchema = {
+    "type": "object",
+    "properties": {
+        "sections": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "description": "the id of the section, can be a filename if working on a file, a slug if working on a document or path, or a unique identifier if working on a model."
+                    },
+                    "operation": {
+                        "type": "string",
+                        "enum": ["create", "update", "delete"],
+                        "description": "The operation to perform on the section, create, update or delete. If update, you will be requested later to provide the list of change operation to perform."
+                    },
+                    "name": {
+                        "type": "string",
+                        "description": "The name or title of the section, should be the path in the OpenAPI spec, of the title of the section/part."
+                    },
+                    "description": {
+                        "type": "string"
+                    },
+                    "instructions": {
+                        "type": "string"
+                    },
+                    "parts":
+                    {
+                        "type": "array",
+                        "description": "when the section is too large, you can split it into parts, each part should have a title and description. Use it to split the section into subsection. When doing an API documentation, you can do one part for each path. When generating code, you can do one part for each method. When generating an OpenAPI spec, you can do one part for each operation.",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "id": {
+                                    "type": "string",
+                                    "description": "the id of the part, can be a filename if working on a file, a slug if working on a document or path, or a unique identifier if working on a model."
+                                },
+                                "name": {
+                                    "type": "string",
+                                    "description": "The name or title of the part, should be the path in the OpenAPI spec, of the title of the section/part."
+                                },
+                                /*
+                                "description": {
+                                    "type": "string"
+                                },
+                                */
+                                "instructions": {
+                                    "type": "string"
+                                }
+                            },
+                            "required": [
+                                "id",
+                                "name",
+                            ]
+                        }
+                    }
+                },
+                "required": [
+                    "id",
+                    "name",
+                    "operation"
+                ]
+            }
+        }
+    },
+    "required": [
+        "sections"
+    ]
+}
+
+export async function it_gen_generateToc(payload: WorkflowExecutionPayload): Promise<TocIndex> {
+    const vars = payload.vars as IterativeGenerationPayload;
+
+    const schema = vars.toc_schema || defaultTocSchema;
+
+    const client = getClient(payload);
+
+    const run = await executeWithVars(client, vars.interaction, vars, undefined, schema);
+
+    const toc = run.result as Toc;
+
+    await buildAndPublishMemoryPack(client, `${vars.memory}/output`, async () => {
+        return {
+            toc,
+            lastProcessdPart: undefined, // the part index (a number array)
+            previouslyGenerated: ""
+        } as OutputMemoryMeta
+    });
+
+    return tocIndex(toc);
+}

package/src/iterative-generation/activities/index.ts

@@ -0,0 +1,4 @@
+export { it_gen_generateToc } from './generateToc.js';
+export { it_gen_generatePart } from './generatePart.js';
+export { it_gen_extractToc } from './extractToc.js';
+export { it_gen_finalizeOutput } from './finalizeOutput.js'

package/src/iterative-generation/iterativeGenerationWorkflow.ts

@@ -0,0 +1,67 @@
+import { WorkflowExecutionPayload } from "@vertesia/common";
+
+import { log, proxyActivities } from "@temporalio/workflow";
+import * as activities from "./activities/index.js";
+import { IterativeGenerationPayload, PartIndex, SECTION_ID_PLACEHOLDER } from "./types.js";
+
+const {
+    it_gen_extractToc,
+    it_gen_generateToc,
+    it_gen_generatePart,
+    it_gen_finalizeOutput
+} = proxyActivities<typeof activities>({
+    startToCloseTimeout: "15 minute",
+    retry: {
+        initialInterval: '30s',
+        backoffCoefficient: 2,
+        maximumAttempts: 20,
+        maximumInterval: 100 * 30 * 1000, //ms
+        nonRetryableErrorTypes: [],
+    },
+});
+
+export async function iterativeGenerationWorkflow(payload: WorkflowExecutionPayload) {
+    log.info(`Executing Iterative generation workflow.`);
+
+    const vars = payload.vars as IterativeGenerationPayload;
+    if (vars.section_file_pattern && !vars.section_file_pattern.includes(SECTION_ID_PLACEHOLDER)) {
+        throw new Error(`Invalid section_file_pattern: ${vars.section_file_pattern}. It must include the ${SECTION_ID_PLACEHOLDER} placeholder.`);
+    }
+
+    // extractToc tries to extract the toc from the input memory pack (toc.json or toc.yaml)
+    // the generateToc activity is retiurning the toc hierarchy.
+    // It doesn't include extra TOC details like description etc.
+    // To minimize the payload size only the hierarchy and the section/part names are returned
+    let toc = await it_gen_extractToc(payload);
+    if (!toc) {
+        log.info(`No TOC was specified in the input memory pack. Generating one.`);
+        toc = await it_gen_generateToc(payload);
+    } else {
+        log.info(`Using the TOC specified in the input memory pack.`);
+    }
+
+    if (toc.sections.length === 0) {
+        //TODO how to handle this case?
+        throw new Error("Nothing to generate: TOC is empty");
+    }
+
+    for (const section of toc.sections) {
+        log.info(`Generating section: ${formatPath(section)}`);
+        await it_gen_generatePart(payload, section.path);
+
+        if (section.parts) {
+            for (const part of section.parts) {
+                log.info(`Generating part: ${formatPath(part)}`);
+                await it_gen_generatePart(payload, part.path);
+            }
+        }
+    }
+
+    log.info(`Post-processing output memory pack`);
+    await it_gen_finalizeOutput(payload);
+}
+
+function formatPath(node: PartIndex) {
+    // we print 1 based indexes
+    return node.path.map(i => i + 1).join('.') + ' ' + node.name;
+}

package/src/iterative-generation/types.ts

@@ -0,0 +1,99 @@
+
+export const SECTION_ID_PLACEHOLDER = '%id';
+
+/**
+ * An iterative generation workflow uses 2 memory packs one for input and the other for output.
+ * The input memory packs must be available in the project blobs bucket at `${tenant_id/memories/${memory_name}/input.tar.gz`.
+ * The output memory pack will be generated at `${tenant_id/memories/${memory_name}/output.tar.gz`.
+ * Each iteration is overwriting the output memory pack with the new generated content.
+ * The complete name of the input and output memory packs are: "${name}/input" and "${name}/output" where name is the base memory name.
+ */
+export interface IterativeGenerationPayload {
+    // the main interaction to execute. If iterative_generation is defined
+    // the main interaction will only be used to prepare the iteration (to generate the TOC)
+    // otherwise it will be used for the iterative generation too.
+    interaction: string;
+    // if defined this will be used for the iterative interaction which will genrate parts.
+    // otherwise the main interaction will be used for iterative generation.
+    iterative_interaction?: string;
+    // the environment to use
+    environment?: string;
+    // the model to use
+    model?: string;
+    // A custom max tokens
+    max_tokens?: number;
+    // A custom temperature
+    temperature?: number;
+    // the memory pack group name
+    memory: string;
+    // the input memory pack mapping
+    input_mapping?: Record<string, string>;
+    // custom toc schema if any TODO remove this
+    toc_schema?: Record<string, any>
+    /**
+     * If not set to "none" the previously generated content will be passed to the iteration.
+     * If not set at all defaults to "section".
+     * If "section" is used only the section content previously generated will be passed to the next iteration.
+     * If "document" is used the whole previopusly generated document content will be passed to the next iteration.
+     * Defaults to section.
+     */
+    rememberance_strategy?: "document" | "section" | "none";
+    /**
+     * If present will save sections in files using the pattern
+     * The pattern must include a placeholder for the section id: %id.
+     * Examples: `sections/%id.md`, `%id/page.mdx` etc.
+     * @see SECTION_ID_PLACEHOLDER
+     */
+    section_file_pattern?: string;
+    /**
+     * An optional header to prepend to the section files.
+     * The header can contain the following variables:
+     * - ${section} - the section object
+     * - ${date} - the date when the file was generated
+     */
+    section_file_header?: string;
+}
+
+export interface TocPart {
+    id: string;
+    name: string;
+    description?: string;
+    instructions?: string;
+}
+
+export interface TocSection {
+    id: string;
+    name: string;
+    description?: string;
+    instructions?: string;
+    parts?: TocPart[];
+}
+
+export interface Toc {
+    sections: TocSection[];
+}
+
+
+export interface SectionIndex extends PartIndex {
+    parts?: PartIndex[];
+}
+export interface PartIndex {
+    path: number[];
+    name: string;
+}
+export interface TocIndex {
+    sections: SectionIndex[];
+}
+
+export interface OutputMemoryMeta {
+    toc: Toc;
+    previouslyGenerated: string;
+    lastProcessdPart?: number[] | undefined;
+}
+
+export interface Section {
+    id: string;
+    name: string;
+    description?: string;
+    content: string;
+}

package/src/iterative-generation/utils.ts

@@ -0,0 +1,123 @@
+import { ComposableClient } from "@vertesia/client";
+import { ExecutionRun } from "@vertesia/common";
+import { ApplicationFailure } from "@temporalio/workflow";
+import { OutputMemoryMeta, PartIndex, Toc, TocIndex, TocSection } from "./types.js";
+
+export interface ExecuteOptions {
+    interaction: string;
+    memory: string;
+    memory_mapping?: Record<string, any>;
+    environment?: string;
+    model?: string;
+    max_tokens?: number;
+    temperature?: number;
+    result_schema?: Record<string, any>;
+}
+
+export async function execute<T = any>(client: ComposableClient, options: ExecuteOptions): Promise<ExecutionRun<any, T>> {
+    return client.interactions.executeByName(options.interaction, {
+        data: {
+            ...options.memory_mapping,
+            "@memory": options.memory
+        },
+        result_schema: options.result_schema,
+        config: {
+            environment: options.environment,
+            model: options.model,
+            max_tokens: options.max_tokens,
+            temperature: options.temperature,
+        }
+    });
+}
+
+export function executeWithVars<T = any>(client: ComposableClient, interaction: string, vars: Record<string, any>, mapping?: Record<string, any>, result_schema?: Record<string, any>): Promise<ExecutionRun<any, T>> {
+    if (mapping) {
+        mapping = { ...vars.input_mapping, ...mapping };
+    } else {
+        mapping = vars.input_mapping;
+    }
+    return execute(client, {
+        interaction: interaction,
+        memory: `${vars.memory}/input`,
+        memory_mapping: mapping,
+        environment: vars.environment,
+        model: vars.model,
+        max_tokens: vars.max_tokens,
+        temperature: vars.temperature,
+        result_schema: result_schema
+    });
+}
+
+export function isSamePartIndex(part1: number[], part2: number[]) {
+    return part1 && part2 && part1.length === part2.length && part1.every((v, i) => v === part2[i]);
+}
+
+export function getPreviousPathIndex(toc: Toc, pathIndex: number[]): number[] | null {
+    let [sectionIdx, partIdx] = pathIndex;
+    if (partIdx === undefined) {
+        let prevSectionIdx = sectionIdx - 1;
+        if (prevSectionIdx < 0) {
+            return null;
+        } else {
+            const prevParts = toc.sections[prevSectionIdx].parts;
+            if (prevParts && prevParts.length > 0) { // return the last part of the previous section
+                return [prevSectionIdx, prevParts.length - 1];
+            } else { // if no parts return the section itself
+                return [prevSectionIdx];
+            }
+        }
+    } else if (partIdx > 0) { // return the previous part in the same section
+        return [sectionIdx, partIdx - 1];
+    } else { // if the first part return the section itself
+        return [sectionIdx];
+    }
+}
+
+
+export function expectMemoryIsConsistent(meta: OutputMemoryMeta, pathIndex: number[]) {
+    const metaLastProcessedPart = meta.lastProcessdPart;
+    if (!metaLastProcessedPart) {
+        if (pathIndex.length > 1 && pathIndex[0] !== 0) {
+            throw ApplicationFailure.nonRetryable('Memory last processed part is not consitent with the workflow.', 'MemoryPackNotConsistent', { currentIndex: pathIndex, expectedPreviousIndex: [pathIndex[0], pathIndex[1] - 1], previousIndex: metaLastProcessedPart });
+        } else {
+            return;
+        }
+    }
+    const prevPathIndex = getPreviousPathIndex(meta.toc, pathIndex);
+    if (!prevPathIndex) {
+        throw ApplicationFailure.nonRetryable('Memory last processed part is not consitent with the workflow', 'MemoryPackNotConsistent', { currentIndex: pathIndex, expectedPreviousIndex: prevPathIndex, previousIndex: metaLastProcessedPart });
+    } else if (!isSamePartIndex(prevPathIndex, metaLastProcessedPart)) {
+        throw ApplicationFailure.nonRetryable('Memory last processed part is not consitent with the workflow', 'MemoryPackNotConsistent', { currentIndex: pathIndex, expectedPreviousIndex: prevPathIndex, previousIndex: meta.lastProcessdPart });
+    }
+}
+
+export function sectionWithoutParts(section: TocSection) {
+    const clone = { ...section };
+    delete clone.parts;
+    return clone;
+}
+
+export function tocIndex(toc: Toc): TocIndex {
+    const index = { sections: [] } as TocIndex;
+    const sections = toc.sections;
+    for (let i = 0, l = sections.length; i < l; i++) {
+        const section = sections[i];
+        const indexParts: PartIndex[] = [];
+        if (section.parts) {
+            const parts = section.parts;
+            for (let k = 0, ll = section.parts.length; k < ll; k++) {
+                const part = parts[k];
+                indexParts.push({
+                    name: part.id,
+                    path: [i, k]
+                });
+            }
+        }
+        index.sections.push({
+            name: section.id,
+            path: [i],
+            parts: indexParts
+        });
+    }
+    return index;
+}

package/src/result-types.ts

@@ -0,0 +1,25 @@
+
+
+
+/**
+ * The result of a text extraction operation.
+ */
+export interface TextExtractionResult {
+    objectId: string;
+    status: TextExtractionStatus;
+    hasText: boolean;
+    message?: string;
+    tokens?: {
+        count: number;
+        encoding: string;
+        etag: string;
+    };
+    len?: number;
+    error?: string;
+}
+
+export enum TextExtractionStatus {
+    skipped = "skipped",
+    success = "success",
+    error = "error",
+}

package/src/system/generateObjectText.ts

@@ -0,0 +1,109 @@
+
+import { DSLWorkflowExecutionPayload } from "@vertesia/common";
+import { log, proxyActivities } from "@temporalio/workflow";
+import { GetObject } from "../activities/getObjectFromStore.js";
+import * as activities from "../activities/index.js";
+import { NoDocumentFound } from "../errors.js";
+import { TextExtractionResult } from "../index.js";
+
+const {
+    getObjectFromStore,
+    extractDocumentText
+} = proxyActivities<typeof activities>({
+    startToCloseTimeout: "5 minute",
+    retry: {
+        initialInterval: '5s',
+        backoffCoefficient: 2,
+        maximumAttempts: 5,
+        maximumInterval: 100 * 30 * 1000, //ms
+        nonRetryableErrorTypes: [],
+    },
+});
+
+const {
+    transcribeMedia,
+    convertPdfToStructuredText
+} = proxyActivities<typeof activities>({
+    startToCloseTimeout: "30 minute",
+    retry: {
+        initialInterval: '30s',
+        backoffCoefficient: 2,
+        maximumAttempts: 5,
+        maximumInterval: 100 * 30 * 1000, //ms
+        nonRetryableErrorTypes: [],
+    },
+});
+
+
+export async function generateObjectText(payload: DSLWorkflowExecutionPayload): Promise<TextExtractionResult> {
+
+    const { objectIds } = payload;
+    const objectId = objectIds[0];
+
+    const object = await getObjectFromStore({
+        ...payload,
+        activity: {
+            name: "getObject",
+        } satisfies GetObject,
+        params: {},
+        workflow_name: "Generate Text",
+    });
+
+    if (!object.content?.source) {
+        throw new NoDocumentFound(`No source or mimetype found for object ${objectId}`, objectIds);
+    }
+    const mimetype = object.content.type;
+    if (!mimetype) {
+        throw new NoDocumentFound(`No mimetype found for object ${objectId}`, objectIds);
+    }
+
+    const converter = ConverterActivity.find(({ type }) => type.test(mimetype));
+    if (!converter) {
+        throw new NoDocumentFound(`No converter found for mimetype ${mimetype}`, objectIds);
+    }
+    log.info(`Converting file type ${mimetype} to text with ${converter.name}`);
+
+    const res = await converter.activity(payload)({
+        ...payload,
+        activity: {
+            name: converter.name,
+        },
+        params: converter.params,
+        workflow_name: "Generate Text",
+    });
+
+    log.info("Generated text for object", {res, objectId});
+    return res;
+
+}
+
+
+const ConverterActivity = [
+    {
+        type: /application\/pdf/,
+        activity: (payload: DSLWorkflowExecutionPayload) => {
+            const useTextractForPDF = payload.vars?.useTextractForPdf?? false;
+            return useTextractForPDF ? convertPdfToStructuredText : extractDocumentText;
+        },
+        name: "ConvertPdfToStructuredText",
+        params: {},
+    },
+    {
+        type: /audio\/.+/,
+        activity: () => transcribeMedia,
+        name: "TranscribeMedia",
+        params: {},
+    },
+    {
+        type: /video\/.+/,
+        activity: () => transcribeMedia,
+        name: "TranscribeMedia",
+        params: {},
+    },
+    {
+        type: /.+/,
+        activity: () => extractDocumentText,
+        name: "extractText",
+        params: {},
+    }
+]

package/src/system/notifyWebhookWorkflow.ts

@@ -0,0 +1,64 @@
+
+import { ContentEventName, DSLWorkflowExecutionPayload } from "@vertesia/common";
+import { log, proxyActivities } from "@temporalio/workflow";
+import * as activities from "../activities/index.js";
+
+const {
+    notifyWebhook
+} = proxyActivities<typeof activities>({
+    startToCloseTimeout: "5 minute",
+    retry: {
+        initialInterval: '5s',
+        backoffCoefficient: 2,
+        maximumAttempts: 5,
+        maximumInterval: 100 * 30 * 1000, //ms
+        nonRetryableErrorTypes: [],
+    },
+});
+
+
+interface NotifyWebhookWorkflowParams extends DSLWorkflowExecutionPayload {
+}
+
+export async function notifyWebhookWorkflow(payload: NotifyWebhookWorkflowParams): Promise<any> {
+
+    const { objectIds, vars } = payload;
+    const notifications = [];
+    const endpoints = vars?.webhooks || [];
+    const eventName = vars.event || ContentEventName.workflow_finished;
+
+    if (!endpoints.length) {
+        log.info(`No webhooks to notify`);
+        return { notifications: [], message: "No webhooks to notify" };
+    }
+
+    for (const ep of endpoints) {
+        const n = notifyWebhook({
+            ...payload,
+            activity: {
+                name: "notifyWebhook",
+            } ,
+            params: {
+                target_url: ep,
+                method: 'POST',
+                payload: {
+                    object_ids: objectIds,
+                    event: eventName,
+                    data: vars.webhook_data ?? undefined,
+                    vars
+                }
+            },
+            workflow_name: "Notify Webhook",
+        } ).then(res => {
+            log.info(`Webhook notified at ${ep} with response code: ${res.status}`, { res });
+            return res;
+        });
+        notifications.push(n);
+    }
+
+    const res = await Promise.all(notifications);
+    log.info(`Webhooks notified`);
+
+    return { notifications: res, message: "Webhooks notified" };
+
+}

package/src/system/recalculateEmbeddingsWorkflow.ts

@@ -0,0 +1,46 @@
+import { proxyActivities } from "@temporalio/workflow";
+
+import { DSLActivitySpec, DSLWorkflowExecutionPayload, SupportedEmbeddingTypes } from "@vertesia/common";
+import { GenerateEmbeddings } from "../activities/generateEmbeddings.js";
+import * as activities from "../activities/index.js";
+import { NoDocumentFound } from "../errors.js";
+
+const {
+    generateEmbeddings,
+} = proxyActivities<typeof activities>({
+    startToCloseTimeout: "5 minute",
+    retry: {
+        initialInterval: '10s',
+        backoffCoefficient: 2,
+        maximumAttempts: 10,
+        maximumInterval: 100 * 30 * 1000, //ms
+        nonRetryableErrorTypes: [NoDocumentFound.name],
+    },
+});
+
+export async function recalculateEmbeddingsWorkflow(payload: DSLWorkflowExecutionPayload) {
+
+    const embeddings = [];
+
+    for (const type of Object.values(SupportedEmbeddingTypes)) {
+        const activityConfig: DSLActivitySpec = {
+            name: 'generateEmbeddings',
+            params: {
+                force: true,
+                type
+            },
+        } satisfies GenerateEmbeddings;
+
+        embeddings.push(generateEmbeddings({
+            ...payload,
+            params: {},
+            workflow_name: 'recalculateEmbeddingsWorkflow',
+            activity: activityConfig,
+        }));
+    }
+
+    const res = await Promise.all(embeddings);
+
+    return res;
+
+}

package/src/utils/auth.ts

@@ -0,0 +1,10 @@
+import { AuthTokenPayload, ProjectRef } from '@vertesia/common';
+import jwt from 'jsonwebtoken';
+
+export function decodeAuthToken(token: string): AuthTokenPayload {
+    return jwt.decode(token, { json: true }) as AuthTokenPayload;
+}
+
+export function getProjectFromToken(token: string): ProjectRef | undefined {
+    return decodeAuthToken(token)?.project;
+}