Synthetic Telecom CDR Stream Generator

This repository contains a deterministic, config-driven generator for synthetic telecom-like Call Detail Record (CDR) event streams. It is designed as a reusable research artifact for experiments involving fraud injection, abrupt drift, and sequential stream-style consumption.

The repository intentionally contains only the generator and its reference configuration. Experiment pipelines, detector benchmarking, plots, and paper assets belong in a separate downstream repository.

Features

• Deterministic output under a fixed random seed
• Time-ordered telecom-like CDR events
• Configurable fraud prevalence before and after drift
• Abrupt drift injection at a known timestamp
• Caller-history features such as recent activity and international ratio
• CSV export by default, with optional Parquet export
• Batch iterator support for stream-style consumption

Repository Layout

.
├── configs/
│   └── default.yaml
├── data/
│   └── demo_stream.csv
├── src/
│   └── telecom_stream/
├── generate_stream.py
├── requirements.txt
└── CITATION.cff

Installation

pip install -r requirements.txt

If you want Parquet output, install pyarrow separately.

Usage

Generate the reference demo dataset:

python generate_stream.py --config configs/default.yaml --output data/demo_stream.csv

Generate Parquet instead:

python generate_stream.py --config configs/default.yaml --output data/demo_stream.parquet

If --output is omitted, the CLI writes to data/generated_stream.<default_format> using the default format from the config file.

Output Schema

Generated events include:

• event_id
• event_time
• caller_id
• callee_id
• call_duration_sec
• call_type
• destination_type
• region
• roaming_flag
• sim_age_days
• calls_last_24h
• unique_callees_last_24h
• international_ratio_7d
• fraud_label
• drift_regime
• hour_of_day
• day_of_week
• is_weekend
• network_type

Drift Scenario

The default configuration injects an abrupt drift at a configurable timestamp.

• Before drift: fraud is shorter, burstier, and more international.
• After drift: fraud becomes less obviously international and closer to normal traffic while remaining behaviorally distinct.

The active regime is stored in drift_regime as baseline or post_drift.

Configuration

The YAML config controls:

• random seed
• subscriber and event counts
• time range
• fraud ratios before and after drift
• drift timestamp
• behavior profiles for normal, pre-drift fraud, and post-drift fraud
• region choices
• export defaults and batch size

See configs/default.yaml for the reference configuration.

Citation

Repository metadata is provided in CITATION.cff. After creating a GitHub release and archiving it in Zenodo, update the citation file with the release DOI for paper-ready citation.

License

Add a license file before making the repository public for reuse.