Extension SDK#
Level: Expert
You will: publish deterministic scenarios, rails, behavior models, fault
injectors, or sinks without importing arbitrary configuration paths.
Before you start: the Architecture guide and Python
packaging experience.
Services: None.
FraudTwin exposes small, typed ports so domain extensions do not need to edit
the simulator internals. The public contracts are available from
fraudtwin.extensions:
from fraudtwin import ExtensionMetadata, FraudScenario
metadata = ExtensionMetadata("acme.account-takeover", "1.0.0")
Supported ports are FraudScenario, PaymentRail, BehaviorModel,
DataFaultInjector, and OutputSink. Each implementation must expose
ExtensionMetadata, use only the supplied deterministic seed/context, and
preserve stable logical identities.
Discovery and compatibility#
Packages may register implementations through the
fraudtwin.extensions Python entry-point group. FraudTwin loads installed
packages only; configuration never executes arbitrary import strings or
downloads code. Discovery is ordered by extension ID and the manifest records
the extension ID, semantic version, distribution, and distribution version.
Breaking changes require a new major extension version and a documented compatibility range. Extensions must not expose oracle-only fields through observable sinks or alter authoritative ledger transitions.
For an application-owned registry, use ExtensionRegistry and register the
implementations explicitly before constructing the workflow. Keep the registry
snapshot alongside the run manifest so a result can be reproduced later.
The complete external-package example is in
examples/extensions/.
It includes a minimal fault injector and the corresponding pyproject.toml
entry-point declaration to copy into a separately versioned distribution.
Next#
Follow the Architecture boundaries, then validate the extension in a bounded Development workflow.