dsh-library 0.1.0

package/lib/types/quality/chunk-visual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-visual.d.ts","sourceRoot":"","sources":["../../../src/quality/chunk-visual.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,0EAA0E;AAC1E,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,CAoBnF;AAED,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAAiC,CAAA;AAEjF,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IAC9F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,kBAAkB,CA8B/E;AAED,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAA;IACtC,mFAAmF;IACnF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,qFAAqF;IACrF,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,gBAAgB,CAmBzE;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAE9C;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,aAAa,EAAE,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAcpD"}

package/lib/types/quality/citation.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Port of Citation-Validator-Lite (upstream/PerryLink, Apache-2.0): citation
+ * extraction (`[n]` markers), sentence-bounded claim windows, and fuzzy
+ * validation against the cited source. The upstream `fuzzywuzzy`
+ * `partial_ratio` is reimplemented as a bounded token-sequence partial ratio
+ * (zero dependencies) — the shorter text slides over every token window of
+ * the longer one and the best ratio wins, matching the upstream semantics.
+ * @module dsh-library/quality/citation
+ */
+/** One citation match — the upstream `CitationMatch` dataclass. */
+export interface CitationMatch {
+    readonly number: string;
+    readonly context: string;
+    readonly is_valid: boolean;
+    /** Fuzzy score 0..100. */
+    readonly score: number;
+    readonly start_pos: number;
+    readonly end_pos: number;
+    readonly reason: string;
+}
+/** The whole validation result — the upstream `ValidationResult` dataclass. */
+export interface ValidationResult {
+    readonly results: readonly CitationMatch[];
+    readonly threshold: number;
+}
+/**
+ * Extract every `[<digits>]` citation marker as (number, start, end) — the
+ * upstream `extract_citations` (`r'\[(\d+)\]'`).
+ * @param text - the answer text.
+ * @returns the markers in scan order.
+ */
+export declare function extractCitationNumbers(text: string): Array<{
+    number: string;
+    start: number;
+    end: number;
+}>;
+/**
+ * Extract the sentence around a citation position — the upstream
+ * `extract_sentence_with_citation`: scan backwards to the nearest sentence
+ * ending (`.`, `!`, `?`, newline) and forwards the same way, bounded by the
+ * window.
+ * @param text - the answer text.
+ * @param citationPos - the citation marker position.
+ * @param window - maximum half-window in characters.
+ * @returns the trimmed sentence context.
+ */
+export declare function extractSentenceWithCitation(text: string, citationPos: number, window?: number): string;
+/**
+ * Bounded port of `fuzz.partial_ratio`: the best sequence ratio between one
+ * text and every token window of the other. Both sides are token-capped so
+ * hostilely long sources stay within a fixed quadratic budget.
+ * @param claim - the claim text.
+ * @param source - the source text.
+ * @returns the best ratio as a 0..100 integer score.
+ */
+export declare function fuzzyPartialRatio(claim: string, source: string): number;
+/**
+ * Validate one citation claim against its source — the upstream
+ * `validate_citation` (`fuzz.partial_ratio(claim, source) >= threshold`).
+ * @param claim - the claim context.
+ * @param source - the cited source text.
+ * @param threshold - pass score (0..100).
+ * @returns `[isValid, score]`.
+ */
+export declare function validateCitation(claim: string, source: string, threshold?: number): [boolean, number];
+/**
+ * Validate every citation in an answer — the upstream `validate_citations`.
+ * Unknown source numbers are invalid with score 0 and reason
+ * "Source not found"; low scores carry a "Low match score: N%" reason.
+ * @param answer - the answer text with `[n]` markers.
+ * @param sources - source text keyed by citation number.
+ * @param threshold - pass score (0..100).
+ * @returns the validation result.
+ */
+export declare function validateCitations(answer: string, sources: Readonly<Record<string, string>>, threshold?: number): ValidationResult;
+//# sourceMappingURL=citation.d.ts.map

package/lib/types/quality/citation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation.d.ts","sourceRoot":"","sources":["../../../src/quality/citation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAA;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAM1G;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAM,GAAG,MAAM,CAmBnG;AA8BD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAYvE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAK,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAGjG;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,SAAS,SAAK,GAAG,gBAAgB,CAmB7H"}

package/lib/types/quality/diversity.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Port of Retrieval-Diversity-Check (upstream/PerryLink, Apache-2.0): the
+ * TF-IDF cosine duplicate scan (`check_diversity`) plus the maximal-marginal
+ * relevance re-ranking that `library_search` applies to its hybrid-ranked
+ * candidates. Pure functions — the upstream numpy/sklearn calls are replaced
+ * by the shared token vocabulary.
+ * @module dsh-library/quality/diversity
+ */
+/** One duplicate pair from {@link checkDiversity}. */
+export interface DuplicatePair {
+    readonly first: number;
+    readonly second: number;
+    readonly similarity: number;
+}
+/** The `check_diversity` result dictionary, ported 1:1. */
+export interface DiversityReport {
+    readonly totalTexts: number;
+    readonly duplicateCount: number;
+    /** Percentage of texts involved in at least one duplicate pair. */
+    readonly tokenSavings: number;
+    readonly duplicates: readonly DuplicatePair[];
+    /** Row-major lower-triangle-free matrix of pairwise cosine similarities. */
+    readonly similarityMatrix: readonly (readonly number[])[];
+}
+/**
+ * Check a text list for near-duplicates — the upstream `check_diversity`.
+ * TF-IDF-lite vectors share one token vocabulary; pairs whose cosine
+ * similarity is STRICTLY above `threshold` are duplicates (upstream uses
+ * `>`). Fewer than two texts throw, like upstream.
+ * @param texts - the texts to compare.
+ * @param threshold - similarity threshold (0..1).
+ * @returns the diversity report.
+ * @throws TypeError on fewer than two texts.
+ */
+export declare function checkDiversity(texts: readonly string[], threshold?: number): DiversityReport;
+/** One re-rankable candidate: an item plus its relevance and pair similarity. */
+export interface RerankCandidate {
+    readonly id: string;
+    /** Pre-existing relevance (hybrid score), used as the MMR relevance term. */
+    readonly relevance: number;
+    /** Pairwise similarity to one already-selected item. */
+    similarityTo(other: RerankCandidate): number;
+}
+/**
+ * Maximal marginal relevance over {@link RerankCandidate}s: greedily pick the
+ * candidate maximizing `lambda * relevance - (1 - lambda) * maxSimilarity`.
+ * `lambda = 1` is pure relevance order, `lambda = 0` pure diversity.
+ * @param candidates - the ranked candidate pool.
+ * @param lambda - relevance/diversity trade-off within 0..1.
+ * @param topK - how many to pick.
+ * @returns the picked candidates in selection order.
+ */
+export declare function maximalMarginalRelevance<T extends RerankCandidate>(candidates: readonly T[], lambda: number, topK: number): T[];
+//# sourceMappingURL=diversity.d.ts.map

package/lib/types/quality/diversity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diversity.d.ts","sourceRoot":"","sources":["../../../src/quality/diversity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;IAC7C,4EAA4E;IAC5E,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAA;CAC1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,SAAM,GAAG,eAAe,CAsBzF;AAiBD,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,wDAAwD;IACxD,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAA;CAC7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,eAAe,EAChE,UAAU,EAAE,SAAS,CAAC,EAAE,EACxB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,CAAC,EAAE,CAsBL"}

package/lib/types/quality/few-shot.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Port of Few-Shot-Selector (upstream/PerryLink, Apache-2.0): the
+ * similarity-ranked example selection and the prompt formatter. The upstream
+ * ChromaDB collection + SentenceTransformer model are replaced by the
+ * plugin's deterministic hash embedder (zero downloads) — same
+ * "embed question, cosine-rank, top-n" pipeline and the same prompt layout.
+ * @module dsh-library/quality/few-shot
+ */
+/** One QA example in the local store, mirroring the upstream metadata shape. */
+export interface QaExample {
+    readonly id: string;
+    readonly question: string;
+    readonly answer: string;
+    readonly category?: string;
+    /** Free-form tags, joined by commas in the upstream metadata. */
+    readonly tags?: readonly string[];
+}
+/** One selected example plus its similarity to the query. */
+export interface SelectedExample {
+    readonly example: QaExample;
+    /** Cosine similarity to the query (0..1 for the hash embedder). */
+    readonly score: number;
+}
+/** Selection options: how many examples and the embedding dimensionality. */
+export interface FewShotOptions {
+    /** How many examples to return (upstream `n_results`). */
+    readonly n?: number;
+    /** Hash-embedding dimensionality used for ranking. */
+    readonly dims?: number;
+}
+/** Whether a QA pair is usable, ported from upstream `validate_qa_pair`. */
+export declare function validateQaPair(question: string, answer: string): boolean;
+/**
+ * Rank the example store by cosine similarity to the query and return the
+ * top `n` — the upstream `search_similar` with the hash embedder in place of
+ * the SentenceTransformer model. An empty query or store throws, like
+ * upstream (`ValueError` / `DatabaseNotInitializedError`).
+ * @param query - the query text.
+ * @param examples - the QA store.
+ * @param options - selection options.
+ * @returns the selected examples, best first.
+ * @throws TypeError on an empty query or empty store.
+ */
+export declare function selectFewShot(query: string, examples: readonly QaExample[], options?: FewShotOptions): SelectedExample[];
+/**
+ * Format the upstream few-shot prompt: an intro line, one numbered
+ * question/answer block per example, then the query — ported 1:1 from
+ * `format_prompt`.
+ * @param query - the query text.
+ * @param selected - the selected examples, in order.
+ * @returns the formatted prompt text.
+ */
+export declare function formatFewShotPrompt(query: string, selected: readonly SelectedExample[]): string;
+//# sourceMappingURL=few-shot.d.ts.map

package/lib/types/quality/few-shot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"few-shot.d.ts","sourceRoot":"","sources":["../../../src/quality/few-shot.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAClC;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,6EAA6E;AAC7E,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAA;IACnB,sDAAsD;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAExE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,SAAS,EAAE,EAAE,OAAO,GAAE,cAAmB,GAAG,eAAe,EAAE,CAW5H;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,CAS/F"}

package/lib/types/quality/lost-middle.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Port of Lost-in-Middle-Tester (upstream/PerryLink, Apache-2.0): the probe
+ * insertion and position statistics vocabulary, plus the avoidance strategy
+ * that `library_search` applies to its retrieved list — the strongest chunks
+ * are pinned to the head and tail of the context so the model never meets
+ * the key evidence only in the middle.
+ * @module dsh-library/quality/lost-middle
+ */
+/** One probe trial's outcome, mirroring the upstream `TestResult` shape. */
+export interface ProbeResult {
+    /** Relative insertion position within 0..1. */
+    readonly position: number;
+    readonly probe: string;
+    readonly found: boolean;
+}
+/** Default probe prefix, mirroring the upstream `SECRET_CODE_` convention. */
+export declare const PROBE_PREFIX = "SECRET_CODE_";
+/**
+ * Deterministic probe text for one trial. The upstream generator draws 4
+ * random chars; here the caller supplies the suffix so tests replay.
+ * @param suffix - the 4-character uppercase/digit suffix.
+ * @returns the full probe string.
+ */
+export declare function makeProbe(suffix: string): string;
+/**
+ * Insert a probe sentence into one paragraph — the upstream
+ * `PasswordInserter.insert`, deterministic instead of random.
+ * @param paragraphs - the paragraph list.
+ * @param position - relative position within 0..1 (clamped to the list).
+ * @param probe - the probe string to insert.
+ * @returns the modified list, the probe, and the insertion index.
+ */
+export declare function insertProbe(paragraphs: readonly string[], position: number, probe: string): {
+    modified: string[];
+    probe: string;
+    index: number;
+};
+/** Per-position statistics, mirroring the upstream `ResultCollector`. */
+export interface PositionStats {
+    readonly successRate: number;
+    readonly successCount: number;
+    readonly totalCount: number;
+}
+/** Success counts keyed by position (the upstream statistics dictionary). */
+export declare function successByPosition(results: readonly ProbeResult[]): Map<number, PositionStats>;
+/**
+ * The upstream prompt template used to test whether a model can surface a
+ * probe at a given position.
+ * @param document - the joined document text.
+ * @returns the model prompt.
+ */
+export declare function buildProbePrompt(document: string): string;
+/** One ranked item the avoidance strategy reorders. */
+export interface RankedItem {
+    readonly id: string;
+    readonly score: number;
+}
+/**
+ * Lost-in-the-middle avoidance: reorder a ranked list so the strongest items
+ * sit at the head and the tail of the context window (the positions models
+ * read most reliably), leaving the weakest in the middle. Within each zone
+ * the score order is preserved.
+ * @param ranked - the items ranked by score, descending.
+ * @param head - how many strongest items to pin to the head.
+ * @param tail - how many next-strongest items to pin to the tail.
+ * @returns the reordered list (same length, same members).
+ */
+export declare function avoidLostMiddle(ranked: readonly RankedItem[], head: number, tail: number): RankedItem[];
+/** One position bin of a middle-penalty report. */
+export interface PositionBin {
+    /** Inclusive relative start of the bin (0..1). */
+    readonly start: number;
+    /** Exclusive relative end of the bin (0..1). */
+    readonly end: number;
+    readonly count: number;
+    readonly meanScore: number;
+}
+/**
+ * Bin one ranked list by relative position and fold each bin's mean score —
+ * the middle-penalty report: a score trough in the middle bins is the
+ * lost-in-the-middle risk signal `library_diagnose` reports.
+ * @param ranked - the items in their final context order.
+ * @param bins - how many equal-width bins to use.
+ * @returns one entry per bin.
+ */
+export declare function positionBins(ranked: readonly RankedItem[], bins: number): PositionBin[];
+/**
+ * The middle-penalty magnitude: how much the middle bins' mean score drops
+ * below the best bin's mean. 0 means no penalty (flat distribution); larger
+ * values mean strong content sits at the edges and weak content in the middle.
+ * @param bins - a {@link positionBins} report.
+ * @returns the penalty within 0..1, or 0 for an empty report.
+ */
+export declare function middlePenalty(bins: readonly PositionBin[]): number;
+//# sourceMappingURL=lost-middle.d.ts.map

package/lib/types/quality/lost-middle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lost-middle.d.ts","sourceRoot":"","sources":["../../../src/quality/lost-middle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAED,8EAA8E;AAC9E,eAAO,MAAM,YAAY,iBAAiB,CAAA;AAE1C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAQtD;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAiB7F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAMvG;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAiBvF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAUlE"}

package/lib/types/quality/purge.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Port of RAG-Purge-Verify (upstream/PerryLink, Apache-2.0): after a
+ * document is removed, probe the remaining index with deterministic
+ * signatures of the removed content and report any residue. The upstream
+ * metadata-filter and payload-text engine probes become token n-gram
+ * signature probes over the remaining chunks; `passed` requires zero hits,
+ * exactly like the upstream `total_found == 0` gate.
+ * @module dsh-library/quality/purge
+ */
+/** One remaining index entry the purge verification probes against. */
+export interface RemainingChunk {
+    readonly id: string;
+    readonly text: string;
+}
+/** One signature probe's outcome — the upstream per-check result dictionary. */
+export interface PurgeProbeResult {
+    readonly signature: string;
+    readonly foundCount: number;
+    readonly residueIds: readonly string[];
+}
+/** The whole verification report — the upstream `verify` return. */
+export interface PurgeReport {
+    /** True when no signature matched anything (the upstream pass stamp). */
+    readonly passed: boolean;
+    readonly totalFound: number;
+    readonly probes: readonly PurgeProbeResult[];
+}
+/** Purge verification options, bound to the resolved purge config. */
+export interface PurgeOptions {
+    /** Token n-gram width of the signatures. */
+    readonly signatureLength?: number;
+    /** How many signatures are probed; longer documents sample deterministically. */
+    readonly maxProbes?: number;
+}
+/**
+ * Deterministically pick up to `maxProbes` signatures from a list: indices
+ * are spread evenly across the list so long documents are sampled end to end.
+ * @param signatures - the full signature list.
+ * @param maxProbes - the probe budget.
+ * @returns the sampled signatures in original order.
+ */
+export declare function sampleSignatures(signatures: readonly string[], maxProbes: number): string[];
+/**
+ * Verify that a removed document left no residue in the remaining index —
+ * the upstream `Verifier.verify` flow. Signatures are token n-grams of the
+ * removed content; a chunk is residue when it contains every token of one
+ * signature (as token-subsequence containment is too strict for chunk
+ * boundaries, exact phrase containment is used).
+ * @param remaining - the chunks that should remain after removal.
+ * @param removedContent - the removed document text.
+ * @param options - purge options.
+ * @returns the purge report; `passed` is true only on zero residue.
+ */
+export declare function verifyPurge(remaining: readonly RemainingChunk[], removedContent: string, options?: PurgeOptions): PurgeReport;
+//# sourceMappingURL=purge.d.ts.map

package/lib/types/quality/purge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"purge.d.ts","sourceRoot":"","sources":["../../../src/quality/purge.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC7C;AAED,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ3F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,cAAc,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,WAAW,CAYjI"}

package/lib/types/quality/reference.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Port of RAG-Reference-Checker (upstream/PerryLink, Apache-2.0): citation
+ * extraction (`[n]` markers), the surrounding-context window, and the
+ * verify loop that marks each citation valid / suspicious / missing. The
+ * upstream SentenceTransformer model (and its `download_model.py`) is
+ * replaced by the plugin's deterministic hash embedder — zero downloads, and
+ * the similarity threshold is the resolved `citation.minSemantic` config.
+ * @module dsh-library/quality/reference
+ */
+/** One extracted citation marker: its numeric id and [start, end) span. */
+export interface CitationMarker {
+    readonly refId: number;
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Extract every `[<digits>]` citation marker — the upstream
+ * `extract_citations` (`r'\[(\d+)\]'`), with the numeric id returned as a
+ * number like the upstream `int(match.group(1))`.
+ * @param text - the answer text.
+ * @returns the markers in scan order.
+ */
+export declare function extractCitations(text: string): CitationMarker[];
+/**
+ * Extract the character window around a citation position — the upstream
+ * `extract_context` (`position ± window`, trimmed).
+ * @param text - the answer text.
+ * @param position - the citation marker position.
+ * @param window - half-window size in characters.
+ * @returns the trimmed context.
+ */
+export declare function extractContext(text: string, position: number, window?: number): string;
+/** One reference document the checker verifies against. */
+export interface ReferenceDocument {
+    readonly id: number;
+    readonly content: string;
+}
+/** One citation verdict — the upstream per-citation result dictionary. */
+export interface ReferenceVerdict {
+    readonly refId: number;
+    /** `valid` (similarity ≥ threshold), `suspicious` (below), or `missing` (unknown id). */
+    readonly status: 'valid' | 'suspicious' | 'missing';
+    /** Semantic similarity, rounded to two decimals like upstream. */
+    readonly similarity: number;
+    /** The claim context the similarity was computed from. */
+    readonly context: string;
+    /** Present on suspicious/missing verdicts only. */
+    readonly reason?: string;
+}
+/** The whole verification report — the upstream `verify_references` return. */
+export interface ReferenceReport {
+    readonly total: number;
+    readonly valid: number;
+    readonly suspicious: number;
+    readonly details: readonly ReferenceVerdict[];
+}
+/** Verification options: similarity threshold and embedding dimensionality. */
+export interface ReferenceOptions {
+    /** Similarity threshold (0..1); below it a citation is `suspicious`. */
+    readonly threshold?: number;
+    /** Hash-embedding dimensionality. */
+    readonly dims?: number;
+}
+/**
+ * Verify every citation in an answer against the reference list — the
+ * upstream `verify_references` with the hash embedder substituted for the
+ * model. Unknown reference ids are `missing`; known ids whose context
+ * similarity falls below the threshold are `suspicious`.
+ * @param answer - the answer text containing `[n]` markers.
+ * @param references - the reference documents keyed by numeric id.
+ * @param options - verification options.
+ * @returns the verification report.
+ */
+export declare function verifyReferences(answer: string, references: readonly ReferenceDocument[], options?: ReferenceOptions): ReferenceReport;
+//# sourceMappingURL=reference.d.ts.map

package/lib/types/quality/reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../src/quality/reference.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CAM/D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,MAAM,CAIlF;AAED,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAAA;IACnD,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC9C;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,qCAAqC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,iBAAiB,EAAE,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA0B1I"}

package/lib/types/quality/relevance.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Port of Context-Relevance-Scorer (upstream/PerryLink, Apache-2.0): the
+ * relevance scoring/filtering pipeline that `library_search` runs after
+ * retrieval. The upstream cross-encoder model is replaced by a local-rules
+ * lexical scorer (zero downloads): token overlap weighted toward rarer
+ * query terms, normalized to 0..1 — same `(document, score, passed)` API
+ * shape as the upstream `score_batch`/`filter_documents`.
+ * @module dsh-library/quality/relevance
+ */
+/**
+ * Score one document's relevance to a query with the local-rules scorer.
+ * Each query token contributes its document frequency share: a query term
+ * the document covers at least once contributes fully; the score is the
+ * covered-query-weight fraction. Repeated query terms are down-weighted
+ * (1/count) so spam cannot inflate coverage.
+ * @param query - the query text.
+ * @param document - the candidate document text.
+ * @returns relevance within 0..1 (0 for an empty query or document).
+ */
+export declare function scoreRelevance(query: string, document: string): number;
+/** One scored document, mirroring the upstream `score_batch` tuple. */
+export interface ScoredDocument {
+    readonly document: string;
+    readonly score: number;
+    readonly passed: boolean;
+}
+/**
+ * Score a batch of documents against one query — the upstream `score_batch`.
+ * @param query - the query text.
+ * @param documents - the candidate documents.
+ * @param threshold - the pass threshold (0..1); score ≥ threshold passes.
+ * @returns one entry per document, in input order.
+ */
+export declare function scoreBatch(query: string, documents: readonly string[], threshold?: number): ScoredDocument[];
+/**
+ * Keep only documents that pass the threshold — the upstream
+ * `filter_documents`, with the local-rules scorer substituted for the model.
+ * @param query - the query text.
+ * @param documents - the candidate documents.
+ * @param threshold - the pass threshold (0..1).
+ * @returns the passing documents in input order.
+ */
+export declare function filterDocuments(query: string, documents: readonly string[], threshold?: number): string[];
+//# sourceMappingURL=relevance.d.ts.map

package/lib/types/quality/relevance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relevance.d.ts","sourceRoot":"","sources":["../../../src/quality/relevance.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAatE;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,SAAM,GAAG,cAAc,EAAE,CAKzG;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,SAAS,SAAM,GAAG,MAAM,EAAE,CAItG"}

package/lib/types/text.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared text utilities for the quality modules: tokenization, term
+ * frequencies, and n-gram windows. Pure and deterministic — every scoring
+ * module builds on this vocabulary.
+ * @module dsh-library/text
+ */
+/**
+ * Normalize prose for scoring: lowercase and collapse whitespace.
+ * Does NOT strip punctuation (token boundaries still cut on it).
+ * @param text - input text.
+ * @returns the normalized text.
+ */
+export declare function normalize(text: string): string;
+/**
+ * Tokenize into lowercase word tokens. ASCII words keep their boundaries;
+ * every other run of letters counts as one token so CJK text still scores.
+ * @param text - input text.
+ * @returns the token list.
+ */
+export declare function tokenize(text: string): string[];
+/** Deduplicated token set of one text. */
+export declare function tokenSet(text: string): ReadonlySet<string>;
+/**
+ * Term-frequency map of one text: token → occurrence count.
+ * @param text - input text.
+ * @returns the frequency map (plain object, no prototype).
+ */
+export declare function termFrequencies(text: string): Record<string, number>;
+/**
+ * Character n-grams of a normalized text, for the built-in hash embedder.
+ * A space-padded form adds leading/trailing boundary markers so prefixes and
+ * suffixes still contribute.
+ * @param text - input text.
+ * @param n - n-gram width.
+ * @returns the n-gram array.
+ */
+export declare function charNGrams(text: string, n: number): string[];
+/**
+ * Token n-grams of a tokenized text (the purge signature vocabulary).
+ * @param tokens - token list from {@link tokenize}.
+ * @param n - n-gram width.
+ * @returns n-gram tokens joined by spaces, deduplicated.
+ */
+export declare function tokenNGrams(tokens: readonly string[], n: number): string[];
+/**
+ * FNV-1a 32-bit string hash — the deterministic bucket of the hash embedder.
+ * @param text - string to hash.
+ * @returns an unsigned 32-bit integer.
+ */
+export declare function fnv1a(text: string): number;
+//# sourceMappingURL=text.d.ts.map

package/lib/types/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../../src/text.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAO/C;AAED,0CAA0C;AAC1C,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIpE;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ5D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ1E;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO1C"}