Loading pattern preview
BlocksTools & Utilities
Jev Entity Resolution
Jev Entity Resolution
Resolve messy card statement descriptors to the merchants behind them. Code blocks and vetoes, Jev answers one boolean per pair, and unsure matches wait for review.
Use this when records name the same merchant, customer, or product in different ways and you need them matched, with unsure cases left for a person.
Loading pattern preview
Problems solved
Technical challenges this implementation handles out of the box.
- Match records that name the same real-world thing in different words
- Keep hard conflicts and merges in code while a model judges identity
- Send unsure matches to a review queue instead of merging them
Use cases
Products and workflows this pattern is designed to support.
- Merchant names from card or bank statement lines
- Duplicate customers or companies across two lists
- Matching products across supplier catalogs
Compare with
Similar patterns, and when each one is the better fit.
Jev Semantic ClusteringUse this when you have a pile of comments, tickets, or survey answers and need to discover the themes in them before any categories exist.
Jev Email TagsUse this when you are multi-label tagging a known set of messages, such as an inbox, without writing a classifier prompt or allowing invented labels.
Jev Search FilterFreeUse this when you want semantic search over a known catalog, such as emoji or icons, without building embeddings, scoring each item with a boolean.
Jev Table QueryUse this when users type filter or sort requests over a fixed table, with column sorts run in code and other phrases scored by the model per row.
Setup
Requirements, wiring steps, and what this pattern adds to your project.
Getting started
Pick how you want to pull this pattern in. Then wire env vars and routes the same way.
- 1
Download → Next.js app
Use Download → Next.js app in the preview toolbar. You get a zip scaffold (Pro downloads rewrite preview `/view/.../api/*` paths to `/api/*` automatically).
- 2
Extract the zip and install dependencies
Unzip the archive, then run `pnpm install` (or npm / yarn) in the project folder.
- 3
Fill .env.local
The download includes .env.local placeholders when needed. Add real values for: AI_GATEWAY_API_KEY.
- 4
Customize the agent and tool files
Adapt prompts, tools, and stop conditions in the generated project for your product.
- 5
Run the app and open the pattern route
Run `pnpm dev`, open the setup/checklist page if present, then navigate to the generated pattern route and verify responses.
Environment variables
AI_GATEWAY_API_KEYGet key
Capabilities
AI SDK APIs
experimental_evaluateembedManygenerateTextgatewayProviders
Jev
External services
gatewayvercel-ai-gatewayUpstash
Files added
24 files
app/page.tsxapp/layout.tsxapp/api/resolve/route.tscomponents/resolution-demo.tsxcomponents/statement-list.tsxcomponents/result-header.tsxcomponents/review-queue.tsxcomponents/merchant-list.tsxcomponents/typesafe-ai.tsxhooks/use-resolution.tslib/statement.tslib/descriptors.tslib/candidate-pairs.tslib/match-questions.tslib/match-evaluation.tslib/match-policy.tslib/entity-graph.tslib/merchant-names.tslib/resolve-pipeline.tslib/review.tslib/result-copy.tslib/rate-limit.tslib/request-utils.tsREADME.md
Dependencies
7 total
npm packages
6UpstashAISDKlucide-reactmotionNext.jsReact
Registry components
button
Critical files
6 files
lib/resolve-pipeline.tsresolveMerchants is the whole pipeline: buildRecords (exact match in code), embedMany, candidatePairs, evaluatePairs, categoryConflicts, resolveLinks, reviewCandidates, then names. The same resolveLinks call over raw cosine similarity is the baseline. Embedding, Jev model, and naming are injectable so tests never touch the network.
lib/entity-graph.tsresolveLinks merges groups by average linkage over compared pairs at MERGE_FLOOR. A vetoed pair can never share a group no matter how high the probability. A merge needs two compared pairs unless only one exists. Every record ends in exactly one group. Do not use connected components for identity: one wrong link would merge two real entities.
lib/match-policy.tscategoryConflicts is the hard conflict rule checked in code: two descriptors the issuer files under different categories are never auto-merged. reviewCandidates queues group pairs that still look like a match, with the reason. Replace the category rule with your own structured conflicts (domain, country, tax id) and keep it in code.
lib/descriptors.tscleanDescriptor strips processor prefixes, order references, store numbers, and phone numbers so identical keys match in code and never reach a model. buildRecords groups charges by that key.
lib/match-questions.tsbuildMatchQuestions, MERGE_FLOOR (0.80), and REVIEW_FLOOR (0.60). The same-merchant criteria are the identity rule. Change the criteria to change what counts as one entity.
lib/review.tsapplyReview applies a person's Same or Keep separate answer in code. Same merges totals and members and re-points other queued items. The model is not asked again.
Requirements
- Complexity
- Intermediate
- Setup time
- ~5 minutes
- Node
- 24+
- Memory
- 256MB
Upstash Redis for deployed demo rate limiting
