Clarify library scope and design philosophy in top-level README.md

PiperOrigin-RevId: 989871809

Author: Ryan McKenna

CONTRIBUTING.md

@@ -89,20 +89,30 @@ for new standalone additions.
 
 When reviewing contributions, we primarily look for two things:
 
-### 1. Simplicity
-
-Simpler contributions with smaller diffs are more likely to be accepted. For new
-mechanisms in particular:
-
--   **Aim for a single file** with at most ~500 lines of code.
--   You don't need to use the same internal helper functions that existing
-    mechanisms use. If your approach is novel, a self-contained implementation
-    is perfectly fine.
--   However, your mechanism **should conform to the same API contract** as
-    existing mechanisms (e.g., implementing `DPMechanism`, accepting the same
-    calibration/configuration interface). The exception is mechanisms designed
-    for a new data modality (e.g., relational data), where a new API surface may
-    be necessary.
+### 1. Clean Mechanism Boundaries and Simplicity
+
+For new mechanisms and subpackages, we look for a clean separation between a
+lightweight outer contract and a flexible internal implementation:
+
+-   **Implement `MechanismConfig` / `CalibratedMechanism`**: Conform to the two
+    core abstractions in
+    [`docs/mechanism_api.md`](docs/mechanism_api.md)
+    (`MechanismConfig.configure` / `calibrate` returning a `CalibratedMechanism`
+    with `dp_event` and `__call__`). This contract is lightweight and
+    modality-agnostic (`domain` and `data` can be whatever types your modality
+    requires) while ensuring consistent privacy calibration and accounting
+    across the library.
+-   **Curate the public API surface**: Be deliberate and thoughtful about what
+    is exported in the public API and what the API contract is. Do not expose
+    internal helper functions or implementation details to the top-level core
+    library.
+-   **Flexible internal implementation**: You do not need to use the same
+    internal helper functions or data structures that existing mechanisms use.
+    Because end users only depend on the curated outer API, your internal
+    implementation details and code organization can be completely
+    self-contained and change freely over time. Single-file mechanisms (~500
+    lines) are welcome for focused algorithms, while larger modality-specific
+    mechanisms can live in their own subpackage directory.
 
 ### 2. No New Heavy Dependencies
 

README.md

@@ -1,12 +1,12 @@
-# DPSynth: Differentially Private Synthetic Tabular Data
+# DPSynth: Differentially Private Synthetic Data Generation
 
 [![Documentation](https://readthedocs.org/projects/dpsynth/badge/?version=latest)](https://dpsynth.readthedocs.io/en/latest/)
 
-DPSynth is a library for differentially private synthetic tabular data
-generation. Given a sensitive dataset of records defined w.r.t. a single-table
-schema, our library can generate a synthetic version of the dataset, preserving
-the structure and statistical properties of the source data while satisfying
-differential privacy.
+DPSynth is a library housing mechanisms for differentially private (DP)
+synthetic data generation across a wide range of data modalities. Given a
+sensitive dataset, our library can generate a synthetic version of the dataset,
+preserving the structure and statistical properties of the source data while
+satisfying differential privacy.
 
 📖 **[Full documentation on ReadTheDocs](https://dpsynth.readthedocs.io/en/latest/)**
 
@@ -30,6 +30,93 @@ differential privacy.
 > Your feedback directly shapes the library's direction. Thank you for your
 > patience as we build toward a stable release!
 
+## Scope and Design Philosophy
+
+DPSynth is a Python library for **differentially private synthetic data
+generation**. This scope is deliberately inclusive and does not mean just
+"tabular" data or "text" data. Methods for **any data modality** are in
+principle in scope for the library, and community contributions for new
+modalities and mechanisms are welcome.
+
+Unlike [JAX Privacy](https://github.com/google-deepmind/jax_privacy), which
+focuses on lower-level DP-SGD ingredients, DPSynth implements a wide variety of
+DP mechanisms that naturally compose and build on top of each other:
+
+*   **Supported Modalities**:
+    *   **Discrete**: Low-level discrete, integer-encoded datasets via
+        marginal-based graphical models
+        ([`DiscreteConfig`](dpsynth/discrete_mechanisms/discrete.py),
+        [`discrete_mechanisms/`](dpsynth/discrete_mechanisms/README.md)).
+    *   **Tabular (Single-Table)**: Categorical, numerical, and open-set
+        attributes ([`TabularConfig`](dpsynth/data_generation_v3.py)).
+    *   **Relational (Multi-Table)**: Multi-table databases with foreign-key
+        hierarchies and referential integrity
+        ([`dpsynth.relational`](dpsynth/relational/synthesizer.py)).
+    *   **Nested**: Hierarchically structured and typed records with shared and
+        per-type schemas
+        ([`dpsynth.experimental.nested`](dpsynth/experimental/nested.py)).
+    *   **Sequence**: Event sequences, trajectories, and user session logs.
+    *   **Text**: Unstructured text and prompt/response pairs via DP language
+        model fine-tuning and conditional generation
+        ([`dpsynth.text`](dpsynth/text/dp_sft.py)).
+*   **Why Co-Development Matters**: State-of-the-art mechanisms for text data
+    (such as [ACTG](https://arxiv.org/abs/2510.18232) and
+    [MAPLE](https://arxiv.org/abs/2603.19258)) depend directly on
+    state-of-the-art primitives for tabular data (for example, privately
+    synthesizing structured metadata or summary attributes first and generating
+    text conditioned on those attributes). Similarly, novel mechanisms for new
+    modalities (including [nested](dpsynth/experimental/nested.py),
+    [relational](https://arxiv.org/abs/2503.22970), sequence, and text data)
+    can often be defined by reducing the problem to a tabular synthetic data
+    problem. Having a robust library of tabular primitives makes it easy for
+    other modalities to leverage them directly.
+*   **Built for Heterogeneous, Mixed-Modality Data**: Many real-world datasets
+    are *mixed* (for example, combining structured tabular columns with
+    free-form text). DPSynth has been designed *from the ground up* to support
+    such heterogeneous use cases, from how the
+    [`MechanismConfig` / `CalibratedMechanism`](docs/mechanism_api.md)
+    API is curated to how tight privacy accounting and budget calibration are
+    performed under the hood across composed sub-mechanisms.
+*   **Library Code vs. Binaries and Infrastructure**: As a library, DPSynth
+    consists of importable Python code and does not house deployment binaries,
+    experiment orchestration, or surrounding serving infrastructure in the core
+    package. Instead, we maintain a dedicated [`examples/`](examples/) directory
+    with runnable scripts and binaries that demonstrate how to use the library.
+
+### Mechanism Architecture and Requirements
+
+To keep the library cohesive across diverse modalities without constraining how
+individual algorithms are built, mechanisms in DPSynth follow three core
+principles:
+
+1.  **Implement the `MechanismConfig` / `CalibratedMechanism` API**: Every
+    mechanism is structured around two lightweight abstractions (detailed in
+    [`docs/mechanism_api.md`](docs/mechanism_api.md)):
+    *   `MechanismConfig`: A serializable, frozen configuration recipe that
+        defines `configure(domain, zcdp_rho=...)` and
+        `calibrate(domain, epsilon=..., delta=...)` to bind a domain and privacy
+        budget and return a `CalibratedMechanism`.
+    *   `CalibratedMechanism`: An immutable, runnable instance exposing
+        `dp_event` (an exact characterization of privacy properties via
+        `dp_accounting`) and `__call__(rng, data)` to execute on sensitive data.
+    *   Because this contract places no restrictions on the types of `domain` or
+        `data`, it is lightweight, modality-agnostic, and a natural fit for any
+        DP mechanism: it cleanly separates configuration from execution and
+        enables automatic privacy calibration and composition across mechanisms.
+2.  **Provide a Carefully Curated Public API**: Mechanisms should expose a
+    deliberate, minimal public surface (typically the config class, calibrated
+    mechanism class, and any required domain/schema types) with a clear API
+    contract, rather than exporting internal helpers or intermediate utilities
+    to the top-level library.
+3.  **Complete Flexibility of Internal Implementation**: Because end users and
+    downstream pipelines depend only on the curated outer API contract, a
+    mechanism's internal implementation details, modeling abstractions, and file
+    organization are completely flexible and can evolve freely over time without
+    breaking callers. If you have a novel synthetic data mechanism for any
+    modality, consider contributing it upstream by
+    [opening an issue](https://github.com/google/dpsynth/issues) to discuss the
+    design (see [`CONTRIBUTING.md`](CONTRIBUTING.md)).
+
 ## Two Code Paths
 
 DPSynth contains **two independent implementations** of differentially private