@deepcitation/deepcitation-js 1.1.26 → 1.1.28

package/lib/prompts/citationPrompts.js

@@ -1,168 +0,0 @@
-export const CITATION_MARKDOWN_SYNTAX_PROMPT = `
-Citation syntax to use within Markdown:
-• To support any ideas or information that requires a citation from the provided content, use the following citation syntax:
-<cite attachment_id='attachment_id' start_page_key='page_number_PAGE_index_INDEX' full_phrase='the verbatim text of the terse phrase inside <attachment_text />; remember to escape quotes and newlines inside the full_phrase to remain as valid JSON' key_span='the verbatim 1-3 words within full_phrase that best support the citation' line_ids='2-6' reasoning='the terse logic used to conclude the citation' />
-
-• Very important: for page numbers, only use the page number and page index info from the page_number_PAGE_index_INDEX format (e.g. <page_number_1_index_0>) and never from the contents inside the page.
-• start_page_key, full_phrase, and line_ids are required for each citation.
-• Infer line_ids, as we only provide the first, last, and every 5th line. When copying a previous <cite />, use the full info from the previous citation without changing the start_page_key, line_ids, or any other <cite /> attributes.
-• Use refer to line_ids inclusively, and use a range (or single) for each citation, split multiple sequential line_ids into multiple citations.
-• These citations will be replaced and displayed in-line as a numeric element (e.g. [1]), the markdown preceding <cite /> should read naturally with only one <cite /> per sentence with rare exceptions for two <cite /> in a sentence. <cite /> often present best at the end of the sentence, and are not grouped at the end of the document.
-• The full_phrase should be the exact verbatim text of the phrase or paragraph from the source document to support the insight or idea.
-• We do NOT put the full_phrase inside <cite ...></cite>; we only use full_phrase inside the full_phrase attribute.
-`;
-export const AV_CITATION_MARKDOWN_SYNTAX_PROMPT = `
-• To support any ideas or information that requires a citation from the provided content, use the following citation syntax:
-<cite attachment_id='attachment_id' full_phrase='the verbatim text of the phrase; remember to escape quotes and newlines inside the full_phrase to remain as valid JSON' timestamps='HH:MM:SS.SSS-HH:MM:SS.SSS' reasoning='the logic connecting the form section requirements to the supporting source citation' />
-• These citations are displayed in-line or in the relevant list item, and are not grouped at the end of the document.
-`;
-/**
- * Wraps your existing system prompt with DeepCitation's citation syntax instructions.
- * This enables LLMs to output verifiable citations that can be checked against source documents.
- *
- * @example
- * ```typescript
- * import { wrapSystemCitationPrompt } from '@deepcitation/deepcitation-js';
- *
- * const systemPrompt = "You are a helpful assistant that analyzes documents.";
- * const enhanced = wrapSystemCitationPrompt({ systemPrompt });
- *
- * // Use enhanced prompt with your LLM
- * const response = await openai.chat.completions.create({
- *   messages: [{ role: "system", content: enhanced }],
- *   // ...
- * });
- * ```
- */
-export function wrapSystemCitationPrompt(options) {
-    const { systemPrompt, isAudioVideo = false, prependCitationInstructions = false, } = options;
-    const citationPrompt = isAudioVideo
-        ? AV_CITATION_MARKDOWN_SYNTAX_PROMPT
-        : CITATION_MARKDOWN_SYNTAX_PROMPT;
-    if (prependCitationInstructions) {
-        return `${citationPrompt.trim()}
-
-${systemPrompt.trim()}`;
-    }
-    //append
-    return `${systemPrompt.trim()}
-
-${citationPrompt.trim()}`;
-}
-/**
- * Wraps both system and user prompts with DeepCitation's citation syntax instructions.
- * This is the recommended way to prepare prompts for citation verification.
- *
- * @example
- * ```typescript
- * import { wrapCitationPrompt } from '@deepcitation/deepcitation-js';
- *
- * // Single file
- * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
- *   systemPrompt: "You are a helpful assistant.",
- *   userPrompt: "Analyze this document and summarize it.",
- *   deepTextPromptPortion, // from uploadFile response
- * });
- *
- * // Multiple files
- * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
- *   systemPrompt: "You are a helpful assistant.",
- *   userPrompt: "Compare these documents.",
- *   deepTextPromptPortion: [deepTextPromptPortion1, deepTextPromptPortion2], // array of file texts
- * });
- *
- * // Use enhanced prompts with your LLM
- * const response = await llm.chat({
- *   messages: [
- *     { role: "system", content: enhancedSystemPrompt },
- *     { role: "user", content: enhancedUserPrompt },
- *   ],
- * });
- * ```
- */
-export function wrapCitationPrompt(options) {
-    const { systemPrompt, userPrompt, deepTextPromptPortion, isAudioVideo = false, } = options;
-    const enhancedSystemPrompt = wrapSystemCitationPrompt({
-        systemPrompt,
-        isAudioVideo,
-    });
-    // Build enhanced user prompt with file content if provided
-    let enhancedUserPrompt = userPrompt;
-    if (deepTextPromptPortion) {
-        const fileTexts = Array.isArray(deepTextPromptPortion)
-            ? deepTextPromptPortion
-            : [deepTextPromptPortion];
-        const fileContent = fileTexts
-            .map((text, index) => {
-            if (fileTexts.length === 1) {
-                return `\n${text}`;
-            }
-            return `\n${text}`;
-        })
-            .join("\n\n");
-        enhancedUserPrompt = `${fileContent}\n\n${userPrompt}`;
-    }
-    return {
-        enhancedSystemPrompt,
-        enhancedUserPrompt,
-    };
-}
-export const CITATION_JSON_OUTPUT_FORMAT = {
-    type: "object",
-    properties: {
-        attachmentId: { type: "string" },
-        startPageKey: {
-            type: "string",
-            description: 'Only return a result like "page_number_PAGE_index_INDEX" from the provided page keys (e.g. <page_number_1_index_0>) and never from the contents inside the page.',
-        },
-        reasoning: {
-            type: "string",
-            description: "The logic connecting the form section requirements to the supporting source citation",
-        },
-        fullPhrase: {
-            type: "string",
-            description: "The verbatim text of the terse phrase inside <attachment_text /> to support the citation (if there is a detected OCR correction, use the corrected text)",
-        },
-        keySpan: {
-            type: "string",
-            description: "the verbatim 1-3 words within fullPhrase that best support the citation",
-        },
-        lineIds: {
-            type: "array",
-            items: { type: "number" },
-            description: "Infer lineIds, as we only provide the first, last, and every 5th line. Provide inclusive lineIds for the fullPhrase.",
-        },
-    },
-    required: [
-        "attachmentId",
-        "startPageKey",
-        "reasoning",
-        "fullPhrase",
-        "keySpan",
-        "lineIds",
-    ],
-};
-export const CITATION_AV_BASED_JSON_OUTPUT_FORMAT = {
-    type: "object",
-    properties: {
-        attachmentId: { type: "string" },
-        startPageKey: {
-            type: "string",
-            description: 'Only return a result like "page_number_PAGE_index_INDEX" from the provided page keys (e.g. <page_number_1_index_0>) and never from the contents inside the page.',
-        },
-        fullPhrase: {
-            type: "string",
-            description: "The exact verbatim text of the phrase or paragraph from the source document to support the citation (if there is a detected OCR correction, use the verbatim corrected text)",
-        },
-        timestamps: {
-            type: "object",
-            properties: {
-                startTime: { type: "string" },
-                endTime: { type: "string" },
-            },
-            required: ["startTime", "endTime"],
-            description: "The timestamp of the audio or video frame including milliseconds formatted as: HH:MM:SS.SSS",
-        },
-    },
-    required: ["attachmentId", "startPageKey", "fullPhrase", "timestamps"],
-};

package/lib/prompts/promptCompression.d.ts

@@ -1,14 +0,0 @@
-import { CompressedResult } from "./types.js";
-/**
- * Compress all occurrences of `ids` inside `obj`, returning a new object
- * plus the `prefixMap` needed to decompress.
- */
-export declare function compressPromptIds<T>(obj: T, ids: string[] | undefined): CompressedResult<T>;
-/**
- * Decompress all minimal prefixes back into their full IDs,
- * using the `prefixMap` returned from `compressPromptIds`.
- *
- * If you pass in a string, it will return a string.
- * If you pass in an object, it will JSON‑serialize and parse it back.
- */
-export declare function decompressPromptIds<T>(compressed: T | string, prefixMap: Record<string, string>): T | string;

package/lib/prompts/promptCompression.js

@@ -1,127 +0,0 @@
-const MIN_PREFIX_LENGTH = 4;
-const MIN_CHARACTERS_PER_PREFIX_WITH_AT_LEAST_ONE_DIGIT = 3;
-const MIN_CHARACTERS_PER_PREFIX_WITH_NO_DIGITS = 5;
-/**
- * Build a map from each ID's minimal unique prefix to the full ID,
- * such that the prefix only ever appears in the prompt where the full ID appears.
- */
-function buildSafePrefixMap(ids, prompt) {
-    const map = {};
-    for (const id of ids) {
-        for (let len = MIN_PREFIX_LENGTH; len <= id.length; len++) {
-            const prefix = id.slice(0, len);
-            // Check minimum requirements
-            const digitCount = (prefix.match(/\d/g) || []).length;
-            const letterCount = (prefix.match(/[a-zA-Z]/g) || []).length;
-            if (prefix.length < MIN_PREFIX_LENGTH ||
-                (digitCount > 0 &&
-                    letterCount < MIN_CHARACTERS_PER_PREFIX_WITH_AT_LEAST_ONE_DIGIT) ||
-                (digitCount === 0 &&
-                    letterCount < MIN_CHARACTERS_PER_PREFIX_WITH_NO_DIGITS)) {
-                continue;
-            }
-            // 1) Unique among IDs
-            if (ids.some((other) => other !== id && other.startsWith(prefix))) {
-                continue;
-            }
-            // 2) Only appears in prompt as part of the full ID
-            const esc = (s) => s.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
-            const prefixCount = (prompt.match(new RegExp(esc(prefix), "g")) || [])
-                .length;
-            const fullCount = (prompt.match(new RegExp(esc(id), "g")) || []).length;
-            if (prefixCount !== fullCount) {
-                continue;
-            }
-            map[prefix] = id;
-            break;
-        }
-        if (!Object.values(map).includes(id)) {
-            throw new Error(`Cannot find a safe unique prefix for ID "${id}" that meets the minimum requirements (length: ${MIN_PREFIX_LENGTH})`);
-        }
-    }
-    return map;
-}
-/**
- * Compress all occurrences of `ids` inside `obj`, returning a new object
- * plus the `prefixMap` needed to decompress.
- */
-export function compressPromptIds(obj, ids) {
-    if (!ids || ids.length === 0) {
-        return { compressed: obj, prefixMap: {} };
-    }
-    const uniqueIds = Array.from(new Set(ids));
-    const text = JSON.stringify(obj);
-    const prefixMap = buildSafePrefixMap(uniqueIds, text);
-    // Sort prefixes by descending length to avoid partial matches
-    const prefixes = Object.keys(prefixMap).sort((a, b) => b.length - a.length);
-    let compressedText = text;
-    for (const prefix of prefixes) {
-        const full = prefixMap[prefix];
-        const escFull = full.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
-        compressedText = compressedText.replace(new RegExp(escFull, "g"), prefix);
-    }
-    return {
-        compressed: JSON.parse(compressedText),
-        prefixMap,
-    };
-}
-/**
- * Decompress all minimal prefixes back into their full IDs,
- * using the `prefixMap` returned from `compressPromptIds`.
- *
- * If you pass in a string, it will return a string.
- * If you pass in an object, it will JSON‑serialize and parse it back.
- */
-export function decompressPromptIds(compressed, prefixMap) {
-    if (!prefixMap || Object.keys(prefixMap).length === 0) {
-        return compressed;
-    }
-    // Prepare sorted [prefix, full] entries (longest prefix first)
-    const entries = Object.entries(prefixMap).sort((a, b) => b[0].length - a[0].length);
-    // Decide whether we're working on a string or an object
-    let text;
-    let shouldParseBack = false;
-    if (typeof compressed === "string") {
-        text = compressed;
-    }
-    else {
-        text = JSON.stringify(compressed);
-        shouldParseBack = true;
-    }
-    const originalLength = text?.length;
-    // Perform all prefix → full-ID replacements
-    for (const [prefix, full] of entries) {
-        const escPrefix = prefix.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
-        text = text.replace(new RegExp(escPrefix, "g"), full);
-    }
-    // Handle cases where the LLM may output ID in a different attribute format
-    // We look for common ID attribute patterns and replace compressed prefixes within them
-    // Note: fileId variants are supported for backwards compatibility with legacy citations
-    const idAttributeKeys = [
-        "attachmentId",
-        "attachment_id",
-        "attachment_ID",
-        "attachmentID",
-        "fileId",
-        "file_id",
-        "file_ID",
-        "fileID",
-        "fileid",
-    ];
-    // For each prefix, look for it within ID attribute values and replace with full ID
-    for (const [prefix, full] of entries) {
-        const escPrefix = prefix.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
-        const keyPattern = idAttributeKeys.join("|");
-        const quotePattern = "([\"'`])";
-        // Match: attributeName = 'prefix' or attributeName="prefix" etc.
-        // Only replace the prefix part, preserving the attribute name and quotes
-        const re = new RegExp(`(${keyPattern})(\\s*=\\s*)${quotePattern}${escPrefix}\\3`, "g");
-        text = text.replace(re, `$1$2$3${full}$3`);
-    }
-    const newLength = text?.length;
-    const diff = originalLength - newLength;
-    if (diff > 0) {
-        throw new Error(`[decompressedPromptIds] diff ${diff} originalLength ${originalLength} newLength ${newLength}`);
-    }
-    return shouldParseBack ? JSON.parse(text) : text;
-}

package/lib/prompts/types.d.ts

@@ -1,4 +0,0 @@
-export interface CompressedResult<T> {
-    compressed: T;
-    prefixMap: Record<string, string>;
-}

package/lib/prompts/types.js

@@ -1 +0,0 @@
-export {};

package/lib/react/CitationComponent.d.ts

@@ -1,93 +0,0 @@
-import React from "react";
-import { type CitationStatus } from "../types/citation.js";
-import type { Verification } from "../types/verification.js";
-import type { BaseCitationProps, CitationBehaviorConfig, CitationEventHandlers, CitationRenderProps, CitationVariant } from "./types.js";
-export type { CitationVariant } from "./types.js";
-/**
- * Props for the CitationComponent.
- *
- * ## Behavior
- *
- * Default interaction pattern:
- * - **Hover**: Shows popover with verification image/details
- * - **Click**: Opens full-size image overlay (zoom)
- * - **Escape / Click outside / Click overlay**: Closes image overlay
- *
- * Custom behavior:
- * - Use `behaviorConfig.onClick` to replace the default click behavior
- * - Use `eventHandlers.onClick` to add side effects (disables default)
- *
- * @example Default usage
- * ```tsx
- * <CitationComponent
- *   citation={citation}
- *   verification={verification}
- * />
- * ```
- *
- * @example Custom click behavior
- * ```tsx
- * <CitationComponent
- *   citation={citation}
- *   verification={verification}
- *   behaviorConfig={{
- *     onClick: (context) => {
- *       // Custom action
- *       console.log('Clicked:', context.citationKey);
- *       return { setImageExpanded: true };
- *     }
- *   }}
- * />
- * ```
- */
-export interface CitationComponentProps extends BaseCitationProps {
-    /** Verification result from the DeepCitation API */
-    verification?: Verification | null;
-    /**
-     * Display variant for the citation.
-     * - `brackets`: [keySpan✓] with styling (default)
-     * - `text`: keySpan✓ inherits parent styling
-     * - `minimal`: text with indicator, no brackets
-     * - `indicator`: only the status indicator
-     */
-    variant?: CitationVariant;
-    /** Hide square brackets (only for brackets variant) */
-    hideBrackets?: boolean;
-    /** Event handlers for citation interactions */
-    eventHandlers?: CitationEventHandlers;
-    /**
-     * Configuration for customizing default click/hover behaviors.
-     * Providing onClick REPLACES the default click behavior.
-     */
-    behaviorConfig?: CitationBehaviorConfig;
-    /** Enable mobile touch handlers */
-    isMobile?: boolean;
-    /** Custom render function for the status indicator */
-    renderIndicator?: (status: CitationStatus) => React.ReactNode;
-    /** Custom render function for entire citation content */
-    renderContent?: (props: CitationRenderProps) => React.ReactNode;
-    /** Position of popover. Use "hidden" to disable. */
-    popoverPosition?: "top" | "bottom" | "hidden";
-    /** Custom render function for popover content */
-    renderPopoverContent?: (props: {
-        citation: BaseCitationProps["citation"];
-        verification: Verification | null;
-        status: CitationStatus;
-    }) => React.ReactNode;
-}
-/**
- * CitationComponent displays a citation with verification status.
- *
- * ## Interaction Pattern
- *
- * - **Hover**: Shows popover with verification image or details
- * - **Click**: Opens full-size image overlay (if image available)
- * - **Escape / Click overlay**: Closes the image overlay
- *
- * ## Customization
- *
- * Use `behaviorConfig.onClick` to completely replace the click behavior,
- * or `eventHandlers.onClick` to add side effects (which disables defaults).
- */
-export declare const CitationComponent: React.ForwardRefExoticComponent<CitationComponentProps & React.RefAttributes<HTMLSpanElement>>;
-export declare const MemoizedCitationComponent: React.NamedExoticComponent<CitationComponentProps & React.RefAttributes<HTMLSpanElement>>;