/**
 * Citation management utilities for tracking and deduplicating citations.
 *
 * Port of `backend/agent/citations.py` and `backend/agent/tools/process_citations.py`
 * to TypeScript. Produces identical IDs via djb2 hash for cross-language compatibility.
 *
 * Citations have numeric string IDs that can be inlined in LLM messages using
 * {{citation-ID}} syntax so the frontend can render source links.
 */
export interface WebCitation {
    type: 'web';
    id: string;
    url: string;
    title: string;
    citedText: string;
}
export interface DocumentCitation {
    type: 'document';
    id: string;
    title: string;
    citedText: string;
    pageStart?: number | null;
    pageEnd?: number | null;
}
export type Citation = WebCitation | DocumentCitation;
/** Draft citation before ID assignment. */
export type DraftWebCitation = Omit<WebCitation, 'id'>;
export type DraftDocumentCitation = Omit<DocumentCitation, 'id'>;
export type DraftCitation = DraftWebCitation | DraftDocumentCitation;
export interface AnthropicPageLocationCitation {
    type: 'page_location';
    cited_text: string;
    document_title: string | null;
    start_page_number: number;
    end_page_number: number;
}
export interface AnthropicCharLocationCitation {
    type: 'char_location';
    cited_text?: string;
    document_title?: string | null;
    start_char_index: number;
    end_char_index: number;
}
export interface AnthropicWebSearchResultLocationCitation {
    type: 'web_search_result_location' | 'web_location';
    cited_text?: string;
    url?: string;
    title?: string;
}
export type AnthropicCitation = AnthropicPageLocationCitation | AnthropicCharLocationCitation | AnthropicWebSearchResultLocationCitation;
export interface AnthropicTextBlock {
    type: 'text';
    text: string;
    citations?: AnthropicCitation[];
}
export type AnthropicContentBlock = string | AnthropicTextBlock | Record<string, unknown>;
/**
 * djb2 hash algorithm — matches Python implementation for cross-language compatibility.
 *
 * CRITICAL: Python uses `& 0xFFFFFFFF` to mask to 32-bit unsigned and then `abs()`.
 * JavaScript's bitwise `<<` operates on signed 32-bit ints. We use `>>> 0` to
 * convert to unsigned 32-bit, matching Python's `& 0xFFFFFFFF` + `abs()` behavior.
 */
export declare function createTextHash(text: string): number;
/**
 * Generate source key for deduplication and ordering.
 * Matches Python's `get_source_key()` exactly.
 */
export declare function getSourceKey(citation: DraftCitation): string;
/**
 * Generate a citation ID from the citation's source key hash.
 * Produces the same numeric string as Python's `get_citation_id()`.
 */
export declare function getCitationId(citation: DraftCitation): string;
/**
 * Format a single citation ID for inline embedding in message text.
 * Example: formatInlineCitation("1240308948") => "{{citation-1240308948}}"
 */
export declare function formatInlineCitation(id: string): string;
/**
 * Format multiple citations for appending after a text block.
 * Matches Python's `format_inline_citations_for_text_block()`.
 */
export declare function formatInlineCitations(citations: Citation[]): string;
export interface ProcessCitationsResult {
    contentWithCitations: string;
    citations: Record<string, Citation>;
}
/**
 * Process Anthropic API content blocks to extract citations and format inline markers.
 *
 * Takes the `content` array from an Anthropic API response and returns:
 * - `contentWithCitations`: the concatenated text with {{citation-ID}} markers appended
 *   after each text block that has citations
 * - `citations`: a deduped map of citation ID -> Citation object
 *
 * Handles three Anthropic citation types:
 * - `page_location` — PDF page citations
 * - `char_location` — character-offset citations (with optional <!--page=N--> markers)
 * - `web_search_result_location` / `web_location` — web search citations
 *
 * The LLM proxy emits `content_block` SSE events when text blocks carry
 * citation arrays from Anthropic's API, which are accumulated and passed here.
 */
export declare function processAnthropicCitations(contentBlocks: string | AnthropicContentBlock[] | null | undefined): ProcessCitationsResult;
/**
 * Merge new citations into an existing citations record, deduplicating by ID.
 * Returns the merged record (mutates `existing` for efficiency).
 */
export declare function mergeCitations(existing: Record<string, Citation>, incoming: Record<string, Citation>): Record<string, Citation>;
//# sourceMappingURL=citations.d.ts.map