From 004cfa247786146bc09f56b6e461316c4aa06cd3 Mon Sep 17 00:00:00 2001 From: Benson Date: Mon, 16 Mar 2026 16:26:44 +0700 Subject: [PATCH 1/5] docs: replace tag references with current [N] numeric marker format The XML tag format was removed in favor of numeric [N] markers with a <<>> JSON block. Updated all prose/comments that still referenced the old format across 5 doc files. Co-Authored-By: Claude Sonnet 4.6 --- docs/frameworks/langchain.md | 2 +- docs/frameworks/nextjs.md | 2 +- docs/frameworks/vercel-ai-sdk.md | 2 +- docs/getting-started.md | 2 +- docs/index.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/frameworks/langchain.md b/docs/frameworks/langchain.md index 3537c8ce..918a8e88 100644 --- a/docs/frameworks/langchain.md +++ b/docs/frameworks/langchain.md @@ -98,7 +98,7 @@ async function answerWithCitations(pdfPath: string, question: string) { const llmOutput = response.content as string; // 5. Extract and verify citations - // getAllCitationsFromLlmOutput parses tags from the LLM response. + // getAllCitationsFromLlmOutput parses numeric [N] markers from the LLM response's <<>> block. // verifyAttachment checks each citation against the source document. const citations = getAllCitationsFromLlmOutput(llmOutput); const citationCount = Object.keys(citations).length; diff --git a/docs/frameworks/nextjs.md b/docs/frameworks/nextjs.md index 14d34cf0..35978d67 100644 --- a/docs/frameworks/nextjs.md +++ b/docs/frameworks/nextjs.md @@ -259,7 +259,7 @@ export default function Home() { A common question: **does `verifyAttachment()` work on partial (mid-stream) responses?** -**No — verification requires the complete LLM output.** The LLM writes `` tags that may span multiple streamed chunks. Calling `getAllCitationsFromLlmOutput()` on a partial response will miss citations whose tags haven't fully arrived yet. +**No — verification requires the complete LLM output.** The LLM appends its `<<>>` block at the very end of the response. Calling `getAllCitationsFromLlmOutput()` on a partial response will miss the citation data if that block hasn't arrived yet. The correct pattern (used in the example above) is: diff --git a/docs/frameworks/vercel-ai-sdk.md b/docs/frameworks/vercel-ai-sdk.md index aa2481c1..3c697fb0 100644 --- a/docs/frameworks/vercel-ai-sdk.md +++ b/docs/frameworks/vercel-ai-sdk.md @@ -32,7 +32,7 @@ npm install deepcitation ai @ai-sdk/openai @ai-sdk/react ## How DeepCitation Integrates with streamText -`streamText` streams tokens to the client. Citation verification must happen **after** streaming ends — `` tags in the LLM's response may span multiple chunks, so you need the complete output before calling `getAllCitationsFromLlmOutput()`. +`streamText` streams tokens to the client. Citation verification must happen **after** streaming ends — the LLM appends its `<<>>` block at the very end of the response, so you need the complete output before calling `getAllCitationsFromLlmOutput()`. The integration model is: diff --git a/docs/getting-started.md b/docs/getting-started.md index 73a8a35a..29668cfc 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -35,7 +35,7 @@ Wrap prompts, call your LLM, verify citations, and optionally persist results. ### Section 3: Display with CitationComponent -Parse `` tags, generate citation keys, and render inline with verification status. +Parse numeric `[N]` markers via `parseCitationResponse`, map to citation keys, and render inline with verification status. --- diff --git a/docs/index.md b/docs/index.md index 26383927..275b32d9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -43,7 +43,7 @@ Verify AI citations against source documents. Visual proof for every claim. 1. **Install & Setup** — Install, import types, initialize client, prepare sources, configure proof images 2. **Server Side** — Wrap prompts, call your LLM, verify citations, optionally persist results -3. **Display with CitationComponent** — Parse `` tags, generate citation keys, render inline with verification status +3. **Display with CitationComponent** — Parse numeric `[N]` markers via `parseCitationResponse`, map to citation keys, render inline with verification status --- From cc91bfa289ec0b350d9f239ce1a77295788a03e1 Mon Sep 17 00:00:00 2001 From: Benson Date: Mon, 16 Mar 2026 16:26:50 +0700 Subject: [PATCH 2/5] chore: refresh agent index (repo-map + docs-site-map to HEAD 9e9dcbb) Picks up new src/docs/ and examples/static-html/ directories, corrects parsing/ description, and bumps staleness tracking to current commit. Co-Authored-By: Claude Sonnet 4.6 --- docs/agents/docs-site-map.md | 32 ++++++++++++++++---------------- docs/agents/repo-map.md | 10 ++++++---- 2 files changed, 22 insertions(+), 20 deletions(-) diff --git a/docs/agents/docs-site-map.md b/docs/agents/docs-site-map.md index 4315fba5..104ccdbf 100644 --- a/docs/agents/docs-site-map.md +++ b/docs/agents/docs-site-map.md @@ -1,6 +1,6 @@ --- -generated_at: "2026-03-12T09:32:04Z" -commit_sha: "224f843" +generated_at: "2026-03-16T09:26:19Z" +commit_sha: "9e9dcbb" page_count: 16 tracked: 14 stale: 0 @@ -17,72 +17,72 @@ stale: 0 ### Components - **File**: `docs/components.md` - **Description**: React CitationComponent documentation -- **Staleness**: FRESH (8/15 commits since last update) +- **Staleness**: FRESH (14/15 commits since last update) ### Curl Guide - **File**: `docs/curl-guide.md` - **Description**: Direct API usage with curl examples -- **Staleness**: FRESH (3/15 commits since last update) +- **Staleness**: FRESH (4/15 commits since last update) ### LangChain - **File**: `docs/frameworks/langchain.md` - **Description**: DeepCitation + LangChain: citation verification in your RAG pipeline -- **Staleness**: FRESH (3/20 commits since last update) +- **Staleness**: FRESH (7/20 commits since last update) ### Home - **File**: `docs/index.md` - **Description**: DeepCitation - Verify AI citations against source documents with visual proof -- **Staleness**: FRESH (5/30 commits since last update) +- **Staleness**: FRESH (4/30 commits since last update) ### Types - **File**: `docs/types.md` - **Description**: TypeScript interface definitions for DeepCitation -- **Staleness**: FRESH (3/10 commits since last update) +- **Staleness**: FRESH (7/10 commits since last update) ### Next.js App Router - **File**: `docs/frameworks/nextjs.md` - **Description**: DeepCitation + Next.js App Router: server components, streaming, and use client boundaries -- **Staleness**: FRESH (7/15 commits since last update) +- **Staleness**: FRESH (14/15 commits since last update) ### Getting Started - **File**: `docs/getting-started.md` - **Description**: Installation and quick start guide for DeepCitation -- **Staleness**: FRESH (6/20 commits since last update) +- **Staleness**: FRESH (12/20 commits since last update) ### Styling - **File**: `docs/styling.md` - **Description**: CSS customization options for CitationComponent -- **Staleness**: FRESH (7/20 commits since last update) +- **Staleness**: FRESH (12/20 commits since last update) ### Verification Statuses - **File**: `docs/verification-statuses.md` - **Description**: Understanding verification result statuses -- **Staleness**: FRESH (2/10 commits since last update) +- **Staleness**: FRESH (3/10 commits since last update) ### API Reference - **File**: `docs/api-reference.md` - **Description**: REST API endpoints for file preparation and citation verification -- **Staleness**: FRESH (3/10 commits since last update) +- **Staleness**: FRESH (4/10 commits since last update) ### Vercel AI SDK - **File**: `docs/frameworks/vercel-ai-sdk.md` - **Description**: DeepCitation + Vercel AI SDK: streamText, useChat, and citation verification -- **Staleness**: FRESH (7/15 commits since last update) +- **Staleness**: FRESH (13/15 commits since last update) ### Code Examples - **File**: `docs/code-examples.md` - **Description**: SDK usage examples and integration patterns -- **Staleness**: FRESH (3/20 commits since last update) +- **Staleness**: FRESH (7/20 commits since last update) ### Error Handling - **File**: `docs/error-handling.md` - **Description**: Error handling patterns for DeepCitation in production -- **Staleness**: FRESH (1/15 commits since last update) +- **Staleness**: FRESH (2/15 commits since last update) ### Frameworks - **File**: `docs/frameworks/index.md` - **Description**: Framework-specific integration guides for DeepCitation -- **Staleness**: FRESH (3/30 commits since last update) +- **Staleness**: FRESH (7/30 commits since last update) ### 404 - **File**: `docs/404.md` diff --git a/docs/agents/repo-map.md b/docs/agents/repo-map.md index 58495914..1e45dd1c 100644 --- a/docs/agents/repo-map.md +++ b/docs/agents/repo-map.md @@ -1,7 +1,7 @@ --- -generated_at: "2026-03-12T09:31:59Z" -commit_sha: "224f843" -commit_sha_full: "224f843143979aa746e08bc002a0407965686ec2" +generated_at: "2026-03-16T09:26:13Z" +commit_sha: "9e9dcbb" +commit_sha_full: "9e9dcbb046ae65ba18fece1103ea7ff3ff68cce8" stale_after_commits: 30 --- @@ -30,10 +30,11 @@ Source src/ # Source files __tests__/ # Unit test files client/ # DeepCitation API client + docs/ # (no description) drawing/ # Drawing/canvas utilities markdown/ # Markdown rendering (renderMarkdown, markdownVariants) testing/ # Markdown test helpers - parsing/ # Citation extraction: parseCitation, parseCitationResponse, parseWorkAround + parsing/ # Citation extraction: parseCitation, normalizeCitation, parseWorkAround prompts/ # LLM prompt templates (citationPrompts, promptCompression) react/ # React components and hooks (CitationComponent, SourcesList, i18n, popovers) hooks/ # Extracted React hooks @@ -85,5 +86,6 @@ examples/ # Integration examples (Next.js, etc.) assets/ # Shared example assets basic-verification/ # Basic citation verification example nextjs-ai-sdk/ # Next.js AI SDK integration example + static-html/ # (no description) url-example/ # URL citation verification example ``` From f9809dd5d268493931fb866259f97cde1779ebdf Mon Sep 17 00:00:00 2001 From: Benson Date: Mon, 16 Mar 2026 16:52:36 +0700 Subject: [PATCH 3/5] docs: update Full Integration Example to current API (prepareAttachments + verifyAttachment) Replaces deprecated uploadFile/verify with prepareAttachments/verifyAttachment. Fixes attachmentId destructuring (now from fileDataParts[0].attachmentId). Adds React render step to getting-started showing parseCitationResponse/markerMap pattern matching IntegrateSection RENDER_CODE. Updates index.md Quick Install snippet to match. Co-Authored-By: Claude Sonnet 4.6 --- docs/getting-started.md | 46 +++++++++++++++++++++++++++++++++-------- docs/index.md | 8 +++---- 2 files changed, 41 insertions(+), 13 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 29668cfc..a890ad52 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -64,12 +64,13 @@ bun add deepcitation ```typescript import { DeepCitation, wrapCitationPrompt, getAllCitationsFromLlmOutput } from "deepcitation"; -const deepcitation = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY }); +const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY }); -// 1. Upload your source document -const { attachmentId, deepTextPromptPortion } = await deepcitation.uploadFile(pdfBuffer, { - filename: "report.pdf" -}); +// 1. Prepare your source document +const { fileDataParts, deepTextPromptPortion } = await dc.prepareAttachments([ + { file: pdfBuffer, filename: "report.pdf" }, +]); +const attachmentId = fileDataParts[0].attachmentId; // 2. Wrap your prompts with citation instructions const systemPrompt = "You are a helpful assistant that cites sources."; @@ -77,7 +78,7 @@ const systemPrompt = "You are a helpful assistant that cites sources."; const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({ systemPrompt, userPrompt, - deepTextPromptPortion // Pass file content directly + deepTextPromptPortion, }); // 3. Call your LLM @@ -85,15 +86,15 @@ const response = await yourLLM.chat({ messages: [ { role: "system", content: enhancedSystemPrompt }, { role: "user", content: enhancedUserPrompt }, - ] + ], }); // 4. Extract and verify citations const citations = getAllCitationsFromLlmOutput(response.content); -const verified = await deepcitation.verify(attachmentId, citations); +const { verifications } = await dc.verifyAttachment(attachmentId, citations); // 5. Use verification results -for (const [key, result] of Object.entries(verified.verifications)) { +for (const [key, result] of Object.entries(verifications)) { console.log(`Citation ${key}: ${result.searchState?.status}`); if (result.verificationImageBase64) { // Display visual proof to users @@ -101,6 +102,33 @@ for (const [key, result] of Object.entries(verified.verifications)) { } ``` +### Section 3: Render (React) + +```tsx +import { parseCitationResponse } from "deepcitation"; +import { CitationComponent } from "deepcitation/react"; + +const { visibleText, citations, markerMap, splitPattern } = parseCitationResponse(llmOutput); + +return ( +

+ {visibleText.split(splitPattern).map((part, i) => { + const key = markerMap[Number(part.replace(/[\[\]]/g, ""))]; + if (key) { + return ( + + ); + } + return {part}; + })} +

+); +``` + --- ## Authentication diff --git a/docs/index.md b/docs/index.md index 275b32d9..66c16787 100644 --- a/docs/index.md +++ b/docs/index.md @@ -65,12 +65,12 @@ npm install deepcitation ```typescript import { DeepCitation, wrapCitationPrompt, getAllCitationsFromLlmOutput } from "deepcitation"; -const deepcitation = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY }); +const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY }); -// Upload and verify in 3 steps -const { attachmentId, deepTextPromptPortion } = await deepcitation.uploadFile(pdfBuffer, { filename: "report.pdf" }); +// Prepare, wrap, verify in 3 steps +const { fileDataParts, deepTextPromptPortion } = await dc.prepareAttachments([{ file: pdfBuffer, filename: "report.pdf" }]); const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({ systemPrompt, userPrompt, deepTextPromptPortion }); // ... call your LLM ... const citations = getAllCitationsFromLlmOutput(response.content); -const verified = await deepcitation.verify(attachmentId, citations); +const { verifications } = await dc.verifyAttachment(fileDataParts[0].attachmentId, citations); ``` From 47a7ab7e755839bb00213d45b1af527bc2af1329 Mon Sep 17 00:00:00 2001 From: Benson Date: Mon, 16 Mar 2026 16:58:07 +0700 Subject: [PATCH 4/5] docs: add contributor-facing BRANDING.md at package root (B6a) Creates packages/deepcitation/BRANDING.md with a clean, audience-appropriate sub-brand guide for GitHub contributors: color tokens, customization examples, typography rules, and key contributor rules. The existing docs/agents/branding.md (agent/implementation-focused) is kept intact and cross-linked. The new root file covers only the public surface (--dc-* tokens, DeepCitationTheme, font/radius rules) without internal implementation details. Co-Authored-By: Claude Sonnet 4.6 --- BRANDING.md | 103 ++++++++++++++++++++++++++++++++++++++++ docs/agents/branding.md | 1 + 2 files changed, 104 insertions(+) create mode 100644 BRANDING.md diff --git a/BRANDING.md b/BRANDING.md new file mode 100644 index 00000000..d0277e03 --- /dev/null +++ b/BRANDING.md @@ -0,0 +1,103 @@ +# DeepCitation SDK — Sub-Brand Guide + +The SDK is a **sub-brand** of DeepCitation. It is designed to embed harmoniously within any host application, so its visual defaults intentionally differ from the DeepCitation web app. + +--- + +## Sub-Brand vs Web App + +| Property | Web App | SDK | +|----------|---------|-----| +| Color palette | Slate scale (`slate-*`) | `--dc-*` CSS custom properties | +| Border radius | Sharp (`rounded-none`) | Soft (`rounded-lg` / 8px) | +| Font | Inter (loaded) | System font stack | +| Customization | Tailwind classes | `--dc-*` tokens + `` React prop | + +The soft corners and system font ensure the SDK feels at home in any host UI without imposing the web app's editorial aesthetic. + +--- + +## Color Tokens + +All SDK colors are expressed as `--dc-*` CSS custom properties. Host applications can override the entire palette via CSS or the `DeepCitationTheme` React component. + +### Surface & Text + +| Token | Light | Dark | Usage | +|-------|-------|------|-------| +| `--dc-background` | `#ffffff` | `#27272a` | Card / popover / drawer surface | +| `--dc-muted` | `#f4f4f5` | `#3f3f46` | Subdued surface: code blocks, tab bars | +| `--dc-foreground` | `#18181b` | `#fafafa` | Primary text | +| `--dc-muted-foreground` | `#71717a` | `#a1a1aa` | Body text, secondary labels | +| `--dc-subtle-foreground` | `#a1a1aa` | `#71717a` | Icons, timestamps, tertiary text | +| `--dc-border` | `#e4e4e7` | `#3f3f46` | Borders and dividers | +| `--dc-ring` | `#3b82f6` | `#3b82f6` | Focus ring | + +### Verification Status + +| Token | Light | Dark | Usage | +|-------|-------|------|-------| +| `--dc-verified` | `#16a34a` | `#22c55e` | Verified citation | +| `--dc-partial` | `#f59e0b` | `#fbbf24` | Partial match | +| `--dc-destructive` | `#ef4444` | `#f87171` | Not found / error | +| `--dc-pending` | `#a1a1aa` | `#71717a` | Pending / loading | + +--- + +## Customization + +### CSS (global override) + +```css +:root { + --dc-background: #fdfbf7; + --dc-border: #e2e0dc; + --dc-verified: #0d9488; +} +.dark { + --dc-background: #1c1917; + --dc-border: #44403c; +} +``` + +### React component + +```tsx +import { DeepCitationTheme } from "deepcitation"; + + +``` + +All `--dc-*` tokens are accepted as camelCase props (e.g. `mutedForeground`, `subtleForeground`). + +--- + +## Typography + +The SDK uses the system font stack. **Never** load or reference Inter, Playfair Display, or any external font in SDK components. + +```css +font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, + "Helvetica Neue", Arial, sans-serif; +``` + +--- + +## Key Rules for Contributors + +- Use `text-dc-*` / `bg-dc-*` / `border-dc-*` Tailwind classes — never hardcode `slate-N` for persistent colors +- Use `rounded-lg` (8px) for containers — never `rounded-none` +- Do not add external font dependencies +- Do not override `--dc-*` tokens with `!important` or inline styles +- Animation timing constants live in `src/react/constants.ts` — do not inline values + +--- + +## References + +- Full implementation rules for contributors modifying SDK internals: [`docs/agents/branding.md`](docs/agents/branding.md) +- Web app brand (full brand spec): [`packages/deepcitation-web/BRANDING.md`](../deepcitation-web/BRANDING.md) +- Styling guide for consumers: [docs.deepcitation.com/styling](https://docs.deepcitation.com/styling) diff --git a/docs/agents/branding.md b/docs/agents/branding.md index aff78533..462a0bd3 100644 --- a/docs/agents/branding.md +++ b/docs/agents/branding.md @@ -226,3 +226,4 @@ SDK uses `rounded-lg` (8px) as default. This is the opposite of the web app's `r - Animation rules: `docs/agents/animation-transition-rules.md` - React citation UI: `docs/agents/react-citation-ui.md` - Web app full brand: `packages/deepcitation-web/BRANDING.md` +- Contributor-facing sub-brand overview: `packages/deepcitation/BRANDING.md` From c084900fdfacc31302ffd2222da49f391d901af8 Mon Sep 17 00:00:00 2001 From: Benson Date: Mon, 16 Mar 2026 17:37:52 +0700 Subject: [PATCH 5/5] fix(readme): fix black-on-black logos in GitHub dark mode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Uses + prefers-color-scheme to swap to brand-color variants (logos/color/) in dark mode. OpenAI → #10A37F, Anthropic → #D4A27F, Google → #4285F4. Vercel's color variant is also black so adds a white SVG (docs/assets/vercel-white.svg) and references it via raw.githubusercontent.com for the dark-mode srcset. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 2 +- docs/assets/vercel-white.svg | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 docs/assets/vercel-white.svg diff --git a/README.md b/README.md index 056752ff..86d3acc3 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ A set of high-quality React components to help you build production-ready attrib **Works with any LLM** -- OpenAI, Anthropic, Google, AI SDK, local models, or any leading model. -| OpenAI logo | Anthropic logo | Google Gemini logo | Vercel AI SDK logo | +| OpenAI logo | Anthropic logo | Google Gemini logo | Vercel AI SDK logo | | --- | --- | --- | --- | | OpenAI ✔ | Anthropic ✔ | Gemini ✔ | AI SDK ✔ | diff --git a/docs/assets/vercel-white.svg b/docs/assets/vercel-white.svg new file mode 100644 index 00000000..46b5ac45 --- /dev/null +++ b/docs/assets/vercel-white.svg @@ -0,0 +1 @@ +Vercel