/**
 * use_file_pipeline — orchestrates classification → validation for uploaded files.
 *
 * Phase 1 (client upload): classify → fetch immediate rules → validate
 * Phase 2 (agent review): fetch backoffice rules → validate
 */
import type { ContentItem, ClassificationResult, ClassificationDocumentType } from '../types.js';
import type { DocCheckData, AiContentResult } from '../types.js';
import type { ValidationRuleResult, ValidationGap } from '../../../types/validation.js';
import type { ExtractedResponseFields } from '../../../types/shared_data.js';
export type FileStatus = 'queued' | 'classifying' | 'validating' | 'done' | 'error';
/**
 * Per-file pipeline state. Carries the status enum plus optional metadata so
 * the UI can surface validation progress (rule count + names) instead of a
 * generic "Running validation rules…" placeholder.
 */
export interface FileStatusEntry {
    status: FileStatus;
    /** Total rules being run in the current validation phase. Set after rules
     *  are fetched, before the validate API call. */
    total_rules?: number;
    /** Rule display names. Used for hover-reveal in FileBar. */
    rule_names?: string[];
}
/**
 * Result of a per-group periodic_coverage rule execution. One entry per
 * (group_key, rule) pair. Consumer is responsible for surfacing these as
 * user-visible validations / clarifications.
 */
export interface GroupCoverageResult {
    /** Tag/group key files were grouped by */
    group_key: string;
    /** Document type that the rule matched on */
    document_type: string;
    /** Rule that produced these gaps */
    rule_id: string;
    /** Rule's display name (for UI) */
    rule_name: string;
    /** Custom message template from rule (consumer renders gaps with substitution).
     *  When undefined, consumer should use a default like:
     *  "Missing {{document_type}} for the period {{gap.start}} to {{gap.end}}." */
    custom_issue_description?: string;
    /** Detected gaps for this rule on this group */
    gaps: ValidationGap[];
    /** True when rule was skipped because period bounds did not resolve */
    skipped?: boolean;
}
export interface UseFilePipelineOptions {
    classification_api_url?: string;
    validation_api_url?: string;
    validation_rules_api_url?: string;
    content_gate_api_url?: string;
    /**
     * Optional endpoint that extracts structured fields (total, date, vendor)
     * from a response file — used by the sum_match resolver. When omitted, the
     * extract_response_fields method returns null and the resolver falls back to
     * "No total extracted" reporting.
     */
    response_extraction_api_url?: string;
    /**
     * Document-type allow-list passed to the classification API. When provided,
     * the LLM must pick a type_id from this list (or 'unknown'). Sourced from
     * the Document Types editor in the consuming app. Each entry may include
     * `expected_fields` to drive per-doctype field hints in both the prompt
     * and the inline renderer.
     */
    document_types?: ClassificationDocumentType[];
    /**
     * Classification-tag allow-list passed to the classification API. When
     * provided, the LLM must pick tag_ids from this list. Sourced from the Tag
     * Editor in the consuming app.
     */
    available_tags?: Array<{
        tag_id: string;
        tag_label: string;
        description?: string;
    }>;
    /**
     * File manager callbacks used by run_backoffice_validation to resolve a
     * download URL for each file. Required when the agent triggers backoffice
     * validation; can be omitted if that phase is never invoked.
     */
    file_manager?: import('../../../types/file_manager.js').FileManagerCallbacks;
    /** Activity log callback — receives short, human-readable pipeline events. */
    on_log?: (message: string) => void;
}
export interface UseFilePipelineReturn {
    /** Run classification + immediate validation on a file */
    process_file: (item: ContentItem, file_b64: string) => Promise<{
        classification: ClassificationResult | null;
        validation_results: ValidationRuleResult[];
        doc_check: DocCheckData | null;
        ai_result: AiContentResult | null;
    }>;
    /**
     * Extract structured monetary fields (total/date/vendor) from a response
     * file. Returns null when no extraction endpoint is configured or extraction
     * yields nothing — caller treats null as "no fields available". `file_b64`
     * is optional: pass it for fresh uploads where bytes are still in memory;
     * omit it for already-uploaded files (the server resolves bytes by file_id).
     */
    extract_response_fields: (file_id: string, file_b64: string | null, file_name: string, mime_type: string) => Promise<ExtractedResponseFields | null>;
    /** Run validation rules against text content */
    process_text: (message_id: string, text: string) => Promise<{
        validation_results: ValidationRuleResult[];
        doc_check: DocCheckData | null;
    }>;
    /**
     * Quick heuristic + LLM gate: decides whether a text message is worth
     * running through validation. Returns has_content=false for short or
     * conversational replies (so validation noise stays away from the client).
     */
    gate_text_content: (text: string) => Promise<{
        has_content: boolean;
        reason: string;
    }>;
    /** Run back-office validation on already-classified files */
    run_backoffice_validation: (items: ContentItem[]) => Promise<Map<string, {
        validation_results: ValidationRuleResult[];
        ai_result: AiContentResult;
    }>>;
    /**
     * Run per-group periodic_coverage rules across already-classified +
     * per-file-validated files. Groups files by classification primary tag
     * (or document_type) and detects coverage gaps against the rule's
     * cadence/alignment using each file's extracted period_start/period_end.
     */
    run_periodic_coverage_pass: (items: ContentItem[], ctx: import('../../../lib/resolve_variable.js').ResolveContext) => Promise<GroupCoverageResult[]>;
    /** Pipeline status + optional progress metadata per content_id */
    file_statuses: Map<string, FileStatusEntry>;
    /** Classification results per content_id */
    classification_results: Map<string, ClassificationResult>;
    /** Validation results per content_id */
    validation_results: Map<string, ValidationRuleResult[]>;
}
export declare function use_file_pipeline({ classification_api_url, validation_api_url, validation_rules_api_url, content_gate_api_url, response_extraction_api_url, document_types, available_tags, file_manager, on_log, }: UseFilePipelineOptions): UseFilePipelineReturn;
//# sourceMappingURL=use_file_pipeline.d.ts.map