@geotechcli/core 0.4.21 → 0.4.23

package/dist/ingest/geotech-document.js

@@ -0,0 +1,1006 @@
+import { resolveProviderCapabilities } from '../llm/index.js';
+import { extractGeotechDocumentFactsFromText, interpretGeotechDocumentPage, } from '../vision/geotech-document.js';
+import { transcribeDocumentImageText } from '../vision/index.js';
+import { recoverDocumentTextHint } from '../vision/ocr.js';
+function uniqueStrings(values) {
+    return [...new Set(values.filter((value) => typeof value === 'string' && value.trim().length > 0))];
+}
+function createFindingKey(finding) {
+    return [
+        finding.severity,
+        finding.scope,
+        finding.code,
+        finding.message,
+        finding.pageNumber ?? '',
+        finding.materialDescription ?? '',
+    ].join('|');
+}
+function uniqueFindings(findings) {
+    const seen = new Set();
+    const unique = [];
+    for (const finding of findings) {
+        const key = createFindingKey(finding);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        unique.push(finding);
+    }
+    return unique;
+}
+function findingRequiresReview(finding) {
+    return finding.severity !== 'advisory';
+}
+function summarizeReviewReasons(findings) {
+    return uniqueStrings(findings
+        .filter(findingRequiresReview)
+        .map((finding) => finding.message));
+}
+function normalizePageErrorMessage(message) {
+    let normalized = message.trim();
+    for (let index = 0; index < 4; index += 1) {
+        const updated = normalized.replace(/^Page \d+:\s*/i, '').trim();
+        if (updated === normalized) {
+            break;
+        }
+        normalized = updated;
+    }
+    return normalized;
+}
+function summarizeInspection(inspection, ocrRecoveredPageCount = 0) {
+    if (!inspection) {
+        return null;
+    }
+    const counts = {};
+    let imageHeavyPageCount = 0;
+    let nativeTextPageCount = 0;
+    let degradedPageCount = 0;
+    for (const page of inspection.pages) {
+        counts[page.classification] = (counts[page.classification] ?? 0) + 1;
+        if (page.classification === 'image-only' || page.classification === 'text-unreadable') {
+            imageHeavyPageCount += 1;
+        }
+        if (page.capabilities.nativeTextExtraction !== 'unavailable') {
+            nativeTextPageCount += 1;
+        }
+        if (page.degradation.level !== 'none') {
+            degradedPageCount += 1;
+        }
+    }
+    return {
+        pageClassificationCounts: counts,
+        imageHeavyPageCount,
+        nativeTextPageCount,
+        degradedPageCount,
+        ocrRecoveredPageCount,
+    };
+}
+function buildInspectionWarnings(inspection) {
+    if (!inspection) {
+        return [];
+    }
+    const warnings = [...inspection.warnings];
+    for (const page of inspection.pages) {
+        if (page.classification === 'image-only' || page.classification === 'text-unreadable') {
+            warnings.push(`PDF page ${page.pageNumber} is ${page.classification}. Native text was not recovered from the PDF parser, so OCR-style transcription may be needed.`);
+        }
+    }
+    return uniqueStrings(warnings);
+}
+function mergeParseStatus(statuses) {
+    if (statuses.length === 0) {
+        return 'failed';
+    }
+    if (statuses.every((status) => status === 'parsed')) {
+        return 'parsed';
+    }
+    if (statuses.some((status) => status !== 'failed')) {
+        return 'partial';
+    }
+    return 'failed';
+}
+function mergeMaterials(results) {
+    const seen = new Set();
+    const materials = [];
+    for (const result of results) {
+        for (const material of result.materials) {
+            const key = [
+                material.kind,
+                material.description.toLowerCase(),
+                material.uscsSymbol ?? '',
+                material.lithology?.toLowerCase() ?? '',
+            ].join('|');
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            materials.push(material);
+        }
+    }
+    return materials;
+}
+function mergeClassifications(results) {
+    const seen = new Set();
+    const classifications = [];
+    for (const result of results) {
+        for (const classification of result.classifications) {
+            const key = [
+                classification.system.toLowerCase(),
+                classification.value.toLowerCase(),
+                classification.context?.toLowerCase() ?? '',
+            ].join('|');
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            classifications.push(classification);
+        }
+    }
+    return classifications;
+}
+function mergeParameters(results) {
+    const seen = new Set();
+    const parameters = [];
+    for (const result of results) {
+        for (const parameter of result.parameters) {
+            const key = [
+                parameter.name.toLowerCase(),
+                parameter.valueText.toLowerCase(),
+                parameter.unit?.toLowerCase() ?? '',
+                parameter.material?.toLowerCase() ?? '',
+                parameter.context?.toLowerCase() ?? '',
+            ].join('|');
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            parameters.push(parameter);
+        }
+    }
+    return parameters;
+}
+function resolvePageConcurrency(config, requestedConcurrency) {
+    if (requestedConcurrency != null && Number.isFinite(requestedConcurrency)) {
+        return Math.max(1, Math.min(4, Math.trunc(requestedConcurrency)));
+    }
+    const capabilities = resolveProviderCapabilities(config);
+    if (config.provider === 'hosted-beta') {
+        return 2;
+    }
+    return capabilities.visionImages ? 3 : 2;
+}
+async function mapWithConcurrency(items, concurrency, mapper) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const currentIndex = nextIndex;
+            nextIndex += 1;
+            results[currentIndex] = await mapper(items[currentIndex], currentIndex);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, items.length || 1)) }, () => worker()));
+    return results;
+}
+async function withPageTimeout(task, timeoutMs, message) {
+    let handle = null;
+    try {
+        return await Promise.race([
+            task,
+            new Promise((_, reject) => {
+                handle = setTimeout(() => reject(new Error(message)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (handle) {
+            clearTimeout(handle);
+        }
+    }
+}
+function resolvePagePhaseTimeoutMs(config, input) {
+    const baseTimeoutMs = Math.min(Math.max(config.timeout ?? 120000, 60000), 120000);
+    const isHeavyVisualPage = input.sourceKind === 'raster-image'
+        || input.classification === 'image-only'
+        || input.classification === 'text-unreadable';
+    return isHeavyVisualPage
+        ? Math.min(Math.max(baseTimeoutMs, 180000), 180000)
+        : baseTimeoutMs;
+}
+function resolveTextExtractionTimeoutMs(baseTimeoutMs, textHint) {
+    if (!textHint) {
+        return baseTimeoutMs;
+    }
+    if (textHint.length >= 1800) {
+        return Math.min(Math.max(baseTimeoutMs, 150000), 180000);
+    }
+    if (textHint.length >= 1000) {
+        return Math.max(baseTimeoutMs, 120000);
+    }
+    return baseTimeoutMs;
+}
+function normalizeHeadingText(value) {
+    return value
+        .toLowerCase()
+        .replace(/\s+/g, ' ')
+        .replace(/[^\w\s:/()-]+/g, '')
+        .trim();
+}
+function buildHeadingKey(headings) {
+    return headings
+        .map(normalizeHeadingText)
+        .filter(Boolean)
+        .join(' > ');
+}
+function collectResultTextSignals(result) {
+    return [
+        result.title,
+        result.summary,
+        ...result.materials.map((material) => material.description),
+        ...result.classifications.map((classification) => `${classification.system} ${classification.value}${classification.context ? ` ${classification.context}` : ''}`.trim()),
+        ...result.parameters.map((parameter) => `${parameter.name} ${parameter.valueText}${parameter.unit ? ` ${parameter.unit}` : ''}${parameter.context ? ` ${parameter.context}` : ''}`.trim()),
+        ...result.risks,
+        ...result.recommendations,
+    ]
+        .filter((value) => typeof value === 'string' && value.trim().length > 0)
+        .join('\n')
+        .trim();
+}
+function inferChunkScope(inspectionPage) {
+    return inspectionPage?.normalizedArtifact?.tablesDetected
+        ? 'table'
+        : inspectionPage?.normalizedArtifact?.figuresDetected
+            ? 'figure'
+            : (inspectionPage?.normalizedArtifact?.headingHints.length ?? 0) > 0
+                ? 'section'
+                : 'page';
+}
+function inferSectionType(input) {
+    if (input.result.documentClass === 'administrative-document') {
+        return 'administrative';
+    }
+    if (input.result.documentClass === 'visual-appendix-document') {
+        return 'visual-appendix';
+    }
+    const leadingSignalText = buildPageLeadText(input.inspectionPage, {
+        bodyLineLimit: 8,
+        bodyCharacterLimit: 420,
+        acceptedOnly: true,
+    }).toLowerCase();
+    const signalText = [
+        input.result.title,
+        input.result.summary,
+        ...(input.inspectionPage?.normalizedArtifact?.headingHints ?? []),
+        input.inspectionPage?.normalizedArtifact?.nativeText ?? '',
+    ]
+        .filter((value) => typeof value === 'string' && value.trim().length > 0)
+        .join('\n')
+        .toLowerCase();
+    const extractedEngineeringSignals = input.result.materials.length > 0
+        || input.result.classifications.length > 0
+        || input.result.parameters.length > 0;
+    const pageEngineeringSignals = hasEngineeringPageSignals(input.inspectionPage);
+    const hasMeaningfulEngineeringSignals = extractedEngineeringSignals || pageEngineeringSignals;
+    if (!hasMeaningfulEngineeringSignals
+        && /\b(cover|title page|document control|distribution|revision|issue register|transmittal|copyright|prepared for|prepared by|checked by|approved by|table of contents|contents)\b/.test(leadingSignalText)) {
+        return 'administrative';
+    }
+    if (/\b(executive summary|summary|conclusion|overview|scope of works?)\b/.test(signalText)) {
+        return 'summary';
+    }
+    if (input.result.recommendations.length > 0 || /\b(recommend|mitigation|next step|monitor|confirm|verify|further investigation)\b/.test(signalText)) {
+        return 'recommendation';
+    }
+    if (/\b(groundwater|water table|seepage|piezometric|aquifer|dewatering)\b/.test(signalText)) {
+        return 'groundwater';
+    }
+    if (input.result.classifications.length > 0
+        || /\b(uscs|rmr|rqd|q-system|classification)\b/.test(signalText)) {
+        return 'classification';
+    }
+    if (input.result.materials.length > 0
+        || /\b(geology|geological|lithology|lithological|strata|stratigraphy|formation|borehole|ground conditions?|subsurface|rock mass|weathered|fill|standard penetration test|spt|field methods?)\b/.test(signalText)) {
+        return 'ground-model';
+    }
+    if (input.result.parameters.length > 0
+        || /\b(laboratory|lab report|triaxial|atterberg|plasticity|permeability|moisture content|ucs|uniaxial|direct shear|ccil|chain of custody)\b/.test(signalText)) {
+        return 'laboratory';
+    }
+    if (!hasMeaningfulEngineeringSignals
+        && (input.scope === 'figure'
+            || /\b(figure|fig\.|plate|photo|sketch|section view|appendix|appendices|photo log|drawing)\b/.test(leadingSignalText))) {
+        return 'visual-appendix';
+    }
+    return 'general';
+}
+function scoreChunkSignificance(input) {
+    let score = 0;
+    score += Math.min(16, input.result.materials.length * 3);
+    score += Math.min(15, input.result.classifications.length * 4);
+    score += Math.min(24, input.result.parameters.length * 5);
+    score += Math.min(8, input.result.risks.length * 2);
+    score += Math.min(8, input.result.recommendations.length * 2);
+    if (input.result.summary) {
+        score += 6;
+    }
+    if (input.result.parseStatus === 'parsed') {
+        score += 8;
+    }
+    else if (input.result.parseStatus === 'partial') {
+        score += 3;
+    }
+    switch (input.sectionType) {
+        case 'ground-model':
+            score += 12;
+            break;
+        case 'laboratory':
+            score += 14;
+            break;
+        case 'classification':
+            score += 10;
+            break;
+        case 'groundwater':
+            score += 9;
+            break;
+        case 'recommendation':
+            score += 7;
+            break;
+        case 'summary':
+            score += 5;
+            break;
+        case 'visual-appendix':
+            score -= 6;
+            break;
+        case 'administrative':
+            score -= 18;
+            break;
+        default:
+            break;
+    }
+    if (input.scope === 'table') {
+        score += 5;
+    }
+    else if (input.scope === 'figure') {
+        score -= 4;
+    }
+    return Math.max(0, Math.min(100, score));
+}
+function buildPreparedPageChunks(results, inspection) {
+    return results
+        .filter((result) => result.pageNumber != null)
+        .map((result) => {
+        const pageNumber = result.pageNumber ?? 0;
+        const inspectionPage = inspection?.pages[pageNumber - 1];
+        const text = collectResultTextSignals(result);
+        const scope = inferChunkScope(inspectionPage);
+        const sectionType = inferSectionType({ result, inspectionPage, scope });
+        const significance = scoreChunkSignificance({ result, scope, sectionType });
+        return {
+            chunkId: `page-${pageNumber}`,
+            pageRange: [pageNumber, pageNumber],
+            headingAncestry: inspectionPage?.normalizedArtifact?.headingHints ?? [],
+            scope,
+            sectionType,
+            significance,
+            text,
+            sourcePages: [pageNumber],
+            documentClass: result.documentClass,
+            title: result.title,
+            summary: result.summary,
+        };
+    })
+        .filter((chunk) => chunk.text.trim().length > 0);
+}
+function shouldMergePreparedChunks(previous, current) {
+    if (current.pageRange[0] !== previous.pageRange[1] + 1) {
+        return false;
+    }
+    if (previous.sectionType !== current.sectionType) {
+        return false;
+    }
+    if (previous.sectionType === 'administrative'
+        || previous.sectionType === 'visual-appendix'
+        || previous.scope === 'figure'
+        || current.scope === 'figure') {
+        return false;
+    }
+    const previousHeadingKey = buildHeadingKey(previous.headingAncestry);
+    const currentHeadingKey = buildHeadingKey(current.headingAncestry);
+    if (previousHeadingKey && currentHeadingKey) {
+        return previousHeadingKey === currentHeadingKey;
+    }
+    return previous.scope === current.scope;
+}
+function mergePreparedChunks(chunks) {
+    const merged = [];
+    for (const chunk of chunks) {
+        const previous = merged[merged.length - 1];
+        if (!previous || !shouldMergePreparedChunks(previous, chunk)) {
+            merged.push({
+                ...chunk,
+                sourcePages: [...chunk.sourcePages],
+            });
+            continue;
+        }
+        previous.chunkId = `${previous.chunkId}+${chunk.chunkId}`;
+        previous.pageRange = [previous.pageRange[0], chunk.pageRange[1]];
+        previous.sourcePages = [...new Set([...previous.sourcePages, ...chunk.sourcePages])];
+        previous.headingAncestry = previous.headingAncestry.length >= chunk.headingAncestry.length
+            ? previous.headingAncestry
+            : chunk.headingAncestry;
+        previous.text = `${previous.text}\n\n${chunk.text}`.trim();
+        previous.significance = Math.min(100, previous.significance + chunk.significance);
+        if (!previous.summary && chunk.summary) {
+            previous.summary = chunk.summary;
+        }
+        if (!previous.title && chunk.title) {
+            previous.title = chunk.title;
+        }
+        if (!previous.documentClass && chunk.documentClass) {
+            previous.documentClass = chunk.documentClass;
+        }
+        if (previous.scope === 'page' && chunk.scope === 'section') {
+            previous.scope = 'section';
+        }
+        if (previous.scope === 'page' && chunk.scope === 'table') {
+            previous.scope = 'table';
+        }
+    }
+    return merged;
+}
+function buildContentChunks(results, inspection) {
+    return mergePreparedChunks(buildPreparedPageChunks(results, inspection));
+}
+function isGenericDocumentTitle(value) {
+    if (!value?.trim()) {
+        return true;
+    }
+    return /\b(cover sheet|cover page|table of contents|contents|appendix|drawing register|revision history|project information)\b/i.test(value);
+}
+function chooseDocumentClass(chunks) {
+    const scores = new Map();
+    const firstMeaningfulClass = chunks.find((chunk) => chunk.sectionType !== 'administrative'
+        && chunk.sectionType !== 'visual-appendix'
+        && typeof chunk.documentClass === 'string'
+        && chunk.documentClass.trim().length > 0
+        && chunk.documentClass.toLowerCase() !== 'unknown')?.documentClass?.trim() ?? null;
+    for (const chunk of chunks) {
+        const documentClass = chunk.documentClass?.trim();
+        if (!documentClass || documentClass.toLowerCase() === 'unknown') {
+            continue;
+        }
+        const weight = chunk.sectionType === 'administrative' || chunk.sectionType === 'visual-appendix'
+            ? 0
+            : Math.max(1, chunk.significance);
+        if (weight === 0) {
+            continue;
+        }
+        scores.set(documentClass, (scores.get(documentClass) ?? 0)
+            + weight
+            - (documentClass === 'geotechnical-document' ? 3 : 0));
+    }
+    const ranked = [...scores.entries()].sort((left, right) => right[1] - left[1]);
+    if (ranked.length === 0) {
+        return firstMeaningfulClass;
+    }
+    if (firstMeaningfulClass
+        && ranked.length > 1
+        && ranked[0][1] - ranked[1][1] <= 12) {
+        return firstMeaningfulClass;
+    }
+    return ranked[0]?.[0] ?? firstMeaningfulClass;
+}
+function chooseDocumentTitle(chunks) {
+    return [...chunks]
+        .sort((left, right) => right.significance - left.significance)
+        .map((chunk) => chunk.title)
+        .find((value) => typeof value === 'string' && value.trim().length > 0 && !isGenericDocumentTitle(value))
+        ?? null;
+}
+function chooseDocumentSummary(chunks) {
+    const ranked = [...chunks]
+        .filter((chunk) => chunk.sectionType !== 'administrative')
+        .sort((left, right) => right.significance - left.significance);
+    const summaries = uniqueStrings(ranked
+        .map((chunk) => chunk.summary)
+        .filter((value) => typeof value === 'string' && value.trim().length > 0)).slice(0, 3);
+    return summaries.length > 0 ? summaries.join(' ') : null;
+}
+function buildPageLeadText(inspectionPage, options) {
+    if (!inspectionPage) {
+        return '';
+    }
+    const bodyLineLimit = options?.bodyLineLimit ?? 8;
+    const bodyCharacterLimit = options?.bodyCharacterLimit ?? 480;
+    const acceptedOnly = options?.acceptedOnly ?? false;
+    const accepted = inspectionPage.normalizedArtifact?.textQuality.accepted ?? false;
+    const nativeText = acceptedOnly && !accepted
+        ? ''
+        : inspectionPage.normalizedArtifact?.nativeText
+            ?? inspectionPage.normalizedText
+            ?? '';
+    const bodyPreview = nativeText
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(0, bodyLineLimit)
+        .join('\n')
+        .slice(0, bodyCharacterLimit);
+    return uniqueStrings([
+        ...(inspectionPage.normalizedArtifact?.headingHints ?? []),
+        bodyPreview,
+    ])
+        .join('\n')
+        .trim();
+}
+function hasEngineeringPageSignals(inspectionPage) {
+    if (!inspectionPage) {
+        return false;
+    }
+    if (inspectionPage.normalizedArtifact?.tablesDetected) {
+        return true;
+    }
+    const cueText = buildPageLeadText(inspectionPage, {
+        bodyLineLimit: 18,
+        bodyCharacterLimit: 1200,
+        acceptedOnly: false,
+    }).toLowerCase();
+    return /\b(bh\d{1,5}[a-z0-9-]*|borehole|northing|easting|elevation|masl|m asl|standard penetration test|spt|astm|soil sample|laboratory|triaxial|consolidation|plasticity|liquid limit|grain size|shear|friction angle|cohesion|unit weight|moisture content|permeability|groundwater|rqd|rmr|q-system|ucs)\b/.test(cueText);
+}
+function inferNonCriticalPageRole(inspectionPage) {
+    if (!inspectionPage) {
+        return null;
+    }
+    const engineeringSignals = hasEngineeringPageSignals(inspectionPage);
+    const headingText = buildPageLeadText(inspectionPage, {
+        bodyLineLimit: 6,
+        bodyCharacterLimit: 360,
+        acceptedOnly: true,
+    }).toLowerCase();
+    if (!engineeringSignals
+        && /\b(cover|title page|table of contents|contents|document control|revision|distribution|transmittal|copyright)\b/.test(headingText)) {
+        return 'administrative';
+    }
+    if (!engineeringSignals
+        && (inspectionPage.normalizedArtifact?.figuresDetected
+            || /\b(appendix|figure|fig\.|plate|photo|sketch|drawing)\b/.test(headingText))) {
+        return 'visual-appendix';
+    }
+    return null;
+}
+function inferAppendixDividerRole(inspectionPage) {
+    if (!inspectionPage) {
+        return null;
+    }
+    const leadText = buildPageLeadText(inspectionPage, {
+        bodyLineLimit: 6,
+        bodyCharacterLimit: 320,
+        acceptedOnly: true,
+    }).toLowerCase();
+    if (!leadText || !/\bappendix\b/.test(leadText)) {
+        return null;
+    }
+    if (/\b(figures?|plates?|photos?|photographs?|drawings?|plans?|sketches?|site layout)\b/.test(leadText)) {
+        return 'visual-appendix';
+    }
+    if (/\b(record of boreholes?|borehole logs?|borehole records?|test pits?|cpt|cone penetration)\b/.test(leadText)) {
+        return null;
+    }
+    return null;
+}
+export function inferPreflightLowYieldPageRole(input) {
+    const explicitRole = inferNonCriticalPageRole(input.inspectionPage);
+    if (explicitRole) {
+        return explicitRole;
+    }
+    const inspectionPage = input.inspectionPage;
+    if (!inspectionPage) {
+        return null;
+    }
+    if (inspectionPage.classification === 'empty') {
+        return input.pageNumber === 1 ? 'administrative' : 'visual-appendix';
+    }
+    const wordCount = inspectionPage.metadata?.wordCount ?? 0;
+    const textSource = inspectionPage.normalizedArtifact?.textSource;
+    const previousDividerRole = inferAppendixDividerRole(input.previousInspectionPage);
+    if (input.pageNumber === 1
+        && inspectionPage.classification === 'image-only'
+        && textSource === 'native-text-low-quality'
+        && wordCount > 0
+        && wordCount <= 80
+        && !inspectionPage.normalizedArtifact?.tablesDetected
+        && !inspectionPage.normalizedArtifact?.figuresDetected) {
+        return 'administrative';
+    }
+    if (previousDividerRole === 'visual-appendix'
+        && (inspectionPage.classification === 'image-only' || inspectionPage.classification === 'graphics-only')
+        && textSource === 'native-text-low-quality'
+        && wordCount <= 120
+        && !hasEngineeringPageSignals(inspectionPage)) {
+        return 'visual-appendix';
+    }
+    if (inspectionPage.classification === 'graphics-only'
+        && input.pageNumber === input.totalPages) {
+        return 'visual-appendix';
+    }
+    if (inspectionPage.classification === 'graphics-only'
+        && input.sourceKind === 'raster-image'
+        && wordCount <= 80) {
+        return 'visual-appendix';
+    }
+    return null;
+}
+export function buildPreflightLowYieldInsight(input) {
+    const headingSummary = buildPageLeadText(input.inspectionPage, {
+        bodyLineLimit: 6,
+        bodyCharacterLimit: 200,
+        acceptedOnly: true,
+    })
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 200);
+    const title = input.role === 'administrative'
+        ? headingSummary || 'Administrative / cover page'
+        : headingSummary || 'Figure / appendix page';
+    const summary = input.role === 'administrative'
+        ? `Page ${input.pageNumber} of ${input.totalPages} appears to be an administrative or cover-style page. No reliable engineering data was extracted, so this page was summarized without an expensive vision pass.`
+        : `Page ${input.pageNumber} of ${input.totalPages} appears to be a graphics or appendix page. It was summarized as low-yield visual content without a full multimodal extraction pass.`;
+    const warnings = [
+        input.role === 'administrative'
+            ? 'Low-yield administrative/cover page was short-circuited before multimodal extraction.'
+            : 'Low-yield figure/appendix page was short-circuited before multimodal extraction.',
+    ];
+    return {
+        documentClass: input.role === 'administrative' ? 'administrative-document' : 'visual-appendix-document',
+        title,
+        summary,
+        materials: [],
+        classifications: [],
+        parameters: [],
+        risks: [],
+        recommendations: [],
+        pageNumber: input.pageNumber,
+        totalPages: input.totalPages,
+        rawLLMText: '',
+        latencyMs: 0,
+        parseStatus: 'partial',
+        confidence: input.role === 'administrative' ? 48 : 55,
+        warnings,
+        canAutoProceed: false,
+    };
+}
+function deriveDocumentFindings(results, pageFailures, materials, classifications, parameters, inspection) {
+    const findings = [];
+    const hasEngineeringContent = materials.length > 0 || classifications.length > 0 || parameters.length > 0;
+    for (const result of results) {
+        const inspectionPage = result.pageNumber != null ? inspection?.pages[result.pageNumber - 1] : undefined;
+        const nonCriticalRole = inferPreflightLowYieldPageRole({
+            inspectionPage,
+            pageNumber: result.pageNumber,
+            totalPages: result.totalPages,
+        });
+        if (result.parseStatus === 'failed') {
+            findings.push({
+                code: nonCriticalRole === 'administrative' ? 'administrative_page_low_yield' : nonCriticalRole === 'visual-appendix' ? 'visual_appendix_low_yield' : 'page_geotech_extraction_failed',
+                severity: nonCriticalRole && hasEngineeringContent ? 'advisory' : 'blocking',
+                scope: 'page',
+                message: nonCriticalRole === 'administrative'
+                    ? `Page ${result.pageNumber ?? '?'} looked administrative (cover/contents/control) and did not contribute engineering content.`
+                    : nonCriticalRole === 'visual-appendix'
+                        ? `Page ${result.pageNumber ?? '?'} looked like a figure/appendix page and did not contribute structured engineering content.`
+                        : `Page ${result.pageNumber ?? '?'} did not yield usable geotechnical content.`,
+                pageNumber: result.pageNumber ?? undefined,
+            });
+            continue;
+        }
+        if (result.parseStatus === 'partial' || result.confidence < 60) {
+            findings.push({
+                code: nonCriticalRole === 'administrative' ? 'administrative_page_partial' : nonCriticalRole === 'visual-appendix' ? 'visual_appendix_partial' : 'page_geotech_extraction_partial',
+                severity: nonCriticalRole ? 'advisory' : 'review',
+                scope: 'page',
+                message: nonCriticalRole === 'administrative'
+                    ? `Page ${result.pageNumber ?? '?'} appears administrative and produced only low-yield extraction output.`
+                    : nonCriticalRole === 'visual-appendix'
+                        ? `Page ${result.pageNumber ?? '?'} appears to be a figure/appendix page and produced only partial engineering yield.`
+                        : `Page ${result.pageNumber ?? '?'} produced partial or low-confidence geotechnical interpretation.`,
+                pageNumber: result.pageNumber ?? undefined,
+            });
+        }
+    }
+    for (const failure of pageFailures) {
+        const pageNumber = Number((failure.match(/^Page (\d+):/) ?? [])[1]);
+        const isTimeout = /timed out/i.test(failure);
+        const inspectionPage = Number.isFinite(pageNumber) ? inspection?.pages[pageNumber - 1] : undefined;
+        const nonCriticalRole = inferPreflightLowYieldPageRole({
+            inspectionPage,
+            pageNumber: Number.isFinite(pageNumber) ? pageNumber : null,
+            totalPages: inspection?.totalPages ?? null,
+        });
+        findings.push({
+            code: nonCriticalRole === 'administrative'
+                ? 'administrative_page_failed'
+                : nonCriticalRole === 'visual-appendix'
+                    ? (isTimeout ? 'visual_appendix_timeout' : 'visual_appendix_failed')
+                    : isTimeout
+                        ? 'visual_page_timeout'
+                        : 'page_ingest_failed',
+            severity: nonCriticalRole && hasEngineeringContent
+                ? 'advisory'
+                : isTimeout
+                    ? 'review'
+                    : 'blocking',
+            scope: 'page',
+            message: nonCriticalRole === 'administrative'
+                ? `${failure} This page appears administrative and was downgraded from a blocking failure.`
+                : nonCriticalRole === 'visual-appendix'
+                    ? `${failure} This page appears to be a figure/appendix page and was downgraded from a blocking failure.`
+                    : failure,
+            pageNumber: Number.isFinite(pageNumber) ? pageNumber : undefined,
+        });
+    }
+    if (materials.length === 0 && classifications.length === 0 && parameters.length === 0) {
+        findings.push({
+            code: 'no_geotech_content_detected',
+            severity: 'blocking',
+            scope: 'document',
+            message: 'No usable geology, lithology, or geotechnical engineering parameters were extracted from the supplied pages.',
+        });
+    }
+    else if (parameters.length === 0) {
+        findings.push({
+            code: 'parameters_not_detected',
+            severity: 'review',
+            scope: 'document',
+            message: 'Ground descriptions were found, but no explicit engineering parameters were extracted. Manual review may still be needed.',
+        });
+    }
+    else if (classifications.length === 0) {
+        findings.push({
+            code: 'classifications_not_detected',
+            severity: 'advisory',
+            scope: 'document',
+            message: 'Engineering parameters were found, but no formal soil/rock classification was extracted.',
+        });
+    }
+    return uniqueFindings(findings);
+}
+export async function ingestGeotechDocument(options) {
+    const interpretPage = options.interpretPage ?? interpretGeotechDocumentPage;
+    const extractTextFacts = options.extractTextFacts ?? extractGeotechDocumentFactsFromText;
+    const transcribePageImageText = options.transcribePageImageText ?? transcribeDocumentImageText;
+    const now = options.now ?? (() => new Date());
+    if (!options.image && (!options.pages || options.pages.length === 0)) {
+        throw new Error('Geotechnical document ingest requires either a single image input or one or more PDF page inputs.');
+    }
+    const pageAudits = [];
+    const pageFailures = [];
+    const pageResults = [];
+    const documentWarnings = buildInspectionWarnings(options.inspection);
+    const recoveredOcrPages = new Set();
+    const pageConcurrency = resolvePageConcurrency(options.config, options.pageConcurrency);
+    if (options.pages && options.pages.length > 0) {
+        const pages = [...options.pages].sort((left, right) => left.pageNumber - right.pageNumber);
+        const settledPages = await mapWithConcurrency(pages, pageConcurrency, async (page) => {
+            const inspectionPage = options.inspection?.pages[page.pageNumber - 1];
+            const lowYieldRole = inferPreflightLowYieldPageRole({
+                inspectionPage,
+                pageNumber: page.pageNumber,
+                totalPages: page.totalPages,
+                sourceKind: page.sourceKind,
+            });
+            let pageTextHint = inspectionPage?.normalizedArtifact?.nativeText
+                ?? inspectionPage?.normalizedText
+                ?? undefined;
+            let textHintSource = pageTextHint?.trim() ? 'native-text' : 'none';
+            try {
+                if (lowYieldRole && inspectionPage) {
+                    return {
+                        ok: true,
+                        pageNumber: page.pageNumber,
+                        inspectionPage,
+                        textHintSource,
+                        recoveryWarnings: [
+                            lowYieldRole === 'administrative'
+                                ? 'Administrative/cover page was summarized without a full multimodal extraction call.'
+                                : 'Figure/appendix page was summarized without a full multimodal extraction call.',
+                        ],
+                        ocrRecovered: false,
+                        result: buildPreflightLowYieldInsight({
+                            role: lowYieldRole,
+                            inspectionPage,
+                            pageNumber: page.pageNumber,
+                            totalPages: page.totalPages,
+                        }),
+                    };
+                }
+                const pageTimeoutMs = resolvePagePhaseTimeoutMs(options.config, {
+                    classification: inspectionPage?.classification,
+                    sourceKind: page.sourceKind,
+                });
+                const pagePhaseConfig = {
+                    ...options.config,
+                    timeout: pageTimeoutMs,
+                };
+                const recovery = await withPageTimeout(recoverDocumentTextHint({
+                    existingTextHint: pageTextHint,
+                    existingTextAccepted: inspectionPage?.normalizedArtifact?.textQuality.accepted ?? true,
+                    imageBase64: page.base64,
+                    mimeType: page.mimeType,
+                    config: pagePhaseConfig,
+                    pdfFilePath: page.filePath,
+                    pdfPageNumber: page.pageNumber,
+                    visionTranscribe: transcribePageImageText,
+                }), pageTimeoutMs, `Page ${page.pageNumber}: OCR/text recovery timed out after ${Math.round(pageTimeoutMs / 1000)}s`);
+                if (recovery.textHint) {
+                    pageTextHint = recovery.textHint;
+                }
+                textHintSource = recovery.source;
+                const context = {
+                    pageNumber: page.pageNumber,
+                    totalPages: page.totalPages,
+                    pageClassification: inspectionPage?.classification,
+                    pageTextHint,
+                };
+                const extractionTimeoutMs = resolveTextExtractionTimeoutMs(pageTimeoutMs, pageTextHint);
+                const extractionConfig = {
+                    ...options.config,
+                    timeout: extractionTimeoutMs,
+                };
+                const result = pageTextHint
+                    ? await withPageTimeout(extractTextFacts(pageTextHint, extractionConfig, context), extractionTimeoutMs, `Page ${page.pageNumber}: text extraction timed out after ${Math.round(extractionTimeoutMs / 1000)}s`)
+                    : await withPageTimeout(interpretPage(page.base64, page.mimeType, pagePhaseConfig, context), pageTimeoutMs, `Page ${page.pageNumber}: visual page interpretation timed out after ${Math.round(pageTimeoutMs / 1000)}s`);
+                return {
+                    ok: true,
+                    pageNumber: page.pageNumber,
+                    inspectionPage,
+                    textHintSource,
+                    recoveryWarnings: recovery.warnings,
+                    ocrRecovered: recovery.source === 'local-ocr' || recovery.source === 'vision-ocr',
+                    result,
+                };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    pageNumber: page.pageNumber,
+                    inspectionPage,
+                    textHintSource,
+                    error: normalizePageErrorMessage(error instanceof Error ? error.message : String(error)),
+                };
+            }
+        });
+        settledPages.sort((left, right) => left.pageNumber - right.pageNumber);
+        for (const settled of settledPages) {
+            if (settled.ok) {
+                if (settled.ocrRecovered) {
+                    recoveredOcrPages.add(settled.pageNumber);
+                    documentWarnings.push(`Recovered ${settled.textHintSource === 'local-ocr' ? 'local OCR' : 'OCR-style'} text hint for page ${settled.pageNumber}.`);
+                }
+                else if (settled.textHintSource === 'pdfjs-text') {
+                    documentWarnings.push(`Recovered high-fidelity PDF text for page ${settled.pageNumber} without a multimodal OCR call.`);
+                }
+                documentWarnings.push(...settled.recoveryWarnings.map((warning) => `Page ${settled.pageNumber}: ${warning}`));
+                pageResults.push(settled.result);
+                pageAudits.push({
+                    pageNumber: settled.pageNumber,
+                    classification: settled.inspectionPage?.classification ?? null,
+                    textHintSource: settled.textHintSource,
+                    parseStatus: settled.result.parseStatus,
+                    confidence: settled.result.confidence,
+                    materialCount: settled.result.materials.length,
+                    classificationCount: settled.result.classifications.length,
+                    parameterCount: settled.result.parameters.length,
+                    warnings: uniqueStrings([
+                        ...settled.recoveryWarnings,
+                        ...settled.result.warnings,
+                    ]),
+                });
+                continue;
+            }
+            pageFailures.push(`Page ${settled.pageNumber}: ${settled.error}`);
+            pageAudits.push({
+                pageNumber: settled.pageNumber,
+                classification: settled.inspectionPage?.classification ?? null,
+                textHintSource: settled.textHintSource,
+                parseStatus: 'failed',
+                confidence: 0,
+                materialCount: 0,
+                classificationCount: 0,
+                parameterCount: 0,
+                warnings: [settled.error],
+            });
+        }
+    }
+    else if (options.image) {
+        const result = await interpretPage(options.image.base64, options.image.mimeType, options.config, { pageNumber: 1, totalPages: 1 });
+        pageResults.push(result);
+        pageAudits.push({
+            pageNumber: 1,
+            classification: null,
+            textHintSource: 'none',
+            parseStatus: result.parseStatus,
+            confidence: result.confidence,
+            materialCount: result.materials.length,
+            classificationCount: result.classifications.length,
+            parameterCount: result.parameters.length,
+            warnings: result.warnings,
+        });
+    }
+    if (pageResults.length === 0) {
+        throw new Error(pageFailures.length > 0
+            ? `No pages could be ingested successfully.\n${pageFailures.join('\n')}`
+            : 'No pages could be ingested successfully.');
+    }
+    const materials = mergeMaterials(pageResults);
+    const classifications = mergeClassifications(pageResults);
+    const parameters = mergeParameters(pageResults);
+    const risks = uniqueStrings(pageResults.flatMap((result) => result.risks));
+    const recommendations = uniqueStrings(pageResults.flatMap((result) => result.recommendations));
+    const summaries = uniqueStrings(pageResults.map((result) => result.summary));
+    const contentChunks = buildContentChunks(pageResults, options.inspection);
+    const title = chooseDocumentTitle(contentChunks);
+    const documentClass = chooseDocumentClass(contentChunks);
+    const partialAuditCount = pageAudits.filter((audit) => audit.parseStatus === 'partial').length;
+    const failedAuditCount = pageAudits.filter((audit) => audit.parseStatus === 'failed').length;
+    const parseStatus = pageFailures.length > 0
+        ? 'partial'
+        : mergeParseStatus(pageResults.map((result) => result.parseStatus));
+    const baseConfidence = Math.round(pageResults.reduce((sum, result) => sum + result.confidence, 0) / pageResults.length);
+    const failurePenalty = Math.min(30, failedAuditCount * 12);
+    const partialPenalty = Math.min(18, partialAuditCount * 6);
+    const confidenceCap = failedAuditCount > 0
+        ? 68
+        : partialAuditCount > 0
+            ? 78
+            : 100;
+    const confidence = Math.max(0, Math.min(confidenceCap, Math.round(baseConfidence - failurePenalty - partialPenalty)));
+    const reviewFindings = deriveDocumentFindings(pageResults, pageFailures, materials, classifications, parameters, options.inspection);
+    const reviewRequired = reviewFindings.some(findingRequiresReview);
+    const allPagesParsed = pageAudits.length > 0 && pageAudits.every((audit) => audit.parseStatus === 'parsed');
+    const warnings = uniqueStrings([
+        ...documentWarnings,
+        ...pageResults.flatMap((result) => result.warnings),
+    ]);
+    return {
+        kind: 'geotech-ingest-result',
+        schemaVersion: 1,
+        documentType: 'geotech-document',
+        generatedAt: now().toISOString(),
+        source: {
+            ...options.source,
+            totalPages: options.pages?.length ?? 1,
+            successfulPages: pageResults.length,
+            failedPages: pageFailures.length,
+        },
+        inspection: options.inspection ?? null,
+        inspectionSummary: summarizeInspection(options.inspection, recoveredOcrPages.size),
+        documentClass,
+        title,
+        summary: chooseDocumentSummary(contentChunks) ?? (summaries.length > 0 ? summaries.join(' ') : null),
+        materials,
+        classifications,
+        parameters,
+        risks,
+        recommendations,
+        contentChunks: contentChunks.map((chunk) => ({
+            chunkId: chunk.chunkId,
+            pageRange: chunk.pageRange,
+            headingAncestry: chunk.headingAncestry,
+            scope: chunk.scope,
+            sectionType: chunk.sectionType,
+            significance: chunk.significance,
+            text: chunk.text,
+            sourcePages: chunk.sourcePages,
+        })),
+        pageAudits,
+        pageFailures,
+        warnings,
+        reviewFindings,
+        reviewReasons: summarizeReviewReasons(reviewFindings),
+        parseStatus,
+        confidence,
+        reviewRequired,
+        canAutoProceed: !reviewRequired && parseStatus === 'parsed' && confidence >= 70 && allPagesParsed && pageFailures.length === 0,
+    };
+}
+//# sourceMappingURL=geotech-document.js.map