@trazum/core 1.8.0

package/dist/reorder.js

@@ -0,0 +1,215 @@
+import { BACKWARD_REFERENCES_BY_LANGUAGE, UNCOVERED_SCRIPTS } from './phrases.js';
+import { segment } from './segment.js';
+import { estimateTokens } from './tokenizer.js';
+/**
+ * Finds the offset of the first template placeholder.
+ *
+ * Uses the same segmentation as everything else, so "placeholder" means exactly
+ * what the protection pass means by it — there is no second definition to drift.
+ */
+function firstPlaceholderOffset(prompt) {
+    let offset = 0;
+    for (const seg of segment(prompt)) {
+        if (seg.kind === 'protected' && seg.protection === 'placeholder')
+            return offset;
+        offset += seg.text.length;
+    }
+    return null;
+}
+/** Blank-line separated blocks, with their original separators preserved. */
+function toBlocks(text) {
+    // Splitting on a blank line and keeping the delimiter means rejoining cannot
+    // silently normalise somebody's spacing.
+    //
+    // Written as a line scan rather than the `split(/(?<=\n)(?=\s*\n)/)` it
+    // replaces. That regex reads better and is quadratic in the length of a run
+    // of blank lines, because the lookahead re-consumes the whole run at every
+    // position in it: 3.3 seconds on 60 KB of newlines, in a library reachable
+    // over HTTP. Here every character is visited once.
+    const blocks = [];
+    let start = 0;
+    let i = 0;
+    while (i < text.length) {
+        const nl = text.indexOf('\n', i);
+        const end = nl === -1 ? text.length : nl + 1;
+        // A blank line opens a block, and travels with the block it precedes.
+        if (i > start && text.slice(i, end).trim() === '') {
+            blocks.push(text.slice(start, i));
+            start = i;
+        }
+        i = end;
+    }
+    if (start < text.length)
+        blocks.push(text.slice(start));
+    return blocks;
+}
+const hasPlaceholder = (text) => segment(text).some((s) => s.kind === 'protected' && s.protection === 'placeholder');
+/**
+ * The backward reference in a block, if any.
+ *
+ * Lowercased on both sides because a prompt written in title case is still a
+ * prompt. Word-boundary matched for languages written with spaces, so
+ * "aboveboard" does not pin a block — and *not* for Japanese and Chinese, where
+ * the neighbouring character is always a letter and a boundary-matched phrase
+ * could never fire.
+ *
+ * Every language's list runs against every prompt. Detecting the language first
+ * would be one more thing to get wrong, and the cost of testing a French prompt
+ * against German phrases is a saving not taken, which is the direction this
+ * module errs in on purpose.
+ */
+function backwardReference(text) {
+    const haystack = text.toLowerCase();
+    const boundary = (c) => c === undefined || !/[\p{L}\p{N}]/u.test(c);
+    for (const set of Object.values(BACKWARD_REFERENCES_BY_LANGUAGE)) {
+        for (const phrase of set.phrases) {
+            const index = haystack.indexOf(phrase);
+            if (index === -1)
+                continue;
+            if (!set.wordBoundaries)
+                return phrase;
+            if (boundary(haystack[index - 1]) && boundary(haystack[index + phrase.length])) {
+                return phrase;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * A script the phrase lists do not cover, if the prompt is written in one.
+ *
+ * The fourth refusal, and the one that exists because of what the other three
+ * were quietly not doing. Every safety argument in this module rests on
+ * recognising a backward reference, and for a Russian, Arabic or Korean prompt
+ * there was nothing to recognise it with — so `--reorder` rearranged freely and
+ * called it a saving. Refusing is the honest answer until the list exists.
+ *
+ * Deliberately triggered by a *single* character rather than by the prompt being
+ * mostly that script. A prompt in English with one Cyrillic instruction in it is
+ * exactly the case where a missed reference does damage, and the cost of being
+ * wrong here is a saving the author can still take by hand.
+ */
+function uncoveredScript(text) {
+    return UNCOVERED_SCRIPTS.find((script) => script.pattern.test(text))?.name;
+}
+/**
+ * Rearranges a prompt so its stable instructions sit in the cacheable prefix.
+ *
+ * Returns the original text unchanged when nothing can safely move, and always
+ * reports what it declined and why — a saving Trazum silently chose not to take
+ * is one the author cannot evaluate.
+ */
+export function reorderForCache(prompt, options = {}) {
+    const count = options.count ?? estimateTokens;
+    const minPrefixTokens = options.minPrefixTokens ?? 0;
+    const unchanged = () => {
+        const prefix = firstPlaceholderOffset(prompt);
+        const prefixTokens = prefix === null ? count(prompt) : count(prompt.slice(0, prefix));
+        return {
+            text: prompt,
+            moved: [],
+            declined: [],
+            tokensMoved: 0,
+            prefixTokensBefore: prefixTokens,
+            prefixTokensAfter: prefixTokens,
+        };
+    };
+    const offset = firstPlaceholderOffset(prompt);
+    if (offset === null)
+        return unchanged();
+    // Before anything else: if the prompt is written in a script whose backward
+    // references this module cannot recognise, none of the refusals below mean
+    // anything. Nothing moves, and the report says which script and why.
+    const script = uncoveredScript(prompt);
+    if (script !== undefined) {
+        return {
+            ...unchanged(),
+            declined: [{ text: prompt.slice(offset), reason: 'uncovered-script', script }],
+        };
+    }
+    // The placeholder's own line stays with the content after it: "Customer
+    // message: {{message}}" is one unit, and splitting it would strand the label.
+    const lineStart = prompt.lastIndexOf('\n', offset) + 1;
+    const head = prompt.slice(0, lineStart);
+    const rest = prompt.slice(lineStart);
+    const blocks = toBlocks(rest);
+    const prefixTokensBefore = count(head);
+    const moved = [];
+    const declined = [];
+    const stay = [];
+    let pinned = false;
+    for (const [index, block] of blocks.entries()) {
+        // The first block holds the placeholder itself; it can never move.
+        if (index === 0 || hasPlaceholder(block)) {
+            stay.push(block);
+            continue;
+        }
+        if (pinned) {
+            // Everything after a pinned block stays, because moving it would change
+            // its order relative to the block that had to stay.
+            stay.push(block);
+            if (block.trim() !== '')
+                declined.push({ text: block, reason: 'after-pinned' });
+            continue;
+        }
+        const phrase = backwardReference(block);
+        if (phrase !== undefined) {
+            pinned = true;
+            stay.push(block);
+            declined.push({ text: block, reason: 'backward-reference', phrase });
+            continue;
+        }
+        if (block.trim() === '') {
+            stay.push(block);
+            continue;
+        }
+        moved.push({ text: block, tokens: count(block) });
+    }
+    const tokensMoved = moved.reduce((sum, b) => sum + b.tokens, 0);
+    // Against the prefix this would produce, not against the amount moved. A head
+    // that already clears the minimum gains from any block that joins it.
+    if (moved.length === 0 || prefixTokensBefore + tokensMoved < minPrefixTokens) {
+        // Report the refusals even when nothing moved: "no saving here" and "there
+        // was a saving and it was not safe to take" are different answers.
+        return { ...unchanged(), declined };
+    }
+    // Normalise the seams rather than concatenating raw slices: a block carries the
+    // blank line that preceded it, so joining head + block + rest naively leaves a
+    // three-newline gap where two belong.
+    //
+    // In the author's own line ending, though. Rejoining a CRLF prompt with bare
+    // newlines would rewrite every seam in a file nobody asked to reformat — and
+    // where the whole point is a byte-for-byte cache prefix, a changed byte is a
+    // changed price.
+    const gap = prompt.includes('\r\n') ? '\r\n\r\n' : '\n\n';
+    const movedText = moved
+        // `^\s*\n+` drops the blank-line separator the block carries without taking
+        // the first line's own indentation with it, which `trimStart` would. It is
+        // anchored, so it is tried from one position and stays linear.
+        .map((b) => b.text.replace(/^\s*\n+/, '').trimEnd())
+        .join(gap);
+    const before = head.trimEnd();
+    const after = stay.join('').replace(/^\s*\n+/, '').trimEnd();
+    // No leading gap when the placeholder was on the very first line: there is no
+    // head for the moved blocks to sit after, and emitting one would open the
+    // prompt with a blank line.
+    const body = before === '' ? `${movedText}${gap}${after}` : `${before}${gap}${movedText}${gap}${after}`;
+    // However the prompt ended, it still ends that way. A block carries the blank
+    // line that followed it, so trimming the seams without restoring the original
+    // ending either strands a newline at the end or drops the one that was there.
+    // Collapsing runs of blank lines is the whitespace rule's job, not this one's.
+    //
+    // Via `trimEnd` rather than `/\s*$/`, which is quadratic on a prompt that
+    // holds a long whitespace run and does not end in one: 31 seconds on 200 KB,
+    // under the 400 KB the HTTP API accepts.
+    const text = `${body}${prompt.slice(prompt.trimEnd().length)}`;
+    return {
+        text,
+        moved,
+        declined,
+        tokensMoved,
+        prefixTokensBefore,
+        prefixTokensAfter: count(text.slice(0, firstPlaceholderOffset(text) ?? text.length)),
+    };
+}
+//# sourceMappingURL=reorder.js.map

package/dist/reorder.js.map

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

package/dist/review.d.ts

@@ -0,0 +1,54 @@
+import type { LlmProvider, TokenCounter } from './types.js';
+/**
+ * Semantic review of few-shot examples.
+ *
+ * The deterministic detector in `structure.ts` finds near-copies and stops
+ * there, on purpose: a paraphrase — the same lesson in different words —
+ * scores around 0.54 on word overlap, close enough to two genuinely distinct
+ * examples (~0.20) that catching it would mean flagging examples that teach
+ * different things.
+ *
+ * Deciding that "arrived quickly" and "arrived fast" demonstrate the same
+ * pattern needs a model. So this lives behind the optional LLM layer, costs a
+ * call, and is never on the path of an ordinary `optimize()`.
+ *
+ * It only ever reports. Nothing here edits a prompt, which is what lets it be
+ * relaxed about a model that answers badly: the worst outcome is a suggestion
+ * you ignore.
+ */
+export declare const EXAMPLE_REVIEW_SYSTEM_PROMPT = "You judge whether few-shot examples in a prompt teach the same thing.\n\nYou are given numbered examples. Group together any that demonstrate the same pattern \u2014 the same kind of input mapping to the same kind of output \u2014 even when they are worded completely differently. Examples that differ only in surface detail (names, numbers, dates) teach the same thing.\n\nDo NOT group examples that look similar but demonstrate different behaviour, and do NOT group an example that exists to show a boundary or edge case. When in doubt, leave an example on its own: a false grouping costs the reader more than a missed one.\n\nReturn ONLY a JSON array, no prose and no code fences. Each element is a group of two or more examples that teach the same thing:\n\n[{\"keep\": 0, \"redundant\": [2], \"reason\": \"both classify a missing delivery as shipping\"}]\n\n\"keep\" is the example worth keeping (usually the earliest), \"redundant\" lists the others, and \"reason\" is one short clause. Return [] when every example teaches something distinct.";
+export interface ExampleRedundancy {
+    /** Index of the example worth keeping. */
+    keep: number;
+    /** Indices the model considers redundant with it. */
+    redundant: number[];
+    /** The model's one-clause justification, for the reader to judge. */
+    reason: string;
+    /** Tokens held by the redundant examples. */
+    tokens: number;
+}
+export interface ExampleReview {
+    provider: string;
+    model: string;
+    /** Examples found in the prompt, in order. */
+    exampleCount: number;
+    groups: ExampleRedundancy[];
+    /** Tokens across every example marked redundant. */
+    redundantTokens: number;
+    /** Set when the model answered but nothing usable came back. */
+    unusableResponse?: string;
+}
+export interface ReviewExamplesOptions {
+    tokenCounter?: TokenCounter;
+}
+/**
+ * Asks the configured model which examples teach the same thing.
+ *
+ * Returns `null` when there is nothing to review — fewer than two examples —
+ * so the caller can skip the call rather than pay for a certain answer.
+ *
+ * Never throws on a bad answer. A provider that errors will still throw,
+ * because that is a configuration problem the caller should see.
+ */
+export declare function reviewExamples(prompt: string, provider: LlmProvider, options?: ReviewExamplesOptions): Promise<ExampleReview | null>;
+//# sourceMappingURL=review.d.ts.map

package/dist/review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../src/review.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5D;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,4BAA4B,8hCAU4I,CAAC;AAEtL,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,oDAAoD;IACpD,eAAe,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,YAAY,CAAC,EAAE,YAAY,CAAC;CAC7B;AAwDD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAmD/B"}

package/dist/review.js

@@ -0,0 +1,131 @@
+import { findExamples } from './structure.js';
+import { estimateTokens } from './tokenizer.js';
+/**
+ * Semantic review of few-shot examples.
+ *
+ * The deterministic detector in `structure.ts` finds near-copies and stops
+ * there, on purpose: a paraphrase — the same lesson in different words —
+ * scores around 0.54 on word overlap, close enough to two genuinely distinct
+ * examples (~0.20) that catching it would mean flagging examples that teach
+ * different things.
+ *
+ * Deciding that "arrived quickly" and "arrived fast" demonstrate the same
+ * pattern needs a model. So this lives behind the optional LLM layer, costs a
+ * call, and is never on the path of an ordinary `optimize()`.
+ *
+ * It only ever reports. Nothing here edits a prompt, which is what lets it be
+ * relaxed about a model that answers badly: the worst outcome is a suggestion
+ * you ignore.
+ */
+export const EXAMPLE_REVIEW_SYSTEM_PROMPT = `You judge whether few-shot examples in a prompt teach the same thing.
+
+You are given numbered examples. Group together any that demonstrate the same pattern — the same kind of input mapping to the same kind of output — even when they are worded completely differently. Examples that differ only in surface detail (names, numbers, dates) teach the same thing.
+
+Do NOT group examples that look similar but demonstrate different behaviour, and do NOT group an example that exists to show a boundary or edge case. When in doubt, leave an example on its own: a false grouping costs the reader more than a missed one.
+
+Return ONLY a JSON array, no prose and no code fences. Each element is a group of two or more examples that teach the same thing:
+
+[{"keep": 0, "redundant": [2], "reason": "both classify a missing delivery as shipping"}]
+
+"keep" is the example worth keeping (usually the earliest), "redundant" lists the others, and "reason" is one short clause. Return [] when every example teaches something distinct.`;
+/** Pulls the first JSON array out of a response, fences and prose included. */
+function extractJsonArray(raw) {
+    const trimmed = raw.trim();
+    const fenced = /^(?:```|~~~)[a-zA-Z]*\n([\s\S]*?)\n?(?:```|~~~)$/.exec(trimmed);
+    const body = fenced?.[1] ?? trimmed;
+    const start = body.indexOf('[');
+    const end = body.lastIndexOf(']');
+    if (start === -1 || end === -1 || end < start)
+        return null;
+    try {
+        return JSON.parse(body.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validates one group against the examples that actually exist.
+ *
+ * Everything the model returns is treated as a suggestion from an untrusted
+ * source: indices are range-checked, self-references dropped, duplicates
+ * collapsed, and the reason truncated. A model that answers with nonsense
+ * produces an empty review, not a crash and not a bogus saving.
+ */
+function parseGroup(value, exampleCount) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const record = value;
+    const keep = record.keep;
+    if (typeof keep !== 'number' || !Number.isInteger(keep) || keep < 0 || keep >= exampleCount) {
+        return null;
+    }
+    const rawRedundant = Array.isArray(record.redundant) ? record.redundant : [];
+    const redundant = [
+        ...new Set(rawRedundant.filter((index) => typeof index === 'number' &&
+            Number.isInteger(index) &&
+            index >= 0 &&
+            index < exampleCount &&
+            index !== keep)),
+    ].sort((a, b) => a - b);
+    if (redundant.length === 0)
+        return null;
+    const reason = typeof record.reason === 'string' ? record.reason.trim().slice(0, 160) : '';
+    return { keep, redundant, reason };
+}
+/**
+ * Asks the configured model which examples teach the same thing.
+ *
+ * Returns `null` when there is nothing to review — fewer than two examples —
+ * so the caller can skip the call rather than pay for a certain answer.
+ *
+ * Never throws on a bad answer. A provider that errors will still throw,
+ * because that is a configuration problem the caller should see.
+ */
+export async function reviewExamples(prompt, provider, options = {}) {
+    const count = options.tokenCounter ?? estimateTokens;
+    const examples = findExamples(prompt, count);
+    if (examples.length < 2)
+        return null;
+    const numbered = examples
+        .map((example, index) => `--- Example ${index} ---\n${example.text}`)
+        .join('\n\n');
+    const raw = await provider.complete({
+        system: EXAMPLE_REVIEW_SYSTEM_PROMPT,
+        user: numbered,
+    });
+    const base = {
+        provider: provider.name,
+        model: provider.model,
+        exampleCount: examples.length,
+    };
+    const parsed = extractJsonArray(raw);
+    if (!Array.isArray(parsed)) {
+        return { ...base, groups: [], redundantTokens: 0, unusableResponse: raw.trim().slice(0, 200) };
+    }
+    // An example can only be claimed once. Without this a model that returns
+    // overlapping groups would have the same tokens counted twice, and the
+    // saving would read higher than the prompt could possibly deliver.
+    const claimed = new Set();
+    const groups = [];
+    for (const entry of parsed) {
+        const group = parseGroup(entry, examples.length);
+        if (!group)
+            continue;
+        const fresh = group.redundant.filter((index) => !claimed.has(index) && index !== group.keep);
+        if (fresh.length === 0)
+            continue;
+        fresh.forEach((index) => claimed.add(index));
+        groups.push({
+            ...group,
+            redundant: fresh,
+            tokens: fresh.reduce((sum, index) => sum + examples[index].tokens, 0),
+        });
+    }
+    return {
+        ...base,
+        groups,
+        redundantTokens: groups.reduce((sum, group) => sum + group.tokens, 0),
+    };
+}
+//# sourceMappingURL=review.js.map

package/dist/review.js.map

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

package/dist/rules.d.ts

@@ -0,0 +1,5 @@
+import type { Rule } from './types.js';
+/** Every rule, in the order they must run. */
+export declare const RULES: readonly Rule[];
+export declare function getRule(id: string): Rule | undefined;
+//# sourceMappingURL=rules.d.ts.map

package/dist/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAiSvC,8CAA8C;AAC9C,eAAO,MAAM,KAAK,EAAE,SAAS,IAAI,EAgBhC,CAAC;AAEF,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAEpD"}