Building GraphSentinel: from a fraud alert to an investigation
A graph-grounded investigation system that turns uncertain transaction signals into attributable evidence, explicit uncertainty, and a policy-routed next action.
A model score can say “look here.” It cannot explain whether a customer changed devices, several customer groups share an origin, a disputed charge resembles previous behavior, or a block would harm an innocent cardholder.
What I built
GraphSentinel is an evidence-driven fraud investigation system for analysts. It accepts a risk signal, customer report, or analyst request; opens a case; explores a bounded relationship neighborhood; identifies graph motifs; retrieves relevant closed cases; separates risk from evidence confidence; and chooses a policy-valid next action.
The repository contains a working FastAPI service, two analyst views, 20 benchmark answer files, GSQL schema and queries, a restricted graph adapter, an MCP facade, deterministic policy controls, SQLite case progression for the synthetic workflow, SAR generation, benchmark auditing, and automated tests.
The dataset forced the design
The supplied HHGOA IEEE data contains 590,742 transactions, 144,432 identity records, 5,565 closed cases, and 20 benchmark triggers. It deliberately omits a direct fraud label for the transactions under investigation.
It also contains no merchant identifier and no verified card identifier on every transaction. I therefore did not invent Transaction → Merchant edges or assign transactions to physical cards by guessing from issuer attributes. Customers connect to transactions through the supplied customer_id; card-to-transaction relationships exist only where the case pack or closed cases explicitly provide them.
Architecture
The state machine makes investigation inspectable: initial retrieval, pattern analysis, case-memory search, uncertainty assessment, evidence request, reassessment, action selection, policy check, stopping decision, approval, and case update. Every tool call records its reason, parameters, result summary, state, and latency.
Graph traversal, thresholds, permissions, and persistence remain deterministic. An optional OpenAI Responses API component can synthesize a cited narrative, but it cannot change probabilities, policy routes, or actions. Unknown evidence citations cause a fallback to the deterministic summary.
How TigerGraph is used
The HHGOA graph model represents customers, cards, transactions, detailed device profiles, email domains, billing regions, closed cases, investigation cases, and evidence. Five allowlisted GSQL queries answer bounded investigation questions:
- retrieve a transaction and its customer and identity context;
- inspect the customer’s bounded transaction window;
- find other customers sharing a detailed device profile;
- retrieve related closed cases and explicitly known cards;
- retrieve transactions connected to historical cases.
The GraphRAG layer does not dump raw rows into a language model. It converts retrieval results into evidence packages containing a claim, source, query reference, real entity identifiers, and strength. Historical outcomes are supporting context, never labels for the current transaction.
The repository includes the GSQL schema, queries, idempotent importer, graph retrieval adapter, MCP tools, and case writeback verification path. The committed benchmark run was produced with the reproducible offline data index and transparently records written_to_graph: false. Live GSQL compilation and writeback still require a connected TigerGraph endpoint.
Agentic capabilities
Evidence value
The investigator chooses the missing evidence most likely to reduce uncertainty. In the interactive case, customer confirmation outranks deeper graph expansion.
Adaptive action
T100 begins with a request for confirmation at 71% confidence. A customer denial raises confidence to 95% and changes the proposal to BLOCK_CARD.
Policy gates
Rules R1–R10 map actions to automatic, L1, or L2 routes. A named analyst must approve customer-impacting actions.
Stopping policy
Investigation stops when evidence is sufficient, another query has low estimated value, or control must pass to a customer or analyst.
Case memory
Resolved cases retain evidence, actions, decisions, and outcomes so later investigations can retrieve related context without copying the verdict.
Auditable explanations
Every important claim maps to evidence and real identifiers. SAR drafts are generated from the structured record rather than invented prose.
What the graph revealed
The most useful motif was not “two rows have the same browser.” Shared browsers and device profiles can create false positives. GraphSentinel requires corroboration through amount, product, timing, identity, or email-domain context.
In HHG-019, three customer groups made closely matching near-$100 online purchases using the same detailed profile and email-domain combination in a short window. The system classifies this as an undocumented pattern rather than forcing it into a supplied typology. In HHG-017, broader profile overlap lacks equivalent corroboration, so the case stays uncertain.
The closed-case sample also challenged naive model-score dependence. The 900 cleared cases averaged a 0.881 upstream score, while 4,665 confirmed fraud cases averaged 0.475. New identity status appeared in 83.2% of cleared cases. Because this is a selected historical sample, those rates are diagnostic rather than calibrated probabilities—but they clearly argue against automatic blocking from a score or New flag alone.
What I learned
Graph technology is valuable when the question concerns relationships, provenance, and bounded paths. It does not remove the need for careful semantics. A graph can make a weak relationship look visually persuasive, so the evidence contract must state what an edge proves and what it does not.
Risk and confidence must be separate. An event can have severe potential harm while the explanation remains weak. In that situation, a reversible verification step is often safer than an irreversible block.
Policy belongs in code rather than a prompt. The reasoning layer can propose and explain, but authorization must be deterministic and auditable. Finally, stopping is a real agent capability: more traversal is not automatically better once the next query is unlikely to change the decision.
What I would improve with more time
- Compile and benchmark every GSQL query against a live Savanna workspace, then regenerate the 20 cases through graph retrieval and verified writeback.
- Measure probability calibration and false-positive cost once current-case outcome labels become available.
- Evaluate community detection and risk propagation against the bounded motifs instead of adding algorithms only for novelty.
- Add a durable hosted case store and a production identity provider for the analyst approval flow.
- Build a reproducible TigerGraph deployment manifest covering schema, loading jobs, installed queries, scoped tokens, and integration checks.