Skip to content

Enrichment Pipeline

The Enrichment Pipeline is a deterministic, pure-function pipeline that converts a minimal Plan Draft (produced by the Planner) into a fully typed Full Plan IR (ready for validation and execution).

import { enrichPlanDraft, CapabilityRegistry } from '@zakardo/core';
import type { PlanDraft, EnrichmentResult } from '@zakardo/core';
const registry = new CapabilityRegistry();
// ... register capabilities ...
const draft: PlanDraft = {
goal: 'List all VIP contacts',
steps: [
{ capability: 'contacts_list', version: '1.0.0', description: 'Get VIP contacts', inputs: { tag: 'VIP' } },
],
};
const result: EnrichmentResult = enrichPlanDraft(draft, registry);
if (result.ok) {
console.log(result.plan); // Full PlanIR — ready for validation
} else {
console.error(result.errors); // Structured enrichment errors
}

Each step is a pure function. The pipeline composes them sequentially, failing fast on unresolvable errors.

Resolves capability names and versions from the registry. Fails if a capability is not registered or the requested version does not exist.

Error codes: CAPABILITY_NOT_FOUND, VERSION_NOT_FOUND

Infers the plan’s input and output schemas from the resolved capability definitions. The plan’s overall input schema is the union of all step inputs that are not satisfied by other step outputs.

Converts the simplified draft bindings (e.g., { tag: "VIP" }) into full path expression bindings (e.g., $context.plan.inputs.tag). Literal values become LiteralBinding objects.

Helper exports:

import { convertDraftBinding, convertStepBindings, buildOutputNameMap } from '@zakardo/core';

Converts conditions from the draft format to structured Condition objects. In v1, natural language conditions are passed through with a raw flag for future LLM-based structuring.

Analyzes path expressions in bindings to compute depends_on relationships between steps. If Step 2’s input references $context.steps.step_0.output.contacts, then Step 2 depends on Step 0.

This produces a directed acyclic graph (DAG) that determines execution order. Cycles are detected and reported as errors.

Error codes: CIRCULAR_DEPENDENCY

Assigns deterministic step_index values and output_key identifiers to each step. Output keys follow the pattern step_0, step_1, etc.

Generates plan-level metadata:

  • plan_id — unique UUID v4
  • version — 1.0.0 for new plans
  • name — derived from the goal
  • lifecycle_state — CANDIDATE for new plans

Applies default error handling, retry, and execution constraints:

  • Error policy — default behavior on step failure
  • Retry policy — exponential backoff for transient errors
  • Execution constraints — timeout limits, mode requirements
type EnrichmentResult =
| { ok: true; plan: PlanIR }
| { ok: false; errors: readonly EnrichmentError[] };
interface EnrichmentError {
code: string;
step_index?: number;
capability?: string;
message: string;
suggestion?: string;
}
const result = enrichPlanDraft(draft, registry, {
plan_name: 'Custom Plan Name', // Override auto-generated name
version: '2.0.0', // Override default version
});