@aid-framework/runtime 0.0.0 → 0.1.48

package/dist/providers/fake.js

@@ -0,0 +1,181 @@
+/**
+ * A deterministic provider for tests.
+ *
+ * This is not a mock in the "returns a canned value" sense. It is a *seeded
+ * simulation* of a probabilistic model: given the same seed and the same request it
+ * produces byte-identical output, but it deliberately answers correctly only a
+ * configurable fraction of the time. That is the whole point -- it lets the eval gate
+ * be tested against genuine non-determinism, so a test can prove that run-to-run
+ * variation is tolerated while a real regression is caught.
+ *
+ * ## One documented divergence from the Python runtime
+ *
+ * The reference implementation draws its accuracy sample from
+ * `random.Random("seed:index:prompt").random()`, which is CPython's Mersenne Twister
+ * seeded from a string. That seeding is a CPython implementation detail with no
+ * portable equivalent, so this runtime draws from a SHA-256 hash of the same triple
+ * instead. The properties the gate depends on are preserved:
+ *
+ * - the draw is a pure function of `(seed, call index, prompt)`, so a recorded
+ *   baseline reproduces exactly;
+ * - the call index is part of the input, so re-running a dataset re-draws every case
+ *   and an N-run sample genuinely varies.
+ *
+ * What is *not* claimed is that the two runtimes draw the same number. They do not,
+ * and no test in either runtime should assert that they do.
+ */
+import { ProviderError } from '../errors.js';
+import { digestPrefix, sha256Hex } from '../internal/json.js';
+import { CompletionResponse, TokenUsage, ToolCall, } from '../types.js';
+/**
+ * One scripted model turn: some text, some tool calls, or both.
+ *
+ * `calls` is `(name, arguments)` pairs rather than `ToolCall` because a script should not
+ * have to invent unique call ids. The provider derives `call_<turn>_<position>` from the
+ * turn's position in the script, so two turns calling the same tool still produce
+ * distinguishable ids.
+ */
+export class ScriptedTurn {
+    text;
+    calls;
+    constructor(text, calls) {
+        this.text = text;
+        this.calls = calls;
+    }
+    static answer(text) {
+        return new ScriptedTurn(text, []);
+    }
+    static tool(name, arguments_ = {}) {
+        return new ScriptedTurn('', [[name, { ...arguments_ }]]);
+    }
+    static tools(...calls) {
+        return new ScriptedTurn('', calls);
+    }
+    get finishReason() {
+        return this.calls.length > 0 ? 'tool-calls' : 'stop';
+    }
+    toolCalls(turn) {
+        return this.calls.map(([name, arguments_], position) => new ToolCall({ id: `call_${turn}_${position}`, name, arguments: { ...arguments_ } }));
+    }
+}
+/** Deterministic, seedable, and optionally inaccurate. */
+export class FakeProvider {
+    _responder;
+    _answers;
+    _script;
+    _accuracy;
+    _seed;
+    _name;
+    _failures;
+    _tokensPerChar;
+    _overheadTokens;
+    _served = 0;
+    /** Every request this provider has seen, in order. */
+    calls = [];
+    constructor(options = {}) {
+        const accuracy = options.accuracy ?? 1.0;
+        if (!(accuracy >= 0.0 && accuracy <= 1.0)) {
+            throw new RangeError('accuracy must be between 0.0 and 1.0');
+        }
+        this._responder = options.responder;
+        this._answers = new Map(Object.entries(options.answers ?? {}));
+        // A script is consumed one turn per call, then the provider behaves normally -- so a
+        // scripted loop that overshoots its script is visible rather than silently answered.
+        this._script = [...(options.script ?? [])];
+        this._accuracy = accuracy;
+        this._seed = options.seed ?? 0;
+        this._name = options.name ?? 'fake';
+        this._failures = [...(options.failWith ?? [])];
+        this._tokensPerChar = options.tokensPerChar ?? 0.25;
+        this._overheadTokens = options.overheadTokens ?? 8;
+    }
+    get name() {
+        return this._name;
+    }
+    get capabilities() {
+        return new Set(['tool-calling', 'structured-output', 'long-context']);
+    }
+    async complete(request, model) {
+        this.calls.push(request);
+        const index = this.calls.length - 1;
+        const failure = this._failures.shift();
+        if (failure !== undefined)
+            throw new ProviderError(failure);
+        const inputTokens = this.countTokens(promptText(request));
+        const turn = this._served < this._script.length ? this._script[this._served] : undefined;
+        if (turn !== undefined) {
+            this._served += 1;
+            return new CompletionResponse({
+                text: turn.text,
+                model: model.name,
+                provider: this._name,
+                usage: new TokenUsage({
+                    inputTokens,
+                    outputTokens: this.countTokens(turn.text),
+                }),
+                toolCalls: turn.toolCalls(this._served - 1),
+                finishReason: turn.finishReason,
+            });
+        }
+        const text = this.respondTo(request, index);
+        return new CompletionResponse({
+            text,
+            model: model.name,
+            provider: this._name,
+            usage: new TokenUsage({
+                inputTokens,
+                outputTokens: this.countTokens(text),
+            }),
+            finishReason: 'stop',
+        });
+    }
+    async close() {
+        return;
+    }
+    respondTo(request, index) {
+        if (this._responder !== undefined)
+            return this._responder(request, index);
+        const prompt = promptText(request);
+        let ideal = this._answers.get(prompt);
+        if (ideal === undefined) {
+            for (const [key, value] of this._answers) {
+                if (prompt.includes(key)) {
+                    ideal = value;
+                    break;
+                }
+            }
+        }
+        if (ideal === undefined) {
+            // No expectation to hit, so accuracy does not apply: echo deterministically.
+            return `echo:${digestPrefix(`${this._seed}:${prompt}`)}`;
+        }
+        if (this._accuracy >= 1.0)
+            return ideal;
+        if (this.draw(prompt, index) < this._accuracy)
+            return ideal;
+        // A wrong answer must still be deterministic and visibly wrong.
+        return `${ideal}#${digestPrefix(`${this._seed + index}:${prompt}`)}`;
+    }
+    /**
+     * A stable pseudo-random draw in `[0, 1)` for this `(seed, index, prompt)` triple.
+     *
+     * See the module comment: this is a hash, not CPython's PRNG, and the divergence is
+     * deliberate and documented.
+     */
+    draw(prompt, index) {
+        const hex = sha256Hex(`${this._seed}:${index}:${prompt}`).slice(0, 16);
+        return Number(BigInt(`0x${hex}`)) / 2 ** 64;
+    }
+    countTokens(text) {
+        return Math.trunc(text.length * this._tokensPerChar) + this._overheadTokens;
+    }
+}
+/** The concatenated message text, which is what a provider keys its answers on. */
+export function promptText(request) {
+    return request.messages.map((message) => message.content).join('\n');
+}
+/** Convenience factory used by the eval-gate tests. */
+export function withAccuracy(accuracy, options = {}) {
+    return new FakeProvider({ accuracy, seed: options.seed ?? 0 });
+}
+//# sourceMappingURL=fake.js.map

package/dist/providers/fake.js.map

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

package/dist/providers/http.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A provider for any OpenAI-compatible chat-completions endpoint.
+ *
+ * One adapter covers OpenAI, Azure OpenAI, vLLM, Ollama, Together, Groq and most
+ * others, because they all speak the same request and response shape. Providers that
+ * diverge are handled by writing a new {@link Provider}, not by adding flags here.
+ *
+ * Note the capability list: `long-context` is not claimed. Whether a given deployment
+ * has a large window is a property of the deployment, not of the wire protocol, so
+ * claiming it here would let the gateway route a request that the endpoint then
+ * rejects.
+ */
+import { type Capability, type CompletionRequest, CompletionResponse, type ModelSpec } from '../types.js';
+import type { Provider } from './base.js';
+/** The public OpenAI endpoint, used when no base URL is configured. */
+export declare const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+export type FetchLike = (url: string, init: {
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+}>;
+export interface OpenAICompatibleOptions {
+    readonly baseUrl?: string;
+    readonly apiKey?: string;
+    readonly name?: string;
+    readonly timeoutSeconds?: number;
+    readonly maxAttempts?: number;
+    readonly backoffSeconds?: number;
+    /** Supplied by tests, or to share a connection pool. */
+    readonly fetchImpl?: FetchLike;
+    readonly extraHeaders?: Readonly<Record<string, string>>;
+}
+/** Talks to an OpenAI-compatible `/chat/completions` endpoint. */
+export declare class OpenAICompatibleProvider implements Provider {
+    private readonly _baseUrl;
+    private readonly _apiKey;
+    private readonly _name;
+    private readonly _timeoutSeconds;
+    private readonly _maxAttempts;
+    private readonly _backoffSeconds;
+    private readonly _fetch;
+    private readonly _extraHeaders;
+    private _closed;
+    constructor(options?: OpenAICompatibleOptions);
+    get name(): string;
+    get capabilities(): ReadonlySet<Capability>;
+    complete(request: CompletionRequest, model: ModelSpec): Promise<CompletionResponse>;
+    close(): Promise<void>;
+    private payload;
+    private headers;
+    private post;
+    private parse;
+    private usage;
+    private toolCalls;
+    private finishReason;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/providers/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/providers/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,kBAAkB,EAElB,KAAK,SAAS,EAGf,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAc5D,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IACJ,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B,KACE,OAAO,CAAC;IACX,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC,CAAC;AAEH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC1D;AAaD,kEAAkE;AAClE,qBAAa,wBAAyB,YAAW,QAAQ;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,OAAO,CAAC,OAAO,CAAS;IAExB,YAAY,OAAO,GAAE,uBAA4B,EAiBhD;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,YAAY,IAAI,WAAW,CAAC,UAAU,CAAC,CAE1C;IAEK,QAAQ,CAAC,OAAO,EAAE,iBAAiB,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAIxF;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;IAED,OAAO,CAAC,OAAO;IAkCf,OAAO,CAAC,OAAO;YASD,IAAI;IAsClB,OAAO,CAAC,KAAK;IA8Bb,OAAO,CAAC,KAAK;IAUb,OAAO,CAAC,SAAS;IA2BjB,OAAO,CAAC,YAAY;CAIrB"}

package/dist/providers/http.js

@@ -0,0 +1,245 @@
+/**
+ * A provider for any OpenAI-compatible chat-completions endpoint.
+ *
+ * One adapter covers OpenAI, Azure OpenAI, vLLM, Ollama, Together, Groq and most
+ * others, because they all speak the same request and response shape. Providers that
+ * diverge are handled by writing a new {@link Provider}, not by adding flags here.
+ *
+ * Note the capability list: `long-context` is not claimed. Whether a given deployment
+ * has a large window is a property of the deployment, not of the wire protocol, so
+ * claiming it here would let the gateway route a request that the endpoint then
+ * rejects.
+ */
+import { ProviderError, ProviderResponseError } from '../errors.js';
+import { stripTrailingSlashes } from '../internal/text.js';
+import { CompletionResponse, TokenUsage, ToolCall, } from '../types.js';
+/** The public OpenAI endpoint, used when no base URL is configured. */
+export const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+/** Statuses worth retrying: the request was well-formed and may succeed unchanged. */
+const RETRYABLE_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
+/** The wire names a `finish_reason` can take, mapped to the runtime's vocabulary. */
+const FINISH_REASONS = {
+    stop: 'stop',
+    length: 'length',
+    tool_calls: 'tool-calls',
+    content_filter: 'content-filter',
+    error: 'error',
+};
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function delay(seconds) {
+    if (seconds <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        setTimeout(resolve, seconds * 1000);
+    });
+}
+/** Talks to an OpenAI-compatible `/chat/completions` endpoint. */
+export class OpenAICompatibleProvider {
+    _baseUrl;
+    _apiKey;
+    _name;
+    _timeoutSeconds;
+    _maxAttempts;
+    _backoffSeconds;
+    _fetch;
+    _extraHeaders;
+    _closed = false;
+    constructor(options = {}) {
+        const baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL);
+        if (!/^https?:\/\/[^/]/i.test(baseUrl)) {
+            throw new RangeError(`base_url must be an absolute http(s) URL, got ${JSON.stringify(baseUrl)}`);
+        }
+        const maxAttempts = options.maxAttempts ?? 3;
+        if (maxAttempts < 1)
+            throw new RangeError('max_attempts must be at least 1');
+        this._baseUrl = baseUrl;
+        this._apiKey = options.apiKey;
+        this._name = options.name ?? 'openai-compatible';
+        this._timeoutSeconds = options.timeoutSeconds ?? 60;
+        this._maxAttempts = maxAttempts;
+        this._backoffSeconds = options.backoffSeconds ?? 0.5;
+        this._fetch = options.fetchImpl ?? globalThis.fetch;
+        this._extraHeaders = options.extraHeaders ?? {};
+    }
+    get name() {
+        return this._name;
+    }
+    get capabilities() {
+        return new Set(['tool-calling', 'structured-output']);
+    }
+    async complete(request, model) {
+        if (this._closed)
+            throw new ProviderError(`${this._name} is closed`);
+        const body = await this.post(this.payload(request, model));
+        return this.parse(body, model);
+    }
+    async close() {
+        // A caller-supplied client owns its own connection pool and stays open.
+        this._closed = true;
+    }
+    payload(request, model) {
+        const payload = {
+            model: model.name,
+            messages: request.messages.map((message) => {
+                const wire = {
+                    role: message.role,
+                    content: message.content,
+                };
+                // A tool turn the provider cannot attribute to its call is unusable, and an
+                // assistant turn that asked for tools must carry those calls back or the loop
+                // replays an observation with no caller.
+                const toolCalls = message.toolCalls ?? [];
+                if (toolCalls.length > 0) {
+                    wire.tool_calls = toolCalls.map((call) => ({
+                        id: call.id,
+                        type: 'function',
+                        function: { name: call.name, arguments: JSON.stringify(call.args) },
+                    }));
+                }
+                if (message.toolCallId !== undefined)
+                    wire.tool_call_id = message.toolCallId;
+                if (message.name !== undefined)
+                    wire.name = message.name;
+                return wire;
+            }),
+        };
+        if (request.temperature !== undefined)
+            payload.temperature = request.temperature;
+        const requested = request.maxOutputTokens ?? model.maxOutputTokens;
+        payload.max_tokens = Math.min(requested, model.maxOutputTokens);
+        if (request.stop !== undefined && request.stop.length > 0)
+            payload.stop = [...request.stop];
+        if (request.tools !== undefined && request.tools.length > 0) {
+            payload.tools = request.tools.map((tool) => tool.asOpenAiTool());
+        }
+        return payload;
+    }
+    headers() {
+        const headers = {
+            'content-type': 'application/json',
+            ...this._extraHeaders,
+        };
+        if (this._apiKey !== undefined)
+            headers.authorization = `Bearer ${this._apiKey}`;
+        return headers;
+    }
+    async post(payload) {
+        const url = `${this._baseUrl}/chat/completions`;
+        let last = 'no attempt was made';
+        for (let attempt = 1; attempt <= this._maxAttempts; attempt += 1) {
+            try {
+                const response = await this._fetch(url, {
+                    method: 'POST',
+                    headers: this.headers(),
+                    body: JSON.stringify(payload),
+                    signal: AbortSignal.timeout(this._timeoutSeconds * 1000),
+                });
+                const text = await response.text();
+                if (!response.ok) {
+                    last = `${this._name} returned ${response.status}: ${text}`;
+                    if (RETRYABLE_STATUSES.has(response.status) && attempt < this._maxAttempts) {
+                        await delay(this._backoffSeconds * 2 ** (attempt - 1));
+                        continue;
+                    }
+                    throw new ProviderError(last);
+                }
+                try {
+                    return JSON.parse(text);
+                }
+                catch {
+                    throw new ProviderResponseError(`${this._name} returned a body that is not JSON`);
+                }
+            }
+            catch (error) {
+                if (error instanceof ProviderResponseError || error instanceof ProviderError)
+                    throw error;
+                last = `${this._name} request failed: ${error instanceof Error ? error.message : String(error)}`;
+                if (attempt < this._maxAttempts) {
+                    await delay(this._backoffSeconds * 2 ** (attempt - 1));
+                    continue;
+                }
+                throw new ProviderError(last);
+            }
+        }
+        throw new ProviderError(`${this._name} failed after ${this._maxAttempts} attempt(s): ${last}`);
+    }
+    parse(body, model) {
+        if (!isObject(body)) {
+            throw new ProviderResponseError(`${this._name} returned a JSON body that is not an object`);
+        }
+        const choices = body.choices;
+        if (!Array.isArray(choices) || choices.length === 0) {
+            throw new ProviderResponseError(`${this._name} returned no choices`);
+        }
+        const first = choices[0];
+        if (!isObject(first)) {
+            throw new ProviderResponseError(`${this._name} returned a malformed choice`);
+        }
+        const message = first.message;
+        if (!isObject(message)) {
+            throw new ProviderResponseError(`${this._name} returned a choice without a message`);
+        }
+        const content = message.content;
+        if (content !== null && content !== undefined && typeof content !== 'string') {
+            throw new ProviderResponseError(`${this._name} returned non-string content`);
+        }
+        return new CompletionResponse({
+            text: typeof content === 'string' ? content : '',
+            model: model.name,
+            provider: this._name,
+            usage: this.usage(message, body),
+            toolCalls: this.toolCalls(message),
+            finishReason: this.finishReason(first.finish_reason),
+        });
+    }
+    usage(message, body) {
+        const raw = isObject(body.usage) ? body.usage : isObject(message.usage) ? message.usage : {};
+        const input = raw.prompt_tokens;
+        const output = raw.completion_tokens;
+        return new TokenUsage({
+            inputTokens: typeof input === 'number' ? Math.trunc(input) : 0,
+            outputTokens: typeof output === 'number' ? Math.trunc(output) : 0,
+        });
+    }
+    toolCalls(message) {
+        const raw = message.tool_calls;
+        if (!Array.isArray(raw))
+            return undefined;
+        const calls = [];
+        for (const [index, entry] of raw.entries()) {
+            if (!isObject(entry))
+                continue;
+            const fn = entry.function;
+            if (!isObject(fn))
+                continue;
+            const name = fn.name;
+            if (typeof name !== 'string' || name.length === 0)
+                continue;
+            let args = {};
+            if (typeof fn.arguments === 'string') {
+                try {
+                    const parsed = JSON.parse(fn.arguments);
+                    if (isObject(parsed))
+                        args = parsed;
+                }
+                catch {
+                    args = {};
+                }
+            }
+            else if (isObject(fn.arguments)) {
+                args = fn.arguments;
+            }
+            const id = typeof entry.id === 'string' && entry.id.length > 0 ? entry.id : `call_${index}`;
+            calls.push(new ToolCall({ id, name, arguments: args }));
+        }
+        return calls;
+    }
+    finishReason(raw) {
+        if (typeof raw !== 'string')
+            return 'stop';
+        return FINISH_REASONS[raw] ?? 'stop';
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/providers/http.js.map

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

package/dist/retrieval/chunking.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Turning documents into deterministic, size-bounded chunks.
+ *
+ * The IR declares a strategy, a size and an overlap; it does not declare the split
+ * algorithm. This module pins one, and the pin is the spec validator's own reading
+ * of the intent: *"spec v0.1 chunks by size (fixed, recursive, code)"*. `semantic`
+ * is refused because it needs an embedding pass over the whole source at ingest --
+ * a different shape of job, not a different boundary rule.
+ *
+ * So all three implemented strategies are size-bounded splitters and the only thing
+ * that distinguishes them is **where a boundary is allowed to fall**:
+ *
+ * `fixed`
+ *     Anywhere. The window always fills to `size`, cutting mid-word when that is
+ *     where the budget ends. This is the honest baseline other strategies improve on.
+ * `recursive`
+ *     Prefer the last paragraph break, then the last line break, then the last
+ *     sentence end, then the last word break inside the window.
+ * `code`
+ *     Prefer the last blank line, then the last line break, then the last statement
+ *     end. Code is line-structured, so a blank line is the closest thing it has to a
+ *     paragraph, and cutting mid-statement is the failure worth avoiding.
+ *
+ * Chunks are pure functions of the text, so the same input always produces the same
+ * chunks with the same ids in the same order -- which is what makes re-ingesting a
+ * corpus a no-op instead of a duplicate.
+ */
+import type { SourceDocument } from './connectors.js';
+import { Chunk, type ChunkingSpec, type ChunkingStrategy } from './types.js';
+/** A strategy's preference order, outermost first. */
+export type MarkerGroups = readonly (readonly string[])[];
+/** Splits a document into chunks, deterministically. */
+export interface Chunker {
+    readonly strategy: ChunkingStrategy;
+    chunk(document: SourceDocument): readonly Chunk[];
+}
+/** Shared windowing. Subclasses only choose where a boundary may fall. */
+declare abstract class SizeChunker implements Chunker {
+    private readonly _size;
+    private readonly _overlap;
+    private readonly _keep;
+    constructor(init: {
+        readonly size: number;
+        readonly overlap: number;
+        readonly keepMetadata?: readonly string[];
+    });
+    abstract get strategy(): ChunkingStrategy;
+    /** Where to end the window that starts at `start` and may reach `limit`. */
+    protected abstract cut(text: string, start: number, limit: number): number;
+    chunk(document: SourceDocument): readonly Chunk[];
+    private build;
+    /**
+     * The end offset of the last `marker` in `text.slice(start, limit)`, if usable.
+     *
+     * `null` means "no boundary worth taking", and the caller falls back to `limit`.
+     * The minimum-fill rule is applied here rather than by each strategy so no
+     * strategy can forget it.
+     */
+    private boundary;
+    /** The first usable boundary from `markerGroups`, in preference order. */
+    protected fill(text: string, start: number, limit: number, markerGroups: MarkerGroups): number;
+}
+/** Cuts on size alone. */
+export declare class FixedChunker extends SizeChunker {
+    get strategy(): ChunkingStrategy;
+    protected cut(_text: string, _start: number, limit: number): number;
+}
+/** Prefers prose boundaries: paragraph, then line, then sentence, then word. */
+export declare class RecursiveChunker extends SizeChunker {
+    get strategy(): ChunkingStrategy;
+    protected cut(text: string, start: number, limit: number): number;
+}
+/** Prefers code boundaries: blank line, then line, then statement, then token. */
+export declare class CodeChunker extends SizeChunker {
+    get strategy(): ChunkingStrategy;
+    protected cut(text: string, start: number, limit: number): number;
+}
+/**
+ * Resolve a chunking block to an implementation.
+ *
+ * `semantic` is refused here as well as in the spec validator, because the runtime
+ * is reachable from generated code the validator never saw.
+ */
+export declare function chunkerFor(spec: ChunkingSpec): Chunker;
+/** Chunk one document with the strategy the spec names. */
+export declare function chunkDocument(document: SourceDocument, spec: ChunkingSpec): readonly Chunk[];
+export {};
+//# sourceMappingURL=chunking.d.ts.map

package/dist/retrieval/chunking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunking.d.ts","sourceRoot":"","sources":["../../src/retrieval/chunking.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,KAAK,EAAE,KAAK,YAAY,EAAE,KAAK,gBAAgB,EAAc,MAAM,YAAY,CAAC;AAWzF,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;AAE1D,wDAAwD;AACxD,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,KAAK,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,KAAK,EAAE,CAAC;CACnD;AAED,0EAA0E;AAC1E,uBAAe,WAAY,YAAW,OAAO;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAE1C,YAAY,IAAI,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;KAC3C,EAgBA;IAED,QAAQ,KAAK,QAAQ,IAAI,gBAAgB,CAAC;IAE1C,4EAA4E;IAC5E,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAE3E,KAAK,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,KAAK,EAAE,CAoBhD;IAED,OAAO,CAAC,KAAK;IAwBb;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAmBhB,0EAA0E;IAC1E,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAM7F;CACF;AAED,0BAA0B;AAC1B,qBAAa,YAAa,SAAQ,WAAW;IAC3C,IAAa,QAAQ,IAAI,gBAAgB,CAExC;IAED,UAAmB,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3E;CACF;AAED,gFAAgF;AAChF,qBAAa,gBAAiB,SAAQ,WAAW;IAC/C,IAAa,QAAQ,IAAI,gBAAgB,CAExC;IAED,UAAmB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzE;CACF;AAED,kFAAkF;AAClF,qBAAa,WAAY,SAAQ,WAAW;IAC1C,IAAa,QAAQ,IAAI,gBAAgB,CAExC;IAED,UAAmB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzE;CACF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAyBtD;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,EAAE,YAAY,GAAG,SAAS,KAAK,EAAE,CAE5F"}