diff --git a/packages/core/README.md b/packages/core/README.md index 4e7f37feaa..567ca05e8a 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -106,6 +106,7 @@ export default defineFlow({ **Helper factories (`helper.*`):** - `helper.summarizer(config)` — Generator factory for brief, detailed, or executive summaries with optional focus `objectives` and a default `{ summary, keyPoints? }` output contract +- `helper.combiner(config)` — Handler factory for deterministic artifact merging via concatenation, deduplication, and structural normalization with default `{ combined, mergeNotes? }` output - `helper.intentClassifier(config)` — Generator factory for bounded intent classification with required category descriptions and default `{ category, confidence, reasoning? }` output contract - `helper.memoryExtractor(config)` — Generator factory for stateless durable-memory extraction with a default `{ memories: Array<{ type, content, confidence?, source? }> }` output contract (`type` ∈ `fact | preference | constraint | decision`) diff --git a/packages/core/src/helpers/combiner.ts b/packages/core/src/helpers/combiner.ts new file mode 100644 index 0000000000..152244116e --- /dev/null +++ b/packages/core/src/helpers/combiner.ts @@ -0,0 +1,161 @@ +import { z, type ZodTypeAny } from "zod"; +import { handler } from "../blocks"; + +export const combinerOutputSchema = z.object({ + combined: z.unknown(), + mergeNotes: z.array(z.string()).optional() +}); + +const combinerInputSchema = z.union([ + z.array(z.unknown()), + z.object({ + artifacts: z.array(z.unknown()) + }) +]); + +type MergeContext = { + notes: string[]; +}; + +export interface CombinerConfig< + TOutputSchema extends ZodTypeAny = typeof combinerOutputSchema +> { + name: string; + outputSchema?: TOutputSchema; +} + +function isPlainObject(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +function stableSerialize(value: unknown): string { + if (Array.isArray(value)) { + return `[${value.map((entry) => stableSerialize(entry)).join(",")}]`; + } + + if (isPlainObject(value)) { + return `{${Object.keys(value) + .sort() + .map((key) => `${JSON.stringify(key)}:${stableSerialize(value[key])}`) + .join(",")}}`; + } + + return JSON.stringify(value); +} + +function dedupe(values: unknown[]): unknown[] { + const seen = new Set(); + const result: unknown[] = []; + + for (const value of values) { + const signature = stableSerialize(value); + if (seen.has(signature)) { + continue; + } + + seen.add(signature); + result.push(value); + } + + return result; +} + +function mergeArrays(current: unknown[], next: unknown[], ctx: MergeContext, path: string): unknown[] { + const merged = dedupe([...current, ...next]); + + if (merged.length < current.length + next.length) { + ctx.notes.push(`${path}: deduplicated array entries during merge.`); + } + + return merged; +} + +function mergeValues(current: unknown, next: unknown, ctx: MergeContext, path: string): unknown { + if (Array.isArray(current) && Array.isArray(next)) { + return mergeArrays(current, next, ctx, path); + } + + if (isPlainObject(current) && isPlainObject(next)) { + return mergeObjects(current, next, ctx, path); + } + + if (stableSerialize(current) !== stableSerialize(next)) { + ctx.notes.push(`${path}: conflicting values resolved by taking the later artifact.`); + } + + return next; +} + +function mergeObjects( + current: Record, + next: Record, + ctx: MergeContext, + path: string +): Record { + const merged: Record = { ...current }; + + for (const key of Object.keys(next)) { + const nextPath = path === "combined" ? `combined.${key}` : `${path}.${key}`; + + if (key in merged) { + merged[key] = mergeValues(merged[key], next[key], ctx, nextPath); + continue; + } + + merged[key] = next[key]; + } + + return merged; +} + +function normalizeInput(input: z.infer): unknown[] { + return Array.isArray(input) ? input : input.artifacts; +} + +function combineArtifacts(artifacts: unknown[]): { combined: unknown; mergeNotes?: string[] } { + const ctx: MergeContext = { notes: [] }; + + if (artifacts.length === 0) { + return { combined: [], mergeNotes: ["No artifacts provided; returned an empty combined array."] }; + } + + if (artifacts.every((artifact) => Array.isArray(artifact))) { + return { + combined: mergeArrays([], artifacts.flat(), ctx, "combined"), + mergeNotes: ctx.notes.length > 0 ? ctx.notes : undefined + }; + } + + if (artifacts.every((artifact) => isPlainObject(artifact))) { + const combined = artifacts.reduce>( + (accumulator, artifact) => mergeObjects(accumulator, artifact, ctx, "combined"), + {} + ); + + return { + combined, + mergeNotes: ctx.notes.length > 0 ? ctx.notes : undefined + }; + } + + return { + combined: dedupe(artifacts), + mergeNotes: [ + "Mixed artifact types detected; normalized by preserving artifact order and deduplicating exact matches." + ] + }; +} + +/** + * Factory that returns a handler block for deterministic artifact combination. + */ +export function combiner< + TOutputSchema extends ZodTypeAny = typeof combinerOutputSchema +>(config: CombinerConfig) { + return handler({ + name: config.name, + inputSchema: combinerInputSchema, + outputSchema: config.outputSchema ?? combinerOutputSchema, + execute: (input) => combineArtifacts(normalizeInput(input)) + }); +} diff --git a/packages/core/src/helpers/index.ts b/packages/core/src/helpers/index.ts index ab5df9d7e6..db0cb77d1e 100644 --- a/packages/core/src/helpers/index.ts +++ b/packages/core/src/helpers/index.ts @@ -1,17 +1,28 @@ +export { + combiner, + combinerOutputSchema +} from "./combiner"; + +export type { + CombinerConfig +} from "./combiner"; + export { memoryCandidateSchema, memoryExtractor, memoryExtractorOutputSchema, memoryExtractorTypeSchema } from "./memoryExtractor"; + +export type { + MemoryExtractorConfig +} from "./memoryExtractor"; + export { summarizer, summarizerOutputSchema } from "./summarizer"; -export type { - MemoryExtractorConfig -} from "./memoryExtractor"; export type { SummarizerConfig, SummarizerGranularity diff --git a/packages/core/test/combiner.test.ts b/packages/core/test/combiner.test.ts new file mode 100644 index 0000000000..f42e73b633 --- /dev/null +++ b/packages/core/test/combiner.test.ts @@ -0,0 +1,144 @@ +import { describe, expect, it } from "vitest"; +import { z } from "zod"; +import { helper, sequencer } from "../src"; +import { createMockContext } from "./helpers"; + +describe("helper.combiner", () => { + it("returns a handler block definition", () => { + const block = helper.combiner({ name: "merge-results" }); + + expect(block.kind).toBe("handler"); + expect(block.name).toBe("merge-results"); + }); + + it("merges multiple objects with deterministic rules", async () => { + const block = helper.combiner({ name: "object-merge" }); + + await expect( + block.run( + [ + { + topic: "alpha", + tags: ["a", "shared"], + metadata: { score: 0.4, owner: "team-a" } + }, + { + tags: ["shared", "b"], + metadata: { score: 0.9 }, + summary: "done" + } + ], + createMockContext() + ) + ).resolves.toEqual({ + combined: { + topic: "alpha", + tags: ["a", "shared", "b"], + metadata: { score: 0.9, owner: "team-a" }, + summary: "done" + }, + mergeNotes: [ + "combined.tags: deduplicated array entries during merge.", + "combined.metadata.score: conflicting values resolved by taking the later artifact." + ] + }); + }); + + it("concatenates and deduplicates top-level arrays", async () => { + const block = helper.combiner({ name: "array-merge" }); + + await expect( + block.run( + [ + ["a", "b", "shared"], + ["shared", "c"], + ["c", "d"] + ], + createMockContext() + ) + ).resolves.toEqual({ + combined: ["a", "b", "shared", "c", "d"], + mergeNotes: ["combined: deduplicated array entries during merge."] + }); + }); + + it("normalizes mixed input artifact types", async () => { + const block = helper.combiner({ name: "mixed-merge" }); + + await expect( + block.run( + { + artifacts: [ + { id: 1 }, + "note", + { id: 1 }, + ["a"], + "note" + ] + }, + createMockContext() + ) + ).resolves.toEqual({ + combined: [{ id: 1 }, "note", ["a"]], + mergeNotes: [ + "Mixed artifact types detected; normalized by preserving artifact order and deduplicating exact matches." + ] + }); + }); + + it("uses default output schema and supports override", async () => { + const defaultBlock = helper.combiner({ name: "default-schema" }); + const customBlock = helper.combiner({ + name: "custom-schema", + outputSchema: z.object({ + combined: z.object({ title: z.string() }), + mergeNotes: z.array(z.string()).optional() + }) + }); + + await expect(defaultBlock.run([], createMockContext())).resolves.toEqual({ + combined: [], + mergeNotes: ["No artifacts provided; returned an empty combined array."] + }); + + await expect( + customBlock.run([{ title: "first" }, { title: "second" }], createMockContext()) + ).resolves.toEqual({ + combined: { title: "second" }, + mergeNotes: ["combined.title: conflicting values resolved by taking the later artifact."] + }); + }); + + it("is composable inside sequencers", async () => { + const combine = helper.combiner({ name: "combine-in-sequencer" }); + + const chain = sequencer({ + name: "combine-chain", + inputSchema: z.object({ + primary: z.object({ + tags: z.array(z.string()) + }), + secondary: z.object({ + tags: z.array(z.string()) + }) + }) + }) + .map((input) => [input.primary, input.secondary]) + .then(combine); + + await expect( + chain.run( + { + primary: { tags: ["a", "shared"] }, + secondary: { tags: ["shared", "b"] } + }, + createMockContext() + ) + ).resolves.toEqual({ + combined: { + tags: ["a", "shared", "b"] + }, + mergeNotes: ["combined.tags: deduplicated array entries during merge."] + }); + }); +});