Savanna Fraud Investigator: An Agentic Fraud Investigation System on TigerGraph

Built for the TigerGraph Agentic Fraud Investigation HHGOA hackathon

What we built

Fraud teams don't lack data — they lack time. An analyst investigating a single flagged transaction has to manually pull transaction history, trace connected cards and devices, check prior case outcomes, weigh a fraud policy, and decide what to do, often while the window to actually stop the money closes. We built Savanna Fraud Investigator to compress that loop into an agent that investigates, decides, and explains itself — without ever letting a language model be the one making the actual call on blocking a card or filing a report.

The system ships two investigation paths on top of the same graph:

• A deterministic pipeline (src/generate_cases.py) that runs the identical evidence-gathering steps and a fixed policy engine over every case. This is what produced our 20 required answer files — reliable and reproducible by design.
• A genuinely agentic investigator (src/mcp_agent.py) that connects to a live TigerGraph MCP server and lets Gemini, through a LangGraph ReAct loop, decide for itself which graph queries to run and in what order. This path found things the fixed pipeline structurally can't — for example, billing-region velocity that looks like impossible travel — because it isn't locked into one investigation script.

A local web dashboard sits on top of both: a case docket showing evidence, before/after next-best-action, SAR status, and case memory for all 20 cases, plus a button to run the live agent against any case and stream its real output.

Architecture

At the center is TigerGraph Savanna holding the IEEE-CIS-derived transaction graph — transactions, cards, devices, customers, and prior closed cases as first-class vertices and edges. Everything else is built to never replace graph analysis with model guesswork:

• GSQL layer (tigergraph/): schema, loading jobs, and four custom installed queries — card_window (transactions near a flagged one on the same card), transaction_device (device fingerprint lookup), device_neighbors (other cards sharing that device), and hhg_write_case (writes the finished investigation back as an InvestigationCase vertex — our case memory).
• Evidence layer (src/evidence.py, src/tg_client.py): a thin pyTigerGraph client that calls those four queries and normalizes results into typed evidence the rest of the system can reason over.
• Policy engine (src/policy.py): a fixed, non-negotiable R1–R10 rule set that owns verdicts, next-best actions, approval routes, and SAR eligibility. Neither LLM path can override it — an agent can gather evidence and explain a recommendation, but the actual decision of "block this card" or "file this report" comes from code, not a prompt.
• Synthesis layer (src/synthesis.py): grounds Gemini's explanations strictly in retrieved evidence, with a deterministic fallback if no API key is present — the pipeline always produces policy-compliant, non-fabricated output whether or not an LLM is in the loop.
• Contracts (src/contracts.py): every one of the 20 generated cases is validated against the hackathon's exact JSON schema before it's written to disk.

How we used TigerGraph

TigerGraph isn't a data store we occasionally query — it's the arbiter. Our policy explicitly treats the transaction's incoming risk score as an investigation trigger, not a verdict: probability of fraud only moves meaningfully once graph evidence (a burst of small authorizations on the same card, a device shared across multiple cards) actually corroborates it. A high risk score with no graph corroboration and no customer complaint gets closed as legitimate rather than escalated — we didn't want a system that just rubber-stamps the input model's score with extra words.

The hhg_write_case query closes the loop by writing every finished investigation back into the graph as an InvestigationCase vertex, so future investigations — whether run through the deterministic pipeline or the agentic path — can retrieve prior outcomes for the same entities as case memory rather than starting cold.

Agentic design

The deterministic pipeline gives us reliability for the 20 required answer files. The agentic investigator is where the actual agentic capability lives: it's handed the TigerGraph MCP tool surface and decides for itself, case by case, what evidence it needs and in what order, rather than following one fixed script. Its tool access is deliberately restricted to read-mostly TigerGraph MCP tools plus the single write path — it can gather evidence and record a finished case, but it can't touch schema or delete data. The dashboard's "Run Live Agentic Investigation" button calls this path directly against mcp_agent.py and streams its real output, so the demo isn't simulated.

What we learned

Most of the real engineering work wasn't the graph queries or the policy rules — it was making sure "live TigerGraph evidence" actually stayed live all the way through a 20-case batch run, not just in a one-off connection test. We hit a genuinely subtle bug: our connection helper cached its result for the lifetime of the process, so if credentials weren't fully loaded at the very first call, every subsequent case in the batch silently fell back to document-only evidence with no error raised at all. It's a good reminder that "it worked when I tested it" and "it works across a full batch run" are different claims, and that a policy engine's decisions are only as trustworthy as the evidence pipeline feeding it — a silent fallback is more dangerous than a loud crash.

What we'd improve with more time

• Add explicit health checks and fail-loud behavior around the graph connection, rather than allowing any case to silently fall back to document-only evidence
• Expand the agentic path's pattern coverage beyond the five documented fraud typologies, using the freedom the ReAct loop already has
• Add persistent approve/reject workflow state for analysts reviewing agent recommendations, rather than a stateless demo
• Stream the agent's reasoning to the dashboard live, rather than only showing output once a run completes

Built for the TigerGraph Agentic Fraud Investigation HHGOA hackathon. Code: https://github.com/SHKsushant/savanna-fraud-investigator