Metadata-Version: 2.4
Name: vasundhara
Version: 1.1.1
Summary: Synthetic multi-party dataset generator for data clean room testing
Project-URL: Homepage, https://github.com/pn3uma-7/dhara
Project-URL: Source Code, https://github.com/pn3uma-7/dhara
Project-URL: Bug Tracker, https://github.com/pn3uma-7/dhara/issues
Project-URL: Docker Hub, https://hub.docker.com/r/pn3uma7/dhara
Author-email: Amey Tambe <fr3nzy.at@gmail.com>
License: MIT
License-File: LICENSE
Keywords: adtech,clean-room,data,data-generation,martech,privacy,synthetic,testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: faker>=25.0.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Description-Content-Type: text/markdown

# Dhara

**Synthetic multi-party dataset generator for data clean room testing.**

*Reap what you sow.*

---

## What is Dhara?

Data clean room tests fail not because the infrastructure is wrong — but because the test data is wrong.

Nulls, mismatched IDs, unrealistic distributions, and uncontrolled overlap rates make clean room query results meaningless during development. Dhara solves this at the source.

Given a use case configuration, Dhara generates N CSV files — one per data partner — where:

- Each file has a **match ID column** — SHA-256 hashed (`hashed_email`, `hashed_phone`, `hashed_customer_id`) or UUID v4 (`device_id` / IDFA / GAID)
- **Cross-file ID overlap is mathematically controlled** via a pairwise match rate matrix (inclusion-exclusion algorithm)
- **Column values follow your defined distributions** — weighted categorical, integer, decimal, boolean, date, datetime, email, free text
- **Nullable percentages** are respected per column
- **Achieved match rates are verified** post-generation and reported in `metadata.json`
- **Participant schemas can be imported** from a pasted CSV sample or JSON column list — types, distributions, and value weights inferred automatically
- **All runs are reproducible** via a seed

---

## Quickstart

### Web UI (Docker)

```bash
docker pull pn3uma7/dhara
docker run -p 8080:8080 pn3uma7/dhara
# Open http://localhost:8080
```

### CLI

```bash
pip install vasundhara
dhara init                                          # interactive config builder → usecase.json
dhara generate --config usecase.json                # generate datasets → ./dhara_output/
dhara generate --config usecase.json --seed a3f9    # reproduce an exact run
```

---

## How it works — 5 steps

| Step | What you do |
|------|-------------|
| **1 Use Case** | Name your scenario, choose match ID type, set number of partners |
| **2 Participants** | Import each partner's schema from a CSV sample or JSON, or build manually |
| **3 Match Rates** | Set pairwise overlap % — drag sliders, see absolute pool sizes live with industry benchmarks |
| **4 Review** | Run the Audience Simulator — see how filters reduce the shared pool before generating |
| **5 Generate** | Download a ZIP: one CSV per partner + `metadata.json` with match rate verification |

---

## Example use case

Three-way clean room intersection: Brand × Publisher A × Publisher B

```
Match rates:  Brand ∩ Pub-A = 20%,  Brand ∩ Pub-B = 15%,  Pub-A ∩ Pub-B = 10%
All-3 overlap: 5%

Brand query:    WHERE segment = 'premium' AND recency = 'active'
Pub-A query:    WHERE content_vertical = 'finance'
Pub-B query:    WHERE device_type = 'mobile'

→ Shared pool before filters: ~150,000 IDs
→ After all three filters:    ~18,000 – 25,000 IDs
```

See [`examples/monster_doordash_walmart.json`](examples/monster_doordash_walmart.json) for a complete ready-to-run config.

---

## Features

### Match ID types

| Type | Format | Use case |
|------|--------|----------|
| `hashed_email` | SHA-256 hex | Email-based clean rooms |
| `hashed_phone` | SHA-256 hex | SMS / mobile targeting |
| `device_id` | UUID v4 (IDFA / GAID) | Mobile app audiences |
| `hashed_customer_id` | SHA-256 hex | CRM / loyalty ID matching |

### Column types
Categorical · Integer · Decimal · Boolean · Date · Datetime · Email · Free Text

### Schema inference
Paste a CSV sample → Dhara infers column types, value distributions, and weights from actual frequency data. Match key columns are auto-detected and skipped.

### Audience Simulator
Before generating, simulate a clean room query: apply one filter per partner and see how many IDs survive — with a per-step funnel and survival rate.

### Proportional weight sliders
Drag a categorical value's weight up — others reduce proportionally. Hard 95% cap prevents any one value from owning the entire distribution.

### Reproducibility
Every run produces a seed. Re-run with `--seed` to get byte-identical output.

---

## Output

```
dhara_run_20260530_143022.zip
├── brand_dataset.csv           ← match ID + column values
├── publisher_a_dataset.csv
├── publisher_b_dataset.csv
└── metadata.json               ← seed, requested vs achieved rates, drift warnings
```

---

## Tech stack

| Layer | Technology |
|-------|-----------|
| Frontend | React 18, TypeScript, Tailwind CSS, Ubuntu font |
| Backend | Python 3.11, FastAPI |
| Data generation | NumPy, Pandas, Faker |
| ID generation | `hashlib` SHA-256, `uuid` v4 |
| Packaging | Docker · PyPI (`pip install vasundhara`) · `typer` CLI |

---

## Self-hosting

```bash
# One-time setup — no auth, no data leaves your machine
docker run -d -p 8080:8080 --restart=always pn3uma7/dhara

# Expose via VPN or internal DNS: dhara.yourcompany.com
```

---

Part of the **Vasu** tool universe. Dhara (धरा) — earth, foundation, the one who holds.

MIT Licence — free to use, self-host, and modify.
