tabdat-synth 0.1.0__tar.gz → 0.2.0__tar.gz

{tabdat_synth-0.1.0 → tabdat_synth-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabdat-synth
-Version: 0.1.0
+Version: 0.2.0
 Summary: Spec-driven tabular data synthesis with reusable fitted bundles.
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/SaehwanPark/tabdat-synth
@@ -54,7 +54,7 @@ Real tabular data often carries privacy, governance, licensing, or access constr
 
 - Spec-driven generation from YAML configuration.
 - Directed synthesis workflows with stable topological execution.
-- Empirical, truncated-normal, categorical-model, coefficient-sum, sigmoid-probability, and Bernoulli-response steps.
+- Empirical, truncated-normal, categorical-model, bin-map, coefficient-sum, sigmoid-probability, and Bernoulli-response steps.
 - Built-in categorical backends for LightGBM and logistic regression.
 - Reusable fitted bundles for generating later without the original source file.
 - Evaluation reports for marginal quality and row-level disclosure-risk heuristics.
@@ -70,7 +70,7 @@ A synthesis run has five stages:
 4. Sample synthetic rows from the fitted artifacts.
 5. Evaluate the synthetic table against source data when appropriate.
 
-The DAG controls which generated columns are available to later steps. For categorical-model steps, declared parents define graph edges, and the fitted model receives the full incoming ancestor context in stable order.
+The DAG controls which generated columns are available to later steps. For categorical-model steps, declared parents define graph edges, and the fitted model receives the full incoming ancestor context in stable order by default, or exactly the columns named in an optional `feature_columns` tuple. Bin-map steps convert a generated numeric column into a categorical column through fixed breaks and labels, with no fitting and no random draw.
 
 ## Installation
 

{tabdat_synth-0.1.0 → tabdat_synth-0.2.0}/README.md

@@ -24,7 +24,7 @@ Real tabular data often carries privacy, governance, licensing, or access constr
 
 - Spec-driven generation from YAML configuration.
 - Directed synthesis workflows with stable topological execution.
-- Empirical, truncated-normal, categorical-model, coefficient-sum, sigmoid-probability, and Bernoulli-response steps.
+- Empirical, truncated-normal, categorical-model, bin-map, coefficient-sum, sigmoid-probability, and Bernoulli-response steps.
 - Built-in categorical backends for LightGBM and logistic regression.
 - Reusable fitted bundles for generating later without the original source file.
 - Evaluation reports for marginal quality and row-level disclosure-risk heuristics.
@@ -40,7 +40,7 @@ A synthesis run has five stages:
 4. Sample synthetic rows from the fitted artifacts.
 5. Evaluate the synthetic table against source data when appropriate.
 
-The DAG controls which generated columns are available to later steps. For categorical-model steps, declared parents define graph edges, and the fitted model receives the full incoming ancestor context in stable order.
+The DAG controls which generated columns are available to later steps. For categorical-model steps, declared parents define graph edges, and the fitted model receives the full incoming ancestor context in stable order by default, or exactly the columns named in an optional `feature_columns` tuple. Bin-map steps convert a generated numeric column into a categorical column through fixed breaks and labels, with no fitting and no random draw.
 
 ## Installation
 

{tabdat_synth-0.1.0 → tabdat_synth-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tabdat-synth"
-version = "0.1.0"
+version = "0.2.0"
 description = "Spec-driven tabular data synthesis with reusable fitted bundles."
 readme = "README.md"
 requires-python = ">=3.12"

{tabdat_synth-0.1.0 → tabdat_synth-0.2.0}/src/tabdat_synth/__init__.py

@@ -3,6 +3,7 @@
 from tabdat_synth.version import __version__
 from tabdat_synth.domain.contracts import (
   BernoulliResponseSpec,
+  BinMapSpec,
   CategoricalModelStepArtifact,
   ColumnSpec,
   CoefficientSumSpec,
@@ -40,6 +41,7 @@ from tabdat_synth.workflows.pipelines import (
 __all__ = [
   "__version__",
   "BernoulliResponseSpec",
+  "BinMapSpec",
   "CategoricalModelStepArtifact",
   "ColumnSpec",
   "CoefficientSumSpec",

{tabdat_synth-0.1.0 → tabdat_synth-0.2.0}/src/tabdat_synth/core/validation.py

@@ -8,6 +8,7 @@ import polars as pl
 
 from tabdat_synth.domain.contracts import (
   BernoulliResponseSpec,
+  BinMapSpec,
   CoefficientSumSpec,
   ColumnSpec,
   DatasetSchema,
@@ -24,6 +25,7 @@ ALLOWED_MISSING_VALUE_POLICIES = {
 _SOURCE_STEP_KINDS = {"empirical", "truncated_normal", "categorical_model"}
 _FEATURE_STEP_KINDS = {"categorical_model", "coefficient_sum"}
 _INPUT_STEP_KINDS = {"sigmoid_probability", "bernoulli_response"}
+_BIN_MAP_STEP_KINDS = {"bin_map"}
 
 
 def validate_generation_spec(spec: GenerationSpec) -> None:
@@ -61,6 +63,7 @@ def validate_generation_spec(spec: GenerationSpec) -> None:
       if dependency == step.output_column:
         raise ValueError(f"step '{step.name}' cannot depend on itself")
 
+  _validate_feature_columns(spec)
   _validate_terminal_bernoulli_steps(spec)
   topologically_sort_steps(spec)
 
@@ -163,12 +166,17 @@ def _validate_step_shape(
   elif step.source_column is not None:
     raise ValueError(f"{step.kind} step '{step.name}' cannot declare source_column")
 
-  if step.kind in _INPUT_STEP_KINDS:
+  if step.kind in _INPUT_STEP_KINDS or step.kind in _BIN_MAP_STEP_KINDS:
     if step.input_column is None:
       raise ValueError(f"{step.kind} step '{step.name}' requires input_column")
   elif step.input_column is not None:
     raise ValueError(f"{step.kind} step '{step.name}' cannot declare input_column")
 
+  if step.kind == "bin_map":
+    _validate_bin_map_step(step, output_spec)
+  elif step.bin_map is not None:
+    raise ValueError(f"{step.kind} step '{step.name}' cannot declare bin_map")
+
   if step.kind == "categorical_model":
     if not step.parent_columns:
       raise ValueError(
@@ -183,6 +191,11 @@ def _validate_step_shape(
   elif step.parent_columns:
     raise ValueError(f"{step.kind} step '{step.name}' cannot declare parent_columns")
 
+  if step.feature_columns and step.kind != "categorical_model":
+    raise ValueError(
+      f"{step.kind} step '{step.name}' cannot declare feature_columns"
+    )
+
   if step.kind == "truncated_normal" and output_spec.data_type == "categorical":
     raise ValueError(
       f"truncated_normal step '{step.name}' cannot target a categorical column"
@@ -253,6 +266,53 @@ def _validate_response_spec(step_name: str, response: BernoulliResponseSpec) ->
     )
 
 
+def _validate_feature_columns(spec: GenerationSpec) -> None:
+  for step in spec.steps:
+    if not step.feature_columns:
+      continue
+    if len(set(step.feature_columns)) != len(step.feature_columns):
+      raise ValueError(f"step '{step.name}' has duplicate feature_columns")
+    ancestors = resolve_incoming_ancestor_outputs(spec, step)
+    unknown = [column for column in step.feature_columns if column not in ancestors]
+    if unknown:
+      raise ValueError(
+        f"step '{step.name}' feature_columns must already be ancestor outputs; "
+        f"unknown feature columns: {unknown}"
+      )
+
+
+def _validate_bin_map_step(step: GenerationStep, output_spec: ColumnSpec) -> None:
+  if step.source_column is not None:
+    raise ValueError(f"bin_map step '{step.name}' cannot declare source_column")
+  if step.parent_columns:
+    raise ValueError(f"bin_map step '{step.name}' cannot declare parent_columns")
+  if step.response is not None:
+    raise ValueError(f"bin_map step '{step.name}' cannot declare response")
+  if step.coefficient_sum is not None:
+    raise ValueError(f"bin_map step '{step.name}' cannot declare coefficient_sum")
+  if step.feature_columns:
+    raise ValueError(f"bin_map step '{step.name}' cannot declare feature_columns")
+  if output_spec.data_type != "categorical":
+    raise ValueError(f"bin_map step '{step.name}' requires categorical output")
+  if step.bin_map is None:
+    raise ValueError(f"bin_map step '{step.name}' requires bin_map")
+  _validate_bin_map_spec(step.name, step.bin_map)
+
+
+def _validate_bin_map_spec(step_name: str, bin_map: BinMapSpec) -> None:
+  breaks = bin_map.breaks
+  labels = bin_map.labels
+
+  if not breaks:
+    raise ValueError(f"bin_map step '{step_name}' requires at least one break")
+  if len(labels) != len(breaks) + 1:
+    raise ValueError(
+      f"bin_map step '{step_name}' requires len(labels) == len(breaks) + 1"
+    )
+  if any(right <= left for left, right in zip(breaks, breaks[1:])):
+    raise ValueError(f"bin_map step '{step_name}' requires strictly increasing breaks")
+
+
 def _validate_forbidden_specs(
   step: GenerationStep,
   *,

{tabdat_synth-0.1.0 → tabdat_synth-0.2.0}/src/tabdat_synth/domain/contracts.py

@@ -16,6 +16,7 @@ GenerationStepKind = Literal[
   "coefficient_sum",
   "sigmoid_probability",
   "bernoulli_response",
+  "bin_map",
 ]
 BackendParamValue: TypeAlias = str | int | float | bool
 BackendScalarValue: TypeAlias = str | int | float
@@ -65,6 +66,14 @@ class BernoulliResponseSpec:
   slope: float = 1.0
 
 
+@dataclass(frozen=True)
+class BinMapSpec:
+  """Typed deterministic binning configuration for one numeric input column."""
+
+  breaks: tuple[float, ...] = field(default_factory=tuple)
+  labels: tuple[str, ...] = field(default_factory=tuple)
+
+
 @dataclass(frozen=True)
 class ColumnSpec:
   """Declarative schema metadata for one source or generated column."""
@@ -103,6 +112,8 @@ class GenerationStep:
   mean_shift: float = 0.0
   coefficient_sum: CoefficientSumSpec | None = None
   response: BernoulliResponseSpec | None = None
+  feature_columns: tuple[str, ...] = field(default_factory=tuple)
+  bin_map: BinMapSpec | None = None
 
 
 @dataclass(frozen=True)

{tabdat_synth-0.1.0 → tabdat_synth-0.2.0}/src/tabdat_synth/interfaces/bundles.py

@@ -13,6 +13,7 @@ import yaml  # type: ignore[import-untyped]
 
 from tabdat_synth.domain.contracts import (
   BernoulliResponseSpec,
+  BinMapSpec,
   CategoricalModelStepArtifact,
   CoefficientSumSpec,
   CoefficientTerm,
@@ -330,6 +331,10 @@ def _load_generation_step(raw_step: object) -> GenerationStep:
     mean_shift=float(raw_step.get("mean_shift", 0.0)),
     coefficient_sum=_load_coefficient_sum(raw_step.get("coefficient_sum")),
     response=_load_response(raw_step.get("response")),
+    feature_columns=tuple(
+      str(column) for column in raw_step.get("feature_columns", [])
+    ),
+    bin_map=_load_bin_map(raw_step.get("bin_map")),
   )
 
 
@@ -351,6 +356,10 @@ def _generation_step_to_dict(step: GenerationStep) -> dict[str, object]:
     payload["coefficient_sum"] = _coefficient_sum_to_dict(step.coefficient_sum)
   if step.response is not None:
     payload["response"] = _response_to_dict(step.response)
+  if step.feature_columns:
+    payload["feature_columns"] = list(step.feature_columns)
+  if step.bin_map is not None:
+    payload["bin_map"] = _bin_map_to_dict(step.bin_map)
   return payload
 
 
@@ -421,5 +430,31 @@ def _response_to_dict(response: BernoulliResponseSpec) -> dict[str, object]:
   }
 
 
+def _load_bin_map(raw_bin_map: object) -> BinMapSpec | None:
+  if raw_bin_map is None:
+    return None
+  if not isinstance(raw_bin_map, dict):
+    raise ValueError("bundle step bin_map must be a mapping")
+
+  raw_breaks = raw_bin_map.get("breaks", [])
+  raw_labels = raw_bin_map.get("labels", [])
+  if not isinstance(raw_breaks, list):
+    raise ValueError("bundle step bin_map.breaks must be a list")
+  if not isinstance(raw_labels, list):
+    raise ValueError("bundle step bin_map.labels must be a list")
+
+  return BinMapSpec(
+    breaks=tuple(float(value) for value in raw_breaks),
+    labels=tuple(str(value) for value in raw_labels),
+  )
+
+
+def _bin_map_to_dict(bin_map: BinMapSpec) -> dict[str, object]:
+  return {
+    "breaks": list(bin_map.breaks),
+    "labels": list(bin_map.labels),
+  }
+
+
 def _safe_token(value: str) -> str:
   return re.sub(r"[^A-Za-z0-9_.-]+", "_", value)

{tabdat_synth-0.1.0 → tabdat_synth-0.2.0}/src/tabdat_synth/interfaces/io.py

@@ -12,6 +12,7 @@ import yaml  # type: ignore[import-untyped]
 from tabdat_synth.core.sampling import MISSING_CATEGORY_LABEL
 from tabdat_synth.domain.contracts import (
   BernoulliResponseSpec,
+  BinMapSpec,
   CoefficientSumSpec,
   CoefficientTerm,
   ColumnSpec,
@@ -294,6 +295,10 @@ def _load_generation_steps(raw_steps: object) -> tuple[GenerationStep, ...]:
         mean_shift=float(cast(Any, raw_step.get("mean_shift", 0.0))),
         coefficient_sum=_load_coefficient_sum(raw_step.get("coefficient_sum")),
         response=_load_response(raw_step.get("response")),
+        feature_columns=tuple(
+          str(column) for column in raw_step.get("feature_columns", [])
+        ),
+        bin_map=_load_bin_map(raw_step.get("bin_map")),
       )
     )
 
@@ -369,6 +374,25 @@ def _load_response(raw_response: object) -> BernoulliResponseSpec | None:
   )
 
 
+def _load_bin_map(raw_bin_map: object) -> BinMapSpec | None:
+  if raw_bin_map is None:
+    return None
+  if not isinstance(raw_bin_map, dict):
+    raise ValueError("bin_map must be a mapping when provided")
+
+  raw_breaks = raw_bin_map.get("breaks", [])
+  raw_labels = raw_bin_map.get("labels", [])
+  if not isinstance(raw_breaks, list):
+    raise ValueError("bin_map.breaks must be a list when provided")
+  if not isinstance(raw_labels, list):
+    raise ValueError("bin_map.labels must be a list when provided")
+
+  return BinMapSpec(
+    breaks=tuple(float(cast(Any, value)) for value in raw_breaks),
+    labels=tuple(str(value) for value in raw_labels),
+  )
+
+
 def _column_spec_to_dict(column: ColumnSpec) -> dict[str, object]:
   payload: dict[str, object] = {
     "name": column.name,
@@ -406,6 +430,10 @@ def _generation_step_to_dict(step: GenerationStep) -> dict[str, object]:
     payload["coefficient_sum"] = _coefficient_sum_to_dict(step.coefficient_sum)
   if step.response is not None:
     payload["response"] = _response_to_dict(step.response)
+  if step.feature_columns:
+    payload["feature_columns"] = list(step.feature_columns)
+  if step.bin_map is not None:
+    payload["bin_map"] = _bin_map_to_dict(step.bin_map)
   return payload
 
 
@@ -436,3 +464,10 @@ def _response_to_dict(response: BernoulliResponseSpec) -> dict[str, object]:
     "intercept": response.intercept,
     "slope": response.slope,
   }
+
+
+def _bin_map_to_dict(bin_map: BinMapSpec) -> dict[str, object]:
+  return {
+    "breaks": list(bin_map.breaks),
+    "labels": list(bin_map.labels),
+  }

{tabdat_synth-0.1.0 → tabdat_synth-0.2.0}/src/tabdat_synth/version.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{tabdat_synth-0.1.0 → tabdat_synth-0.2.0}/src/tabdat_synth/workflows/pipelines.py

@@ -186,7 +186,7 @@ def _fit_generation_step(
   if step.kind == "categorical_model":
     assert step.source_column is not None
     source_series = prepared_source_df[step.source_column]
-    input_columns = resolve_incoming_ancestor_outputs(spec, step)
+    input_columns = _resolve_categorical_input_columns(spec, step)
     X_source = source_generated_df.select(list(input_columns))
     model = fit_categorical_model(
       X_source,
@@ -220,6 +220,14 @@ def _fit_generation_step(
       column_spec,
     )
 
+  if step.kind == "bin_map":
+    binned_values = _calculate_bin_map_series(step, source_generated_df)
+    return ConfiguredStepArtifact(step=step), _cast_output_series(
+      step.output_column,
+      binned_values,
+      column_spec,
+    )
+
   if step.kind == "sigmoid_probability":
     probability_values = _calculate_sigmoid_probability_series(
       step,
@@ -289,6 +297,10 @@ def _execute_fitted_step(
     values = _calculate_coefficient_sum_series(step, synth_df, n_samples)
     return _cast_output_series(step.output_column, values, column_spec)
 
+  if step.kind == "bin_map":
+    values = _calculate_bin_map_series(step, synth_df)
+    return _cast_output_series(step.output_column, values, column_spec)
+
   if step.kind == "sigmoid_probability":
     values = _calculate_sigmoid_probability_series(step, synth_df)
     return _cast_output_series(step.output_column, values, column_spec)
@@ -329,6 +341,36 @@ def _calculate_sigmoid_probability_series(
   return sigmoid(_input_values(step, frame))
 
 
+def _calculate_bin_map_series(
+  step: GenerationStep,
+  frame: pl.DataFrame,
+) -> np.ndarray:
+  assert step.bin_map is not None
+  assert step.input_column is not None
+  breaks = list(step.bin_map.breaks)
+  labels = list(step.bin_map.labels)
+  binned = (
+    frame.select(
+      pl.col(step.input_column)
+      .cut(breaks=breaks, labels=labels)
+      .cast(pl.String)
+      .alias(step.output_column)
+    )
+    .to_series()
+    .to_numpy()
+  )
+  return binned
+
+
+def _resolve_categorical_input_columns(
+  spec: GenerationSpec,
+  step: GenerationStep,
+) -> tuple[str, ...]:
+  if step.feature_columns:
+    return step.feature_columns
+  return resolve_incoming_ancestor_outputs(spec, step)
+
+
 def _input_values(step: GenerationStep, frame: pl.DataFrame) -> np.ndarray:
   assert step.input_column is not None
   return frame[step.input_column].cast(pl.Float64).to_numpy()

{tabdat_synth-0.1.0 → tabdat_synth-0.2.0}/src/tabdat_synth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tabdat-synth
-Version: 0.1.0
+Version: 0.2.0
 Summary: Spec-driven tabular data synthesis with reusable fitted bundles.
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/SaehwanPark/tabdat-synth
@@ -54,7 +54,7 @@ Real tabular data often carries privacy, governance, licensing, or access constr
 
 - Spec-driven generation from YAML configuration.
 - Directed synthesis workflows with stable topological execution.
-- Empirical, truncated-normal, categorical-model, coefficient-sum, sigmoid-probability, and Bernoulli-response steps.
+- Empirical, truncated-normal, categorical-model, bin-map, coefficient-sum, sigmoid-probability, and Bernoulli-response steps.
 - Built-in categorical backends for LightGBM and logistic regression.
 - Reusable fitted bundles for generating later without the original source file.
 - Evaluation reports for marginal quality and row-level disclosure-risk heuristics.
@@ -70,7 +70,7 @@ A synthesis run has five stages:
 4. Sample synthetic rows from the fitted artifacts.
 5. Evaluate the synthetic table against source data when appropriate.
 
-The DAG controls which generated columns are available to later steps. For categorical-model steps, declared parents define graph edges, and the fitted model receives the full incoming ancestor context in stable order.
+The DAG controls which generated columns are available to later steps. For categorical-model steps, declared parents define graph edges, and the fitted model receives the full incoming ancestor context in stable order by default, or exactly the columns named in an optional `feature_columns` tuple. Bin-map steps convert a generated numeric column into a categorical column through fixed breaks and labels, with no fitting and no random draw.
 
 ## Installation