Semantic Clusters

Fields with similar meanings are automatically grouped into semantic clusters using AI embeddings. For example, "Vendor Name", "Supplier Name", and "Company Name" cluster together because they represent the same underlying concept. You can manually merge or split clusters from the Field Graph view (the list / Field Graph toggle on the Field Registry, under Registry in the sidebar). Clusters are a key mechanism for cross-document field normalization: they allow the platform to recognize that different document types use different names for the same data point.

Clustering uses the same three-band similarity model as field resolution. Fields with similarity >= 0.80 are automatically grouped into the same cluster. Fields in the 0.50-0.79 range are flagged as potential cluster candidates for manual confirmation. Fields below 0.50 similarity are kept separate. This graduated approach prevents false merges while still surfacing useful grouping suggestions.

From the Field Graph view, you can manually merge two clusters when you know they represent the same concept (e.g., merging a "Ship To Address" cluster with a "Delivery Address" cluster). You can also split a field out of a cluster if it was incorrectly grouped. These manual adjustments are permanent and improve the resolution model for all future documents: the system learns from your corrections.

Semantic clusters serve a practical purpose beyond organization. When a job runs, the resolution engine uses clusters to transfer values between fields that belong to the same cluster. If a document has a field called "Supplier Name" and your schema expects "Vendor Name", the cluster linkage allows the value to transfer automatically without an AI call. This is one of the key mechanisms that reduces extraction cost as your registry matures.

Cluster Operations

• Merge — Combine two clusters that represent the same concept. All fields from both clusters are unified under a single canonical entry.
• Split — Remove a field from a cluster if it was incorrectly grouped. The split field becomes its own independent cluster.
• Inspect — View all fields in a cluster, their source document types, and occurrence counts to understand why they were grouped.

Working with Clusters via API

Cluster membership is readable through the REST API. Use GET /v1/fields?cluster_id={uuid} to list every field in a cluster, and GET /v1/fields/{id}/similar to retrieve up to 10 fields most similar to a given field by cosine similarity on its name embedding (all-MiniLM-L6-v2, 384 dimensions). This is useful for auditing cluster quality programmatically, for example flagging pairs with high similarity that live in separate clusters as merge candidates to review in the Field Graph. Merging and splitting themselves are manual operations performed in the Field Graph view.

curl "https://api.talonic.com/v1/fields?cluster_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

curl https://api.talonic.com/v1/fields/a1b2c3d4-e5f6-7890-abcd-ef1234567890/similar \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Response:
# {
#   "data": [
#     { "id": "c9d0e1f2-...", "canonical_name": "supplier_name", "similarity": 0.91 },
#     { "id": "d0e1f2a3-...", "canonical_name": "company_name", "similarity": 0.84 }
#   ]
# }

A well-curated cluster set has a direct impact on extraction cost and accuracy. When clusters accurately represent field synonyms, the resolution engine can transfer values between related fields without triggering an AI call. For instance, if "Ship To Address" and "Delivery Address" are correctly clustered together, a document containing "Ship To Address" will automatically resolve when your schema expects "Delivery Address". Without the cluster link, this would require an AI extraction call, increasing both cost and latency.

Cluster quality is especially important during the early stages of platform adoption. When your registry is still growing, incorrect clusters can cause value transfers between unrelated fields, leading to extraction errors that are difficult to trace. Take time during the first few weeks to review the Field Graph view and split any clusters where the platform has grouped fields that look similar in name but have different semantic meanings. For example, "Order Date" and "Order Number" might score above the 0.80 similarity threshold due to the shared "Order" prefix, but they represent fundamentally different data types and should be separate clusters.