Citation and Provenance Display in Responses

When a response draws on context from both the Knowledge Base and the Codebase Context Fabric, Keeptrusts generates structured citations that trace each part of the response back to its originating source. This page explains how citations appear in the chat interface and API responses, and how you configure their display.

Use this page when

• You want to understand how citations from Knowledge Base and Fabric sources appear in cached responses.
• You need to verify that provenance metadata survives cache retrieval and is displayed correctly.
• You are configuring citation display settings or troubleshooting missing source attribution.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

Citation Object Structure

Every citation in a response contains a structured object with the following fields:

Field	Type	Description
citation_id	string (UUID)	Unique identifier for this citation
source_type	string	Either knowledge_base or codebase_context_fabric
source_reference	object	Source-specific reference details (see below)
relevance_score	float (0.0–1.0)	How relevant this source was to the cited portion
token_contribution	integer	Number of context tokens this source contributed
text_span	object	Character range in the response that this citation supports

Text Span

The text_span object identifies the exact portion of the response text that a citation supports:

{
  "start": 142,
  "end": 287
}

These are zero-based character offsets into the response text. A single response span can have multiple supporting citations, and a single source can support multiple spans.

Knowledge Base Citations

When a response draws on KB content, the citation's source_reference contains:

{
  "source_type": "knowledge_base",
  "source_reference": {
    "asset_id": "uuid-of-the-asset",
    "asset_title": "Session Management Policy",
    "asset_version": 3,
    "promotion_status": "active",
    "binding_id": "uuid-of-the-binding",
    "asset_detail_url": "/knowledge-base/assets/uuid-of-the-asset"
  }
}

In the chat interface, KB citations display as:

• Asset title — clickable link to the KB asset detail page.
• Version badge — shows the version number (e.g., "v3").
• Status indicator — shows the promotion status (active, draft, or archived).

Codebase Context Fabric Citations

When a response draws on fabric content, the citation's source_reference contains:

{
  "source_type": "codebase_context_fabric",
  "source_reference": {
    "workspace_id": "uuid-of-workspace",
    "workspace_name": "backend-api",
    "file_path": "src/auth/session.ts",
    "symbol": "validateSession",
    "language": "typescript",
    "last_indexed_at": "2026-04-30T13:45:00Z",
    "commit_sha": "a1b2c3d4"
  }
}

In the chat interface, fabric citations display as:

• File path — shown as a code-formatted path (e.g., src/auth/session.ts).
• Symbol name — function or class name if applicable.
• Workspace label — identifies which codebase the context came from.
• Freshness indicator — relative timestamp (e.g., "indexed 45 minutes ago").

Mixed Citation Display

When a response uses both KB and fabric context, the chat interface groups citations by source type. A typical response footer shows:

Sources:
  📋 Session Management Policy (v3, active)
  📋 Authentication Standards (v2, active)
  💻 src/auth/session.ts → validateSession (backend-api, 45m ago)
  💻 src/middleware/auth.ts → authMiddleware (backend-api, 45m ago)

The response text itself uses inline citation markers (superscript numbers) that link to the corresponding source in the footer.

API Response Format

In the API response JSON, citations appear in the citations array:

{
  "response": "The validateSession function checks token expiry...",
  "citations": [
    {
      "citation_id": "cit-uuid-1",
      "source_type": "knowledge_base",
      "source_reference": {
        "asset_id": "asset-uuid",
        "asset_title": "Session Management Policy",
        "asset_version": 3,
        "promotion_status": "active"
      },
      "relevance_score": 0.92,
      "token_contribution": 856,
      "text_span": { "start": 0, "end": 45 }
    },
    {
      "citation_id": "cit-uuid-2",
      "source_type": "codebase_context_fabric",
      "source_reference": {
        "workspace_id": "ws-uuid",
        "file_path": "src/auth/session.ts",
        "symbol": "validateSession",
        "last_indexed_at": "2026-04-30T13:45:00Z"
      },
      "relevance_score": 0.88,
      "token_contribution": 234,
      "text_span": { "start": 46, "end": 189 }
    }
  ]
}

Configuring Citation Display

You control citation visibility through the citation_display configuration:

citation_display:
  show_provenance: true
  show_relevance_scores: false
  show_token_contribution: false
  group_by_source_type: true
  max_citations_displayed: 10
  inline_markers: true

Configuration Fields

Field	Default	Description
show_provenance	true	Display source provenance details in the citation footer
show_relevance_scores	false	Show the numeric relevance score next to each citation
show_token_contribution	false	Show how many tokens each source contributed
group_by_source_type	true	Group citations by KB vs fabric in the display
max_citations_displayed	10	Maximum number of citations shown in the UI (all remain in the API response)
inline_markers	true	Show superscript citation numbers inline in the response text

Showing Relevance Scores

When you enable show_relevance_scores, each citation displays its score:

Sources:
  📋 Session Management Policy (v3, active) — relevance: 0.92
  💻 src/auth/session.ts → validateSession — relevance: 0.88

This is useful during configuration tuning to verify that your budget allocation and ranking weights produce expected results.

Delineating KB vs Fabric Contributions

The chat interface visually distinguishes which parts of a response were informed by KB content versus fabric content. When group_by_source_type is enabled:

• Sections primarily supported by KB citations may show a subtle indicator that the content reflects organizational policy or standards.
• Sections primarily supported by fabric citations may show an indicator that the content reflects current codebase state.

This delineation helps readers understand the authority and freshness of different parts of a response without examining individual citations.

Audit and Export

Citation records are stored in the event log alongside the full response. You can export citation data for compliance reporting:

• Filter events by source_type to find all responses that cited a specific KB asset.
• Track which codebase files are most frequently cited across your organization.
• Identify responses where citations had low relevance scores (potential quality issues).

Next steps

• Understand how provenance is tracked end-to-end in Provenance Separation.
• Learn how joint selection determines which content gets cited in Joint Context Selection.
• See how caching interacts with citation freshness in Cache Keys with Mixed Context.

For AI systems

• Canonical terms: Keeptrusts, citations, provenance display, knowledge_base source_type, codebase_context_fabric source_type, citation_id, text_span, relevance_score.
• Exact feature/config names: citations array in API response, source_type field, source_reference object, text_span (start/end offsets), relevance_score, token_contribution, group_by_source_type display option.
• Best next pages: Provenance Separation, Joint Context Selection, Cache Keys with Mixed Context.

For engineers

• KB citations include asset_id, asset_version, promotion_status, binding_id, and a clickable link to the KB asset detail page.
• Fabric citations include workspace_id, file_path, symbol, language, last_indexed_at, and commit_sha.
• Use text_span (zero-based character offsets) to identify which response sections each citation supports.
• Enable debug.show_context_selection: true for verbose citation diagnostics including relevance scores.
• Export citation data from the event log for compliance audits — filter by source_type to find all responses citing a specific KB asset.

For leaders

• Citations provide complete audit trail: every response traces back to specific policy documents (KB) and code files (fabric) that informed it.
• Visual distinction between KB and fabric citations helps readers assess authority (policy-backed) vs. currency (code-backed) of response content.
• Low relevance scores in citations surface quality issues — monitor these to identify context configuration improvements.
• Citation records support regulatory compliance: prove that AI responses were informed by approved organizational policies.