fraudtwin.calibration#

Reference-data calibration and fidelity reports.

Status: Experimental

Classes#

`fraudtwin.calibration.CalibrationMetric`	Deterministic plug-in that scores generated aggregate summaries.
`fraudtwin.calibration.CalibrationModel`	Deterministic plug-in that fits summaries from a reference dataset.
`fraudtwin.calibration.CalibrationProfile`	Immutable collection of summaries, distributions, and provenance.
`fraudtwin.calibration.CalibrationProvenance`	Inputs and versions that identify how a profile was fitted.
`fraudtwin.calibration.FeatureDependency`	Conditional relationship used to preserve feature dependencies.
`fraudtwin.calibration.FidelityMetric`	One weighted comparison between reference and generated aggregates.
`fraudtwin.calibration.FidelityReport`	Immutable per-summary and composite fidelity assessment.
`fraudtwin.calibration.FittedDistribution`	Finite quantiles and bounds fitted from one reference column.
`fraudtwin.calibration.ReferenceDataset`	Validated reference data held only for the duration of fitting/scoring.
`fraudtwin.calibration.ResolvedCalibration`	Effective calibration context applied to a simulation configuration.
`fraudtwin.calibration.StatisticalSummary`	Immutable aggregate statistic captured in a calibration profile.

Functions#

`fraudtwin.calibration.apply_calibration_profile`	Return an immutable generation context for a fitted profile.
`fraudtwin.calibration.compute_fidelity_report`	Compare generated aggregate values with a fitted profile.
`fraudtwin.calibration.fit_calibration_profile`	Fit the deterministic built-in aggregate profile.
`fraudtwin.calibration.load_calibration_profile`	Load and validate a YAML calibration profile.
`fraudtwin.calibration.load_reference_data`	Load and strictly validate one canonical Parquet reference table.
`fraudtwin.calibration.register_calibration_metric`	Register a deterministic fidelity metric under a unique name.
`fraudtwin.calibration.register_calibration_model`	Register a deterministic calibration model under a unique name.
`fraudtwin.calibration.resolve_calibration`	Resolve an optional profile against a simulation configuration.
`fraudtwin.calibration.resolve_calibration_configuration`	Explicitly named public alias for resolving calibration configuration.
`fraudtwin.calibration.validate_calibration_output`	Reject output that attempts to carry reference rows or invalid metrics.
`fraudtwin.calibration.write_calibration_profile`	Write one immutable inspectable YAML profile and its JSON manifest.

Constants and protocols#

Name	Reference
`CALIBRATED_AMOUNT_STREAM_ID`	`fraudtwin.calibration.CALIBRATED_AMOUNT_STREAM_ID`
`CALIBRATED_BALANCE_STREAM_ID`	`fraudtwin.calibration.CALIBRATED_BALANCE_STREAM_ID`
`CALIBRATED_MERCHANT_STREAM_ID`	`fraudtwin.calibration.CALIBRATED_MERCHANT_STREAM_ID`
`CALIBRATED_STREAM_ID`	`fraudtwin.calibration.CALIBRATED_STREAM_ID`
`CALIBRATED_TIMING_STREAM_ID`	`fraudtwin.calibration.CALIBRATED_TIMING_STREAM_ID`
`CALIBRATION_STREAM_ID`	`fraudtwin.calibration.CALIBRATION_STREAM_ID`

Detailed API#

Deterministic aggregate reference calibration for FraudTwin.

Calibration deliberately produces parameter summaries rather than examples or rows. The causal payment, ledger, fraud, and graph generators remain the authoritative producers of output records.

class fraudtwin.calibration.CalibrationMetric(*args, **kwargs)[source][source]

Bases: Protocol

Deterministic plug-in that scores generated aggregate summaries.

class fraudtwin.calibration.CalibrationModel(*args, **kwargs)[source][source]

Bases: Protocol

Deterministic plug-in that fits summaries from a reference dataset.

class fraudtwin.calibration.CalibrationProfile(**data)[source][source]

Bases: BaseModel

Immutable collection of summaries, distributions, and provenance.

Parameters:

profile_id (str)
profile_version (str)
provenance (CalibrationProvenance)
summaries (tuple[StatisticalSummary, ...])
distributions (tuple[FittedDistribution, ...])
dependencies (tuple[FeatureDependency, ...])

model_config: ClassVar[ConfigDict] = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.calibration.CalibrationProvenance(**data)[source][source]

Bases: BaseModel

Inputs and versions that identify how a profile was fitted.

Parameters:

calibration_version (str)
source_fingerprint (str)
source_schema_fingerprint (str)
row_count (Annotated[int, Ge(ge=1)])
seed (Annotated[int, Ge(ge=0)])
configuration_hash (str)
stream_ids (tuple[str, ...])
model_versions (dict[str, str])

model_config: ClassVar[ConfigDict] = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.calibration.FeatureDependency(**data)[source][source]

Bases: BaseModel

Conditional relationship used to preserve feature dependencies.

Parameters:

source (str)
target (str)
version (str)
conditional_weights (dict[str, float])

model_config: ClassVar[ConfigDict] = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.calibration.FidelityMetric(**data)[source][source]

Bases: BaseModel

One weighted comparison between reference and generated aggregates.

Parameters:

name (str)
version (str)
status (str)
score (Annotated[float | None, Ge(ge=0), Le(le=1)])
weight (Annotated[float, Gt(gt=0)])
reference_summary_fingerprint (str | None)
generated_summary_fingerprint (str | None)
details (dict[str, str | int | float | bool | None])

model_config: ClassVar[ConfigDict] = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.calibration.FidelityReport(**data)[source][source]

Bases: BaseModel

Immutable per-summary and composite fidelity assessment.

Parameters:

report_version (str)
profile_id (str | None)
metrics (tuple[FidelityMetric, ...])
composite_score (Annotated[float | None, Ge(ge=0), Le(le=1)])
report_fingerprint (str)

model_config: ClassVar[ConfigDict] = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.calibration.FittedDistribution(**data)[source][source]

Bases: BaseModel

Finite quantiles and bounds fitted from one reference column.

Parameters:

name (str)
version (str)
quantiles (tuple[float, ...])
probabilities (tuple[float, ...])
minimum (float | None)
maximum (float | None)

model_config: ClassVar[ConfigDict] = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.calibration.ReferenceDataset(frame, *, source_fingerprint, schema_fingerprint)[source][source]

Bases: object

Validated reference data held only for the duration of fitting/scoring.

Parameters:

frame (DataFrame)
source_fingerprint (str)
schema_fingerprint (str)

class fraudtwin.calibration.ResolvedCalibration(**data)[source][source]

Bases: BaseModel

Effective calibration context applied to a simulation configuration.

Parameters:

enabled (bool)
profile_id (str | None)
profile (CalibrationProfile | None)
effective_configuration_hash (str)
stream_ids (tuple[str, ...])

model_config: ClassVar[ConfigDict] = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fraudtwin.calibration.StatisticalSummary(**data)[source][source]

Bases: BaseModel

Immutable aggregate statistic captured in a calibration profile.

Parameters:

name (str)
version (str)
available (bool)
fields (tuple[str, ...])
parameters (dict[str, Any])
fingerprint (str)

model_config: ClassVar[ConfigDict] = {'allow_inf_nan': False, 'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

fraudtwin.calibration.apply_calibration_profile(profile, *, seed=0, config=None)[source][source]

Return an immutable generation context for a fitted profile.

Return type:

ResolvedCalibration

Parameters:

profile (CalibrationProfile)
seed (int)
config (Any | None)

fraudtwin.calibration.compute_fidelity_report(profile, generated, *, weights=None, minimum_scores=None)[source][source]

Compare generated aggregate values with a fitted profile.

Parameters:

profile (CalibrationProfile) – Reference summaries to score.
generated (Mapping[str, object]) – Mapping of summary names to generated values or score payloads.
weights (Mapping[Any, float] | None) – Optional positive weight per summary name.
minimum_scores (Mapping[Any, float] | None) – Optional threshold that marks a metric below target.

Return type:

FidelityReport

Returns:

A deterministic report containing one metric per profile summary and a weighted composite score when at least one value is available.

fraudtwin.calibration.fit_calibration_profile(reference, *, seed=0, configuration=None, config=None)[source][source]

Fit the deterministic built-in aggregate profile.

Return type:

CalibrationProfile

Parameters:

reference (ReferenceDataset | Path | str)
seed (int)
configuration (Mapping[str, object] | None)
config (Mapping[str, object] | None)

fraudtwin.calibration.load_calibration_profile(path)[source][source]

Load and validate a YAML calibration profile.

Parameters:: path (Path | str) – YAML profile path written by write_calibration_profile().
Return type:: CalibrationProfile
Returns:: The validated immutable profile.
Raises:: ValueError – If the path, YAML root, or profile schema is invalid.

fraudtwin.calibration.load_reference_data(path)[source][source]

Load and strictly validate one canonical Parquet reference table.

Return type:: ReferenceDataset
Parameters:: path (Path | str)

fraudtwin.calibration.register_calibration_metric(name, metric)[source][source]

Register a deterministic fidelity metric under a unique name.

Parameters:

name (str) – Stable configuration name for the metric.
metric (CalibrationMetric) – Plug-in implementing the CalibrationMetric protocol.

Raises:

ValueError – If the name is empty/duplicate or metadata is incomplete.

Return type:

None

fraudtwin.calibration.register_calibration_model(name, model)[source][source]

Register a deterministic calibration model under a unique name.

Parameters:

name (str) – Stable configuration name for the model.
model (CalibrationModel) – Plug-in implementing the CalibrationModel protocol.

Raises:

ValueError – If the name is empty/duplicate or metadata is incomplete.

Return type:

None

fraudtwin.calibration.resolve_calibration(config, profile=None)[source][source]

Resolve an optional profile against a simulation configuration.

Return type:

ResolvedCalibration

Parameters:

config (Any)
profile (CalibrationProfile | None)

fraudtwin.calibration.resolve_calibration_configuration(config)[source][source]

Explicitly named public alias for resolving calibration configuration.

Return type:: ResolvedCalibration
Parameters:: config (Any)

fraudtwin.calibration.validate_calibration_output(profile, generated)[source][source]

Reject output that attempts to carry reference rows or invalid metrics.

Return type:

None

Parameters:

profile (CalibrationProfile)
generated (Mapping[str, object])

fraudtwin.calibration.write_calibration_profile(profile, path)[source][source]

Write one immutable inspectable YAML profile and its JSON manifest.

Return type:

Path

Parameters:

profile (CalibrationProfile)
path (Path | str)