@cogenta/agents 0.1.0

package/dist/providers/openai.js

@@ -0,0 +1,143 @@
+import { CogentaError } from '@cogenta/core';
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1/chat/completions';
+const STOP_REASON = {
+    stop: 'end_turn',
+    tool_calls: 'tool_use',
+    length: 'max_tokens',
+    content_filter: 'stop_sequence',
+};
+function toOpenAiMessage(message) {
+    if (message.role === 'tool') {
+        if (message.toolCallId === undefined) {
+            throw new CogentaError({
+                code: 'PROVIDER_RESPONSE_INVALID',
+                message: 'A tool-role message is missing its toolCallId.',
+                hint: "Set toolCallId to the id the model's tool call carried.",
+            });
+        }
+        return { role: 'tool', content: message.content ?? '', tool_call_id: message.toolCallId };
+    }
+    const toolCalls = message.toolCalls ?? [];
+    return {
+        role: message.role,
+        content: message.content ?? null,
+        ...(toolCalls.length === 0
+            ? {}
+            : {
+                tool_calls: toolCalls.map((call) => ({
+                    id: call.id,
+                    type: 'function',
+                    function: { name: call.name, arguments: JSON.stringify(call.input) },
+                })),
+            }),
+    };
+}
+/** Pure — no network. */
+export function buildOpenAiRequest(request) {
+    const messages = [];
+    if (request.system !== undefined) {
+        messages.push({ role: 'system', content: request.system });
+    }
+    messages.push(...request.messages.map(toOpenAiMessage));
+    return {
+        model: request.model,
+        max_tokens: request.maxTokens,
+        messages,
+        ...(request.tools === undefined
+            ? {}
+            : {
+                tools: request.tools.map((tool) => ({
+                    type: 'function',
+                    function: {
+                        name: tool.name,
+                        description: tool.description,
+                        parameters: tool.inputSchema,
+                    },
+                })),
+            }),
+        ...(request.temperature === undefined ? {} : { temperature: request.temperature }),
+    };
+}
+/** Pure — no network. */
+export function parseOpenAiResponse(body) {
+    const choice = body.choices[0];
+    if (choice === undefined) {
+        throw new CogentaError({
+            code: 'PROVIDER_RESPONSE_INVALID',
+            message: 'OpenAI returned no choices.',
+            hint: 'Retry the request; this is not something the caller can fix by itself.',
+        });
+    }
+    const toolCalls = (choice.message.tool_calls ?? []).map((call) => ({
+        id: call.id,
+        name: call.function.name,
+        input: parseArguments(call.function.arguments),
+    }));
+    return {
+        content: choice.message.content,
+        toolCalls,
+        stopReason: STOP_REASON[choice.finish_reason],
+        usage: { inputTokens: body.usage.prompt_tokens, outputTokens: body.usage.completion_tokens },
+    };
+}
+function parseArguments(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : {};
+    }
+    catch (cause) {
+        throw new CogentaError({
+            code: 'PROVIDER_RESPONSE_INVALID',
+            message: "OpenAI's tool call arguments were not valid JSON.",
+            hint: 'This is a vendor-side malformed response; retry the request.',
+            cause,
+        });
+    }
+}
+/** API key injected at the runtime boundary — never in a prompt or tool input (rule R7). */
+export function createOpenAiClient(config) {
+    const doFetch = config.fetchImpl ?? fetch;
+    const url = config.baseUrl ?? DEFAULT_BASE_URL;
+    return {
+        name: 'openai',
+        model: config.model,
+        async chat(request, options) {
+            const response = await doFetch(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    authorization: `Bearer ${config.apiKey}`,
+                },
+                body: JSON.stringify(buildOpenAiRequest(request)),
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            }).catch((cause) => {
+                throw new CogentaError({
+                    code: 'PROVIDER_REQUEST_FAILED',
+                    message: 'The request to OpenAI could not be sent.',
+                    hint: 'Check network connectivity and COGENTA_OPENAI_API_KEY.',
+                    cause,
+                });
+            });
+            if (response.status === 429) {
+                throw new CogentaError({
+                    code: 'PROVIDER_RATE_LIMITED',
+                    message: 'OpenAI rate-limited this request.',
+                    hint: 'Retry with backoff, or lower callsPerHour for this agent.',
+                });
+            }
+            if (!response.ok) {
+                throw new CogentaError({
+                    code: 'PROVIDER_REQUEST_FAILED',
+                    message: `OpenAI returned status ${response.status}.`,
+                    hint: 'Check the request and COGENTA_OPENAI_API_KEY.',
+                    details: { status: response.status },
+                });
+            }
+            const body = (await response.json());
+            return parseOpenAiResponse(body);
+        },
+    };
+}
+//# sourceMappingURL=openai.js.map

package/dist/providers/openai.js.map

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

package/dist/providers/registry.d.ts

@@ -0,0 +1,31 @@
+import type { ProviderClient } from './types.js';
+export declare const PROVIDER_NAMES: readonly ['anthropic', 'openai', 'google'];
+export type ProviderName = (typeof PROVIDER_NAMES)[number];
+export interface ProviderRegistryConfig {
+    readonly anthropic?: {
+        readonly apiKey: string;
+        readonly model: string;
+        readonly baseUrl?: string;
+    };
+    readonly openai?: {
+        readonly apiKey: string;
+        readonly model: string;
+        readonly baseUrl?: string;
+    };
+    readonly google?: {
+        readonly apiKey: string;
+        readonly model: string;
+        readonly baseUrl?: string;
+    };
+}
+/**
+ * One client per configured vendor — a site with no LLM provider configured
+ * simply has an empty registry, which is exactly what rule R2 requires ("le
+ * CMS fonctionne sans IA"): nothing here fails to construct, `get()` is what
+ * refuses, and only once an agent actually tries to run.
+ */
+export declare function createProviderRegistry(config: ProviderRegistryConfig): {
+    readonly get: (name: ProviderName) => ProviderClient;
+    readonly has: (name: ProviderName) => boolean;
+};
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,eAAO,MAAM,cAAc,YAAI,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAA;AACxE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA;AAE1D,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE;QACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;QACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAC1B,CAAA;IACD,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAChG,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACjG;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG;IACtE,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,cAAc,CAAA;IACpD,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAA;CAC9C,CAqBA"}

package/dist/providers/registry.js

@@ -0,0 +1,35 @@
+import { CogentaError } from '@cogenta/core';
+import { createAnthropicClient } from './anthropic.js';
+import { createGoogleClient } from './google.js';
+import { createOpenAiClient } from './openai.js';
+export const PROVIDER_NAMES = ['anthropic', 'openai', 'google'];
+/**
+ * One client per configured vendor — a site with no LLM provider configured
+ * simply has an empty registry, which is exactly what rule R2 requires ("le
+ * CMS fonctionne sans IA"): nothing here fails to construct, `get()` is what
+ * refuses, and only once an agent actually tries to run.
+ */
+export function createProviderRegistry(config) {
+    const clients = new Map();
+    if (config.anthropic !== undefined)
+        clients.set('anthropic', createAnthropicClient(config.anthropic));
+    if (config.openai !== undefined)
+        clients.set('openai', createOpenAiClient(config.openai));
+    if (config.google !== undefined)
+        clients.set('google', createGoogleClient(config.google));
+    return {
+        has: (name) => clients.has(name),
+        get(name) {
+            const client = clients.get(name);
+            if (client === undefined) {
+                throw new CogentaError({
+                    code: 'PROVIDER_UNKNOWN',
+                    message: `No provider named "${name}" is configured for this site.`,
+                    hint: 'Set the matching COGENTA_*_API_KEY, or choose a configured provider.',
+                });
+            }
+            return client;
+        },
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/providers/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/providers/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAGhD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAU,CAAA;AAaxE;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA8B;IAInE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAA;IACvD,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS;QAChC,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,qBAAqB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAA;IACnE,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;IACzF,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;IAEzF,OAAO;QACL,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;QAChC,GAAG,CAAC,IAAI;YACN,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;YAChC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,IAAI,YAAY,CAAC;oBACrB,IAAI,EAAE,kBAAkB;oBACxB,OAAO,EAAE,sBAAsB,IAAI,gCAAgC;oBACnE,IAAI,EAAE,sEAAsE;iBAC7E,CAAC,CAAA;YACJ,CAAC;YACD,OAAO,MAAM,CAAA;QACf,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/providers/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * L4 task 1: the normalized shape every provider adapter speaks, so the
+ * execution loop (task 2) calls one interface regardless of vendor. Tool-
+ * calling wire formats differ enough between vendors (Anthropic's
+ * `tool_use` content blocks, OpenAI's `tool_calls` array, Google's
+ * `functionCall` parts) that this is the one place that difference is
+ * allowed to exist — everything above `ProviderClient` sees only this.
+ */
+export type ChatRole = 'user' | 'assistant' | 'tool';
+/** One tool invocation the model asked for — never executed here, only described. */
+export interface ProviderToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+}
+export interface ChatMessage {
+    readonly role: ChatRole;
+    /** Absent (not empty-string) when a turn is tool calls with no accompanying text. */
+    readonly content?: string;
+    /** Set on an `assistant` message that requested tool calls. */
+    readonly toolCalls?: readonly ProviderToolCall[];
+    /** Set on a `tool` message: which call this is the result of. */
+    readonly toolCallId?: string;
+    /** Set on a `tool` message: the tool's name, some vendors require it alongside the id. */
+    readonly toolName?: string;
+}
+/** A tool's shape as the model sees it — `inputSchema` is JSON Schema, already converted from the Zod schema `defineTool` (Contract C) declares. */
+export interface ProviderToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+export interface ChatRequest {
+    readonly model: string;
+    readonly system?: string;
+    readonly messages: readonly ChatMessage[];
+    readonly tools?: readonly ProviderToolSpec[];
+    readonly maxTokens: number;
+    readonly temperature?: number;
+}
+export type StopReason = 'end_turn' | 'tool_use' | 'max_tokens' | 'stop_sequence';
+export interface TokenUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+export interface ChatResponse {
+    /** `null` when the turn is tool calls only, with no accompanying text. */
+    readonly content: string | null;
+    readonly toolCalls: readonly ProviderToolCall[];
+    readonly stopReason: StopReason;
+    readonly usage: TokenUsage;
+}
+export interface ChatOptions {
+    /** Cancels the underlying HTTP request — the execution loop's own timeout/cancellation (task 2) threads through here. */
+    readonly signal?: AbortSignal;
+}
+/** What every adapter implements — the execution loop (task 2) depends on this, never on a vendor SDK type directly. */
+export interface ProviderClient {
+    readonly name: string;
+    readonly model: string;
+    chat(request: ChatRequest, options?: ChatOptions): Promise<ChatResponse>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAA;AAEpD,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAClD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,qFAAqF;IACrF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAChD,iEAAiE;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,0FAA0F;IAC1F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,oJAAoJ;AACpJ,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACxD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAA;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,YAAY,GAAG,eAAe,CAAA;AAEjF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAC/C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,yHAAyH;IACzH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,wHAAwH;AACxH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CACzE"}

package/dist/providers/types.js

@@ -0,0 +1,10 @@
+/**
+ * L4 task 1: the normalized shape every provider adapter speaks, so the
+ * execution loop (task 2) calls one interface regardless of vendor. Tool-
+ * calling wire formats differ enough between vendors (Anthropic's
+ * `tool_use` content blocks, OpenAI's `tool_calls` array, Google's
+ * `functionCall` parts) that this is the one place that difference is
+ * allowed to exist — everything above `ProviderClient` sees only this.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/providers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/rag/chunking/chunk-document.d.ts

@@ -0,0 +1,13 @@
+import type { Chunk, ChunkableDocument } from './types.js';
+/**
+ * "Découpage sémantique par bloc et par titre": a block is the atomic unit
+ * (never split mid-block) and a heading block always starts a new chunk
+ * (never folded into the section above it) — the two boundaries the lot
+ * names. Within those boundaries, consecutive blocks are packed into one
+ * chunk up to `maxChunkChars`, so a chunk stays one coherent section rather
+ * than one block each, which would starve retrieval of context.
+ */
+export declare function chunkDocument(document: ChunkableDocument, options?: {
+    readonly maxChunkChars?: number;
+}): readonly Chunk[];
+//# sourceMappingURL=chunk-document.d.ts.map

package/dist/rag/chunking/chunk-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-document.d.ts","sourceRoot":"","sources":["../../../src/rag/chunking/chunk-document.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAc1D;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,SAAS,KAAK,EAAE,CAqClB"}

package/dist/rag/chunking/chunk-document.js

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto';
+const DEFAULT_MAX_CHUNK_CHARS = 2000;
+function hashText(text) {
+    return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+/**
+ * "Découpage sémantique par bloc et par titre": a block is the atomic unit
+ * (never split mid-block) and a heading block always starts a new chunk
+ * (never folded into the section above it) — the two boundaries the lot
+ * names. Within those boundaries, consecutive blocks are packed into one
+ * chunk up to `maxChunkChars`, so a chunk stays one coherent section rather
+ * than one block each, which would starve retrieval of context.
+ */
+export function chunkDocument(document, options) {
+    const maxChunkChars = options?.maxChunkChars ?? DEFAULT_MAX_CHUNK_CHARS;
+    const chunks = [];
+    let current = null;
+    function flush() {
+        if (current === null || current.blockIds.length === 0)
+            return;
+        // The document title is folded into every chunk's text, not just kept as
+        // metadata — retrieval otherwise loses which document/section a chunk
+        // belongs to once it is embedded and floating in a vector index.
+        const text = [document.title, ...current.texts].join('\n\n');
+        chunks.push({
+            id: `${document.documentId}:${current.blockIds.join(',')}`,
+            documentId: document.documentId,
+            blockIds: [...current.blockIds],
+            text,
+            hash: hashText(text),
+        });
+        current = null;
+    }
+    for (const block of document.blocks) {
+        const blockText = block.text.trim();
+        if (blockText === '')
+            continue;
+        if (block.isHeading === true)
+            flush();
+        if (current !== null && current.chars > 0 && current.chars + blockText.length > maxChunkChars) {
+            flush();
+        }
+        current ??= { blockIds: [], texts: [], chars: 0 };
+        current.blockIds.push(block.id);
+        current.texts.push(blockText);
+        current.chars += blockText.length;
+    }
+    flush();
+    return chunks;
+}
+//# sourceMappingURL=chunk-document.js.map

package/dist/rag/chunking/chunk-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-document.js","sourceRoot":"","sources":["../../../src/rag/chunking/chunk-document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC,MAAM,uBAAuB,GAAG,IAAI,CAAA;AAEpC,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAChE,CAAC;AAQD;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAC3B,QAA2B,EAC3B,OAA6C;IAE7C,MAAM,aAAa,GAAG,OAAO,EAAE,aAAa,IAAI,uBAAuB,CAAA;IACvE,MAAM,MAAM,GAAY,EAAE,CAAA;IAC1B,IAAI,OAAO,GAAoB,IAAI,CAAA;IAEnC,SAAS,KAAK;QACZ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAM;QAC7D,yEAAyE;QACzE,sEAAsE;QACtE,iEAAiE;QACjE,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QAC5D,MAAM,CAAC,IAAI,CAAC;YACV,EAAE,EAAE,GAAG,QAAQ,CAAC,UAAU,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;YAC1D,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;YAC/B,IAAI;YACJ,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC;SACrB,CAAC,CAAA;QACF,OAAO,GAAG,IAAI,CAAA;IAChB,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpC,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;QACnC,IAAI,SAAS,KAAK,EAAE;YAAE,SAAQ;QAE9B,IAAI,KAAK,CAAC,SAAS,KAAK,IAAI;YAAE,KAAK,EAAE,CAAA;QACrC,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,GAAG,CAAC,IAAI,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,MAAM,GAAG,aAAa,EAAE,CAAC;YAC9F,KAAK,EAAE,CAAA;QACT,CAAC;QACD,OAAO,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAA;QACjD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QAC/B,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QAC7B,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC,MAAM,CAAA;IACnC,CAAC;IACD,KAAK,EAAE,CAAA;IAEP,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/rag/chunking/incremental.d.ts

@@ -0,0 +1,19 @@
+import type { Chunk } from './types.js';
+export interface IngestionPlan {
+    /** New chunk ids, and chunks whose text (hence hash) changed since the previous run — these need `EmbeddingProvider.embed()`. */
+    readonly toEmbed: readonly Chunk[];
+    /** Chunk ids present before but absent now — their vectors should be deleted from the index. */
+    readonly toRemove: readonly string[];
+    /** Same id, same hash — skipped entirely, "ré-embedding des seuls chunks modifiés". */
+    readonly unchanged: readonly Chunk[];
+}
+/**
+ * Compares one document's previous chunk set to its freshly re-chunked
+ * current set, by id and hash only — this is the whole incremental
+ * ingestion mechanism the lot asks for: "hash par chunk → ré-embedding des
+ * seuls chunks modifiés". No I/O here; the caller owns fetching `previous`
+ * from wherever the index stores it and calling the embedding provider and
+ * the index with the plan's three lists.
+ */
+export declare function planIncrementalIngestion(previous: readonly Chunk[], next: readonly Chunk[]): IngestionPlan;
+//# sourceMappingURL=incremental.d.ts.map

package/dist/rag/chunking/incremental.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"incremental.d.ts","sourceRoot":"","sources":["../../../src/rag/chunking/incremental.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC,MAAM,WAAW,aAAa;IAC5B,iIAAiI;IACjI,QAAQ,CAAC,OAAO,EAAE,SAAS,KAAK,EAAE,CAAA;IAClC,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,uFAAuF;IACvF,QAAQ,CAAC,SAAS,EAAE,SAAS,KAAK,EAAE,CAAA;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,KAAK,EAAE,EAC1B,IAAI,EAAE,SAAS,KAAK,EAAE,GACrB,aAAa,CAef"}

package/dist/rag/chunking/incremental.js

@@ -0,0 +1,24 @@
+/**
+ * Compares one document's previous chunk set to its freshly re-chunked
+ * current set, by id and hash only — this is the whole incremental
+ * ingestion mechanism the lot asks for: "hash par chunk → ré-embedding des
+ * seuls chunks modifiés". No I/O here; the caller owns fetching `previous`
+ * from wherever the index stores it and calling the embedding provider and
+ * the index with the plan's three lists.
+ */
+export function planIncrementalIngestion(previous, next) {
+    const previousById = new Map(previous.map((chunk) => [chunk.id, chunk]));
+    const nextIds = new Set(next.map((chunk) => chunk.id));
+    const toEmbed = [];
+    const unchanged = [];
+    for (const chunk of next) {
+        const prior = previousById.get(chunk.id);
+        if (prior === undefined || prior.hash !== chunk.hash)
+            toEmbed.push(chunk);
+        else
+            unchanged.push(chunk);
+    }
+    const toRemove = previous.filter((chunk) => !nextIds.has(chunk.id)).map((chunk) => chunk.id);
+    return { toEmbed, toRemove, unchanged };
+}
+//# sourceMappingURL=incremental.js.map

package/dist/rag/chunking/incremental.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"incremental.js","sourceRoot":"","sources":["../../../src/rag/chunking/incremental.ts"],"names":[],"mappings":"AAWA;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAA0B,EAC1B,IAAsB;IAEtB,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;IACxE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;IAEtD,MAAM,OAAO,GAAY,EAAE,CAAA;IAC3B,MAAM,SAAS,GAAY,EAAE,CAAA;IAC7B,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QACxC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;YAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;;YACpE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC5B,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IAE5F,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;AACzC,CAAC"}

package/dist/rag/chunking/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Deliberately not `@cogenta/blocks`' own block union — the same reasoning
+ * `ContentServiceLike` (task 5) documents for content tools: a narrow
+ * structural shape the real block-flattening step (wherever content is read
+ * from, outside this package) can satisfy, instead of a hard dependency.
+ */
+export interface ChunkableBlock {
+    readonly id: string;
+    /** A heading/title block — always starts a new chunk, never gets folded into the section above it. */
+    readonly isHeading?: boolean;
+    readonly text: string;
+}
+export interface ChunkableDocument {
+    readonly documentId: string;
+    readonly title: string;
+    readonly blocks: readonly ChunkableBlock[];
+}
+export interface Chunk {
+    /**
+     * `${documentId}:${blockIds.join(',')}` — identity comes from which blocks
+     * make up the chunk, not from its position or its text. An edit to a
+     * block's text keeps the same chunk id (so incremental ingestion sees "same
+     * chunk, new hash" rather than a spurious remove+add); a block moving to a
+     * different section, or a chunk boundary shifting, is a genuinely different
+     * chunk and gets a different id.
+     */
+    readonly id: string;
+    readonly documentId: string;
+    readonly blockIds: readonly string[];
+    readonly text: string;
+    /** SHA-256 of `text` — the only thing incremental ingestion compares to decide what needs re-embedding. */
+    readonly hash: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rag/chunking/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/rag/chunking/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,sGAAsG;IACtG,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAA;CAC3C;AAED,MAAM,WAAW,KAAK;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,2GAA2G;IAC3G,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB"}

package/dist/rag/chunking/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/rag/chunking/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/rag/chunking/types.ts"],"names":[],"mappings":""}

package/dist/rag/embeddings/hashing-provider.d.ts

@@ -0,0 +1,22 @@
+import type { EmbeddingProvider } from './types.js';
+/**
+ * The "hashing trick" (scikit-learn's `HashingVectorizer` is the same idea):
+ * a bag-of-words vector folded into a fixed size by hashing each token to a
+ * dimension and a sign, then L2-normalised for cosine similarity. Local, CPU,
+ * zero dependency, no model to download — deliberately not the
+ * `multilingual-e5-small` ONNX model the lot names as the eventual default.
+ *
+ * That adapter is deferred: the natural library for local ONNX text
+ * embeddings in Node, `@huggingface/transformers`, declares `sharp` as a
+ * hard (non-optional) direct dependency even for text-only use — the exact
+ * native-without-WASM-fallback failure R10 exists to prevent, breaking
+ * `pnpm install` on ARM/musl/shared hosting regardless of which backend is
+ * actually used at runtime. `EmbeddingProvider` is shaped so a real ONNX
+ * adapter can replace this one later (task 15/16's RAG index keys on
+ * `{provider, model, dimensions}`, not on how a vector was produced) once a
+ * `sharp`-free path exists — a follow-up, not this task's call to make.
+ */
+export declare function createHashingEmbeddingProvider(options?: {
+    readonly dimensions?: number;
+}): EmbeddingProvider;
+//# sourceMappingURL=hashing-provider.d.ts.map

package/dist/rag/embeddings/hashing-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashing-provider.d.ts","sourceRoot":"","sources":["../../../src/rag/embeddings/hashing-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AA8BnD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,CAAC,EAAE;IACvD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,GAAG,iBAAiB,CAUpB"}

package/dist/rag/embeddings/hashing-provider.js

@@ -0,0 +1,53 @@
+const DEFAULT_DIMENSIONS = 256;
+function tokenize(text) {
+    return text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+}
+/** FNV-1a — deterministic, no dependency, good enough spread for a hashing-trick embedding. */
+function hashToken(token) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < token.length; i++) {
+        hash ^= token.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+function embedOne(text, dimensions) {
+    const vector = new Array(dimensions).fill(0);
+    for (const token of tokenize(text)) {
+        const hash = hashToken(token);
+        const index = hash % dimensions;
+        const sign = hash & 1 ? 1 : -1;
+        vector[index] = (vector[index] ?? 0) + sign;
+    }
+    const norm = Math.sqrt(vector.reduce((sum, value) => sum + value * value, 0));
+    return norm === 0 ? vector : vector.map((value) => value / norm);
+}
+/**
+ * The "hashing trick" (scikit-learn's `HashingVectorizer` is the same idea):
+ * a bag-of-words vector folded into a fixed size by hashing each token to a
+ * dimension and a sign, then L2-normalised for cosine similarity. Local, CPU,
+ * zero dependency, no model to download — deliberately not the
+ * `multilingual-e5-small` ONNX model the lot names as the eventual default.
+ *
+ * That adapter is deferred: the natural library for local ONNX text
+ * embeddings in Node, `@huggingface/transformers`, declares `sharp` as a
+ * hard (non-optional) direct dependency even for text-only use — the exact
+ * native-without-WASM-fallback failure R10 exists to prevent, breaking
+ * `pnpm install` on ARM/musl/shared hosting regardless of which backend is
+ * actually used at runtime. `EmbeddingProvider` is shaped so a real ONNX
+ * adapter can replace this one later (task 15/16's RAG index keys on
+ * `{provider, model, dimensions}`, not on how a vector was produced) once a
+ * `sharp`-free path exists — a follow-up, not this task's call to make.
+ */
+export function createHashingEmbeddingProvider(options) {
+    const dimensions = options?.dimensions ?? DEFAULT_DIMENSIONS;
+    return {
+        provider: 'local-hashing',
+        model: 'feature-hashing-v1',
+        dimensions,
+        async embed(texts) {
+            return texts.map((text) => embedOne(text, dimensions));
+        },
+    };
+}
+//# sourceMappingURL=hashing-provider.js.map

package/dist/rag/embeddings/hashing-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashing-provider.js","sourceRoot":"","sources":["../../../src/rag/embeddings/hashing-provider.ts"],"names":[],"mappings":"AAEA,MAAM,kBAAkB,GAAG,GAAG,CAAA;AAE9B,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAA;AAC1D,CAAC;AAED,+FAA+F;AAC/F,SAAS,SAAS,CAAC,KAAa;IAC9B,IAAI,IAAI,GAAG,UAAU,CAAA;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;QAC3B,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;IACpC,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,CAAA;AACnB,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY,EAAE,UAAkB;IAChD,MAAM,MAAM,GAAG,IAAI,KAAK,CAAS,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACpD,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAA;QAC7B,MAAM,KAAK,GAAG,IAAI,GAAG,UAAU,CAAA;QAC/B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;QAC9B,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAA;IAC7C,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAA;IAC7E,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;AAClE,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,8BAA8B,CAAC,OAE9C;IACC,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,kBAAkB,CAAA;IAC5D,OAAO;QACL,QAAQ,EAAE,eAAe;QACzB,KAAK,EAAE,oBAAoB;QAC3B,UAAU;QACV,KAAK,CAAC,KAAK,CAAC,KAAK;YACf,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAA;QACxD,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/rag/embeddings/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * L4 task 14. "L'index porte `{provider, model, dimensions}`. Changer de
+ * modèle crée un index parallèle" — this triple is the identity an index is
+ * built against, so every embedding call carries it, never just a bare
+ * vector.
+ */
+export interface EmbeddingModelInfo {
+    readonly provider: string;
+    readonly model: string;
+    readonly dimensions: number;
+}
+export interface EmbeddingProvider extends EmbeddingModelInfo {
+    /** One vector per input text, same order, same length as `texts`. */
+    embed(texts: readonly string[]): Promise<readonly (readonly number[])[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rag/embeddings/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/rag/embeddings/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,MAAM,WAAW,iBAAkB,SAAQ,kBAAkB;IAC3D,qEAAqE;IACrE,KAAK,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;CACzE"}

package/dist/rag/embeddings/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/rag/embeddings/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/rag/embeddings/types.ts"],"names":[],"mappings":""}

package/dist/rag/index/bm25.d.ts

@@ -0,0 +1,4 @@
+import type { IndexedChunk, RankedId } from './types.js';
+/** Standard Okapi BM25 over each chunk's text — the keyword half of the hybrid search. */
+export declare function bm25Rank(chunks: readonly IndexedChunk[], queryText: string): readonly RankedId[];
+//# sourceMappingURL=bm25.d.ts.map

package/dist/rag/index/bm25.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bm25.d.ts","sourceRoot":"","sources":["../../../src/rag/index/bm25.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AASxD,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,QAAQ,EAAE,CAiChG"}