FraudTwin documentation#
Level: All levels
You will: find the right learning route, canonical guide, and reference
surface for your work.
Before you start: none.
Services: None.
FraudTwin is a deterministic synthetic payment world for fraud detection, graph analysis, data engineering, and machine-learning experiments. The manual is organized by reader intent: Tutorials, How-to guides, Explanation, and Reference. Use the onboarding page when you want help choosing where to begin.
Installation#
Installation and support - install the base package, choose extras, and verify an environment.
Quickstart - install FraudTwin and generate your first run.
Choose your path - select the canonical documentation section for your goal.
Python package and CLI - choose between the Python API and command-line workflows.
Build the documentation with
poetry run sphinx-build -E -W --keep-going -b html docs docs/_build/html.
Tutorials#
The published sidebar groups these notebooks into eight tutorial categories: Visualization and exploration, Getting started, Core workflows, Production ML and reliability, Graph analytics, Streaming and Kafka reliability, Operations and incident response, and Advanced experiments.
Start with a category page instead of a flat notebook list. Each page explains the expected input size, optional extras, service requirements, generated artifacts, and the next recommended step.
Tutorial filenames are descriptive. Historical numeric routes remain redirects for readers with old bookmarks; use the category pages as the recommended path. Follow the category order for the recommended learning path; descriptive filenames and rendered titles explain what each notebook teaches.
Visualization and exploration - temporal, spatial, distribution, scenario, and feature analysis.
Getting started - installation through delayed labels.
Core workflows - point-in-time datasets and benchmarks.
Production ML and reliability - model lifecycle and drift.
Graph analytics - Neo4j and PyTorch Geometric.
Streaming and Kafka reliability - delivery faults and Avro evolution.
Operations and incident response - repair, scale, persistence, and observability.
Advanced experiments - four combined workflows for calibration/interventions, graph investigations, ML shift/backtesting, and scale/reproducibility.
How-to guides#
Build and evaluate - configure runs, build datasets, evaluate models, and measure drift.
Integrate and serve - connect optional services and validate serving or streaming paths.
Operate and repair - handle quality faults, graphs, reconciliation, and bounded scale.
Extend and release - publish extensions and prepare release or benchmark evidence.
Explanation#
Core concepts - understand determinism, lifecycles, labels, graph provenance, and quality faults.
Determinism and reproducibility - understand seeds, streams, and fingerprints.
Architecture and trust boundaries - understand source truth and integration boundaries.
Reference#
Python API reference - supported objects, workflow APIs, and generated module indexes.
Configuration parameter reference - generated tables for configuration sections.
CLI reference - command groups and workflow entry points.
Data contracts - generated-run artifacts, grains, and oracle boundaries.
Verified capabilities - runnable commands and evidence behind supported workflows.
Resources#
Troubleshooting - resolve installation and optional dependency issues.
Migration guides - check compatibility boundaries when moving between releases.
Compatibility and support policy - understand stable, optional, and experimental surfaces.
Development guide - run checks and contribute safely.
References and related work - standards, papers, and projects that informed the design.
Documentation style#
Every maintained guide states its level, expected outcome, prerequisites, and service requirements near the beginning. Commands are written for copy/paste, with the expected artifact or next decision explained immediately afterward. Feature names are used in public prose; compatibility identifiers remain only where a file format, release history, or existing command requires them.
Package Reference#
Python API reference - workflow guides plus generated indexes for every supported
fraudtwinexport and importable module.Configuration parameter reference - generated tables for every major Pydantic configuration section.
CLI reference - command groups, validation commands, and workflow entry points.
Data contracts - generated-run artifacts, grains, and oracle boundaries.
Source code on GitHub - implementation, tests, and issue tracker.
Cheatsheets#
Configuration cheatsheet - the main configuration sections at a glance.
Workflow cheatsheet - the recommended generation and evaluation sequence.
Graph and benchmark cheatsheet - choose the fixture that matches your experiment.
Resources#
Development guide - run checks, target tests, and contribute safely.
Glossary - definitions for observable views, label maturity, campaigns, fingerprints, and checkpoints.
Release notes - follow release history and notable changes.
Contributor entry point - the short repository-level workflow.
External Resources#
FraudTwin on GitHub - source code, tests, issues, and project history.
References and related work - standards, handbooks, papers, and projects that informed the design.
A useful mental model#
Every run starts with entities and customer behavior, produces legitimate payments and lifecycle events, and can then layer on fraud, workflow, quality faults, graph structure, or benchmark stress. The simulator keeps those layers deterministic and connected, so a generated case can be traced back to the payment, actors, timestamps, and source records that explain it.
Next#
Choose a route from Choose your path, starting with the Quickstart if you are new to FraudTwin.