syntharc 0.1.0

Unified synthetic data generation for tabular, time-series, image, and text data

syntharc: The Grand Unified Synthetic Data Generator

syntharc is a powerful, flexible, and unified Python library for generating high-quality synthetic data across multiple domains. In the modern machine learning ecosystem, acquiring high-quality, privacy-compliant, and diverse datasets is often the biggest bottleneck. syntharc solves this by abstracting the complexity of various generative algorithms into a single, intuitive framework.

Whether you need to anonymize sensitive tabular records, augment image operations for computer vision, simulate realistic text sequences, or replicate complex financial time-series signals. syntharc provides the unified API to do it all using state-of-the-art backend engines like PyTorch, Hugging Face Transformers, Albumentations, and the Synthetic Data Vault (SDV).

---

🧠 How It Works: The Unified Lifecycle

One of the biggest hurdles in synthetic data generation is the fragmented tooling across different data types. syntharc forces all underlying models into a highly predictable 3-step lifecycle inherited from our BaseSynthesizer architecture:

1. prepare(**kwargs): Configures the internal environment. This is where you define structural metadata, column types, sequence keys, or image transformation pipelines to guide the generation.
2. fit(data): Feeds your actual, real-world dataset into the generative model so it can learn patterns, probabilistic distributions, and internal representations.
3. generate(**kwargs): Samples from the trained model to yield your brand new synthetic dataset—retaining the statistical properties of the original without exposing real user information.

---

🚀 Key Features

• 📊 Tabular Data: Synthesize fully relational datasets using Deep Learning (CTGANSynthesizer) or statistical modeling (GaussianCopulaSynthesizer).
• 📝 Text Generation: Leverage the power of LLMs (TransformerSynthesizer), classic statistical chains (MarkovSynthesizer), or strict ruleings (TemplateSynthesizer).
• 🖼️ Image Augmentation: Use ImageAugmentor to rapidly iterate through spatial and pixel-level augmentations, dynamically expanding computer vision datasets.
• 📈 Time-Series: Employ the PARSynthesizer (Probabilistic AutoRegressive model) to safely synthesize robust sequence data over time.
• ✅ Evaluations: Built-in tools for evaluating the quality, fidelity, and privacy metrics of your generated data against your source data.

---

📦 Installation

Install syntharc via pip. The base package provides the core infrastructure. We highly recommend installing the specific domain dependencies you intend to use to keep your environment lean:

# Install everything (Recommended for the full experience)
pip install "syntharc[all]"

# Or individually pick your domains:
pip install "syntharc[tabular]"
pip install "syntharc[text]"
pip install "syntharc[image]"
pip install "syntharc[timeseries]"

# For contributors and local development:
pip install "syntharc[dev]"

---

💡 Comprehensive Quick Start

Below are examples of how our unified framework elegantly handles vastly different data constraints.

1. Privacy-Preserving Tabular Data

Train a CTGAN model to learn the distribution of your customer data without saving real identities.

import pandas as pd
from syntharc.tabular.ctgan import CTGANSynthesizer

real_data = pd.read_csv("customer_data.csv")

# 1. Initialize & Prepare metadata
synth = CTGANSynthesizer(epochs=50)
synth.prepare(metadata_dict={"primary_key": "user_id"})

# 2. Fit to real data
synth.fit(real_data)

# 3. Generate 1,000 synthetic rows!
synthetic_data = synth.generate(num_rows=1000)
print(synthetic_data.head())

2. Deep Time-Series Generation

Synthesize sequential metrics, like stock prices or IoT sensor readings, using AutoRegressive modeling.

from syntharc.timeseries.par import PARSynthesizer

# 1. Initialize & Prepare
synth = PARSynthesizer(epochs=25)
# Define what makes a "sequence" (e.g., separate tracking per 'device_id')
synth.prepare(metadata_dict={
    "sequence_key": "device_id",
    "context_columns": ["region"]
})

# 2. Fit
synth.fit(sensor_dataframe)

# 3. Generate sequential data
synthetic_series = synth.generate(num_sequences=50)

3. Causal Text Generation (LLMs)

Easily utilize Hugging Face causal language models.

from syntharc.text.transformer import TransformerTextGenerator

# 1. Initialize (Downloads SmolLM2-360M-Instruct by default)
synth = TransformerTextGenerator()

# 2. Prepare with an optional style context
synth.prepare(corpus="The future of synthetic data is bright and highly scalable.")

# 3. Generate structured text from instructions
text_output = synth.generate(num_samples=1, instructions="Write a short summary about data.")
print(text_output[0])

4. High-Speed Image Augmentation

Prepare a pipeline of augmentations to expand your Machine Learning dataset effortlessly.

from syntharc.image.augmentor import ImageAugmentor
import cv2

# 1. Initialize rules
augmentor = ImageAugmentor()
# Uses Albumentations backend dictionary standards mapping
augmentor.prepare(config={
    'resize': (256, 256),
    'horizontal_flip': 0.5,
    'brightness_contrast': 0.2
})

# 2. Load Real Image
image = cv2.imread('dataset/cat.jpg')

# 3. Generate augmentations
# The generator seamlessly wraps Albumentations under the hood
augmented_image = augmentor.generate(num_samples=1, data=[image])
print(f"Augmented Shape: {augmented_image[0].shape}")

---

📖 Documentation

For comprehensive guides, parameter references, evaluations, and interactive Jupyter showcase notebooks, please check out the docs/ folder:

• Getting Started
• Tabular Generation Guide
• Time-Series Generation Guide
• Text Generation Guide
• Image Augmentation Guide
• API Reference

---

🤝 Contributing

We love our contributors! If you're interested in adding a new generative model, fixing a bug, or improving the documentation, please refer to our CONTRIBUTING.md for detailed instructions on setting up your local environment, managing dependencies, and passing our CI checks.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ by the syntharc team