Python API reference

This is the reference for supported FraudTwin Python APIs. The task-oriented pages below group the most common workflows, while the exhaustive inventory lists every supported public export. Signatures and member lists are generated from the installed source; implementation helpers and private names are intentionally omitted.

API status at a glance

Area	Status	Use it for
Generation and configuration	Stable	Deterministic runs, YAML loading, validation, and run identity.
Data, ML, and graph	Stable	Point-in-time datasets, replay, evaluation, graph export, and PyG conversion.
Calibration and benchmarks	Experimental	Reference-data fitting and stress suites whose interfaces may evolve between releases.
PostgreSQL, Kafka, and Iceberg	Optional	Install the matching extra before importing an integration adapter.

Every detailed page starts with a symbol summary and then expands the public objects with signatures, typed parameters, return values, exceptions, and source links. A symbol marked experimental or optional is still supported, but should be pinned to a documentation version in production integrations.

Module index

The workflow pages below are the module-level entry points. The complete alphabetized class, exception, function, and constant indexes follow them.

Module area	Documentation page
fraudtwin.generation and fraudtwin.scale	Generation
fraudtwin.config	Configuration and Configuration parameter reference
fraudtwin.ml	Data and machine learning
fraudtwin.graph	Graph
Calibration, difficulty, camouflage, and campaigns	Advanced simulation
PostgreSQL, Kafka, lakehouse, replay, and storage	Integrations
Benchmarks, quality, and observability	Benchmarks, quality, and observability
All importable public modules	Module API reference

• Typed API cookbook
  • Generate and load a persisted run
  • Build a point-in-time dataset
  • Graph, drift, and Kafka workflows
  • Which API should I use?
• Generation
  • Large-scale iteration
• Configuration
  • Loading and hashing
  • Configuration model classes
• Data and machine learning
  • Point-in-time datasets
  • Backtesting and prediction evaluation
  • Drift analysis
• Graph
• Advanced simulation
  • Calibration
  • Counterfactuals, difficulty, and camouflage
  • Campaign dynamics and labels
• Integrations
  • PostgreSQL
  • Kafka and lakehouse
  • Replay and scale
• Benchmarks, quality, and observability
  • Benchmarks
  • Generator quality
  • Observability
• Module API reference

Import the stable high-level API from fraudtwin whenever possible. The module pages identify optional dependencies and the output objects returned by each operation.

Complete supported public API

The following indexes are generated from the package’s supported public API. Every listed symbol has a detail page with its signature, docstring, members, and source link.

Classes

fraudtwin.BehaviorModel	Port for a deterministic customer-behavior model.
fraudtwin.BronzeRecord	Canonical raw-record envelope used by both ingestion paths.
fraudtwin.CalibrationMetric	Deterministic plug-in that scores generated aggregate summaries.
fraudtwin.CalibrationModel	Deterministic plug-in that fits summaries from a reference dataset.
fraudtwin.CalibrationProfile	Immutable collection of summaries, distributions, and provenance.
fraudtwin.CalibrationProvenance	Inputs and versions that identify how a profile was fitted.
fraudtwin.CamouflagePlan	Resolved strengths for one generator family and scenario.
fraudtwin.ChaosEnvelope	Transport metadata wrapped around one immutable publication payload.
fraudtwin.ChunkCompletion	Fingerprint and location for one atomically completed chunk.
fraudtwin.ChunkDescriptor	Half-open logical ordinal range belonging to a stable shard.
fraudtwin.CounterfactualChangeSet	Machine-readable explanation of one accepted or rejected request.
fraudtwin.CounterfactualDataset	Original/modified sidecar records and oracle metadata.
fraudtwin.CounterfactualScope	Resolved controls for one objective request.
fraudtwin.DataFaultInjector	Port for deterministic observable-data mutations.
fraudtwin.DistanceFunction	Protocol implemented by pluggable counterfactual distances.
fraudtwin.DynamicCampaignDataset	Dynamic records and the complete post-evolution graph dataset.
fraudtwin.ExtensionMetadata	Identity recorded in manifests for one installed extension.
fraudtwin.ExtensionRegistry	Explicit, deterministic registry of extension implementations.
fraudtwin.FeatureDependency	Conditional relationship used to preserve feature dependencies.
fraudtwin.FidelityMetric	One weighted comparison between reference and generated aggregates.
fraudtwin.FidelityReport	Immutable per-summary and composite fidelity assessment.
fraudtwin.FittedDistribution	Finite quantiles and bounds fitted from one reference column.
fraudtwin.FraudScenario	Port for a deterministic fraud-scenario implementation.
fraudtwin.FsspecScaleStorage	S3/MinIO-compatible publisher backed by optional fsspec.
fraudtwin.GeneratedData	Generated FraudTwin data kept in memory.
fraudtwin.GeneratedRun	Metadata and paths for a generated run written to disk.
fraudtwin.GraphCampaign	Oracle descriptor for one deterministic scenario instance.
fraudtwin.GraphDataset	One immutable graph view and its structural descriptors.
fraudtwin.GraphEdge	Time-bounded relationship with provenance back to source events.
fraudtwin.GraphEvidence	Normalized lineage for a derived relationship.
fraudtwin.GraphHyperedge	Optional higher-order campaign incidence record.
fraudtwin.GraphHyperedgeMembership	Membership of an entity in a higher-order graph relationship.
fraudtwin.GraphNode	Versioned entity node in an observable or oracle graph view.
fraudtwin.IcebergLakehouse	Small PyIceberg writer with immutable append and snapshot metadata.
fraudtwin.KafkaChaosConfig	Immutable, seeded policy for logical Kafka delivery faults.
fraudtwin.KafkaChaosOutage	A source-time interval with a deterministic delivery behavior.
fraudtwin.KafkaChaosResult	Auditable output of one seeded logical-message chaos run.
fraudtwin.LakehouseEnvironment	Non-secret connection settings resolved from environment variables.
fraudtwin.LakehouseMaterializationResult	Immutable metadata produced by a batch or streaming materialization.
fraudtwin.LocalScaleStorage	Filesystem implementation used by default and in CI.
fraudtwin.OutputSink	Port for a chunk-aware output adapter.
fraudtwin.PartitionCompletion	Fingerprint and counts for one atomically completed partition.
fraudtwin.PaymentRail	Port for a payment rail that preserves FraudTwin lifecycle semantics.
fraudtwin.PostgresPersistenceResult	Non-secret metadata recorded in a generated run manifest.
fraudtwin.PublicBenchmarkPack	Immutable, distributable M21 benchmark definition.
fraudtwin.QualityAdapterMetadata	Identity and capabilities advertised by an external generator.
fraudtwin.QualityAdapterRequest	Read-only public workload delivered to an external adapter.
fraudtwin.QualityArtifactBundle	Normalized external output consumed by the quality scorer.
fraudtwin.QualityBenchmarkProfile	Immutable public workload and protocol selection.
fraudtwin.QualityBenchmarkRequest	Programmatic equivalent of the quality-benchmark CLI command.
fraudtwin.QualityBenchmarkResult	Immutable result and artifact location for a quality benchmark run.
fraudtwin.QualityCandidateReport	Normalized quality dimensions for one generator candidate.
fraudtwin.QualityCapability	Declared dimensions supplied by a native or external candidate.
fraudtwin.QualityGeneratorAdapter	Protocol implemented by an external generator benchmark adapter.
fraudtwin.QualityMetric	One independently interpretable quality result.
fraudtwin.ReconciliationResult	Cross-partition invariant results recorded in manifests/checkpoints.
fraudtwin.ReferenceDataset	Validated reference data held only for the duration of fitting/scoring.
fraudtwin.ResolvedCalibration	Effective calibration context applied to a simulation configuration.
fraudtwin.ResolvedCamouflage	Complete, deterministic and hashable M13 configuration.
fraudtwin.ResolvedCounterfactual	Complete immutable M14 configuration resolution.
fraudtwin.ResolvedDifficulty	Complete, hashable M12 difficulty configuration.
fraudtwin.ScaleCheckpoint	Serializable checkpoint manifest for deterministic resume.
fraudtwin.ScalePlan	Resolved, immutable execution parameters for one scale run.
fraudtwin.ScenarioDifficultyPlan	Resolved transformations for one fraud or graph scenario.
fraudtwin.ShardDescriptor	Stable shard identity; it is independent of the worker executing it.
fraudtwin.SourceTrajectory	One legitimate source payment and its point-in-time snapshot.
fraudtwin.StatisticalSummary	Immutable aggregate statistic captured in a calibration profile.

Exceptions

fraudtwin.LakehouseConfigurationError	Raised for missing or unsafe lakehouse configuration.
fraudtwin.LakehouseDependencyError	Raised when an Iceberg/Kafka integration extra is not installed.

Functions

fraudtwin.aggregate_fingerprint	Hash rows incrementally without retaining the complete input.
fraudtwin.apply_calibration_profile	Return an immutable generation context for a fitted profile.
fraudtwin.apply_camouflage	Return a stable per-scenario plan; no data or RNG is mutated.
fraudtwin.apply_difficulty	Apply resolved controls to one scenario without changing its objective.
fraudtwin.apply_label_observation	Apply a deterministic observation policy without mutating source records.
fraudtwin.build_bronze_records	Build a deterministic raw envelope from a complete generated run.
fraudtwin.build_graph	Build a deterministic temporal graph without generating source data.
fraudtwin.checkpoint_fingerprint	Return a stable fingerprint excluding the wall-clock creation time.
fraudtwin.chunk_payment_ranges	Yield stable shard-local payment chunks without materializing IDs.
fraudtwin.compute_fidelity_report	Compare generated aggregate values with a fitted profile.
fraudtwin.consume_kafka_once	Consume a bounded Kafka batch into immutable Bronze and Silver tables.
fraudtwin.create_scale_stream_rng	Create a deterministic hierarchical stream for one scale task.
fraudtwin.database_status	Return applied migration versions without changing the database.
fraudtwin.deduplicate_records	Apply a stable Silver decision while retaining deterministic winners.
fraudtwin.discover_extensions	Load installed entry points in stable name order.
fraudtwin.ensure_database_ready	Fail before file emission when the operational schema is unavailable.
fraudtwin.evolve_campaigns	Evolve all configured M11 campaigns in stable order.
fraudtwin.fit_calibration_profile	Fit the deterministic built-in aggregate profile.
fraudtwin.generate	Generate a deterministic FraudTwin run.
fraudtwin.generate_counterfactuals	Generate deterministic sidecar counterfactuals from a pristine stream.
fraudtwin.generate_scale	Run an explicitly requested scale job using the scale manifest path.
fraudtwin.iter_chunks	Yield deterministic half-open chunk descriptors.
fraudtwin.iter_partition_query	Execute an out-of-core DuckDB query over partitioned Parquet.
fraudtwin.iter_partition_rows	Read scale chunks one file at a time, keeping reader memory bounded.
fraudtwin.iter_payment_ranges	Yield deterministic contiguous payment ordinal ranges per shard.
fraudtwin.iter_scale_records	Stream canonical entities, profiles, payments, events, and ledger rows.
fraudtwin.iter_scale_run	Yield scale records from a producer or an existing partitioned run.
fraudtwin.list_public_packs	Return all bundled public packs in stable identity order.
fraudtwin.load_calibration_profile	Load and validate a YAML calibration profile.
fraudtwin.load_checkpoint	Load and validate a checkpoint manifest.
fraudtwin.load_public_pack	Resolve an exact or unambiguous major/minor public-pack reference.
fraudtwin.load_quality_profile	Load one bundled immutable M22 profile or a YAML profile path.
fraudtwin.load_reference_data	Load and strictly validate one canonical Parquet reference table.
fraudtwin.materialize_dataset	Materialize already-loaded domain objects without regenerating them.
fraudtwin.materialize_run	Backfill one generated run and optionally commit it to Iceberg.
fraudtwin.migrate_database	Apply the packaged, ordered PostgreSQL migrations and return the version.
fraudtwin.partition_id	Return the canonical shard ID for a logical record.
fraudtwin.partition_index	Map a logical ID to a stable shard without using Python hash randomization.
fraudtwin.persist_run	Persist one generated run atomically after migrations have been applied.
fraudtwin.persist_scale_records	Persist a partition-record stream without whole-run materialization.
fraudtwin.reconcile_logical_ids	Detect duplicate/lost IDs and return a serializable reconciliation result.
fraudtwin.reconstruct_label_history	Return the immutable versions in validated chronological order.
fraudtwin.register_calibration_metric	Register a deterministic fidelity metric under a unique name.
fraudtwin.register_calibration_model	Register a deterministic calibration model under a unique name.
fraudtwin.register_distance_function	Register a deterministic named distance function.
fraudtwin.register_intensity_model	Register a campaign intensity model by stable name.
fraudtwin.register_transition_model	Register a campaign phase-transition model by stable name.
fraudtwin.report_run	Create an invariant report for one existing native generated run.
fraudtwin.require_scale_plan	Resolve an enabled scale plan and narrow away the optional result.
fraudtwin.resolve_calibration	Resolve an optional profile against a simulation configuration.
fraudtwin.resolve_calibration_configuration	Explicitly named public alias for resolving calibration configuration.
fraudtwin.resolve_camouflage	Resolve global, family, and leaf M13 controls without consuming RNG.
fraudtwin.resolve_campaign_dynamics	Validate and resolve registered models without consuming randomness.
fraudtwin.resolve_counterfactual	Resolve M14 precedence without consuming a random stream.
fraudtwin.resolve_difficulty	Resolve a level and its optional per-dimension replacements.
fraudtwin.resolve_label_observation	Return the validated M17 policy from either a run or policy config.
fraudtwin.resolve_scale_plan	Resolve the opt-in scale configuration, returning None when disabled.
fraudtwin.resume_generation	Resume a scale run from a validated checkpoint manifest.
fraudtwin.run_public_benchmark	Run one immutable bundled M21 pack and verify its frozen outputs.
fraudtwin.run_quality_benchmark	Run the native or external M22 quality protocol.
fraudtwin.run_scale_benchmark	Run one explicitly requested scale job and publish machine evidence.
fraudtwin.select_source_trajectories	Select deterministic legitimate-only source trajectories.
fraudtwin.silver_rows	Normalize deduplicated Bronze records without rewriting raw payloads.
fraudtwin.simulate_delivery	Apply seeded logical-message faults at a producer or consumer boundary.
fraudtwin.storage_for	Resolve a configured storage backend without importing optional packages.
fraudtwin.to_pyg	Convert a graph to torch_geometric.data.HeteroData when installed.
fraudtwin.validate_calibration_output	Reject output that attempts to carry reference rows or invalid metrics.
fraudtwin.validate_campaign_dynamics	Validate dynamic IDs, lifecycle records, graph membership, and ledger closure.
fraudtwin.validate_graph	Validate IDs, temporal closure, and edge references for one graph view.
fraudtwin.validate_graph_scenarios	Validate campaign closure and higher-order incidence records.
fraudtwin.validate_label_observation	Validate references, ordering, and immutable truth invariants.
fraudtwin.verify_materialization	Validate a materialization manifest without contacting Iceberg.
fraudtwin.verify_public_benchmark	Verify an existing public benchmark artifact without regenerating it.
fraudtwin.visible_label_at	Resolve the latest label version available at a prediction timestamp.
fraudtwin.write_calibration_profile	Write one immutable inspectable YAML profile and its JSON manifest.
fraudtwin.write_checkpoint	Atomically publish a checkpoint manifest.
fraudtwin.write_graph	Write one append-only graph artifact containing the requested views.
fraudtwin.write_scale_benchmark_manifest	Write non-deterministic machine evidence separately from run identity.

Constants and protocols

Name	Reference
Extension	fraudtwin.Extension
__version__	fraudtwin.__version__