@workglow/ai 0.2.32 → 0.2.34

package/dist/task/AiChatWithKbTask.d.ts

@@ -0,0 +1,710 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IExecuteContext, StreamEvent } from "@workglow/task-graph";
+import type { DataPortSchema, FromSchema } from "@workglow/util/schema";
+import type { AiJobInput } from "../job/AiJob";
+import { StreamingAiTask } from "./base/StreamingAiTask";
+import type { ChatMessage } from "./ChatMessage";
+export interface ChatChunkReference {
+    readonly kbId: string;
+    readonly kbLabel: string;
+    readonly title: string;
+    readonly url: string | undefined;
+    readonly snippet: string;
+    readonly score: number;
+    /**
+     * 1-based position of this chunk in the prompt the model sees, so the
+     * model's reply citing `[N]` maps back to this entry. `0` for
+     * author-supplied `noMatchReferences` (which don't correspond to any
+     * prompt chunk).
+     */
+    readonly index: number;
+}
+export declare const AiChatWithKbInputSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly model: {
+            readonly oneOf: readonly [{
+                readonly title: "Model";
+                readonly description: `The model ${string}`;
+            } & {
+                readonly format: import(".").TypeModelSemantic;
+                readonly type: "string";
+            }, {
+                readonly type: "object";
+                readonly properties: {
+                    readonly model_id: {
+                        readonly type: "string";
+                    };
+                    readonly tasks: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly "x-ui-editor": "multiselect";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                        readonly "x-ui-editor": "textarea";
+                    };
+                    readonly provider: {
+                        readonly type: "string";
+                    };
+                    readonly provider_config: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly credential_key: {
+                                readonly type: "string";
+                                readonly format: "credential";
+                                readonly "x-ui-hidden": true;
+                            };
+                            readonly native_dimensions: {
+                                readonly type: "integer";
+                                readonly description: "Native output vector dimensions for embedding models";
+                            };
+                            readonly mrl: {
+                                readonly type: "boolean";
+                                readonly description: "Whether the model supports Matryoshka Representation Learning";
+                            };
+                        };
+                        readonly additionalProperties: true;
+                        readonly default: {};
+                    };
+                    readonly metadata: {
+                        readonly type: "object";
+                        readonly default: {};
+                        readonly "x-ui-hidden": true;
+                    };
+                };
+                readonly required: readonly ["provider", "provider_config"];
+                readonly format: "model";
+                readonly additionalProperties: true;
+            } & {
+                readonly format: import(".").TypeModelSemantic;
+            }];
+        } & {
+            readonly format: import(".").TypeModelSemantic;
+        };
+        readonly prompt: {
+            readonly oneOf: readonly [{
+                readonly type: "string";
+                readonly title: "Prompt";
+                readonly description: "The initial user message";
+            }, {
+                readonly type: "array";
+                readonly title: "Prompt";
+                readonly description: "The initial user message as structured content blocks";
+                readonly items: {
+                    readonly oneOf: readonly [{
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly type: {
+                                readonly type: "string";
+                                readonly enum: readonly ["text"];
+                            };
+                            readonly text: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["type", "text"];
+                        readonly additionalProperties: false;
+                    }, {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly type: {
+                                readonly type: "string";
+                                readonly enum: readonly ["image"];
+                            };
+                            readonly mimeType: {
+                                readonly type: "string";
+                            };
+                            readonly data: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly required: readonly ["type", "mimeType", "data"];
+                        readonly additionalProperties: false;
+                    }, {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly type: {
+                                readonly type: "string";
+                                readonly enum: readonly ["tool_use"];
+                            };
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                            readonly name: {
+                                readonly type: "string";
+                            };
+                            readonly input: {
+                                readonly type: "object";
+                                readonly additionalProperties: true;
+                            };
+                        };
+                        readonly required: readonly ["type", "id", "name", "input"];
+                        readonly additionalProperties: false;
+                    }, {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly type: {
+                                readonly type: "string";
+                                readonly enum: readonly ["tool_result"];
+                            };
+                            readonly tool_use_id: {
+                                readonly type: "string";
+                            };
+                            readonly content: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly oneOf: readonly [{
+                                        readonly type: "object";
+                                        readonly properties: {
+                                            readonly type: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["text"];
+                                            };
+                                            readonly text: {
+                                                readonly type: "string";
+                                            };
+                                        };
+                                        readonly required: readonly ["type", "text"];
+                                        readonly additionalProperties: false;
+                                    }, {
+                                        readonly type: "object";
+                                        readonly properties: {
+                                            readonly type: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["image"];
+                                            };
+                                            readonly mimeType: {
+                                                readonly type: "string";
+                                            };
+                                            readonly data: {
+                                                readonly type: "string";
+                                            };
+                                        };
+                                        readonly required: readonly ["type", "mimeType", "data"];
+                                        readonly additionalProperties: false;
+                                    }, {
+                                        readonly type: "object";
+                                        readonly properties: {
+                                            readonly type: {
+                                                readonly type: "string";
+                                                readonly enum: readonly ["tool_use"];
+                                            };
+                                            readonly id: {
+                                                readonly type: "string";
+                                            };
+                                            readonly name: {
+                                                readonly type: "string";
+                                            };
+                                            readonly input: {
+                                                readonly type: "object";
+                                                readonly additionalProperties: true;
+                                            };
+                                        };
+                                        readonly required: readonly ["type", "id", "name", "input"];
+                                        readonly additionalProperties: false;
+                                    }];
+                                };
+                            };
+                            readonly is_error: {
+                                readonly type: "boolean";
+                            };
+                        };
+                        readonly required: readonly ["type", "tool_use_id", "content"];
+                        readonly additionalProperties: false;
+                    }];
+                    readonly title: "ContentBlock";
+                    readonly description: "A single content block within a chat message";
+                };
+            }];
+            readonly title: "Prompt";
+            readonly description: "The first user message to start the conversation";
+        };
+        readonly messages: {
+            readonly type: "array";
+            readonly title: "Messages";
+            readonly description: "Conversation history (managed internally by the chat loop; not a user-facing input)";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly role: {
+                        readonly type: "string";
+                        readonly enum: readonly ["user", "assistant", "tool", "system"];
+                    };
+                    readonly content: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly oneOf: readonly [{
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["text"];
+                                    };
+                                    readonly text: {
+                                        readonly type: "string";
+                                    };
+                                };
+                                readonly required: readonly ["type", "text"];
+                                readonly additionalProperties: false;
+                            }, {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["image"];
+                                    };
+                                    readonly mimeType: {
+                                        readonly type: "string";
+                                    };
+                                    readonly data: {
+                                        readonly type: "string";
+                                    };
+                                };
+                                readonly required: readonly ["type", "mimeType", "data"];
+                                readonly additionalProperties: false;
+                            }, {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["tool_use"];
+                                    };
+                                    readonly id: {
+                                        readonly type: "string";
+                                    };
+                                    readonly name: {
+                                        readonly type: "string";
+                                    };
+                                    readonly input: {
+                                        readonly type: "object";
+                                        readonly additionalProperties: true;
+                                    };
+                                };
+                                readonly required: readonly ["type", "id", "name", "input"];
+                                readonly additionalProperties: false;
+                            }, {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["tool_result"];
+                                    };
+                                    readonly tool_use_id: {
+                                        readonly type: "string";
+                                    };
+                                    readonly content: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly oneOf: readonly [{
+                                                readonly type: "object";
+                                                readonly properties: {
+                                                    readonly type: {
+                                                        readonly type: "string";
+                                                        readonly enum: readonly ["text"];
+                                                    };
+                                                    readonly text: {
+                                                        readonly type: "string";
+                                                    };
+                                                };
+                                                readonly required: readonly ["type", "text"];
+                                                readonly additionalProperties: false;
+                                            }, {
+                                                readonly type: "object";
+                                                readonly properties: {
+                                                    readonly type: {
+                                                        readonly type: "string";
+                                                        readonly enum: readonly ["image"];
+                                                    };
+                                                    readonly mimeType: {
+                                                        readonly type: "string";
+                                                    };
+                                                    readonly data: {
+                                                        readonly type: "string";
+                                                    };
+                                                };
+                                                readonly required: readonly ["type", "mimeType", "data"];
+                                                readonly additionalProperties: false;
+                                            }, {
+                                                readonly type: "object";
+                                                readonly properties: {
+                                                    readonly type: {
+                                                        readonly type: "string";
+                                                        readonly enum: readonly ["tool_use"];
+                                                    };
+                                                    readonly id: {
+                                                        readonly type: "string";
+                                                    };
+                                                    readonly name: {
+                                                        readonly type: "string";
+                                                    };
+                                                    readonly input: {
+                                                        readonly type: "object";
+                                                        readonly additionalProperties: true;
+                                                    };
+                                                };
+                                                readonly required: readonly ["type", "id", "name", "input"];
+                                                readonly additionalProperties: false;
+                                            }];
+                                        };
+                                    };
+                                    readonly is_error: {
+                                        readonly type: "boolean";
+                                    };
+                                };
+                                readonly required: readonly ["type", "tool_use_id", "content"];
+                                readonly additionalProperties: false;
+                            }];
+                            readonly title: "ContentBlock";
+                            readonly description: "A single content block within a chat message";
+                        };
+                    };
+                };
+                readonly required: readonly ["role", "content"];
+                readonly additionalProperties: false;
+                readonly title: "ChatMessage";
+                readonly description: "A single chat message with role and structured content blocks";
+            };
+            readonly "x-ui-hidden": true;
+        };
+        readonly systemPrompt: {
+            readonly type: "string";
+            readonly title: "System Prompt";
+            readonly description: "Optional system instructions for the model";
+        };
+        readonly maxTokens: {
+            readonly type: "number";
+            readonly title: "Max Tokens";
+            readonly description: "Per-turn token limit";
+            readonly minimum: 1;
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly temperature: {
+            readonly type: "number";
+            readonly title: "Temperature";
+            readonly description: "Sampling temperature";
+            readonly minimum: 0;
+            readonly maximum: 2;
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly maxIterations: {
+            readonly type: "number";
+            readonly title: "Max Iterations";
+            readonly description: "Safety cap on conversation turns";
+            readonly minimum: 1;
+            readonly default: 100;
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly knowledgeBaseIds: {
+            readonly type: "array";
+            readonly title: "Knowledge Base IDs";
+            readonly description: "Knowledge bases to retrieve from on each turn";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly topKPerKb: {
+            readonly type: "number";
+            readonly title: "Top K per KB";
+            readonly description: "Top results per KB before threshold filtering";
+            readonly minimum: 1;
+            readonly default: 4;
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly minScore: {
+            readonly type: "number";
+            readonly title: "Min score";
+            readonly description: "Score floor for a chunk to count as a useful match";
+            readonly minimum: 0;
+            readonly maximum: 1;
+            readonly default: 0.3;
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly maxReferences: {
+            readonly type: "number";
+            readonly title: "Max references";
+            readonly description: "Cap on the chunk references emitted per turn";
+            readonly minimum: 1;
+            readonly default: 6;
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly noMatchReply: {
+            readonly type: "string";
+            readonly title: "No-match reply";
+            readonly description: "When set and zero chunks match: emit this verbatim and skip the provider";
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly noMatchReferences: {
+            readonly type: "array";
+            readonly title: "No-match references";
+            readonly description: "When set and zero chunks match: emit these verbatim on the references port";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly kbId: {
+                        readonly type: "string";
+                    };
+                    readonly kbLabel: {
+                        readonly type: "string";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly url: {
+                        readonly type: "string";
+                    };
+                    readonly snippet: {
+                        readonly type: "string";
+                    };
+                    readonly score: {
+                        readonly type: "number";
+                    };
+                    readonly index: {
+                        readonly type: "number";
+                    };
+                };
+                readonly required: readonly ["kbId", "kbLabel", "title", "snippet", "score", "index"];
+            };
+            readonly "x-ui-group": "Configuration";
+        };
+        readonly responseFormat: {
+            readonly type: "string";
+            readonly enum: readonly ["text", "markdown"];
+            readonly default: "text";
+            readonly title: "Response format";
+            readonly description: string;
+            readonly "x-ui-group": "Configuration";
+        };
+    };
+    readonly required: readonly ["model", "prompt", "knowledgeBaseIds"];
+    readonly additionalProperties: false;
+};
+export declare const AiChatWithKbOutputSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly text: {
+            readonly type: "string";
+            readonly title: "Text";
+            readonly description: "Full streamed transcript across all assistant turns";
+            readonly "x-stream": "append";
+        };
+        readonly messages: {
+            readonly type: "array";
+            readonly title: "Messages";
+            readonly description: "Full conversation history";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly role: {
+                        readonly type: "string";
+                        readonly enum: readonly ["user", "assistant", "tool", "system"];
+                    };
+                    readonly content: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly oneOf: readonly [{
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["text"];
+                                    };
+                                    readonly text: {
+                                        readonly type: "string";
+                                    };
+                                };
+                                readonly required: readonly ["type", "text"];
+                                readonly additionalProperties: false;
+                            }, {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["image"];
+                                    };
+                                    readonly mimeType: {
+                                        readonly type: "string";
+                                    };
+                                    readonly data: {
+                                        readonly type: "string";
+                                    };
+                                };
+                                readonly required: readonly ["type", "mimeType", "data"];
+                                readonly additionalProperties: false;
+                            }, {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["tool_use"];
+                                    };
+                                    readonly id: {
+                                        readonly type: "string";
+                                    };
+                                    readonly name: {
+                                        readonly type: "string";
+                                    };
+                                    readonly input: {
+                                        readonly type: "object";
+                                        readonly additionalProperties: true;
+                                    };
+                                };
+                                readonly required: readonly ["type", "id", "name", "input"];
+                                readonly additionalProperties: false;
+                            }, {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["tool_result"];
+                                    };
+                                    readonly tool_use_id: {
+                                        readonly type: "string";
+                                    };
+                                    readonly content: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly oneOf: readonly [{
+                                                readonly type: "object";
+                                                readonly properties: {
+                                                    readonly type: {
+                                                        readonly type: "string";
+                                                        readonly enum: readonly ["text"];
+                                                    };
+                                                    readonly text: {
+                                                        readonly type: "string";
+                                                    };
+                                                };
+                                                readonly required: readonly ["type", "text"];
+                                                readonly additionalProperties: false;
+                                            }, {
+                                                readonly type: "object";
+                                                readonly properties: {
+                                                    readonly type: {
+                                                        readonly type: "string";
+                                                        readonly enum: readonly ["image"];
+                                                    };
+                                                    readonly mimeType: {
+                                                        readonly type: "string";
+                                                    };
+                                                    readonly data: {
+                                                        readonly type: "string";
+                                                    };
+                                                };
+                                                readonly required: readonly ["type", "mimeType", "data"];
+                                                readonly additionalProperties: false;
+                                            }, {
+                                                readonly type: "object";
+                                                readonly properties: {
+                                                    readonly type: {
+                                                        readonly type: "string";
+                                                        readonly enum: readonly ["tool_use"];
+                                                    };
+                                                    readonly id: {
+                                                        readonly type: "string";
+                                                    };
+                                                    readonly name: {
+                                                        readonly type: "string";
+                                                    };
+                                                    readonly input: {
+                                                        readonly type: "object";
+                                                        readonly additionalProperties: true;
+                                                    };
+                                                };
+                                                readonly required: readonly ["type", "id", "name", "input"];
+                                                readonly additionalProperties: false;
+                                            }];
+                                        };
+                                    };
+                                    readonly is_error: {
+                                        readonly type: "boolean";
+                                    };
+                                };
+                                readonly required: readonly ["type", "tool_use_id", "content"];
+                                readonly additionalProperties: false;
+                            }];
+                            readonly title: "ContentBlock";
+                            readonly description: "A single content block within a chat message";
+                        };
+                    };
+                };
+                readonly required: readonly ["role", "content"];
+                readonly additionalProperties: false;
+                readonly title: "ChatMessage";
+                readonly description: "A single chat message with role and structured content blocks";
+            };
+            readonly "x-stream": "object";
+        };
+        readonly iterations: {
+            readonly type: "number";
+            readonly title: "Iterations";
+            readonly description: "Number of completed turns";
+        };
+        readonly references: {
+            readonly type: "array";
+            readonly title: "References";
+            readonly description: "Per-chunk citation references emitted each turn (one entry per surviving chunk; not deduped)";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly kbId: {
+                        readonly type: "string";
+                    };
+                    readonly kbLabel: {
+                        readonly type: "string";
+                    };
+                    readonly title: {
+                        readonly type: "string";
+                    };
+                    readonly url: {
+                        readonly type: "string";
+                    };
+                    readonly snippet: {
+                        readonly type: "string";
+                    };
+                    readonly score: {
+                        readonly type: "number";
+                    };
+                    readonly index: {
+                        readonly type: "number";
+                    };
+                };
+                readonly required: readonly ["kbId", "kbLabel", "title", "snippet", "score", "index"];
+            };
+            readonly "x-stream": "object";
+        };
+    };
+    readonly required: readonly ["text", "messages", "iterations", "references"];
+    readonly additionalProperties: false;
+};
+export type AiChatWithKbTaskInput = Omit<FromSchema<typeof AiChatWithKbInputSchema>, "messages" | "noMatchReferences"> & {
+    readonly messages?: ReadonlyArray<ChatMessage>;
+    readonly noMatchReferences?: ReadonlyArray<ChatChunkReference>;
+};
+export type AiChatWithKbTaskOutput = Omit<FromSchema<typeof AiChatWithKbOutputSchema>, "references"> & {
+    readonly references: readonly ChatChunkReference[];
+};
+export declare class AiChatWithKbTask extends StreamingAiTask<AiChatWithKbTaskInput, AiChatWithKbTaskOutput> {
+    static type: string;
+    protected static readonly streamingPhaseLabel = "Replying";
+    static category: string;
+    static title: string;
+    static description: string;
+    static cacheable: boolean;
+    static configSchema(): DataPortSchema;
+    static inputSchema(): DataPortSchema;
+    static outputSchema(): DataPortSchema;
+    private _sessionId;
+    protected getJobInput(input: AiChatWithKbTaskInput): Promise<AiJobInput<AiChatWithKbTaskInput>>;
+    executeStream(input: AiChatWithKbTaskInput, context: IExecuteContext): AsyncIterable<StreamEvent<AiChatWithKbTaskOutput>>;
+}
+//# sourceMappingURL=AiChatWithKbTask.d.ts.map