Dolos Hybrid
One transaction classifier: a frozen, directed GraphSAGE encoder supplies account-neighborhood embeddings to a single XGBoost head. The classifier also receives direct transaction features. This is the checkpoint bundled with the Dolos demo, created by Abhi Agasanakoppa and Timothy Vu of Thomas Wootton High School, Rockville, MD, USA.
Source and training notebook · Demo video
Model and intended use
This checkpoint is for synthetic-data demonstrations, reproducible research, and exploring transaction explanations. All 2,880 training-source rows were generated by Dolos. No private bank statements or IBM AMLworld records trained this checkpoint.
The encoder has two directed mean-aggregation layers with historical fanouts of 4 and 2. It produces 128 joined sender/receiver features. The final classifier receives those features and 8 transaction features: 136 inputs total. XGBoost uses 150 trees, maximum depth 5, learning rate 0.08, and random seed 7.
The serving implementation evaluates the exported trained encoder tensors with NumPy and the final head with native XGBoost. It needs neither PyTorch nor a document-extraction provider at inference time. Both components are required for the one final decision.
Run locally
From a download or clone of this model repository:
uv sync
uv run python predict.py --input examples/synthetic-transfers.csv --explain
The included example should produce 432 scored transactions and 144 positive decisions. Output is written to predictions.json. The entire history is provided for graph context; only eligible transactions at or after the checkpoint's model-selection cutoff are scored.
On the Dolos project's Nix-enabled development machine, enter nix develop before running these commands. The parent flake supplies Node, pnpm, and uv, and the macOS OpenMP library used by XGBoost. A separate macOS installation needs an OpenMP runtime available to XGBoost.
Python usage:
from dolos_hybrid import DolosHybrid
model = DolosHybrid(".")
result = model.predict_csv("examples/synthetic-transfers.csv", explain=True)
for item in result["scores"][:3]:
print(item["transaction_id"], item["score"], item["component_contributions"])
Load weights from Hugging Face
Install the local runtime and optional Hub dependency with uv sync --extra hub, then:
from dolos_hybrid import DolosHybrid
model = DolosHybrid.from_pretrained(
"YOUR_USERNAME/dolos-hybrid",
revision="YOUR_MODEL_COMMIT_SHA",
)
result = model.predict_csv("examples/synthetic-transfers.csv", explain=True)
Use a model-repository commit SHA to pin the encoder, head, and manifests together. The loader downloads data files; the inference implementation comes from this repository's local Python package. This custom graph pipeline runs locally or in your own backend; uploading weights does not create a hosted prediction endpoint.
For the existing Dolos API, download the snapshot and set DOLOS_MODEL_DIR to its directory. The expected files are at the root of this repository.
Inputs and temporal context
Supply complete canonical transaction CSV columns:
timestamp,from_bank,from_account,to_bank,to_account,amount_received,receiving_currency,amount_paid,payment_currency,payment_format
The original IBM-style header is also supported by the parser. Bank/account identifiers stay strings, preserving leading zeroes. Amounts must be finite, nonnegative decimal values. Naive timestamps are interpreted as UTC. Rows are sorted chronologically while preserving their source-row identities. The optional laundering-label column in the sample is not an inference feature.
Hourly context contains only transfers strictly before the target hour. The model-selection cutoff is 2025-01-14T12:00:00Z (the manifest stores epoch microseconds). Keep earlier history when scoring later transfers. Partial document relationships without all canonical fields need a separate review method; this model package does not extract PDF statements.
read_csv(..., prefix="simulation") reproduces demo row IDs. Use distinct prefixes if combining several CSV files into one history. predict(rows) accepts normalized rows from read_csv; IDs must be unique.
Scores and explanations
Each score is an uncalibrated raw decision margin. Above 0 is a positive classifier decision. It is not a confidence percentage.
With explain=True, every scored transfer receives grouped TreeSHAP credits for the graph features and transaction fields. Those credits plus the base margin sum to the final decision margin, subject to floating-point rounding. The ten highest-scoring transfers additionally receive feature contributions, actual paths through the first three trees, and the sampled historical context.
Credits describe the final classifier's inputs. A sampled neighbor is context, not proof that the neighbor caused a decision or participated in a crime.
Training and evaluation
| Item | Bundled checkpoint |
|---|---|
| Source rows | 2,880 synthetic transfers |
| Training rows | 2,016, chronological |
| Validation rows | 432, chronological |
| Held-out rows | 432, chronological |
| Held-out positive labels | 144 |
| Held-out positive decisions | 144 |
| Held-out average precision | 1.0 |
These metrics are recorded in hybrid_manifest.json. Training and evaluation use the same synthetic generator, so they do not establish real-world performance or generalization. This is the bundled website checkpoint; later notebook experiment runs may have different artifact IDs and evaluation results.
The frozen encoder is selected using chronological validation. The final XGBoost head is fitted on pre-training-cutoff rows with fixed hyperparameters. Future transfers do not enter a target's historical graph context.
Limitations
- Vocabulary coverage is narrow: the bundled source uses USD and WIRE. Unknown categories use the frozen unknown-category encoding.
- Scores depend on available history, the hourly cutoff, and bounded graph sampling.
- Synthetic examples are not evidence of operational fraud-detection accuracy, calibrated risk, or criminal responsibility.
- A positive decision is a review candidate. An unflagged transfer is not a guarantee of safety.
- Human review and representative external evaluation are required before considering operational use.
Files and provenance
graphsage.npz: trained encoder tensors used by the NumPy runtime.hybrid_xgboost.json: the one final classifier.manifest.json: original feature vocabulary and encoder-training metadata.hybrid_manifest.json: final pipeline metadata, evaluation, and encoder/head hashes.dolos_hybrid/: standalone inference and canonical validation code copied from production.examples/synthetic-transfers.csv: the exact generated source used by this checkpoint.provenance.json: source revision and checksums for exported artifacts and runtime files.
The base manifest retains historical experiment metadata for provenance; this repository exports only the components required for the final hybrid. Checkpoint loading verifies that the encoder and head hashes and run IDs match.
GraphSAGE follows Hamilton et al., Inductive Representation Learning on Large Graphs; the directed implementation is in Dolos. The tree classifier uses XGBoost. Runtime dependencies retain their own licenses.