@deepcitation/deepcitation-js 1.1.27 → 1.1.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +253 -253
  3. package/lib/chunk-2IZXUOQR.js +66 -0
  4. package/lib/chunk-4FGOHQFP.cjs +66 -0
  5. package/lib/chunk-CFXDRAJL.cjs +1 -0
  6. package/lib/chunk-DEUSSEFH.js +2 -0
  7. package/lib/chunk-F2MMVEVC.cjs +1 -0
  8. package/lib/chunk-J7U6YFOI.cjs +2 -0
  9. package/lib/chunk-O2XFH626.js +1 -0
  10. package/lib/chunk-RQPZSRID.js +1 -0
  11. package/lib/client/index.cjs +1 -0
  12. package/lib/client/{DeepCitation.d.ts → index.d.cts} +159 -3
  13. package/lib/client/index.d.ts +342 -2
  14. package/lib/client/index.js +1 -1
  15. package/lib/index.cjs +1 -0
  16. package/lib/index.d.cts +127 -0
  17. package/lib/index.d.ts +126 -22
  18. package/lib/index.js +1 -20
  19. package/lib/prompts/index.cjs +1 -0
  20. package/lib/prompts/index.d.cts +196 -0
  21. package/lib/prompts/index.d.ts +196 -3
  22. package/lib/prompts/index.js +1 -3
  23. package/lib/react/index.cjs +4 -0
  24. package/lib/react/index.js +4 -20
  25. package/lib/types/index.cjs +1 -0
  26. package/lib/types/index.d.cts +96 -0
  27. package/lib/types/index.d.ts +96 -11
  28. package/lib/types/index.js +1 -7
  29. package/package.json +46 -11
  30. package/lib/client/DeepCitation.js +0 -374
  31. package/lib/client/types.d.ts +0 -154
  32. package/lib/client/types.js +0 -1
  33. package/lib/parsing/normalizeCitation.d.ts +0 -5
  34. package/lib/parsing/normalizeCitation.js +0 -198
  35. package/lib/parsing/parseCitation.d.ts +0 -79
  36. package/lib/parsing/parseCitation.js +0 -431
  37. package/lib/parsing/parseWorkAround.d.ts +0 -2
  38. package/lib/parsing/parseWorkAround.js +0 -73
  39. package/lib/prompts/citationPrompts.d.ts +0 -138
  40. package/lib/prompts/citationPrompts.js +0 -168
  41. package/lib/prompts/promptCompression.d.ts +0 -14
  42. package/lib/prompts/promptCompression.js +0 -127
  43. package/lib/prompts/types.d.ts +0 -4
  44. package/lib/prompts/types.js +0 -1
  45. package/lib/react/CitationComponent.d.ts +0 -106
  46. package/lib/react/CitationComponent.js +0 -419
  47. package/lib/react/CitationVariants.d.ts +0 -132
  48. package/lib/react/CitationVariants.js +0 -277
  49. package/lib/react/DiffDisplay.d.ts +0 -10
  50. package/lib/react/DiffDisplay.js +0 -33
  51. package/lib/react/Popover.d.ts +0 -15
  52. package/lib/react/Popover.js +0 -20
  53. package/lib/react/UrlCitationComponent.d.ts +0 -83
  54. package/lib/react/UrlCitationComponent.js +0 -224
  55. package/lib/react/VerificationTabs.d.ts +0 -10
  56. package/lib/react/VerificationTabs.js +0 -36
  57. package/lib/react/icons.d.ts +0 -22
  58. package/lib/react/icons.js +0 -16
  59. package/lib/react/index.d.ts +0 -17
  60. package/lib/react/primitives.d.ts +0 -99
  61. package/lib/react/primitives.js +0 -187
  62. package/lib/react/types.d.ts +0 -315
  63. package/lib/react/types.js +0 -1
  64. package/lib/react/useSmartDiff.d.ts +0 -16
  65. package/lib/react/useSmartDiff.js +0 -64
  66. package/lib/react/utils.d.ts +0 -44
  67. package/lib/react/utils.js +0 -88
  68. package/lib/types/boxes.d.ts +0 -11
  69. package/lib/types/boxes.js +0 -1
  70. package/lib/types/citation.d.ts +0 -39
  71. package/lib/types/citation.js +0 -1
  72. package/lib/types/search.d.ts +0 -19
  73. package/lib/types/search.js +0 -1
  74. package/lib/types/verification.d.ts +0 -27
  75. package/lib/types/verification.js +0 -11
  76. package/lib/utils/diff.d.ts +0 -60
  77. package/lib/utils/diff.js +0 -414
  78. package/lib/utils/sha.d.ts +0 -10
  79. package/lib/utils/sha.js +0 -108
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 FileLasso, Inc.
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 FileLasso, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,253 +1,253 @@
1
- <div align="center">
2
-
3
- # @deepcitation/deepcitation-js
4
-
5
- **Deterministic AI citation verification. Eliminate hallucination risk by proving every AI citation against source documents.**
6
-
7
- [![npm version](https://img.shields.io/npm/v/@deepcitation/deepcitation-js.svg)](https://www.npmjs.com/package/@deepcitation/deepcitation-js)
8
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9
- [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
10
-
11
- [Documentation](https://deepcitation.com/docs) · [Get Free API Key](https://deepcitation.com/signup) · [Examples](./examples) · [Discord](https://discord.gg/deepcitation)
12
-
13
- </div>
14
-
15
- ---
16
-
17
- ## Why DeepCitation?
18
-
19
- LLMs hallucinate. Even when given source documents, they make up quotes, invent statistics, and cite pages that don't exist. DeepCitation solves this by **deterministically verifying every citation** against your source documents—and generating visual proof.
20
-
21
- <div align="center">
22
- <img src="./examples/assets/deepcitation-medical-demo.gif" alt="DeepCitation medical documentation demo showing verified inline citations" width="700" />
23
- <br />
24
- <em>Medical documentation with verified inline citations — certainty at a glance</em>
25
- </div>
26
-
27
- ```
28
- Before: "Revenue grew 45% [1]" → ❓ Did the LLM make this up?
29
- After: "Revenue grew 45% [1]" → ✅ Verified on page 3, line 12 (with screenshot)
30
- ```
31
-
32
- ## Features
33
-
34
- - **Deterministic Matching** – Every citation traced to its exact location. No fuzzy matching, no guessing.
35
- - **Visual Proof** – Automated screenshots with highlighted text show exactly where citations come from.
36
- - **Any LLM Provider** – Works with OpenAI, Anthropic, Google, Azure, or your own models.
37
- - **React Components** – Pre-built components + composable primitives for citation UIs.
38
- - **TypeScript Native** – Full type safety with comprehensive type definitions.
39
-
40
- ## Installation
41
-
42
- ```bash
43
- npm install @deepcitation/deepcitation-js
44
- ```
45
-
46
- Get a free API key at [deepcitation.com](https://deepcitation.com/signup) — no credit card required.
47
-
48
- ```bash
49
- # .env
50
- DEEPCITATION_API_KEY=sk-dc-your_api_key_here
51
- ```
52
-
53
- ---
54
-
55
- ## Quick Start
56
-
57
- DeepCitation works in three steps: **Pre-Prompt**, **Post-Prompt**, and **Display**.
58
-
59
- ### Step 1: Pre-Prompt
60
-
61
- Upload source documents and enhance your prompt with citation instructions.
62
-
63
- ```typescript
64
- import { DeepCitation, wrapCitationPrompt } from "@deepcitation/deepcitation-js";
65
-
66
- const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
67
-
68
- // Upload source files, this can be done before the user types their prompt
69
- const { fileDataParts, deepTextPromptPortion } = await dc.prepareFiles([
70
- { file: pdfBuffer, filename: "report.pdf" },
71
- ]);
72
-
73
- // Wrap prompts with citation instructions
74
- const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
75
- systemPrompt: "You are a helpful assistant...",
76
- userPrompt: "Analyze this document",
77
- deepTextPromptPortion,
78
- });
79
-
80
- // Call your LLM
81
- const response = await llm.chat({
82
- messages: [
83
- { role: "system", content: enhancedSystemPrompt },
84
- { role: "user", content: enhancedUserPrompt },
85
- ],
86
- });
87
- ```
88
-
89
- ### Step 2: Post-Prompt
90
-
91
- Verify citations against the source documents.
92
-
93
- ```typescript
94
- const result = await dc.verifyCitations({
95
- llmOutput: response.content,
96
- fileDataParts, //optional
97
- });
98
-
99
- // result.verifications contains verification status + visual proof
100
- const { citations, verifications } = result;
101
-
102
- ```
103
-
104
- ### Step 3: Display
105
-
106
- Parse the LLM output and render verified citations inline with React components.
107
-
108
- ```tsx
109
- import { CitationComponent } from "@deepcitation/deepcitation-js/react";
110
- import {
111
- parseCitation,
112
- generateCitationKey,
113
- } from "@deepcitation/deepcitation-js";
114
- import "@deepcitation/deepcitation-js/react/styles.css";
115
-
116
- function Response({ llmOutput, verifications }) {
117
- // Split LLM output by citation tags and render inline
118
- const renderWithCitations = (text: string) => {
119
- const parts = text.split(/(<cite\s+[^>]*\/>)/g);
120
-
121
- return parts.map((part, index) => {
122
- if (part.startsWith("<cite")) {
123
- const { citation } = parseCitation(part);
124
- const citationKey = generateCitationKey(citation);
125
-
126
- return (
127
- <CitationComponent
128
- key={index}
129
- citation={citation}
130
- verification={verifications[citationKey]}
131
- />
132
- );
133
- }
134
- return <span key={index}>{part}</span>;
135
- });
136
- };
137
-
138
- return <div>{renderWithCitations(llmOutput)}</div>;
139
- }
140
- ```
141
-
142
- ---
143
-
144
- ## Core API
145
-
146
- ### DeepCitation Client
147
-
148
- ```typescript
149
- const dc = new DeepCitation({
150
- apiKey: string // Your API key (sk-dc-*)
151
- });
152
-
153
- // Upload and prepare source files
154
- await dc.prepareFiles(files: FileInput[])
155
-
156
- // Convert URLs/Office docs to PDF
157
- await dc.convertToPdf(urlOrOptions: string | ConvertOptions)
158
-
159
- // Verify LLM citations
160
- await dc.verifyCitations({ llmOutput, fileDataParts?, outputImageFormat? })
161
- ```
162
-
163
- ### Prompt Utilities
164
-
165
- ```typescript
166
- import {
167
- wrapCitationPrompt, // Wrap system + user prompts
168
- wrapSystemCitationPrompt, // Wrap system prompt only
169
- getAllCitationsFromLlmOutput, // Extract citations from response
170
- CITATION_JSON_OUTPUT_FORMAT, // JSON schema for structured output
171
- } from "@deepcitation/deepcitation-js";
172
- ```
173
-
174
- ### React Components
175
-
176
- ```typescript
177
- import {
178
- CitationComponent, // Primary citation display component
179
- CitationVariants, // Alternative citation styles
180
- UrlCitationComponent, // For URL-based citations
181
- } from "@deepcitation/deepcitation-js/react";
182
- ```
183
-
184
- ### Types
185
-
186
- ```typescript
187
- import type {
188
- Citation,
189
- Verification,
190
- SearchStatus,
191
- SearchAttempt,
192
- } from "@deepcitation/deepcitation-js";
193
- ```
194
-
195
- ---
196
-
197
- ## Examples
198
-
199
- Check out the [examples directory](./examples) for complete, runnable examples:
200
-
201
- - [**basic-verification**](./examples/basic-verification) – Core 3-step workflow
202
- - [**support-bot**](./examples/support-bot) – Customer support bot with invisible citations
203
- - [**nextjs-ai-sdk**](./examples/nextjs-ai-sdk) – Full-stack Next.js chat app
204
-
205
- ```bash
206
- cd examples/basic-verification
207
- npm install
208
- cp .env.example .env # Add your API keys
209
- npm run start:openai
210
- ```
211
-
212
- ---
213
-
214
- ## Documentation
215
-
216
- For comprehensive documentation including:
217
- - Full API reference
218
- - Integration patterns
219
- - Error handling
220
- - Advanced React components
221
- - TypeScript types
222
-
223
- Visit **[deepcitation.com/docs](https://deepcitation.com/docs)**
224
-
225
- ---
226
-
227
- ## Supported File Types
228
-
229
- **Documents:** PDF (native and scanned), URLs, Office formats (`.docx`, `.xlsx`, `.pptx`, etc.)
230
- **Images:** PNG, JPEG, TIFF, WebP, AVIF, HEIC
231
- **Media:** Audio and video (with timestamp-based citations)
232
-
233
- ---
234
-
235
- ## Contributing
236
-
237
- Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
238
-
239
- ---
240
-
241
- ## License
242
-
243
- MIT License - see [LICENSE](./LICENSE) for details.
244
-
245
- ---
246
-
247
- ## Links
248
-
249
- - [Documentation](https://deepcitation.com/docs)
250
- - [Get API Key](https://deepcitation.com/signup)
251
- - [Discord Community](https://discord.gg/deepcitation)
252
- - [GitHub Issues](https://github.com/deepcitation/deepcitation-js/issues)
253
- - [Examples](./examples)
1
+ <div align="center">
2
+
3
+ # @deepcitation/deepcitation-js
4
+
5
+ **Deterministic AI citation verification. Eliminate hallucination risk by proving every AI citation against source documents.**
6
+
7
+ [![npm version](https://img.shields.io/npm/v/@deepcitation/deepcitation-js.svg)](https://www.npmjs.com/package/@deepcitation/deepcitation-js)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
10
+
11
+ [Documentation](https://deepcitation.com/docs) · [Get Free API Key](https://deepcitation.com/signup) · [Examples](./examples) · [Discord](https://discord.gg/deepcitation)
12
+
13
+ </div>
14
+
15
+ ---
16
+
17
+ ## Why DeepCitation?
18
+
19
+ LLMs hallucinate. Even when given source documents, they make up quotes, invent statistics, and cite pages that don't exist. DeepCitation solves this by **deterministically verifying every citation** against your source documents—and generating visual proof.
20
+
21
+ <div align="center">
22
+ <img src="./examples/assets/deepcitation-medical-demo.gif" alt="DeepCitation medical documentation demo showing verified inline citations" width="700" />
23
+ <br />
24
+ <em>Medical documentation with verified inline citations — certainty at a glance</em>
25
+ </div>
26
+
27
+ ```
28
+ Before: "Revenue grew 45% [1]" → ❓ Did the LLM make this up?
29
+ After: "Revenue grew 45% [1]" → ✅ Verified on page 3, line 12 (with screenshot)
30
+ ```
31
+
32
+ ## Features
33
+
34
+ - **Deterministic Matching** – Every citation traced to its exact location. No fuzzy matching, no guessing.
35
+ - **Visual Proof** – Automated screenshots with highlighted text show exactly where citations come from.
36
+ - **Any LLM Provider** – Works with OpenAI, Anthropic, Google, Azure, or your own models.
37
+ - **React Components** – Pre-built components + composable primitives for citation UIs.
38
+ - **TypeScript Native** – Full type safety with comprehensive type definitions.
39
+
40
+ ## Installation
41
+
42
+ ```bash
43
+ npm install @deepcitation/deepcitation-js
44
+ ```
45
+
46
+ Get a free API key at [deepcitation.com](https://deepcitation.com/signup) — no credit card required.
47
+
48
+ ```bash
49
+ # .env
50
+ DEEPCITATION_API_KEY=sk-dc-your_api_key_here
51
+ ```
52
+
53
+ ---
54
+
55
+ ## Quick Start
56
+
57
+ DeepCitation works in three steps: **Pre-Prompt**, **Post-Prompt**, and **Display**.
58
+
59
+ ### Step 1: Pre-Prompt
60
+
61
+ Upload source documents and enhance your prompt with citation instructions.
62
+
63
+ ```typescript
64
+ import { DeepCitation, wrapCitationPrompt } from "@deepcitation/deepcitation-js";
65
+
66
+ const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
67
+
68
+ // Upload source files, this can be done before the user types their prompt
69
+ const { fileDataParts, deepTextPromptPortion } = await dc.prepareFiles([
70
+ { file: pdfBuffer, filename: "report.pdf" },
71
+ ]);
72
+
73
+ // Wrap prompts with citation instructions
74
+ const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
75
+ systemPrompt: "You are a helpful assistant...",
76
+ userPrompt: "Analyze this document",
77
+ deepTextPromptPortion,
78
+ });
79
+
80
+ // Call your LLM
81
+ const response = await llm.chat({
82
+ messages: [
83
+ { role: "system", content: enhancedSystemPrompt },
84
+ { role: "user", content: enhancedUserPrompt },
85
+ ],
86
+ });
87
+ ```
88
+
89
+ ### Step 2: Post-Prompt
90
+
91
+ Verify citations against the source documents.
92
+
93
+ ```typescript
94
+ const result = await dc.verifyCitations({
95
+ llmOutput: response.content,
96
+ fileDataParts, //optional
97
+ });
98
+
99
+ // result.verifications contains verification status + visual proof
100
+ const { citations, verifications } = result;
101
+
102
+ ```
103
+
104
+ ### Step 3: Display
105
+
106
+ Parse the LLM output and render verified citations inline with React components.
107
+
108
+ ```tsx
109
+ import { CitationComponent } from "@deepcitation/deepcitation-js/react";
110
+ import {
111
+ parseCitation,
112
+ generateCitationKey,
113
+ } from "@deepcitation/deepcitation-js";
114
+ import "@deepcitation/deepcitation-js/react/styles.css";
115
+
116
+ function Response({ llmOutput, verifications }) {
117
+ // Split LLM output by citation tags and render inline
118
+ const renderWithCitations = (text: string) => {
119
+ const parts = text.split(/(<cite\s+[^>]*\/>)/g);
120
+
121
+ return parts.map((part, index) => {
122
+ if (part.startsWith("<cite")) {
123
+ const { citation } = parseCitation(part);
124
+ const citationKey = generateCitationKey(citation);
125
+
126
+ return (
127
+ <CitationComponent
128
+ key={index}
129
+ citation={citation}
130
+ verification={verifications[citationKey]}
131
+ />
132
+ );
133
+ }
134
+ return <span key={index}>{part}</span>;
135
+ });
136
+ };
137
+
138
+ return <div>{renderWithCitations(llmOutput)}</div>;
139
+ }
140
+ ```
141
+
142
+ ---
143
+
144
+ ## Core API
145
+
146
+ ### DeepCitation Client
147
+
148
+ ```typescript
149
+ const dc = new DeepCitation({
150
+ apiKey: string // Your API key (sk-dc-*)
151
+ });
152
+
153
+ // Upload and prepare source files
154
+ await dc.prepareFiles(files: FileInput[])
155
+
156
+ // Convert URLs/Office docs to PDF
157
+ await dc.convertToPdf(urlOrOptions: string | ConvertOptions)
158
+
159
+ // Verify LLM citations
160
+ await dc.verifyCitations({ llmOutput, fileDataParts?, outputImageFormat? })
161
+ ```
162
+
163
+ ### Prompt Utilities
164
+
165
+ ```typescript
166
+ import {
167
+ wrapCitationPrompt, // Wrap system + user prompts
168
+ wrapSystemCitationPrompt, // Wrap system prompt only
169
+ getAllCitationsFromLlmOutput, // Extract citations from response
170
+ CITATION_JSON_OUTPUT_FORMAT, // JSON schema for structured output
171
+ } from "@deepcitation/deepcitation-js";
172
+ ```
173
+
174
+ ### React Components
175
+
176
+ ```typescript
177
+ import {
178
+ CitationComponent, // Primary citation display component
179
+ CitationVariants, // Alternative citation styles
180
+ UrlCitationComponent, // For URL-based citations
181
+ } from "@deepcitation/deepcitation-js/react";
182
+ ```
183
+
184
+ ### Types
185
+
186
+ ```typescript
187
+ import type {
188
+ Citation,
189
+ Verification,
190
+ SearchStatus,
191
+ SearchAttempt,
192
+ } from "@deepcitation/deepcitation-js";
193
+ ```
194
+
195
+ ---
196
+
197
+ ## Examples
198
+
199
+ Check out the [examples directory](./examples) for complete, runnable examples:
200
+
201
+ - [**basic-verification**](./examples/basic-verification) – Core 3-step workflow
202
+ - [**support-bot**](./examples/support-bot) – Customer support bot with invisible citations
203
+ - [**nextjs-ai-sdk**](./examples/nextjs-ai-sdk) – Full-stack Next.js chat app
204
+
205
+ ```bash
206
+ cd examples/basic-verification
207
+ npm install
208
+ cp .env.example .env # Add your API keys
209
+ npm run start:openai
210
+ ```
211
+
212
+ ---
213
+
214
+ ## Documentation
215
+
216
+ For comprehensive documentation including:
217
+ - Full API reference
218
+ - Integration patterns
219
+ - Error handling
220
+ - Advanced React components
221
+ - TypeScript types
222
+
223
+ Visit **[deepcitation.com/docs](https://deepcitation.com/docs)**
224
+
225
+ ---
226
+
227
+ ## Supported File Types
228
+
229
+ **Documents:** PDF (native and scanned), URLs, Office formats (`.docx`, `.xlsx`, `.pptx`, etc.)
230
+ **Images:** PNG, JPEG, TIFF, WebP, AVIF, HEIC
231
+ **Media:** Audio and video (with timestamp-based citations)
232
+
233
+ ---
234
+
235
+ ## Contributing
236
+
237
+ Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
238
+
239
+ ---
240
+
241
+ ## License
242
+
243
+ MIT License - see [LICENSE](./LICENSE) for details.
244
+
245
+ ---
246
+
247
+ ## Links
248
+
249
+ - [Documentation](https://deepcitation.com/docs)
250
+ - [Get API Key](https://deepcitation.com/signup)
251
+ - [Discord Community](https://discord.gg/deepcitation)
252
+ - [GitHub Issues](https://github.com/deepcitation/deepcitation-js/issues)
253
+ - [Examples](./examples)
@@ -0,0 +1,66 @@
1
+ var y=`
2
+ <citation-instructions priority="critical">
3
+ ## REQUIRED: Citation Format
4
+
5
+ You MUST cite sources using this exact syntax:
6
+
7
+ <cite attachment_id='ID' reasoning='why this supports the claim' key_span='1-3 key words' full_phrase='verbatim quote' start_page_key='page_number_N_index_I' line_ids='X-Y' />
8
+
9
+ ### Syntax Rules (MUST follow)
10
+
11
+ 1. **attachment_id**: Use the exact ID from the source document
12
+ 2. **reasoning**: Brief explanation of why this citation supports your claim (think first!)
13
+ 3. **key_span**: The 1-3 most important words from full_phrase
14
+ 4. **full_phrase**: Copy text VERBATIM from source. Escape quotes (\\') and newlines (\\n).
15
+ 5. **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.
16
+ 6. **line_ids**: Inclusive range (e.g., '2-6' or '4'). Infer intermediate lines since only every 5th line is shown.
17
+
18
+ ### Placement Rules
19
+
20
+ - Place <cite /> inline, typically at the end of a claim
21
+ - One citation per distinct idea, concept, or value (a sentence citing 3 different values needs 3 citations)
22
+ - Do NOT group citations at the end of the document
23
+ - The <cite /> tag is self-closing - never use <cite>...</cite>
24
+
25
+ ### Example
26
+
27
+ The company reported strong growth<cite attachment_id='abc123' reasoning='directly states revenue growth percentage' key_span='increased 45%' full_phrase='Revenue increased 45% year-over-year to $2.3 billion' start_page_key='page_number_2_index_1' line_ids='12-14' />
28
+
29
+ </citation-instructions>
30
+ `,T=`
31
+ <citation-instructions priority="critical">
32
+ ## REQUIRED: Audio/Video Citation Format
33
+
34
+ You MUST cite sources using this exact syntax:
35
+
36
+ <cite attachment_id='ID' reasoning='why this supports the claim' key_span='1-3 key words' full_phrase='verbatim transcript quote' timestamps='HH:MM:SS.SSS-HH:MM:SS.SSS' />
37
+
38
+ ### Syntax Rules (MUST follow)
39
+
40
+ 1. **attachment_id**: Use the exact ID from the source
41
+ 2. **reasoning**: Brief explanation of why this citation supports your claim (think first!)
42
+ 3. **key_span**: The 1-3 most important words from full_phrase
43
+ 4. **full_phrase**: Copy transcript text VERBATIM. Escape quotes (\\') and newlines (\\n).
44
+ 5. **timestamps**: Start and end time with milliseconds (e.g., '00:01:23.456-00:01:45.789')
45
+
46
+ ### Placement Rules
47
+
48
+ - Place <cite /> inline, typically at the end of a claim
49
+ - One citation per distinct idea, concept, or value (a sentence citing 3 different values needs 3 citations)
50
+ - Do NOT group citations at the end of the document
51
+ - The <cite /> tag is self-closing - never use <cite>...</cite>
52
+
53
+ </citation-instructions>
54
+ `,u="<citation-reminder>Remember: You MUST use <cite /> tags with all required attributes for every claim from source documents.</citation-reminder>",f="<citation-reminder>Remember: You MUST use <cite /> tags with timestamps for every claim from source media.</citation-reminder>";function x(i){let{systemPrompt:r,isAudioVideo:s=false}=i,e=s?T:y,t=s?f:u;return `${e.trim()}
55
+
56
+ ${r.trim()}
57
+
58
+ ${t}`}function S(i){let{systemPrompt:r,userPrompt:s,deepTextPromptPortion:e,isAudioVideo:t=false,addUserReminder:o=false}=i,c=x({systemPrompt:r,isAudioVideo:t}),n=s;if(e){let a=Array.isArray(e)?e:[e];n=`${a.map((l,m)=>a.length===1?`
59
+ ${l}`:`
60
+ ${l}`).join(`
61
+
62
+ `)}
63
+
64
+ ${s}`;}return o&&(n=`${n}
65
+
66
+ ${t?f:u}`),{enhancedSystemPrompt:c,enhancedUserPrompt:n}}var O={type:"object",properties:{attachmentId:{type:"string"},reasoning:{type:"string",description:"The logic connecting the form section requirements to the supporting source citation (think first!)"},keySpan:{type:"string",description:"The verbatim 1-3 words within fullPhrase that best support the 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)"},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.'},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","reasoning","keySpan","fullPhrase","startPageKey","lineIds"]},A={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"]};var d=4,I=3,P=5;function R(i,r){let s={};for(let e of i){for(let t=d;t<=e.length;t++){let o=e.slice(0,t),c=(o.match(/\d/g)||[]).length,n=(o.match(/[a-zA-Z]/g)||[]).length;if(o.length<d||c>0&&n<I||c===0&&n<P||i.some(m=>m!==e&&m.startsWith(o)))continue;let a=m=>m.replace(/[-\/\\^$*+?.()|[\]{}]/g,"\\$&"),p=(r.match(new RegExp(a(o),"g"))||[]).length,l=(r.match(new RegExp(a(e),"g"))||[]).length;if(p===l){s[o]=e;break}}if(!Object.values(s).includes(e))throw new Error(`Cannot find a safe unique prefix for ID "${e}" that meets the minimum requirements (length: ${d})`)}return s}function E(i,r){if(!r||r.length===0)return {compressed:i,prefixMap:{}};let s=Array.from(new Set(r)),e=JSON.stringify(i),t=R(s,e),o=Object.keys(t).sort((n,a)=>a.length-n.length),c=e;for(let n of o){let p=t[n].replace(/[-\/\\^$*+?.()|[\]{}]/g,"\\$&");c=c.replace(new RegExp(p,"g"),n);}return {compressed:JSON.parse(c),prefixMap:t}}function b(i,r){if(!r||Object.keys(r).length===0)return i;let s=Object.entries(r).sort((p,l)=>l[0].length-p[0].length),e,t=false;typeof i=="string"?e=i:(e=JSON.stringify(i),t=true);let o=e?.length;for(let[p,l]of s){let m=p.replace(/[-\/\\^$*+?.()|[\]{}]/g,"\\$&");e=e.replace(new RegExp(m,"g"),l);}let c=["attachmentId","attachment_id","attachment_ID","attachmentID","fileId","file_id","file_ID","fileID","fileid"];for(let[p,l]of s){let m=p.replace(/[-\/\\^$*+?.()|[\]{}]/g,"\\$&"),g=c.join("|"),h="([\"'`])",_=new RegExp(`(${g})(\\s*=\\s*)${h}${m}\\3`,"g");e=e.replace(_,`$1$2$3${l}$3`);}let n=e?.length,a=o-n;if(a>0)throw new Error(`[decompressedPromptIds] diff ${a} originalLength ${o} newLength ${n}`);return t?JSON.parse(e):e}export{y as a,T as b,u as c,f as d,x as e,S as f,O as g,A as h,E as i,b as j};