API Reference

ColumnDefinition

`kroft.core.column.ColumnDefinition`

Metadata and generator for a single table column.

Parameters:

Name	Type	Description	Default
`name`	`str`	Column name as it appears in the database.	required
`sql_type`	`str`	SQL type string (e.g. `"UUID"`, `"TEXT"`, `"FLOAT"`).	required
`generator`	`Callable[[], Any]`	Zero-argument callable that returns a new value each call.	required
`constraints`	`Optional[str]`	Optional SQL constraint string appended to the DDL (e.g. "PRIMARY KEY"```,"NOT NULL"``).	`None`
`reserved`	`bool`	If `True`, the column is excluded from the initial schema and can be promoted later via schema evolution.	`False`
`protected`	`bool`	If `True`, the column is never chosen for mutation (updates/deletes) or schema drops.	`False`

`ddl()`

Return the DDL fragment for this column (e.g. id UUID PRIMARY KEY).

`generate()`

Return a freshly generated value for this column.

SchemaManager

`kroft.core.schema.SchemaManager`

Manages the physical database schema for a single table.

Tracks active vs. reserved columns, issues DDL against the database, and maintains a version history of schema changes.

Parameters:

Name	Type	Description	Default
`conn`	`Any`	A live `psycopg2` connection.	required
`schema`	`str`	PostgreSQL schema name (e.g. `"public"`).	required
`table_name`	`str`	Name of the table to manage.	required
`columns`	`Dict[str, ColumnDefinition]`	Full column pool — both active and reserved — keyed by column name. Reserved columns are excluded from the initial schema and can be promoted later via :meth:`add_column`.	required

`add_column()`

Promote a reserved column from registry to active schema and evolve the DB.

`drop_column()`

Drop a random column that is not protected from the physical table and update active schema.

`register_column(name, col_def)`

Add a new column definition to the registry (without altering DB schema).

BatchGenerator

`kroft.core.batch.BatchGenerator`

Generates synthetic rows from a column schema.

Parameters:

Name	Type	Description	Default
`schema`	`Optional[Dict[str, ColumnDefinition]]`	Dictionary mapping column name to :class:`ColumnDefinition`. Provide this or set `use_registry=True`.	`None`
`use_registry`	`bool`	If `True`, loads the schema from the global column registry populated via :func:`~kroft.core.registry.register_column`.	`False`

MutationEngine

`kroft.core.mutator.MutationEngine`

Performs insert, update, and delete operations against a live table.

Supports four composable simulation scenarios:

Insert only — call :meth:insert_batch and nothing else.
Insert + Update — call :meth:insert_batch then :meth:update_batch.
Insert + Update + Delete — chain all three methods.
Probabilistic mutations — use :meth:maybe_mutate_batch with configurable probability and fraction parameters.

Parameters:

Name	Type	Description	Default
`conn`	`Any`	A live `psycopg2` connection.	required
`schema`	`str`	PostgreSQL schema name (e.g. `"public"`).	required
`table_name`	`str`	Target table name.	required
`primary_key`	`str`	Name of the primary key column. Defaults to `"id"`.	`'id'`
`update_column`	`Optional[str]`	Optional timestamp column set to `now()` on every update (e.g. `"updated_at"`).	`None`
`generator`	`Optional[BatchGenerator]`	:class:`BatchGenerator` used to produce replacement values during updates. Required for update operations.	`None`

`delete_batch(ids, fraction=0.1, probability=1.0)`

Delete a random fraction of the given ids.

Parameters:

Name	Type	Description	Default
`ids`	`List[str]`	Pool of record ids to sample from.	required
`fraction`	`float`	Fraction of ids to delete (0.0–1.0).	`0.1`
`probability`	`float`	Chance this call does anything (0.0–1.0).	`1.0`

`maybe_mutate_batch(inserted_ids, probability=0.5, update_fraction=0.2, delete_fraction=0.1, allow_updates=True, allow_deletes=True)`

Randomly mutate a subset of the inserted batch.

Parameters:

Name	Type	Description	Default
`inserted_ids`	`List[str]`	Ids from the most recent insert.	required
`probability`	`float`	Chance any mutation happens at all (0.0–1.0).	`0.5`
`update_fraction`	`float`	Fraction of ids to update when updates are chosen.	`0.2`
`delete_fraction`	`float`	Fraction of ids to delete when deletes are chosen.	`0.1`
`allow_updates`	`bool`	Include updates in the possible operations.	`True`
`allow_deletes`	`bool`	Include deletes in the possible operations.	`True`

`update_batch(ids, fraction=0.2, probability=1.0)`

Update a random fraction of the given ids.

Parameters:

Name	Type	Description	Default
`ids`	`List[str]`	Pool of record ids to sample from.	required
`fraction`	`float`	Fraction of ids to update (0.0–1.0).	`0.2`
`probability`	`float`	Chance this call does anything (0.0–1.0).	`1.0`

EvolutionController

`kroft.core.evolution.EvolutionController`

Controls when and how the table schema evolves during a simulation.

On each batch, call :meth:evolve — it decides probabilistically whether to promote a reserved column (add) or drop a non-protected one, subject to the configured limits.

Parameters:

Name	Type	Description	Default
`manager`	`SchemaManager`	The :class:`~kroft.core.schema.SchemaManager` whose schema this controller will evolve.	required
`evolution_interval`	`int`	Only consider evolving every N batches.	`25`
`evolution_probability`	`float`	Probability of evolution firing when the interval is reached (0.0–1.0).	`0.2`
`add_probability`	`float`	When evolution fires and both add and drop are possible, probability of choosing add over drop (0.0–1.0).	`0.7`
`max_additions`	`int`	Maximum number of columns that can be added over the lifetime of the simulation.	`7`
`max_drops`	`int`	Maximum number of columns that can be dropped over the lifetime of the simulation.	`3`

SimulationRunner

`kroft.core.runner.SimulationRunner`

Orchestrates a full data simulation: generate batches, mutate, evolve.

Composes :class:~kroft.core.schema.SchemaManager, :class:~kroft.core.mutator.MutationEngine, and :class:~kroft.core.evolution.EvolutionController into a single run loop. For finer-grained control over mutations or evolution, drive each component directly instead.

Parameters:

Name	Type	Description	Default
`schema_mgr`	`SchemaManager`	Manages the table schema and active columns.	required
`mutator`	`MutationEngine`	Handles insert, update, and delete operations.	required
`evolution_controller`	`EvolutionController`	Decides when and how to evolve the schema.	required
`total_records`	`int`	Total number of rows to generate across all batches.	`10000`
`batch_size`	`int`	Number of rows per batch.	`500`
`seed`	`Optional[int]`	Optional integer seed for `random` to make runs reproducible.	`None`