@exellix/ai-tasks 7.8.0

package/dist/builders/task-request-builder.d.ts

@@ -0,0 +1,310 @@
+import type { RunTaskRequest, ModelConfig, AIScopingInstruction, ExecutionStep, SynthesisConfig, SynthesisMode, AuditConfig, PolishConfig, TemplateRenderOptions, GatewayTemplateTokens, LlmCallConfig, ExecutionStrategyInvocation, SmartInputRenderOptions, RunTaskSmartInput, XynthesizedMemory } from "../types/index.js";
+/**
+ * Builder for constructing task requests.
+ *
+ * Provides a fluent API for building task requests with proper defaults
+ * and validation. This makes it easier to construct complex requests
+ * and ensures consistency across the SDK.
+ */
+export declare class TaskRequestBuilder {
+    private request;
+    constructor();
+    /**
+     * Set the skill key to execute.
+     *
+     * @param skillKey The skill key (e.g., "skills/professional-answer")
+     * @returns The builder instance for chaining
+     */
+    withSkillKey(skillKey: string): this;
+    /**
+     * Required `@exellix/ai-skills` correlation ids (agent, job type, task type). Must be set before `build()`.
+     */
+    withAiSkillsCorrelation(agentId: string, jobTypeId: string, taskTypeId: string): this;
+    /**
+     * Set the input data.
+     *
+     * @param input The input data (object or string)
+     * @returns The builder instance for chaining
+     */
+    withInput(input: Record<string, any> | string): this;
+    /**
+     * Set AI scoping instructions (optional). When present, internal AI calls scope memory content into input.aiScoped before the main task runs.
+     *
+     * @param instructions Array of { source, instructions, targetToken }
+     * @returns The builder instance for chaining
+     */
+    withAiScoping(instructions: AIScopingInstruction[]): this;
+    /**
+     * Set the execution pipeline (pre → main → post steps).
+     *
+     * @param steps Array of { phase, type, config? }
+     * @returns The builder instance for chaining
+     */
+    withExecutionPipeline(steps: ExecutionStep[]): this;
+    /**
+     * MAIN wrappers (`RunTaskRequest.executionStrategies`): required at runtime; defaults to `[]` in `build()` when unset.
+     */
+    withExecutionStrategies(executionStrategies: ExecutionStrategyInvocation[]): this;
+    /**
+     * Add a synthesized-context PRE step before the main task. A weak model synthesizes context from narrix/memory;
+     * the main task then runs with that as context. Sets includeContextInPrompt to true.
+     * If no pipeline is set yet, defaults to [main: direct] and inserts this pre step.
+     *
+     * @param modelOrConfig Optional model name (e.g. "gpt-5-nano") or full SynthesisConfig
+     * @returns The builder instance for chaining
+     */
+    withSynthesizedContextPreStep(modelOrConfig?: string | SynthesisConfig): this;
+    /**
+     * Set synthesis mode on existing synthesized-context PRE step configs.
+     */
+    withSynthesisMode(synthesisMode: SynthesisMode): this;
+    /**
+     * Add an audit POST step. Quality-gate loop with re-runs and optional synthesis.
+     * Ensures executionPipeline exists with a MAIN "direct" step, then appends the audit step.
+     *
+     * @param config AuditConfig (gateway.must, gateway.should, threshold, maxCycles, etc.)
+     * @returns The builder instance for chaining
+     */
+    withAuditPostStep(config: AuditConfig): this;
+    /**
+     * Add a polish POST step. Refinement pass against a prioritized checklist.
+     * Ensures executionPipeline exists with a MAIN "direct" step, then appends the polish step.
+     *
+     * @param config PolishConfig (checklist, maxPasses, etc.)
+     * @returns The builder instance for chaining
+     */
+    withPolishPostStep(config: PolishConfig): this;
+    /**
+     * Set contextual variables.
+     *
+     * @param variables The variables object
+     * @returns The builder instance for chaining
+     */
+    withVariables(variables: Record<string, any>): this;
+    /**
+     * Set job- or graph-level fields merged into template variables (lowest precedence vs `withVariables` and `input`-derived bindings).
+     */
+    withJobContext(jobContext: Record<string, unknown>): this;
+    /**
+     * Set context data.
+     *
+     * @param context The context (object or string)
+     * @returns The builder instance for chaining
+     */
+    withContext(context: Record<string, any> | string): this;
+    /**
+     * Set knowledge data.
+     *
+     * @param knowledge The knowledge object
+     * @returns The builder instance for chaining
+     */
+    withKnowledge(knowledge: Record<string, any>): this;
+    /**
+     * Set job memory.
+     *
+     * @param jobMemory The job memory
+     * @returns The builder instance for chaining
+     */
+    withJobMemory(jobMemory: any): this;
+    /**
+     * Set task memory.
+     *
+     * @param taskMemory The task memory
+     * @returns The builder instance for chaining
+     */
+    withTaskMemory(taskMemory: any): this;
+    /**
+     * Set execution memory.
+     *
+     * @param executionMemory The execution memory (history of execution context)
+     * @returns The builder instance for chaining
+     */
+    withExecutionMemory(executionMemory: any): this;
+    /**
+     * Set job ID.
+     *
+     * @param jobId The job ID
+     * @returns The builder instance for chaining
+     */
+    withJobId(jobId: string): this;
+    /**
+     * Set agent ID.
+     *
+     * @param agentId The agent ID
+     * @returns The builder instance for chaining
+     */
+    withAgentId(agentId: string): this;
+    /** `@exellix/ai-skills` job type id (required with agentId / taskTypeId for `build()`). */
+    withJobTypeId(jobTypeId: string): this;
+    /** `@exellix/ai-skills` task type id (required with agentId / jobTypeId for `build()`). */
+    withTaskTypeId(taskTypeId: string): this;
+    /**
+     * Set timeout in milliseconds.
+     *
+     * @param timeoutMs The timeout in milliseconds
+     * @returns The builder instance for chaining
+     */
+    withTimeout(timeoutMs: number): this;
+    /**
+     * Set additional skill-related IDs.
+     *
+     * @param coreSkillId The core skill ID (renamed from skillId to avoid confusion with runSkill's skillId)
+     * @param masterSkillId The master skill ID
+     * @param masterSkillActivityId The master skill activity ID
+     * @returns The builder instance for chaining
+     */
+    withSkillIds(coreSkillId?: string, masterSkillId?: string, masterSkillActivityId?: string): this;
+    /**
+     * Set graph execution context for better activity tracking.
+     *
+     * These fields enable smarter activity tracking and identity for nodes
+     * executing within graph workflows. When provided, they are automatically
+     * mapped to activity identity fields in the gateway.
+     *
+     * @param graphId Graph identifier for activity tracking
+     * @param nodeId Node identifier for activity tracking
+     * @param prevNodeId Previous node identifier for activity tracking
+     * @returns The builder instance for chaining
+     */
+    withGraphContext(graphId?: string, nodeId?: string, prevNodeId?: string): this;
+    /**
+     * Set graph identifier for activity tracking.
+     *
+     * @param graphId The graph identifier
+     * @returns The builder instance for chaining
+     */
+    withGraphId(graphId: string): this;
+    /**
+     * Set node identifier for activity tracking.
+     *
+     * @param nodeId The node identifier
+     * @returns The builder instance for chaining
+     */
+    withNodeId(nodeId: string): this;
+    /**
+     * Set previous node identifier for activity tracking.
+     *
+     * Used to track the previous node in a graph execution flow.
+     * Automatically mapped to identity.prevNodeId in activity tracking.
+     *
+     * @param prevNodeId The previous node identifier
+     * @returns The builder instance for chaining
+     */
+    withPrevNodeId(prevNodeId: string): this;
+    /**
+     * Set model configuration for this task execution.
+     *
+     * Controls which model is used and how it generates responses.
+     * This configuration overrides default model settings from client initialization
+     * and is passed through to the gateway for model selection and parameter control.
+     *
+     * @param modelConfig Model configuration (model, temperature, maxTokens, etc.)
+     * @returns The builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.withModelConfig({
+     *   model: "gpt-4-turbo",
+     *   temperature: 0.7,
+     *   maxTokens: 2000
+     * })
+     * ```
+     */
+    withModelConfig(modelConfig: ModelConfig): this;
+    /**
+     * Set the **main-skill** LLM call configuration (`RunTaskRequest.llmCall`).
+     *
+     * `LlmCallConfig` is the canonical, per-stage knob set used everywhere LLMs are invoked
+     * (PRE synthesis, AI scoping, MAIN skill, POST audit/polish, utilities). It supports:
+     *
+     * - `model`         — provider/model id (overrides `modelConfig.model`).
+     * - `maxTokensCap`  — **hard ceiling** for completion tokens; passed to `xynthesis.resolveMaxTokens`
+     *                     so the dynamic budget never exceeds this value. Use this instead of a bare
+     *                     `maxTokens` when you want to keep auto-sizing on but bound it.
+     * - `maxTokens`     — alias for `maxTokensCap` (kept for ergonomic parity with `ModelConfig`).
+     * - `temperature`   — sampling temperature.
+     * - `topP`          — nucleus-sampling cutoff.
+     * - `outputExpectation` — caller-supplied size/density hint forwarded to `resolveMaxTokens`
+     *                         (overrides per-action `ACTION_OUTPUT_DEFAULTS` from xynthesis routing JSON).
+     * - `maxOutputLength` — character cap applied after the LLM returns (post-truncation, not a token cap).
+     * - `timeoutMs`     — per-call timeout for the underlying invoke.
+     *
+     * `LlmCallConfig` is composable with the deprecated `modelConfig` and per-step `model`/`timeoutMs`/
+     * `maxOutputLength` fields — when both are set, `llmCall.*` wins.
+     *
+     * @example
+     * ```typescript
+     * builder.withLlmCall({
+     *   model: "gpt-5-mini",
+     *   maxTokensCap: 4096,
+     *   temperature: 0.4,
+     *   outputExpectation: { size: { kind: "absolute", maxWords: 600 }, density: "default" },
+     * })
+     * ```
+     */
+    withLlmCall(llmCall: LlmCallConfig): this;
+    /**
+     * Set AI-scoping execution options (request-level fallback for every per-instruction scoping call).
+     *
+     * - `llmCall` — default {@link LlmCallConfig} for scoping LLM calls. Per-instruction `instruction.llmCall`
+     *               overrides this.
+     * - `concurrency` — max parallel scoping calls (default 5; env `AI_SCOPING_CONCURRENCY`).
+     * - `timeoutMsPerItem` — per-instruction timeout in ms (default 30_000; env `AI_SCOPING_TIMEOUT_MS`).
+     *
+     * Per-item failures are captured (not silently dropped) on the response under
+     * `result.metadata.aiScopingFailures`. In trace mode the per-item observations are also surfaced
+     * under `result.metadata.aiScopingLlmCalls`.
+     */
+    withAiScopingOptions(opts: {
+        llmCall?: LlmCallConfig;
+        concurrency?: number;
+        timeoutMsPerItem?: number;
+    }): this;
+    /**
+     * Replace the `llmCall` config on the synthesized-context PRE step (must be added first via
+     * {@link withSynthesizedContextPreStep}).
+     */
+    withSynthesisLlmCall(llmCall: LlmCallConfig): this;
+    /**
+     * Replace the `llmCall` config on the audit POST step (must be added first via
+     * {@link withAuditPostStep}). When `role` is omitted, sets the top-level audit `llmCall` (used by both
+     * the audit evaluator and the synthesis-merge call). Use `role: "audit"` or `role: "synthesis"` to
+     * target a specific sub-call.
+     */
+    withAuditLlmCall(llmCall: LlmCallConfig, role?: "audit" | "synthesis"): this;
+    /**
+     * Replace the `llmCall` config on the polish POST step (must be added first via
+     * {@link withPolishPostStep}).
+     */
+    withPolishLlmCall(llmCall: LlmCallConfig): this;
+    /**
+     * Per-task overrides for gateway / athenix-parser template rendering (merged on client defaults for this invoke).
+     * See `@exellix/ai-skills` gateway template v4 docs (`subPathSearch`, optional tokens, etc.).
+     */
+    withTemplateRenderOptions(templateRenderOptions: TemplateRenderOptions): this;
+    /**
+     * Highest-priority template token overlay for this invoke (gateway `templateTokens`).
+     */
+    withTemplateTokens(templateTokens: GatewayTemplateTokens): this;
+    /** Graph/job-level xynthesized memory (job, task, and execution scopes). */
+    withXynthesized(xynthesized: XynthesizedMemory): this;
+    /** Passthrough smart-input config for upstream / Rendrix (legacy string paths or native `{ title, path }[]`). */
+    withSmartInput(config: RunTaskSmartInput): this;
+    /** Sets {@link RunTaskRequest.smartInput} with Rendrix-native path entries (`title` defaults to each path string). */
+    withSmartInputPaths(paths: string[]): this;
+    /** Gateway/Rendrix rendering options for the smart-input macro (merged like `RunSkillRequest.smartInputRenderOptions`). */
+    withSmartInputRenderOptions(opts: SmartInputRenderOptions): this;
+    /** Merge one key into `xynthesized.job`. */
+    withXynthesizedJob(key: string, value: unknown): this;
+    /** Merge one key into `xynthesized.task`. */
+    withXynthesizedTask(key: string, value: unknown): this;
+    /** Merge one key into `xynthesized.execution`. */
+    withXynthesizedExecution(key: string, value: unknown): this;
+    /**
+     * Build the final task request.
+     *
+     * @returns The complete task request
+     */
+    build(): RunTaskRequest;
+}
+//# sourceMappingURL=task-request-builder.d.ts.map

package/dist/builders/task-request-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-request-builder.d.ts","sourceRoot":"","sources":["../../src/builders/task-request-builder.ts"],"names":[],"mappings":"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"}