@deepcitation/deepcitation-js 1.1.49 → 1.1.51

package/lib/prompts/index.d.ts

@@ -1,14 +1,48 @@
-declare const CITATION_MARKDOWN_SYNTAX_PROMPT = "\n<citation-instructions priority=\"critical\">\n## REQUIRED: Citation Format\n\n### Scope (Where to use)\nFor every claim, value, or fact in your chat response; you MUST cite the attachment using this exact syntax:\n\n<cite attachment_id='ID' reasoning='why this supports the claim' full_phrase='verbatim quote' key_span='1-3 key words' start_page_key='page_number_N_index_I' line_ids='X-Y' />\n\n### Syntax Rules (MUST follow)\n\n1. **attachment_id**: Use the exact ID from the source document\n2. **reasoning**: Brief explanation of why this citation supports your claim (think first!)\n3. **full_phrase**: Copy text VERBATIM from source. Escape quotes (\\') and newlines (\\n).\n4. **key_span**: The 1-3 most important words or value from full_phrase\n5. **start_page_key**: ONLY use format `page_number_N_index_I` from page tags (e.g., `<page_number_1_index_0>`). Never extract page numbers from document content.\n6. **line_ids**: Inclusive range (e.g., '2-6' or '4'). Infer intermediate lines since only every 5th line is shown.\n\n### Placement Rules\n\n- Place <cite /> inline, typically at the end of a claim\n- One citation per distinct idea, concept, or value (a sentence citing 3 different values needs 3 citations)\n- Do NOT group citations at the end of the document\n- The <cite /> tag is self-closing - never use <cite>...</cite>\n\n### Example Citation 1\n\nThe company reported strong growth<cite attachment_id='abc123' reasoning='directly states revenue growth percentage' full_phrase='Revenue increased 45% year-over-year to $2.3 billion' key_span='increased 45%' start_page_key='page_number_2_index_1' line_ids='12-14' />\n\n### Example Citation 2\n\nThe total amount is $500 USD <cite attachment_id='abc123' reasoning='directly states the total amount' full_phrase='The total amount is $500 USD' key_span='$500 USD' start_page_key='page_number_2_index_1' line_ids='12-14' />\n</citation-instructions>\n\n";
-declare const AV_CITATION_MARKDOWN_SYNTAX_PROMPT = "\n<citation-instructions priority=\"critical\">\n## REQUIRED: Audio/Video Citation Format\n\nFor every claim, value, or fact; you MUST cite the attachment using this exact syntax:\n\n<cite attachment_id='ID' reasoning='why this supports the claim' full_phrase='verbatim transcript quote' key_span='1-3 key words' timestamps='HH:MM:SS.SSS-HH:MM:SS.SSS' />\n\n### Syntax Rules (MUST follow)\n\n1. **attachment_id**: Use the exact ID from the source\n2. **reasoning**: Brief explanation of why this citation supports your claim (think first!)\n3. **full_phrase**: Copy transcript text VERBATIM. Escape quotes (\\') and newlines (\\n).\n4. **key_span**: The 1-3 most important words or value from full_phrase\n5. **timestamps**: Start and end time with milliseconds (e.g., '00:01:23.456-00:01:45.789')\n\n### Placement Rules\n\n- Place <cite /> inline, typically at the end of a claim\n- One citation per distinct idea, concept, or value (a sentence citing 3 different values needs 3 citations)\n- Do NOT group citations at the end of the document\n- The <cite /> tag is self-closing - never use <cite>...</cite>\n\n</citation-instructions>\n";
+/**
+ * Citation Prompts
+ *
+ * This module provides the "Deferred JSON Pattern" for citation output.
+ * The LLM uses lightweight markers (e.g., [1], [2]) in the text and outputs
+ * a structured JSON block at the end of the response.
+ *
+ * Benefits:
+ * - **Robustness**: JSON.parse handles escaping naturally, avoiding quote-escaping issues
+ * - **Streaming Latency**: No mid-sentence pausing for hidden metadata generation
+ * - **Token Efficiency**: ~40% reduction in tokens per citation
+ */
+/** Start delimiter for the citation data block */
+declare const CITATION_DATA_START_DELIMITER = "<<<CITATION_DATA>>>";
+/** End delimiter for the citation data block */
+declare const CITATION_DATA_END_DELIMITER = "<<<END_CITATION_DATA>>>";
+/**
+ * Citation prompt for document-based citations.
+ * Uses [N] markers in text with JSON metadata at the end.
+ * Citations are grouped by attachment_id to avoid repetition.
+ *
+ * Shorthand key mapping (optional):
+ * - n: id, r: reasoning, f: full_phrase
+ * - k: anchor_text, p: page_id, l: line_ids
+ */
+declare const CITATION_PROMPT = "\n<citation-instructions priority=\"critical\">\n## REQUIRED: Citation Format\n\n### In-Text Markers\nFor every claim, value, or fact from attachments, place a sequential integer marker like [1], [2], [3] at the end of the claim.\n\n### Citation Data Block\nAt the END of your response, append a citation block. Group citations by attachment_id to avoid repetition.\n\n### Format\n```\n<<<CITATION_DATA>>>\n{\n  \"attachment_id_here\": [\n    {\"id\": 1, \"reasoning\": \"why\", \"full_phrase\": \"quote\", \"anchor_text\": \"key\", \"page_id\": \"2_1\", \"line_ids\": [12]}\n  ]\n}\n<<<END_CITATION_DATA>>>\n```\n\n### Shorthand (Optional)\nTo save tokens: n=id, r=reasoning, f=full_phrase, k=anchor_text, p=page_id, l=line_ids\n\n### JSON Field Rules\n\n1. **Group key**: The attachment_id (exact ID from source document)\n2. **id** (or n): Must match the [N] marker in your text (integer)\n3. **reasoning** (or r): Brief explanation connecting the citation to your claim (think first!)\n4. **full_phrase** (or f): Copy text VERBATIM from source. Use proper JSON escaping for quotes.\n5. **anchor_text** (or k): The 1-3 most important words from full_phrase\n6. **page_id** (or p): Format \"N_I\" where N=page number, I=index (from `<page_number_N_index_I>` tags)\n7. **line_ids** (or l): Array of line numbers. Infer intermediate lines since only every 5th is shown.\n\n### Placement Rules\n\n- Place [N] markers inline, typically at the end of a claim\n- One marker per distinct idea, concept, or value\n- Use sequential numbering starting from [1]\n- The JSON block MUST appear at the very end of your response\n\n### Example Response\n\nThe company reported strong growth [1]. Revenue increased significantly in Q4 [2]. The competitor also grew [3].\n\n<<<CITATION_DATA>>>\n{\n  \"abc123\": [\n    {\"id\": 1, \"reasoning\": \"directly states growth metrics\", \"full_phrase\": \"The company achieved 45% year-over-year growth\", \"anchor_text\": \"45% year-over-year growth\", \"page_id\": \"2_1\", \"line_ids\": [12, 13]},\n    {\"id\": 2, \"reasoning\": \"states Q4 revenue figure\", \"full_phrase\": \"Q4 revenue reached $2.3 billion, up from $1.8 billion\", \"anchor_text\": \"$2.3 billion\", \"page_id\": \"3_2\", \"line_ids\": [5, 6, 7]}\n  ],\n  \"def456\": [\n    {\"id\": 3, \"reasoning\": \"competitor data\", \"full_phrase\": \"Competitor X reported 20% growth\", \"anchor_text\": \"20% growth\", \"page_id\": \"1_0\", \"line_ids\": [8]}\n  ]\n}\n<<<END_CITATION_DATA>>>\n</citation-instructions>\n\n";
+/**
+ * Citation prompt for audio/video content.
+ * Uses timestamps instead of page/line references.
+ * Citations are grouped by attachment_id to avoid repetition.
+ *
+ * Shorthand key mapping (optional):
+ * - n: id, r: reasoning, f: full_phrase
+ * - k: anchor_text, t: timestamps (with s: start_time, e: end_time)
+ */
+declare const AV_CITATION_PROMPT = "\n<citation-instructions priority=\"critical\">\n## REQUIRED: Audio/Video Citation Format\n\n### In-Text Markers\nFor every claim, value, or fact from media content, place a sequential integer marker like [1], [2], [3] at the end of the claim.\n\n### Citation Data Block\nAt the END of your response, append a citation block. Group citations by attachment_id to avoid repetition.\n\n### Format\n```\n<<<CITATION_DATA>>>\n{\n  \"attachment_id_here\": [\n    {\"id\": 1, \"reasoning\": \"why\", \"full_phrase\": \"quote\", \"anchor_text\": \"key\", \"timestamps\": {\"start_time\": \"HH:MM:SS.SSS\", \"end_time\": \"HH:MM:SS.SSS\"}}\n  ]\n}\n<<<END_CITATION_DATA>>>\n```\n\n### Shorthand (Optional)\nTo save tokens: n=id, r=reasoning, f=full_phrase, k=anchor_text, t=timestamps (with s=start_time, e=end_time)\n\n### JSON Field Rules\n\n1. **Group key**: The attachment_id (exact ID from source media)\n2. **id** (or n): Must match the [N] marker in your text (integer)\n3. **reasoning** (or r): Brief explanation connecting the citation to your claim (think first!)\n4. **full_phrase** (or f): Copy transcript text VERBATIM. Use proper JSON escaping.\n5. **anchor_text** (or k): The 1-3 most important words from full_phrase\n6. **timestamps** (or t): Object with start_time/s and end_time/e in HH:MM:SS.SSS format\n\n### Placement Rules\n\n- Place [N] markers inline, typically at the end of a claim\n- One marker per distinct idea, concept, or value\n- Use sequential numbering starting from [1]\n- The JSON block MUST appear at the very end of your response\n\n### Example Response\n\nThe speaker discussed exercise benefits [1]. They recommended specific techniques [2].\n\n<<<CITATION_DATA>>>\n{\n  \"video123\": [\n    {\"id\": 1, \"reasoning\": \"speaker directly states health benefits\", \"full_phrase\": \"Regular exercise improves cardiovascular health by 30%\", \"anchor_text\": \"cardiovascular health\", \"timestamps\": {\"start_time\": \"00:05:23.000\", \"end_time\": \"00:05:45.500\"}},\n    {\"id\": 2, \"reasoning\": \"demonstrates proper form\", \"full_phrase\": \"Keep your back straight and engage your core\", \"anchor_text\": \"engage your core\", \"timestamps\": {\"start_time\": \"00:12:10.200\", \"end_time\": \"00:12:25.800\"}}\n  ]\n}\n<<<END_CITATION_DATA>>>\n</citation-instructions>\n\n";
 /**
  * A brief reminder to reinforce citation requirements in user messages.
  * Use this when you want to add emphasis without repeating full instructions.
  */
-declare const CITATION_REMINDER = "<citation-reminder>STOP and CHECK: Did you use <cite /> tags with all required attributes for every claim, value, or fact from attachments?</citation-reminder>";
+declare const CITATION_REMINDER = "<citation-reminder>STOP and CHECK: Did you use [N] markers for every claim and include the <<<CITATION_DATA>>> JSON block at the end?</citation-reminder>";
 /**
  * Audio/video version of the citation reminder.
  */
-declare const CITATION_AV_REMINDER = "<citation-reminder>STOP and CHECK: Did you use <cite /> tags with timestamps for every claim, value, or fact from source media?</citation-reminder>";
+declare const CITATION_AV_REMINDER = "<citation-reminder>STOP and CHECK: Did you use [N] markers for every claim and include the <<<CITATION_DATA>>> JSON block with timestamps at the end?</citation-reminder>";
 interface WrapSystemPromptOptions {
     /** The original system prompt to wrap with citation instructions */
     systemPrompt: string;
@@ -48,12 +82,12 @@ interface WrapCitationPromptResult {
  *
  * ### 2. Chain-of-Thought (CoT) Attribute Ordering
  * The citation attributes are ordered to encourage the model to "think first":
- * `attachment_id` → `reasoning` → `full_phrase` → `key_span` → `start_page_key` → `line_ids`
+ * `attachment_id` → `reasoning` → `full_phrase` → `anchor_text` → `page_id` → `line_ids`
  *
  * By placing `reasoning` early, the model must articulate WHY it's citing before
- * specifying WHAT it's citing. Then `full_phrase` comes before `key_span` so the model
- * first produces the complete verbatim quote, then extracts the key span from it,
- * ensuring `key_span` is always a valid substring of `full_phrase`.
+ * specifying WHAT it's citing. Then `full_phrase` comes before `anchor_text` so the model
+ * first produces the complete verbatim quote, then extracts the anchor text from it,
+ * ensuring `anchor_text` is always a valid substring of `full_phrase`.
  *
  * ### Why Not Just Append?
  * In large system prompts, appended instructions can get "lost" in the middle of the
@@ -107,72 +141,160 @@ declare function wrapSystemCitationPrompt(options: WrapSystemPromptOptions): str
  * ```
  */
 declare function wrapCitationPrompt(options: WrapCitationPromptOptions): WrapCitationPromptResult;
+/**
+ * JSON schema for citation data (for structured output LLMs).
+ * This can be used with OpenAI's response_format or similar features.
+ */
 declare const CITATION_JSON_OUTPUT_FORMAT: {
-    type: string;
-    properties: {
-        attachmentId: {
-            type: string;
+    readonly type: "object";
+    readonly properties: {
+        readonly id: {
+            readonly type: "integer";
+            readonly description: "Citation marker number matching [N] in text";
+        };
+        readonly attachment_id: {
+            readonly type: "string";
+            readonly description: "Exact attachment ID from source document";
         };
-        reasoning: {
-            type: string;
-            description: string;
+        readonly reasoning: {
+            readonly type: "string";
+            readonly description: "Brief explanation of why this supports the claim";
         };
-        fullPhrase: {
-            type: string;
-            description: string;
+        readonly full_phrase: {
+            readonly type: "string";
+            readonly description: "Verbatim quote from source document";
         };
-        keySpan: {
-            type: string;
-            description: string;
+        readonly anchor_text: {
+            readonly type: "string";
+            readonly description: "1-3 key words from full_phrase";
         };
-        startPageKey: {
-            type: string;
-            description: string;
+        readonly page_id: {
+            readonly type: "string";
+            readonly description: "Page ID in format 'N_I' (pageNumber_index)";
         };
-        lineIds: {
-            type: string;
-            items: {
-                type: string;
+        readonly line_ids: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "integer";
             };
-            description: string;
+            readonly description: "Array of line numbers for the citation";
         };
     };
-    required: string[];
+    readonly required: readonly ["id", "attachment_id", "full_phrase", "anchor_text"];
 };
-declare const CITATION_AV_BASED_JSON_OUTPUT_FORMAT: {
-    type: string;
-    properties: {
-        attachmentId: {
-            type: string;
+/**
+ * JSON schema for AV citation data.
+ */
+declare const CITATION_AV_JSON_OUTPUT_FORMAT: {
+    readonly type: "object";
+    readonly properties: {
+        readonly id: {
+            readonly type: "integer";
+            readonly description: "Citation marker number matching [N] in text";
+        };
+        readonly attachment_id: {
+            readonly type: "string";
+            readonly description: "Exact attachment ID from source media";
         };
-        startPageKey: {
-            type: string;
-            description: string;
+        readonly reasoning: {
+            readonly type: "string";
+            readonly description: "Brief explanation of why this supports the claim";
         };
-        fullPhrase: {
-            type: string;
-            description: string;
+        readonly full_phrase: {
+            readonly type: "string";
+            readonly description: "Verbatim transcript quote";
         };
-        keySpan: {
-            type: string;
-            description: string;
+        readonly anchor_text: {
+            readonly type: "string";
+            readonly description: "1-3 key words from full_phrase";
         };
-        timestamps: {
-            type: string;
-            properties: {
-                startTime: {
-                    type: string;
+        readonly timestamps: {
+            readonly type: "object";
+            readonly properties: {
+                readonly start_time: {
+                    readonly type: "string";
+                    readonly description: "Start time in HH:MM:SS.SSS format";
                 };
-                endTime: {
-                    type: string;
+                readonly end_time: {
+                    readonly type: "string";
+                    readonly description: "End time in HH:MM:SS.SSS format";
                 };
             };
-            required: string[];
-            description: string;
+            readonly required: readonly ["start_time", "end_time"];
         };
     };
-    required: string[];
+    readonly required: readonly ["id", "attachment_id", "full_phrase", "anchor_text", "timestamps"];
 };
+/**
+ * Compact citation data format from LLM output.
+ * Uses single-character keys for token efficiency.
+ */
+interface CompactCitationData {
+    /** Citation number (n) - matches [N] marker */
+    n: number;
+    /** Attachment ID (a) */
+    a?: string;
+    /** Reasoning (r) */
+    r?: string;
+    /** Full phrase (f) - verbatim quote */
+    f?: string;
+    /** Key phrase (k) - anchor text */
+    k?: string;
+    /** Page ID (p) - format "N_I" */
+    p?: string;
+    /** Line IDs (l) */
+    l?: number[];
+    /** Timestamps (t) for AV citations */
+    t?: {
+        /** Start time (s) */
+        s?: string;
+        /** End time (e) */
+        e?: string;
+    };
+}
+/**
+ * Interface for citation data from JSON block.
+ * This is the normalized/expanded format used internally after parsing.
+ * The parser expands compact keys (n,a,r,f,k,p,l,t) to these full names.
+ */
+interface CitationData {
+    /** Citation marker number (matches [N] in text). Compact key: n */
+    id: number;
+    /** Attachment ID from source document. Compact key: a */
+    attachment_id?: string;
+    /** Reasoning for the citation. Compact key: r */
+    reasoning?: string;
+    /** Verbatim quote from source. Compact key: f */
+    full_phrase?: string;
+    /** Anchor text (1-3 words). Compact key: k */
+    anchor_text?: string;
+    /** Page ID in format "N_I" or legacy "page_number_N_index_I". Compact key: p */
+    page_id?: string;
+    /** Line IDs array. Compact key: l */
+    line_ids?: number[];
+    /** Timestamps for AV citations. Compact key: t */
+    timestamps?: {
+        /** Start time. Compact key: s */
+        start_time?: string;
+        /** End time. Compact key: e */
+        end_time?: string;
+    };
+}
+/**
+ * Result of parsing a citation response.
+ */
+interface ParsedCitationResponse {
+    /** The clean text meant for display (content before the delimiter) */
+    visibleText: string;
+    /** The structured citation data from the JSON block */
+    citations: CitationData[];
+    /** Helper map for O(1) lookups by ID */
+    citationMap: Map<number, CitationData>;
+    /** Whether parsing was successful */
+    success: boolean;
+    /** Error message if parsing failed */
+    error?: string;
+}
 
 interface CompressedResult<T> {
     compressed: T;
@@ -193,4 +315,4 @@ declare function compressPromptIds<T>(obj: T, ids: string[] | undefined): Compre
  */
 declare function decompressPromptIds<T>(compressed: T | string, prefixMap: Record<string, string>): T | string;
 
-export { AV_CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_AV_BASED_JSON_OUTPUT_FORMAT, CITATION_AV_REMINDER, CITATION_JSON_OUTPUT_FORMAT, CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_REMINDER, type CompressedResult, type WrapCitationPromptOptions, type WrapCitationPromptResult, type WrapSystemPromptOptions, compressPromptIds, decompressPromptIds, wrapCitationPrompt, wrapSystemCitationPrompt };
+export { AV_CITATION_PROMPT, CITATION_AV_JSON_OUTPUT_FORMAT, CITATION_AV_REMINDER, CITATION_DATA_END_DELIMITER, CITATION_DATA_START_DELIMITER, CITATION_JSON_OUTPUT_FORMAT, CITATION_PROMPT, CITATION_REMINDER, type CitationData, type CompactCitationData, type CompressedResult, type ParsedCitationResponse, type WrapCitationPromptOptions, type WrapCitationPromptResult, type WrapSystemPromptOptions, compressPromptIds, decompressPromptIds, wrapCitationPrompt, wrapSystemCitationPrompt };

package/lib/prompts/index.js

@@ -1 +1,2 @@
-export{b as AV_CITATION_MARKDOWN_SYNTAX_PROMPT,h as CITATION_AV_BASED_JSON_OUTPUT_FORMAT,d as CITATION_AV_REMINDER,g as CITATION_JSON_OUTPUT_FORMAT,a as CITATION_MARKDOWN_SYNTAX_PROMPT,c as CITATION_REMINDER,i as compressPromptIds,j as decompressPromptIds,f as wrapCitationPrompt,e as wrapSystemCitationPrompt}from'../chunk-ND6LFDGK.js';import'../chunk-O2XFH626.js';
+export{a as compressPromptIds,b as decompressPromptIds}from'../chunk-BWQLFMTV.js';export{d as AV_CITATION_PROMPT,j as CITATION_AV_JSON_OUTPUT_FORMAT,f as CITATION_AV_REMINDER,b as CITATION_DATA_END_DELIMITER,a as CITATION_DATA_START_DELIMITER,i as CITATION_JSON_OUTPUT_FORMAT,c as CITATION_PROMPT,e as CITATION_REMINDER,h as wrapCitationPrompt,g as wrapSystemCitationPrompt}from'../chunk-BDSA6VGC.js';import'../chunk-5XGN7UAV.js';//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/lib/prompts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}