Skip to main content

Document Graph

The Document Graph is a visual force-directed (D3-force) layout of the bipartite document-entity graph: it shows every linked document, every shared entity, and the link key connections between them. It lives on the Cases page under Assemble, where a view toggle switches between the cases list and the graph (the older /document-graph address redirects there). The graph makes it easy to verify that linking is producing sensible clusters before you rely on cases for review.

Documents are drawn as circles colored by document type, and entities as diamonds colored by link key category: purple for Identity, blue for Transaction, and teal for Reference. Edges take the color of their category, and tightly connected clusters naturally pull together through the force simulation, which zooms to fit once the layout settles. Clicking a node opens a side panel: for a document it shows the document type and an Open document link, for an entity its category and how many documents carry it, and for both a list of connections with the category and the field each link came from.

  • Force-directed layout with distinct shapes for document (circle) and entity (diamond) nodes
  • Click a node to open its detail panel and trace document-entity connections
  • A Labels checkbox shows node names once you zoom in far enough; long names are truncated
  • Graphs above 500 nodes show a node and edge counter in the corner
  • Export downloads the current graph as JSON for offline analysis
  • Index all documents runs a linking backfill and reloads the graph when it finishes

Using the graph during setup

The graph view is particularly useful during onboarding. When you first upload documents, the graph gives you immediate visual feedback on whether your link key configuration is producing sensible clusters. If you see one massive cluster with everything connected, a frequent value may be acting as a bridge: check the Field Registry and reclassify the offending field. If you see many disconnected single-document nodes, your documents may lack shared identifiers, or the right fields are not yet link keys. Once you are confident in your link key configuration, the list view is more practical for day-to-day case review and triage.

The graph also explains what it left out. Every entity node carries an excluded flag and, when set, an excluded_reason: owner for an Identity value in more than half of the linked documents, or high_frequency for any value in more than 30% of them. Excluded entities are drawn but do not join documents into cases. If a large component would still contain more than 40% of all documents, it is split again using only Transaction and Reference entities. The stats block reports total, linked, and unlinked document counts plus the excluded values by name. Index all documents is shown to users who may change model configuration (an Admin in a self-service organization); it starts the backfill and polls progress every two seconds.

Case templates

Case templates capture recurring document type patterns, for example "Invoice + Purchase Order + Contract". Discovery fingerprints each case by its set of document types, and any pattern shared by 3 or more cases becomes a template named "Discovered: …", unless it overlaps an existing template by 80% or more. Discovery runs automatically after a linking backfill once at least 3 cases exist, and Admins can also create, edit, delete, or re-discover templates by hand. Each expected document type can be required or optional.

A case is matched to the template whose expected document types it covers best, and the match only counts when that share reaches the template's match threshold (0.5 by default). Templates then serve as completeness monitors: the Missing Document Type anomaly detector (D4) raises a warning for every required type the case lacks and an info-level anomaly for every missing optional type. This is particularly valuable in procurement workflows where a complete audit trail requires specific document types to be present.

Read the linking graph behind the view
# The full bipartite document-entity graph (what the UI renders):
curl -s https://api.talonic.com/v1/linking/graph \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> {
#   "nodes": [
#     { "id": "…", "type": "document", "label": "Invoice_4521.pdf", "document_type": "Invoice" },
#     { "id": "entity:…", "type": "entity", "label": "Operations", "category": "reference",
#       "document_count": 512, "excluded": true, "excluded_reason": "high_frequency" }
#   ],
#   "edges": [ { "source": "…", "target": "entity:…", "field_key": "department", "category": "reference" } ],
#   "cases": [ { "case_key": "8c1ca050535e3ea3", "document_ids": [ … ], "entity_ids": [ … ] } ],
#   "entity_groups": [ … ],
#   "stats": { "total_documents": 1840, "linked_documents": 1622, "unlinked_documents": 218,
#              "excluded_entities": 2, "owner_entities": [ … ], "high_frequency_entities": [ "Operations" ] }
# }
Check the open gaps of one case
# Completeness of one case (cases are addressed by their UUID):
curl -s https://api.talonic.com/v1/cases/CASE_UUID/completeness \
  -H "Authorization: Bearer $TALONIC_API_KEY"
# -> { "case_id": "…", "document_count": 2, "open_findings": 1, "dismissed_findings": 0,
#      "completeness": 0.67,
#      "missing": [ { "kind": "dangling_reference", "via_field": "contract_number", "value": "C-2207" } ] }

The completeness endpoint scores open gaps: completeness is the member count divided by members plus open findings, so a case with no open gaps reads 1.0. To see which template a case matched and which required or optional types it expects, read GET /v1/cases/{key}/anomalies, whose template object carries the template name with its required and optional types. Use both to catch incomplete transaction bundles, such as an invoice and purchase order without their contract, before they reach downstream systems.

Document Graph vs. entity graph

The public API also exposes a separate entity graph at GET /v1/linking/entity-graph. It is built from all extracted field values rather than only link key fields, returns entities, documents, field_names, edges, and stats, and is rebuilt lazily when new documents have been resolved since the last build; POST /v1/linking/entity-graph/recompute forces a rebuild. The Document Graph is the one that drives cases. The linking graph response is cached for 60 seconds per organization, so a change can take up to a minute to show; viewers restricted by access rules or Collections always get a fresh, filtered read.

Templates are auto-discovered; you do not need to define them manually. The system analyzes existing cases and proposes a template when at least 3 cases share the same set of document types. Read the matched template from GET /v1/cases/{key}/anomalies and the open gaps from GET /v1/cases/{key}/completeness.

Frequently asked questions

What is the Document Graph?+
The Document Graph is a visual force-directed layout of the bipartite document-entity graph. It shows how documents are connected through shared link key entities, and which frequent entities were excluded from case formation.
What are case templates?+
Case templates are recurring document type patterns. A pattern shared by 3 or more cases is discovered automatically as a template, and Admins can also create and edit templates. A case matches a template when it covers at least the template's match threshold of expected types (0.5 by default).
Where do I switch between graph and list views?+
On the Cases page under Assemble, use the view toggle in the header. Both views show the same underlying linking data; the graph is best for checking link key configuration, the list for day-to-day review.
How do case templates trigger anomaly detection?+
Once a case matches a template (e.g., Invoice + Purchase Order + Contract), the Missing Document Type detector (D4) checks it against the template. Each missing required type raises a warning and each missing optional type an info-level anomaly, which helps you catch incomplete transaction bundles before they reach downstream systems.
How do I check whether a case is complete?+
Call GET /v1/cases/{key}/completeness for the member count, open and dismissed findings, a 0 to 1 completeness ratio, and the list of missing references. For template coverage, read the template object returned by GET /v1/cases/{key}/anomalies.
Why does an entity appear in the graph but not connect anything into a case?+
It is probably excluded: check its excluded flag and excluded_reason. Identity values in more than half of linked documents are treated as the owner of the document set, and any value in more than 30% of them counts as high frequency. Both stay visible but are skipped when cases are formed.

Related

Cases
Entity Linking
Anomaly Detection
Link Keys