@sirdaspdf/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sırdaş
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @sirdaspdf/core
+
+The engine behind [Sırdaş](https://sirdas.app): PDF operations, PDF→Markdown for
+LLMs, local anonymization of personal data, and the pieces needed to turn
+documents into a training set. Runs in the browser and in Node, with the same
+code path.
+
+```bash
+npm install @sirdaspdf/core
+```
+
+## Use
+
+```js
+import { pdfToMarkdown, anonymize, deanonymize } from "@sirdaspdf/core";
+
+const markdown = await pdfToMarkdown(pdfjsDocument);
+const { text, findings } = anonymize(markdown);
+// …send `text` to a model, then put the real data back into its answer:
+const real = deanonymize(answer, findings);
+```
+
+PDF.js is a peer dependency and optional: the text functions take a document you
+have already opened, so the browser uses its own worker and Node uses the legacy
+build. Structural operations (merge, split, compress) only need `pdf-lib`.
+
+Subpath imports are available and the package is `sideEffects: false`, so a
+bundler only pulls in what you use:
+
+```js
+import { chunkMarkdown } from "@sirdaspdf/core/chunk";
+import { dedupe } from "@sirdaspdf/core/dedupe";
+```
+
+## What is in it
+
+| Module | |
+|---|---|
+| `markdown` | Layout-aware PDF→Markdown: font size becomes heading level, running headers removed, token estimate |
+| `anonymize` | Rule-based detection with consistent, **reversible** placeholders. Tuned for Spanish and Colombian documents |
+| `tables` | Table detection and CSV/Markdown export; columns rebuilt from recurring whitespace |
+| `chunk` | Split at headings into context-sized pieces, each carrying its heading |
+| `diff` | Line-level diff of two documents with a similarity score |
+| `dataset` | Records for fine-tuning in TRL's field names, with provenance |
+| `dedupe` | MinHash + LSH near-duplicate detection |
+| `paragraphs` | CCNet-style repeated-paragraph detection |
+| `contamination` | n-gram overlap between training and evaluation sets |
+| `datasplit` | Train/validation/test split **by document**, never by chunk |
+| `verifiable` | (prompt, ground_truth) pairs from tables, for RL with verifiable rewards |
+| `merge` · `split` · `organize` · `lossless` · `ranges` · `ocr` · `errors` | |
+
+Anonymization detection is rule-based and can miss unusual formats. Review
+before sharing a sensitive document.
+
+Full documentation: https://sirdas.app/docs/agents/core.md ·
+Source: https://github.com/Brayan15p/SIRDAS-APP-PDF · MIT

package/dist/anonymize.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Motor de anonimización local basado en reglas (v1).
+ * Pseudonimiza: el mismo valor recibe siempre la misma etiqueta,
+ * para que la IA conserve la coherencia del documento.
+ */
+export type EntityType = "EMAIL" | "NIT" | "DOCUMENTO" | "TARJETA" | "TELEFONO" | "FECHA" | "DIRECCION" | "NOMBRE" | "HISTORIA_CLINICA";
+export interface Finding {
+    type: EntityType;
+    value: string;
+    label: string;
+}
+export declare function anonymize(text: string): {
+    text: string;
+    findings: Finding[];
+};
+/**
+ * Devuelve los datos reales a un texto anonimizado: el viaje de vuelta.
+ *
+ * El flujo pensado es: anonimizar → pegar el texto con etiquetas en la IA →
+ * traer aquí la respuesta → recuperar los nombres y números reales. El
+ * documento original nunca se modifica y nada de esto sale del dispositivo.
+ *
+ * `unknown` recoge las etiquetas que aparecen en el texto pero no están en el
+ * mapa: casi siempre significa que la IA se inventó una etiqueta, o que el
+ * mapa no corresponde a este documento.
+ */
+export declare function deanonymize(text: string, findings: Finding[]): {
+    text: string;
+    restored: number;
+    unknown: string[];
+};
+/** Serializa el mapa de etiquetas para guardarlo o pasarlo entre herramientas. */
+export declare function findingsToMap(findings: Finding[]): Record<string, string>;
+/** Reconstruye los hallazgos desde un mapa guardado. */
+export declare function mapToFindings(map: Record<string, string>): Finding[];

package/dist/anonymize.js

@@ -0,0 +1,113 @@
+const MONTHS = "enero|febrero|marzo|abril|mayo|junio|julio|agosto|septiembre|setiembre|octubre|noviembre|diciembre|january|february|march|april|may|june|july|august|september|october|november|december";
+// Un nombre debe capturarse ENTERO: si se corta, el apellido que queda fuera
+// se filtra. Cubrimos las partículas españolas ("de", "del", "de la/las/los")
+// y hasta siete palabras, que es lo que llega a tener un nombre compuesto
+// colombiano con dos apellidos.
+const PARTICLE = "(?:de\\s+(?:la|las|los)\\s+|del\\s+|de\\s+)?";
+const NAME = `[A-ZÁÉÍÓÚÑ][a-záéíóúñü]+(?:\\s+${PARTICLE}[A-ZÁÉÍÓÚÑ][a-záéíóúñü]+){1,6}`;
+const NAME_UPPER = "[A-ZÁÉÍÓÚÑ]{2,}(?:\\s+[A-ZÁÉÍÓÚÑ]{2,}){1,6}";
+/** Vuelve insensible a mayúsculas solo las etiquetas (el nombre sí distingue mayúsculas). */
+const ci = (src) => src.replace(/[a-záéíóúñ]/g, (ch) => `[${ch}${ch.toUpperCase()}]`);
+const NAME_LABELS = "nombres?(?:\\s+completo)?|paciente|usuario|afiliado|señora?|sr\\.|sra\\.|don|doña|comprador(?:a)?|vendedor(?:a)?|otorgante|compareciente|demandante|demandado|arrendador(?:a)?|arrendatario|apoderad[oa]|titular|firmado por|name|patient|client|signed by";
+const RULES = [
+    { type: "EMAIL", re: /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g },
+    { type: "HISTORIA_CLINICA", re: /\b(?:historia\s+cl[ií]nica|h\.?\s?c\.?|n[uú]mero\s+de\s+historia)\s*(?:n[oº°.]*|#|:)?\s*([A-Z0-9-]{4,})/gi, group: 1 },
+    { type: "NIT", re: /\b(?:NIT\.?\s*:?\s*)?\d{3}\.?\d{3}\.?\d{3}\s?-\s?\d\b/g },
+    { type: "TARJETA", re: /\b(?:\d{4}[ -]?){3}\d{1,4}\b/g },
+    {
+        type: "DOCUMENTO",
+        re: /\b(?:C\.?\s?C\.?|c[eé]dula(?:\s+de\s+ciudadan[ií]a)?|T\.?\s?I\.?|C\.?\s?E\.?|NUIP|pasaporte|DNI|RUT|CURP|RFC|ID)\s*(?:n[oº°.]*|#|:)?\s*([A-Z]{0,4}\d[\d.\s-]{4,14}\d)/gi,
+        group: 1,
+    },
+    { type: "DOCUMENTO", re: /(?<![$€£\d.,]\s?)\b\d{1,3}(?:\.\d{3}){2,3}\b(?!\s*(?:pesos|cop|usd|millones|m²|m2))/gi },
+    {
+        type: "TELEFONO",
+        re: /(?:\+\d{1,3}[\s.-]?)?(?:\(\d{1,4}\)[\s.-]?)?\b(?:3\d{2}[\s.-]?\d{3}[\s.-]?\d{4}|60\d[\s.-]?\d{3}[\s.-]?\d{4}|\d{3}[\s.-]\d{3}[\s.-]\d{4})\b/g,
+    },
+    // Fijo colombiano con indicativo entre paréntesis: "(601) 742 1234", "(1) 742-1234".
+    {
+        type: "TELEFONO",
+        re: /(?:\+\d{1,3}[\s.-]?)?\(\d{1,3}\)[\s.-]?\d{3}[\s.-]?\d{4}\b/g,
+    },
+    { type: "FECHA", re: /\b\d{1,2}[/.-]\d{1,2}[/.-](?:\d{4}|\d{2})\b/g },
+    { type: "FECHA", re: /\b\d{4}-\d{2}-\d{2}\b/g },
+    { type: "FECHA", re: new RegExp(`\\b\\d{1,2}\\s+(?:de\\s+)?(?:${MONTHS})(?:\\s+(?:de|del)?\\s*\\d{4})?\\b`, "gi") },
+    {
+        type: "DIRECCION",
+        re: /\b(?:calle|cll?|carrera|cra|kr|kra|avenida|av|transversal|tv|diagonal|dg|autopista|street|st|avenue|ave)\.?\s*\d+[a-z]?(?:\s*bis)?(?:\s*(?:sur|norte|este))?\s*(?:#|n[oº°.]*|no\.?)\s*\d+[a-z]?\s*-\s*\d+(?:\s*(?:sur|norte|este))?(?:[,\s]+(?:apto|apartamento|oficina|of|int|interior|casa|torre)\.?\s*[\w-]+)*/gi,
+    },
+    { type: "NOMBRE", re: new RegExp(`(?:${ci(NAME_LABELS)})\\s*[:\\-]?\\s*(${NAME_UPPER}|${NAME})(?![a-záéíóúñ])`, "g"), group: 1 },
+];
+export function anonymize(text) {
+    const map = new Map();
+    const counters = new Map();
+    const findings = [];
+    const labelFor = (type, value) => {
+        const key = `${type}:${value.replace(/\s+/g, " ").trim().toLowerCase()}`;
+        const found = map.get(key);
+        if (found)
+            return found;
+        const n = (counters.get(type) ?? 0) + 1;
+        counters.set(type, n);
+        const label = `[${type}_${n}]`;
+        map.set(key, label);
+        findings.push({ type, value: value.trim(), label });
+        return label;
+    };
+    let out = text;
+    for (const rule of RULES) {
+        out = out.replace(rule.re, (...args) => {
+            const full = args[0];
+            const target = rule.group ? args[rule.group] : full;
+            if (!target || target.startsWith("["))
+                return full;
+            if (rule.type === "NOMBRE" && /\[/.test(target))
+                return full;
+            const label = labelFor(rule.type, target);
+            return rule.group ? full.replace(target, label) : label;
+        });
+    }
+    // Segunda pasada: cualquier aparición suelta de un nombre ya detectado.
+    for (const f of findings.filter((x) => x.type === "NOMBRE")) {
+        const esc = f.value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, "\\s+");
+        out = out.replace(new RegExp(`\\b${esc}\\b`, "gi"), f.label);
+    }
+    return { text: out, findings };
+}
+/**
+ * Devuelve los datos reales a un texto anonimizado: el viaje de vuelta.
+ *
+ * El flujo pensado es: anonimizar → pegar el texto con etiquetas en la IA →
+ * traer aquí la respuesta → recuperar los nombres y números reales. El
+ * documento original nunca se modifica y nada de esto sale del dispositivo.
+ *
+ * `unknown` recoge las etiquetas que aparecen en el texto pero no están en el
+ * mapa: casi siempre significa que la IA se inventó una etiqueta, o que el
+ * mapa no corresponde a este documento.
+ */
+export function deanonymize(text, findings) {
+    const byLabel = new Map(findings.map((f) => [f.label, f.value]));
+    let restored = 0;
+    const unknown = new Set();
+    const out = text.replace(/\[([A-Z_]+)_(\d+)\]/g, (label) => {
+        const value = byLabel.get(label);
+        if (value === undefined) {
+            unknown.add(label);
+            return label;
+        }
+        restored++;
+        return value;
+    });
+    return { text: out, restored, unknown: [...unknown] };
+}
+/** Serializa el mapa de etiquetas para guardarlo o pasarlo entre herramientas. */
+export function findingsToMap(findings) {
+    return Object.fromEntries(findings.map((f) => [f.label, f.value]));
+}
+/** Reconstruye los hallazgos desde un mapa guardado. */
+export function mapToFindings(map) {
+    return Object.entries(map).map(([label, value]) => {
+        const type = (label.match(/^\[([A-Z_]+)_\d+\]$/)?.[1] ?? "NOMBRE");
+        return { type, value, label };
+    });
+}

package/dist/chunk.d.ts

@@ -0,0 +1,13 @@
+export interface Chunk {
+    /** Posición, base 1. */
+    index: number;
+    /** Encabezado bajo el que cae este trozo, si lo hay. */
+    heading: string | null;
+    text: string;
+    tokens: number;
+}
+/**
+ * Divide el Markdown en trozos de como máximo `maxTokens` (estimados).
+ * Secciones consecutivas pequeñas se agrupan para no generar ruido.
+ */
+export declare function chunkMarkdown(markdown: string, maxTokens?: number): Chunk[];

package/dist/chunk.js

@@ -0,0 +1,93 @@
+// Divide un documento en trozos del tamaño que acepta un modelo de IA.
+//
+// Cada trozo se corta en un encabezado y arrastra el encabezado que lo
+// contiene, de modo que sea comprensible por sí solo: eso es lo que hace que
+// un fragmento sirva tanto para pegarlo en un chat como para indexarlo en RAG.
+import { estimateTokens } from "./markdown.js";
+const HEADING = /^(#{1,3})\s+(.+)$/;
+/** Parte el Markdown por encabezados, conservando el texto previo al primero. */
+function sections(markdown) {
+    const out = [];
+    let heading = null;
+    let body = [];
+    const flush = () => {
+        const text = body.join("\n").trim();
+        if (text || heading)
+            out.push({ heading, body: text });
+        body = [];
+    };
+    for (const line of markdown.split("\n")) {
+        const m = line.match(HEADING);
+        if (m) {
+            flush();
+            heading = m[2].trim();
+        }
+        else {
+            body.push(line);
+        }
+    }
+    flush();
+    return out;
+}
+/** Parte un bloque largo por párrafos sin pasarse del presupuesto. */
+function splitLong(body, maxTokens) {
+    const paragraphs = body.split(/\n{2,}/);
+    const parts = [];
+    let current = [];
+    const size = () => estimateTokens(current.join("\n\n"));
+    for (const p of paragraphs) {
+        if (current.length && size() + estimateTokens(p) > maxTokens) {
+            parts.push(current.join("\n\n"));
+            current = [];
+        }
+        // Un solo párrafo más grande que el presupuesto va solo: partirlo a la
+        // mitad de una frase sería peor que entregarlo entero.
+        current.push(p);
+    }
+    if (current.length)
+        parts.push(current.join("\n\n"));
+    return parts.filter((p) => p.trim());
+}
+/**
+ * Divide el Markdown en trozos de como máximo `maxTokens` (estimados).
+ * Secciones consecutivas pequeñas se agrupan para no generar ruido.
+ */
+export function chunkMarkdown(markdown, maxTokens = 2000) {
+    const text = markdown.trim();
+    if (!text)
+        return [];
+    if (estimateTokens(text) <= maxTokens) {
+        return [{ index: 1, heading: null, text, tokens: estimateTokens(text) }];
+    }
+    const chunks = [];
+    const push = (heading, body) => {
+        const withHeading = heading ? `# ${heading}\n\n${body}`.trim() : body.trim();
+        if (!withHeading)
+            return;
+        chunks.push({ index: chunks.length + 1, heading, text: withHeading, tokens: estimateTokens(withHeading) });
+    };
+    let pending = null;
+    const flushPending = () => {
+        if (pending)
+            push(pending.heading, pending.body);
+        pending = null;
+    };
+    for (const sec of sections(text)) {
+        const whole = sec.heading ? `# ${sec.heading}\n\n${sec.body}` : sec.body;
+        if (estimateTokens(whole) > maxTokens) {
+            flushPending();
+            for (const part of splitLong(sec.body, maxTokens))
+                push(sec.heading, part);
+            continue;
+        }
+        if (pending && estimateTokens(`${pending.body}\n\n${whole}`) <= maxTokens) {
+            // Cabe con la sección anterior: agrupamos para no fragmentar de más.
+            pending.body = `${pending.body}\n\n${whole}`.trim();
+            continue;
+        }
+        flushPending();
+        pending = { heading: sec.heading, body: sec.body };
+    }
+    flushPending();
+    return chunks.map((c, i) => ({ ...c, index: i + 1 }));
+}

package/dist/contamination.d.ts

@@ -0,0 +1,45 @@
+export interface ContaminationOptions {
+    /** Palabras por n-grama. 13 es la heurística habitual. */
+    n?: number;
+    /** Fracción de n-gramas compartidos a partir de la cual se marca. */
+    threshold?: number;
+    /** Cuántos ejemplos de coincidencia devolver por registro. */
+    samples?: number;
+    /**
+     * Ignorar los n-gramas que aparezcan en más de este número de documentos de
+     * referencia. Es la regla de GPT-3 contra el texto repetido: una cláusula
+     * legal o un pie de página que sale en media empresa no es contaminación,
+     * es formulario. Poner 0 desactiva el filtro.
+     */
+    ignoreCommon?: number;
+}
+export interface Contaminated {
+    /** Índice en el conjunto revisado. */
+    index: number;
+    /** N-gramas de este registro que aparecen en el otro conjunto. */
+    shared: number;
+    /** Total de n-gramas del registro. */
+    total: number;
+    /** shared / total. */
+    ratio: number;
+    /** Fragmentos concretos que coincidieron. */
+    examples: string[];
+}
+export interface ContaminationReport {
+    contaminated: Contaminated[];
+    /** Índices que se pueden usar sin problema. */
+    clean: number[];
+    /** Fracción de registros marcados. */
+    ratio: number;
+    n: number;
+    /** N-gramas descartados por salir en demasiados documentos de referencia. */
+    ignoredAsBoilerplate: number;
+}
+/**
+ * Marca los registros de `check` que comparten texto con `reference`.
+ *
+ * El uso normal es `check` = entrenamiento y `reference` = evaluación: así
+ * sabes qué quitar del entrenamiento para que la evaluación siga valiendo.
+ * Al revés también sirve, para saber qué preguntas del test ya están gastadas.
+ */
+export declare function findContamination(check: string[], reference: string[], options?: ContaminationOptions): ContaminationReport;

package/dist/contamination.js

@@ -0,0 +1,74 @@
+// Detección de contaminación: qué parte de tu conjunto de entrenamiento
+// aparece también en el de evaluación.
+//
+// Si un fragmento del test está en el train, la métrica de evaluación deja de
+// medir si el modelo aprendió y pasa a medir si recordó. El método estándar en
+// la industria es el solapamiento de n-gramas largos: un n-grama de 13 palabras
+// que aparece en los dos lados no es una coincidencia del idioma, es el mismo
+// texto.
+import { fnv1a, ngrams, ngramHashes } from "./text.js";
+const DEFAULTS = { n: 13, threshold: 0.01, samples: 3, ignoreCommon: 10 };
+/**
+ * Marca los registros de `check` que comparten texto con `reference`.
+ *
+ * El uso normal es `check` = entrenamiento y `reference` = evaluación: así
+ * sabes qué quitar del entrenamiento para que la evaluación siga valiendo.
+ * Al revés también sirve, para saber qué preguntas del test ya están gastadas.
+ */
+export function findContamination(check, reference, options = {}) {
+    const { n, threshold, samples, ignoreCommon } = { ...DEFAULTS, ...options };
+    // Se cuenta en cuántos documentos distintos sale cada n-grama, no cuántas
+    // veces en total: repetir una frase dentro de un mismo documento no la
+    // convierte en formulario.
+    const docsWith = new Map();
+    for (const text of reference) {
+        for (const h of ngramHashes(text, n))
+            docsWith.set(h, (docsWith.get(h) ?? 0) + 1);
+    }
+    const refHashes = new Set();
+    let ignored = 0;
+    for (const [h, count] of docsWith) {
+        if (ignoreCommon > 0 && count > ignoreCommon)
+            ignored++;
+        else
+            refHashes.add(h);
+    }
+    const contaminated = [];
+    const clean = [];
+    for (let i = 0; i < check.length; i++) {
+        const grams = ngrams(check[i], n);
+        if (grams.length === 0) {
+            clean.push(i);
+            continue;
+        }
+        // Se recorre el texto, no el conjunto, para poder devolver el fragmento
+        // literal que coincidió: un informe que solo da un número no se puede
+        // comprobar.
+        const seen = new Set();
+        const examples = [];
+        let shared = 0;
+        for (const g of grams) {
+            if (!refHashes.has(fnv1a(g)))
+                continue;
+            shared++;
+            if (examples.length < samples && !seen.has(g)) {
+                seen.add(g);
+                examples.push(g);
+            }
+        }
+        const ratio = shared / grams.length;
+        if (shared > 0 && ratio >= threshold) {
+            contaminated.push({ index: i, shared, total: grams.length, ratio, examples });
+        }
+        else {
+            clean.push(i);
+        }
+    }
+    return {
+        contaminated,
+        clean,
+        ratio: check.length === 0 ? 0 : contaminated.length / check.length,
+        n,
+        ignoredAsBoilerplate: ignored,
+    };
+}

package/dist/dataset.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Formatos de salida. Los nombres de campo son los que consumen los
+ * entrenadores; cambiarlos rompe la carga del dataset, así que no se tocan.
+ */
+export type DatasetFormat = "text" | "chat" | "prompt-completion";
+export interface SourceDocument {
+    /** Nombre del archivo: es la clave del reparto y de la trazabilidad. */
+    name: string;
+    /** El documento ya convertido a Markdown. */
+    markdown: string;
+}
+export interface BuildOptions {
+    format?: DatasetFormat;
+    /** Tokens por registro antes de trocear. */
+    maxTokens?: number;
+    /** Anonimizar los datos personales. Activado por defecto, y con motivo. */
+    anonymize?: boolean;
+    /**
+     * Plantilla de la instrucción para los formatos `chat` y
+     * `prompt-completion`. Admite {heading} y {document}.
+     */
+    template?: string;
+    /** Instrucción de sistema, solo para `chat`. */
+    system?: string;
+}
+/** Procedencia: sin esto un dataset no se puede auditar ni corregir. */
+export interface Provenance {
+    document: string;
+    /** Índice del trozo dentro del documento, empezando en 1. */
+    chunk: number;
+    heading: string;
+    tokens: number;
+    /** Cuántos datos personales se sustituyeron en este registro. */
+    redacted: number;
+}
+export interface DatasetRecord {
+    /** Los campos del formato elegido, tal cual van al JSONL. */
+    data: Record<string, unknown>;
+    meta: Provenance;
+}
+/**
+ * Convierte documentos en registros de entrenamiento.
+ *
+ * Cada trozo de cada documento da un registro. El troceado es por encabezados,
+ * así que un registro no parte una idea por la mitad, y el encabezado viaja
+ * dentro del texto para que el fragmento se entienda solo.
+ */
+export declare function buildRecords(docs: SourceDocument[], options?: BuildOptions): DatasetRecord[];
+/**
+ * Serializa a JSONL. Una línea por registro, sin sangrado: es lo que leen los
+ * cargadores de datasets.
+ *
+ * `withMeta` añade la procedencia a cada línea. Los entrenadores ignoran los
+ * campos que no conocen, así que dejarla puesta sale gratis y permite rastrear
+ * de qué página salió cada ejemplo cuando el modelo diga algo raro.
+ */
+export declare function toJsonl(records: DatasetRecord[], withMeta?: boolean): string;
+export interface DatasetStats {
+    records: number;
+    documents: number;
+    tokens: number;
+    /** Total de datos personales sustituidos en todo el conjunto. */
+    redacted: number;
+    /** Registros en los que se sustituyó al menos un dato personal. */
+    recordsWithPii: number;
+    medianTokens: number;
+    maxTokens: number;
+}
+export declare function datasetStats(records: DatasetRecord[]): DatasetStats;

package/dist/dataset.js

@@ -0,0 +1,95 @@
+// Construcción del conjunto de datos: de documentos a JSONL listo para
+// entrenar.
+//
+// Lo que NO hace, a propósito: inventar preguntas y respuestas con un modelo.
+// Eso exigiría mandar tus documentos a una API, que es exactamente lo que este
+// producto existe para evitar. Aquí todo sale del documento por reglas, y cada
+// registro dice de dónde salió.
+import { chunkMarkdown } from "./chunk.js";
+import { anonymize as redactPii } from "./anonymize.js";
+import { estimateTokens } from "./markdown.js";
+const DEFAULT_TEMPLATE = "Resume el contenido de «{heading}» del documento {document}.";
+/** Un trozo sin encabezado no puede pedir «resume la sección “archivo.pdf”». */
+const DEFAULT_TEMPLATE_NO_HEADING = "Resume el contenido del documento {document}.";
+function fillTemplate(tpl, values) {
+    return tpl.replace(/\{(heading|document)\}/g, (_, k) => values[k]);
+}
+/**
+ * Convierte documentos en registros de entrenamiento.
+ *
+ * Cada trozo de cada documento da un registro. El troceado es por encabezados,
+ * así que un registro no parte una idea por la mitad, y el encabezado viaja
+ * dentro del texto para que el fragmento se entienda solo.
+ */
+export function buildRecords(docs, options = {}) {
+    const { format = "text", maxTokens = 2000, anonymize = true, system, } = options;
+    const records = [];
+    for (const doc of docs) {
+        const chunks = chunkMarkdown(doc.markdown, maxTokens);
+        chunks.forEach((chunk, i) => {
+            let text = chunk.text;
+            let redacted = 0;
+            if (anonymize) {
+                const result = redactPii(text);
+                text = result.text;
+                redacted = result.findings.length;
+            }
+            if (text.trim() === "")
+                return;
+            const meta = {
+                document: doc.name,
+                chunk: i + 1,
+                heading: chunk.heading ?? "",
+                tokens: estimateTokens(text),
+                redacted,
+            };
+            const hasHeading = (chunk.heading ?? "").trim() !== "";
+            const tpl = options.template ?? (hasHeading ? DEFAULT_TEMPLATE : DEFAULT_TEMPLATE_NO_HEADING);
+            const instruction = fillTemplate(tpl, { heading: chunk.heading ?? "", document: doc.name });
+            records.push({ data: shape(format, text, instruction, system), meta });
+        });
+    }
+    return records;
+}
+function shape(format, text, instruction, system) {
+    switch (format) {
+        case "text":
+            return { text };
+        case "prompt-completion":
+            return { prompt: instruction, completion: text };
+        case "chat": {
+            const messages = [];
+            if (system)
+                messages.push({ role: "system", content: system });
+            messages.push({ role: "user", content: instruction });
+            messages.push({ role: "assistant", content: text });
+            return { messages };
+        }
+    }
+}
+/**
+ * Serializa a JSONL. Una línea por registro, sin sangrado: es lo que leen los
+ * cargadores de datasets.
+ *
+ * `withMeta` añade la procedencia a cada línea. Los entrenadores ignoran los
+ * campos que no conocen, así que dejarla puesta sale gratis y permite rastrear
+ * de qué página salió cada ejemplo cuando el modelo diga algo raro.
+ */
+export function toJsonl(records, withMeta = true) {
+    return records
+        .map((r) => JSON.stringify(withMeta ? { ...r.data, sirdas: r.meta } : r.data))
+        .join("\n");
+}
+export function datasetStats(records) {
+    const tokens = records.map((r) => r.meta.tokens).sort((a, b) => a - b);
+    const total = tokens.reduce((a, b) => a + b, 0);
+    return {
+        records: records.length,
+        documents: new Set(records.map((r) => r.meta.document)).size,
+        tokens: total,
+        redacted: records.reduce((n, r) => n + r.meta.redacted, 0),
+        recordsWithPii: records.filter((r) => r.meta.redacted > 0).length,
+        medianTokens: tokens.length === 0 ? 0 : tokens[Math.floor(tokens.length / 2)],
+        maxTokens: tokens.length === 0 ? 0 : tokens[tokens.length - 1],
+    };
+}

package/dist/datasplit.d.ts

@@ -0,0 +1,30 @@
+export interface SplitRatios {
+    train: number;
+    validation: number;
+    test: number;
+}
+export interface SplitOptions {
+    ratios?: SplitRatios;
+    /** Cambiarla reordena el reparto; la misma semilla da siempre lo mismo. */
+    seed?: string;
+}
+export interface SplitResult<T> {
+    train: T[];
+    validation: T[];
+    test: T[];
+    /** Cuántos documentos distintos fueron a cada partición. */
+    documents: {
+        train: number;
+        validation: number;
+        test: number;
+    };
+}
+/**
+ * Reparte registros agrupándolos por documento de origen.
+ *
+ * `docOf` dice a qué documento pertenece cada registro. El reparto se decide
+ * hasheando el nombre del documento junto con la semilla, así que es estable:
+ * volver a ejecutarlo con los mismos archivos da exactamente el mismo reparto,
+ * y añadir un documento nuevo no mueve a los demás de partición.
+ */
+export declare function splitByDocument<T>(records: T[], docOf: (record: T) => string, options?: SplitOptions): SplitResult<T>;