@alextis59/athena 1.0.0

package/dist/retrieval/tools.js

@@ -0,0 +1,803 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { createDeterministicEmbeddingVector, decodeVector } from "../embeddings/index.js";
+import { UserFacingError } from "../errors.js";
+import { openDatabase, resolveAthenaPaths } from "../storage/index.js";
+export class RetrievalToolRuntime {
+    trace = {
+        seenChunkIds: new Set(),
+        readLocators: [],
+        searchScores: []
+    };
+    database;
+    root;
+    constructor(root, dbPath) {
+        const paths = resolveAthenaPaths(root, dbPath);
+        this.root = paths.root;
+        this.database = openDatabase(paths.databasePath, {
+            readonly: true,
+            fileMustExist: true
+        });
+    }
+    close() {
+        this.database.close();
+    }
+    searchDocs(input) {
+        return this.searchDocsWithMode(input, "hybrid");
+    }
+    searchDocsWithMode(input, mode) {
+        const query = requireNonEmptyString(input.query, "query");
+        const limit = clampLimit(input.limit, 10, 50);
+        const ftsQuery = toFtsQuery(query);
+        const candidates = new Map();
+        if (mode !== "vector") {
+            for (const candidate of this.searchFtsCandidates(input, query, ftsQuery, limit)) {
+                candidates.set(candidate.result.chunkId, candidate);
+            }
+        }
+        if (mode !== "fts") {
+            for (const candidate of this.searchVectorCandidates(input, query, limit)) {
+                const existing = candidates.get(candidate.result.chunkId);
+                if (existing === undefined) {
+                    candidates.set(candidate.result.chunkId, candidate);
+                    continue;
+                }
+                existing.vectorScore = Math.max(existing.vectorScore, candidate.vectorScore);
+                existing.result.scores.vector = existing.vectorScore;
+                existing.result.scores.merged = mergeScoreForLocator(existing.ftsScore, existing.vectorScore, existing.result.locator);
+                existing.result.score = existing.result.scores.merged;
+            }
+        }
+        const rankedCandidates = [...candidates.values()].sort(compareCandidates);
+        const results = this.expandNeighborCandidates(rankedCandidates, limit)
+            .sort(compareCandidates)
+            .map((candidate) => candidate.result)
+            .sort(compareResults)
+            .slice(0, limit);
+        for (const result of results) {
+            this.trace.seenChunkIds.add(result.chunkId);
+            this.trace.searchScores.push({
+                chunkId: result.chunkId,
+                path: result.path,
+                ftsScore: result.scores.fts,
+                vectorScore: result.scores.vector,
+                mergedScore: result.scores.merged,
+                ...(result.contextOfChunkId === undefined
+                    ? {}
+                    : { contextOfChunkId: result.contextOfChunkId })
+            });
+        }
+        return results;
+    }
+    readSourceRange(input) {
+        const source = this.getSourceByPath(input.path);
+        const startLine = requirePositiveInteger(input.startLine, "startLine");
+        const endLine = requirePositiveInteger(input.endLine, "endLine");
+        if (endLine < startLine) {
+            throw new UserFacingError("endLine must be greater than or equal to startLine.");
+        }
+        return this.readSourceRangeFromSource(source, startLine, endLine);
+    }
+    readPdfSource(input) {
+        const source = this.getSourceByPath(input.path);
+        if (source.kind !== "pdf") {
+            throw new UserFacingError(`Source is not a PDF: ${source.relative_path}`);
+        }
+        const requestedPage = input.page === undefined
+            ? undefined
+            : requirePositiveInteger(input.page, "page");
+        const requestedRegionId = input.regionId === undefined
+            ? undefined
+            : requireNonEmptyString(input.regionId, "regionId");
+        const artifacts = this.getParserArtifacts(source.id);
+        const markdown = readGeneratedPdfMarkdown(artifacts, source.relative_path);
+        const sourceMap = readArtifactPayload(artifacts, "source-map");
+        const warnings = readArrayArtifactPayload(artifacts, "warnings");
+        const confidence = readArtifactPayload(artifacts, "confidence");
+        const assets = readArrayArtifactPayload(artifacts, "assets");
+        const locators = this.getPdfLocators(source.id);
+        const pageCount = inferPdfPageCount(artifacts, locators);
+        const locator = selectPdfLocator({
+            path: source.relative_path,
+            locators,
+            page: requestedPage,
+            regionId: requestedRegionId,
+            pageCount
+        });
+        const markdownLineCount = countMarkdownLines(markdown);
+        const markdownStartLine = clampLine(locator.markdownStartLine ?? 1, markdownLineCount);
+        const markdownEndLine = clampLine(locator.markdownEndLine ?? markdownLineCount, markdownLineCount);
+        this.trace.readLocators.push(locator);
+        return {
+            path: source.relative_path,
+            page: locator.page,
+            markdown: sliceMarkdownLines(markdown, markdownStartLine, markdownEndLine),
+            markdownStartLine,
+            markdownEndLine,
+            locator,
+            sourceMapEntries: filterSourceMapEntries(sourceMap, locator),
+            warnings,
+            confidence,
+            assets
+        };
+    }
+    async grepDocs(input) {
+        const pattern = requireNonEmptyString(input.pattern, "pattern");
+        if (pattern.length > 128) {
+            throw new UserFacingError("grep pattern must be 128 characters or fewer.");
+        }
+        const limit = clampLimit(input.limit, 20, 100);
+        const listInput = { limit: 500 };
+        if (input.pathPrefix !== undefined) {
+            listInput.pathPrefix = input.pathPrefix;
+        }
+        if (input.kind !== undefined) {
+            listInput.kind = input.kind;
+        }
+        const sources = this.listDocs(listInput);
+        const matcher = createMatcher(pattern, input.regex === true);
+        const results = [];
+        for (const source of sources) {
+            const filePath = path.join(this.root, source.path);
+            const lines = (await readFile(filePath, "utf8"))
+                .replace(/\r\n?/gu, "\n")
+                .split("\n");
+            for (const [index, line] of lines.entries()) {
+                if (!matcher(line)) {
+                    continue;
+                }
+                const locator = {
+                    type: "text",
+                    path: source.path,
+                    startLine: index + 1,
+                    endLine: index + 1
+                };
+                this.trace.readLocators.push(locator);
+                results.push({
+                    path: source.path,
+                    lineNumber: index + 1,
+                    line,
+                    locator
+                });
+                if (results.length >= limit) {
+                    return results;
+                }
+            }
+        }
+        return results;
+    }
+    listDocs(input = {}) {
+        const filters = ["root = ?"];
+        const params = [this.root];
+        if (input.pathPrefix !== undefined) {
+            filters.push("relative_path LIKE ? ESCAPE '\\'");
+            params.push(`${escapeLike(input.pathPrefix)}%`);
+        }
+        if (input.kind !== undefined) {
+            filters.push("kind = ?");
+            params.push(input.kind);
+        }
+        params.push(clampLimit(input.limit, 100, 500));
+        const whereClause = filters.length === 0 ? "" : `WHERE ${filters.join(" AND ")}`;
+        const rows = this.database
+            .prepare([
+            "SELECT id, root, relative_path, kind, size_bytes, content_hash",
+            "FROM sources",
+            whereClause,
+            "ORDER BY relative_path LIMIT ?"
+        ].join(" "))
+            .all(...params);
+        return rows.map(toListDocsResult);
+    }
+    getDoc(pathValue) {
+        const source = this.findSourceByPath(pathValue);
+        return source === null ? null : toListDocsResult(source);
+    }
+    relatedChunks(input) {
+        const before = clampLimit(input.before, 1, 10, 0);
+        const after = clampLimit(input.after, 1, 10, 0);
+        const center = this.getChunkById(input.chunkId);
+        const rows = this.database
+            .prepare([
+            "SELECT chunks.id, chunks.source_id, sources.relative_path, chunks.ordinal,",
+            "chunks.text, chunks.locator_json, chunks.previous_chunk_id,",
+            "chunks.next_chunk_id",
+            "FROM chunks",
+            "JOIN sources ON sources.id = chunks.source_id",
+            "WHERE chunks.source_id = ?",
+            "AND chunks.ordinal BETWEEN ? AND ?",
+            "ORDER BY chunks.ordinal"
+        ].join(" "))
+            .all(center.source_id, center.ordinal - before, center.ordinal + after);
+        for (const row of rows) {
+            this.trace.seenChunkIds.add(row.id);
+        }
+        return rows.map((row) => ({
+            chunkId: row.id,
+            path: row.relative_path,
+            ordinal: row.ordinal,
+            text: row.text,
+            locator: parseLocator(row.locator_json)
+        }));
+    }
+    async readSourceRangeFromSource(source, startLine, endLine) {
+        const filePath = path.join(this.root, source.relative_path);
+        const lines = (await readFile(filePath, "utf8"))
+            .replace(/\r\n?/gu, "\n")
+            .split("\n");
+        if (endLine > lines.length) {
+            throw new UserFacingError(`Line range ${String(startLine)}-${String(endLine)} is outside ${source.relative_path}.`);
+        }
+        const locator = {
+            type: "text",
+            path: source.relative_path,
+            startLine,
+            endLine
+        };
+        this.trace.readLocators.push(locator);
+        return {
+            path: source.relative_path,
+            startLine,
+            endLine,
+            text: lines.slice(startLine - 1, endLine).join("\n"),
+            locator
+        };
+    }
+    searchFtsCandidates(input, query, ftsQuery, limit) {
+        if (ftsQuery === "") {
+            return [];
+        }
+        const { filters, params } = buildSourceFilters(input, "sources", this.root);
+        filters.unshift("chunks_fts MATCH ?");
+        params.unshift(ftsQuery);
+        params.push(limit * 4);
+        const rows = this.database
+            .prepare([
+            "SELECT chunks.id AS chunk_id, chunks.source_id, sources.relative_path,",
+            "sources.kind, chunks.heading_path_json, chunks.locator_json,",
+            "chunks.text, bm25(chunks_fts) AS fts_rank,",
+            "snippet(chunks_fts, 1, '[', ']', '...', 12) AS snippet",
+            "FROM chunks_fts",
+            "JOIN chunks ON chunks.id = chunks_fts.chunk_id",
+            "JOIN sources ON sources.id = chunks.source_id",
+            `WHERE ${filters.join(" AND ")}`,
+            "ORDER BY fts_rank LIMIT ?"
+        ].join(" "))
+            .all(...params);
+        return rows.map((row) => this.toFtsCandidate(row, query));
+    }
+    searchVectorCandidates(input, query, limit) {
+        const { filters, params } = buildSourceFilters(input, "sources", this.root);
+        filters.unshift("embeddings.vector IS NOT NULL");
+        const rows = this.database
+            .prepare([
+            "SELECT chunks.id AS chunk_id, chunks.source_id, sources.relative_path,",
+            "sources.kind, chunks.heading_path_json, chunks.locator_json,",
+            "chunks.text, embeddings.vector, embeddings.metadata_json,",
+            "embeddings.dimensions",
+            "FROM embeddings",
+            "JOIN chunks ON chunks.id = embeddings.chunk_id",
+            "JOIN sources ON sources.id = chunks.source_id",
+            `WHERE ${filters.join(" AND ")}`,
+            "ORDER BY sources.relative_path, chunks.ordinal"
+        ].join(" "))
+            .all(...params);
+        const candidates = [];
+        const queryVectors = new Map();
+        for (const row of rows) {
+            if (row.vector === null) {
+                continue;
+            }
+            const metadata = parseEmbeddingMetadata(row.metadata_json, row.dimensions);
+            const cacheKey = `${String(metadata.dimensions)}:${String(metadata.normalize)}`;
+            let queryVector = queryVectors.get(cacheKey);
+            if (queryVector === undefined) {
+                queryVector = createDeterministicEmbeddingVector(query, metadata.dimensions);
+                if (metadata.normalize) {
+                    normalizeVector(queryVector);
+                }
+                queryVectors.set(cacheKey, queryVector);
+            }
+            const similarity = cosineSimilarity(queryVector, decodeVector(row.vector));
+            if (similarity <= 0) {
+                continue;
+            }
+            candidates.push(this.toVectorCandidate(row, similarity, query));
+        }
+        return candidates
+            .sort((left, right) => right.vectorScore - left.vectorScore)
+            .slice(0, limit * 4);
+    }
+    toFtsCandidate(row, query) {
+        const headingPath = parseHeadingPath(row.heading_path_json);
+        const locator = parseLocator(row.locator_json);
+        const ftsScore = 1 / (1 + Math.abs(row.fts_rank)) +
+            this.rankingAdjustments(row.relative_path, row.text, headingPath, query);
+        const mergedScore = mergeScoreForLocator(ftsScore, 0, locator);
+        return {
+            ftsScore,
+            vectorScore: 0,
+            result: {
+                chunkId: row.chunk_id,
+                sourceId: row.source_id,
+                path: row.relative_path,
+                kind: row.kind,
+                headingPath,
+                snippet: row.snippet,
+                score: mergedScore,
+                scores: {
+                    fts: ftsScore,
+                    vector: 0,
+                    merged: mergedScore
+                },
+                locator
+            }
+        };
+    }
+    toVectorCandidate(row, similarity, query) {
+        const headingPath = parseHeadingPath(row.heading_path_json);
+        const locator = parseLocator(row.locator_json);
+        const vectorScore = similarity +
+            this.rankingAdjustments(row.relative_path, row.text, headingPath, query);
+        const mergedScore = mergeScoreForLocator(0, vectorScore, locator);
+        return {
+            ftsScore: 0,
+            vectorScore,
+            result: {
+                chunkId: row.chunk_id,
+                sourceId: row.source_id,
+                path: row.relative_path,
+                kind: row.kind,
+                headingPath,
+                snippet: createSnippet(row.text),
+                score: mergedScore,
+                scores: {
+                    fts: 0,
+                    vector: vectorScore,
+                    merged: mergedScore
+                },
+                locator
+            }
+        };
+    }
+    expandNeighborCandidates(candidates, limit) {
+        const expanded = [...candidates];
+        const seenChunkIds = new Set(candidates.map((candidate) => candidate.result.chunkId));
+        const seedCandidates = candidates.slice(0, Math.min(limit, 3));
+        for (const candidate of seedCandidates) {
+            const center = this.getChunkById(candidate.result.chunkId);
+            const neighbors = this.getNeighborRows(center);
+            for (const neighbor of neighbors) {
+                if (neighbor.chunk_id === candidate.result.chunkId) {
+                    continue;
+                }
+                if (seenChunkIds.has(neighbor.chunk_id)) {
+                    continue;
+                }
+                seenChunkIds.add(neighbor.chunk_id);
+                expanded.push(this.toNeighborCandidate(neighbor, candidate));
+            }
+        }
+        return expanded;
+    }
+    getNeighborRows(center) {
+        return this.database
+            .prepare([
+            "SELECT chunks.id AS chunk_id, chunks.source_id, sources.relative_path,",
+            "sources.kind, chunks.heading_path_json, chunks.locator_json,",
+            "chunks.ordinal, chunks.text",
+            "FROM chunks",
+            "JOIN sources ON sources.id = chunks.source_id",
+            "WHERE chunks.source_id = ?",
+            "AND chunks.ordinal BETWEEN ? AND ?",
+            "ORDER BY chunks.ordinal"
+        ].join(" "))
+            .all(center.source_id, center.ordinal - 1, center.ordinal + 1);
+    }
+    toNeighborCandidate(row, sourceCandidate) {
+        const inheritedFtsScore = Math.max(0, sourceCandidate.ftsScore) * 0.65;
+        const inheritedVectorScore = Math.max(0, sourceCandidate.vectorScore) * 0.65;
+        const mergedScore = mergeScore(inheritedFtsScore, inheritedVectorScore);
+        return {
+            ftsScore: inheritedFtsScore,
+            vectorScore: inheritedVectorScore,
+            result: {
+                chunkId: row.chunk_id,
+                sourceId: row.source_id,
+                path: row.relative_path,
+                kind: row.kind,
+                headingPath: parseHeadingPath(row.heading_path_json),
+                snippet: createSnippet(row.text),
+                score: mergedScore,
+                contextOfChunkId: sourceCandidate.result.chunkId,
+                scores: {
+                    fts: inheritedFtsScore,
+                    vector: inheritedVectorScore,
+                    merged: mergedScore
+                },
+                locator: parseLocator(row.locator_json)
+            }
+        };
+    }
+    rankingAdjustments(relativePath, text, headingPath, query) {
+        return rankingAdjustments({
+            relativePath,
+            text,
+            headingPath,
+            query,
+            recentReadPaths: new Set(this.trace.readLocators.map((locator) => locator.path))
+        });
+    }
+    getSourceByPath(pathValue) {
+        const source = this.findSourceByPath(pathValue);
+        if (source === null) {
+            throw new UserFacingError(`Unknown indexed source: ${pathValue}`);
+        }
+        return source;
+    }
+    findSourceByPath(pathValue) {
+        if (pathValue.includes("..") || path.isAbsolute(pathValue)) {
+            throw new UserFacingError("Source path must be repository-relative.");
+        }
+        const source = this.database
+            .prepare([
+            "SELECT id, root, relative_path, kind, size_bytes, content_hash",
+            "FROM sources WHERE root = ? AND relative_path = ?"
+        ].join(" "))
+            .get(this.root, pathValue);
+        return source ?? null;
+    }
+    getChunkById(chunkId) {
+        const chunk = this.database
+            .prepare([
+            "SELECT chunks.id, chunks.source_id, sources.relative_path, chunks.ordinal,",
+            "chunks.text, chunks.locator_json, chunks.previous_chunk_id,",
+            "chunks.next_chunk_id",
+            "FROM chunks",
+            "JOIN sources ON sources.id = chunks.source_id",
+            "WHERE sources.root = ? AND chunks.id = ?"
+        ].join(" "))
+            .get(this.root, chunkId);
+        if (chunk === undefined) {
+            throw new UserFacingError(`Unknown chunk: ${chunkId}`);
+        }
+        return chunk;
+    }
+    getParserArtifacts(sourceId) {
+        return this.database
+            .prepare([
+            "SELECT kind, payload_json FROM parser_artifacts",
+            "WHERE source_id = ? ORDER BY kind, id"
+        ].join(" "))
+            .all(sourceId);
+    }
+    getPdfLocators(sourceId) {
+        const rows = this.database
+            .prepare("SELECT locator_json FROM chunks WHERE source_id = ? ORDER BY ordinal")
+            .all(sourceId);
+        return rows
+            .map((row) => parseLocator(row.locator_json))
+            .filter((locator) => locator.type === "pdf");
+    }
+}
+function buildSourceFilters(input, sourceAlias, root) {
+    const filters = [`${sourceAlias}.root = ?`];
+    const params = [root];
+    if (input.pathPrefix !== undefined) {
+        filters.push(`${sourceAlias}.relative_path LIKE ? ESCAPE '\\'`);
+        params.push(`${escapeLike(input.pathPrefix)}%`);
+    }
+    if (input.kind !== undefined) {
+        filters.push(`${sourceAlias}.kind = ?`);
+        params.push(input.kind);
+    }
+    return { filters, params };
+}
+function toListDocsResult(row) {
+    return {
+        sourceId: row.id,
+        path: row.relative_path,
+        kind: row.kind,
+        sizeBytes: row.size_bytes,
+        contentHash: row.content_hash
+    };
+}
+function mergeScore(ftsScore, vectorScore) {
+    return ftsScore + vectorScore * 2;
+}
+function mergeScoreForLocator(ftsScore, vectorScore, locator) {
+    return mergeScore(ftsScore, vectorScore) - pdfConfidencePenalty(locator);
+}
+function compareCandidates(left, right) {
+    return compareResults(left.result, right.result);
+}
+function compareResults(left, right) {
+    const scoreDifference = right.score - left.score;
+    if (scoreDifference !== 0) {
+        return scoreDifference;
+    }
+    const pathDifference = left.path.localeCompare(right.path);
+    if (pathDifference !== 0) {
+        return pathDifference;
+    }
+    return left.chunkId.localeCompare(right.chunkId);
+}
+function pdfConfidencePenalty(locator) {
+    if (locator.type !== "pdf") {
+        return 0;
+    }
+    const confidencePenalty = typeof locator.confidence === "number" && locator.confidence < 0.65
+        ? (0.65 - locator.confidence) * 1.5
+        : 0;
+    const warningPenalty = locator.warningCodes?.includes("pdf-low-confidence")
+        ? 0.75
+        : 0;
+    return confidencePenalty + warningPenalty;
+}
+function rankingAdjustments(input) {
+    const normalizedQuery = input.query.toLowerCase();
+    const queryTerms = tokenizeRankingText(input.query);
+    const queryTermSet = new Set(queryTerms);
+    const headingText = input.headingPath.join(" ").toLowerCase();
+    const headingTerms = new Set(tokenizeRankingText(headingText));
+    const sourceTitleTerms = new Set(tokenizeRankingText(sourceTitle(input.relativePath)));
+    const identifierMatches = input.query.match(/[A-Z][A-Z0-9_]{3,}/gu) ?? [];
+    const searchableText = `${input.relativePath}\n${headingText}\n${input.text}`;
+    const exactBoost = normalizedQuery !== "" && input.text.toLowerCase().includes(normalizedQuery)
+        ? 2
+        : 0;
+    const headingBoost = normalizedQuery !== "" && headingText.includes(normalizedQuery)
+        ? 1.25
+        : queryTermsMatch(headingTerms, queryTerms)
+            ? 0.9
+            : queryTermsContainAll(headingTerms, queryTermSet)
+                ? 0.8
+                : 0;
+    const sourceTitleBoost = queryTermsMatch(sourceTitleTerms, queryTerms)
+        ? 1.25
+        : queryTermsContainAll(sourceTitleTerms, queryTermSet)
+            ? 1.1
+            : queryTermsOverlap(sourceTitleTerms, queryTerms)
+                ? 0.4
+                : 0;
+    const identifierBoost = identifierMatches.some((identifier) => searchableText.includes(identifier))
+        ? 1.75
+        : 0;
+    const recentReadBoost = input.recentReadPaths.has(input.relativePath)
+        ? 0.75
+        : 0;
+    const genericPenalty = genericChunkPenalty(input, queryTerms);
+    const stalePenalty = /(legacy|deprecated|superseded|old)/iu.test(`${input.relativePath}\n${input.text}`)
+        ? 2
+        : 0;
+    return (exactBoost +
+        headingBoost +
+        sourceTitleBoost +
+        identifierBoost +
+        recentReadBoost -
+        genericPenalty -
+        stalePenalty);
+}
+function genericChunkPenalty(input, queryTerms) {
+    const headings = input.headingPath.map((heading) => heading.toLowerCase());
+    const lastHeading = headings.at(-1) ?? "";
+    const title = sourceTitle(input.relativePath).toLowerCase();
+    const genericHeadingPenalty = /^(overview|introduction|summary|general|notes|misc|reference)$/u.test(lastHeading) ||
+        /^(overview|introduction|summary|general|notes|misc|reference)$/u.test(title)
+        ? 1.2
+        : 0;
+    const textTerms = tokenizeRankingText(input.text);
+    const queryTermSet = new Set(queryTerms);
+    const queryDensity = textTerms.length === 0
+        ? 0
+        : textTerms.filter((term) => queryTermSet.has(term)).length /
+            textTerms.length;
+    const broadLanguagePenalty = /\b(common|general|various|multiple|several|everything|overview)\b/iu.test(input.text) && queryDensity < 0.2
+        ? 0.4
+        : 0;
+    return genericHeadingPenalty + broadLanguagePenalty;
+}
+function sourceTitle(relativePath) {
+    return path.basename(relativePath).replace(/\.[^.]+$/u, "");
+}
+function tokenizeRankingText(value) {
+    return value.toLowerCase().match(/[a-z0-9]+/gu) ?? [];
+}
+function queryTermsMatch(haystackTerms, queryTerms) {
+    return (queryTerms.length > 0 && queryTerms.every((term) => haystackTerms.has(term)));
+}
+function queryTermsOverlap(haystackTerms, queryTerms) {
+    return queryTerms.some((term) => haystackTerms.has(term));
+}
+function queryTermsContainAll(requiredTerms, queryTerms) {
+    return (requiredTerms.size > 1 &&
+        [...requiredTerms].every((term) => queryTerms.has(term)));
+}
+function parseEmbeddingMetadata(metadataJson, fallbackDimensions) {
+    try {
+        const parsed = JSON.parse(metadataJson);
+        return {
+            dimensions: typeof parsed.dimensions === "number"
+                ? parsed.dimensions
+                : fallbackDimensions,
+            normalize: typeof parsed.normalize === "boolean" ? parsed.normalize : true
+        };
+    }
+    catch {
+        return {
+            dimensions: fallbackDimensions,
+            normalize: true
+        };
+    }
+}
+function normalizeVector(vector) {
+    let magnitude = 0;
+    for (const value of vector) {
+        magnitude += value * value;
+    }
+    if (magnitude === 0) {
+        return;
+    }
+    const scale = 1 / Math.sqrt(magnitude);
+    for (let index = 0; index < vector.length; index += 1) {
+        vector[index] = (vector[index] ?? 0) * scale;
+    }
+}
+function cosineSimilarity(left, right) {
+    const length = Math.min(left.length, right.length);
+    let dot = 0;
+    let leftMagnitude = 0;
+    let rightMagnitude = 0;
+    for (let index = 0; index < length; index += 1) {
+        const leftValue = left[index] ?? 0;
+        const rightValue = right[index] ?? 0;
+        dot += leftValue * rightValue;
+        leftMagnitude += leftValue * leftValue;
+        rightMagnitude += rightValue * rightValue;
+    }
+    if (leftMagnitude === 0 || rightMagnitude === 0) {
+        return 0;
+    }
+    return dot / (Math.sqrt(leftMagnitude) * Math.sqrt(rightMagnitude));
+}
+function createSnippet(text) {
+    const normalized = text.replace(/\s+/gu, " ").trim();
+    if (normalized.length <= 240) {
+        return normalized;
+    }
+    return `${normalized.slice(0, 237)}...`;
+}
+function toFtsQuery(query) {
+    return (query
+        .match(/[A-Za-z0-9_./:-]+/gu)
+        ?.map((term) => `"${term.replace(/"/gu, '""')}"`)
+        .join(" OR ") ?? "");
+}
+function createMatcher(pattern, regex) {
+    if (!regex) {
+        return (line) => line.includes(pattern);
+    }
+    if (pattern.length > 128) {
+        throw new UserFacingError("regex pattern must be 128 characters or fewer.");
+    }
+    let expression;
+    try {
+        expression = new RegExp(pattern, "u");
+    }
+    catch (error) {
+        throw new UserFacingError("Invalid regex pattern.", error);
+    }
+    return (line) => expression.test(line);
+}
+function parseLocator(locatorJson) {
+    return JSON.parse(locatorJson);
+}
+function readGeneratedPdfMarkdown(artifacts, sourcePath) {
+    const payload = readArtifactPayload(artifacts, "generated-markdown");
+    if (!isRecord(payload) || typeof payload.markdown !== "string") {
+        throw new UserFacingError(`Generated PDF Markdown is unavailable for ${sourcePath}.`);
+    }
+    return payload.markdown;
+}
+function readArtifactPayload(artifacts, kind) {
+    const row = artifacts.find((artifact) => artifact.kind === kind);
+    if (row === undefined) {
+        return undefined;
+    }
+    return JSON.parse(row.payload_json);
+}
+function readArrayArtifactPayload(artifacts, kind) {
+    const payload = readArtifactPayload(artifacts, kind);
+    return Array.isArray(payload) ? payload : [];
+}
+function inferPdfPageCount(artifacts, locators) {
+    const diagnostics = readArtifactPayload(artifacts, "diagnostics");
+    const diagnosticPages = isRecord(diagnostics) ? diagnostics.pages : undefined;
+    const maxDiagnosticPage = Array.isArray(diagnosticPages) && diagnosticPages.length > 0
+        ? Math.max(...diagnosticPages.map((page) => isRecord(page) && typeof page.pageIndex === "number"
+            ? page.pageIndex + 1
+            : 0))
+        : 0;
+    const maxLocatorPage = Math.max(0, ...locators.map((locator) => locator.page));
+    return Math.max(maxDiagnosticPage, maxLocatorPage, 1);
+}
+function selectPdfLocator(input) {
+    if (input.page !== undefined && input.page > input.pageCount) {
+        throw new UserFacingError(`PDF page ${String(input.page)} is outside ${input.path}; page count is ${String(input.pageCount)}.`);
+    }
+    if (input.regionId !== undefined) {
+        const regionLocator = input.locators.find((locator) => locator.regionId === input.regionId);
+        if (regionLocator === undefined) {
+            throw new UserFacingError(`PDF region is not backed by the source map: ${input.regionId}`);
+        }
+        if (input.page !== undefined && regionLocator.page !== input.page) {
+            throw new UserFacingError(`PDF region ${input.regionId} is on page ${String(regionLocator.page)}, not page ${String(input.page)}.`);
+        }
+        return regionLocator;
+    }
+    const page = input.page ?? input.locators[0]?.page ?? 1;
+    return (input.locators.find((locator) => locator.page === page) ?? {
+        type: "pdf",
+        path: input.path,
+        page
+    });
+}
+function countMarkdownLines(markdown) {
+    return markdown.replace(/\r\n?/gu, "\n").split("\n").length;
+}
+function clampLine(line, lineCount) {
+    return Math.min(Math.max(line, 1), Math.max(lineCount, 1));
+}
+function sliceMarkdownLines(markdown, startLine, endLine) {
+    const lines = markdown.replace(/\r\n?/gu, "\n").split("\n");
+    return lines.slice(startLine - 1, endLine).join("\n");
+}
+function filterSourceMapEntries(sourceMap, locator) {
+    const entries = isRecord(sourceMap) ? sourceMap.entries : undefined;
+    if (!Array.isArray(entries)) {
+        return [];
+    }
+    return entries.filter((entry) => {
+        if (!isRecord(entry) || !Array.isArray(entry.regions)) {
+            return false;
+        }
+        return entry.regions.some((region) => isRecord(region) &&
+            typeof region.pageIndex === "number" &&
+            region.pageIndex + 1 === locator.page);
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function parseHeadingPath(headingPathJson) {
+    const parsed = JSON.parse(headingPathJson);
+    return Array.isArray(parsed) &&
+        parsed.every((item) => typeof item === "string")
+        ? parsed
+        : [];
+}
+function requireNonEmptyString(value, fieldName) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new UserFacingError(`${fieldName} must be a non-empty string.`);
+    }
+    return value;
+}
+function requirePositiveInteger(value, fieldName) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new UserFacingError(`${fieldName} must be a positive integer.`);
+    }
+    return value;
+}
+function clampLimit(value, defaultValue, max, min = 1) {
+    if (value === undefined) {
+        return defaultValue;
+    }
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new UserFacingError(`limit must be an integer between ${String(min)} and ${String(max)}.`);
+    }
+    return value;
+}
+function escapeLike(value) {
+    return value.replace(/[%_]/gu, (match) => `\\${match}`);
+}
+//# sourceMappingURL=tools.js.map