signalwire-agents 0.1.0

package/dist/ContextBuilder.js

@@ -0,0 +1,751 @@
+/**
+ * ContextBuilder - Contexts and Steps workflow system.
+ *
+ * Contexts contain ordered Steps, each with prompt text/POM sections,
+ * completion criteria, function restrictions, and navigation rules.
+ */
+// ── GatherQuestion ──────────────────────────────────────────────────
+/** Represents a single question within a gather operation. */
+export class GatherQuestion {
+    /** Unique key used to store the answer. */
+    key;
+    /** The question text presented to the user. */
+    question;
+    /** Expected answer type (e.g., "string", "number"). */
+    type;
+    /** Whether the answer requires user confirmation. */
+    confirm;
+    /** Optional additional prompt context for this question. */
+    prompt;
+    /** Optional list of SWAIG function names available during this question. */
+    functions;
+    /**
+     * Creates a new GatherQuestion.
+     * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
+     */
+    constructor(opts) {
+        this.key = opts.key;
+        this.question = opts.question;
+        this.type = opts.type ?? 'string';
+        this.confirm = opts.confirm ?? false;
+        this.prompt = opts.prompt;
+        this.functions = opts.functions;
+    }
+    /**
+     * Serializes this question to a plain object for SWML output.
+     * @returns A dictionary representation of this question.
+     */
+    toDict() {
+        const d = { key: this.key, question: this.question };
+        if (this.type !== 'string')
+            d['type'] = this.type;
+        if (this.confirm)
+            d['confirm'] = true;
+        if (this.prompt)
+            d['prompt'] = this.prompt;
+        if (this.functions)
+            d['functions'] = this.functions;
+        return d;
+    }
+}
+// ── GatherInfo ──────────────────────────────────────────────────────
+/** Collects structured information from the user through a series of questions. */
+export class GatherInfo {
+    questions = [];
+    outputKey;
+    completionAction;
+    prompt;
+    /**
+     * Creates a new GatherInfo.
+     * @param opts - Optional output key, completion action, and prompt configuration.
+     */
+    constructor(opts) {
+        this.outputKey = opts?.outputKey;
+        this.completionAction = opts?.completionAction;
+        this.prompt = opts?.prompt;
+    }
+    /**
+     * Adds a question to this gather operation.
+     * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
+     * @returns This GatherInfo for chaining.
+     */
+    addQuestion(opts) {
+        this.questions.push(new GatherQuestion(opts));
+        return this;
+    }
+    /**
+     * Returns all questions in this gather operation.
+     * @returns The array of GatherQuestion instances.
+     */
+    getQuestions() {
+        return this.questions;
+    }
+    /**
+     * Serializes this gather operation to a plain object for SWML output.
+     * @returns A dictionary representation of the gather info and its questions.
+     */
+    toDict() {
+        if (!this.questions.length)
+            throw new Error('gather_info must have at least one question');
+        const d = { questions: this.questions.map((q) => q.toDict()) };
+        if (this.prompt)
+            d['prompt'] = this.prompt;
+        if (this.outputKey)
+            d['output_key'] = this.outputKey;
+        if (this.completionAction)
+            d['completion_action'] = this.completionAction;
+        return d;
+    }
+}
+/** A single step within a context, with prompt content, criteria, function restrictions, and navigation rules. */
+export class Step {
+    /** The unique name identifying this step within its context. */
+    name;
+    text = null;
+    stepCriteria = null;
+    functions = null;
+    validSteps = null;
+    validContexts = null;
+    sections = [];
+    gatherInfo = null;
+    _end = false;
+    skipUserTurn = false;
+    _skipToNextStep = false;
+    resetSystemPrompt = null;
+    resetUserPrompt = null;
+    resetConsolidate = false;
+    resetFullReset = false;
+    /**
+     * Creates a new Step.
+     * @param name - The unique step name.
+     */
+    constructor(name) {
+        this.name = name;
+    }
+    /**
+     * Sets raw text content for this step, mutually exclusive with POM sections.
+     * @param text - The raw prompt text.
+     * @returns This step for chaining.
+     */
+    setText(text) {
+        if (this.sections.length)
+            throw new Error('Cannot use setText() when POM sections have been added.');
+        this.text = text;
+        return this;
+    }
+    /**
+     * Adds a POM section with a body, mutually exclusive with raw text.
+     * @param title - The section heading.
+     * @param body - The section body text.
+     * @returns This step for chaining.
+     */
+    addSection(title, body) {
+        if (this.text !== null)
+            throw new Error('Cannot add POM sections when setText() has been used.');
+        this.sections.push({ title, body });
+        return this;
+    }
+    /**
+     * Adds a POM section with bullet points, mutually exclusive with raw text.
+     * @param title - The section heading.
+     * @param bullets - The list of bullet point strings.
+     * @returns This step for chaining.
+     */
+    addBullets(title, bullets) {
+        if (this.text !== null)
+            throw new Error('Cannot add POM sections when setText() has been used.');
+        this.sections.push({ title, bullets });
+        return this;
+    }
+    /**
+     * Sets the criteria that must be met before this step is considered complete.
+     * @param criteria - A description of the completion criteria.
+     * @returns This step for chaining.
+     */
+    setStepCriteria(criteria) {
+        this.stepCriteria = criteria;
+        return this;
+    }
+    /**
+     * Restricts which SWAIG functions are available during this step.
+     * @param functions - A function name, list of names, or "*" for all.
+     * @returns This step for chaining.
+     */
+    setFunctions(functions) {
+        this.functions = functions;
+        return this;
+    }
+    /**
+     * Sets which steps the AI may navigate to from this step.
+     * @param steps - List of allowed step names.
+     * @returns This step for chaining.
+     */
+    setValidSteps(steps) {
+        this.validSteps = steps;
+        return this;
+    }
+    /**
+     * Sets which contexts the AI may navigate to from this step.
+     * @param contexts - List of allowed context names.
+     * @returns This step for chaining.
+     */
+    setValidContexts(contexts) {
+        this.validContexts = contexts;
+        return this;
+    }
+    /**
+     * Marks this step as an end step, terminating the conversation when reached.
+     * @param end - Whether this is an end step.
+     * @returns This step for chaining.
+     */
+    setEnd(end) {
+        this._end = end;
+        return this;
+    }
+    /**
+     * Sets whether to skip waiting for user input when entering this step.
+     * @param skip - Whether to skip the user turn.
+     * @returns This step for chaining.
+     */
+    setSkipUserTurn(skip) {
+        this.skipUserTurn = skip;
+        return this;
+    }
+    /**
+     * Sets whether to automatically advance to the next step after this one completes.
+     * @param skip - Whether to skip to the next step.
+     * @returns This step for chaining.
+     */
+    setSkipToNextStep(skip) {
+        this._skipToNextStep = skip;
+        return this;
+    }
+    /**
+     * Initializes a gather info operation on this step for collecting structured data.
+     * @param opts - Optional output key, completion action, and prompt configuration.
+     * @returns This step for chaining.
+     */
+    setGatherInfo(opts) {
+        this.gatherInfo = new GatherInfo(opts);
+        return this;
+    }
+    /**
+     * Adds a question to this step's gather info operation.
+     * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
+     * @returns This step for chaining.
+     */
+    addGatherQuestion(opts) {
+        if (!this.gatherInfo)
+            throw new Error('Must call setGatherInfo() before addGatherQuestion()');
+        this.gatherInfo.addQuestion(opts);
+        return this;
+    }
+    /**
+     * Removes all POM sections and raw text from this step.
+     * @returns This step for chaining.
+     */
+    clearSections() {
+        this.sections = [];
+        this.text = null;
+        return this;
+    }
+    /**
+     * Sets the system prompt to use when resetting context at this step.
+     * @param systemPrompt - The replacement system prompt text.
+     * @returns This step for chaining.
+     */
+    setResetSystemPrompt(systemPrompt) {
+        this.resetSystemPrompt = systemPrompt;
+        return this;
+    }
+    /**
+     * Sets the user prompt to use when resetting context at this step.
+     * @param userPrompt - The replacement user prompt text.
+     * @returns This step for chaining.
+     */
+    setResetUserPrompt(userPrompt) {
+        this.resetUserPrompt = userPrompt;
+        return this;
+    }
+    /**
+     * Sets whether to consolidate conversation history when resetting at this step.
+     * @param consolidate - Whether to consolidate.
+     * @returns This step for chaining.
+     */
+    setResetConsolidate(consolidate) {
+        this.resetConsolidate = consolidate;
+        return this;
+    }
+    /**
+     * Sets whether to perform a full conversation reset at this step.
+     * @param fullReset - Whether to fully reset.
+     * @returns This step for chaining.
+     */
+    setResetFullReset(fullReset) {
+        this.resetFullReset = fullReset;
+        return this;
+    }
+    renderText() {
+        if (this.text !== null)
+            return this.text;
+        if (!this.sections.length)
+            throw new Error(`Step '${this.name}' has no text or POM sections defined`);
+        const parts = [];
+        for (const section of this.sections) {
+            parts.push(`## ${section.title}`);
+            if (section.bullets) {
+                for (const b of section.bullets)
+                    parts.push(`- ${b}`);
+            }
+            else if (section.body) {
+                parts.push(section.body);
+            }
+            parts.push('');
+        }
+        return parts.join('\n').trim();
+    }
+    /**
+     * Serializes this step to a plain object for SWML output.
+     * @returns A dictionary representation of this step.
+     */
+    toDict() {
+        const d = { name: this.name, text: this.renderText() };
+        if (this.stepCriteria)
+            d['step_criteria'] = this.stepCriteria;
+        if (this.functions !== null)
+            d['functions'] = this.functions;
+        if (this.validSteps !== null)
+            d['valid_steps'] = this.validSteps;
+        if (this.validContexts !== null)
+            d['valid_contexts'] = this.validContexts;
+        if (this._end)
+            d['end'] = true;
+        if (this.skipUserTurn)
+            d['skip_user_turn'] = true;
+        if (this._skipToNextStep)
+            d['skip_to_next_step'] = true;
+        const reset = {};
+        if (this.resetSystemPrompt !== null)
+            reset['system_prompt'] = this.resetSystemPrompt;
+        if (this.resetUserPrompt !== null)
+            reset['user_prompt'] = this.resetUserPrompt;
+        if (this.resetConsolidate)
+            reset['consolidate'] = true;
+        if (this.resetFullReset)
+            reset['full_reset'] = true;
+        if (Object.keys(reset).length)
+            d['reset'] = reset;
+        if (this.gatherInfo)
+            d['gather_info'] = this.gatherInfo.toDict();
+        return d;
+    }
+}
+// ── Context ─────────────────────────────────────────────────────────
+/** A named context containing ordered steps, prompt configuration, and navigation rules. */
+export class Context {
+    /** The unique name identifying this context. */
+    name;
+    steps = new Map();
+    stepOrder = [];
+    _validContexts = null;
+    _validSteps = null;
+    _postPrompt = null;
+    _systemPrompt = null;
+    systemPromptSections = [];
+    _consolidate = false;
+    _fullReset = false;
+    _userPrompt = null;
+    _isolated = false;
+    promptText = null;
+    promptSections = [];
+    _enterFillers = null;
+    _exitFillers = null;
+    /**
+     * Creates a new Context.
+     * @param name - The unique context name.
+     */
+    constructor(name) {
+        this.name = name;
+    }
+    /**
+     * Adds a new step to this context.
+     * @param name - The unique step name within this context.
+     * @param opts - Optional shorthand for task text, bullets, criteria, functions, and valid steps.
+     * @returns The newly created Step for further configuration.
+     */
+    addStep(name, opts) {
+        if (this.steps.has(name))
+            throw new Error(`Step '${name}' already exists in context '${this.name}'`);
+        const step = new Step(name);
+        this.steps.set(name, step);
+        this.stepOrder.push(name);
+        if (opts?.task)
+            step.addSection('Task', opts.task);
+        if (opts?.bullets)
+            step.addBullets('Process', opts.bullets);
+        if (opts?.criteria)
+            step.setStepCriteria(opts.criteria);
+        if (opts?.functions)
+            step.setFunctions(opts.functions);
+        if (opts?.validSteps)
+            step.setValidSteps(opts.validSteps);
+        return step;
+    }
+    /**
+     * Returns a step by name.
+     * @param name - The step name to retrieve.
+     * @returns The matching Step, or undefined if not found.
+     */
+    getStep(name) {
+        return this.steps.get(name);
+    }
+    /**
+     * Removes a step from this context by name.
+     * @param name - The step name to remove.
+     * @returns This context for chaining.
+     */
+    removeStep(name) {
+        this.steps.delete(name);
+        this.stepOrder = this.stepOrder.filter((s) => s !== name);
+        return this;
+    }
+    /**
+     * Moves a step to a new position in the step order.
+     * @param name - The step name to move.
+     * @param position - The zero-based index to insert at.
+     * @returns This context for chaining.
+     */
+    moveStep(name, position) {
+        if (!this.steps.has(name))
+            throw new Error(`Step '${name}' not found in context '${this.name}'`);
+        this.stepOrder = this.stepOrder.filter((s) => s !== name);
+        this.stepOrder.splice(position, 0, name);
+        return this;
+    }
+    /**
+     * Sets which contexts the AI may navigate to from this context.
+     * @param contexts - List of allowed context names.
+     * @returns This context for chaining.
+     */
+    setValidContexts(contexts) {
+        this._validContexts = contexts;
+        return this;
+    }
+    /**
+     * Sets which steps the AI may navigate to from this context.
+     * @param steps - List of allowed step names.
+     * @returns This context for chaining.
+     */
+    setValidSteps(steps) {
+        this._validSteps = steps;
+        return this;
+    }
+    /**
+     * Sets the post-prompt text for this context.
+     * @param postPrompt - The post-prompt string.
+     * @returns This context for chaining.
+     */
+    setPostPrompt(postPrompt) {
+        this._postPrompt = postPrompt;
+        return this;
+    }
+    /**
+     * Sets raw system prompt text, mutually exclusive with system POM sections.
+     * @param systemPrompt - The system prompt string.
+     * @returns This context for chaining.
+     */
+    setSystemPrompt(systemPrompt) {
+        if (this.systemPromptSections.length)
+            throw new Error('Cannot use setSystemPrompt() when POM sections have been added.');
+        this._systemPrompt = systemPrompt;
+        return this;
+    }
+    /**
+     * Sets whether to consolidate conversation history when entering this context.
+     * @param consolidate - Whether to consolidate.
+     * @returns This context for chaining.
+     */
+    setConsolidate(consolidate) {
+        this._consolidate = consolidate;
+        return this;
+    }
+    /**
+     * Sets whether to fully reset conversation history when entering this context.
+     * @param fullReset - Whether to fully reset.
+     * @returns This context for chaining.
+     */
+    setFullReset(fullReset) {
+        this._fullReset = fullReset;
+        return this;
+    }
+    /**
+     * Sets the user prompt text for this context.
+     * @param userPrompt - The user prompt string.
+     * @returns This context for chaining.
+     */
+    setUserPrompt(userPrompt) {
+        this._userPrompt = userPrompt;
+        return this;
+    }
+    /**
+     * Sets whether this context is isolated from other contexts' conversation history.
+     * @param isolated - Whether to isolate.
+     * @returns This context for chaining.
+     */
+    setIsolated(isolated) {
+        this._isolated = isolated;
+        return this;
+    }
+    /**
+     * Adds a POM section to the system prompt, mutually exclusive with raw system prompt text.
+     * @param title - The section heading.
+     * @param body - The section body text.
+     * @returns This context for chaining.
+     */
+    addSystemSection(title, body) {
+        if (this._systemPrompt !== null)
+            throw new Error('Cannot add POM sections when setSystemPrompt() has been used.');
+        this.systemPromptSections.push({ title, body });
+        return this;
+    }
+    /**
+     * Adds a POM section with bullets to the system prompt, mutually exclusive with raw system prompt text.
+     * @param title - The section heading.
+     * @param bullets - The list of bullet point strings.
+     * @returns This context for chaining.
+     */
+    addSystemBullets(title, bullets) {
+        if (this._systemPrompt !== null)
+            throw new Error('Cannot add POM sections when setSystemPrompt() has been used.');
+        this.systemPromptSections.push({ title, bullets });
+        return this;
+    }
+    /**
+     * Sets raw prompt text for this context, mutually exclusive with POM prompt sections.
+     * @param prompt - The prompt string.
+     * @returns This context for chaining.
+     */
+    setPrompt(prompt) {
+        if (this.promptSections.length)
+            throw new Error('Cannot use setPrompt() when POM sections have been added.');
+        this.promptText = prompt;
+        return this;
+    }
+    /**
+     * Adds a POM section with a body to the context prompt, mutually exclusive with raw prompt text.
+     * @param title - The section heading.
+     * @param body - The section body text.
+     * @returns This context for chaining.
+     */
+    addSection(title, body) {
+        if (this.promptText !== null)
+            throw new Error('Cannot add POM sections when setPrompt() has been used.');
+        this.promptSections.push({ title, body });
+        return this;
+    }
+    /**
+     * Adds a POM section with bullets to the context prompt, mutually exclusive with raw prompt text.
+     * @param title - The section heading.
+     * @param bullets - The list of bullet point strings.
+     * @returns This context for chaining.
+     */
+    addBullets(title, bullets) {
+        if (this.promptText !== null)
+            throw new Error('Cannot add POM sections when setPrompt() has been used.');
+        this.promptSections.push({ title, bullets });
+        return this;
+    }
+    /**
+     * Sets filler phrases spoken when entering this context, keyed by language code.
+     * @param fillers - Map of language codes to arrays of filler phrases.
+     * @returns This context for chaining.
+     */
+    setEnterFillers(fillers) {
+        this._enterFillers = fillers;
+        return this;
+    }
+    /**
+     * Sets filler phrases spoken when exiting this context, keyed by language code.
+     * @param fillers - Map of language codes to arrays of filler phrases.
+     * @returns This context for chaining.
+     */
+    setExitFillers(fillers) {
+        this._exitFillers = fillers;
+        return this;
+    }
+    /**
+     * Adds enter filler phrases for a specific language.
+     * @param languageCode - The language code (e.g., "en-US").
+     * @param fillers - Array of filler phrases.
+     * @returns This context for chaining.
+     */
+    addEnterFiller(languageCode, fillers) {
+        if (!this._enterFillers)
+            this._enterFillers = {};
+        this._enterFillers[languageCode] = fillers;
+        return this;
+    }
+    /**
+     * Adds exit filler phrases for a specific language.
+     * @param languageCode - The language code (e.g., "en-US").
+     * @param fillers - Array of filler phrases.
+     * @returns This context for chaining.
+     */
+    addExitFiller(languageCode, fillers) {
+        if (!this._exitFillers)
+            this._exitFillers = {};
+        this._exitFillers[languageCode] = fillers;
+        return this;
+    }
+    /** @internal */
+    getSteps() {
+        return this.steps;
+    }
+    /** @internal */
+    getValidContexts() {
+        return this._validContexts;
+    }
+    renderPrompt() {
+        if (this.promptText !== null)
+            return this.promptText;
+        if (!this.promptSections.length)
+            return null;
+        return this.renderSections(this.promptSections);
+    }
+    renderSystemPrompt() {
+        if (this._systemPrompt !== null)
+            return this._systemPrompt;
+        if (!this.systemPromptSections.length)
+            return null;
+        return this.renderSections(this.systemPromptSections);
+    }
+    renderSections(sections) {
+        const parts = [];
+        for (const s of sections) {
+            parts.push(`## ${s.title}`);
+            if (s.bullets)
+                for (const b of s.bullets)
+                    parts.push(`- ${b}`);
+            else if (s.body)
+                parts.push(s.body);
+            parts.push('');
+        }
+        return parts.join('\n').trim();
+    }
+    /**
+     * Serializes this context and all its steps to a plain object for SWML output.
+     * @returns A dictionary representation of this context.
+     */
+    toDict() {
+        if (!this.steps.size)
+            throw new Error(`Context '${this.name}' has no steps defined`);
+        const d = {
+            steps: this.stepOrder.map((name) => this.steps.get(name).toDict()),
+        };
+        if (this._validContexts !== null)
+            d['valid_contexts'] = this._validContexts;
+        if (this._validSteps !== null)
+            d['valid_steps'] = this._validSteps;
+        if (this._postPrompt !== null)
+            d['post_prompt'] = this._postPrompt;
+        const sp = this.renderSystemPrompt();
+        if (sp !== null)
+            d['system_prompt'] = sp;
+        if (this._consolidate)
+            d['consolidate'] = true;
+        if (this._fullReset)
+            d['full_reset'] = true;
+        if (this._userPrompt !== null)
+            d['user_prompt'] = this._userPrompt;
+        if (this._isolated)
+            d['isolated'] = true;
+        if (this.promptSections.length) {
+            d['pom'] = this.promptSections;
+        }
+        else if (this.promptText !== null) {
+            d['prompt'] = this.promptText;
+        }
+        if (this._enterFillers)
+            d['enter_fillers'] = this._enterFillers;
+        if (this._exitFillers)
+            d['exit_fillers'] = this._exitFillers;
+        return d;
+    }
+}
+// ── ContextBuilder ──────────────────────────────────────────────────
+/** Builds and validates a collection of named contexts for multi-step AI workflows. */
+export class ContextBuilder {
+    contexts = new Map();
+    contextOrder = [];
+    /**
+     * Adds a new named context to the builder.
+     * @param name - The unique context name.
+     * @returns The newly created Context for further configuration.
+     */
+    addContext(name) {
+        if (this.contexts.has(name))
+            throw new Error(`Context '${name}' already exists`);
+        const ctx = new Context(name);
+        this.contexts.set(name, ctx);
+        this.contextOrder.push(name);
+        return ctx;
+    }
+    /**
+     * Returns a context by name.
+     * @param name - The context name to retrieve.
+     * @returns The matching Context, or undefined if not found.
+     */
+    getContext(name) {
+        return this.contexts.get(name);
+    }
+    /**
+     * Validates that all contexts have steps, naming constraints are met, and cross-context references are valid.
+     * @throws Error if validation fails.
+     */
+    validate() {
+        if (!this.contexts.size)
+            throw new Error('At least one context must be defined');
+        if (this.contexts.size === 1) {
+            const name = [...this.contexts.keys()][0];
+            if (name !== 'default')
+                throw new Error("When using a single context, it must be named 'default'");
+        }
+        for (const [name, ctx] of this.contexts) {
+            if (!ctx.getSteps().size)
+                throw new Error(`Context '${name}' must have at least one step`);
+        }
+        // Validate context references
+        for (const [, ctx] of this.contexts) {
+            const vc = ctx.getValidContexts();
+            if (vc) {
+                for (const ref of vc) {
+                    if (!this.contexts.has(ref)) {
+                        throw new Error(`Context '${ctx.name}' references unknown context '${ref}'`);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Validates and serializes all contexts to a plain object for SWML output.
+     * @returns A dictionary mapping context names to their serialized representations.
+     */
+    toDict() {
+        this.validate();
+        const result = {};
+        for (const name of this.contextOrder) {
+            result[name] = this.contexts.get(name).toDict();
+        }
+        return result;
+    }
+}
+// ── Helper ──────────────────────────────────────────────────────────
+/**
+ * Creates a standalone Context instance without a ContextBuilder.
+ * @param name - The context name (defaults to "default").
+ * @returns A new Context instance.
+ */
+export function createSimpleContext(name = 'default') {
+    return new Context(name);
+}
+//# sourceMappingURL=ContextBuilder.js.map