API Reference

Full API reference for all public functions and classes.

For detailed guides with examples, see:

Data Generators

superstore.superstore(config=None, count=None, output=None, seed=None)

Generate superstore sales data with structured configuration.

Parameters:

  • config – Optional SuperstoreConfig pydantic model, dict, or int (for backward compatibility). If int, treated as count. If None, uses default configuration.

  • count – Number of rows (overrides config if provided)

  • output – Output format (“pandas”, “polars”, or “dict”)

  • seed – Random seed (overrides config if provided)

Returns:

Superstore sales data in the specified format.

superstore.employees(count=1000, output='pandas', seed=None)
superstore.timeseries(config=None, nper=None, freq=None, ncol=None, output=None, seed=None)

Generate time series data with structured configuration.

Parameters:

  • config – Optional TimeseriesConfig pydantic model, dict, or int (for backward compatibility). If int, treated as nper. If None, uses default configuration.

  • nper – Number of periods (overrides config if provided)

  • freq – Frequency string (overrides config if provided)

  • ncol – Number of columns (overrides config if provided)

  • output – Output format (“pandas”, “polars”, or “dict”)

  • seed – Random seed (overrides config if provided)

Returns:

Time series data in the specified format.

superstore.weather(config=None, count=None, output='pandas', seed=None)

Generate weather data with structured configuration.

Parameters:

  • config – Optional WeatherConfig pydantic model or dict with configuration. If None, uses default configuration.

  • count – Number of readings (overrides config if provided)

  • output – Output format (“pandas”, “polars”, or “dict”)

  • seed – Random seed (overrides config if provided)

Returns:

Weather sensor data in the specified format.

superstore.logs(config=None)

Generate web server access logs.

Returns realistic HTTP access log entries with configurable traffic patterns, status code distributions (via Markov chain), latency (LogNormal), and error bursts.

# Arguments * config - Optional LogsConfig or dict with generation parameters

# Returns * DataFrame (pandas/polars) or dict of log entries

superstore.app_logs(config=None)

Generate application event logs.

Returns application-level log entries with log levels, loggers, messages, thread IDs, trace/span IDs, and optional exceptions.

# Arguments * config - Optional LogsConfig or dict with generation parameters

# Returns * DataFrame (pandas/polars) or dict of application log entries

superstore.stock_prices(config=None)

Generate stock price data (OHLCV bars).

Returns realistic stock price data using Geometric Brownian Motion with optional jump diffusion. Includes OHLCV bars with realistic intraday relationships and volume patterns.

# Arguments * config - Optional FinanceConfig or dict with generation parameters

# Returns * DataFrame (pandas/polars) or dict of OHLCV bars

superstore.options_chain(config=None, spot_price=None, date=None)

Generate options chain with Greeks.

Returns options data including Black-Scholes pricing and Greeks (delta, gamma, theta, vega) for various strikes and expirations.

# Arguments * config - Optional FinanceConfig or dict with generation parameters * spot_price - Current underlying price (default: 100.0) * date - Pricing date (default: “2024-01-15”)

# Returns * DataFrame (pandas/polars) of options chain

superstore.finance(config=None)

Generate complete finance dataset: stock prices + options.

Returns both OHLCV price data and an options chain for the last trading day.

# Arguments * config - Optional FinanceConfig or dict with generation parameters

# Returns * Tuple of (prices_df, options_df)

superstore.telemetry(config=None, scenario=None)

Generate IoT telemetry data with configurable behaviors and preset scenarios.

# Arguments * config - Optional TelemetryConfig dict or None for defaults * scenario - Optional preset scenario name: “normal”, “cpu_spikes”, “memory_leak”,

“network_congestion”, “disk_pressure”, “cascade_failure”, “maintenance_window”, “sensor_drift”, “degradation_cycle”, “production”, “chaos”

# Returns * DataFrame (pandas/polars) with telemetry readings

superstore.machines(config=None, count=None, json=False, seed=None)

Generate machine data with structured configuration.

Parameters:

  • config – Optional CrossfilterConfig pydantic model, dict, or int (for backward compatibility). If int, treated as count. If None, uses default configuration.

  • count – Number of machines (overrides config if provided)

  • json – Whether to return JSON (deprecated, unused)

  • seed – Random seed (overrides config if provided)

Returns:

List of machine dictionaries.

superstore.usage(machine, json=False, seed=None)
superstore.status(machine, json=False)
superstore.jobs(machine, json=False, seed=None)
superstore.ecommerce_sessions(count, seed=None, output='pandas')

Generate e-commerce sessions

Parameters:

  • count – Number of sessions to generate

  • seed – Optional random seed for reproducibility

  • output – Output format (“pandas”, “polars”, or “dict”)

Returns:

DataFrame or dict with session data

superstore.ecommerce_products(count, seed=None, output='pandas')

Generate e-commerce product catalog

Parameters:

  • count – Number of products to generate

  • seed – Optional random seed for reproducibility

  • output – Output format (“pandas”, “polars”, or “dict”)

Returns:

DataFrame or dict with product data

superstore.ecommerce_data(config=None, output='pandas')

Generate complete e-commerce dataset

Parameters:

  • config – EcommerceConfig dict with generation parameters

  • output – Output format (“pandas”, “polars”, or “dict”)

Returns:

Dict with DataFrames for products, sessions, cart_events, orders, customers

Streaming & Parallel

superstore.superstoreStream(total_count, chunk_size=1000, seed=None)

Create a streaming superstore data generator.

This returns an iterator that yields chunks of data, allowing memory-efficient processing of large datasets.

Parameters:

  • total_count – Total number of rows to generate

  • chunk_size – Number of rows per chunk (default: 1000)

  • seed – Optional seed for reproducibility

Returns:

An iterator yielding lists of dicts

Example

>>> for chunk in superstoreStream(1_000_000, chunk_size=10000):
...     process(chunk)  # Each chunk is a list of 10000 dicts
superstore.employeesStream(total_count, chunk_size=1000, seed=None)

Create a streaming employee data generator.

This returns an iterator that yields chunks of data, allowing memory-efficient processing of large datasets.

Parameters:

  • total_count – Total number of employees to generate

  • chunk_size – Number of employees per chunk (default: 1000)

  • seed – Optional seed for reproducibility

Returns:

An iterator yielding lists of dicts

Example

>>> for chunk in employeesStream(1_000_000, chunk_size=10000):
...     process(chunk)  # Each chunk is a list of 10000 dicts
superstore.superstoreParallel(count=1000, output='pandas', seed=None)

Generate superstore data in parallel using multiple CPU cores.

This function uses Rayon to parallelize data generation across all available CPU cores, providing significant speedup for large datasets.

Parameters:

  • count – Number of rows to generate

  • output – Output format - “pandas”, “polars”, or “dict” (default: “pandas”)

  • seed – Optional seed for reproducibility

Returns:

DataFrame or list of dicts depending on output format

Example

>>> df = superstoreParallel(1_000_000)  # Uses all CPU cores
superstore.employeesParallel(count=1000, output='pandas', seed=None)

Generate employee data in parallel using multiple CPU cores.

This function uses Rayon to parallelize data generation across all available CPU cores, providing significant speedup for large datasets.

Parameters:

  • count – Number of employees to generate

  • output – Output format - “pandas”, “polars”, or “dict” (default: “pandas”)

  • seed – Optional seed for reproducibility

Returns:

DataFrame or list of dicts depending on output format

Example

>>> df = employeesParallel(1_000_000)  # Uses all CPU cores
superstore.numThreads()

Get the number of CPU threads available for parallel operations.

Returns:

Number of threads Rayon will use

superstore.setNumThreads(num_threads)

Set the number of threads for parallel operations.

This should be called early in the program before any parallel operations. Once set, it cannot be changed.

Parameters:

num_threads – Number of threads to use for parallel generation

Raises:

RuntimeError – If the thread pool has already been initialized

Export Functions

superstore.superstoreArrowIpc(count, seed=None)

Generate superstore data as Arrow IPC bytes.

The returned bytes can be read by PyArrow: ```python import pyarrow as pa from superstore import superstoreArrowIpc

ipc_bytes = superstoreArrowIpc(100) reader = pa.ipc.open_stream(ipc_bytes) table = reader.read_all() df = table.to_pandas() ```

# Arguments * count - Number of rows to generate * seed - Optional random seed for reproducibility

# Returns Arrow IPC stream bytes

superstore.employeesArrowIpc(count, seed=None)

Generate employee data as Arrow IPC bytes.

The returned bytes can be read by PyArrow: ```python import pyarrow as pa from superstore import employeesArrowIpc

ipc_bytes = employeesArrowIpc(100) reader = pa.ipc.open_stream(ipc_bytes) table = reader.read_all() df = table.to_pandas() ```

# Arguments * count - Number of rows to generate * seed - Optional random seed for reproducibility

# Returns Arrow IPC stream bytes

superstore.superstoreToParquet(path, count, seed=None, compression=None)

Write superstore data directly to a Parquet file.

# Arguments * path - Output file path * count - Number of rows to generate * seed - Optional random seed for reproducibility * compression - Compression type: ‘none’, ‘snappy’ (default), or ‘zstd’

# Returns Number of rows written

superstore.employeesToParquet(path, count, seed=None, compression=None)

Write employee data directly to a Parquet file.

# Arguments * path - Output file path * count - Number of rows to generate * seed - Optional random seed for reproducibility * compression - Compression type: ‘none’, ‘snappy’ (default), or ‘zstd’

# Returns Number of rows written

superstore.superstoreToCsv(path, count, seed=None)

Write superstore data directly to a CSV file.

# Arguments * path - Output file path * count - Number of rows to generate * seed - Optional random seed for reproducibility

# Returns Number of rows written

superstore.employeesToCsv(path, count, seed=None)

Write employee data directly to a CSV file.

# Arguments * path - Output file path * count - Number of rows to generate * seed - Optional random seed for reproducibility

# Returns Number of rows written

Distributions

superstore.sampleUniform(min, max, n=1, seed=None)

Sample from a uniform distribution.

Parameters:

  • min – Minimum value

  • max – Maximum value

  • n – Number of samples (default: 1)

  • seed – Optional seed for reproducibility

Returns:

Single value if n=1, list of values otherwise

superstore.sampleNormal(mean, std_dev, n=1, seed=None)

Sample from a normal (Gaussian) distribution.

Parameters:

  • mean – Mean of the distribution

  • std_dev – Standard deviation

  • n – Number of samples (default: 1)

  • seed – Optional seed for reproducibility

Returns:

Single value if n=1, list of values otherwise

superstore.sampleLogNormal(mu, sigma, n=1, seed=None)

Sample from a log-normal distribution.

Parameters:

  • mu – Mean of the underlying normal distribution

  • sigma – Standard deviation of the underlying normal distribution

  • n – Number of samples (default: 1)

  • seed – Optional seed for reproducibility

Returns:

Single value if n=1, list of values otherwise

superstore.sampleExponential(lambda_, n=1, seed=None)

Sample from an exponential distribution.

Parameters:

  • lambda – Rate parameter (1/mean)

  • n – Number of samples (default: 1)

  • seed – Optional seed for reproducibility

Returns:

Single value if n=1, list of values otherwise

superstore.sampleBeta(alpha, beta, n=1, seed=None)

Sample from a Beta distribution.

Parameters:

  • alpha – Shape parameter alpha

  • beta – Shape parameter beta

  • n – Number of samples (default: 1)

  • seed – Optional seed for reproducibility

Returns:

Single value if n=1, list of values otherwise (values in [0, 1])

superstore.sampleGamma(shape, scale, n=1, seed=None)

Sample from a Gamma distribution.

Parameters:

  • shape – Shape parameter

  • scale – Scale parameter

  • n – Number of samples (default: 1)

  • seed – Optional seed for reproducibility

Returns:

Single value if n=1, list of values otherwise

superstore.sampleWeibull(shape, scale, n=1, seed=None)

Sample from a Weibull distribution.

Parameters:

  • shape – Shape parameter

  • scale – Scale parameter

  • n – Number of samples (default: 1)

  • seed – Optional seed for reproducibility

Returns:

Single value if n=1, list of values otherwise

superstore.samplePareto(scale, shape, n=1, seed=None)

Sample from a Pareto (power law) distribution.

Parameters:

  • scale – Scale parameter (minimum value)

  • shape – Shape parameter (tail index)

  • n – Number of samples (default: 1)

  • seed – Optional seed for reproducibility

Returns:

Single value if n=1, list of values otherwise

superstore.samplePoisson(lambda_, n=1, seed=None)

Sample from a Poisson distribution.

Parameters:

  • lambda – Rate parameter (expected count)

  • n – Number of samples (default: 1)

  • seed – Optional seed for reproducibility

Returns:

Single value if n=1, list of values otherwise

superstore.sampleCategorical(weights, n=1, seed=None)

Sample from a categorical distribution with weights.

Parameters:

  • weights – List of weights for each category (will be normalized)

  • n – Number of samples (default: 1)

  • seed – Optional seed for reproducibility

Returns:

Single category index if n=1, list of indices otherwise

superstore.sampleMixture(means, std_devs, weights, n=1, seed=None)

Sample from a mixture of normal distributions.

Parameters:

  • means – List of means for each component

  • std_devs – List of standard deviations for each component

  • weights – List of weights for each component (will be normalized)

  • n – Number of samples (default: 1)

  • seed – Optional seed for reproducibility

Returns:

Single value if n=1, list of values otherwise

Example

>>> # Bimodal distribution
>>> samples = sampleMixture([30000, 80000], [10000, 20000], [0.6, 0.4], n=1000)
superstore.addGaussianNoise(values, std_dev, seed=None)

Add Gaussian noise to values.

Parameters:

  • values – List of values to add noise to

  • std_dev – Standard deviation of the noise

  • seed – Optional seed for reproducibility

Returns:

List of values with noise added

superstore.applyMissing(values, probability, seed=None)

Apply missing at random to values.

Parameters:

  • values – List of values

  • probability – Probability of each value being missing (0-1)

  • seed – Optional seed for reproducibility

Returns:

List of values with some replaced by None

Correlation & Copulas

superstore.pearsonCorrelation(x, y)

Compute the Pearson correlation coefficient between two lists.

# Arguments * x - First variable * y - Second variable

# Returns The correlation coefficient (between -1 and 1)

superstore.sampleBivariate(n, rho, mean1=0.0, std1=1.0, mean2=0.0, std2=1.0, seed=None)

Generate correlated bivariate normal data.

This is a convenience function for the common case of generating two correlated variables.

# Arguments * n - Number of samples * rho - Correlation coefficient between the two variables * mean1, std1 - Mean and standard deviation for first variable * mean2, std2 - Mean and standard deviation for second variable * seed - Optional random seed

# Returns A tuple of two lists (x, y)

class superstore.GaussianCopula(correlation_matrix)

Bases: object

Gaussian (Normal) Copula.

Uses multivariate normal distribution to model dependencies. The correlation between variables is specified via a correlation matrix.

Example

>>> copula = GaussianCopula([[1.0, 0.8], [0.8, 1.0]])
>>> samples = copula.sample(100)
>>> # Each sample is a list of uniform [0,1] values with the specified correlation
dim

Get the dimension of the copula.

sample(n, seed=None)

Generate n samples from the copula.

Parameters:

  • n – Number of samples to generate

  • seed – Optional random seed

Returns:

List of n samples, where each sample is a list of d uniform [0,1] values

class superstore.ClaytonCopula(theta, dim)

Bases: object

Clayton Copula.

An Archimedean copula with lower tail dependence. Good for modeling dependencies where extreme low values tend to occur together.

Example

>>> copula = ClaytonCopula(2.0, 2)  # theta=2, 2 dimensions
>>> samples = copula.sample(100)
dim

Get the dimension of the copula.

kendalls_tau()

Get Kendall’s tau (measure of correlation).

sample(n, seed=None)

Generate n samples from the copula.

theta

Get theta parameter.

class superstore.FrankCopula(theta)

Bases: object

Frank Copula.

An Archimedean copula with symmetric tail dependence. Good for modeling overall dependence without tail asymmetry.

Example

>>> copula = FrankCopula(5.0)  # positive dependence
>>> samples = copula.sample(100)
kendalls_tau()

Get Kendall’s tau (measure of correlation).

sample(n, seed=None)

Generate n bivariate samples from the copula.

Returns:

List of n tuples (u, v), each containing two uniform [0,1] values

theta

Get theta parameter.

class superstore.GumbelCopula(theta)

Bases: object

Gumbel Copula.

An Archimedean copula with upper tail dependence. Good for modeling dependencies where extreme high values tend to occur together.

Example

>>> copula = GumbelCopula(2.0)  # theta=2 means moderate upper tail dependence
>>> samples = copula.sample(100)
kendalls_tau()

Get Kendall’s tau (measure of correlation).

sample(n, seed=None)

Generate n bivariate samples from the copula.

Returns:

List of n tuples (u, v), each containing two uniform [0,1] values

theta

Get theta parameter.

upper_tail_dependence()

Get upper tail dependence coefficient.

Temporal Models

class superstore.AR1(phi, sigma, mean=0.0)

Bases: object

AR(1) autoregressive model for generating temporally dependent data.

Generates values according to: x_t = mean + phi * (x_{t-1} - mean) + epsilon_t where epsilon_t ~ N(0, sigma^2)

mean

Get the mean.

phi

Get the phi coefficient.

reset()

Reset the state to the mean.

sample(n, seed=None)

Generate n samples.

Parameters:

  • n – Number of samples to generate

  • seed – Optional random seed

Returns:

List of n values

sigma

Get the sigma value.

state

Get the current state.

stationary_variance()

Get the stationary variance of the process.

class superstore.ARp(coefficients, sigma, mean=0.0)

Bases: object

AR(p) autoregressive model of order p.

Generates values according to: x_t = mean + sum_i(phi_i * (x_{t-i} - mean)) + epsilon_t

static ar2(phi1, phi2, sigma, mean=0.0)

Create an AR(2) model.

order()

Get the order of the AR model.

reset()

Reset the state to the mean.

sample(n, seed=None)

Generate n samples.

class superstore.MarkovChain(transition_matrix, states)

Bases: object

Markov chain for generating temporally dependent categorical data.

current_state

Get current state.

sample(n, seed=None)

Generate n state transitions.

sample_indices(n, seed=None)

Generate n state transitions as indices.

set_state(state)

Set current state by name.

states()

Get all states.

stationary_distribution()

Get stationary distribution.

static two_state(state_a, state_b, prob_a_to_b, prob_b_to_a)

Create a simple two-state Markov chain.

Parameters:

  • state_a – Name of first state

  • state_b – Name of second state

  • prob_a_to_b – Probability of transitioning from A to B

  • prob_b_to_a – Probability of transitioning from B to A

class superstore.RandomWalk(sigma, start=0.0, drift=0.0)

Bases: object

Random walk model.

position

Get current position.

sample(n, seed=None)

Generate n samples.

class superstore.ExponentialSmoothing(alpha, sigma, initial=0.0)

Bases: object

Exponential smoothing generator for smooth trend generation.

sample(n, seed=None)

Generate n samples.

smoothed

Get current smoothed value.

Configuration Classes

pydantic model superstore.SuperstoreConfig[source]

Bases: BaseModel

Configuration for the superstore data generator.

Generates realistic retail transaction data with correlations between sales, quantity, discount, and profit.

field count: int = 1000

Number of rows to generate

field output: OutputFormat = OutputFormat.DICT

Output format

field seed: int | None = None

Random seed for reproducibility

field pool_size: int = 1000

Size of pre-generated data pools for performance

field sales_quantity_correlation: float = 0.8

Sales-quantity correlation

field sales_profit_correlation: float = 0.9

Sales-profit correlation

field discount_profit_correlation: float = -0.6

Discount-profit correlation

field enable_price_points: bool = True

Round prices to realistic $X.99 values

field seasonality: SeasonalityConfig [Optional]

Seasonal patterns

field promotions: PromotionalConfig [Optional]

Promotional effects

field customers: CustomerConfig [Optional]

Customer behavior

pydantic model superstore.TimeseriesConfig[source]

Bases: BaseModel

Configuration for the time series generator.

Generates financial-style time series with optional regime changes, volatility clustering, and jump diffusion.

field nper: int = 30

Number of periods

field ncol: int = 4

Number of columns (max 26)

field freq: Literal['B', 'D', 'W', 'M'] = 'B'

Frequency: B=business, D=daily, W=weekly, M=monthly

field output: OutputFormat = OutputFormat.DICT

Output format

field seed: int | None = None

Random seed for reproducibility

field ar_phi: float = 0.95

AR(1) persistence parameter

field sigma: float = 1.0

Innovation standard deviation

field drift: float = 0.0

Drift/trend per period

field cumulative: bool = True

Apply cumulative sum (price-like behavior)

field use_fat_tails: bool = False

Use Student-t instead of normal innovations

field degrees_freedom: float = 5.0

Degrees of freedom for Student-t

field cross_correlation: float = 0.0

Correlation between columns (0 = independent)

field regimes: RegimeConfig [Optional]

Regime switching configuration

field jumps: JumpConfig [Optional]

Jump diffusion configuration

pydantic model superstore.WeatherConfig[source]

Bases: BaseModel

Configuration for the weather data generator.

Generates realistic outdoor sensor data with temporal patterns, seasonal variations, and weather events.

field count: int = 1000

Number of readings to generate

field output: OutputFormat = OutputFormat.DICT

Output format

field seed: int | None = None

Random seed for reproducibility

field start_date: str | None = None

Start date (YYYY-MM-DD). Defaults to 30 days ago.

field frequency_minutes: int = 15

Reading frequency in minutes

field climate_zone: ClimateZone = ClimateZone.TEMPERATE

Climate zone for realistic patterns

field latitude: float = 40.0

Latitude for day/night calculations

field base_temp_celsius: float = 15.0

Annual average temperature in Celsius

field temp_daily_amplitude: float = 10.0

Day/night temperature swing in Celsius

field temp_seasonal_amplitude: float = 15.0

Summer/winter temperature swing in Celsius

field temp_noise_stddev: float = 2.0

Random noise standard deviation

field base_humidity_percent: float = 60.0

Average humidity percentage

field humidity_temp_correlation: float = -0.3

Correlation between temp and humidity (-1 to 1)

field precipitation_probability: float = 0.15

Base probability of precipitation

field enable_weather_events: bool = True

Enable weather event simulation

field event_probability: float = 0.05

Probability of weather event occurring

field outlier_probability: float = 0.01

Probability of outlier readings (sensor errors)

field sensor_drift: bool = False

Enable gradual sensor calibration drift

field sensor_drift_rate: float = 0.001

Rate of sensor drift per reading

pydantic model superstore.LogsConfig[source]

Bases: BaseModel

Configuration for the logs data generator.

Generates realistic web server access logs and application event logs with configurable traffic patterns, error rates, and latency distributions.

field count: int = 1000

Number of log entries to generate

field output: OutputFormat = OutputFormat.DICT

Output format (pandas, polars, or dict)

field seed: int | None = None

Random seed for reproducibility

field format: LogFormat = LogFormat.COMBINED

Log format style

field start_time: str | None = None

Start timestamp (ISO format). Defaults to current time.

field requests_per_second: float = 100.0

Average requests per second (Poisson rate)

field success_rate: float = 0.95

Base success rate (2xx responses)

field error_burst: ErrorBurstConfig [Optional]

Error burst configuration

field latency: LatencyConfig [Optional]

Latency distribution configuration

field include_user_agent: bool = True

Include user agent strings

field unique_ips: int = 1000

Number of unique IP addresses to generate

field unique_users: int = 500

Number of unique user IDs

field api_path_ratio: float = 0.7

Ratio of API paths vs static paths

pydantic model superstore.FinanceConfig[source]

Bases: BaseModel

Configuration for the finance data generator.

Generates realistic financial market data including OHLCV stock prices, multi-asset correlated returns, and options chains with Black-Scholes pricing.

field ndays: int = 252

Number of trading days to generate (252 = 1 year)

field n_assets: int = 1

Number of assets (1 = single stock, >1 = correlated multi-asset)

field output: OutputFormat = OutputFormat.DICT

Output format (pandas, polars, or dict)

field seed: int | None = None

Random seed for reproducibility

field start_date: str | None = None

Start date (ISO format YYYY-MM-DD). Defaults to 2024-01-02.

field tickers: list[str] [Optional]

Ticker symbols for the assets

field asset_correlation: float = 0.5

Correlation between assets (for multi-asset generation)

field stock: StockConfig [Optional]

Stock price generation configuration

field ohlcv: OhlcvConfig [Optional]

OHLCV bar configuration

field options: OptionsConfig [Optional]

Options chain configuration

pydantic model superstore.CrossfilterConfig[source]

Bases: BaseModel

Configuration for crossfilter IoT data generator.

Generates machine telemetry data suitable for dashboard demos with optional anomalies and temporal patterns.

field n_machines: int = 10

Number of machines

field n_readings: int = 1000

Number of usage readings per machine

field output: OutputFormat = OutputFormat.DICT

Output format

field seed: int | None = None

Random seed for reproducibility

field machine_types: list[MachineType] [Optional]

Types of machines to generate

field cores_range: tuple[int, int] = (4, 64)

Range of CPU cores per machine

field zones: list[str] [Optional]

Available zones

field regions: list[str] [Optional]

Available regions

field base_cpu_load: float = 0.3

Base CPU utilization

field base_memory_load: float = 0.5

Base memory utilization

field load_variance: float = 0.2

Variance in load readings

field anomalies: AnomalyConfig [Optional]

Anomaly injection settings

field temporal_patterns: TemporalPatternConfig [Optional]

Temporal pattern settings

field enable_failures: bool = False

Enable machine failure simulation

field failure_probability: float = 0.001

Probability of failure per reading

field cascade_failure_probability: float = 0.3

Probability of cascade failure when dependent machine fails

pydantic model superstore.EcommerceConfig[source]

Bases: BaseModel

Configuration for e-commerce data generation.

Generates realistic e-commerce data including: - User sessions via MarkovChain state machines - Shopping cart events with abandonment patterns - Customer RFM (Recency, Frequency, Monetary) metrics - Product catalog with categories and pricing - Conversion funnels with realistic drop-off rates

field sessions: int = 10000

Number of sessions to generate

field customers: int = 2000

Number of unique customers

field seed: int | None = None

Random seed for reproducibility

field start_date: str | None = None

Start date for data generation (YYYY-MM-DD)

field days: int = 30

Number of days to generate

field session: SessionConfig [Optional]

Session behavior configuration

field cart: CartConfig [Optional]

Cart behavior configuration

field catalog: CatalogConfig [Optional]

Product catalog configuration

field rfm: RfmConfig [Optional]

RFM analysis configuration

field funnel: FunnelConfig [Optional]

Conversion funnel configuration

pydantic model superstore.SessionConfig[source]

Bases: BaseModel

Configuration for session behavior in e-commerce.

field avg_pages_per_session: float = 5.0

Average pages viewed per session

field cart_add_probability: float = 0.15

Probability of adding item to cart given product view

field checkout_start_probability: float = 0.4

Probability of starting checkout given cart view

field purchase_completion_probability: float = 0.65

Probability of completing purchase given checkout start

field avg_session_duration_seconds: int = 300

Average session duration in seconds

field enable_bounces: bool = True

Enable session bounces (single-page visits)

field bounce_rate: float = 0.35

Bounce rate (probability of immediate exit)

pydantic model superstore.CartConfig[source]

Bases: BaseModel

Configuration for cart behavior.

field avg_items_per_cart: float = 2.5

Average items per cart

field remove_probability: float = 0.1

Probability of removing an item from cart

field quantity_update_probability: float = 0.05

Probability of updating quantity

field max_items: int = 20

Maximum items per cart

field enable_abandonment: bool = True

Enable cart abandonment simulation

field abandonment_rate: float = 0.7

Cart abandonment rate

pydantic model superstore.CatalogConfig[source]

Bases: BaseModel

Configuration for product catalog.

field num_products: int = 500

Number of unique products

field min_price: float = 5.0

Minimum product price

field max_price: float = 1000.0

Maximum product price

field lognormal_prices: bool = True

Price follows log-normal distribution (realistic skew)

field categories: list[str] [Optional]

Product categories

pydantic model superstore.RfmConfig[source]

Bases: BaseModel

Configuration for RFM (Recency, Frequency, Monetary) analysis.

field enable: bool = True

Enable RFM metrics calculation

field recency_window_days: int = 365

Days to look back for recency

field num_buckets: int = 5

Number of RFM score buckets (typically 5)

field pareto_shape: float = 1.5

Pareto distribution shape for customer value (80/20 rule)

pydantic model superstore.FunnelConfig[source]

Bases: BaseModel

Configuration for conversion funnel.

field enable: bool = True

Enable funnel stage tracking

field stages: list[str] [Optional]

Funnel stages

field time_of_day_effects: bool = True

Time-of-day effects on conversions

field day_of_week_effects: bool = True

Day-of-week effects on conversions

Enums

class superstore.ClimateZone(value)[source]

Bases: str, Enum

Climate zone affecting weather patterns.

ARID = 'arid'
CONTINENTAL = 'continental'
MEDITERRANEAN = 'mediterranean'
POLAR = 'polar'
SUBTROPICAL = 'subtropical'
TEMPERATE = 'temperate'
TROPICAL = 'tropical'
class superstore.OutputFormat(value)[source]

Bases: str, Enum

Output format for generators.

DICT = 'dict'
PANDAS = 'pandas'
POLARS = 'polars'
class superstore.LogLevel(value)[source]

Bases: str, Enum

Log severity levels.

DEBUG = 'debug'
ERROR = 'error'
INFO = 'info'
TRACE = 'trace'
WARN = 'warn'
class superstore.LogFormat(value)[source]

Bases: str, Enum

Log output format styles.

APPLICATION = 'application'
COMBINED = 'combined'
COMMON = 'common'
JSON = 'json'