Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions packages/core/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`)

Expand Down
161 changes: 161 additions & 0 deletions packages/core/src/helpers/combiner.ts
Original file line number Diff line number Diff line change
@@ -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<string, unknown> {
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<string>();
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<string, unknown>,
next: Record<string, unknown>,
ctx: MergeContext,
path: string
): Record<string, unknown> {
const merged: Record<string, unknown> = { ...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<typeof combinerInputSchema>): 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<Record<string, unknown>>(
(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<TOutputSchema>) {
return handler({
name: config.name,
inputSchema: combinerInputSchema,
outputSchema: config.outputSchema ?? combinerOutputSchema,
execute: (input) => combineArtifacts(normalizeInput(input))
});
}
17 changes: 14 additions & 3 deletions packages/core/src/helpers/index.ts
Original file line number Diff line number Diff line change
@@ -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
Expand Down
144 changes: 144 additions & 0 deletions packages/core/test/combiner.test.ts
Original file line number Diff line number Diff line change
@@ -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."]
});
});
});