> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arcbeam.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Lineage

> Track which original source files power your AI responses

Source attribution connects AI responses back to the original files they came from—PDFs, web pages, internal docs, or code repositories. This transparency builds trust and helps you maintain your knowledge base.

## What Is Source Attribution?

Every document in your vector database came from somewhere. Source attribution tracks which of these original sources are actually being cited in AI responses.

<CardGroup cols={2}>
  <Card title="PDF Files" icon="file-pdf">
    Product manuals, research papers, and documentation
  </Card>

  <Card title="Web Pages" icon="globe">
    Blog posts, documentation sites, and online resources
  </Card>

  <Card title="Markdown Files" icon="markdown">
    READMEs, wiki pages, and technical documentation
  </Card>

  <Card title="Code Files" icon="code">
    Source code with docstrings and inline documentation
  </Card>

  <Card title="Database Records" icon="database">
    FAQ entries, support tickets, and structured data
  </Card>
</CardGroup>

## Why Source Attribution Matters

<CardGroup cols={2}>
  <Card title="Build Trust with Stakeholders" icon="handshake">
    When showing AI outputs to non-technical stakeholders, source attribution transforms unverifiable claims into trustworthy information. Instead of "The AI said we have a 30-day return policy," you can say "The AI said we have a 30-day return policy, based on our official Return Policy PDF last updated in March 2024."
  </Card>

  <Card title="Find Outdated Content" icon="clock">
    If traces are using a "Pricing Guide 2022.pdf" in 2025, you immediately know this source is outdated, needs to be updated or removed, and current pricing might be wrong in AI responses.
  </Card>

  <Card title="Prioritize Content Updates" icon="list-ol">
    Focus on updating high-impact sources. Source A used in 500 traces should be updated first, while Source B used in 2 traces can be lower priority.
  </Card>

  <Card title="Audit Compliance" icon="shield-check">
    For regulated industries, track which official documents were cited, ensure AI only uses approved sources, and demonstrate compliance in audits.
  </Card>
</CardGroup>

## Viewing Source Attribution

<Steps>
  <Step title="Navigate to Datasets">
    Go to **Data → Datasets** in the main navigation
  </Step>

  <Step title="Select a Dataset">
    Click on the dataset you want to analyze
  </Step>

  <Step title="Open Sources Tab">
    Navigate to the **Sources** tab to see the breakdown by original source file
  </Step>
</Steps>

## Source-Level Metrics

For each source file, you see these key metrics that help you understand source performance and value:

<CardGroup cols={2}>
  <Card title="Document Count" icon="file-lines">
    **How many documents** in your vector database came from this source.

    Example: "product-guide.pdf" was chunked into 45 documents.
  </Card>

  <Card title="Retrieval Count" icon="arrow-down-to-bracket">
    **How many times** documents from this source were retrieved across all traces.

    Shows which source files are most valuable.
  </Card>

  <Card title="Usage Rate" icon="percent">
    **Percentage of documents** from this source that have been retrieved at least once.

    | Rate      | Meaning                                        |
    | --------- | ---------------------------------------------- |
    | Above 70% | Highly relevant source, most chunks are useful |
    | 40-70%    | Good source, many chunks are used              |
    | Below 40% | Sparse source, many chunks unused              |
  </Card>

  <Card title="Last Retrieved" icon="calendar">
    **When** a document from this source was most recently used.

    | Timeframe          | Status                                     |
    | ------------------ | ------------------------------------------ |
    | Recent             | Actively cited                             |
    | Old (over 90 days) | Possibly outdated, check if still relevant |
  </Card>

  <Card title="Average Relevance" icon="chart-line">
    **Mean relevance score** for documents from this source when retrieved.

    | Score | Interpretation                                  |
    | ----- | ----------------------------------------------- |
    | High  | Well-written source, good for embeddings        |
    | Low   | Poorly structured source, hard to retrieve from |
  </Card>

  <Card title="User Satisfaction" icon="thumbs-up">
    **Feedback correlation** - How users rate traces that cited this source.

    | Feedback         | Interpretation                   |
    | ---------------- | -------------------------------- |
    | High thumbs up   | Trusted, accurate source         |
    | High thumbs down | Problematic source, needs review |
  </Card>
</CardGroup>

## Source Details Page

Click on any source to see comprehensive information about that source file.

### Full Source Information

<CardGroup cols={3}>
  <Card title="File Path or URL" icon="link">
    Where this source lives
  </Card>

  <Card title="Last Updated" icon="clock">
    When the original file was modified
  </Card>

  <Card title="Size" icon="hard-drive">
    Original file size
  </Card>

  <Card title="Format" icon="file-code">
    PDF, HTML, Markdown, etc.
  </Card>

  <Card title="Owner" icon="user">
    Who maintains this file (if tracked)
  </Card>
</CardGroup>

### Documents from This Source

List of all document chunks that came from this source:

* **Document content** (preview)
* **Retrieval count** per document
* **Relevance scores**

Click through to see individual document analytics.

### Traces Using This Source <Badge icon="clock" color="orange">Coming Soon</Badge>

Recent traces that retrieved documents from this source:

* **Trace ID** and link
* **User query**
* **Which document from this source was used**
* **Timestamp**
* **User feedback**

<Info>
  This view helps you see how this source is being used in practice and understand the context in which it's retrieved.
</Info>

### Related Sources

Other sources frequently cited alongside this one. For example: "Refund Policy PDF" often cited with "Returns FAQ HTML"

This shows which sources cover related topics and helps you understand content relationships.

## Use Cases

### Identify High-Impact Sources

<Steps>
  <Step title="Sort by Retrieval Count">
    Sort sources by **Retrieval Count** from high to low to see which sources are used most frequently
  </Step>

  <Step title="Note Top Sources">
    Identify the top 10 sources that are being retrieved most often
  </Step>

  <Step title="Prioritize Updates">
    Make these sources your priority for keeping up to date, and set alerts if they become outdated
  </Step>
</Steps>

<Check>
  **Result**: Focus maintenance efforts on high-value sources that directly impact AI response quality.
</Check>

### Find Outdated Sources

<Steps>
  <Step title="Filter by Last Updated">
    Filter sources to show only those with **Last Updated > 1 year ago**
  </Step>

  <Step title="Cross-check Retrieval Count">
    Check the **Retrieval Count** for these old sources. High retrieval count plus old date means urgent update needed.
  </Step>

  <Step title="Update and Re-sync">
    Update the source file and re-sync to Arcbeam to ensure current information is being used
  </Step>
</Steps>

<Check>
  **Result**: Keep AI responses accurate and current by proactively catching stale content.
</Check>

### Audit Which Sources Are Used

<Steps>
  <Step title="Review Sources with Retrievals">
    Review all sources that have been retrieved at least once
  </Step>

  <Step title="Check Against Approved List">
    Check each source against your approved sources list
  </Step>

  <Step title="Remove Unapproved Sources">
    If an unapproved source is being cited, remove it and re-sync the data source
  </Step>
</Steps>

<Check>
  **Result**: Compliance with internal policies and confidence that only approved content is cited.
</Check>

### Remove Unused Sources

<Steps>
  <Step title="Filter Zero Retrievals">
    Filter to sources with **zero retrievals** over the past 90 days
  </Step>

  <Step title="Review Each Source">
    Review each source to determine if it's truly irrelevant or if it might be needed in the future
  </Step>

  <Step title="Clean Up Database">
    Remove irrelevant sources from your vector database and re-sync
  </Step>
</Steps>

<Check>
  **Result**: Leaner, faster vector database that focuses on relevant content.
</Check>

### Track Source Quality

<Steps>
  <Step title="Sort by User Satisfaction">
    Sort sources by **User Satisfaction** from low to high to identify problematic sources
  </Step>

  <Step title="Review Bottom Sources">
    Check sources with the lowest satisfaction scores and read documents from those sources
  </Step>

  <Step title="Take Action">
    Determine the issue and take appropriate action:
    • Content is wrong → Update source
    • Content is confusing → Rewrite for clarity
    • Source is irrelevant → Remove it
  </Step>
</Steps>

<Check>
  **Result**: Higher quality AI responses through continuous source quality improvement.
</Check>

## Grouping Sources

Group related sources for easier management using these common organizational strategies:

<CardGroup cols={3}>
  <Card title="By Type" icon="layer-group">
    **Product Documentation** - All product guide PDFs

    **Marketing Content** - Blog posts, landing pages

    **Technical Docs** - API references, code docs

    **Support Materials** - FAQs, troubleshooting guides
  </Card>

  <Card title="By Department" icon="building">
    **Engineering** - Technical specifications, architecture docs

    **Product** - Product requirements, roadmaps

    **Customer Success** - Support articles, training materials

    **Legal** - Policies, terms of service
  </Card>

  <Card title="By Recency" icon="calendar-days">
    | Category | Last Updated     |
    | -------- | ---------------- |
    | Current  | In last 6 months |
    | Recent   | 6-12 months ago  |
    | Old      | 1-2 years ago    |
    | Stale    | Over 2 years ago |
  </Card>
</CardGroup>

## Source Update Workflow

When a source needs updating, follow this workflow to ensure quality improvements:

<Steps>
  <Step title="Identify the Issue">
    From Arcbeam, look for warning signs:
    • Source is outdated (last updated over 1 year ago)
    • High retrieval count combined with low user satisfaction
    • Negative feedback on traces using this source
  </Step>

  <Step title="Update the Original File">
    Edit the PDF, webpage, or markdown file to correct outdated information and improve clarity if needed
  </Step>

  <Step title="Update Vector Database">
    Replace old chunks with new ones, or add the new file and deprecate the old one. Ensure embeddings are regenerated for the updated content.
  </Step>

  <Step title="Re-sync to Arcbeam">
    Go to **Settings → Data Sources**, click **Sync Now**, and wait for the sync to complete
  </Step>

  <Step title="Verify Improvement">
    Check new traces using this source, monitor user feedback, and confirm responses are better
  </Step>
</Steps>

## Source Versioning <Badge icon="clock" color="orange">Coming Soon</Badge>

Track changes to sources over time to understand how content evolution impacts AI responses.

### Version History

When a source file is updated, version tracking helps you understand which content was used:

* **V1**: Original content
* **V2**: Updated content (March 2024)
* **V3**: Latest revision (January 2025)

<Info>
  See which version was used in each trace to debug issues like "This trace used the old pricing from V1, before we updated it" or "All traces after March use V2, which has the corrected information"
</Info>

## Compliance and Governance

For organizations with compliance requirements, source attribution provides critical audit capabilities:

| Capability            | What It Provides                                  | How To Use It                                                                                                                                                                             |
| --------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Approved Sources List | Control which sources can be used in AI responses | Maintain a list of approved sources (official documentation only, no personal notes or drafts, only sources reviewed by legal/compliance). Set alerts if unapproved sources are detected. |
| Source Audit Trail    | Complete history of source management             | Track who added each source, when it was added, who approved it, and when it was last reviewed.                                                                                           |
| Citation Requirements | Enforcement of citation standards                 | Configure Arcbeam to always include source attribution in responses, warn if responses lack source citations, or block responses without verifiable sources (strict mode).                |

## Best Practices

### Review High-Usage Sources Quarterly

Regularly review your top 20 sources by retrieval count to verify they're still accurate, check for updates in source files, and re-sync if changes were made.

<Tip>
  Set up a recurring calendar reminder to review high-impact sources every quarter to stay ahead of potential issues.
</Tip>

### Set Update Reminders

For critical sources, establish a review cadence with clear ownership:

* Set calendar reminders to review
* Assign owners for each major source
* Track updates in a spreadsheet

**Example tracking**:

Source: Product Pricing PDF
Owner: Sales Team
Review Frequency: Quarterly
Last Review: Jan 2025
Next Review: Apr 2025

### Correlate with Business Events

After major changes, immediately update and re-sync affected sources:

| Business Event | Required Source Updates      |
| -------------- | ---------------------------- |
| Product launch | Update product docs          |
| Policy change  | Update policy PDFs           |
| Rebranding     | Update all marketing content |

<Warning>
  Failing to update sources after major business changes can lead to AI responses with outdated or incorrect information.
</Warning>

### Use Source Tags

Tag sources for easier organization and filtering:

| Tag            | Purpose                              |
| -------------- | ------------------------------------ |
| **official**   | Approved, authoritative sources      |
| **draft**      | Work-in-progress, not for production |
| **deprecated** | Old sources, scheduled for removal   |
| **external**   | Third-party sources                  |

### Monitor for Deleted Sources

Set up alerts to catch when a source file is deleted from its original location but is still being cited in traces. When this happens, update your vector database to remove the obsolete source.

## Next Steps

<CardGroup cols={2}>
  <Card title="Document Usage" icon="file" href="/v0/data-insights/see-what-data-is-used">
    Drill down to individual document metrics
  </Card>

  <Card title="Dataset Analytics" icon="chart-bar" href="/v0/data-insights/dataset-analytics">
    Understand dataset-level patterns
  </Card>

  <Card title="Retrieved Documents" icon="file-lines" href="/v0/debugging/trace-issues-to-source-data">
    See sources cited in traces
  </Card>

  <Card title="Add Data Sources" icon="arrows-rotate" href="/v0/setup/add-data-sources">
    Keep source data up to date
  </Card>
</CardGroup>