@deepcitation/deepcitation-js 1.1.49 → 1.1.51

package/lib/index.d.ts

@@ -1,8 +1,9 @@
-export { CitationInput, DeepCitation, DeepCitationConfig, FileDataPart, FileInput, PrepareFilesResult, UploadFileOptions, UploadFileResponse, VerifyCitationsOptions, VerifyCitationsResponse, verifyAll } from './client/index.js';
-import { C as Citation, V as Verification, a as CitationStatus } from './index-fvVBZYVK.js';
-export { B as BLANK_VERIFICATION, b as CitationType, f as ContentMatchStatus, D as DEFAULT_OUTPUT_IMAGE_FORMAT, k as DeepTextItem, I as IVertex, N as NOT_FOUND_VERIFICATION_INDEX, O as OutputImageFormat, P as PENDING_VERIFICATION_INDEX, j as ScreenBox, i as SearchAttempt, h as SearchMethod, g as SearchStatus, e as SourceMeta, S as SourceType, U as UrlAccessStatus, c as VerifyCitationRequest, d as VerifyCitationResponse } from './index-fvVBZYVK.js';
-export { C as CITATION_X_PADDING, c as CITATION_Y_PADDING, b as generateCitationInstanceId, g as generateCitationKey, a as generateVerificationKey } from './utils-DuacFTtu.js';
-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, CompressedResult, WrapCitationPromptOptions, WrapCitationPromptResult, WrapSystemPromptOptions, compressPromptIds, decompressPromptIds, wrapCitationPrompt, wrapSystemCitationPrompt } from './prompts/index.js';
+export { CitationInput, DeepCitation, DeepCitationConfig, FileDataPart, FileInput, PrepareFilesResult, UploadFileOptions, UploadFileResponse, VerifyCitationsOptions, VerifyCitationsResponse } from './client/index.js';
+import { C as Citation, V as Verification, a as CitationStatus } from './index-BHjI8Bh1.js';
+export { B as BLANK_VERIFICATION, b as CitationType, c as ContentMatchStatus, D as DEFAULT_OUTPUT_IMAGE_FORMAT, d as DeepTextItem, I as IVertex, N as NOT_FOUND_VERIFICATION_INDEX, O as OutputImageFormat, P as PENDING_VERIFICATION_INDEX, S as ScreenBox, e as SearchAttempt, f as SearchMethod, g as SearchStatus, h as SourceMeta, i as SourceType, U as UrlAccessStatus, j as VerifyCitationRequest, k as VerifyCitationResponse } from './index-BHjI8Bh1.js';
+import { CitationData, ParsedCitationResponse } from './prompts/index.js';
+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, CompressedResult, WrapCitationPromptOptions, WrapCitationPromptResult, WrapSystemPromptOptions, compressPromptIds, decompressPromptIds, wrapCitationPrompt, wrapSystemCitationPrompt } from './prompts/index.js';
+export { C as CITATION_X_PADDING, a as CITATION_Y_PADDING, g as generateCitationInstanceId, b as generateCitationKey, c as generateVerificationKey } from './utils-CoSP-i76.js';
 
 /**
  * Calculates the verification status of a citation based on the found highlight and search state.
@@ -82,12 +83,136 @@ declare function groupCitationsByAttachmentIdObject(citations: Citation[] | {
     };
 };
 
+/**
+ * Citation Parser
+ *
+ * Implements the "Split & Parse" strategy for the deferred JSON citation pattern.
+ * This parser extracts citations from LLM responses that use [N] markers in text
+ * and include a JSON data block at the end.
+ *
+ * Algorithm:
+ * 1. Detection: Look for the start delimiter <<<CITATION_DATA>>>
+ * 2. Splitting: Separate visible content from the citation data block
+ * 3. Data Extraction: Extract the JSON string between delimiters
+ * 4. Sanitization: Parse with JSON.parse, with fallback repair for common issues
+ * 5. Hydration: Map the JSON objects to a usable format
+ */
+
+/**
+ * Parses a citation response from an LLM.
+ *
+ * This function:
+ * 1. Finds the <<<CITATION_DATA>>> delimiter in the response
+ * 2. Splits the response into visible text and citation data
+ * 3. Parses the JSON citation data
+ * 4. Returns a structured result with both
+ *
+ * @param llmResponse - The full LLM response text
+ * @returns ParsedCitationResponse with visible text and parsed citations
+ *
+ * @example
+ * ```typescript
+ * const response = `
+ *   The company grew 45% [1].
+ *
+ *   <<<CITATION_DATA>>>
+ *   [{"id": 1, "attachment_id": "abc", "full_phrase": "grew 45%", "anchor_text": "45%"}]
+ *   <<<END_CITATION_DATA>>>
+ * `;
+ *
+ * const parsed = parseDeferredCitationResponse(response);
+ * console.log(parsed.visibleText); // "The company grew 45% [1]."
+ * console.log(parsed.citations); // [{id: 1, attachment_id: "abc", ...}]
+ * ```
+ */
+declare function parseDeferredCitationResponse(llmResponse: string): ParsedCitationResponse;
+/**
+ * Converts a CitationData object to the standard Citation format.
+ *
+ * @param data - The citation data
+ * @param citationNumber - Optional override for citation number (defaults to data.id)
+ * @returns Standard Citation object
+ */
+declare function deferredCitationToCitation(data: CitationData, citationNumber?: number): Citation;
+/**
+ * Extracts all citations from a citation response and returns them
+ * in the standard dictionary format used by the verification API.
+ *
+ * This function parses the response, converts each citation to the standard
+ * Citation format, and generates deterministic keys for each.
+ *
+ * @param llmResponse - The full LLM response with citation block
+ * @returns Dictionary of parsed Citation objects keyed by citation key
+ *
+ * @example
+ * ```typescript
+ * const citations = getAllCitationsFromDeferredResponse(llmOutput);
+ * // Returns: { "abc123...": { attachmentId: "...", fullPhrase: "...", ... }, ... }
+ * ```
+ */
+declare function getAllCitationsFromDeferredResponse(llmResponse: string): {
+    [key: string]: Citation;
+};
+/**
+ * Checks if a response contains citation markers.
+ *
+ * @param response - The LLM response to check
+ * @returns True if the response contains the citation data delimiter
+ */
+declare function hasDeferredCitations(response: string): boolean;
+/**
+ * Extracts just the visible text from a response,
+ * removing the citation data block.
+ *
+ * @param llmResponse - The full LLM response
+ * @returns The visible text portion only
+ */
+declare function extractVisibleText(llmResponse: string): string;
+/**
+ * Replaces [N] citation markers in text with optional content.
+ *
+ * @param text - The text containing [N] markers
+ * @param options - Configuration for replacement
+ * @returns The text with markers replaced
+ *
+ * @example
+ * ```typescript
+ * const text = "Revenue grew 45% [1] in Q4 [2].";
+ *
+ * // Remove markers entirely
+ * replaceDeferredMarkers(text);
+ * // Returns: "Revenue grew 45% in Q4."
+ *
+ * // Replace with anchor texts
+ * replaceDeferredMarkers(text, {
+ *   citationMap: new Map([[1, { anchor_text: "45%" }], [2, { anchor_text: "Q4" }]]),
+ *   showAnchorText: true,
+ * });
+ * // Returns: "Revenue grew 45% 45% in Q4 Q4."
+ * ```
+ */
+declare function replaceDeferredMarkers(text: string, options?: {
+    /** Map of citation IDs to their data */
+    citationMap?: Map<number, CitationData>;
+    /** Whether to show the anchor text after the marker */
+    showAnchorText?: boolean;
+    /** Custom replacement function */
+    replacer?: (id: number, data?: CitationData) => string;
+}): string;
+/**
+ * Gets all citation marker IDs found in a text.
+ *
+ * @param text - The text to scan for [N] markers
+ * @returns Array of citation IDs in order of appearance
+ */
+declare function getCitationMarkerIds(text: string): number[];
+
 interface ReplaceCitationsOptions {
     /**
-     * If true, leaves the key_span text behind when removing citations.
+     * If true, leaves the anchor_text text behind when removing citations.
      * @default false
      */
-    leaveKeySpanBehind?: boolean;
+    leaveAnchorTextBehind?: boolean;
     /**
      * Map of citation keys to verification results.
      * Used to determine verification status for each citation.
@@ -120,12 +245,12 @@ declare const getVerificationTextIndicator: (verification: Verification | null |
  * // Remove all citations
  * const clean = replaceCitations(llmOutput);
  *
- * // Leave key_span text behind
- * const withKeySpans = replaceCitations(llmOutput, { leaveKeySpanBehind: true });
+ * // Leave anchor_text text behind
+ * const withAnchorTexts = replaceCitations(llmOutput, { leaveAnchorTextBehind: true });
  *
  * // Show verification status indicators
  * const withStatus = replaceCitations(llmOutput, {
- *   leaveKeySpanBehind: true,
+ *   leaveAnchorTextBehind: true,
  *   verifications: verificationMap,
  *   showVerificationStatus: true,
  * });
@@ -133,13 +258,9 @@ declare const getVerificationTextIndicator: (verification: Verification | null |
  * ```
  */
 declare const replaceCitations: (markdownWithCitations: string, options?: ReplaceCitationsOptions) => string;
-/**
- * @deprecated Use `replaceCitations` instead. This function is kept for backward compatibility.
- */
-declare const removeCitations: (markdownWithCitations: string, leaveKeySpanBehind?: boolean) => string;
 declare const removePageNumberMetadata: (pageText: string) => string;
 declare const removeLineIdMetadata: (pageText: string) => string;
-declare const getCitationPageNumber: (startPageKey?: string | null) => number | null;
+declare const getCitationPageNumber: (startPageId?: string | null) => number | null;
 declare const normalizeCitations: (response: string) => string;
 
 declare const isGeminiGarbage: (content: string) => boolean;
@@ -156,4 +277,4 @@ declare function cleanRepeatingLastSentence(text: string): string;
  */
 declare function sha1Hash(data: string | any): string;
 
-export { Citation, CitationStatus, type ReplaceCitationsOptions, Verification, cleanRepeatingLastSentence, getAllCitationsFromLlmOutput, getCitationPageNumber, getCitationStatus, getVerificationTextIndicator, groupCitationsByAttachmentId, groupCitationsByAttachmentIdObject, isGeminiGarbage, normalizeCitations, parseCitation, removeCitations, removeLineIdMetadata, removePageNumberMetadata, replaceCitations, sha1Hash };
+export { Citation, CitationData, CitationStatus, ParsedCitationResponse, type ReplaceCitationsOptions, Verification, cleanRepeatingLastSentence, deferredCitationToCitation, extractVisibleText, getAllCitationsFromDeferredResponse, getAllCitationsFromLlmOutput, getCitationMarkerIds, getCitationPageNumber, getCitationStatus, getVerificationTextIndicator, groupCitationsByAttachmentId, groupCitationsByAttachmentIdObject, hasDeferredCitations, isGeminiGarbage, normalizeCitations, parseCitation, parseDeferredCitationResponse, removeLineIdMetadata, removePageNumberMetadata, replaceCitations, replaceDeferredMarkers, sha1Hash };

package/lib/index.js

@@ -1 +1,2 @@
-export{a as DeepCitation}from'./chunk-3XSZLKJW.js';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';export{d as BLANK_VERIFICATION,a as DEFAULT_OUTPUT_IMAGE_FORMAT,b as NOT_FOUND_VERIFICATION_INDEX,c as PENDING_VERIFICATION_INDEX}from'./chunk-HRCAI3NV.js';export{k as CITATION_X_PADDING,l as CITATION_Y_PADDING,f as generateCitationInstanceId,d as generateCitationKey,e as generateVerificationKey,v as getAllCitationsFromLlmOutput,r as getCitationPageNumber,t as getCitationStatus,m as getVerificationTextIndicator,w as groupCitationsByAttachmentId,x as groupCitationsByAttachmentIdObject,s as normalizeCitations,u as parseCitation,o as removeCitations,q as removeLineIdMetadata,p as removePageNumberMetadata,n as replaceCitations,a as sha1Hash}from'./chunk-PKXMJNRX.js';import'./chunk-O2XFH626.js';var z=t=>{if(!t)return  false;let e=t.trim();if(e.length<64)return  false;let a=e?.[0];for(let r=1;r<e.length;r++)if(e[r]!==a)return  false;return  true};function J(t){t=t.trim();let e=2,a=10,r=/[.?!](?=\s+|$)/g,n=[],c;for(;(c=r.exec(t))!==null;)n.push(c.index);if(n.length<2)return t;let I=n[n.length-1],f=n[n.length-2],o=t.substring(f+1,I+1),p=o.length;if(o.trim().slice(0,-1).length<a||p<=0||t.length<p*e)return t;let m=0,s=I+1;t.endsWith(o)&&(s=t.length);let T=-1;for(;;){let i=s-p;if(i<0)break;if(t.substring(i,s)===o)m++,T=i,s=i;else break}return m>=e?t.substring(0,T)+o:t}export{J as cleanRepeatingLastSentence,z as isGeminiGarbage};
+export{a as DeepCitation}from'./chunk-2HINOG74.js';export{a as compressPromptIds,b as decompressPromptIds}from'./chunk-BWQLFMTV.js';export{d as BLANK_VERIFICATION,a as DEFAULT_OUTPUT_IMAGE_FORMAT,b as NOT_FOUND_VERIFICATION_INDEX,c as PENDING_VERIFICATION_INDEX}from'./chunk-BEYJEW3Y.js';export{k as CITATION_X_PADDING,l as CITATION_Y_PADDING,t as deferredCitationToCitation,w as extractVisibleText,f as generateCitationInstanceId,d as generateCitationKey,e as generateVerificationKey,u as getAllCitationsFromDeferredResponse,B as getAllCitationsFromLlmOutput,y as getCitationMarkerIds,q as getCitationPageNumber,z as getCitationStatus,m as getVerificationTextIndicator,C as groupCitationsByAttachmentId,D as groupCitationsByAttachmentIdObject,v as hasDeferredCitations,r as normalizeCitations,A as parseCitation,s as parseDeferredCitationResponse,p as removeLineIdMetadata,o as removePageNumberMetadata,n as replaceCitations,x as replaceDeferredMarkers,a as sha1Hash}from'./chunk-N7FTXSGM.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';var rt=t=>{if(!t)return  false;let e=t.trim();if(e.length<64)return  false;let a=e?.[0];for(let n=1;n<e.length;n++)if(e[n]!==a)return  false;return  true};function nt(t){t=t.trim();let e=2,a=10,n=/[.?!](?=\s+|$)/g,r=[],I;for(;(I=n.exec(t))!==null;)r.push(I.index);if(r.length<2)return t;let c=r[r.length-1],C=r[r.length-2],i=t.substring(C+1,c+1),p=i.length;if(i.trim().slice(0,-1).length<a||p<=0||t.length<p*e)return t;let m=0,s=c+1;t.endsWith(i)&&(s=t.length);let T=-1;for(;;){let o=s-p;if(o<0)break;if(t.substring(o,s)===i)m++,T=o,s=o;else break}return m>=e?t.substring(0,T)+i:t}export{nt as cleanRepeatingLastSentence,rt as isGeminiGarbage};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/parsing/parseWorkAround.ts"],"names":["isGeminiGarbage","content","trimmedContent","firstCharacter","i","cleanRepeatingLastSentence","text","MIN_REPETITIONS","MIN_SENTENCE_CONTENT_LENGTH","sentenceEndRegex","sentenceEndIndices","match","lastTerminatorIndex","secondLastTerminatorIndex","repeatingUnit","unitLength","repetitionsFound","currentCheckEndIndex","firstRepetitionStartIndex","checkStartIndex"],"mappings":"4zCAEO,IAAMA,GAAmBC,CAAAA,EAAoB,CAClD,GAAI,CAACA,EAAS,OAAO,MAAA,CACrB,IAAMC,CAAAA,CAAiBD,EAAQ,IAAA,EAAK,CACpC,GAAIC,CAAAA,CAAe,MAAA,CAAS,GAAuC,OAAO,MAAA,CAE1E,IAAMC,CAAAA,CAAiBD,IAAiB,CAAC,CAAA,CAEzC,QAASE,CAAAA,CAAI,CAAA,CAAGA,EAAIF,CAAAA,CAAe,MAAA,CAAQE,CAAAA,EAAAA,CACzC,GAAIF,EAAeE,CAAC,CAAA,GAAMD,EAAgB,OAAO,MAAA,CAEnD,OAAO,KACT,EAGO,SAASE,EAAAA,CAA2BC,EAAsB,CAC/DA,CAAAA,CAAOA,CAAAA,CAAK,IAAA,GACZ,IAAMC,CAAAA,CAAkB,CAAA,CAClBC,CAAAA,CAA8B,GAE9BC,CAAAA,CAAmB,iBAAA,CACnBC,EAA+B,EAAC,CAClCC,EACJ,KAAA,CAAQA,CAAAA,CAAQF,CAAAA,CAAiB,IAAA,CAAKH,CAAI,CAAA,IAAO,IAAA,EAC/CI,EAAmB,IAAA,CAAKC,CAAAA,CAAM,KAAK,CAAA,CAGrC,GAAID,CAAAA,CAAmB,MAAA,CAAS,EAC9B,OAAOJ,CAAAA,CAGT,IAAMM,CAAAA,CAAsBF,CAAAA,CAAmBA,EAAmB,MAAA,CAAS,CAAC,CAAA,CACtEG,CAAAA,CAA4BH,EAAmBA,CAAAA,CAAmB,MAAA,CAAS,CAAC,CAAA,CAE5EI,EAAgBR,CAAAA,CAAK,SAAA,CAAUO,CAAAA,CAA4B,CAAA,CAAGD,EAAsB,CAAC,CAAA,CACrFG,EAAaD,CAAAA,CAAc,MAAA,CAUjC,GARwBA,CAAAA,CAAc,IAAA,EAAK,CAAE,KAAA,CAAM,EAAG,EAAE,CAAA,CACpC,OAASN,CAAAA,EAGzBO,CAAAA,EAAc,GAIdT,CAAAA,CAAK,MAAA,CAASS,CAAAA,CAAaR,CAAAA,CAC7B,OAAOD,CAAAA,CAGT,IAAIU,EAAmB,CAAA,CACnBC,CAAAA,CAAuBL,EAAsB,CAAA,CAC7CN,CAAAA,CAAK,QAAA,CAASQ,CAAa,IAC7BG,CAAAA,CAAuBX,CAAAA,CAAK,QAG9B,IAAIY,CAAAA,CAA4B,GAEhC,OAAa,CACX,IAAMC,CAAAA,CAAkBF,EAAuBF,CAAAA,CAE/C,GAAII,EAAkB,CAAA,CACpB,MAKF,GAFcb,CAAAA,CAAK,SAAA,CAAUa,CAAAA,CAAiBF,CAAoB,IAEpDH,CAAAA,CACZE,CAAAA,EAAAA,CACAE,EAA4BC,CAAAA,CAC5BF,CAAAA,CAAuBE,OAEvB,KAEJ,CAEA,OAAIH,CAAAA,EAAoBT,EACQD,CAAAA,CAAK,SAAA,CAAU,EAAGY,CAAyB,CAAA,CAClCJ,EAGhCR,CAEX","file":"index.js","sourcesContent":["//flash and flash lite get super confused if we ask for a MD table and infinite loop\nconst MIN_CONTENT_LENGTH_FOR_GEMINI_GARBAGE = 64;\nexport const isGeminiGarbage = (content: string) => {\n  if (!content) return false;\n  const trimmedContent = content.trim();\n  if (trimmedContent.length < MIN_CONTENT_LENGTH_FOR_GEMINI_GARBAGE) return false;\n\n  const firstCharacter = trimmedContent?.[0];\n\n  for (let i = 1; i < trimmedContent.length; i++) {\n    if (trimmedContent[i] !== firstCharacter) return false;\n  }\n  return true;\n};\n\n// helps clean up infinite rambling bug output from gemini\nexport function cleanRepeatingLastSentence(text: string): string {\n  text = text.trim();\n  const MIN_REPETITIONS = 2;\n  const MIN_SENTENCE_CONTENT_LENGTH = 10;\n\n  const sentenceEndRegex = /[.?!](?=\\s+|$)/g;\n  const sentenceEndIndices: number[] = [];\n  let match;\n  while ((match = sentenceEndRegex.exec(text)) !== null) {\n    sentenceEndIndices.push(match.index);\n  }\n\n  if (sentenceEndIndices.length < 2) {\n    return text;\n  }\n\n  const lastTerminatorIndex = sentenceEndIndices[sentenceEndIndices.length - 1];\n  const secondLastTerminatorIndex = sentenceEndIndices[sentenceEndIndices.length - 2];\n\n  const repeatingUnit = text.substring(secondLastTerminatorIndex + 1, lastTerminatorIndex + 1);\n  const unitLength = repeatingUnit.length;\n\n  const sentenceContent = repeatingUnit.trim().slice(0, -1);\n  if (sentenceContent.length < MIN_SENTENCE_CONTENT_LENGTH) {\n    return text;\n  }\n  if (unitLength <= 0) {\n    return text;\n  }\n\n  if (text.length < unitLength * MIN_REPETITIONS) {\n    return text;\n  }\n\n  let repetitionsFound = 0;\n  let currentCheckEndIndex = lastTerminatorIndex + 1;\n  if (text.endsWith(repeatingUnit)) {\n    currentCheckEndIndex = text.length;\n  }\n\n  let firstRepetitionStartIndex = -1;\n\n  while (true) {\n    const checkStartIndex = currentCheckEndIndex - unitLength;\n\n    if (checkStartIndex < 0) {\n      break;\n    }\n\n    const chunk = text.substring(checkStartIndex, currentCheckEndIndex);\n\n    if (chunk === repeatingUnit) {\n      repetitionsFound++;\n      firstRepetitionStartIndex = checkStartIndex;\n      currentCheckEndIndex = checkStartIndex;\n    } else {\n      break;\n    }\n  }\n\n  if (repetitionsFound >= MIN_REPETITIONS) {\n    const textBeforeRepetitions = text.substring(0, firstRepetitionStartIndex);\n    const result = textBeforeRepetitions + repeatingUnit;\n    return result;\n  } else {\n    return text;\n  }\n}\n"]}

package/lib/prompts/index.cjs

@@ -1 +1,2 @@
-'use strict';var chunkDHVODVIA_cjs=require('../chunk-DHVODVIA.cjs');require('../chunk-F2MMVEVC.cjs');Object.defineProperty(exports,"AV_CITATION_MARKDOWN_SYNTAX_PROMPT",{enumerable:true,get:function(){return chunkDHVODVIA_cjs.b}});Object.defineProperty(exports,"CITATION_AV_BASED_JSON_OUTPUT_FORMAT",{enumerable:true,get:function(){return chunkDHVODVIA_cjs.h}});Object.defineProperty(exports,"CITATION_AV_REMINDER",{enumerable:true,get:function(){return chunkDHVODVIA_cjs.d}});Object.defineProperty(exports,"CITATION_JSON_OUTPUT_FORMAT",{enumerable:true,get:function(){return chunkDHVODVIA_cjs.g}});Object.defineProperty(exports,"CITATION_MARKDOWN_SYNTAX_PROMPT",{enumerable:true,get:function(){return chunkDHVODVIA_cjs.a}});Object.defineProperty(exports,"CITATION_REMINDER",{enumerable:true,get:function(){return chunkDHVODVIA_cjs.c}});Object.defineProperty(exports,"compressPromptIds",{enumerable:true,get:function(){return chunkDHVODVIA_cjs.i}});Object.defineProperty(exports,"decompressPromptIds",{enumerable:true,get:function(){return chunkDHVODVIA_cjs.j}});Object.defineProperty(exports,"wrapCitationPrompt",{enumerable:true,get:function(){return chunkDHVODVIA_cjs.f}});Object.defineProperty(exports,"wrapSystemCitationPrompt",{enumerable:true,get:function(){return chunkDHVODVIA_cjs.e}});
+'use strict';var chunkDS6SOU4L_cjs=require('../chunk-DS6SOU4L.cjs'),chunkWS4CQVDI_cjs=require('../chunk-WS4CQVDI.cjs');require('../chunk-BYLIBOAU.cjs');Object.defineProperty(exports,"compressPromptIds",{enumerable:true,get:function(){return chunkDS6SOU4L_cjs.a}});Object.defineProperty(exports,"decompressPromptIds",{enumerable:true,get:function(){return chunkDS6SOU4L_cjs.b}});Object.defineProperty(exports,"AV_CITATION_PROMPT",{enumerable:true,get:function(){return chunkWS4CQVDI_cjs.d}});Object.defineProperty(exports,"CITATION_AV_JSON_OUTPUT_FORMAT",{enumerable:true,get:function(){return chunkWS4CQVDI_cjs.j}});Object.defineProperty(exports,"CITATION_AV_REMINDER",{enumerable:true,get:function(){return chunkWS4CQVDI_cjs.f}});Object.defineProperty(exports,"CITATION_DATA_END_DELIMITER",{enumerable:true,get:function(){return chunkWS4CQVDI_cjs.b}});Object.defineProperty(exports,"CITATION_DATA_START_DELIMITER",{enumerable:true,get:function(){return chunkWS4CQVDI_cjs.a}});Object.defineProperty(exports,"CITATION_JSON_OUTPUT_FORMAT",{enumerable:true,get:function(){return chunkWS4CQVDI_cjs.i}});Object.defineProperty(exports,"CITATION_PROMPT",{enumerable:true,get:function(){return chunkWS4CQVDI_cjs.c}});Object.defineProperty(exports,"CITATION_REMINDER",{enumerable:true,get:function(){return chunkWS4CQVDI_cjs.e}});Object.defineProperty(exports,"wrapCitationPrompt",{enumerable:true,get:function(){return chunkWS4CQVDI_cjs.h}});Object.defineProperty(exports,"wrapSystemCitationPrompt",{enumerable:true,get:function(){return chunkWS4CQVDI_cjs.g}});//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/lib/prompts/index.cjs.map

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

package/lib/prompts/index.d.cts

@@ -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 };