Entity & concept graph
What this page is — the capability that turns a dense agreement into a navigable map: its parties, defined terms, obligations, amounts and clauses, and the links that bind them.
What it is for — so getting your bearings in an unfamiliar fifty-page contract is a matter of following relationships rather than reading top to bottom.
The problem it solves — understanding who owes what to whom in a long contract means reading it end to end, every time.
Route: /org/papers/documents/<document>/ai → Understand → Entity & concept graph ·
Permission: Use AI drafting/extraction/Q&A for documents. ·
Utility: papers_entity_graph · Cost: 450 credits estimated, 1,800 maximum.
1. What it is
A complex contract hides a web of who-does-what. The graph builder reads the whole document and lays that web out as structured data: a list of material entities, each typed and traced to the clause it came from, and the relationships that connect them.
The value is in the second list. Any capability can list the parties; this one tells you that party
P1 owes obligation OBL2, which depends on date D3, which is defined by term T1.
Unlike most Papers AI, the result does not only sit in a result tab. Running it replaces this
document's ai_extracted edges in the organisation's knowledge graph with the new set.
That is a replace, not a merge: a re-run discards the previous AI-derived edges for this document. Edges from other sources are untouched, and other documents are unaffected. It is the reason a re-run is a decision rather than a free refresh — see the knowledge graph.
| Returns | |
|---|---|
| Entity & concept graph | The structure — nodes and the links between them |
| Extract key terms | The values — parties, dates, obligations as a flat typed record |
| Summarize | The narrative — prose a person reads |
Extraction and the graph overlap in what they read and differ entirely in shape. Extraction answers "what are the obligations?"; the graph answers "which obligation hangs off which definition, and what breaks if that date moves?".
2. Why you would use it
The specific problem this solves is onboarding. Someone hands you an agreement you have never seen, and the question is not "what does it say" but "how does it work".
- It is the fastest route into an unfamiliar contract. Start at the parties, follow their obligations, then see what each obligation depends on or references. That path takes minutes; the linear read takes an afternoon.
- It exposes dependency, which prose hides. A payment obligation that depends on a delivery date defined three sections earlier is a single sentence in the graph and a scavenger hunt in the PDF.
external_reffinds the documents you did not know you needed. Pointers to other agreements and statutes are pulled out as first-class nodes, so the MSA this SOW hangs off stops being a footnote.- Every node cites its clause.
detailcarries the value and where it came from, so the graph is a navigation aid back into the document rather than a summary that replaces it. - A sparse graph is a finding. It maps only what the document says. Thin output usually means a thin draft.
3. What you provide
Nothing. The graph builder is a one-press capability with no parameters.
| Input | Required | Notes |
|---|---|---|
| — | — | No parameters. It works on the open document |
The richness of the graph tracks the completeness of the document. An early draft with unfilled fields produces few amount and date nodes, and the dependency relationships that make the graph worth building are the first thing to go missing.
4. What it reads automatically
| Read from the document | Used for |
|---|---|
| Document text — the full rendered body | Every node and edge |
| Title & family — e.g. "MSA" | Frames which relationships to expect |
| Party names — everyone named | Seeds the party nodes |
| Field summary — filled schema fields | Amount and date nodes carry real values |
5. What you get back
entities[] — every material node.
| Field | Type | Values | Means |
|---|---|---|---|
id | string | e.g. P1, OBL2 | A short stable handle. Relationships point at these |
label | string | — | The human name of the node |
type | enum | party, defined_term, obligation, date, amount, clause, external_ref | What kind of thing it is |
detail | string | — | The value or definition, plus the clause it came from |
relationships[] — every material link.
| Field | Type | Values | Means |
|---|---|---|---|
from | string | an entity id | The source node |
to | string | an entity id | The target node |
type | enum | owes, references, defines, depends_on, party_to, governs | The nature of the link |
note | string | — | One line explaining it |
summary — 2–3 sentences describing the shape of the document: who the key actors are and what
binds them. Read this first; it tells you where to start walking.
6. Worked example
A newly assigned contract manager opens a licence agreement they have never read and presses Entity & concept graph.
Input: none.
One entity and the relationship that gives it meaning:
entity —
id: "OBL2"·type: "obligation"·label: "Pay licence fee"·detail: "USD 40,000/yr — cl. 5.1"relationship —
from: "P1"·to: "OBL2"·type: "owes"·note: "Customer owes the annual licence fee under clause 5.1"
How the manager reads it. They start at summary, then at the party nodes. P1 is the
customer, so they follow every edge leaving P1 — three owes edges, one party_to. OBL2 is the
money. From OBL2 they follow a depends_on edge to a date node, which is the renewal date, which
is defined by a defined_term node three sections away.
Four hops, about ninety seconds, and they know what the agreement costs, when it is due, and what
that date is contingent on. detail gives them clause 5.1 to read for the exact wording.
7. Running it
- Open the document in Orbit Papers.
- Open the AI Assistant drawer, or go to the document's AI workspace.
- Choose Entity & concept graph under Understand.
- The graph appears in the result tab, and this document's AI-derived edges in the knowledge graph are replaced with it.
Read the result by following ids. Every relationship's from and to name an id in
entities[]. Tracing those ids is what makes this a graph rather than two lists.
Because a re-run replaces rather than merges (§1), re-run when the document has materially changed — not to refresh a result you simply want to look at again.
Available for auto-run on submit, round or finalize from the type's AI Config tab. Given the
replace behaviour, on_finalize keeps the organisation-wide graph consistent with finished
documents. See AI configuration.
8. The admin contract
| Must be true | Where | What happens if it is not |
|---|---|---|
| Your role holds Use AI drafting/extraction/Q&A for documents. | Role editor | The AI Assistant button does not appear |
The papers_entity_graph utility is active | Orbit AI Flow → utilities | "This utility is currently disabled" |
| The utility is enabled for your organisation | /org/ai-utilities | Absent from Understand, with no error |
papers.ai_monthly_credit_cap not yet reached | System Config | "monthly AI credit cap reached: n of n credits used this month" |
| The knowledge-graph surface is enabled | Papers module settings | The run succeeds and still writes edges — but nobody can browse them |
For a confidential document, auto-run is default-denied — a platform administrator must set
papers.ai_confidential_cloud to the literal allow, and the block appears only in the server log.
A manual press still works, and where a local model key is configured the run is forced on-prem and
audited on the timeline as ai_local_routed.
9. Don't confuse this with…
| The knowledge graph | The organisation-wide graph across all documents. This builds one document's contribution to it |
| Extract key terms | A flat typed record. This is a network |
| Cross-document consistency | Compares documents against each other. This maps within one |
| Negotiation analytics | Maps the argument. This maps the agreement |
10. Troubleshooting
| Symptom | Cause |
|---|---|
| The graph is sparse | It maps only what the document says. A thin graph usually means a thin draft (§3) |
| Edges from a previous run have gone | A re-run replaces this document's AI-derived edges rather than merging (§1) |
A relationship points at an id not in entities[] | A malformed result — re-run. Every from/to should resolve |
No external_ref nodes on a document I know references an MSA | The reference is implicit rather than named in the text |
| Amounts and dates are missing | The document's schema fields are unfilled, so there is nothing to build those nodes from |
| Edges appear in the graph browser that I did not create | Other sources contribute edges too; only ai_extracted ones come from here |
| The capability is missing from Understand | Role lacks Use AI drafting/extraction/Q&A for documents., or the utility is off for the organisation (§8). The document type does not gate it — AI Config controls auto-run only |