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

# Graph Lineage

> Audit trail for how knowledge graph entities and relationships were created or changed

## Overview

**Graph lineage** records how every meaningful change to the knowledge graph was made — which document,
data source, enrichment rule, or manual review produced each property update or relationship.

Each change is stored as a `:LineageRecord` node in Neo4j, linked to the affected entity via
`:HAS_LINEAGE`. Lineage is **additive**: legacy `source` lists on nodes continue to work during rollout.

Lineage is **not** included in routine AI context or graph visualizations. It is available on demand in
the graph explorer, provenance panel, and read API.

## What gets recorded

| Source                 | When                                                   | Example                                    |
| ---------------------- | ------------------------------------------------------ | ------------------------------------------ |
| **Document ingestion** | New/updated entities or relationships from a file      | Contract attribute extracted from a PDF    |
| **Structured data**    | Scan order row creates or updates a node/relationship  | CRM import updates `annual_revenue`        |
| **Enrichment**         | An enrichment rule adds or updates graph data          | Company `headquarter_region` from LLM rule |
| **Manual review**      | A human resolves a match review (merge, confirm, skip) | Reviewer merges duplicate Engagement nodes |

Each record includes:

* **Operation** — `node_created`, `node_updated`, `relationship_created`, etc.
* **Changes** — property-level `{property, old, new}` transitions
* **Source metadata** — path, data source name, rule name, job id
* **Model** — LLM model name when applicable (ingestion, enrichment)
* **Reviewer** — email address for manual match-review actions
* **Timestamp** — when the write occurred

Document-sourced records may link to the `:Document` node via `:DERIVED_FROM` for one-click file access.

## Viewing lineage in the UI

### Graph explorer (provenance)

When exploring entities cited in chat:

1. Open the **provenance graph explorer** for a response
2. Select an entity node
3. Scroll to the **Graph Lineage** section in the inspector

The timeline shows operations newest-first, with source links, model name, reviewer (if manual), and
property changes. Relationship operations show type and from → to endpoints.

### Provenance panel — View lineage

In the provenance entity cards, click **View lineage** to open the graph explorer focused on that
entity's lineage history.

### Chat — asking about origin

Assistants can call the `get_entity_lineage` tool when you ask where a fact came from (e.g. *"How do we
know this company's revenue?"*). Lineage is never injected proactively into every response.

## Enrichment jobs and Postgres audit

Enrichment rules write graph lineage for each successful apply. The Django **EnrichmentResult** row
also stores an optional **`lineage_record_id`** linking to the graph record for admin cross-reference.

See [Enrichment Rules](/admin-guide/enrichment-rules) for running jobs; open a job's results to see
which nodes were updated and the linked lineage id when present.

## Read API

Authenticated REST endpoints (prefix `/api/graph-lineage/`):

| Endpoint                         | Purpose                                                          |
| -------------------------------- | ---------------------------------------------------------------- |
| `GET /nodes/{element_id}/`       | Lineage history for an entity (optional `?property=` filter)     |
| `GET /records/{lineage_id}/`     | Single record with resolved document link                        |
| `GET /jobs/{job_type}/{job_id}/` | All records for an ingestion file, scan order, or enrichment job |

Relationship lineage appears when querying **either** endpoint node (`from_id` / `to_id` matching).

## Matched document entities

When document ingestion **matches** an existing node and only adds the file to `source` (no new
attributes), a node-level lineage record is **not** created. Relationship lineage from the same
ingest still records links to related entities (e.g. Contract → Company).

## Limitations (v1)

* No automatic backfill for data ingested before lineage shipped
* `relationship_deleted` not recorded (no delete paths wired yet)
* Legacy `client` UI does not include lineage; use the current admin/chat UI (`client-cn`)
* Deprecation of `n.source` in favor of lineage-only provenance is a follow-up ticket

## Related

* [Enrichment Rules](/admin-guide/enrichment-rules) — post-ingestion LLM enrichment
* [Sources & Citations](/user-guide/sources-and-citations) — document citations in chat
* [Matching Strategies](/admin-guide/matching-strategies) — entity matching during ingestion
* Architecture plan: `docs/plans/graph-lineage-architecture.md` (repository)