Building intelligent systems for finance, analytics, and real-world decision making. Trying to build useful things that people actually need and hopefully keep using.

AML alert queues pile up because every flag demands a manual multi-system investigation.

Rule engines surface velocity breaches, round-trip patterns, and watchlist hits. ML models score transaction risk. Each flag lands in an analyst queue — requiring lookups across transaction history, counterparty registers, velocity metrics, and global watchlists. A 2,000-alert queue at 15 minutes per case is 500 hours of backlog before the week starts.

The challenge: automate multi-hop investigations without losing the audit trail — and build a hard escape hatch for cases the agent shouldn't guess on.

A LangGraph state machine with 6 deterministic tools — LLM reasons, tools execute.

• Six deterministic tools: txn_history_query and counterparty_risk_lookup (Postgres), round_trip_detector (recursive CTE following transaction hops up to 168h), velocity_check (Redis ZRANGEBYSCORE pipeline across 1h/6h/24h windows), watchlist_lookup (OFAC-style CSV loaded at module import), and kafka_lag_check (false-positive filter — rules out pipeline delay as the cause of apparent bursts).
• The LangGraph state machine drives the loop: IDLE → INVESTIGATING → TOOL_CALLING → EVALUATING → RESOLVED or ESCALATED. Each node is a pure function, each transition is an explicit conditional edge — testable in isolation without a live LLM.
• Hard limits enforced by the state machine before any LLM call: max 4 hops, confidence ≥ 0.70, 30s wall-clock timeout, $0.05 cost cap. Guard order in node_evaluating: empty evidence → max hops → timeout → cost cap → LLM call → post-call cost re-check → confidence gate. The LLM cannot route around any of them.
• Every tool call is written to tool_execution_log in a finally block — covering success and failure. Evidence chain reads exclusively from this table, not from state.evidence_chain which the LLM populates. Built in 3 milestones: M1 (state machine + Docker stack, mock tools), M2 (6 real tools + gpt-4o-mini), M3 (FastAPI, Kafka consumer, Redis mutex, Streamlit dashboard, Prometheus).

Why these tradeoffs — each came from a real failure during the build.

• Hard limits in node_evaluating, not the routing edge. Edge functions return a route but cannot write state. Putting the limit check in the edge leaves escalation_reason as None — the compliance report INSERT has a required-field constraint that fires. One enforcement site only: the node writes the reason, the edge only reads it.
• Evidence chain from tool_execution_log, not state.evidence_chain. The LLM populates state.evidence_chain during inference. If it hallucinates a tool call, the compliance report contains fabricated evidence. tool_execution_log is written in the finally block of dispatch_tool before the result reaches the LLM — it is ground-truth regardless of LLM behavior.
• tool_input_json: str not dict[str, Any]. OpenAI structured output rejects open-ended dict types. The LLM serializes tool input as a JSON string; the dispatcher deserializes with json.loads. Strict schema enforcement is a feature — it prevents the LLM from inventing fields that don't map to any real tool parameter.
• LLM fallback is escalation, never a default tool call. The original fallback on LLM parse failure called velocity_check with account_id = payload.txn_id — a wrong type that returns 0 transactions, making the investigation look clean. In AML, a false-clean verdict is categorically worse than a false escalation. Safe failure = immediate ESCALATED.

10 runs · 3 scenarios · gpt-4o-mini · real OpenAI API — 2026-04-18, WSL2 (10GB RAM, 8 cores).

What actually broke — and what I learned from fixing it.

• Float precision kills compliance thresholds. A confidence of 0.70 in IEEE 754 can be stored as 0.6999999999999999 — triggering a false low_confidence escalation. Fixed with round(confidence, 4) before every threshold comparison. Never compare raw floats to exact decimal values in compliance logic.
• Seeded data resolves in 1 hop every time. The 3 demo scenarios aren't adversarial enough to force multi-hop LLM reasoning — the agent calls one tool, finds sufficient evidence, resolves. Avg 1.0 hops is correct but not a meaningful measure of multi-hop capability. Real demonstration of the 4-hop ceiling needs fresh, live transaction payloads via the API.
• Module-level DB pool init poisons the test session. Pool init at import time runs during pytest collection — if the DB isn't running, the pool is set to None permanently for that session. Switched to lazy init so the pool is only attempted when a tool is actually invoked. Applies to any module-level singleton that requires infrastructure.
• The first bottleneck at 10x load isn't Postgres — it's the OpenAI rate limit. gpt-4o-mini has a requests-per-minute cap; each investigation makes 2–4 LLM calls. Fix: async LangGraph nodes with a token-bucket rate limiter and Kafka consumer back-pressure rather than queuing investigations in memory.