/**
 * Server-side classification route handler factory.
 *
 * Creates a POST handler that classifies uploaded documents via LLM analysis,
 * returning document type, tags, confidence, and optional metadata.
 *
 * Usage:
 *   import { create_classification_route } from 'hazo_collab_forms/lib';
 *   export const POST = create_classification_route({ hazo_connect_adapter: getHazoConnect() });
 *
 * Uses standard Web API Request/Response for portability.
 * hazo_llm_api is dynamically imported so it's only required at runtime.
 */
import 'server-only';
export type { ExpectedField, ExpectedFieldType, ClassificationDocumentType, } from '../components/thread_form/types.js';
import type { ClassificationDocumentType } from '../components/thread_form/types.js';
export interface ClassificationRouteOptions {
    /** Path to SQLite database for prompt library */
    sqlite_path?: string;
    /** Pre-configured hazo_connect adapter (takes precedence over sqlite_path) */
    hazo_connect_adapter?: unknown;
    /** Error handler */
    on_error?: (err: unknown, ctx: string) => void;
    /**
     * prompt_area for the classification prompt lookup. Default: 'document'.
     */
    prompt_area?: string;
    /**
     * prompt_key for the classification prompt lookup. Default: 'classification'.
     */
    prompt_key?: string;
}
export interface ClassificationAllowedTag {
    tag_id: string;
    tag_label: string;
    description?: string;
}
export interface ClassificationRequest {
    file_b64: string;
    file_name: string;
    mime_type: string;
    /**
     * Optional allow-list of document types. When provided, the LLM is
     * instructed to choose exactly one type_id from this list (or 'unknown'
     * if nothing fits). Substituted into the prompt as {{document_types}} and
     * {{document_type}} (the prompt uses both forms).
     */
    document_types?: ClassificationDocumentType[];
    /**
     * Optional allow-list of classification tags. When provided, the LLM is
     * instructed to use only these tag_ids. Rendered into {{tag_list}}.
     */
    available_tags?: ClassificationAllowedTag[];
    /**
     * Optional pre-rendered tag-list string. Takes precedence over
     * available_tags if both are supplied.
     */
    tag_list?: string;
    /**
     * Optional free-form client text to aid classification. Substituted into
     * the prompt as {{client_text}}.
     */
    client_text?: string;
}
export interface ClassificationTagReason {
    name: string;
    reason: string;
}
export interface ClassificationResponse {
    success: boolean;
    document_type?: string;
    tags?: string[];
    /** Per-tag reasons from the LLM, preserved for debug/review. */
    tag_reasons?: ClassificationTagReason[];
    confidence?: number;
    document_date?: string;
    document_nature?: string;
    /**
     * Structured monetary fields lifted out of the document during classification —
     * populated when the classification prompt asks for them (e.g. for invoice or
     * receipt doc types). Used by the aggregate sum_match resolver to compare
     * receipt totals against an expected amount.
     */
    extracted_fields?: {
        total?: number;
        date?: string;
        vendor?: string;
        property_address?: string;
        [key: string]: unknown;
    };
    error?: string;
}
/** Render the document-types list as a multi-line string for prompt substitution. */
declare function render_document_types(list: ClassificationDocumentType[] | undefined): string;
/** Build the `extracted_fields_instruction` prompt variable based on the supplied
 *  doctype list. Pure function, exported on `__test_only__` for unit testing. */
declare function build_extracted_fields_instruction(document_types: ClassificationDocumentType[] | undefined): string;
/** Substitute {{var}} placeholders. Unknown variables are left as-is. */
declare function substitute_variables(prompt: string, variables: Record<string, string>): string;
interface ParsedClassification {
    document_type: string;
    tags: string[];
    tag_reasons: ClassificationTagReason[];
    confidence: number;
    document_date?: string;
    document_nature?: string;
    extracted_fields?: {
        total?: number;
        date?: string;
        vendor?: string;
        property_address?: string;
        [key: string]: unknown;
    };
}
/**
 * Parse LLM response for classification results.
 *
 * The prompt asks for an array (one entry per file); for single-file
 * classification we take the first entry.
 */
declare function parse_classification_response(text: string): ParsedClassification;
/**
 * Creates a POST route handler for document classification.
 *
 * The handler:
 * 1. Validates the request payload
 * 2. Sends the document to an LLM for classification
 * 3. Parses the response into structured classification data
 * 4. Returns the classification result
 */
export declare function create_classification_route(options?: ClassificationRouteOptions): (request: Request) => Promise<Response>;
/** Internal API for tests. Not part of the public surface. */
export declare const __test_only__: {
    parse_classification_response: typeof parse_classification_response;
    render_document_types: typeof render_document_types;
    substitute_variables: typeof substitute_variables;
    build_extracted_fields_instruction: typeof build_extracted_fields_instruction;
};
//# sourceMappingURL=classification_handler.d.ts.map