@warlock.js/ai 4.5.0 → 4.6.1

package/esm/planner/planner.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"planner.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/planner.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport { agent } from \"../agent/agent\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { PlannerCapability } from \"../contracts/planner/planner-capability.type\";\nimport type { PlannerConfig } from \"../contracts/planner/planner-config.type\";\nimport type { PlannerExecuteOptions } from \"../contracts/planner/planner-execute-options.type\";\nimport type { PlannerResult } from \"../contracts/planner/planner-result.type\";\nimport type { PlannerContract } from \"../contracts/planner/planner.contract\";\nimport { PlannerFailedError } from \"../errors\";\nimport { buildPlanSystemPrompt } from \"./plan-prompt\";\nimport { PlannerRun } from \"./planner-run\";\nimport { computeSignature } from \"./signature\";\n\nconst LOG_MODULE = \"ai.planner\";\n\n/**\n * `ai.planner(config)` — construct a {@link PlannerContract}.\n *\n * Validates the config at author time (throws {@link PlannerFailedError}\n * on a bad shape), builds (or adopts) the plan-generation agent, computes\n * a stable structural signature, and returns an instance satisfying\n * `ExecutableContract` so the planner composes into supervisors,\n * orchestrators, and outer agents through the same uniform surface.\n *\n * At `execute(goal)` the planner asks its LLM for an ordered plan over\n * the registered `capabilities`, then executes that plan step-by-step\n * through each capability's own `execute()` — reusing the existing\n * executable machinery rather than forking it — and returns the unified\n * `{ data, report, usage, error }` envelope with `report.type ===\n * \"planner\"`.\n *\n * @example\n * const research = ai.planner({\n *   name: \"research-assistant\",\n *   model: ai.openai.model({ name: \"gpt-4o\" }),\n *   capabilities: [\n *     { name: \"search\", description: \"Search the web\", executable: searchAgent },\n *     { name: \"write\", description: \"Draft a summary\", executable: writerAgent },\n *   ],\n *   maxSteps: 6,\n * });\n *\n * const { data, report } = await research.execute(\"Compare React vs Vue in 2026\");\n */\nexport function planner<TOutput = unknown>(\n  config: PlannerConfig<TOutput>,\n): PlannerContract<TOutput> {\n  validateConfig(config);\n\n  const maxSteps = config.maxSteps ?? 10;\n  const capabilities = new Map<string, PlannerCapability>();\n\n  for (const capability of config.capabilities) {\n    capabilities.set(capability.name, capability);\n  }\n\n  const signature = computeSignature(config.name, config.capabilities);\n  const planningAgent = resolvePlanningAgent(config, maxSteps);\n\n  async function execute(\n    goal: string,\n    options?: PlannerExecuteOptions<TOutput>,\n  ): Promise<PlannerResult<TOutput>> {\n    log.debug(LOG_MODULE, \"execute\", \"Planner run starting\", {\n      name: config.name,\n      capabilities: capabilities.size,\n    });\n\n    return new PlannerRun<TOutput>({\n      config,\n      capabilities,\n      maxSteps,\n      signature,\n      planningAgent,\n      goal,\n      options,\n    }).run();\n  }\n\n  return {\n    name: config.name,\n    signature,\n    execute,\n  };\n}\n\n/**\n * Resolve the plan-generation agent: either adopt the dev's `planner`\n * agent, or build an internal one from `model` with the generated\n * plan-system-prompt baked on. The plan output schema is supplied\n * per-call in {@link PlannerRun}, so it isn't baked here.\n *\n * **`maxSteps` and BYO planners.** In `model` mode the cap is woven\n * into the generated plan-system-prompt *and* the per-call plan schema\n * (`steps.maxItems`). In `planner` (BYO) mode the dev owns the prompt,\n * so the cap is communicated only through that same per-call schema —\n * and, regardless of mode, {@link PlannerRun} truncates any over-long\n * plan to `skipped` at execution time, so the cap is always enforced.\n */\nfunction resolvePlanningAgent<TOutput>(\n  config: PlannerConfig<TOutput>,\n  maxSteps: number,\n): AgentContract<unknown> {\n  if (config.planner) {\n    return config.planner;\n  }\n\n  const systemPrompt = buildPlanSystemPrompt(\n    config.capabilities,\n    maxSteps,\n    config.systemPrompt,\n    config.dag === true,\n  );\n\n  return agent({\n    name: `${config.name}-planner`,\n    description: \"Generates an ordered execution plan over the planner's capabilities.\",\n    model: config.model!,\n    systemPrompt,\n    maxTrips: 1,\n  });\n}\n\n/**\n * Factory-time validation. Surfaces every violation as a typed\n * {@link PlannerFailedError} tagged `authoring: true`, mirroring the\n * supervisor/orchestrator authoring-error convention.\n */\nfunction validateConfig<TOutput>(config: PlannerConfig<TOutput>): void {\n  if (!config.name || typeof config.name !== \"string\") {\n    throw new PlannerFailedError(\"ai.planner: `name` is required and must be a string\", {\n      context: { authoring: true },\n    });\n  }\n\n  const hasModel = config.model !== undefined;\n  const hasPlanner = config.planner !== undefined;\n\n  if (!hasModel && !hasPlanner) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): one of \\`model\\` or \\`planner\\` is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (hasModel && hasPlanner) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): \\`model\\` and \\`planner\\` are mutually exclusive — configure exactly one`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (!Array.isArray(config.capabilities) || config.capabilities.length === 0) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): at least one capability is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  const seen = new Set<string>();\n\n  for (const capability of config.capabilities) {\n    if (!capability || typeof capability.name !== \"string\" || capability.name.length === 0) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): every capability needs a non-empty \\`name\\``,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (typeof capability.description !== \"string\" || capability.description.length === 0) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): capability \"${capability.name}\" needs a \\`description\\``,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (!capability.executable || typeof capability.executable.execute !== \"function\") {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): capability \"${capability.name}\" needs an \\`executable\\` with an execute() method`,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (seen.has(capability.name)) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): duplicate capability name \"${capability.name}\"`,\n        { context: { authoring: true } },\n      );\n    }\n\n    seen.add(capability.name);\n  }\n\n  if (config.maxSteps !== undefined && config.maxSteps < 1) {\n    throw new PlannerFailedError(`ai.planner(\"${config.name}\"): \\`maxSteps\\` must be >= 1`, {\n      context: { authoring: true, maxSteps: config.maxSteps },\n    });\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"planner.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/planner.ts"],"sourcesContent":["import { log } from \"@warlock.js/logger\";\nimport { agent } from \"../agent/agent\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { PlannerCapability } from \"../contracts/planner/planner-capability.type\";\nimport type { PlannerConfig } from \"../contracts/planner/planner-config.type\";\nimport type {\n  PlannerExecuteOptions,\n  PlannerResumeOptions,\n} from \"../contracts/planner/planner-execute-options.type\";\nimport type { PlannerResult } from \"../contracts/planner/planner-result.type\";\nimport type { PlannerContract } from \"../contracts/planner/planner.contract\";\nimport { PlannerFailedError } from \"../errors\";\nimport { buildPlanSystemPrompt } from \"./plan-prompt\";\nimport { PlannerRun } from \"./planner-run\";\nimport { computeSignature } from \"./signature\";\nimport { loadPlannerSnapshotForResume } from \"./snapshot\";\n\nconst LOG_MODULE = \"ai.planner\";\n\n/**\n * `ai.planner(config)` — construct a {@link PlannerContract}.\n *\n * Validates the config at author time (throws {@link PlannerFailedError}\n * on a bad shape), builds (or adopts) the plan-generation agent, computes\n * a stable structural signature, and returns an instance satisfying\n * `ExecutableContract` so the planner composes into supervisors,\n * orchestrators, and outer agents through the same uniform surface.\n *\n * At `execute(goal)` the planner asks its LLM for an ordered plan over\n * the registered `capabilities`, then executes that plan step-by-step\n * through each capability's own `execute()` — reusing the existing\n * executable machinery rather than forking it — and returns the unified\n * `{ data, report, usage, error }` envelope with `report.type ===\n * \"planner\"`.\n *\n * @example\n * const research = ai.planner({\n *   name: \"research-assistant\",\n *   model: ai.openai.model({ name: \"gpt-4o\" }),\n *   capabilities: [\n *     { name: \"search\", description: \"Search the web\", executable: searchAgent },\n *     { name: \"write\", description: \"Draft a summary\", executable: writerAgent },\n *   ],\n *   maxSteps: 6,\n * });\n *\n * const { data, report } = await research.execute(\"Compare React vs Vue in 2026\");\n */\nexport function planner<TOutput = unknown>(\n  config: PlannerConfig<TOutput>,\n): PlannerContract<TOutput> {\n  validateConfig(config);\n\n  const maxSteps = config.maxSteps ?? 10;\n  const capabilities = new Map<string, PlannerCapability>();\n\n  for (const capability of config.capabilities) {\n    capabilities.set(capability.name, capability);\n  }\n\n  const signature = computeSignature(config.name, config.capabilities);\n  const planningAgent = resolvePlanningAgent(config, maxSteps);\n\n  async function execute(\n    goal: string,\n    options?: PlannerExecuteOptions<TOutput>,\n  ): Promise<PlannerResult<TOutput>> {\n    log.debug(LOG_MODULE, \"execute\", \"Planner run starting\", {\n      name: config.name,\n      capabilities: capabilities.size,\n    });\n\n    return new PlannerRun<TOutput>({\n      config,\n      capabilities,\n      maxSteps,\n      signature,\n      planningAgent,\n      goal,\n      options,\n    }).run();\n  }\n\n  async function resume(\n    runId: string,\n    options?: PlannerResumeOptions<TOutput>,\n  ): Promise<PlannerResult<TOutput>> {\n    // Load the persisted snapshot and run the drift check (throws\n    // PlannerDriftError on a structural mismatch unless `{ force: true }`).\n    const snapshot = await loadPlannerSnapshotForResume({\n      durable: config.durable,\n      plannerName: config.name,\n      signature,\n      runId,\n      options: options as PlannerResumeOptions<unknown> | undefined,\n    });\n\n    return new PlannerRun<TOutput>({\n      config,\n      capabilities,\n      maxSteps,\n      signature,\n      planningAgent,\n      goal: snapshot.goal,\n      options: { ...options, runId } as PlannerExecuteOptions<TOutput>,\n      resumeFrom: snapshot,\n    }).run();\n  }\n\n  return {\n    name: config.name,\n    signature,\n    execute,\n    resume,\n  };\n}\n\n/**\n * Resolve the plan-generation agent: either adopt the dev's `planner`\n * agent, or build an internal one from `model` with the generated\n * plan-system-prompt baked on. The plan output schema is supplied\n * per-call in {@link PlannerRun}, so it isn't baked here.\n *\n * **`maxSteps` and BYO planners.** In `model` mode the cap is woven\n * into the generated plan-system-prompt *and* the per-call plan schema\n * (`steps.maxItems`). In `planner` (BYO) mode the dev owns the prompt,\n * so the cap is communicated only through that same per-call schema —\n * and, regardless of mode, {@link PlannerRun} truncates any over-long\n * plan to `skipped` at execution time, so the cap is always enforced.\n */\nfunction resolvePlanningAgent<TOutput>(\n  config: PlannerConfig<TOutput>,\n  maxSteps: number,\n): AgentContract<unknown> {\n  if (config.planner) {\n    return config.planner;\n  }\n\n  const systemPrompt = buildPlanSystemPrompt(\n    config.capabilities,\n    maxSteps,\n    config.systemPrompt,\n    config.dag === true,\n  );\n\n  return agent({\n    name: `${config.name}-planner`,\n    description: \"Generates an ordered execution plan over the planner's capabilities.\",\n    model: config.model!,\n    systemPrompt,\n    maxTrips: 1,\n  });\n}\n\n/**\n * Factory-time validation. Surfaces every violation as a typed\n * {@link PlannerFailedError} tagged `authoring: true`, mirroring the\n * supervisor/orchestrator authoring-error convention.\n */\nfunction validateConfig<TOutput>(config: PlannerConfig<TOutput>): void {\n  if (!config.name || typeof config.name !== \"string\") {\n    throw new PlannerFailedError(\"ai.planner: `name` is required and must be a string\", {\n      context: { authoring: true },\n    });\n  }\n\n  const hasModel = config.model !== undefined;\n  const hasPlanner = config.planner !== undefined;\n\n  if (!hasModel && !hasPlanner) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): one of \\`model\\` or \\`planner\\` is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (hasModel && hasPlanner) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): \\`model\\` and \\`planner\\` are mutually exclusive — configure exactly one`,\n      { context: { authoring: true } },\n    );\n  }\n\n  if (!Array.isArray(config.capabilities) || config.capabilities.length === 0) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${config.name}\"): at least one capability is required`,\n      { context: { authoring: true } },\n    );\n  }\n\n  const seen = new Set<string>();\n\n  for (const capability of config.capabilities) {\n    if (!capability || typeof capability.name !== \"string\" || capability.name.length === 0) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): every capability needs a non-empty \\`name\\``,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (typeof capability.description !== \"string\" || capability.description.length === 0) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): capability \"${capability.name}\" needs a \\`description\\``,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (!capability.executable || typeof capability.executable.execute !== \"function\") {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): capability \"${capability.name}\" needs an \\`executable\\` with an execute() method`,\n        { context: { authoring: true } },\n      );\n    }\n\n    if (seen.has(capability.name)) {\n      throw new PlannerFailedError(\n        `ai.planner(\"${config.name}\"): duplicate capability name \"${capability.name}\"`,\n        { context: { authoring: true } },\n      );\n    }\n\n    seen.add(capability.name);\n  }\n\n  if (config.maxSteps !== undefined && config.maxSteps < 1) {\n    throw new PlannerFailedError(`ai.planner(\"${config.name}\"): \\`maxSteps\\` must be >= 1`, {\n      context: { authoring: true, maxSteps: config.maxSteps },\n    });\n  }\n}\n"],"mappings":"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"}

package/esm/planner/snapshot.mjs

@@ -0,0 +1,95 @@
+import { PlannerFailedError } from "../errors/planner-failed-error.mjs";
+import { PlannerDriftError } from "../errors/planner-drift-error.mjs";
+import "../errors/index.mjs";
+import { resolveDefaultSnapshotStore } from "../config.mjs";
+
+//#region ../@warlock.js/ai/src/planner/snapshot.ts
+/**
+* Resolve the effective {@link SnapshotStore}: the planner's own
+* `durable.store` wins; absent that, fall back to the global default set
+* via `ai.config({ defaultSnapshotStore })`.
+*
+* The global default is typed for the supervisor snapshot shape, but
+* every store impl keys purely by `runId` and round-trips whatever
+* envelope it is handed — so it serves a `PlannerSnapshot` just as well.
+* The cast re-tags the shape at this single boundary (Option B); the
+* planner only ever hands it a `PlannerSnapshot`.
+*/
+function resolveSnapshotStore(durable) {
+	return durable?.store ?? resolveDefaultSnapshotStore();
+}
+/**
+* Write the current run state to the resolved snapshot store. No-op
+* (returns `{ ok: true }`) when neither `durable.store` nor the global
+* `defaultSnapshotStore` is configured — the common non-durable path.
+* Failures are returned as `{ ok: false }` rather than thrown so the
+* engine can surface them via logs without aborting the run.
+*/
+async function persistPlannerSnapshot(params) {
+	const store = resolveSnapshotStore(params.durable);
+	if (!store) return { ok: true };
+	const snapshot = {
+		runId: params.runId,
+		plannerName: params.plannerName,
+		signature: params.signature,
+		version: params.version,
+		goal: params.goal,
+		plan: params.plan,
+		executedSteps: params.executedSteps,
+		usage: params.usage,
+		children: params.children,
+		replanCount: params.replanCount,
+		status: params.status,
+		startedAt: params.startedAt,
+		savedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	try {
+		await store.save(snapshot);
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+/**
+* Delete a persisted snapshot — used after a successful run when
+* `durable.deleteOnComplete` is set. Never throws. No-op (ok) when no
+* store is configured.
+*/
+async function deletePlannerSnapshot(params) {
+	const store = resolveSnapshotStore(params.durable);
+	if (!store) return { ok: true };
+	try {
+		await store.delete(params.runId);
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+/**
+* Load a persisted snapshot for `resume()` and run the drift check.
+* Throws `PlannerFailedError` when no store is configured or when the run
+* is missing; throws `PlannerDriftError` when the stored signature
+* doesn't match the current definition (unless `force` is set).
+*/
+async function loadPlannerSnapshotForResume(params) {
+	const store = resolveSnapshotStore(params.durable);
+	if (!store) throw new PlannerFailedError(`ai.planner("${params.plannerName}"): no durable store configured — set \`durable: { store }\` on the config or call \`ai.config({ defaultSnapshotStore })\` at boot before calling resume()`, { context: { runId: params.runId } });
+	const snapshot = await store.load(params.runId) ?? null;
+	if (!snapshot) throw new PlannerFailedError(`ai.planner("${params.plannerName}"): no snapshot for runId "${params.runId}"`, { context: { runId: params.runId } });
+	if (!params.options?.force && snapshot.signature !== params.signature) throw new PlannerDriftError(`ai.planner("${params.plannerName}") signature drift on resume`, {
+		savedSignature: snapshot.signature,
+		currentSignature: params.signature,
+		runId: params.runId
+	});
+	return snapshot;
+}
+
+//#endregion
+export { deletePlannerSnapshot, loadPlannerSnapshotForResume, persistPlannerSnapshot };
+//# sourceMappingURL=snapshot.mjs.map

package/esm/planner/snapshot.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/planner/snapshot.ts"],"sourcesContent":["import { resolveDefaultSnapshotStore } from \"../config\";\nimport type { SnapshotStore } from \"../contracts/orchestrator/snapshot-store.contract\";\nimport type { PlannerResumeOptions } from \"../contracts/planner/planner-execute-options.type\";\nimport type { PlannerPlan } from \"../contracts/planner/planner-plan.type\";\nimport type { PlannerStepSnapshot } from \"../contracts/planner/planner-result.type\";\nimport type {\n  PlannerSnapshot,\n  PlannerSnapshotStatus,\n} from \"../contracts/planner/planner-snapshot.type\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { PlannerDriftError, PlannerFailedError } from \"../errors\";\n\n/**\n * The planner's `durable` config, narrowed to the fields the snapshot\n * helpers read.\n */\nexport type PlannerDurableConfig = {\n  store?: SnapshotStore<PlannerSnapshot>;\n  deleteOnComplete?: boolean;\n};\n\n/**\n * Resolve the effective {@link SnapshotStore}: the planner's own\n * `durable.store` wins; absent that, fall back to the global default set\n * via `ai.config({ defaultSnapshotStore })`.\n *\n * The global default is typed for the supervisor snapshot shape, but\n * every store impl keys purely by `runId` and round-trips whatever\n * envelope it is handed — so it serves a `PlannerSnapshot` just as well.\n * The cast re-tags the shape at this single boundary (Option B); the\n * planner only ever hands it a `PlannerSnapshot`.\n */\nfunction resolveSnapshotStore(\n  durable: PlannerDurableConfig | undefined,\n): SnapshotStore<PlannerSnapshot> | undefined {\n  return (\n    durable?.store ??\n    (resolveDefaultSnapshotStore() as SnapshotStore<PlannerSnapshot> | undefined)\n  );\n}\n\nexport type PersistPlannerParams = {\n  durable: PlannerDurableConfig | undefined;\n  runId: string;\n  plannerName: string;\n  signature: string;\n  version?: string;\n  goal: string;\n  plan: PlannerPlan;\n  executedSteps: PlannerStepSnapshot[];\n  usage: Usage;\n  children: BaseReport[];\n  replanCount: number;\n  status: PlannerSnapshotStatus;\n  startedAt: string;\n};\n\nexport type PersistOutcome = { ok: true } | { ok: false; error: unknown };\n\n/**\n * Write the current run state to the resolved snapshot store. No-op\n * (returns `{ ok: true }`) when neither `durable.store` nor the global\n * `defaultSnapshotStore` is configured — the common non-durable path.\n * Failures are returned as `{ ok: false }` rather than thrown so the\n * engine can surface them via logs without aborting the run.\n */\nexport async function persistPlannerSnapshot(\n  params: PersistPlannerParams,\n): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    return { ok: true };\n  }\n\n  const snapshot: PlannerSnapshot = {\n    runId: params.runId,\n    plannerName: params.plannerName,\n    signature: params.signature,\n    version: params.version,\n    goal: params.goal,\n    plan: params.plan,\n    executedSteps: params.executedSteps,\n    usage: params.usage,\n    children: params.children,\n    replanCount: params.replanCount,\n    status: params.status,\n    startedAt: params.startedAt,\n    savedAt: new Date().toISOString(),\n  };\n\n  try {\n    await store.save(snapshot);\n\n    return { ok: true };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Delete a persisted snapshot — used after a successful run when\n * `durable.deleteOnComplete` is set. Never throws. No-op (ok) when no\n * store is configured.\n */\nexport async function deletePlannerSnapshot(params: {\n  durable: PlannerDurableConfig | undefined;\n  runId: string;\n}): Promise<PersistOutcome> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    return { ok: true };\n  }\n\n  try {\n    await store.delete(params.runId);\n\n    return { ok: true };\n  } catch (error) {\n    return { ok: false, error };\n  }\n}\n\n/**\n * Load a persisted snapshot for `resume()` and run the drift check.\n * Throws `PlannerFailedError` when no store is configured or when the run\n * is missing; throws `PlannerDriftError` when the stored signature\n * doesn't match the current definition (unless `force` is set).\n */\nexport async function loadPlannerSnapshotForResume(params: {\n  durable: PlannerDurableConfig | undefined;\n  plannerName: string;\n  signature: string;\n  runId: string;\n  options?: PlannerResumeOptions<unknown>;\n}): Promise<PlannerSnapshot> {\n  const store = resolveSnapshotStore(params.durable);\n\n  if (!store) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${params.plannerName}\"): no durable store configured — set \\`durable: { store }\\` on the config or call \\`ai.config({ defaultSnapshotStore })\\` at boot before calling resume()`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  const snapshot = (await store.load(params.runId)) ?? null;\n\n  if (!snapshot) {\n    throw new PlannerFailedError(\n      `ai.planner(\"${params.plannerName}\"): no snapshot for runId \"${params.runId}\"`,\n      { context: { runId: params.runId } },\n    );\n  }\n\n  if (!params.options?.force && snapshot.signature !== params.signature) {\n    throw new PlannerDriftError(\n      `ai.planner(\"${params.plannerName}\") signature drift on resume`,\n      {\n        savedSignature: snapshot.signature,\n        currentSignature: params.signature,\n        runId: params.runId,\n      },\n    );\n  }\n\n  return snapshot;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAiCA,SAAS,qBACP,SAC4C;CAC5C,OACE,SAAS,SACR,4BAA4B;AAEjC;;;;;;;;AA2BA,eAAsB,uBACpB,QACyB;CACzB,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,OAAO,EAAE,IAAI,KAAK;CAGpB,MAAM,WAA4B;EAChC,OAAO,OAAO;EACd,aAAa,OAAO;EACpB,WAAW,OAAO;EAClB,SAAS,OAAO;EAChB,MAAM,OAAO;EACb,MAAM,OAAO;EACb,eAAe,OAAO;EACtB,OAAO,OAAO;EACd,UAAU,OAAO;EACjB,aAAa,OAAO;EACpB,QAAQ,OAAO;EACf,WAAW,OAAO;EAClB,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;CAClC;CAEA,IAAI;EACF,MAAM,MAAM,KAAK,QAAQ;EAEzB,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO;EAAM;CAC5B;AACF;;;;;;AAOA,eAAsB,sBAAsB,QAGhB;CAC1B,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,OAAO,EAAE,IAAI,KAAK;CAGpB,IAAI;EACF,MAAM,MAAM,OAAO,OAAO,KAAK;EAE/B,OAAO,EAAE,IAAI,KAAK;CACpB,SAAS,OAAO;EACd,OAAO;GAAE,IAAI;GAAO;EAAM;CAC5B;AACF;;;;;;;AAQA,eAAsB,6BAA6B,QAMtB;CAC3B,MAAM,QAAQ,qBAAqB,OAAO,OAAO;CAEjD,IAAI,CAAC,OACH,MAAM,IAAI,mBACR,eAAe,OAAO,YAAY,6JAClC,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,MAAM,WAAY,MAAM,MAAM,KAAK,OAAO,KAAK,KAAM;CAErD,IAAI,CAAC,UACH,MAAM,IAAI,mBACR,eAAe,OAAO,YAAY,6BAA6B,OAAO,MAAM,IAC5E,EAAE,SAAS,EAAE,OAAO,OAAO,MAAM,EAAE,CACrC;CAGF,IAAI,CAAC,OAAO,SAAS,SAAS,SAAS,cAAc,OAAO,WAC1D,MAAM,IAAI,kBACR,eAAe,OAAO,YAAY,+BAClC;EACE,gBAAgB,SAAS;EACzB,kBAAkB,OAAO;EACzB,OAAO,OAAO;CAChB,CACF;CAGF,OAAO;AACT"}

package/esm/rag/index.d.mts

@@ -7,6 +7,13 @@ import { rag } from "./rag.mjs";
 import { chunk } from "./chunk/chunk.mjs";
 import { VectorStore } from "./store/vector-store.contract.mjs";
 import { cacheVectorStore } from "./store/cache-vector-store.mjs";
+import { PgClientLike, PgVectorStoreInstance, PgVectorStoreOptions, pgVectorStore, vectorLiteral } from "./store/pg-vector-store.mjs";
+import { LoadHtmlOptions, LoadPdfOptions, LoadTextOptions, LoadWebOptions, RagLoaderMetadata, RagLoaderOptions, RagLoaderResult, RagLoaderType } from "./loaders/loader.type.mjs";
+import { TextInput, loadText } from "./loaders/load-text.mjs";
+import { loadHtml } from "./loaders/load-html.mjs";
+import { loadWeb } from "./loaders/load-web.mjs";
+import { loadPdf } from "./loaders/load-pdf.mjs";
+import { PDF_PARSE_INSTALL_INSTRUCTIONS } from "./loaders/errors.mjs";
 import { KeywordRerankerOptions, keywordReranker } from "./rerank/keyword-reranker.mjs";
 import { LlmRerankerOptions, llmReranker } from "./rerank/llm-reranker.mjs";
 import { RankedItem, reciprocalRankFusion } from "./hybrid/rrf.mjs";

package/esm/rag/index.mjs

@@ -1,6 +1,13 @@
 import { chunk } from "./chunk/chunk.mjs";
 import { cacheVectorStore } from "./store/cache-vector-store.mjs";
 import { rag } from "./rag.mjs";
+import { pgVectorStore, vectorLiteral } from "./store/pg-vector-store.mjs";
+import { loadText } from "./loaders/load-text.mjs";
+import { loadHtml } from "./loaders/load-html.mjs";
+import { loadWeb } from "./loaders/load-web.mjs";
+import { PDF_PARSE_INSTALL_INSTRUCTIONS } from "./loaders/errors.mjs";
+import { loadPdf } from "./loaders/load-pdf.mjs";
+import "./loaders/index.mjs";
 import { keywordReranker } from "./rerank/keyword-reranker.mjs";
 import { llmReranker } from "./rerank/llm-reranker.mjs";
 import { reciprocalRankFusion } from "./hybrid/rrf.mjs";

package/esm/rag/loaders/errors.d.mts

@@ -0,0 +1,19 @@
+//#region ../@warlock.js/ai/src/rag/loaders/errors.d.ts
+/**
+ * Loader error surface. The only loader-specific failure is a missing
+ * OPTIONAL peer (`pdf-parse`), which — like the moderation detector's
+ * missing `openai` peer — is an *infrastructure* fault, not a content
+ * problem, so {@link loadPdf} throws a plain `Error` carrying the curated
+ * {@link PDF_PARSE_INSTALL_INSTRUCTIONS} rather than an `AIError`. Mirrors
+ * the guard's `OPENAI_INSTALL_INSTRUCTIONS` / ai-panoptic's
+ * `LANGFUSE_INSTALL_INSTRUCTIONS`.
+ */
+/**
+ * Curated install string thrown by {@link loadPdf} on first call when the
+ * `pdf-parse` peer is absent. Surfaced instead of a raw
+ * module-resolution stack trace.
+ */
+declare const PDF_PARSE_INSTALL_INSTRUCTIONS: string;
+//#endregion
+export { PDF_PARSE_INSTALL_INSTRUCTIONS };
+//# sourceMappingURL=errors.d.mts.map

package/esm/rag/loaders/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/errors.ts"],"mappings":";;AAeA;;;;AAKQ;;;;;;;;;cALK,8BAAA"}

package/esm/rag/loaders/errors.mjs

@@ -0,0 +1,25 @@
+//#region ../@warlock.js/ai/src/rag/loaders/errors.ts
+/**
+* Loader error surface. The only loader-specific failure is a missing
+* OPTIONAL peer (`pdf-parse`), which — like the moderation detector's
+* missing `openai` peer — is an *infrastructure* fault, not a content
+* problem, so {@link loadPdf} throws a plain `Error` carrying the curated
+* {@link PDF_PARSE_INSTALL_INSTRUCTIONS} rather than an `AIError`. Mirrors
+* the guard's `OPENAI_INSTALL_INSTRUCTIONS` / ai-panoptic's
+* `LANGFUSE_INSTALL_INSTRUCTIONS`.
+*/
+/**
+* Curated install string thrown by {@link loadPdf} on first call when the
+* `pdf-parse` peer is absent. Surfaced instead of a raw
+* module-resolution stack trace.
+*/
+const PDF_PARSE_INSTALL_INSTRUCTIONS = `
+The @warlock.js/ai PDF loader requires the optional "pdf-parse" peer.
+Install it with:
+
+  npm install pdf-parse
+`.trim();
+
+//#endregion
+export { PDF_PARSE_INSTALL_INSTRUCTIONS };
+//# sourceMappingURL=errors.mjs.map

package/esm/rag/loaders/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/errors.ts"],"sourcesContent":["/**\n * Loader error surface. The only loader-specific failure is a missing\n * OPTIONAL peer (`pdf-parse`), which — like the moderation detector's\n * missing `openai` peer — is an *infrastructure* fault, not a content\n * problem, so {@link loadPdf} throws a plain `Error` carrying the curated\n * {@link PDF_PARSE_INSTALL_INSTRUCTIONS} rather than an `AIError`. Mirrors\n * the guard's `OPENAI_INSTALL_INSTRUCTIONS` / ai-panoptic's\n * `LANGFUSE_INSTALL_INSTRUCTIONS`.\n */\n\n/**\n * Curated install string thrown by {@link loadPdf} on first call when the\n * `pdf-parse` peer is absent. Surfaced instead of a raw\n * module-resolution stack trace.\n */\nexport const PDF_PARSE_INSTALL_INSTRUCTIONS = `\nThe @warlock.js/ai PDF loader requires the optional \"pdf-parse\" peer.\nInstall it with:\n\n  npm install pdf-parse\n`.trim();\n"],"mappings":";;;;;;;;;;;;;;;AAeA,MAAa,iCAAiC;;;;;EAK5C,KAAK"}

package/esm/rag/loaders/index.mjs

@@ -0,0 +1,7 @@
+import { loadText } from "./load-text.mjs";
+import { loadHtml } from "./load-html.mjs";
+import { loadWeb } from "./load-web.mjs";
+import { PDF_PARSE_INSTALL_INSTRUCTIONS } from "./errors.mjs";
+import { loadPdf } from "./load-pdf.mjs";
+
+export {  };

package/esm/rag/loaders/load-html.d.mts

@@ -0,0 +1,26 @@
+import { LoadHtmlOptions, RagLoaderResult } from "./loader.type.mjs";
+
+//#region ../@warlock.js/ai/src/rag/loaders/load-html.d.ts
+/**
+ * Load an HTML string into a single {@link RagDocument} of readable text.
+ * Scripts, styles, and other non-prose elements are dropped content-and-all,
+ * block tags become line breaks (so paragraph structure survives for the
+ * splitter), remaining tags are stripped, and HTML entities are decoded — a
+ * lightweight regex pass, no heavy DOM dependency.
+ *
+ * The document's `metadata.title` is set from the page's `<title>` (unless
+ * the caller overrode it), and `metadata.loader` is `"html"`. The output is
+ * the exact shape `index()` consumes.
+ *
+ * @example
+ * const kb = ai.rag({ embedder, store });
+ * await kb.index(loadHtml(rawHtmlString, { id: "landing-page" }));
+ *
+ * @param html - The raw HTML markup.
+ * @param options - Shared `id` / `metadata` / `tags` ({@link LoadHtmlOptions}).
+ * @returns A {@link RagLoaderResult} (one document) ready for `rag.index()`.
+ */
+declare function loadHtml(html: string, options?: LoadHtmlOptions): RagLoaderResult;
+//#endregion
+export { loadHtml };
+//# sourceMappingURL=load-html.d.mts.map

package/esm/rag/loaders/load-html.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-html.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/load-html.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;iBAiKgB,QAAA,CACd,IAAA,UACA,OAAA,GAAS,eAAA,GACR,eAAe"}

package/esm/rag/loaders/load-html.mjs

@@ -0,0 +1,138 @@
+//#region ../@warlock.js/ai/src/rag/loaders/load-html.ts
+/** Default `id` when the caller supplies none. */
+const DEFAULT_ID = "document";
+/**
+* Elements whose *content* is not human-readable text and must be removed
+* wholesale (open tag → close tag → everything in between) before tags are
+* stripped. `script` / `style` would otherwise leak code into the chunked
+* text; `noscript` / `template` / `head` / `svg` are non-prose noise.
+*/
+const STRIPPED_ELEMENTS = [
+	"script",
+	"style",
+	"noscript",
+	"template",
+	"head",
+	"svg"
+];
+/**
+* Block-level tags that imply a line break in the readable text. Replacing
+* them with `\n` BEFORE the generic tag strip keeps paragraph / list / table
+* structure (so the recursive splitter still sees `\n\n` boundaries) instead
+* of collapsing the whole page onto one line.
+*/
+const BLOCK_TAGS = /<\/?(?:p|div|section|article|header|footer|main|aside|nav|h[1-6]|ul|ol|li|table|tr|td|th|thead|tbody|blockquote|pre|hr|br)\b[^>]*>/gi;
+/** Named HTML entities common in prose. Numeric entities are decoded generically. */
+const NAMED_ENTITIES = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+	nbsp: " ",
+	copy: "©",
+	reg: "®",
+	trade: "™",
+	hellip: "…",
+	mdash: "—",
+	ndash: "–",
+	lsquo: "‘",
+	rsquo: "’",
+	ldquo: "“",
+	rdquo: "”",
+	laquo: "«",
+	raquo: "»",
+	middot: "·",
+	bull: "•"
+};
+/**
+* Decode the HTML entities that survive tag stripping: named (`&amp;`),
+* decimal (`&#169;`), and hex (`&#xA9;`). Unknown named entities are left
+* verbatim rather than dropped, so unusual markup never silently loses text.
+*/
+function decodeEntities(text) {
+	return text.replace(/&(#x?[0-9a-f]+|[a-z][a-z0-9]*);/gi, (match, body) => {
+		if (body[0] === "#") {
+			const codePoint = body[1] === "x" || body[1] === "X" ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+			if (Number.isNaN(codePoint) || codePoint < 0 || codePoint > 1114111) return match;
+			try {
+				return String.fromCodePoint(codePoint);
+			} catch {
+				return match;
+			}
+		}
+		return NAMED_ENTITIES[body.toLowerCase()] ?? match;
+	});
+}
+/**
+* Pull the `<title>` text out of the document, decoded and trimmed, or
+* `undefined` when there is none. Read BEFORE `<head>` is stripped.
+*/
+function extractTitle(html) {
+	const match = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+	if (!match) return;
+	const title = decodeEntities(match[1]).replace(/\s+/g, " ").trim();
+	return title.length > 0 ? title : void 0;
+}
+/**
+* Strip HTML markup down to readable plain text — a lightweight,
+* dependency-free pass (no DOM parser): drop comments and non-prose elements
+* (`script` / `style` / `head` / `svg` / …) content-and-all, convert block
+* tags to line breaks to preserve paragraph structure, remove every
+* remaining tag, decode entities, then collapse runs of whitespace while
+* keeping blank-line paragraph separators.
+*/
+function htmlToText(html) {
+	let text = html;
+	text = text.replace(/<!--[\s\S]*?-->/g, " ");
+	for (const tag of STRIPPED_ELEMENTS) {
+		const element = new RegExp(`<${tag}\\b[^>]*>[\\s\\S]*?<\\/${tag}>`, "gi");
+		text = text.replace(element, " ");
+		text = text.replace(new RegExp(`<\\/?${tag}\\b[^>]*>`, "gi"), " ");
+	}
+	text = text.replace(BLOCK_TAGS, "\n");
+	text = text.replace(/<[^>]+>/g, "");
+	text = decodeEntities(text);
+	text = text.replace(/[^\S\n]+/g, " ").replace(/[ \t]*\n[ \t]*/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+	return text;
+}
+/**
+* Load an HTML string into a single {@link RagDocument} of readable text.
+* Scripts, styles, and other non-prose elements are dropped content-and-all,
+* block tags become line breaks (so paragraph structure survives for the
+* splitter), remaining tags are stripped, and HTML entities are decoded — a
+* lightweight regex pass, no heavy DOM dependency.
+*
+* The document's `metadata.title` is set from the page's `<title>` (unless
+* the caller overrode it), and `metadata.loader` is `"html"`. The output is
+* the exact shape `index()` consumes.
+*
+* @example
+* const kb = ai.rag({ embedder, store });
+* await kb.index(loadHtml(rawHtmlString, { id: "landing-page" }));
+*
+* @param html - The raw HTML markup.
+* @param options - Shared `id` / `metadata` / `tags` ({@link LoadHtmlOptions}).
+* @returns A {@link RagLoaderResult} (one document) ready for `rag.index()`.
+*/
+function loadHtml(html, options = {}) {
+	const id = options.id ?? DEFAULT_ID;
+	const title = extractTitle(html);
+	const text = htmlToText(html);
+	if (text.length === 0) return [];
+	return [{
+		id,
+		text,
+		metadata: {
+			source: id,
+			loader: "html",
+			...title !== void 0 ? { title } : {},
+			...options.metadata
+		},
+		tags: options.tags
+	}];
+}
+
+//#endregion
+export { extractTitle, htmlToText, loadHtml };
+//# sourceMappingURL=load-html.mjs.map

package/esm/rag/loaders/load-html.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-html.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/load-html.ts"],"sourcesContent":["import type { RagDocument } from \"../contracts/rag-document.type\";\nimport type { LoadHtmlOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Default `id` when the caller supplies none. */\nconst DEFAULT_ID = \"document\";\n\n/**\n * Elements whose *content* is not human-readable text and must be removed\n * wholesale (open tag → close tag → everything in between) before tags are\n * stripped. `script` / `style` would otherwise leak code into the chunked\n * text; `noscript` / `template` / `head` / `svg` are non-prose noise.\n */\nconst STRIPPED_ELEMENTS = [\n  \"script\",\n  \"style\",\n  \"noscript\",\n  \"template\",\n  \"head\",\n  \"svg\",\n];\n\n/**\n * Block-level tags that imply a line break in the readable text. Replacing\n * them with `\\n` BEFORE the generic tag strip keeps paragraph / list / table\n * structure (so the recursive splitter still sees `\\n\\n` boundaries) instead\n * of collapsing the whole page onto one line.\n */\nconst BLOCK_TAGS =\n  /<\\/?(?:p|div|section|article|header|footer|main|aside|nav|h[1-6]|ul|ol|li|table|tr|td|th|thead|tbody|blockquote|pre|hr|br)\\b[^>]*>/gi;\n\n/** Named HTML entities common in prose. Numeric entities are decoded generically. */\nconst NAMED_ENTITIES: Record<string, string> = {\n  amp: \"&\",\n  lt: \"<\",\n  gt: \">\",\n  quot: '\"',\n  apos: \"'\",\n  nbsp: \" \",\n  copy: \"©\",\n  reg: \"®\",\n  trade: \"™\",\n  hellip: \"…\",\n  mdash: \"—\",\n  ndash: \"–\",\n  lsquo: \"‘\",\n  rsquo: \"’\",\n  ldquo: \"“\",\n  rdquo: \"”\",\n  laquo: \"«\",\n  raquo: \"»\",\n  middot: \"·\",\n  bull: \"•\",\n};\n\n/**\n * Decode the HTML entities that survive tag stripping: named (`&amp;`),\n * decimal (`&#169;`), and hex (`&#xA9;`). Unknown named entities are left\n * verbatim rather than dropped, so unusual markup never silently loses text.\n */\nfunction decodeEntities(text: string): string {\n  return text.replace(/&(#x?[0-9a-f]+|[a-z][a-z0-9]*);/gi, (match, body: string) => {\n    if (body[0] === \"#\") {\n      const codePoint =\n        body[1] === \"x\" || body[1] === \"X\"\n          ? Number.parseInt(body.slice(2), 16)\n          : Number.parseInt(body.slice(1), 10);\n\n      if (Number.isNaN(codePoint) || codePoint < 0 || codePoint > 0x10ffff) {\n        return match;\n      }\n\n      try {\n        return String.fromCodePoint(codePoint);\n      } catch {\n        return match;\n      }\n    }\n\n    const named = NAMED_ENTITIES[body.toLowerCase()];\n\n    return named ?? match;\n  });\n}\n\n/**\n * Pull the `<title>` text out of the document, decoded and trimmed, or\n * `undefined` when there is none. Read BEFORE `<head>` is stripped.\n */\nfunction extractTitle(html: string): string | undefined {\n  const match = /<title[^>]*>([\\s\\S]*?)<\\/title>/i.exec(html);\n\n  if (!match) {\n    return undefined;\n  }\n\n  const title = decodeEntities(match[1]).replace(/\\s+/g, \" \").trim();\n\n  return title.length > 0 ? title : undefined;\n}\n\n/**\n * Strip HTML markup down to readable plain text — a lightweight,\n * dependency-free pass (no DOM parser): drop comments and non-prose elements\n * (`script` / `style` / `head` / `svg` / …) content-and-all, convert block\n * tags to line breaks to preserve paragraph structure, remove every\n * remaining tag, decode entities, then collapse runs of whitespace while\n * keeping blank-line paragraph separators.\n */\nfunction htmlToText(html: string): string {\n  let text = html;\n\n  // 1. Comments first — a commented-out `<script>` must not survive.\n  text = text.replace(/<!--[\\s\\S]*?-->/g, \" \");\n\n  // 2. Non-prose elements, content and all.\n  for (const tag of STRIPPED_ELEMENTS) {\n    const element = new RegExp(`<${tag}\\\\b[^>]*>[\\\\s\\\\S]*?<\\\\/${tag}>`, \"gi\");\n    text = text.replace(element, \" \");\n    // Defensively drop a self-closing / unterminated open tag too.\n    text = text.replace(new RegExp(`<\\\\/?${tag}\\\\b[^>]*>`, \"gi\"), \" \");\n  }\n\n  // 3. Block tags → newlines, so paragraph / list structure survives.\n  text = text.replace(BLOCK_TAGS, \"\\n\");\n\n  // 4. Every remaining tag → gone.\n  text = text.replace(/<[^>]+>/g, \"\");\n\n  // 5. Entities → characters.\n  text = decodeEntities(text);\n\n  // 6. Normalize whitespace: trim each line, drop blank runs to a single\n  //    blank line (a paragraph separator the recursive splitter honors).\n  text = text\n    .replace(/[^\\S\\n]+/g, \" \")\n    .replace(/[ \\t]*\\n[ \\t]*/g, \"\\n\")\n    .replace(/\\n{3,}/g, \"\\n\\n\")\n    .trim();\n\n  return text;\n}\n\n/**\n * Load an HTML string into a single {@link RagDocument} of readable text.\n * Scripts, styles, and other non-prose elements are dropped content-and-all,\n * block tags become line breaks (so paragraph structure survives for the\n * splitter), remaining tags are stripped, and HTML entities are decoded — a\n * lightweight regex pass, no heavy DOM dependency.\n *\n * The document's `metadata.title` is set from the page's `<title>` (unless\n * the caller overrode it), and `metadata.loader` is `\"html\"`. The output is\n * the exact shape `index()` consumes.\n *\n * @example\n * const kb = ai.rag({ embedder, store });\n * await kb.index(loadHtml(rawHtmlString, { id: \"landing-page\" }));\n *\n * @param html - The raw HTML markup.\n * @param options - Shared `id` / `metadata` / `tags` ({@link LoadHtmlOptions}).\n * @returns A {@link RagLoaderResult} (one document) ready for `rag.index()`.\n */\nexport function loadHtml(\n  html: string,\n  options: LoadHtmlOptions = {},\n): RagLoaderResult {\n  const id = options.id ?? DEFAULT_ID;\n  const title = extractTitle(html);\n  const text = htmlToText(html);\n\n  // An all-markup / empty page strips to nothing; emit no document so\n  // index() never receives a no-op record (matches loadText's behavior).\n  if (text.length === 0) {\n    return [];\n  }\n\n  // Derived keys (source, loader, title) sit UNDER the caller's metadata so\n  // an explicit override always wins.\n  const doc: RagDocument = {\n    id,\n    text,\n    metadata: {\n      source: id,\n      loader: \"html\",\n      ...(title !== undefined ? { title } : {}),\n      ...options.metadata,\n    },\n    tags: options.tags,\n  };\n\n  return [doc];\n}\n\n/** Internal — exported for the web loader so it shares the exact strip pass. */\nexport { htmlToText, extractTitle };\n"],"mappings":";;AAIA,MAAM,aAAa;;;;;;;AAQnB,MAAM,oBAAoB;CACxB;CACA;CACA;CACA;CACA;CACA;AACF;;;;;;;AAQA,MAAM,aACJ;;AAGF,MAAM,iBAAyC;CAC7C,KAAK;CACL,IAAI;CACJ,IAAI;CACJ,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,KAAK;CACL,OAAO;CACP,QAAQ;CACR,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,OAAO;CACP,QAAQ;CACR,MAAM;AACR;;;;;;AAOA,SAAS,eAAe,MAAsB;CAC5C,OAAO,KAAK,QAAQ,sCAAsC,OAAO,SAAiB;EAChF,IAAI,KAAK,OAAO,KAAK;GACnB,MAAM,YACJ,KAAK,OAAO,OAAO,KAAK,OAAO,MAC3B,OAAO,SAAS,KAAK,MAAM,CAAC,GAAG,EAAE,IACjC,OAAO,SAAS,KAAK,MAAM,CAAC,GAAG,EAAE;GAEvC,IAAI,OAAO,MAAM,SAAS,KAAK,YAAY,KAAK,YAAY,SAC1D,OAAO;GAGT,IAAI;IACF,OAAO,OAAO,cAAc,SAAS;GACvC,QAAQ;IACN,OAAO;GACT;EACF;EAIA,OAFc,eAAe,KAAK,YAAY,MAE9B;CAClB,CAAC;AACH;;;;;AAMA,SAAS,aAAa,MAAkC;CACtD,MAAM,QAAQ,mCAAmC,KAAK,IAAI;CAE1D,IAAI,CAAC,OACH;CAGF,MAAM,QAAQ,eAAe,MAAM,EAAE,CAAC,CAAC,QAAQ,QAAQ,GAAG,CAAC,CAAC,KAAK;CAEjE,OAAO,MAAM,SAAS,IAAI,QAAQ;AACpC;;;;;;;;;AAUA,SAAS,WAAW,MAAsB;CACxC,IAAI,OAAO;CAGX,OAAO,KAAK,QAAQ,oBAAoB,GAAG;CAG3C,KAAK,MAAM,OAAO,mBAAmB;EACnC,MAAM,UAAU,IAAI,OAAO,IAAI,IAAI,yBAAyB,IAAI,IAAI,IAAI;EACxE,OAAO,KAAK,QAAQ,SAAS,GAAG;EAEhC,OAAO,KAAK,QAAQ,IAAI,OAAO,QAAQ,IAAI,YAAY,IAAI,GAAG,GAAG;CACnE;CAGA,OAAO,KAAK,QAAQ,YAAY,IAAI;CAGpC,OAAO,KAAK,QAAQ,YAAY,EAAE;CAGlC,OAAO,eAAe,IAAI;CAI1B,OAAO,KACJ,QAAQ,aAAa,GAAG,CAAC,CACzB,QAAQ,mBAAmB,IAAI,CAAC,CAChC,QAAQ,WAAW,MAAM,CAAC,CAC1B,KAAK;CAER,OAAO;AACT;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,SACd,MACA,UAA2B,CAAC,GACX;CACjB,MAAM,KAAK,QAAQ,MAAM;CACzB,MAAM,QAAQ,aAAa,IAAI;CAC/B,MAAM,OAAO,WAAW,IAAI;CAI5B,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAiBV,OAAO,CAAC;EAXN;EACA;EACA,UAAU;GACR,QAAQ;GACR,QAAQ;GACR,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC;GACvC,GAAG,QAAQ;EACb;EACA,MAAM,QAAQ;CAGN,CAAC;AACb"}

package/esm/rag/loaders/load-pdf.d.mts

@@ -0,0 +1,38 @@
+import { LoadPdfOptions, RagLoaderResult } from "./loader.type.mjs";
+
+//#region ../@warlock.js/ai/src/rag/loaders/load-pdf.d.ts
+/**
+ * Load a PDF's bytes into {@link RagDocument}(s) via the OPTIONAL `pdf-parse`
+ * peer. The peer is resolved lazily on the FIRST call (not at import) so
+ * importing `@warlock.js/ai` never forces it to be installed; when it is
+ * absent the curated {@link PDF_PARSE_INSTALL_INSTRUCTIONS} is thrown as a
+ * plain `Error` (a missing optional peer is an infrastructure fault, not a
+ * content problem).
+ *
+ * By default the whole PDF becomes a single document carrying
+ * `metadata.pageCount`. With `perPage: true`, each page becomes its own
+ * document (`id` suffixed `#p<n>`, `metadata.page` set) so citations stay
+ * page-precise. Document `metadata.title` comes from the PDF info
+ * dictionary's `Title` (unless overridden), and `metadata.loader` is
+ * `"pdf"`. The output is the exact shape `index()` consumes.
+ *
+ * @example
+ * import { readFile } from "node:fs/promises";
+ * const kb = ai.rag({ embedder, store });
+ * await kb.index(await loadPdf(await readFile("guide.pdf"), { id: "guide" }));
+ *
+ * @example
+ * // One document per page for page-precise citations:
+ * await kb.index(await loadPdf(bytes, { id: "manual", perPage: true }));
+ *
+ * @param input - The PDF bytes (`Buffer`, `ArrayBuffer`, or `Uint8Array`).
+ * @param options - `perPage` plus shared `id` / `metadata` / `tags`
+ *   ({@link LoadPdfOptions}).
+ * @returns A {@link RagLoaderResult} ready for `rag.index()`.
+ * @throws {Error} carrying {@link PDF_PARSE_INSTALL_INSTRUCTIONS} when the
+ *   `pdf-parse` peer is not installed.
+ */
+declare function loadPdf(input: Buffer | ArrayBuffer | Uint8Array, options?: LoadPdfOptions): Promise<RagLoaderResult>;
+//#endregion
+export { loadPdf };
+//# sourceMappingURL=load-pdf.d.mts.map

package/esm/rag/loaders/load-pdf.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-pdf.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/rag/loaders/load-pdf.ts"],"mappings":";;;;;AA8HA;;;;;;;;;;;;;;;;;;;;AAG0B;;;;;;;;;iBAHJ,OAAA,CACpB,KAAA,EAAO,MAAA,GAAS,WAAA,GAAc,UAAA,EAC9B,OAAA,GAAS,cAAA,GACR,OAAA,CAAQ,eAAA"}

package/esm/rag/loaders/load-pdf.mjs

@@ -0,0 +1,150 @@
+import { PDF_PARSE_INSTALL_INSTRUCTIONS } from "./errors.mjs";
+
+//#region ../@warlock.js/ai/src/rag/loaders/load-pdf.ts
+/** Default `id` when the caller supplies none. */
+const DEFAULT_ID = "document";
+let pdfParse;
+let isModuleExists;
+let loadingPromise;
+/**
+* Settle the lazy import of `pdf-parse` once, concurrency-safe. A bare
+* `catch` flips the flag to `false`; the curated
+* {@link PDF_PARSE_INSTALL_INSTRUCTIONS} surfaces at first
+* {@link loadPdf} call, never a raw module-resolution stack trace. Mirrors
+* the guard moderation detector's `loadOpenAi`.
+*/
+function loadPdfParse() {
+	if (isModuleExists !== void 0) return Promise.resolve();
+	if (loadingPromise) return loadingPromise;
+	loadingPromise = (async () => {
+		try {
+			const mod = await import("pdf-parse");
+			pdfParse = mod.default ?? mod;
+			isModuleExists = typeof pdfParse === "function";
+		} catch {
+			isModuleExists = false;
+		}
+	})();
+	return loadingPromise;
+}
+/**
+* Coerce a {@link RagDocument}-compatible binary input into a `Buffer` for
+* `pdf-parse`. Accepts a Node `Buffer`, an `ArrayBuffer`, or a typed array
+* (`Uint8Array`) — the shapes a file read / fetch body hands back.
+*/
+function toBuffer(input) {
+	if (Buffer.isBuffer(input)) return input;
+	if (input instanceof ArrayBuffer) return Buffer.from(input);
+	return Buffer.from(input.buffer, input.byteOffset, input.byteLength);
+}
+/**
+* Load a PDF's bytes into {@link RagDocument}(s) via the OPTIONAL `pdf-parse`
+* peer. The peer is resolved lazily on the FIRST call (not at import) so
+* importing `@warlock.js/ai` never forces it to be installed; when it is
+* absent the curated {@link PDF_PARSE_INSTALL_INSTRUCTIONS} is thrown as a
+* plain `Error` (a missing optional peer is an infrastructure fault, not a
+* content problem).
+*
+* By default the whole PDF becomes a single document carrying
+* `metadata.pageCount`. With `perPage: true`, each page becomes its own
+* document (`id` suffixed `#p<n>`, `metadata.page` set) so citations stay
+* page-precise. Document `metadata.title` comes from the PDF info
+* dictionary's `Title` (unless overridden), and `metadata.loader` is
+* `"pdf"`. The output is the exact shape `index()` consumes.
+*
+* @example
+* import { readFile } from "node:fs/promises";
+* const kb = ai.rag({ embedder, store });
+* await kb.index(await loadPdf(await readFile("guide.pdf"), { id: "guide" }));
+*
+* @example
+* // One document per page for page-precise citations:
+* await kb.index(await loadPdf(bytes, { id: "manual", perPage: true }));
+*
+* @param input - The PDF bytes (`Buffer`, `ArrayBuffer`, or `Uint8Array`).
+* @param options - `perPage` plus shared `id` / `metadata` / `tags`
+*   ({@link LoadPdfOptions}).
+* @returns A {@link RagLoaderResult} ready for `rag.index()`.
+* @throws {Error} carrying {@link PDF_PARSE_INSTALL_INSTRUCTIONS} when the
+*   `pdf-parse` peer is not installed.
+*/
+async function loadPdf(input, options = {}) {
+	await loadPdfParse();
+	if (!isModuleExists || !pdfParse) throw new Error(PDF_PARSE_INSTALL_INSTRUCTIONS);
+	const id = options.id ?? DEFAULT_ID;
+	if (options.perPage ?? false) return loadPerPage(input, id, options);
+	const parsed = await pdfParse(toBuffer(input));
+	const text = parsed.text.trim();
+	const title = parsed.info?.Title?.trim();
+	if (text.length === 0) return [];
+	return [{
+		id,
+		text,
+		metadata: {
+			source: id,
+			loader: "pdf",
+			pageCount: parsed.numpages,
+			...title ? { title } : {},
+			...options.metadata
+		},
+		tags: options.tags
+	}];
+}
+/**
+* Per-page variant: render each page separately via `pdf-parse`'s
+* `pagerender` hook, accumulating one document per non-empty page. Each
+* carries `metadata.page` (1-based) and `metadata.pageCount`, and its id is
+* the base id suffixed `#p<n>` so every page-document is distinctly
+* identified for citation.
+*
+* `pdf-parse` calls `pagerender` once per page in document order and
+* `await`s the returned string, so capturing each page's joined text content
+* here gives reliable page boundaries the concatenated `text` lacks.
+*/
+async function loadPerPage(input, id, options) {
+	const pages = [];
+	const parsed = await pdfParse(toBuffer(input), { pagerender: async (page) => {
+		const rendered = await renderPage(page);
+		pages.push(rendered);
+		return rendered;
+	} });
+	const title = parsed.info?.Title?.trim();
+	const docs = [];
+	pages.forEach((pageText, index) => {
+		const text = pageText.trim();
+		if (text.length === 0) return;
+		const pageNumber = index + 1;
+		docs.push({
+			id: `${id}#p${pageNumber}`,
+			text,
+			metadata: {
+				source: id,
+				loader: "pdf",
+				page: pageNumber,
+				pageCount: parsed.numpages,
+				...title ? { title } : {},
+				...options.metadata
+			},
+			tags: options.tags
+		});
+	});
+	return docs;
+}
+/**
+* Join a single page's text-layer items in reading order, inserting a space
+* between items so adjacent words do not run together. Mirrors the essence
+* of `pdf-parse`'s default renderer without depending on its internals, so
+* the per-page hook stays stable across `pdf-parse` versions. A page with no
+* text layer (scanned image) renders to an empty string and is dropped.
+*/
+async function renderPage(page) {
+	if (typeof page?.getTextContent !== "function") return "";
+	return (await page.getTextContent({
+		normalizeWhitespace: true,
+		disableCombineTextItems: false
+	})).items.map((item) => item.str).join(" ").replace(/\s+/g, " ").trim();
+}
+
+//#endregion
+export { loadPdf };
+//# sourceMappingURL=load-pdf.mjs.map