@deepcitation/deepcitation-js 1.1.26 → 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.
- package/LICENSE +21 -21
- package/README.md +253 -253
- package/lib/chunk-2IZXUOQR.js +66 -0
- package/lib/chunk-4FGOHQFP.cjs +66 -0
- package/lib/chunk-CFXDRAJL.cjs +1 -0
- package/lib/chunk-DEUSSEFH.js +2 -0
- package/lib/chunk-F2MMVEVC.cjs +1 -0
- package/lib/chunk-J7U6YFOI.cjs +2 -0
- package/lib/chunk-O2XFH626.js +1 -0
- package/lib/chunk-RQPZSRID.js +1 -0
- package/lib/client/index.cjs +1 -0
- package/lib/client/{DeepCitation.d.ts → index.d.cts} +159 -3
- package/lib/client/index.d.ts +342 -2
- package/lib/client/index.js +1 -1
- package/lib/index.cjs +1 -0
- package/lib/index.d.cts +127 -0
- package/lib/index.d.ts +126 -23
- package/lib/index.js +1 -22
- package/lib/prompts/index.cjs +1 -0
- package/lib/prompts/index.d.cts +196 -0
- package/lib/prompts/index.d.ts +196 -3
- package/lib/prompts/index.js +1 -3
- package/lib/react/index.cjs +4 -0
- package/lib/react/index.js +4 -18
- package/lib/types/index.cjs +1 -0
- package/lib/types/index.d.cts +96 -0
- package/lib/types/index.d.ts +96 -11
- package/lib/types/index.js +1 -7
- package/package.json +62 -10
- package/lib/client/DeepCitation.js +0 -374
- package/lib/client/types.d.ts +0 -154
- package/lib/client/types.js +0 -1
- package/lib/parsing/normalizeCitation.d.ts +0 -5
- package/lib/parsing/normalizeCitation.js +0 -198
- package/lib/parsing/parseCitation.d.ts +0 -79
- package/lib/parsing/parseCitation.js +0 -431
- package/lib/parsing/parseWorkAround.d.ts +0 -2
- package/lib/parsing/parseWorkAround.js +0 -73
- package/lib/prompts/citationPrompts.d.ts +0 -138
- package/lib/prompts/citationPrompts.js +0 -168
- package/lib/prompts/promptCompression.d.ts +0 -14
- package/lib/prompts/promptCompression.js +0 -127
- package/lib/prompts/types.d.ts +0 -4
- package/lib/prompts/types.js +0 -1
- package/lib/react/CitationComponent.d.ts +0 -93
- package/lib/react/CitationComponent.js +0 -371
- package/lib/react/CitationVariants.d.ts +0 -132
- package/lib/react/CitationVariants.js +0 -284
- package/lib/react/DiffDisplay.d.ts +0 -10
- package/lib/react/DiffDisplay.js +0 -33
- package/lib/react/Popover.d.ts +0 -15
- package/lib/react/Popover.js +0 -20
- package/lib/react/UrlCitationComponent.d.ts +0 -83
- package/lib/react/UrlCitationComponent.js +0 -224
- package/lib/react/VerificationTabs.d.ts +0 -10
- package/lib/react/VerificationTabs.js +0 -36
- package/lib/react/icons.d.ts +0 -18
- package/lib/react/icons.js +0 -16
- package/lib/react/index.d.ts +0 -16
- package/lib/react/primitives.d.ts +0 -101
- package/lib/react/primitives.js +0 -193
- package/lib/react/types.d.ts +0 -283
- package/lib/react/types.js +0 -1
- package/lib/react/useSmartDiff.d.ts +0 -16
- package/lib/react/useSmartDiff.js +0 -64
- package/lib/react/utils.d.ts +0 -43
- package/lib/react/utils.js +0 -89
- package/lib/types/boxes.d.ts +0 -11
- package/lib/types/boxes.js +0 -1
- package/lib/types/citation.d.ts +0 -39
- package/lib/types/citation.js +0 -1
- package/lib/types/search.d.ts +0 -19
- package/lib/types/search.js +0 -1
- package/lib/types/verification.d.ts +0 -27
- package/lib/types/verification.js +0 -11
- package/lib/utils/diff.d.ts +0 -60
- package/lib/utils/diff.js +0 -414
- package/lib/utils/sha.d.ts +0 -10
- 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
|
-
[](https://www.npmjs.com/package/@deepcitation/deepcitation-js)
|
|
8
|
-
[](https://opensource.org/licenses/MIT)
|
|
9
|
-
[](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
|
+
[](https://www.npmjs.com/package/@deepcitation/deepcitation-js)
|
|
8
|
+
[](https://opensource.org/licenses/MIT)
|
|
9
|
+
[](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};
|